community
/
rclone
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

mount: document the mount helper mode, make command docs - #5594

This commit is contained in:
Ivan Andreev 2021-10-03 01:13:16 +03:00
parent a95c7a001e
commit a065fb23e5
2 changed files with 188 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
cmd/mountlib/help.go
View File

@ -12,13 +12,22 @@ On Linux and OSX, you can either run mount in foreground mode or background (dae
Mount runs in foreground mode by default, use the |--daemon| flag to specify background mode.
You can only run mount in foreground mode on Windows.
In background mode rclone acts as a generic Unix mount program: the main program
starts, spawns a background rclone process to setup and maintain the mount, waits
until success or timeout, kills the child process if mount fails, and immediately
exits with appropriate return code.
On Linux/macOS/FreeBSD start the mount like this, where |/path/to/local/mount|
is an **empty** **existing** directory:
rclone @ remote:path/to/files /path/to/local/mount
On Windows you can start a mount in different ways. See [below](#mounting-modes-on-windows)
for details. The following examples will mount to an automatically assigned drive,
for details. If foreground mount is used interactively from a console window,
rclone will serve the mount and occupy the console so another window should be
used to work with the mount until rclone is interrupted e.g. by pressing Ctrl-C.
The following examples will mount to an automatically assigned drive,
to specific drive letter |X:|, to path |C:\path\parent\mount|
(where parent directory or drive must exist, and mount must **not** exist,
and is not supported when [mounting as a network drive](#mounting-modes-on-windows)), and
@ -225,6 +234,13 @@ 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.
When mount is invoked on Unix with |--daemon|, the main rclone program
will wait until the background mount is ready until timeout specified by
the |--daemon-wait| flag. On Linux rclone will poll ProcFS to check status
so the flag sets the **maximum time to wait**. On macOS/BSD the time to wait
is constant and the check is performed only at the end of sleep so don't
set it too high...
Only supported on Linux, FreeBSD, OS X and Windows at the moment.
### rclone @ vs rclone sync/copy
@ -280,4 +296,80 @@ 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 @ service specified as a requirement
will see all files and folders immediately in this mode.
Note that systemd runs mount units without any environment variables including
|PATH| or |HOME|. This means that tilde (|~|) expansion will not work
and you should provide |--config| and |--cache-dir| explicitly as absolute
paths via rclone arguments. Since mounting requires the |fusermount| program,
rclone will use the fallback PATH of |/bin:/usr/bin| in this scenario.
Please ensure that |fusermount| is present on this PATH.
### Rclone as Unix mount helper
The core Unix program |/bin/mount| normally takes the |-t FSTYPE| argument
then runs the |/sbin/mount.FSTYPE| helper program passing it mount options
as |-o key=val,...| or |--opt=...|. Automount (classic or systemd) follows
the suit.
rclone by default expects GNU-style flags |--key val|. To run it as a
mount helper you should symlink the rclone binary to |/sbin/mount.rclone|
and optionally |/usr/bin/rclonefs|, e.g. |ln -s /usr/bin/rclone /sbin/mount.rclone|.
Now you can run classic mounts like this:
|||
mount sftp1:subdir /mnt/data -t rclone -o vfs_cache_mode=writes,sftp_key_file=/path/to/pem
|||
or create systemd mount units:
|||
# /etc/systemd/system/mnt-data.mount
[Unit]
After=network-online.target
[Mount]
Type=rclone
What=sftp1:subdir
Where=/mnt/data
Options=rw,allow_other,args2env,vfs-cache-mode=writes,config=/etc/rclone.conf,cache-dir=/var/rclone
|||
optionally augmented by systemd automount unit
|||
# /etc/systemd/system/mnt-data.automount
[Unit]
After=network-online.target
Before=remote-fs.target
[Automount]
Where=/mnt/data
TimeoutIdleSec=600
[Install]
WantedBy=multi-user.target
|||
or add in |/etc/fstab| a line like
|||
sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2env,vfs_cache_mode=writes,config=/etc/rclone.conf,cache_dir=/var/cache/rclone 0 0
|||
or use classic Automountd.
Remember to provide explicit |config=...,cache-dir=...| as mount units
run without |HOME|.
Rclone in the mount helper mode will split |-o| argument(s) by comma, replace |_|
by |-| and prepend |--| to get the command-line flags. Options containing commas
or spaces can be wrapped in single or double quotes. Any quotes inside outer quotes
should be doubled.
Mount option syntax includes a few extra options treated specially:
- |env.NAME=VALUE| will set an environment variable for.
This helps with Automountd and Systemd.mount which don't allow to set custom
environment for mount helpers.
Typically you will use |env.HTTPS_PROXY=proxy.host:3128| or |env.HOME=/root|
- |command=cmount| can be used to run any other command rather than default mount
- |args2env| will pass mount options to the background mount helper via environment
variables instead of command line arguments. This allows to hide secrets from such
commands as |ps| or |pgrep|.
- |vv...| will be transformed into appropriate |--verbose=N|
- standard mount options like |x-systemd.automount|, |_netdev|, |nosuid| and alike
are intended only for Automountd so ignored by rclone
`

97
docs/content/commands/rclone_mount.md
View File

@ -22,13 +22,22 @@ On Linux and macOS, you can either run mount in foreground mode or background (d
Mount runs in foreground mode by default, use the `--daemon` flag to specify background mode.
You can only run mount in foreground mode on Windows.
In background mode rclone acts as a generic Unix mount program: the main program
starts, spawns a background rclone process to setup and maintain the mount, waits
until success or timeout, kills the child process if mount fails, and immediately
exits with appropriate return code.
On Linux/macOS/FreeBSD start the mount like this, where `/path/to/local/mount`
is an **empty** **existing** directory:
rclone mount remote:path/to/files /path/to/local/mount
On Windows you can start a mount in different ways. See [below](#mounting-modes-on-windows)
for details. The following examples will mount to an automatically assigned drive,
for details. If foreground mount is used interactively from a console window,
rclone will serve the mount and occupy the console so another window should be
used to work with the mount until rclone is interrupted e.g. by pressing Ctrl-C.
The following examples will mount to an automatically assigned drive,
to specific drive letter `X:`, to path `C:\path\parent\mount`
(where parent directory or drive must exist, and mount must **not** exist,
and is not supported when [mounting as a network drive](#mounting-modes-on-windows)), and
@ -238,6 +247,13 @@ 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.
When mount is invoked on Unix with `--daemon`, the main rclone program
will wait until the background mount is ready until timeout specified by
the `--daemon-wait` flag. On Linux rclone will poll ProcFS to check status
so the flag sets the **maximum time to wait**. On macOS/BSD the time to wait
is constant and the check is performed only at the end of sleep so don't
set it too high...
Only supported on Linux, FreeBSD, macOS and Windows at the moment.
## rclone mount vs rclone sync/copy
@ -294,6 +310,82 @@ 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.
Note that systemd runs mount units without any environment variables including
`PATH` or `HOME`. This means that tilde (`~`) expansion will not work
and you should provide `--config` and `--cache-dir` explicitly as absolute
paths via rclone arguments. Since mounting requires the `fusermount` program,
rclone will use the fallback PATH of `/bin:/usr/bin` in this scenario.
Please ensure that `fusermount` is present on this PATH.
## Rclone as Unix mount helper
The core Unix program `/bin/mount` normally takes the `-t FSTYPE` argument
then runs the `/sbin/mount.FSTYPE` helper program passing it mount options
as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) follows
the suit.
rclone by default expects GNU-style flags `--key val`. To run it as a
mount helper you should symlink the rclone binary to `/sbin/mount.rclone`
and optionally `/usr/bin/rclonefs`, e.g. `ln -s /usr/bin/rclone /sbin/mount.rclone`.
Now you can run classic mounts like this:
```
mount sftp1:subdir /mnt/data -t rclone -o vfs_cache_mode=writes,sftp_key_file=/path/to/pem
```
or create systemd mount units:
```
# /etc/systemd/system/mnt-data.mount
[Unit]
After=network-online.target
[Mount]
Type=rclone
What=sftp1:subdir
Where=/mnt/data
Options=rw,allow_other,args2env,vfs-cache-mode=writes,config=/etc/rclone.conf,cache-dir=/var/rclone
```
optionally augmented by systemd automount unit
```
# /etc/systemd/system/mnt-data.automount
[Unit]
After=network-online.target
Before=remote-fs.target
[Automount]
Where=/mnt/data
TimeoutIdleSec=600
[Install]
WantedBy=multi-user.target
```
or add in `/etc/fstab` a line like
```
sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2env,vfs_cache_mode=writes,config=/etc/rclone.conf,cache_dir=/var/cache/rclone 0 0
```
or use classic Automountd.
Remember to provide explicit `config=...,cache-dir=...` as mount units
run without `HOME`.
Rclone in the mount helper mode will split `-o` argument(s) by comma, replace `_`
by `-` and prepend `--` to get the command-line flags. Options containing commas
or spaces can be wrapped in single or double quotes. Any quotes inside outer quotes
should be doubled.
Mount option syntax includes a few extra options treated specially:
- `env.NAME=VALUE` will set an environment variable for.
This helps with Automountd and Systemd.mount which don't allow to set custom
environment for mount helpers.
Typically you will use `env.HTTPS_PROXY=proxy.host:3128` or `env.HOME=/root`
- `command=cmount` can be used to run any other command rather than default mount
- `args2env` will pass mount options to the background mount helper via environment
variables instead of command line arguments. This allows to hide secrets from such
commands as `ps` or `pgrep`.
- `vv...` will be transformed into appropriate `--verbose=N`
- standard mount options like `x-systemd.automount`, `_netdev`, `nosuid` and alike
are intended only for Automountd so ignored by rclone
## chunked reading
`--vfs-read-chunk-size` will enable reading the source objects in parts.
@ -587,8 +679,9 @@ rclone mount remote:path /path/to/mountpoint [flags]
--allow-root Allow access to root user. Not supported on Windows.
--async-read Use asynchronous reads. Not supported on Windows. (default true)
--attr-timeout duration Time for which file/directory attributes are cached. (default 1s)
--daemon Run mount as a daemon (background mode). Not supported on Windows.
--daemon Run mount in background and exit parent process. Not supported on Windows. As background output is suppressed, use --log-file with --log-format=pid,... to monitor.
--daemon-timeout duration Time limit for rclone to respond to kernel. Not supported on Windows.
--daemon-wait duration Time to wait for ready mount from daemon (maximum time on Linux, constant sleep time on OSX/BSD). Ignored on Windows. (default 1m0s)
--debug-fuse Debug the FUSE internals - needs -v.
--default-permissions Makes kernel enforce access control based on the file mode. Not supported on Windows.
--dir-cache-time duration Time to cache directory entries for. (default 5m0s)