extern/rclone
1
0
Fork 0
mirror of https://github.com/rclone/rclone.git synced 2024-11-07 17:14:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

mount/docs: improve wording

Browse Source
This commit is contained in:
Ivan Andreev 2021-10-09 14:16:33 +03:00
parent a5b8fcc127
commit bce395385d
2 changed files with 76 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
cmd/mountlib/help.go
View File

@ -8,14 +8,15 @@ FUSE.
First set up your remote using |rclone config|. Check it works with |rclone ls| etc. 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. On Linux and macOS, you can run mount in either foreground or background (aka
Mount runs in foreground mode by default, use the |--daemon| flag to specify background mode. daemon) mode. Mount runs in foreground mode by default. Use the |--daemon| flag
You can only run mount in foreground mode on Windows. 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 In background mode rclone acts as a generic Unix mount program: the main
starts, spawns a background rclone process to setup and maintain the mount, waits program starts, spawns background rclone process to setup and maintain the
until success or timeout, kills the child process if mount fails, and immediately mount, waits until success or timeout and exits with appropriate code
exits with appropriate return code. (killing the child process if it fails).
On Linux/macOS/FreeBSD start the mount like this, where |/path/to/local/mount| On Linux/macOS/FreeBSD start the mount like this, where |/path/to/local/mount|
is an **empty** **existing** directory: 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 directories will have a tendency to disappear once they fall out of
the directory cache. the directory cache.
When mount is invoked on Unix with |--daemon|, the main rclone program When |rclone mount| is invoked on Unix with |--daemon| flag, the main rclone
will wait until the background mount is ready until timeout specified by program will wait for the background mount to become ready or until the timeout
the |--daemon-wait| flag. On Linux rclone will poll ProcFS to check status specified by the |--daemon-wait| flag. On Linux it can check mount status using
so the flag sets the **maximum time to wait**. On macOS/BSD the time to wait ProcFS so the flag in fact sets **maximum** time to wait, while the real wait
is constant and the check is performed only at the end of sleep so don't can be less. On macOS / BSD the time to wait is constant and the check is
set it too high... 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. 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 Note that systemd runs mount units without any environment variables including
|PATH| or |HOME|. This means that tilde (|~|) expansion will not work |PATH| or |HOME|. This means that tilde (|~|) expansion will not work
and you should provide |--config| and |--cache-dir| explicitly as absolute and you should provide |--config| and |--cache-dir| explicitly as absolute
paths via rclone arguments. Since mounting requires the |fusermount| program, paths via rclone arguments.
rclone will use the fallback PATH of |/bin:/usr/bin| in this scenario. Since mounting requires the |fusermount| program, rclone will use the fallback
Please ensure that |fusermount| is present on this PATH. PATH of |/bin:/usr/bin| in this scenario. Please ensure that |fusermount|
is present on this PATH.
### Rclone as Unix mount helper ### Rclone as Unix mount helper
The core Unix program |/bin/mount| normally takes the |-t FSTYPE| argument The core Unix program |/bin/mount| normally takes the |-t FSTYPE| argument
then runs the |/sbin/mount.FSTYPE| helper program passing it mount options then runs the |/sbin/mount.FSTYPE| helper program passing it mount options
as |-o key=val,...| or |--opt=...|. Automount (classic or systemd) follows as |-o key=val,...| or |--opt=...|. Automount (classic or systemd) behaves
the suit. in a similar way.
rclone by default expects GNU-style flags |--key val|. To run it as a rclone by default expects GNU-style flags |--key val|. To run it as a mount
mount helper you should symlink the rclone binary to |/sbin/mount.rclone| helper you should symlink rclone binary to |/sbin/mount.rclone| and optionally
and optionally |/usr/bin/rclonefs|, e.g. |ln -s /usr/bin/rclone /sbin/mount.rclone|. |/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: 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 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 # /etc/systemd/system/mnt-data.automount
[Unit] [Unit]
@ -351,25 +354,26 @@ sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2
||| |||
or use classic Automountd. or use classic Automountd.
Remember to provide explicit |config=...,cache-dir=...| as mount units Remember to provide explicit |config=...,cache-dir=...| as a workaround for
run without |HOME|. mount units being run without |HOME|.
Rclone in the mount helper mode will split |-o| argument(s) by comma, replace |_| 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 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 or spaces can be wrapped in single or double quotes. Any inner quotes inside outer
should be doubled. quotes of the same type should be doubled.
Mount option syntax includes a few extra options treated specially: Mount option syntax includes a few extra options treated specially:
- |env.NAME=VALUE| will set an environment variable for. - |env.NAME=VALUE| will set an environment variable for the mount process.
This helps with Automountd and Systemd.mount which don't allow to set custom This helps with Automountd and Systemd.mount which don't allow setting
environment for mount helpers. custom environment for mount helpers.
Typically you will use |env.HTTPS_PROXY=proxy.host:3128| or |env.HOME=/root| 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 - |command=cmount| can be used to run |cmount| or any other rclone command
- |args2env| will pass mount options to the background mount helper via environment rather than the default |mount|.
variables instead of command line arguments. This allows to hide secrets from such - |args2env| will pass mount options to the mount helper running in background
commands as |ps| or |pgrep|. 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| - |vv...| will be transformed into appropriate |--verbose=N|
- standard mount options like |x-systemd.automount|, |_netdev|, |nosuid| and alike - 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.
` `

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

@ -18,14 +18,15 @@ FUSE.
First set up your remote using `rclone config`. Check it works with `rclone ls` etc. 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. On Linux and macOS, you can run mount in either foreground or background (aka
Mount runs in foreground mode by default, use the `--daemon` flag to specify background mode. daemon) mode. Mount runs in foreground mode by default. Use the `--daemon` flag
You can only run mount in foreground mode on Windows. 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 In background mode rclone acts as a generic Unix mount program: the main
starts, spawns a background rclone process to setup and maintain the mount, waits program starts, spawns background rclone process to setup and maintain the
until success or timeout, kills the child process if mount fails, and immediately mount, waits until success or timeout and exits with appropriate code
exits with appropriate return code. (killing the child process if it fails).
On Linux/macOS/FreeBSD start the mount like this, where `/path/to/local/mount` On Linux/macOS/FreeBSD start the mount like this, where `/path/to/local/mount`
is an **empty** **existing** directory: 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 directories will have a tendency to disappear once they fall out of
the directory cache. the directory cache.
When mount is invoked on Unix with `--daemon`, the main rclone program When `rclone mount` is invoked on Unix with `--daemon` flag, the main rclone
will wait until the background mount is ready until timeout specified by program will wait for the background mount to become ready or until the timeout
the `--daemon-wait` flag. On Linux rclone will poll ProcFS to check status specified by the `--daemon-wait` flag. On Linux it can check mount status using
so the flag sets the **maximum time to wait**. On macOS/BSD the time to wait ProcFS so the flag in fact sets **maximum** time to wait, while the real wait
is constant and the check is performed only at the end of sleep so don't can be less. On macOS / BSD the time to wait is constant and the check is
set it too high... 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. 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 Note that systemd runs mount units without any environment variables including
`PATH` or `HOME`. This means that tilde (`~`) expansion will not work `PATH` or `HOME`. This means that tilde (`~`) expansion will not work
and you should provide `--config` and `--cache-dir` explicitly as absolute and you should provide `--config` and `--cache-dir` explicitly as absolute
paths via rclone arguments. Since mounting requires the `fusermount` program, paths via rclone arguments.
rclone will use the fallback PATH of `/bin:/usr/bin` in this scenario. Since mounting requires the `fusermount` program, rclone will use the fallback
Please ensure that `fusermount` is present on this PATH. PATH of `/bin:/usr/bin` in this scenario. Please ensure that `fusermount`
is present on this PATH.
## Rclone as Unix mount helper ## Rclone as Unix mount helper
The core Unix program `/bin/mount` normally takes the `-t FSTYPE` argument The core Unix program `/bin/mount` normally takes the `-t FSTYPE` argument
then runs the `/sbin/mount.FSTYPE` helper program passing it mount options then runs the `/sbin/mount.FSTYPE` helper program passing it mount options
as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) follows as `-o key=val,...` or `--opt=...`. Automount (classic or systemd) behaves
the suit. in a similar way.
rclone by default expects GNU-style flags `--key val`. To run it as a rclone by default expects GNU-style flags `--key val`. To run it as a mount
mount helper you should symlink the rclone binary to `/sbin/mount.rclone` helper you should symlink rclone binary to `/sbin/mount.rclone` and optionally
and optionally `/usr/bin/rclonefs`, e.g. `ln -s /usr/bin/rclone /sbin/mount.rclone`. `/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: 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 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 # /etc/systemd/system/mnt-data.automount
[Unit] [Unit]
@ -364,27 +367,28 @@ sftp1:subdir /mnt/data rclone rw,noauto,nofail,_netdev,x-systemd.automount,args2
``` ```
or use classic Automountd. or use classic Automountd.
Remember to provide explicit `config=...,cache-dir=...` as mount units Remember to provide explicit `config=...,cache-dir=...` as a workaround for
run without `HOME`. mount units being run without `HOME`.
Rclone in the mount helper mode will split `-o` argument(s) by comma, replace `_` 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 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 or spaces can be wrapped in single or double quotes. Any inner quotes inside outer
should be doubled. quotes of the same type should be doubled.
Mount option syntax includes a few extra options treated specially: Mount option syntax includes a few extra options treated specially:
- `env.NAME=VALUE` will set an environment variable for. - `env.NAME=VALUE` will set an environment variable for the mount process.
This helps with Automountd and Systemd.mount which don't allow to set custom This helps with Automountd and Systemd.mount which don't allow setting
environment for mount helpers. custom environment for mount helpers.
Typically you will use `env.HTTPS_PROXY=proxy.host:3128` or `env.HOME=/root` 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 - `command=cmount` can be used to run `cmount` or any other rclone command
- `args2env` will pass mount options to the background mount helper via environment rather than the default `mount`.
variables instead of command line arguments. This allows to hide secrets from such - `args2env` will pass mount options to the mount helper running in background
commands as `ps` or `pgrep`. 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` - `vv...` will be transformed into appropriate `--verbose=N`
- standard mount options like `x-systemd.automount`, `_netdev`, `nosuid` and alike - 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 ## chunked reading