# [[restic]] _Created: 2026-01-15_ | #backup | [[010 System Administration MOC|System Administration]] Single binary encrypted backup utility. Docs: https://restic.readthedocs.io ## Concepts ## Repository https://restic.readthedocs.io/en/stable/030_preparing_a_new_repo.html > - The place where your backups will be saved is called a “repository”. > - This is simply a directory containing a set of subdirectories and files created by restic to store your backups, some corresponding metadata and encryption keys. > - To access the repository, a password (also called a key) must be specified. > - A repository can hold multiple keys that can all be used to access the repository. > - The repository can be stored locally, or on some remote server or service. ### Specifying the path in configuration > - For automated backups, restic supports specifying the repository location in the environment variable `RESTIC_REPOSITORY`. > - Restic can also read the repository location from a file specified via the `--repository-file` option or the environment variable `RESTIC_REPOSITORY_FILE`. ### Specifying the password > - You can use the environment variable `RESTIC_PASSWORD` > - You can specifying the path to a file with the password via the option `--password-file` or the environment variable `RESTIC_PASSWORD_FILE` > - Useful in cases like Kubernetes where the password is provided as a file when using secrets CSI driver > - You can configure a program to be called when the password is needed via the option `--password-command` or the environment variable `RESTIC_PASSWORD_COMMAND` > - Useful when you want to lookup the password from an external source > - Restic by default refuses to create or operate on repositories that use an empty password. > - Use `--insecure-no-password` allows disabling this check. Restic will not prompt for a password when using this option. > - For security reasons, the option must always be specified when operating on repositories with an empty password. ### Initializing the repo The repository location needs to be _initialized_ before you can start taking backups. ```shell-session $ restic init created restic repository ffc69d4bdf at /home/sandipb/restic/repo Please note that knowledge of your password is required to access the repository. Losing your password means that your data is irrecoverably lost. ``` >[!note] SMB shares >> On Linux, storing the backup repository on a CIFS (SMB) share or backing up data from a CIFS share is not recommended due to compatibility issues in older Linux kernels. ### Using remote repos #### sftp ```shell-session $ export RESTIC_REPOSITORY=sftp:sandipb@mercury:/home/sandipb/restic-repo $ restic init created restic repository c69b8030bb at sftp:sandipb@mercury:/home/sandipb/restic-repo ``` - If you want to specify a path relative to the user’s home directory, pass a relative path to the SFTP backend. There is an _URL syntax_, which is needed in case you need to specify ipv6 address or port numbers ```shell-session $ export RESTIC_REPOSITORY=sftp://sandipb@mercury:2222/restic-repo ``` - Note the double slash: the first slash separates the connection settings from the path, while the second is the start of the path. To specify a relative path, use one slash. - Alternatively, you ssh config can contain the overridden ssh port for that hostname #### http ``` restic -r rest:http://host:8000/ init restic -r rest:http+unix:///tmp/rest.socket:/my_backup_repo/ init ``` - Use `RESTIC_REST_USERNAME` and `RESTIC_REST_PASSWORD` for authentication as needed #### S3 ```bash export AWS_ACCESS_KEY_ID=<MY_ACCESS_KEY> export AWS_SECRET_ACCESS_KEY=<MY_SECRET_ACCESS_KEY> # defaults to us-east-1 export AWS_DEFAULT_REGION=xxx. # can also use as parameter `-o s3.region="xxx"` ``` #### Backblaze >[!note] Use S3 instead. >> Due to issues with error handling in the current B2 library that restic uses, the recommended way to utilize Backblaze B2 is by using its S3-compatible API. #### GCP Use service accounts ```bash export GOOGLE_PROJECT_ID=123123123123 export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gs-secret-restic-key.json ``` Then ```bash restic -r gs:foo:/ init ``` > - The number of concurrent connections to the GCS service can be set with the `-o gs.connections=10` switch. By default, at most five parallel connections are established. #### rclone > - The program [rclone](https://rclone.org/) can be used to access many other different services and store data there. > - First configure a remote in rclone. ```bash restic -r rclone:foo:bar init ``` ## Group access - By default `restic init` sets repositories up to be group inaccessible. - In order to give group members read-only access we simply add the read permission bit to all repository files with `chmod`: ```bash chmod -R g+r /srv/restic-repo ``` - the read permission bit on the repository config file triggers restic’s logic to create new files as group accessible - The repository files themselve have to be accessible via Unix's permission system. So the chmod for the whole repo is necessary - For read-write, we need to use directory setgid ```bash find /srv/restic-repo -type d -exec chmod g+s '{}' \; chmod -R g+rw /srv/restic-repo ``` - This sets the `setgid` bit on all existing directories in the repository and then grants read/write permissions for group access. - This permission bit makes newly created directories inherit both the group owner (gid) and setgid bit from the parent directory. - Setting `+s` requires root perms ## Backup [[restic Backup]] ## Diffing snapshots `restic` can diff snapshots. - `restic -r /srv/restic-repo diff 5845b002 2ab627a6` - Diffing specific paths: `restic -r /srv/restic-repo diff 5845b002:/restic 2ab627a6:/restic` - Use `--metadata` to even show changes in metadata ## List snapshots ```shell-session $ restic snapshots repository 18ee1fdc opened (version 2, compression level auto) ID Time Host Tags Paths Size ------------------------------------------------------------------------------------------ 9591349c 2026-01-16 01:25:07 bree.home /Users/sandipb/.config 127.698 MiB 1c0a039a 2026-01-16 01:25:32 bree.home /opt/homebrew/etc 2.785 MiB ------------------------------------------------------------------------------------------ 2 snapshots ``` - The special snapshot ID `latest` can be used to list files and directories of the latest snapshot in the repository. - The `--host` flag can be used in conjunction to select the latest snapshot originating from a certain host only. Filter by paths: ```shell-session $ restic snapshots --path=/opt/homebrew/etc repository 18ee1fdc opened (version 2, compression level auto) ID Time Host Tags Paths Size ----------------------------------------------------------------------------------- 1c0a039a 2026-01-16 01:25:32 bree.home /opt/homebrew/etc 2.785 MiB ----------------------------------------------------------------------------------- 1 snapshots ``` - Filter by host `--host` is also supported. - You can group the listing too, using `--group-by` You can list files in snapshots using `ls`, you can filter the list by path ```shell-session $ restic ls 1c0a039a /opt/homebrew/etc/unbound repository 18ee1fdc opened (version 2, compression level auto) [0:00] 100.00% 2 / 2 index files loaded snapshot 1c0a039a of [/opt/homebrew/etc] at 2026-01-16 01:25:32.108921 -0500 EST by [email protected] filtered by [/opt/homebrew/etc/unbound]: /opt/homebrew/etc/unbound /opt/homebrew/etc/unbound/unbound.conf /opt/homebrew/etc/unbound/unbound.conf.default ``` - You can use `--long` to see the files listed like in `ls -al` ## Copying snapshot between repos ``` restic -r /srv/restic-repo-copy copy --from-repo /srv/restic-repo ``` - You can filter: `--host luigi --path /srv --tag foo,bar` You can directly specify snapshots: ``` restic -r /srv/restic-repo-copy copy --from-repo /srv/restic-repo 410b18a2 4e5d5487 latest ``` ## Removing files from snapshots Files can be removed from existing snapshots ``` restic -r /srv/restic-repo rewrite --exclude secret-file repository c881945a opened (repository version 2) successfully ``` NOTE: Will remove from all snapshots. You can directly specify a snapshot to work on ``` restic -r /srv/restic-repo rewrite --exclude secret-file 6160ddb2 ```