Configuration file :: resticprofile

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisite resticprofile is an automation tool for restic, also known as a wrapper. In short, resticprofile provides a configuration file and a runner that generates all necessary calls to restic. Unless you’re using the resticprofile Docker image, you need to have restic installed on your machine. Choose Your Favorite Format The resticprofile configuration file can be written in: TOML: configuration file with extension .toml or .conf YAML: configuration file with extension .yaml JSON: configuration file with extension .json HCL: configuration file with extension .hcl We recommend using either TOML or YAML.

Examples

Mon, 01 Jan 0001 00:00:00 +0000

Simple configuration using Azure storage Here’s a simple configuration file using a Microsoft Azure backend. You will notice that the env section lets you define environment variables: toml yaml hcl version = "1" [default] repository = "azure:restic:/" password-file = "key" option = "azure.connections=3" [default.env] AZURE_ACCOUNT_NAME = "my_storage_account" AZURE_ACCOUNT_KEY = "my_super_secret_key" [default.backup] exclude-file = "excludes" exclude-caches = true one-file-system = true tag = [ "root" ] source = [ "/", "/var" ] schedule = "daily" schedule-after-network-online = true version: "1" default: repository: "azure:restic:/" password-file: "key" option: "azure.connections=3" env: AZURE_ACCOUNT_NAME: "my_storage_account" AZURE_ACCOUNT_KEY: "my_super_secret_key" backup: exclude-file: "excludes" exclude-caches: true one-file-system: true tag: - "root" source: - "/" - "/var" schedule: "daily" schedule-after-network-online: true default { repository = "azure:restic:/" password-file = "key" options = "azure.connections=3" env { AZURE_ACCOUNT_NAME = "my_storage_account" AZURE_ACCOUNT_KEY = "my_super_secret_key" } backup = { exclude-file = "excludes" exclude-caches = true one-file-system = true tag = [ "root" ] source = [ "/", "/var" ] } } Configuration with inheritance Here’s a more complex configuration file showing profile inheritance and two backup profiles using the same repository:

Path

Mon, 01 Jan 0001 00:00:00 +0000

How paths inside the configuration are resolved All file paths in the configuration are resolved relative to the configuration path, the path where the main configuration file was loaded from. The big exceptions are source in the backup section, status-file, prometheus-save-to-file and the restic repository (if it is a file). These paths are taken as specified, which means they are resolved from the current working directory where you started resticprofile from.

Includes

Mon, 01 Jan 0001 00:00:00 +0000

The configuration may be split into multiple files by adding includes = "glob-pattern" to the main configuration file. E.g. the following profiles.conf loads configurations from conf.d and profiles.d: toml yaml hcl json version = "1" # Includes includes = ["conf.d/*.conf", "profiles.d/*.yaml", "profiles.d/*.toml"] # Defaults [global] initialize = true version: "1" includes: - "conf.d/*.conf" - "profiles.d/*.yaml" - "profiles.d/*.toml" global: initialize: true includes = ["conf.d/*.conf", "profiles.d/*.yaml", "profiles.d/*.toml"] global { initialize = true } { "version": "1", "includes": [ "conf.d/*.conf", "profiles.d/*.yaml", "profiles.d/*.toml" ], "global": { "initialize": true } } Included configuration files may use any supported format and settings are merged so that multiple files can extend the same profiles. The HCL format is special in that it cannot be mixed with other formats.

Inheritance

Mon, 01 Jan 0001 00:00:00 +0000

Tip You can use resticprofile [.]show (or resticprofile [--name ] show) to see the effect inheritance has on a profile Profile Inheritance Profiles can inherit from a parent profile. This allows to define the general behaviour and common configuration in a base profile while derived profiles only define what is specific, e.g. what needs to be included in the backup or which command hooks (e.g. run-before, run-after & run-finally) must be started.

Copy command

Mon, 01 Jan 0001 00:00:00 +0000

Special case for the copy command section The copy command needs two repositories (and quite likely 2 different set of keys). You can configure a copy section like this: toml yaml hcl version = "1" [default] initialize = false repository = "/backup/original" password-file = "key" [default.copy] initialize = true repository = "/backup/copy" password-file = "other_key" version: "1" default: initialize: false repository: "/backup/original" password-file: key copy: initialize: true repository: "/backup/copy" password-file: other_key default { initialize = false repository = "/backup/original" password-file = "key" copy = { initialize = true repository = "/backup/copy" password-file = "other_key" } } You will note that the secondary repository doesn’t need to have a 2 behind its flags (repository2, password-file2, etc.) nor it is prefixed by a from for the more recent version of restic (from-repo, from-password-file, etc.). It’s because the flags are well separated in the configuration and there’s no ambiguity.

Command Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Run commands before, after success or after failure resticprofile has 2 places where you can run commands around restic: commands that will run before and after every restic command (snapshots, backup, check, forget, prune, mount, etc.). These are placed at the root of each profile and are always considered. commands that will only run before and after specific restic commands. These are placed in supported sections of your profiles (currently supported are backup, copy, dump, find, ls, mount, restore, snapshots, stats and tag). Here’s an example of all the external commands that you can run during the execution of a profile:

HTTP Hooks

Mon, 01 Jan 0001 00:00:00 +0000

Send HTTP messages before and after a job As well as being able to run shell commands, you can now send HTTP messages before, after (success or failure) running a restic command. The sections that allow sending HTTP hooks are: backup copy check forget prune Tip You might notice that’s the same sections that can also be scheduled Each of these commands can send 4 different types of hooks:

Templates

Mon, 01 Jan 0001 00:00:00 +0000

Templates are a great way to compose configuration profiles. Please keep in mind that yaml files are sensitive to the number of spaces. Also if you declare a block already declared, it overrides the previous declaration (instead of merging them). For that matter, configuration templates are probably more useful if you use the toml or hcl configuration format. Here’s a simple example {{ define "hello" }} hello = "world" {{ end }} To use the content of this template anywhere in your configuration, simply call it:

Variables

Mon, 01 Jan 0001 00:00:00 +0000

Variable expansion in configuration file You might want to reuse the same configuration (or bits of it) on different environments. One way of doing it is to create a generic configuration where specific bits can be replaced by a variable. There are two kinds of variables: template variables: These variables are fixed once the full configuration file is loaded: includes are loaded, and inheritance is resolved. These variables are replaced by their value before the configuration is parsed. runtime variables: These variables are replaced by their value after the configuration is parsed. In other words: these variables are replaced by their value just before the command is executed. Template variables Pre-defined variables The syntax for using a pre-defined variable is:

Warnings

Mon, 01 Jan 0001 00:00:00 +0000

Warnings from restic Until version 0.13.0, resticprofile was always considering a restic warning as an error. This will remain the default. But the version 0.13.0 introduced a parameter to avoid this behaviour and consider that the backup was successful instead. A restic warning occurs when it cannot read some files, but a snapshot was successfully created. no-error-on-warning toml yaml hcl json version = "1" [profile] [profile.backup] no-error-on-warning = true version: "1" profile: backup: no-error-on-warning: true "profile" = { "backup" = { "no-error-on-warning" = true } } { "version": "1", "profile": { "backup": { "no-error-on-warning": true } } }

Priority

Mon, 01 Jan 0001 00:00:00 +0000

By default, restic is running with the default priority. It means it will get equal share of the resources with other processes. You can lower the priority of restic to avoid slowing down other processes. This is especially useful when you run restic on a production server. Nice You can use these values for the priority parameter, string or numeric values are both valid: String value “nice” equivalent on unixes Notes Idle 19 Background 1 15 This mode is NOT recommended on Windows 11 1 Low 10 Normal 0 Default priority when unspecified High -10 Highest -20 IO Nice This setting is only available on Linux. It allows you to set the disks IO priority of restic.

Preventing system sleep

Mon, 01 Jan 0001 00:00:00 +0000

This feature is available for: macOS Windows Linux with systemd (logind) There’s a global parameter called prevent-sleep that you can set to true, and resticprofile will prevent your system from idle sleeping. Please note: it will not prevent a sleep if the system is running on batteries it will not prevent a sleep triggered by a user action: using the sleep button, closing the laptop lid, etc.

Logs

Mon, 01 Jan 0001 00:00:00 +0000

By default resticprofile will display all logs (from itself and restic) to the console. You can redirect the logs to a local file, a temporary file or a syslog server. Destination The log destination syntax is a such: - redirects all the logs to the console / stdout (is the default log destination) filename redirects all the logs to the local file called filename temp:filename redirects all the logs to a temporary file available during the whole session, and deleted afterwards. syslog:, syslog://syslog_server[:514] or syslog-tcp://syslog_server[:514] redirects all the logs to a local or remote syslog server. Alternative configurations for remote servers are: udp://syslog_server:514 & tcp://syslog_server:514. Note Logging to syslog is not available on Windows.

JSON schema

Mon, 01 Jan 0001 00:00:00 +0000

JSON, YAML and TOML configuration files can benefit from a JSON schema that describes the config structure depending on the selected restic and configuration file version. Schema URL https://505-merge.resticprofile.pages.dev/jsonschema/config.json This schema detects config and restic version and redirects to the corresponding versioned URL. Detection requires full support for JSON Schema Draft 7. Use a versioned URL where not supported (e.g. TOML). Usage (vscode) To use a schema with vscode, begin your config files with:

Configuration v2 proposal

Mon, 01 Jan 0001 00:00:00 +0000

Note The configuration file format v2 is in preview right now. You can try to use it since v0.17.0 but it’s for testing and feedback only. Introduction The current file format was decided at the time resticprofile was only using the toml format. Nesting pieces of configuration in blocks is not the easiest as you have to specify the whole path in the block: