From bce395385d7ea742ed594b7675f25b02f27aabda Mon Sep 17 00:00:00 2001 From: Ivan Andreev Date: Sat, 9 Oct 2021 14:16:33 +0300 Subject: [PATCH] mount/docs: improve wording --- cmd/mountlib/help.go | 72 ++++++++++++++------------- docs/content/commands/rclone_mount.md | 72 ++++++++++++++------------- 2 files changed, 76 insertions(+), 68 deletions(-) diff --git a/cmd/mountlib/help.go b/cmd/mountlib/help.go index 5c7130c33..b6182b76d 100644 --- a/cmd/mountlib/help.go +++ b/cmd/mountlib/help.go @@ -8,14 +8,15 @@ FUSE. First set up your remote using |rclone config|. Check it works with |rclone ls| etc. -On Linux and OSX, 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. -You can only run mount in foreground mode on Windows. +On Linux and macOS, you can run mount in either foreground or background (aka +daemon) mode. Mount runs in foreground mode by default. Use the |--daemon| flag +to force background mode. On Windows you can run mount in foreground only, +the flag is ignored. -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. +In background mode rclone acts as a generic Unix mount program: the main +program starts, spawns background rclone process to setup and maintain the +mount, waits until success or timeout and exits with appropriate code +(killing the child process if it fails). On Linux/macOS/FreeBSD start the mount like this, where |/path/to/local/mount| is an **empty** **existing** directory: @@ -234,12 +235,12 @@ 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... +When |rclone mount| is invoked on Unix with |--daemon| flag, the main rclone +program will wait for the background mount to become ready or until the timeout +specified by the |--daemon-wait| flag. On Linux it can check mount status using +ProcFS so the flag in fact sets **maximum** time to wait, while the real wait +can be less. On macOS / BSD the time to wait is constant and the check is +performed only at the end. We advise you to set wait time on macOS reasonably. Only supported on Linux, FreeBSD, OS X and Windows at the moment. @@ -300,20 +301,22 @@ 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. +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. +as |-o key=val,...| or |--opt=...|. Automount (classic or systemd) behaves +in a similar way. -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|. +rclone by default expects GNU-style flags |--key val|. To run it as a mount +helper you should symlink rclone binary to |/sbin/mount.rclone| and optionally +|/usr/bin/rclonefs|, e.g. |ln -s /usr/bin/rclone /sbin/mount.rclone|. +rclone will detect it and translate command-line arguments appropriately. Now you can run classic mounts like this: ||| @@ -332,7 +335,7 @@ 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 +optionally accompanied by systemd automount unit ||| # /etc/systemd/system/mnt-data.automount [Unit] @@ -351,25 +354,26 @@ sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2 ||| or use classic Automountd. -Remember to provide explicit |config=...,cache-dir=...| as mount units -run without |HOME|. +Remember to provide explicit |config=...,cache-dir=...| as a workaround for +mount units being 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. +or spaces can be wrapped in single or double quotes. Any inner quotes inside outer +quotes of the same type 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. +- |env.NAME=VALUE| will set an environment variable for the mount process. + This helps with Automountd and Systemd.mount which don't allow setting + 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|. +- |command=cmount| can be used to run |cmount| or any other rclone command + rather than the default |mount|. +- |args2env| will pass mount options to the mount helper running in background + 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 + are intended only for Automountd and ignored by rclone. ` diff --git a/docs/content/commands/rclone_mount.md b/docs/content/commands/rclone_mount.md index fc3aaa347..2bcde9883 100644 --- a/docs/content/commands/rclone_mount.md +++ b/docs/content/commands/rclone_mount.md @@ -18,14 +18,15 @@ FUSE. First set up your remote using `rclone config`. Check it works with `rclone ls` etc. -On Linux and macOS, 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. -You can only run mount in foreground mode on Windows. +On Linux and macOS, you can run mount in either foreground or background (aka +daemon) mode. Mount runs in foreground mode by default. Use the `--daemon` flag +to force background mode. On Windows you can run mount in foreground only, +the flag is ignored. -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. +In background mode rclone acts as a generic Unix mount program: the main +program starts, spawns background rclone process to setup and maintain the +mount, waits until success or timeout and exits with appropriate code +(killing the child process if it fails). On Linux/macOS/FreeBSD start the mount like this, where `/path/to/local/mount` is an **empty** **existing** directory: @@ -247,12 +248,12 @@ 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... +When `rclone mount` is invoked on Unix with `--daemon` flag, the main rclone +program will wait for the background mount to become ready or until the timeout +specified by the `--daemon-wait` flag. On Linux it can check mount status using +ProcFS so the flag in fact sets **maximum** time to wait, while the real wait +can be less. On macOS / BSD the time to wait is constant and the check is +performed only at the end. We advise you to set wait time on macOS reasonably. Only supported on Linux, FreeBSD, macOS and Windows at the moment. @@ -313,20 +314,22 @@ 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. +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. +as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) behaves +in a similar way. -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`. +rclone by default expects GNU-style flags `--key val`. To run it as a mount +helper you should symlink rclone binary to `/sbin/mount.rclone` and optionally +`/usr/bin/rclonefs`, e.g. `ln -s /usr/bin/rclone /sbin/mount.rclone`. +rclone will detect it and translate command-line arguments appropriately. Now you can run classic mounts like this: ``` @@ -345,7 +348,7 @@ 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 +optionally accompanied by systemd automount unit ``` # /etc/systemd/system/mnt-data.automount [Unit] @@ -364,27 +367,28 @@ sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2 ``` or use classic Automountd. -Remember to provide explicit `config=...,cache-dir=...` as mount units -run without `HOME`. +Remember to provide explicit `config=...,cache-dir=...` as a workaround for +mount units being 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. +or spaces can be wrapped in single or double quotes. Any inner quotes inside outer +quotes of the same type 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. +- `env.NAME=VALUE` will set an environment variable for the mount process. + This helps with Automountd and Systemd.mount which don't allow setting + 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`. +- `command=cmount` can be used to run `cmount` or any other rclone command + rather than the default `mount`. +- `args2env` will pass mount options to the mount helper running in background + 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 + are intended only for Automountd and ignored by rclone. ## chunked reading