From ae179ee63e15500db1ff5f51b5595f1b0381ca94 Mon Sep 17 00:00:00 2001 From: greatroar <@> Date: Wed, 7 Oct 2020 17:13:29 +0200 Subject: [PATCH 1/2] Systematize documentation of environment variables 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. --- doc/040_backup.rst | 12 +++++++----- doc/cache.rst | 14 ++------------ doc/manual_rest.rst | 6 +++++- 3 files changed, 14 insertions(+), 18 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 970038930..50b64ed55 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -416,6 +416,8 @@ environment variables. The following lists these environment variables: RESTIC_CACHE_DIR Location of the cache directory 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_SECRET_ACCESS_KEY Amazon S3 secret access key AWS_DEFAULT_REGION Amazon S3 default region @@ -453,12 +455,12 @@ environment variables. The following lists these environment variables: RCLONE_BWLIMIT rclone bandwidth limit -In addition to restic-specific environment variables, the following system-wide environment variables -are taken into account for various operations: +See :ref:`caching` for the rules concerning cache locations when +``RESTIC_CACHE_DIR`` is not set. - * ``$XDG_CACHE_HOME/restic``, ``$HOME/.cache/restic``: :ref:`caching`. - * ``$TMPDIR``: :ref:`temporary_files`. - * ``$PATH/fusermount``: Binary for ``restic mount``. +The external programs that restic may execute include ``rclone`` (for rclone +backends) and ``ssh`` (for the SFTP backend). These may respond to further +environment variables and configuration files; see their respective manuals. Exit status codes diff --git a/doc/cache.rst b/doc/cache.rst index 4c8009795..30b601faf 100644 --- a/doc/cache.rst +++ b/doc/cache.rst @@ -3,23 +3,13 @@ Local Cache *********** 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 -`__. 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 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 =========================== diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst index 224e20ea5..7e5e36adb 100644 --- a/doc/manual_rest.rst +++ b/doc/manual_rest.rst @@ -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 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`` * 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 ``$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 From 80911516387cf77199d6313d2bc3a203b421006e Mon Sep 17 00:00:00 2001 From: greatroar <@> Date: Fri, 19 Jun 2020 13:07:41 +0200 Subject: [PATCH 2/2] doc: Update restic mount availability and requirements NetBSD doesn't support restic mount either, so it's easier to list the positive cases. Also noted that FUSE for macOS is required on the Mac. --- doc/050_restore.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/050_restore.rst b/doc/050_restore.rst index 4ded09fec..1f5996ccc 100644 --- a/doc/050_restore.rst +++ b/doc/050_restore.rst @@ -71,10 +71,11 @@ command to serve the repository with FUSE: Now serving /srv/restic-repo at /mnt/restic When finished, quit with Ctrl-c or umount the mountpoint. -Mounting repositories via FUSE is not possible on OpenBSD, Solaris/illumos -and Windows. For Linux, the ``fuse`` kernel module needs to be loaded. For -FreeBSD, you may need to install FUSE and load the kernel module (``kldload -fuse``). +Mounting repositories via FUSE is only possible on Linux, macOS and FreeBSD. +On Linux, the ``fuse`` kernel module needs to be loaded and the ``fusermount`` +command needs to be in the ``PATH``. On macOS, you need `FUSE for macOS +`__. On FreeBSD, you may need to install FUSE +and load the kernel module (``kldload fuse``). Restic supports storage and preservation of hard links. However, since hard links exist in the scope of a filesystem by definition, restoring