docs: add short description of configuration file format (#5142)

Fixes #572
This commit is contained in:
albertony 2021-03-27 17:26:01 +01:00 committed by GitHub
parent 2ccf416e83
commit 9c9186183d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 41 additions and 5 deletions

View File

@ -8,8 +8,8 @@ Configure
First, you'll need to configure rclone. As the object storage systems
have quite complicated authentication these are kept in a config file.
(See the `--config` entry for how to find the config file and choose
its location.)
(See the [`--config`](#config-config-file) entry for how to find the config
file and choose its location.)
The easiest way to make the config is to run rclone with the config
option:
@ -639,7 +639,7 @@ See `--copy-dest` and `--backup-dir`.
### --config=CONFIG_FILE ###
Specify the location of the rclone config file.
Specify the location of the rclone configuration file.
Normally the config file is in your home directory as a file called
`.config/rclone/rclone.conf` (or `.rclone.conf` if created with an
@ -656,8 +656,44 @@ location is for you.
Use this flag to override the config location, e.g. `rclone
--config=".myconfig" .config`.
If this is set to empty string or the special value `/notfound` then
rclone will keep the config file in memory only.
If the location is set to empty string `""` or the special value
`/notfound`, or the os null device represented by value `NUL` on
Windows and `/dev/null` on Unix systems, then rclone will keep the
config file in memory only.
The file format is basic [INI](https://en.wikipedia.org/wiki/INI_file#Format):
Sections of text, led by a `[section]` header and followed by
`key=value` entries on separate lines. In rclone each remote is
represented by its own section, where the section name defines the
name of the remote. Options are specified as the `key=value` entries,
where the key is the option name without the `--backend-` prefix,
in lowercase and with `_` instead of `-`. E.g. option `--mega-hard-delete`
corresponds to key `hard_delete`. Only backend options can be specified.
A special, and required, key `type` identifies the [storage system](/overview/),
where the value is the internal lowercase name as returned by command
`rclone help backends`. Comments are indicated by `;` or `#` at the
beginning of a line.
Example:
[megaremote]
type = mega
user = you@example.com
pass = PDPcQVVjVtzFY-GTdDFozqBhTdsPg3qH
Note that passwords are in [obscured](/commands/rclone_obscure/)
form. Also, many storage systems uses token-based authentication instead
of passwords, and this requires additional steps. It is easier, and safer,
to use the interactive command `rclone config` instead of manually
editing the configuration file.
The configuration file will typically contain login information, and
should therefore have restricted permissions so that only the current user
can read it. Rclone tries to ensure this when it writes the file.
You may also choose to [encrypt](#configuration-encryption) the file.
When token-based authentication are used, the configuration file
must be writable, because rclone needs to update the tokens inside it.
### --contimeout=TIME ###