add information about using the masterkey as credentials

src/commands/forget/recover_no_free_space_error.md

@@ -13,8 +13,16 @@ If you can guarantee that the repository is not used by parallel processes, you
 can also use `rustic prune --instant-delete`.
 
 To use as little scratch space as possibe, run
-`rustic prune --max-repack-size 0`. This removes all unneeded packs without
-repacking partly used packs. Obviously, this can only work if several snapshots
-have been removed using `forget` before. This then allows the `prune` command to
-actually remove data from the repository. If the command succeeds, but there is
-still little free space, then remove a few more snapshots and run `prune` again.
+`rustic prune --max-repack-size 0 --instant-delete` (and make sure no parallel
+process acesses the repository!). This removes all unneeded packs without
+repacking partly used packs. You may need to remove some snapshots using
+`forget` before. This then allows the `prune` command to actually remove data
+from the repository. If the command succeeds, but there is still little free
+space, then remove a few more snapshots and run `prune` again.
+
+In cases where the above commands do not work, `prune` fails because it first
+writes modified index files before removing old ones. To first remove the
+no-loger used index files, use
+`rustic prune --max-repack-size 0 --instant-delete --early-delete-index`. Note
+that if this `prune` run is aborted for some reasons, you first must rebuild
+your index.

src/commands/init/intro.md

@@ -10,17 +10,18 @@ here.
 Note that rustic supports to store configuration in a config profile file in the
 TOML format which is the preferred way to configure rustic.
 
-For the password, several options exist:
+For the credentials, several options exist:
 
-- Setting the password directly in the config profile file:
+- Setting the password directly via the environement variable `RUSTIC_PASSWORD`,
+  the CLI option `--password` (*warning*: This may leak the password in a
+  process list, don't use when others can see the running processes) or in the
+  config profile file:
 
 ```toml
 [repository]
 password = "secret"
 ```
 
-- Setting the environment variable `RUSTIC_PASSWORD`
-
 - Specifying the path to a file with the password via the CLI option
   `--password-file`, the environment variable `RUSTIC_PASSWORD_FILE`, or setting
   in the configuration profile
@@ -30,7 +31,7 @@ password = "secret"
 password-file = "/path/to/my/password.txt"
 ```
 
-- Configuring a program to be called when the password is needed via the CLI
+- Configuring a program which is called to obtain the password; via the CLI
   option `--password-command` , the environment variable
   `RUSTIC_PASSWORD_COMMAND` or setting in the configuration profile
 
@@ -39,10 +40,40 @@ password-file = "/path/to/my/password.txt"
 password-command = "get_my_password.sh"
 ```
 
-If none of these password options is used, rustic will query for a password
-(followed by a confirmation query if the password is to be set).
+- Setting the masterkey directly environement variable `RUSTIC_KEY`, the CLI
+  option `--key` (*warning*: This may leak the key in a process list, don't use
+  when others can see the running processes) or in the config profile file:
+
+```toml
+[repository]
+key = '{"mac":{"k":"TEQN3py56U36eH4hTTgaUA==","r":"+/Cc+P7jN42a7bZVZYyAcw=="},"encrypt":"LKyGDH7dfX24a9u+3q8DgvuFVDfI3fNrzeo6l4r8u64="}'
+```
+
+- Specifying the path to a file with the masterkey via the CLI option
+  `--key-file`, the environment variable `RUSTIC_KEY_FILE`, or setting in the
+  configuration profile
+
+```toml
+[repository]
+key-file = "/path/to/my/masterkey.txt"
+```
+
+- Configuring a program which is called to obtain the masterkey; via the CLI
+  option `--key-command` , the environment variable `RUSTIC_KEY_COMMAND` or
+  setting in the configuration profile
+
+```toml
+[repository]
+key-command = "get_my_masterkey.sh"
+```
+
+Note that you can create a new masterkey before initializeing a new repository
+by running `rustic key create`.
+
+If none of these above credential options is used, rustic will query for a
+password (followed by a confirmation query if the password is to be set).
 
-If you have configured your repository and password in the config profile,
+If you have configured your repository and credentials in the config profile,
 simply run
 
 ```console
@@ -65,7 +96,17 @@ repository version and shows new features introduced by the repository format.
 Moreover, there are different options which can be set when initializing a
 repository:
 
-Options to specify the target pack size:
+- `--set-chunker`, `--set-chunk-size`, `--set-chunk-min-size`,
+  `--set-chunk-max-size` allows to tweak the chunker settings. Currently `rabin`
+  and `fixed_size` are available chunkers. Default is `fixed_size` with an
+  (average) chunk size of 1MiB, a minimum of 512kiB and a maximum of 8MiB.
+- `--set-compression` allows to set the zstd compression level
+- `--set-append-only` puts the repository in append-only mode disabling commands
+  which would remove files.
+- `--set-extra-verify` will perform extra verifications before uploading data
+  (default: true, you can unset this with this option.)
+
+Additionally, there are options to specify the target pack size:
 
 - `--set-treepack-size`, `--set-datapack-size` specify the default target pack
   size for tree and data pack files. Arguments can given using TODO For example,

src/commands/misc/filter.md

@@ -43,13 +43,16 @@ filter-paths = ["/srv"]
 ```
 
 **Note**: For paths and tags it is already possible to give multiple values -
-and then they are `and`ed: `filter-tags=["a,b"]` matches snapshots which have
-both "a" and "b" as tags, whereas `filter-tags=["a","b"]` matches snapshots
+and then they are `and`ed: `filter-tags = ["a,b"]` matches snapshots which have
+both "a" and "b" as tags, whereas `filter-tags = ["a","b"]` matches snapshots
 which have either "a" or "b" as tag.
 
-What is (currently) not possible is to filter exactly for a tag list or path
-list: A snapshot with tags "a,b,c" is currently shown when you specify
-`filter-tags=["a,b"]`.
+Note that `filter-tags` and `filter-paths` also match snapshots which do have
+additional tags or paths, respectively.
+
+For example, a snapshot with tags "a,b,c" is currently shown when you specify
+`filter-tags=["a,b"]`. If you want to get only snapshots with the exact list of
+tags/paths, use `filter-tags-exact` and filter-paths-exact`.
 
 ## Filtering snapshots to copy
 

src/commands/misc/key.md

@@ -1,8 +1,12 @@
-# Key - Manage repository keys
+# Key - Manage repository passwords/keys
 
-The `key` command allows you to set multiple access keys or passwords per
-repository. In fact, you can use the `list`, `add`, `remove`, and `passwd`
-(changes a password) sub-commands to manage these keys very precisely:
+The `key` command allows you to set multiple passwords/access keys for a
+repository. Note that all keys share the same masterkey which is actually used
+for the encryption. Every password/key can be used to derive the masterkey and
+has thus full control over the repository.
+
+You can use the `list`, `add`, `remove`, and `passwd` (changes a password)
+sub-commands to manage these passwords/keys very precisely:
 
 ```console
     $ rustic key list
@@ -21,6 +25,53 @@ repository. In fact, you can use the `list`, `add`, `remove`, and `passwd`
     |-----------|----------|---------|--------------------------------------|
     | *8a9d4286 | username | kasimir | 2025-08-12 13:29:57.759858440 +02:00 |
     | 70970299  | alex     | batman  | 2025-10-11 22:37:29.759858440 +02:00 |
+
+    $ rustic key remove 7
+    [INFO] key 70970299 successfully removed.
+```
+
+**Note**: If the repository is opend by a password, the corresponding used key
+is indicated by an asterisk (`*`) and cannot be removed for safety reasons.
+
+## Changing credentials from password/key-based to masterkey-based
+
+1. Export the masterkey using `rustic key export`, e.g.
+
+```console
+$ rustic key export /path/to/key-file
+```
+
+2. Set this key as credentials to use, e.g. in the profile
+
+```toml
+[repository]
+key-file = "/path/to/key-file"
+```
+
+3. (optionally) list and remove all passwords/keys
+
+```console
+$ rustic key list
+$ rustic key remove <FIRST ENTRY>
+$ rustic key remove <SECOND ENTRY>
+...
+```
+
+## Changing credentials from masterkey-based to password/key-based
+
+1. Create a key from a password (if not already existing):
+
+```console
+$ rustic key add
+enter password for new key: [hidden]
+[INFO] key 70970299 successfully added.
+```
+
+2. Set this password as credential, e.g.
+
+```toml
+[repository]
+password = "my-password"
 ```
 
-**Note**: that the currently used key is indicated by an asterisk (`*`).
+3. (optionally) remove masterkey from configs or where it is stored.

src/commands/misc/upgrading_repository_format.md

@@ -1,18 +1,18 @@
 # Upgrading the repository format version
 
-Repositories created using earlier rustic versions use an older repository
-format version and have to be upgraded to allow using all new features.
-Upgrading must be done explicitly as a newer repository version increases the
-minimum rustic version required to access the repository. For example the
-repository format version 2 is only readable using rustic 0.2.0 or newer.
+Repositories created using earlier rustic (or restic) versions use an older
+repository format version and have to be upgraded to allow using all new
+features. Upgrading must be done explicitly as a newer repository version
+increases the minimum rustic version required to access the repository. For
+example the repository format version 2 is only readable using rustic 0.2.0 or
+newer.
 
 Upgrading to repo version 2 is a two step process: first run
-`migrate upgrade_repo_v2` which will check the repository integrity and then
-upgrade the repository version. Repository problems must be corrected before the
-migration will be possible. After the migration is complete, run `prune` to
-compress the repository metadata. To limit the amount of data rewritten in at
-once, you can use the `prune --max-repack-size size` parameter, see
-:ref:`customize-pruning` for more details.
+`config --set-version 2` which will upgrade the repository version. After the
+migration is complete, run `prune` to compress the repository metadata. To limit
+the amount of data rewritten in at once, you can use the
+`prune --max-repack-size size` parameter, see :ref:`customize-pruning` for more
+details.
 
 File contents stored in the repository will not be rewritten, data from new
 backups will be compressed. Over time more and more of the repository will be