TrueCloudLab/restic
16
0
Fork 2
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Systematize documentation of environment variables

Browse source 
Cache locations were documented inconsistently in three places.

The backup docs mentioned PATH being used to find fusermount, which is
never run by restic backup. It now mentions ssh and rclone, which are
used by backends.

The notion of a "system-wide" environment variable makes no sense.
TMPDIR is now mentioned because it allows for optimization and may
have security implications.
This commit is contained in:
greatroar 2020-10-07 17:13:29 +02:00
parent 1ab4c710e1
commit ae179ee63e
3 changed files with 14 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
doc/040_backup.rst
View file

@ -416,6 +416,8 @@ environment variables. The following lists these environment variables:
RESTIC_CACHE_DIR Location of the cache directory RESTIC_CACHE_DIR Location of the cache directory
RESTIC_PROGRESS_FPS Frames per second by which the progress bar is updated RESTIC_PROGRESS_FPS Frames per second by which the progress bar is updated
TMPDIR Location for temporary files
AWS_ACCESS_KEY_ID Amazon S3 access key ID AWS_ACCESS_KEY_ID Amazon S3 access key ID
AWS_SECRET_ACCESS_KEY Amazon S3 secret access key AWS_SECRET_ACCESS_KEY Amazon S3 secret access key
AWS_DEFAULT_REGION Amazon S3 default region AWS_DEFAULT_REGION Amazon S3 default region
@ -453,12 +455,12 @@ environment variables. The following lists these environment variables:
RCLONE_BWLIMIT rclone bandwidth limit RCLONE_BWLIMIT rclone bandwidth limit
In addition to restic-specific environment variables, the following system-wide environment variables See :ref:`caching` for the rules concerning cache locations when
are taken into account for various operations: ``RESTIC_CACHE_DIR`` is not set.
* ``$XDG_CACHE_HOME/restic``, ``$HOME/.cache/restic``: :ref:`caching`. The external programs that restic may execute include ``rclone`` (for rclone
* ``$TMPDIR``: :ref:`temporary_files`. backends) and ``ssh`` (for the SFTP backend). These may respond to further
* ``$PATH/fusermount``: Binary for ``restic mount``. environment variables and configuration files; see their respective manuals.
Exit status codes Exit status codes

14
doc/cache.rst
View file

@ -3,23 +3,13 @@ Local Cache
*********** ***********
In order to speed up certain operations, restic manages a local cache of data. In order to speed up certain operations, restic manages a local cache of data.
This document describes the data structures for the local cache with version 1. The location of the cache directory depends on the operating system and the
environment; see :ref:`caching`.
Versions
========
The cache directory is selected according to the `XDG base dir specification
<https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__.
Each repository has its own cache sub-directory, consisting of the repository ID Each repository has its own cache sub-directory, consisting of the repository ID
which is chosen at ``init``. All cache directories for different repos are which is chosen at ``init``. All cache directories for different repos are
independent of each other. independent of each other.
The cache dir for a repo contains a file named ``version``, which contains a
single ASCII integer line that stands for the current version of the cache. If
a lower version number is found the cache is recreated with the current
version. If a higher version number is found the cache is ignored and left as
is.
Snapshots, Data and Indexes Snapshots, Data and Indexes
=========================== ===========================

6
doc/manual_rest.rst
View file

@ -398,10 +398,14 @@ This allows faster operations, since meta data does not need to be loaded from
a remote repository. The cache is automatically created, usually in an a remote repository. The cache is automatically created, usually in an
OS-specific cache folder: OS-specific cache folder:
* Linux/other: ``~/.cache/restic`` (or ``$XDG_CACHE_HOME/restic``) * Linux/other: ``$XDG_CACHE_HOME/restic``, or ``~/.cache/restic`` if
``XDG_CACHE_HOME`` is not set
* macOS: ``~/Library/Caches/restic`` * macOS: ``~/Library/Caches/restic``
* Windows: ``%LOCALAPPDATA%/restic`` * Windows: ``%LOCALAPPDATA%/restic``
If the relevant environment variables are not set, restic exits with an error
message.
The command line parameter ``--cache-dir`` or the environment variable The command line parameter ``--cache-dir`` or the environment variable
``$RESTIC_CACHE_DIR`` can be used to override the default cache location. The ``$RESTIC_CACHE_DIR`` can be used to override the default cache location. The
parameter ``--no-cache`` disables the cache entirely. In this case, all data parameter ``--no-cache`` disables the cache entirely. In this case, all data