diff --git a/cmd/mountlib/help.go b/cmd/mountlib/help.go index 2becd330f..5c7130c33 100644 --- a/cmd/mountlib/help.go +++ b/cmd/mountlib/help.go @@ -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 ` diff --git a/docs/content/commands/rclone_mount.md b/docs/content/commands/rclone_mount.md index 67fe38876..fc3aaa347 100644 --- a/docs/content/commands/rclone_mount.md +++ b/docs/content/commands/rclone_mount.md @@ -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)