mirror of
https://github.com/rclone/rclone.git
synced 2024-12-13 02:33:58 +01:00
a54210a2e4
This was done as part of ebfeec9fb4
which unfortunately patched
the auto generated files.
414 lines
19 KiB
Markdown
414 lines
19 KiB
Markdown
---
|
|
date: 2020-02-10T15:20:27Z
|
|
title: "rclone mount"
|
|
slug: rclone_mount
|
|
url: /commands/rclone_mount/
|
|
# autogenerated - DO NOT EDIT, instead edit the source code in cmd/mount/ and as part of making a release run "make commanddocs"
|
|
---
|
|
## rclone mount
|
|
|
|
Mount the remote as file system on a mountpoint.
|
|
|
|
### Synopsis
|
|
|
|
|
|
rclone mount allows Linux, FreeBSD, macOS and Windows to
|
|
mount any of Rclone's cloud storage systems as a file system with
|
|
FUSE.
|
|
|
|
First set up your remote using `rclone config`. Check it works with `rclone ls` etc.
|
|
|
|
You can either run mount in foreground mode or background(daemon) mode. Mount runs in
|
|
foreground mode by default, use the --daemon flag to specify background mode mode.
|
|
Background mode is only supported on Linux and OSX, you can only run mount in
|
|
foreground mode on Windows.
|
|
|
|
Start the mount like this
|
|
|
|
rclone mount remote:path/to/files /path/to/local/mount
|
|
|
|
Or on Windows like this where X: is an unused drive letter
|
|
|
|
rclone mount remote:path/to/files X:
|
|
|
|
When running in background mode the user will have to stop the mount manually (specified below).
|
|
|
|
When the program ends while in foreground mode, either via Ctrl+C or receiving
|
|
a SIGINT or SIGTERM signal, the mount is automatically stopped.
|
|
|
|
The umount operation can fail, for example when the mountpoint is busy.
|
|
When that happens, it is the user's responsibility to stop the mount manually.
|
|
|
|
Stopping the mount manually:
|
|
|
|
# Linux
|
|
fusermount -u /path/to/local/mount
|
|
# OS X
|
|
umount /path/to/local/mount
|
|
|
|
### Installing on Windows
|
|
|
|
To run rclone mount on Windows, you will need to
|
|
download and install [WinFsp](http://www.secfs.net/winfsp/).
|
|
|
|
WinFsp is an [open source](https://github.com/billziss-gh/winfsp)
|
|
Windows File System Proxy which makes it easy to write user space file
|
|
systems for Windows. It provides a FUSE emulation layer which rclone
|
|
uses combination with
|
|
[cgofuse](https://github.com/billziss-gh/cgofuse). Both of these
|
|
packages are by Bill Zissimopoulos who was very helpful during the
|
|
implementation of rclone mount for Windows.
|
|
|
|
#### Windows caveats
|
|
|
|
Note that drives created as Administrator are not visible by other
|
|
accounts (including the account that was elevated as
|
|
Administrator). So if you start a Windows drive from an Administrative
|
|
Command Prompt and then try to access the same drive from Explorer
|
|
(which does not run as Administrator), you will not be able to see the
|
|
new drive.
|
|
|
|
The easiest way around this is to start the drive from a normal
|
|
command prompt. It is also possible to start a drive from the SYSTEM
|
|
account (using [the WinFsp.Launcher
|
|
infrastructure](https://github.com/billziss-gh/winfsp/wiki/WinFsp-Service-Architecture))
|
|
which creates drives accessible for everyone on the system or
|
|
alternatively using [the nssm service manager](https://nssm.cc/usage).
|
|
|
|
#### Mount as a network drive
|
|
|
|
By default, rclone will mount the remote as a normal drive. However,
|
|
you can also mount it as a **Network Drive** (or **Network Share**, as
|
|
mentioned in some places)
|
|
|
|
Unlike other systems, Windows provides a different filesystem type for
|
|
network drives. Windows and other programs treat the network drives
|
|
and fixed/removable drives differently: In network drives, many I/O
|
|
operations are optimized, as the high latency and low reliability
|
|
(compared to a normal drive) of a network is expected.
|
|
|
|
Although many people prefer network shares to be mounted as normal
|
|
system drives, this might cause some issues, such as programs not
|
|
working as expected or freezes and errors while operating with the
|
|
mounted remote in Windows Explorer. If you experience any of those,
|
|
consider mounting rclone remotes as network shares, as Windows expects
|
|
normal drives to be fast and reliable, while cloud storage is far from
|
|
that. See also [Limitations](#limitations) section below for more
|
|
info
|
|
|
|
Add "--fuse-flag --VolumePrefix=\server\share" to your "mount"
|
|
command, **replacing "share" with any other name of your choice if you
|
|
are mounting more than one remote**. Otherwise, the mountpoints will
|
|
conflict and your mounted filesystems will overlap.
|
|
|
|
[Read more about drive mapping](https://en.wikipedia.org/wiki/Drive_mapping)
|
|
|
|
### Limitations
|
|
|
|
Without the use of "--vfs-cache-mode" this can only write files
|
|
sequentially, it can only seek when reading. This means that many
|
|
applications won't work with their files on an rclone mount without
|
|
"--vfs-cache-mode writes" or "--vfs-cache-mode full". See the [File
|
|
Caching](#file-caching) section for more info.
|
|
|
|
The bucket based remotes (eg Swift, S3, Google Compute Storage, B2,
|
|
Hubic) do not support the concept of empty directories, so empty
|
|
directories will have a tendency to disappear once they fall out of
|
|
the directory cache.
|
|
|
|
Only supported on Linux, FreeBSD, OS X and Windows at the moment.
|
|
|
|
### rclone mount vs rclone sync/copy
|
|
|
|
File systems expect things to be 100% reliable, whereas cloud storage
|
|
systems are a long way from 100% reliable. The rclone sync/copy
|
|
commands cope with this with lots of retries. However rclone mount
|
|
can't use retries in the same way without making local copies of the
|
|
uploads. Look at the [file caching](#file-caching)
|
|
for solutions to make mount more reliable.
|
|
|
|
### Attribute caching
|
|
|
|
You can use the flag --attr-timeout to set the time the kernel caches
|
|
the attributes (size, modification time etc) for directory entries.
|
|
|
|
The default is "1s" which caches files just long enough to avoid
|
|
too many callbacks to rclone from the kernel.
|
|
|
|
In theory 0s should be the correct value for filesystems which can
|
|
change outside the control of the kernel. However this causes quite a
|
|
few problems such as
|
|
[rclone using too much memory](https://github.com/rclone/rclone/issues/2157),
|
|
[rclone not serving files to samba](https://forum.rclone.org/t/rclone-1-39-vs-1-40-mount-issue/5112)
|
|
and [excessive time listing directories](https://github.com/rclone/rclone/issues/2095#issuecomment-371141147).
|
|
|
|
The kernel can cache the info about a file for the time given by
|
|
"--attr-timeout". You may see corruption if the remote file changes
|
|
length during this window. It will show up as either a truncated file
|
|
or a file with garbage on the end. With "--attr-timeout 1s" this is
|
|
very unlikely but not impossible. The higher you set "--attr-timeout"
|
|
the more likely it is. The default setting of "1s" is the lowest
|
|
setting which mitigates the problems above.
|
|
|
|
If you set it higher ('10s' or '1m' say) then the kernel will call
|
|
back to rclone less often making it more efficient, however there is
|
|
more chance of the corruption issue above.
|
|
|
|
If files don't change on the remote outside of the control of rclone
|
|
then there is no chance of corruption.
|
|
|
|
This is the same as setting the attr_timeout option in mount.fuse.
|
|
|
|
### Filters
|
|
|
|
Note that all the rclone filters can be used to select a subset of the
|
|
files to be visible in the mount.
|
|
|
|
### systemd
|
|
|
|
When running rclone mount as a systemd service, it is possible
|
|
to use Type=notify. In this case the service will enter the started state
|
|
after the mountpoint has been successfully set up.
|
|
Units having the rclone mount service specified as a requirement
|
|
will see all files and folders immediately in this mode.
|
|
|
|
### chunked reading ###
|
|
|
|
--vfs-read-chunk-size will enable reading the source objects in parts.
|
|
This can reduce the used download quota for some remotes by requesting only chunks
|
|
from the remote that are actually read at the cost of an increased number of requests.
|
|
|
|
When --vfs-read-chunk-size-limit is also specified and greater than --vfs-read-chunk-size,
|
|
the chunk size for each open file will get doubled for each chunk read, until the
|
|
specified value is reached. A value of -1 will disable the limit and the chunk size will
|
|
grow indefinitely.
|
|
|
|
With --vfs-read-chunk-size 100M and --vfs-read-chunk-size-limit 0 the following
|
|
parts will be downloaded: 0-100M, 100M-200M, 200M-300M, 300M-400M and so on.
|
|
When --vfs-read-chunk-size-limit 500M is specified, the result would be
|
|
0-100M, 100M-300M, 300M-700M, 700M-1200M, 1200M-1700M and so on.
|
|
|
|
Chunked reading will only work with --vfs-cache-mode < full, as the file will always
|
|
be copied to the vfs cache before opening with --vfs-cache-mode full.
|
|
|
|
### Directory Cache
|
|
|
|
Using the `--dir-cache-time` flag, you can set how long a
|
|
directory should be considered up to date and not refreshed from the
|
|
backend. Changes made locally in the mount may appear immediately or
|
|
invalidate the cache. However, changes done on the remote will only
|
|
be picked up once the cache expires if the backend configured does not
|
|
support polling for changes. If the backend supports polling, changes
|
|
will be picked up on within the polling interval.
|
|
|
|
Alternatively, you can send a `SIGHUP` signal to rclone for
|
|
it to flush all directory caches, regardless of how old they are.
|
|
Assuming only one rclone instance is running, you can reset the cache
|
|
like this:
|
|
|
|
kill -SIGHUP $(pidof rclone)
|
|
|
|
If you configure rclone with a [remote control](/rc) then you can use
|
|
rclone rc to flush the whole directory cache:
|
|
|
|
rclone rc vfs/forget
|
|
|
|
Or individual files or directories:
|
|
|
|
rclone rc vfs/forget file=path/to/file dir=path/to/dir
|
|
|
|
### File Buffering
|
|
|
|
The `--buffer-size` flag determines the amount of memory,
|
|
that will be used to buffer data in advance.
|
|
|
|
Each open file descriptor will try to keep the specified amount of
|
|
data in memory at all times. The buffered data is bound to one file
|
|
descriptor and won't be shared between multiple open file descriptors
|
|
of the same file.
|
|
|
|
This flag is a upper limit for the used memory per file descriptor.
|
|
The buffer will only use memory for data that is downloaded but not
|
|
not yet read. If the buffer is empty, only a small amount of memory
|
|
will be used.
|
|
The maximum memory used by rclone for buffering can be up to
|
|
`--buffer-size * open files`.
|
|
|
|
### File Caching
|
|
|
|
These flags control the VFS file caching options. The VFS layer is
|
|
used by rclone mount to make a cloud storage system work more like a
|
|
normal file system.
|
|
|
|
You'll need to enable VFS caching if you want, for example, to read
|
|
and write simultaneously to a file. See below for more details.
|
|
|
|
Note that the VFS cache works in addition to the cache backend and you
|
|
may find that you need one or the other or both.
|
|
|
|
--cache-dir string Directory rclone will use for caching.
|
|
--vfs-cache-max-age duration Max age of objects in the cache. (default 1h0m0s)
|
|
--vfs-cache-mode string Cache mode off|minimal|writes|full (default "off")
|
|
--vfs-cache-poll-interval duration Interval to poll the cache for stale objects. (default 1m0s)
|
|
--vfs-cache-max-size int Max total size of objects in the cache. (default off)
|
|
|
|
If run with `-vv` rclone will print the location of the file cache. The
|
|
files are stored in the user cache file area which is OS dependent but
|
|
can be controlled with `--cache-dir` or setting the appropriate
|
|
environment variable.
|
|
|
|
The cache has 4 different modes selected by `--vfs-cache-mode`.
|
|
The higher the cache mode the more compatible rclone becomes at the
|
|
cost of using disk space.
|
|
|
|
Note that files are written back to the remote only when they are
|
|
closed so if rclone is quit or dies with open files then these won't
|
|
get written back to the remote. However they will still be in the on
|
|
disk cache.
|
|
|
|
If using --vfs-cache-max-size note that the cache may exceed this size
|
|
for two reasons. Firstly because it is only checked every
|
|
--vfs-cache-poll-interval. Secondly because open files cannot be
|
|
evicted from the cache.
|
|
|
|
#### --vfs-cache-mode off
|
|
|
|
In this mode the cache will read directly from the remote and write
|
|
directly to the remote without caching anything on disk.
|
|
|
|
This will mean some operations are not possible
|
|
|
|
* Files can't be opened for both read AND write
|
|
* Files opened for write can't be seeked
|
|
* Existing files opened for write must have O_TRUNC set
|
|
* Files open for read with O_TRUNC will be opened write only
|
|
* Files open for write only will behave as if O_TRUNC was supplied
|
|
* Open modes O_APPEND, O_TRUNC are ignored
|
|
* If an upload fails it can't be retried
|
|
|
|
#### --vfs-cache-mode minimal
|
|
|
|
This is very similar to "off" except that files opened for read AND
|
|
write will be buffered to disks. This means that files opened for
|
|
write will be a lot more compatible, but uses the minimal disk space.
|
|
|
|
These operations are not possible
|
|
|
|
* Files opened for write only can't be seeked
|
|
* Existing files opened for write must have O_TRUNC set
|
|
* Files opened for write only will ignore O_APPEND, O_TRUNC
|
|
* If an upload fails it can't be retried
|
|
|
|
#### --vfs-cache-mode writes
|
|
|
|
In this mode files opened for read only are still read directly from
|
|
the remote, write only and read/write files are buffered to disk
|
|
first.
|
|
|
|
This mode should support all normal file system operations.
|
|
|
|
If an upload fails it will be retried up to --low-level-retries times.
|
|
|
|
#### --vfs-cache-mode full
|
|
|
|
In this mode all reads and writes are buffered to and from disk. When
|
|
a file is opened for read it will be downloaded in its entirety first.
|
|
|
|
This may be appropriate for your needs, or you may prefer to look at
|
|
the cache backend which does a much more sophisticated job of caching,
|
|
including caching directory hierarchies and chunks of files.
|
|
|
|
In this mode, unlike the others, when a file is written to the disk,
|
|
it will be kept on the disk after it is written to the remote. It
|
|
will be purged on a schedule according to `--vfs-cache-max-age`.
|
|
|
|
This mode should support all normal file system operations.
|
|
|
|
If an upload or download fails it will be retried up to
|
|
--low-level-retries times.
|
|
|
|
### Case Sensitivity
|
|
|
|
Linux file systems are case-sensitive: two files can differ only
|
|
by case, and the exact case must be used when opening a file.
|
|
|
|
Windows is not like most other operating systems supported by rclone.
|
|
File systems in modern Windows are case-insensitive but case-preserving:
|
|
although existing files can be opened using any case, the exact case used
|
|
to create the file is preserved and available for programs to query.
|
|
It is not allowed for two files in the same directory to differ only by case.
|
|
|
|
Usually file systems on MacOS are case-insensitive. It is possible to make MacOS
|
|
file systems case-sensitive but that is not the default
|
|
|
|
The "--vfs-case-insensitive" mount flag controls how rclone handles these
|
|
two cases. If its value is "false", rclone passes file names to the mounted
|
|
file system as is. If the flag is "true" (or appears without a value on
|
|
command line), rclone may perform a "fixup" as explained below.
|
|
|
|
The user may specify a file name to open/delete/rename/etc with a case
|
|
different than what is stored on mounted file system. If an argument refers
|
|
to an existing file with exactly the same name, then the case of the existing
|
|
file on the disk will be used. However, if a file name with exactly the same
|
|
name is not found but a name differing only by case exists, rclone will
|
|
transparently fixup the name. This fixup happens only when an existing file
|
|
is requested. Case sensitivity of file names created anew by rclone is
|
|
controlled by an underlying mounted file system.
|
|
|
|
Note that case sensitivity of the operating system running rclone (the target)
|
|
may differ from case sensitivity of a file system mounted by rclone (the source).
|
|
The flag controls whether "fixup" is performed to satisfy the target.
|
|
|
|
If the flag is not provided on command line, then its default value depends
|
|
on the operating system where rclone runs: "true" on Windows and MacOS, "false"
|
|
otherwise. If the flag is provided without a value, then it is "true".
|
|
|
|
|
|
```
|
|
rclone mount remote:path /path/to/mountpoint [flags]
|
|
```
|
|
|
|
### Options
|
|
|
|
```
|
|
--allow-non-empty Allow mounting over a non-empty directory.
|
|
--allow-other Allow access to other users.
|
|
--allow-root Allow access to root user.
|
|
--attr-timeout duration Time for which file/directory attributes are cached. (default 1s)
|
|
--daemon Run mount as a daemon (background mode).
|
|
--daemon-timeout duration Time limit for rclone to respond to kernel (not supported by all OSes).
|
|
--debug-fuse Debug the FUSE internals - needs -v.
|
|
--default-permissions Makes kernel enforce access control based on the file mode.
|
|
--dir-cache-time duration Time to cache directory entries for. (default 5m0s)
|
|
--dir-perms FileMode Directory permissions (default 0777)
|
|
--file-perms FileMode File permissions (default 0666)
|
|
--fuse-flag stringArray Flags or arguments to be passed direct to libfuse/WinFsp. Repeat if required.
|
|
--gid uint32 Override the gid field set by the filesystem. (default 1000)
|
|
-h, --help help for mount
|
|
--max-read-ahead SizeSuffix The number of bytes that can be prefetched for sequential reads. (default 128k)
|
|
--no-checksum Don't compare checksums on up/download.
|
|
--no-modtime Don't read/write the modification time (can speed things up).
|
|
--no-seek Don't allow seeking in files.
|
|
-o, --option stringArray Option for libfuse/WinFsp. Repeat if required.
|
|
--poll-interval duration Time to wait between polling for changes. Must be smaller than dir-cache-time. Only on supported remotes. Set to 0 to disable. (default 1m0s)
|
|
--read-only Mount read-only.
|
|
--uid uint32 Override the uid field set by the filesystem. (default 1000)
|
|
--umask int Override the permission bits set by the filesystem.
|
|
--vfs-cache-max-age duration Max age of objects in the cache. (default 1h0m0s)
|
|
--vfs-cache-max-size SizeSuffix Max total size of objects in the cache. (default off)
|
|
--vfs-cache-mode CacheMode Cache mode off|minimal|writes|full (default off)
|
|
--vfs-cache-poll-interval duration Interval to poll the cache for stale objects. (default 1m0s)
|
|
--vfs-case-insensitive If a file name not found, find a case insensitive match.
|
|
--vfs-read-chunk-size SizeSuffix Read the source objects in chunks. (default 128M)
|
|
--vfs-read-chunk-size-limit SizeSuffix If greater than --vfs-read-chunk-size, double the chunk size after each chunk read, until the limit is reached. 'off' is unlimited. (default off)
|
|
--volname string Set the volume name (not supported by all OSes).
|
|
--write-back-cache Makes kernel buffer writes before sending them to rclone. Without this, writethrough caching is used.
|
|
```
|
|
|
|
See the [global flags page](/flags/) for global options not listed here.
|
|
|
|
### SEE ALSO
|
|
|
|
* [rclone](/commands/rclone/) - Show help for rclone commands, flags and backends.
|
|
|