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

mount/docs: improve wording

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.
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.
`

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.
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