From 17dd7743f1c58c49f3d422566c08726ce1ae2320 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 22:38:36 -0500 Subject: [PATCH 01/29] Moving features into another file --- docs/content/_index.md | 32 ++-------------------------- docs/content/features/_index.md | 37 +++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+), 30 deletions(-) create mode 100644 docs/content/features/_index.md diff --git a/docs/content/_index.md b/docs/content/_index.md index aabf7c25..70a089d7 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -6,38 +6,10 @@ description: Configuration profiles manager for restic backup Configuration profiles manager for [restic backup](https://restic.net/) -**resticprofile** bridges the gap between a configuration file and restic backup. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority. - -With resticprofile: - -* No need to remember command parameters and environment variables -* Create multiple profiles in one configuration file -* Profiles can inherit options from other profiles -* Run the forget command before or after a backup (in a section called *retention*) -* Check a repository before or after a backup -* Create groups of profiles to run sequentially -* Run [shell commands]({{% relref "/configuration/run_hooks" %}}) before or after running a profile, useful for mounting and unmounting backup disks -* Run a [shell command]({{% relref "/configuration/run_hooks" %}}) if an error occurs -* Send a backup stream via _stdin_ -* Start restic at different [priorities]({{% relref "/configuration/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) -* Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup -* Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}}) -* Easily [schedule]({{% relref "/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*) -* Generate a simple [status file]({{% relref "/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly -* Use [template syntax]({{% relref "/configuration/templates" %}}) in your configuration file -* Automatically clear [stale locks]({{% relref "/usage/locks" %}}) -* Export a [prometheus]({{% relref "/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway -* Run shell commands in the background when non-fatal errors are detected -* Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy) -* Automatically [initialize the secondary repository]({{% relref "/configuration/copy" %}}) using the `copy-chunker-params` flag -* Send resticprofile [logs]({{% relref "/configuration/logs" %}}) to a syslog server -* Prevent the system from [idle sleeping]({{% relref "/configuration/sleep" %}}) -* View help for both restic and resticprofile via the `help` command or `-h` flag -* Avoid scheduling a job when the system is on battery -* **[new for v0.29.0]** Schedule a group of profiles (configuration `v2` only) +**resticprofile** bridges the gap between a configuration file and restic backup. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task. The configuration file supports various formats: * [TOML](https://github.com/toml-lang/toml): files with extensions *.toml* and *.conf* (for compatibility with versions before 0.6.0) * [JSON](https://en.wikipedia.org/wiki/JSON): files with extension *.json* * [YAML](https://en.wikipedia.org/wiki/YAML): files with extension *.yaml* -* [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl* \ No newline at end of file +* [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl* diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md new file mode 100644 index 00000000..7df146f9 --- /dev/null +++ b/docs/content/features/_index.md @@ -0,0 +1,37 @@ +--- +title: Features +description: Features of resticprofile +--- + +Here is a non-exhaustive list of what resticprofile offers: + +* **Profiles** + * No need to remember command parameters and environment variables + * Create multiple profiles in one configuration file + * Profiles can inherit options from other profiles + * Create groups of profiles to run sequentially + * Easily [schedule]({{% relref "/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*) + * Use [template syntax]({{% relref "/configuration/templates" %}}) in your configuration file + * **[new for v0.29.0]** Schedule a group of profiles (configuration `v2` only) +* **Automation** + * Run the forget command before or after a backup (in a section called *retention*) + * Check a repository before or after a backup + * Run [shell commands]({{% relref "/configuration/run_hooks" %}}) before or after running a profile, useful for mounting and unmounting backup disks + * Run a [shell command]({{% relref "/configuration/run_hooks" %}}) if an error occurs + * Send a backup stream via _stdin_ + * Start restic at different [priorities]({{% relref "/configuration/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) + * Automatically clear [stale locks]({{% relref "/usage/locks" %}}) +* **Monitoring** + * Generate a simple [status file]({{% relref "/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly + * Export a [prometheus]({{% relref "/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway + * Run shell commands in the background when non-fatal errors are detected + * Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy) + * Send resticprofile [logs]({{% relref "/configuration/logs" %}}) to a syslog server +* **Checks** + * Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup + * Avoid scheduling a job when the system is on battery +* **Misc** + * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}}) + * Automatically [initialize the secondary repository]({{% relref "/configuration/copy" %}}) using the `copy-chunker-params` flag + * Prevent the system from [idle sleeping]({{% relref "/configuration/sleep" %}}) + * View help for both restic and resticprofile via the `help` command or `-h` flag From 6f196ada8a39b97f171b615a96f9179daafdc751 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 22:44:41 -0500 Subject: [PATCH 02/29] Moved version into command line flags reference; Moved cmd flags ref and env ref out of index and into seperate pages --- docs/content/usage/cmdline_ref.md | 42 +++++++++++++++++++++++++++++++ docs/content/usage/env_vars.md | 38 ++++++++++++++++++++++++++++ docs/content/usage/version.md | 10 -------- 3 files changed, 80 insertions(+), 10 deletions(-) create mode 100644 docs/content/usage/cmdline_ref.md create mode 100644 docs/content/usage/env_vars.md delete mode 100644 docs/content/usage/version.md diff --git a/docs/content/usage/cmdline_ref.md b/docs/content/usage/cmdline_ref.md new file mode 100644 index 00000000..fdb4bb13 --- /dev/null +++ b/docs/content/usage/cmdline_ref.md @@ -0,0 +1,42 @@ +--- +title: Command Line Reference +weight: 5 +--- +## Version + +The `version` command displays resticprofile version. If run in verbose mode (using `--verbose` flag) additional information such as OS version, golang version and modules are displayed as well. + +```shell +resticprofile --verbose version +``` + +## Command line reference + +There are not many options on the command line, most of the options are in the configuration file. + +* **[-h | --help]**: Display quick help +* **[-c | --config] configuration_file**: Specify a configuration file other than the default ("profiles") +* **[-f | --format] configuration_format**: Specify the configuration file format: `toml`, `yaml`, `json` or `hcl` +* **[-n | --name] profile_name**: Profile section to use from the configuration file. + You can also use `[profile_name].[command]` syntax instead, this will only work if `-n` is not set. + Using `-n [profile_name] [command]` or `[profile_name].[command]` both select profile and command and are technically equivalent. +* **[--dry-run]**: Doesn't run the restic commands but display the command lines instead +* **[-q | --quiet]**: Force resticprofile and restic to be quiet (override any configuration from the profile) +* **[-v | --verbose]**: Force resticprofile and restic to be verbose (override any configuration from the profile) +* **[--trace]**: Display even more debugging information +* **[--no-ansi]**: Disable console colouring (to save output into a log file) +* **[--stderr]**: Send console output from resticprofile to stderr (is enabled for commands `cat` and `dump`) +* **[--no-lock]**: Disable resticprofile locks, neither create nor fail on a lock. restic locks are unaffected by this option. +* **[--theme]**: Can be `light`, `dark` or `none`. The colours will adjust to a +light or dark terminal (none to disable colouring) +* **[--lock-wait] duration**: Retry to acquire resticprofile and restic locks for up to the specified amount of time before failing on a lock failure. +* **[-l | --log] file path or url**: To write the logs to a file or a syslog server instead of displaying on the console. +The format of the syslog server url is `syslog-tcp://192.168.0.1:514`, `syslog://udp-server:514` or `syslog:`. +For custom log forwarding, the prefix `temp:` can be used (e.g. `temp:/t/msg.log`) to create unique log output that can be fed +into a command or http hook by referencing it with `"{{ tempFile "msg.log" }}"` in the configuration file. +* **[--command-output]**: Sets how to redirect command output when a log target is specified. Can be `auto`, `log`, `console` or `all`. +* **[-w | --wait]**: Wait at the very end of the execution for the user to press enter. +This is only useful in Windows when resticprofile is started from explorer and the console window closes automatically at the end. +* **[--ignore-on-battery]**: Don't start the profile when the computer is running on battery. You can specify a value to ignore only when the % charge left is less or equal than the value. +* **[resticprofile OR restic command]**: Like snapshots, backup, check, prune, forget, mount, etc. +* **[additional flags]**: Any additional flags to pass to the restic command line diff --git a/docs/content/usage/env_vars.md b/docs/content/usage/env_vars.md new file mode 100644 index 00000000..297e955b --- /dev/null +++ b/docs/content/usage/env_vars.md @@ -0,0 +1,38 @@ +--- +title: Environment Variables +weight: 7 +--- + +Most flags for resticprofile can be set using environment variables. If both are specified, command line flags take the precedence. + +| Flag | Environment variable | Built-In default | +|-----------------------|-----------------------------------|------------------| +| `--quiet` | `RESTICPROFILE_QUIET` | `false` | +| `--verbose` | `RESTICPROFILE_VERBOSE` | `false` | +| `--trace` | `RESTICPROFILE_TRACE` | `false` | +| `--config` | `RESTICPROFILE_CONFIG` | `"profiles"` | +| `--format` | `RESTICPROFILE_FORMAT` | `""` | +| `--name` | `RESTICPROFILE_NAME` | `"default"` | +| `--log` | `RESTICPROFILE_LOG` | `""` | +| `--command-output` | `RESTICPROFILE_COMMAND_OUTPUT` | `"auto"` | +| `--dry-run` | `RESTICPROFILE_DRY_RUN` | `false` | +| `--no-lock` | `RESTICPROFILE_NO_LOCK` | `false` | +| `--lock-wait` | `RESTICPROFILE_LOCK_WAIT` | `0` | +| `--stderr` | `RESTICPROFILE_STDERR` | `false` | +| `--no-ansi` | `RESTICPROFILE_NO_ANSI` | `false` | +| `--theme` | `RESTICPROFILE_THEME` | `"light"` | +| `--no-priority` | `RESTICPROFILE_NO_PRIORITY` | `false` | +| `--wait` | `RESTICPROFILE_WAIT` | `false` | +| `--ignore-on-battery` | `RESTICPROFILE_IGNORE_ON_BATTERY` | `0` | + +### Other environment variables + +| Environment Variable | Default | Purpose | +|---------------------------------|---------|--------------------------------------------------------------------------------------| +| `RESTICPROFILE_PWSH_NO_AUTOENV` | _empty_ | Disables powershell script pre-processing that converts unset `$VAR` into `$Env:VAR` | + +### Environment variables set by resticprofile + +| Environment Variable | Example | When | +|-----------------------------|--------------------------------|-------------------------------------| +| `RESTICPROFILE_SCHEDULE_ID` | `profiles.yaml:backup@profile` | Set when running scheduled commands | diff --git a/docs/content/usage/version.md b/docs/content/usage/version.md deleted file mode 100644 index d842a294..00000000 --- a/docs/content/usage/version.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Version" -weight: 5 ---- - -The `version` command displays resticprofile version. If run in verbose mode (using `--verbose` flag) additional information such as OS version, golang version and modules are displayed as well. - -```shell -resticprofile --verbose version -``` \ No newline at end of file From f76d5a0c4c34f3060956a43137b17b81dfd3597b Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 22:46:26 -0500 Subject: [PATCH 03/29] Cleaned up usage/index --- docs/content/usage/_index.md | 85 ++++-------------------------------- 1 file changed, 9 insertions(+), 76 deletions(-) diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index a63a43ab..52c8fc24 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -5,15 +5,19 @@ title: "Using resticprofile" weight: 3 --- +A command is either a restic command or a resticprofile own command. + +## Examples + Here are a few examples how to run resticprofile (using the main example configuration file) -See all snapshots of your `default` profile: +### See all snapshots of your `default` profile: ```shell resticprofile ``` -See all available profiles in your configuration file (and the restic commands where some flags are defined): +### See all available profiles in your configuration file (and the restic commands where some flags are defined): ```shell resticprofile profiles @@ -28,7 +32,7 @@ Groups available (name, profiles, description): ``` -Backup root & src profiles (using _full-backup_ group shown earlier) +### Backup root & src profiles (using _full-backup_ group shown earlier) ```shell resticprofile --name "full-backup" backup @@ -50,84 +54,13 @@ or using the alternative syntax: mysqldump --all-databases --order-by-primary | resticprofile stdin.backup ``` -Mount the default profile (_default_) in /mnt/restic: +### Mount the default profile (_default_) in /mnt/restic: ```shell resticprofile mount /mnt/restic ``` -Display quick help +### Display quick help ```shell resticprofile --help -``` - -A command is either a restic command or a resticprofile own command. - - -## Command line reference - -There are not many options on the command line, most of the options are in the configuration file. - -* **[-h | --help]**: Display quick help -* **[-c | --config] configuration_file**: Specify a configuration file other than the default ("profiles") -* **[-f | --format] configuration_format**: Specify the configuration file format: `toml`, `yaml`, `json` or `hcl` -* **[-n | --name] profile_name**: Profile section to use from the configuration file. - You can also use `[profile_name].[command]` syntax instead, this will only work if `-n` is not set. - Using `-n [profile_name] [command]` or `[profile_name].[command]` both select profile and command and are technically equivalent. -* **[--dry-run]**: Doesn't run the restic commands but display the command lines instead -* **[-q | --quiet]**: Force resticprofile and restic to be quiet (override any configuration from the profile) -* **[-v | --verbose]**: Force resticprofile and restic to be verbose (override any configuration from the profile) -* **[--trace]**: Display even more debugging information -* **[--no-ansi]**: Disable console colouring (to save output into a log file) -* **[--stderr]**: Send console output from resticprofile to stderr (is enabled for commands `cat` and `dump`) -* **[--no-lock]**: Disable resticprofile locks, neither create nor fail on a lock. restic locks are unaffected by this option. -* **[--theme]**: Can be `light`, `dark` or `none`. The colours will adjust to a -light or dark terminal (none to disable colouring) -* **[--lock-wait] duration**: Retry to acquire resticprofile and restic locks for up to the specified amount of time before failing on a lock failure. -* **[-l | --log] file path or url**: To write the logs to a file or a syslog server instead of displaying on the console. -The format of the syslog server url is `syslog-tcp://192.168.0.1:514`, `syslog://udp-server:514` or `syslog:`. -For custom log forwarding, the prefix `temp:` can be used (e.g. `temp:/t/msg.log`) to create unique log output that can be fed -into a command or http hook by referencing it with `"{{ tempFile "msg.log" }}"` in the configuration file. -* **[--command-output]**: Sets how to redirect command output when a log target is specified. Can be `auto`, `log`, `console` or `all`. -* **[-w | --wait]**: Wait at the very end of the execution for the user to press enter. -This is only useful in Windows when resticprofile is started from explorer and the console window closes automatically at the end. -* **[--ignore-on-battery]**: Don't start the profile when the computer is running on battery. You can specify a value to ignore only when the % charge left is less or equal than the value. -* **[resticprofile OR restic command]**: Like snapshots, backup, check, prune, forget, mount, etc. -* **[additional flags]**: Any additional flags to pass to the restic command line - -## Environment variables - -Most flags for resticprofile can be set using environment variables. If both are specified, command line flags take the precedence. - -| Flag | Environment variable | Built-In default | -|-----------------------|-----------------------------------|------------------| -| `--quiet` | `RESTICPROFILE_QUIET` | `false` | -| `--verbose` | `RESTICPROFILE_VERBOSE` | `false` | -| `--trace` | `RESTICPROFILE_TRACE` | `false` | -| `--config` | `RESTICPROFILE_CONFIG` | `"profiles"` | -| `--format` | `RESTICPROFILE_FORMAT` | `""` | -| `--name` | `RESTICPROFILE_NAME` | `"default"` | -| `--log` | `RESTICPROFILE_LOG` | `""` | -| `--command-output` | `RESTICPROFILE_COMMAND_OUTPUT` | `"auto"` | -| `--dry-run` | `RESTICPROFILE_DRY_RUN` | `false` | -| `--no-lock` | `RESTICPROFILE_NO_LOCK` | `false` | -| `--lock-wait` | `RESTICPROFILE_LOCK_WAIT` | `0` | -| `--stderr` | `RESTICPROFILE_STDERR` | `false` | -| `--no-ansi` | `RESTICPROFILE_NO_ANSI` | `false` | -| `--theme` | `RESTICPROFILE_THEME` | `"light"` | -| `--no-priority` | `RESTICPROFILE_NO_PRIORITY` | `false` | -| `--wait` | `RESTICPROFILE_WAIT` | `false` | -| `--ignore-on-battery` | `RESTICPROFILE_IGNORE_ON_BATTERY` | `0` | - -### Other environment variables - -| Environment Variable | Default | Purpose | -|---------------------------------|---------|--------------------------------------------------------------------------------------| -| `RESTICPROFILE_PWSH_NO_AUTOENV` | _empty_ | Disables powershell script pre-processing that converts unset `$VAR` into `$Env:VAR` | - -### Environment variables set by resticprofile - -| Environment Variable | Example | When | -|-----------------------------|--------------------------------|-------------------------------------| -| `RESTICPROFILE_SCHEDULE_ID` | `profiles.yaml:backup@profile` | Set when running scheduled commands | From b4090e555ca4a484a146b3bb5d4d5862280f57e8 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 22:48:31 -0500 Subject: [PATCH 04/29] Moved keyfile generation docs into Usage --- docs/content/usage/_index.md | 25 +++++++++++++++++++++++++ docs/content/usage/keyfile.md | 28 ---------------------------- docs/content/usage/locks.md | 2 -- docs/content/usage/memory.md | 3 --- 4 files changed, 25 insertions(+), 33 deletions(-) delete mode 100644 docs/content/usage/keyfile.md diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index 52c8fc24..f8034e92 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -7,6 +7,31 @@ weight: 3 A command is either a restic command or a resticprofile own command. +## Generating random keys + +Resticprofile includes a tool to generate cryptographically secure, base64-encoded random keys. Save the key to a file and use it as a strong key for Restic. + +- On Linux, FreeBSD, Dragonfly, and Solaris, Reader uses `getrandom(2)`. +- On legacy Linux (< 3.17), it uses `/dev/urandom`. +- On macOS, and OpenBSD Reader, uses `arc4random_buf(3)`. +- On NetBSD, Reader uses the kern.arandom sysctl. +- On Windows, Reader uses the ProcessPrng API. + +[Reference from the Go cryto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables) + +```shell +resticprofile generate --random-key +``` + +Generates a 1024-byte random key (converted to 1368 Base64 characters) and displays it in the console. + +To generate a key of a different size, specify the byte length in the command line. + +```shell +resticprofile generate --random-key 2048 +``` + + ## Examples Here are a few examples how to run resticprofile (using the main example configuration file) diff --git a/docs/content/usage/keyfile.md b/docs/content/usage/keyfile.md deleted file mode 100644 index 7cce3f50..00000000 --- a/docs/content/usage/keyfile.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Generate a Keyfile" -weight: 10 ---- - -## Generating random keys - -Resticprofile includes a tool to generate cryptographically secure, base64-encoded random keys. Save the key to a file and use it as a strong key for Restic. - -- On Linux, FreeBSD, Dragonfly, and Solaris, Reader uses `getrandom(2)`. -- On legacy Linux (< 3.17), it uses `/dev/urandom`. -- On macOS, and OpenBSD Reader, uses `arc4random_buf(3)`. -- On NetBSD, Reader uses the kern.arandom sysctl. -- On Windows, Reader uses the ProcessPrng API. - -[Reference from the Go cryto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables) - -```shell -resticprofile generate --random-key -``` - -Generates a 1024-byte random key (converted to 1368 Base64 characters) and displays it in the console. - -To generate a key of a different size, specify the byte length in the command line. - -```shell -resticprofile generate --random-key 2048 -``` diff --git a/docs/content/usage/locks.md b/docs/content/usage/locks.md index 9f091f58..2a1fcf91 100644 --- a/docs/content/usage/locks.md +++ b/docs/content/usage/locks.md @@ -3,8 +3,6 @@ title: "Locks" weight: 20 --- - - restic is already using a lock to avoid running some operations at the same time. Since resticprofile can run several commands in a profile, it could be better to run the whole batch in a lock so nobody can interfere in the meantime. diff --git a/docs/content/usage/memory.md b/docs/content/usage/memory.md index bc1a86d9..73a62fe6 100644 --- a/docs/content/usage/memory.md +++ b/docs/content/usage/memory.md @@ -11,6 +11,3 @@ restic can be memory hungry. I'm running a few servers with no swap and I manage For that matter I've introduced a parameter in the `global` section called `min-memory`. The **default value is 100MB**. You can disable it by using a value of `0`. It compares against `(total - used)` which is probably the best way to know how much memory is available (that is including the memory used for disk buffers/cache). - - - From 8364c695a9c1acfb4861fe3fdfc4f5fe6cccbf44 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:00:22 -0500 Subject: [PATCH 05/29] Realized how to do nested sections --- docs/content/usage/examples/GenRandomKeys.md | 25 ++++++++ docs/content/usage/examples/_index.md | 60 ++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/content/usage/examples/GenRandomKeys.md create mode 100644 docs/content/usage/examples/_index.md diff --git a/docs/content/usage/examples/GenRandomKeys.md b/docs/content/usage/examples/GenRandomKeys.md new file mode 100644 index 00000000..0bb08381 --- /dev/null +++ b/docs/content/usage/examples/GenRandomKeys.md @@ -0,0 +1,25 @@ +--- +title: Generate Random Keys +--- + +Resticprofile includes a tool to generate cryptographically secure, base64-encoded random keys. Save the key to a file and use it as a strong key for Restic. + +- On Linux, FreeBSD, Dragonfly, and Solaris, Reader uses `getrandom(2)`. +- On legacy Linux (< 3.17), it uses `/dev/urandom`. +- On macOS, and OpenBSD Reader, uses `arc4random_buf(3)`. +- On NetBSD, Reader uses the kern.arandom sysctl. +- On Windows, Reader uses the ProcessPrng API. + +[Reference from the Go cryto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables) + +```shell +resticprofile generate --random-key +``` + +Generates a 1024-byte random key (converted to 1368 Base64 characters) and displays it in the console. + +To generate a key of a different size, specify the byte length in the command line. + +```shell +resticprofile generate --random-key 2048 +``` diff --git a/docs/content/usage/examples/_index.md b/docs/content/usage/examples/_index.md new file mode 100644 index 00000000..4a68374e --- /dev/null +++ b/docs/content/usage/examples/_index.md @@ -0,0 +1,60 @@ +--- +title: Examples +--- + +Here are a few examples how to run resticprofile (using the main example configuration file) + +### See all snapshots of your `default` profile: + +```shell +resticprofile +``` + +### See all available profiles in your configuration file (and the restic commands where some flags are defined): + +```shell +resticprofile profiles + +Profiles available (name, sections, description): + root: (backup, copy, forget, retention) + self: (backup, check, copy, forget, retention) + src: (backup, copy, retention, snapshots) + +Groups available (name, profiles, description): + full-backup: [root, src] + +``` + +### Backup root & src profiles (using _full-backup_ group shown earlier) + +```shell +resticprofile --name "full-backup" backup +``` +or using the alternative syntax: + +```shell +resticprofile full-backup.backup +``` + +Assuming the _stdin_ profile from the configuration file shown before, the command to send a mysqldump to the backup is as simple as: + +```shell +mysqldump --all-databases --order-by-primary | resticprofile --name stdin backup +``` +or using the alternative syntax: + +```shell +mysqldump --all-databases --order-by-primary | resticprofile stdin.backup +``` + +### Mount the default profile (_default_) in /mnt/restic: + +```shell +resticprofile mount /mnt/restic +``` + +### Display quick help + +```shell +resticprofile --help +``` From d1daf24e7c6a30c01f7d4f07d1b89f897ceb08b6 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:02:05 -0500 Subject: [PATCH 06/29] Moved the content out of the index of usage --- docs/content/usage/_index.md | 82 +----------------------------------- 1 file changed, 1 insertion(+), 81 deletions(-) diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index f8034e92..5a2aa2e1 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -7,85 +7,5 @@ weight: 3 A command is either a restic command or a resticprofile own command. -## Generating random keys +{{% children sort="weight" depth="2" %}} -Resticprofile includes a tool to generate cryptographically secure, base64-encoded random keys. Save the key to a file and use it as a strong key for Restic. - -- On Linux, FreeBSD, Dragonfly, and Solaris, Reader uses `getrandom(2)`. -- On legacy Linux (< 3.17), it uses `/dev/urandom`. -- On macOS, and OpenBSD Reader, uses `arc4random_buf(3)`. -- On NetBSD, Reader uses the kern.arandom sysctl. -- On Windows, Reader uses the ProcessPrng API. - -[Reference from the Go cryto library documentation](https://golang.org/pkg/crypto/rand/#pkg-variables) - -```shell -resticprofile generate --random-key -``` - -Generates a 1024-byte random key (converted to 1368 Base64 characters) and displays it in the console. - -To generate a key of a different size, specify the byte length in the command line. - -```shell -resticprofile generate --random-key 2048 -``` - - -## Examples - -Here are a few examples how to run resticprofile (using the main example configuration file) - -### See all snapshots of your `default` profile: - -```shell -resticprofile -``` - -### See all available profiles in your configuration file (and the restic commands where some flags are defined): - -```shell -resticprofile profiles - -Profiles available (name, sections, description): - root: (backup, copy, forget, retention) - self: (backup, check, copy, forget, retention) - src: (backup, copy, retention, snapshots) - -Groups available (name, profiles, description): - full-backup: [root, src] - -``` - -### Backup root & src profiles (using _full-backup_ group shown earlier) - -```shell -resticprofile --name "full-backup" backup -``` -or using the alternative syntax: - -```shell -resticprofile full-backup.backup -``` - -Assuming the _stdin_ profile from the configuration file shown before, the command to send a mysqldump to the backup is as simple as: - -```shell -mysqldump --all-databases --order-by-primary | resticprofile --name stdin backup -``` -or using the alternative syntax: - -```shell -mysqldump --all-databases --order-by-primary | resticprofile stdin.backup -``` - -### Mount the default profile (_default_) in /mnt/restic: - -```shell -resticprofile mount /mnt/restic -``` - -### Display quick help - -```shell -resticprofile --help From f1c539bc9a4c36c16a17234c9b23fd7cf7303a8b Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:18:24 -0500 Subject: [PATCH 07/29] moved monitoring into configuration, added an examples subfolder --- docs/content/configuration/_index.md | 100 --- docs/content/configuration/examples.md | 608 ++---------------- .../configuration/examples/azure-storage.md | 84 +++ .../configuration/examples/configWindows.md | 106 +++ .../examples/configWinheritence.md | 343 ++++++++++ docs/content/configuration/examples/stdin.md | 85 +++ docs/content/configuration/prometheus.md | 232 +++++++ docs/content/configuration/status.md | 176 +++++ 8 files changed, 1072 insertions(+), 662 deletions(-) create mode 100644 docs/content/configuration/examples/azure-storage.md create mode 100644 docs/content/configuration/examples/configWindows.md create mode 100644 docs/content/configuration/examples/configWinheritence.md create mode 100644 docs/content/configuration/examples/stdin.md create mode 100644 docs/content/configuration/prometheus.md create mode 100644 docs/content/configuration/status.md diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md index fa6604df..d56cea79 100644 --- a/docs/content/configuration/_index.md +++ b/docs/content/configuration/_index.md @@ -65,106 +65,6 @@ To set the flag `--password-file`, the name of the parameter is simply `password There's **one exception**: the flag `--repo` is named `repository` in the configuration -## Example - -So let's say you normally use this simple command: - -```shell -restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home -``` - -For resticprofile to generate this command automatically for you, here's the configuration file: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -# indentation is not needed but it makes it easier to read ;) -# -version = "1" - -[default] - repository = "local:/backup" - password-file = "password.txt" - - [default.backup] - verbose = true - source = [ "/home" ] -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -default: - repository: "local:/backup" - password-file: "password.txt" - - backup: - verbose: true - source: - - "/home" -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -default { - repository = "local:/backup" - password-file = "password.txt" - - backup = { - verbose = true - source = [ "/home" ] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "default": { - "repository": "local:/backup", - "password-file": "password.txt", - "backup": { - "verbose": true, - "source": [ - "/home" - ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -You may have noticed the `source` flag is accepting an array of values (inside brackets in TOML, list of values in YAML) - -Now, assuming this configuration file is named `profiles.conf` in the current folder (it's the default config file name), you can simply run - -```shell -resticprofile backup -``` - -and resticprofile will do its magic and generate the command line for you. - -If you have any doubt on what it's running, you can try a `--dry-run`: - -```shell -resticprofile --dry-run backup -2022/05/18 17:14:07 profile 'default': starting 'backup' -2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home -2022/05/18 17:14:07 profile 'default': finished 'backup' -``` - ## More information {{% children %}} diff --git a/docs/content/configuration/examples.md b/docs/content/configuration/examples.md index fe22b151..13d854d7 100644 --- a/docs/content/configuration/examples.md +++ b/docs/content/configuration/examples.md @@ -3,216 +3,29 @@ title: "Examples" weight: 5 --- -## Simple configuration using Azure storage +So let's say you normally use this simple command: -Here's a simple configuration file using a Microsoft Azure backend. You will notice that the `env` section lets you define environment variables: - -{{< tabs groupid="config-with-hcl" >}} -{{% tab title="toml" %}} - -```toml -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 +```shell +restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home ``` -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -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 -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -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" ] - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -## Configuration with inheritance -Here's a more complex configuration file showing profile inheritance and two backup profiles using the same repository: +For resticprofile to generate this command automatically for you, here's the configuration file: -{{< tabs groupid="config-with-hcl" >}} +{{< tabs groupid="config-with-json" >}} {{% tab title="toml" %}} ```toml +# indentation is not needed but it makes it easier to read ;) +# version = "1" -[global] - # ionice is available on Linux only - ionice = false - ionice-class = 2 - ionice-level = 6 - # priority is using priority class on windows, and "nice" on unixes - priority = "low" - # run 'snapshots' when no command is specified when invoking resticprofile - default-command = "snapshots" - # initialize a repository if none exist at location - initialize = false - # resticprofile won't start a profile if there's less than 100MB of RAM available - min-memory = 100 - -# a group is a profile that will call all profiles one by one -[groups] - # when starting a backup on profile "full-backup", - # it will run the "root" and "src" backup profiles - full-backup = [ "root", "src" ] - -# Default profile when not specified on the command line (-n or --name) -# There's no default inheritance from the 'default' profile, -# you can use the 'inherit' flag if needed [default] - # you can use a relative path, it will be relative to the configuration file - repository = "/backup" - password-file = "key" - initialize = false - # will run these scripts before and after each command (including 'backup') - run-before = "mount /backup" - run-after = "umount /backup" - # if a restic command fails, the run-after won't be running - # add this parameter to run the script in case of a failure - run-after-fail = "umount /backup" - - # add environment variables - [default.env] - TMPDIR= "/tmp" - -# New profile named 'root' -[root] - inherit = "default" - initialize = true - # LOCAL lockfile so you cannot run the same profile more than once at a time - # (it's totally independent of the restic locks on the repository) - lock = "/tmp/resticprofile-root.lock" - - # 'backup' command of profile 'root' - [root.backup] - # files with no path are relative to the configuration file - exclude-file = [ "root-excludes", "excludes" ] - exclude-caches = true - one-file-system = false - tag = [ "test", "dev" ] - source = [ "/" ] - # ignore restic warnings when files cannot be read - no-error-on-warning = true - # run every day at midnight - schedule = "daily" - schedule-permission = "system" - schedule-lock-wait = "2h" - - # retention policy for profile root - # retention is a special section that run the "forget" command - # before or after a backup - [root.retention] - before-backup = false - after-backup = true - keep-hourly = 1 - keep-daily = 1 - keep-weekly = 1 - keep-monthly = 1 - keep-within = "3h" - keep-tag = [ "forever" ] - prune = false - # tag can be a boolean ('true' meaning to copy tag set from 'backup') - # or a custom set of tags. - # Default is 'false', meaning that tags are NOT used. - tag = true - # host can be a boolean ('true' meaning current hostname) - # or a string to specify a different hostname - host = true - -# New profile named 'src' -[src] - inherit = "default" - initialize = true - - # 'backup' command of profile 'src' - [src.backup] - exclude = [ '/**/.git' ] - exclude-caches = true - one-file-system = false - tag = [ "test", "dev" ] - source = [ "./src" ] - check-before = true - # will only run these scripts before and after a backup - run-before = [ "echo Starting!", "ls -al ./src" ] - run-after = "sync" - # if scheduled, will run every 30 minutes - schedule = "*:0,30" - schedule-permission = "user" - schedule-lock-wait = "10m" - - # retention policy for profile src - [src.retention] - before-backup = false - after-backup = true - keep-within = "30d" - prune = true - - # check command of profile src - [src.check] - read-data = true - # if scheduled, will check the repository the first day of each month at 3am - schedule = "*-*-01 03:00" + repository = "local:/backup" + password-file = "password.txt" + [default.backup] + verbose = true + source = [ "/home" ] ``` {{% /tab %}} @@ -221,400 +34,71 @@ version = "1" ```yaml version: "1" -global: - # run 'snapshots' when no command is specified when invoking resticprofile - default-command: snapshots - # initialize a repository if none exist at location - initialize: false - # priority is using priority class on windows, and "nice" on unixes - priority: low - # resticprofile won't start a profile if there's less than 100MB of RAM available - min-memory: 100 - -# a group is a profile that will call all profiles one by one -groups: - # when starting a backup on profile "full-backup", - # it will run the "root" and "src" backup profiles - full-backup: - - root - - src - -# Default profile when not specified on the command line (-n or --name) -# There's no default inheritance from the 'default' profile, -# you can use the 'inherit' flag if needed default: - # add environment variables - env: - TMPDIR: /tmp - password-file: key - # you can use a relative path, it will be relative to the configuration file - repository: /backup - # will run these scripts before and after each command (including 'backup') - run-before: mount /backup - run-after: umount /backup - # if a restic command fails, the run-after won't be running - # add this parameter to run the script in case of a failure - run-after-fail: umount /backup - -# New profile named 'root' -root: - inherit: default - initialize: true - # LOCAL lockfile so you cannot run the same profile more than once at a time - # (it's totally independent of the restic locks on the repository) - lock: /tmp/resticprofile-root.lock - - backup: - exclude-caches: true - # files with no path are relative to the configuration file - exclude-file: - - root-excludes - - excludes - one-file-system: false - source: - - / - tag: - - test - - dev - # ignore restic warnings when files cannot be read - no-error-on-warning: true - # run every day at midnight - schedule: daily - schedule-permission: system - schedule-lock-wait: 2h - - # retention policy for profile root - # retention is a special section that run the "forget" command - # before or after a backup - retention: - before-backup: false - after-backup: true - keep-daily: 1 - keep-hourly: 1 - keep-weekly: 1 - keep-monthly: 1 - keep-within: 3h - keep-tag: - - forever - prune: false - # tag can be a boolean ('true' meaning to copy tag set from 'backup') - # or a custom set of tags. - # Default is 'false', meaning that tags are NOT used. - tag: true - # host can be a boolean ('true' meaning current hostname) - # or a string to specify a different hostname - host: true + repository: "local:/backup" + password-file: "password.txt" -# New profile named 'src' -src: - lock: "/tmp/resticprofile-profile-src.lock" - force-inactive-lock: false - inherit: default - initialize: true - - # 'backup' command of profile 'src' backup: - check-before: true - exclude: - - /**/.git - exclude-caches: true - one-file-system: false - # will only run these scripts before and after a backup - run-before: - - echo Starting! - - ls -al ~/go - run-after: echo All Done! + verbose: true source: - - ~/go - tag: - - test - - dev - # run every 30 minutes - schedule: "*:0,30" - schedule-permission: user - schedule-lock-wait: 10m - - # retention policy for profile src - retention: - before-backup: false - after-backup: true - keep-within: 30d - prune: true - - # check command of profile src - check: - read-data: true - # check the repository the first day of each month at 3am - schedule: "*-*-01 03:00" - + - "/home" ``` {{% /tab %}} {{% tab title="hcl" %}} ```hcl -global { - priority = "low" - ionice = true - ionice-class = 2 - ionice-level = 6 - # don't start if the memory available is < 1000MB - min-memory = 1000 -} - -groups { - all = ["src", "self"] -} - default { - repository = "/tmp/backup" - password-file = "key" - run-before = "echo Profile started!" - run-after = "echo Profile finished!" - run-after-fail = "echo An error occurred!" -} - - -src { - inherit = "default" - initialize = true - lock = "/tmp/backup/resticprofile-profile-src.lock" - force-inactive-lock = false - - snapshots = { - tag = [ "test", "dev" ] - } + repository = "local:/backup" + password-file = "password.txt" backup = { - run-before = [ "echo Starting!", "ls -al ~/go/src" ] - run-after = "echo All Done!" - exclude = [ "/**/.git" ] - exclude-caches = true - tag = [ "test", "dev" ] - source = [ "~/go/src" ] - check-before = true - } - - retention = { - before-backup = false - after-backup = true - keep-last = 3 - compact = false - prune = true - } - - check = { - check-unused = true - with-cache = false + verbose = true + source = [ "/home" ] } } - -self { - inherit = "default" - initialize = false - - snapshots = { - tag = [ "self" ] - } - - backup = { - source = "./" - tag = [ "self" ] - } -} - -``` - -{{% /tab %}} -{{< /tabs >}} - -## Configuration example for Windows - - -{{< tabs groupid="config-with-hcl" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[global] - restic-binary = "c:\\ProgramData\\chocolatey\\bin\\restic.exe" - -# Default profile when not specified on the command line -# There's no default inheritance from the 'default' profile, -# but you can use the 'inherit' flag if needed -[default] - repository = "local:r:/" - password-file = "key" - initialize = false - -# New profile named 'test' -[test] - inherit = "default" - initialize = true - - # 'backup' command of profile 'test' - [test.backup] - tag = [ "windows" ] - source = [ "c:\\" ] - check-after = true - run-before = "dir /l" - run-after = "echo All Done!" - # ignore restic warnings - # without it the backup is considered failed when restic can't read some files - no-error-on-warning = true ``` {{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -global: - restic-binary: c:\ProgramData\chocolatey\bin\restic.exe - -# Default profile when not specified on the command line -# There's no default inheritance from the 'default' profile, -# but you can use the 'inherit' flag if needed -default: - repository: local:r:/ - password-file: key - initialize: false - -# New profile named 'test' -test: - inherit: default - initialize: true - - # 'backup' command of profile 'test' - backup: - tag: - - windows - source: - - c:\ - check-after: true - run-before: dir /l - run-after: echo All Done! - # ignore restic warnings - # without it the backup is considered failed when restic can't read some files - no-error-on-warning: true -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -global { - restic-binary = "c:\\ProgramData\\chocolatey\\bin\\restic.exe" -} - -default { - repository = "local:r:/" - password-file = "key" - initialize = false -} - -test { - inherit = "default" - initialize = true - - backup = { - tag = [ "windows" ] - source = [ "c:\\" ] - check-after = true - run-before = "dir /l" - run-after = "echo All Done!" - no-error-on-warning = true +{{% tab title="json" %}} + +```json +{ + "version": "1", + "default": { + "repository": "local:/backup", + "password-file": "password.txt", + "backup": { + "verbose": true, + "source": [ + "/home" + ] + } } } - ``` {{% /tab %}} {{< /tabs >}} -## Use stdin in configuration - -Simple example sending a file via stdin - -{{< tabs groupid="config-with-hcl" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[stdin] - repository = "local:/backup/restic" - password-file = "key" - - [stdin.backup] - stdin = true - stdin-filename = "stdin-test" - tag = [ 'stdin' ] - -[mysql] - inherit = "stdin" - - [mysql.backup] - stdin-command = [ 'mysqldump --all-databases --order-by-primary' ] - stdin-filename = "dump.sql" - tag = [ 'mysql' ] - -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" -stdin: - repository: "local:/backup/restic" - password-file: key - backup: - stdin: true - stdin-filename: stdin-test - tag: - - stdin +You may have noticed the `source` flag is accepting an array of values (inside brackets in TOML, list of values in YAML) -mysql: - inherit: stdin - backup: - stdin-command: "mysqldump --all-databases --order-by-primary" - stdin-filename: "dump.sql" - tag: - - mysql +Now, assuming this configuration file is named `profiles.conf` in the current folder (it's the default config file name), you can simply run +```shell +resticprofile backup ``` -{{% /tab %}} -{{% tab title="hcl" %}} +and resticprofile will do its magic and generate the command line for you. -```hcl -# sending stream through stdin -stdin { - repository = "local:/backup/restic" - password-file = "key" +If you have any doubt on what it's running, you can try a `--dry-run`: - backup = { - stdin = true - stdin-filename = "stdin-test" - tag = [ "stdin" ] - } -} - -mysql { - inherit = "stdin" - - backup = { - stdin-command = [ "mysqldump --all-databases --order-by-primary" ] - stdin-filename = "dump.sql" - tag = [ "mysql" ] - } -} +```shell +resticprofile --dry-run backup +2022/05/18 17:14:07 profile 'default': starting 'backup' +2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home +2022/05/18 17:14:07 profile 'default': finished 'backup' ``` -{{% /tab %}} -{{< /tabs >}} - +{{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/examples/azure-storage.md b/docs/content/configuration/examples/azure-storage.md new file mode 100644 index 00000000..36fe6b47 --- /dev/null +++ b/docs/content/configuration/examples/azure-storage.md @@ -0,0 +1,84 @@ +--- +title: "Simple Configuration with 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: + +{{< tabs groupid="config-with-hcl" >}} +{{% tab title="toml" %}} + +```toml +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 +``` +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +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 +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +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" ] + } +} +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/configuration/examples/configWindows.md b/docs/content/configuration/examples/configWindows.md new file mode 100644 index 00000000..f7827769 --- /dev/null +++ b/docs/content/configuration/examples/configWindows.md @@ -0,0 +1,106 @@ +--- +title: "Configuration example for Windows" +--- + +{{< tabs groupid="config-with-hcl" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[global] + restic-binary = "c:\\ProgramData\\chocolatey\\bin\\restic.exe" + +# Default profile when not specified on the command line +# There's no default inheritance from the 'default' profile, +# but you can use the 'inherit' flag if needed +[default] + repository = "local:r:/" + password-file = "key" + initialize = false + +# New profile named 'test' +[test] + inherit = "default" + initialize = true + + # 'backup' command of profile 'test' + [test.backup] + tag = [ "windows" ] + source = [ "c:\\" ] + check-after = true + run-before = "dir /l" + run-after = "echo All Done!" + # ignore restic warnings + # without it the backup is considered failed when restic can't read some files + no-error-on-warning = true +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +global: + restic-binary: c:\ProgramData\chocolatey\bin\restic.exe + +# Default profile when not specified on the command line +# There's no default inheritance from the 'default' profile, +# but you can use the 'inherit' flag if needed +default: + repository: local:r:/ + password-file: key + initialize: false + +# New profile named 'test' +test: + inherit: default + initialize: true + + # 'backup' command of profile 'test' + backup: + tag: + - windows + source: + - c:\ + check-after: true + run-before: dir /l + run-after: echo All Done! + # ignore restic warnings + # without it the backup is considered failed when restic can't read some files + no-error-on-warning: true +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +global { + restic-binary = "c:\\ProgramData\\chocolatey\\bin\\restic.exe" +} + +default { + repository = "local:r:/" + password-file = "key" + initialize = false +} + +test { + inherit = "default" + initialize = true + + backup = { + tag = [ "windows" ] + source = [ "c:\\" ] + check-after = true + run-before = "dir /l" + run-after = "echo All Done!" + no-error-on-warning = true + } +} + +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/configuration/examples/configWinheritence.md b/docs/content/configuration/examples/configWinheritence.md new file mode 100644 index 00000000..66e6cbe3 --- /dev/null +++ b/docs/content/configuration/examples/configWinheritence.md @@ -0,0 +1,343 @@ +--- +title: "Configuration with inheritance" +--- + +Here's a more complex configuration file showing profile inheritance and two backup profiles using the same repository: + +{{< tabs groupid="config-with-hcl" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[global] + # ionice is available on Linux only + ionice = false + ionice-class = 2 + ionice-level = 6 + # priority is using priority class on windows, and "nice" on unixes + priority = "low" + # run 'snapshots' when no command is specified when invoking resticprofile + default-command = "snapshots" + # initialize a repository if none exist at location + initialize = false + # resticprofile won't start a profile if there's less than 100MB of RAM available + min-memory = 100 + +# a group is a profile that will call all profiles one by one +[groups] + # when starting a backup on profile "full-backup", + # it will run the "root" and "src" backup profiles + full-backup = [ "root", "src" ] + +# Default profile when not specified on the command line (-n or --name) +# There's no default inheritance from the 'default' profile, +# you can use the 'inherit' flag if needed +[default] + # you can use a relative path, it will be relative to the configuration file + repository = "/backup" + password-file = "key" + initialize = false + # will run these scripts before and after each command (including 'backup') + run-before = "mount /backup" + run-after = "umount /backup" + # if a restic command fails, the run-after won't be running + # add this parameter to run the script in case of a failure + run-after-fail = "umount /backup" + + # add environment variables + [default.env] + TMPDIR= "/tmp" + +# New profile named 'root' +[root] + inherit = "default" + initialize = true + # LOCAL lockfile so you cannot run the same profile more than once at a time + # (it's totally independent of the restic locks on the repository) + lock = "/tmp/resticprofile-root.lock" + + # 'backup' command of profile 'root' + [root.backup] + # files with no path are relative to the configuration file + exclude-file = [ "root-excludes", "excludes" ] + exclude-caches = true + one-file-system = false + tag = [ "test", "dev" ] + source = [ "/" ] + # ignore restic warnings when files cannot be read + no-error-on-warning = true + # run every day at midnight + schedule = "daily" + schedule-permission = "system" + schedule-lock-wait = "2h" + + # retention policy for profile root + # retention is a special section that run the "forget" command + # before or after a backup + [root.retention] + before-backup = false + after-backup = true + keep-hourly = 1 + keep-daily = 1 + keep-weekly = 1 + keep-monthly = 1 + keep-within = "3h" + keep-tag = [ "forever" ] + prune = false + # tag can be a boolean ('true' meaning to copy tag set from 'backup') + # or a custom set of tags. + # Default is 'false', meaning that tags are NOT used. + tag = true + # host can be a boolean ('true' meaning current hostname) + # or a string to specify a different hostname + host = true + +# New profile named 'src' +[src] + inherit = "default" + initialize = true + + # 'backup' command of profile 'src' + [src.backup] + exclude = [ '/**/.git' ] + exclude-caches = true + one-file-system = false + tag = [ "test", "dev" ] + source = [ "./src" ] + check-before = true + # will only run these scripts before and after a backup + run-before = [ "echo Starting!", "ls -al ./src" ] + run-after = "sync" + # if scheduled, will run every 30 minutes + schedule = "*:0,30" + schedule-permission = "user" + schedule-lock-wait = "10m" + + # retention policy for profile src + [src.retention] + before-backup = false + after-backup = true + keep-within = "30d" + prune = true + + # check command of profile src + [src.check] + read-data = true + # if scheduled, will check the repository the first day of each month at 3am + schedule = "*-*-01 03:00" + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +global: + # run 'snapshots' when no command is specified when invoking resticprofile + default-command: snapshots + # initialize a repository if none exist at location + initialize: false + # priority is using priority class on windows, and "nice" on unixes + priority: low + # resticprofile won't start a profile if there's less than 100MB of RAM available + min-memory: 100 + +# a group is a profile that will call all profiles one by one +groups: + # when starting a backup on profile "full-backup", + # it will run the "root" and "src" backup profiles + full-backup: + - root + - src + +# Default profile when not specified on the command line (-n or --name) +# There's no default inheritance from the 'default' profile, +# you can use the 'inherit' flag if needed +default: + # add environment variables + env: + TMPDIR: /tmp + password-file: key + # you can use a relative path, it will be relative to the configuration file + repository: /backup + # will run these scripts before and after each command (including 'backup') + run-before: mount /backup + run-after: umount /backup + # if a restic command fails, the run-after won't be running + # add this parameter to run the script in case of a failure + run-after-fail: umount /backup + +# New profile named 'root' +root: + inherit: default + initialize: true + # LOCAL lockfile so you cannot run the same profile more than once at a time + # (it's totally independent of the restic locks on the repository) + lock: /tmp/resticprofile-root.lock + + backup: + exclude-caches: true + # files with no path are relative to the configuration file + exclude-file: + - root-excludes + - excludes + one-file-system: false + source: + - / + tag: + - test + - dev + # ignore restic warnings when files cannot be read + no-error-on-warning: true + # run every day at midnight + schedule: daily + schedule-permission: system + schedule-lock-wait: 2h + + # retention policy for profile root + # retention is a special section that run the "forget" command + # before or after a backup + retention: + before-backup: false + after-backup: true + keep-daily: 1 + keep-hourly: 1 + keep-weekly: 1 + keep-monthly: 1 + keep-within: 3h + keep-tag: + - forever + prune: false + # tag can be a boolean ('true' meaning to copy tag set from 'backup') + # or a custom set of tags. + # Default is 'false', meaning that tags are NOT used. + tag: true + # host can be a boolean ('true' meaning current hostname) + # or a string to specify a different hostname + host: true + +# New profile named 'src' +src: + lock: "/tmp/resticprofile-profile-src.lock" + force-inactive-lock: false + inherit: default + initialize: true + + # 'backup' command of profile 'src' + backup: + check-before: true + exclude: + - /**/.git + exclude-caches: true + one-file-system: false + # will only run these scripts before and after a backup + run-before: + - echo Starting! + - ls -al ~/go + run-after: echo All Done! + source: + - ~/go + tag: + - test + - dev + # run every 30 minutes + schedule: "*:0,30" + schedule-permission: user + schedule-lock-wait: 10m + + # retention policy for profile src + retention: + before-backup: false + after-backup: true + keep-within: 30d + prune: true + + # check command of profile src + check: + read-data: true + # check the repository the first day of each month at 3am + schedule: "*-*-01 03:00" + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +global { + priority = "low" + ionice = true + ionice-class = 2 + ionice-level = 6 + # don't start if the memory available is < 1000MB + min-memory = 1000 +} + +groups { + all = ["src", "self"] +} + +default { + repository = "/tmp/backup" + password-file = "key" + run-before = "echo Profile started!" + run-after = "echo Profile finished!" + run-after-fail = "echo An error occurred!" +} + + +src { + inherit = "default" + initialize = true + lock = "/tmp/backup/resticprofile-profile-src.lock" + force-inactive-lock = false + + snapshots = { + tag = [ "test", "dev" ] + } + + backup = { + run-before = [ "echo Starting!", "ls -al ~/go/src" ] + run-after = "echo All Done!" + exclude = [ "/**/.git" ] + exclude-caches = true + tag = [ "test", "dev" ] + source = [ "~/go/src" ] + check-before = true + } + + retention = { + before-backup = false + after-backup = true + keep-last = 3 + compact = false + prune = true + } + + check = { + check-unused = true + with-cache = false + } +} + +self { + inherit = "default" + initialize = false + + snapshots = { + tag = [ "self" ] + } + + backup = { + source = "./" + tag = [ "self" ] + } +} + +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/configuration/examples/stdin.md b/docs/content/configuration/examples/stdin.md new file mode 100644 index 00000000..0ed295ec --- /dev/null +++ b/docs/content/configuration/examples/stdin.md @@ -0,0 +1,85 @@ +--- +title: "Use stdin in configuration" +--- + +Simple example sending a file via stdin + +{{< tabs groupid="config-with-hcl" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[stdin] + repository = "local:/backup/restic" + password-file = "key" + + [stdin.backup] + stdin = true + stdin-filename = "stdin-test" + tag = [ 'stdin' ] + +[mysql] + inherit = "stdin" + + [mysql.backup] + stdin-command = [ 'mysqldump --all-databases --order-by-primary' ] + stdin-filename = "dump.sql" + tag = [ 'mysql' ] + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +stdin: + repository: "local:/backup/restic" + password-file: key + backup: + stdin: true + stdin-filename: stdin-test + tag: + - stdin + +mysql: + inherit: stdin + backup: + stdin-command: "mysqldump --all-databases --order-by-primary" + stdin-filename: "dump.sql" + tag: + - mysql + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +# sending stream through stdin +stdin { + repository = "local:/backup/restic" + password-file = "key" + + backup = { + stdin = true + stdin-filename = "stdin-test" + tag = [ "stdin" ] + } +} + +mysql { + inherit = "stdin" + + backup = { + stdin-command = [ "mysqldump --all-databases --order-by-primary" ] + stdin-filename = "dump.sql" + tag = [ "mysql" ] + } +} +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/configuration/prometheus.md b/docs/content/configuration/prometheus.md new file mode 100644 index 00000000..74c8161c --- /dev/null +++ b/docs/content/configuration/prometheus.md @@ -0,0 +1,232 @@ +--- +title: "Monitoring - Prometheus" +slug: prometheus +weight: 10 +tags: [ "monitoring" ] +--- + +Resticprofile can generate a Prometheus file or send the report to a Pushgateway. Currently, only the `backup` command generates a report. Below is a configuration example for generating a file and sending it to a Pushgateway: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[root] + prometheus-save-to-file = "root.prom" + prometheus-push = "http://localhost:9091/" + + [root.backup] + extended-status = true + no-error-on-warning = true + source = [ "/" ] +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +root: + prometheus-save-to-file: "root.prom" + prometheus-push: "http://localhost:9091/" + backup: + extended-status: true + no-error-on-warning: true + source: + - / +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"root" = { + "prometheus-save-to-file" = "root.prom" + "prometheus-push" = "http://localhost:9091/" + + "backup" = { + "extended-status" = true + "no-error-on-warning" = true + "source" = ["/"] + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "root": { + "prometheus-save-to-file": "root.prom", + "prometheus-push": "http://localhost:9091/", + "backup": { + "extended-status": true, + "no-error-on-warning": true, + "source": [ + "/" + ] + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + +{{% notice style="note" %}} +Set `extended-status` to `true` to access all available metrics. For details, see [Extended status]({{% relref "/monitoring/status/index.html#-extended-status" %}}). +{{% /notice %}} + +Here's an example of a generated prometheus file: + +``` +# HELP restic_build_info restic build information. +# TYPE restic_build_info gauge +restic_build_info{profile="prom",version="0.18.0"} 1 +# HELP resticprofile_backup_added_bytes Total number of bytes added to the repository. +# TYPE resticprofile_backup_added_bytes gauge +resticprofile_backup_added_bytes{profile="prom"} 96167 +# HELP resticprofile_backup_dir_changed Number of directories with changes. +# TYPE resticprofile_backup_dir_changed gauge +resticprofile_backup_dir_changed{profile="prom"} 8 +# HELP resticprofile_backup_dir_new Number of new directories added to the backup. +# TYPE resticprofile_backup_dir_new gauge +resticprofile_backup_dir_new{profile="prom"} 0 +# HELP resticprofile_backup_dir_unmodified Number of directories unmodified since last backup. +# TYPE resticprofile_backup_dir_unmodified gauge +resticprofile_backup_dir_unmodified{profile="prom"} 1060 +# HELP resticprofile_backup_duration_seconds The backup duration (in seconds). +# TYPE resticprofile_backup_duration_seconds gauge +resticprofile_backup_duration_seconds{profile="prom"} 0.986296416 +# HELP resticprofile_backup_files_changed Number of files with changes. +# TYPE resticprofile_backup_files_changed gauge +resticprofile_backup_files_changed{profile="prom"} 2 +# HELP resticprofile_backup_files_new Number of new files added to the backup. +# TYPE resticprofile_backup_files_new gauge +resticprofile_backup_files_new{profile="prom"} 0 +# HELP resticprofile_backup_files_processed Total number of files scanned by the backup for changes. +# TYPE resticprofile_backup_files_processed gauge +resticprofile_backup_files_processed{profile="prom"} 7723 +# HELP resticprofile_backup_files_unmodified Number of files unmodified since last backup. +# TYPE resticprofile_backup_files_unmodified gauge +resticprofile_backup_files_unmodified{profile="prom"} 7721 +# HELP resticprofile_backup_processed_bytes Total number of bytes scanned for changes. +# TYPE resticprofile_backup_processed_bytes gauge +resticprofile_backup_processed_bytes{profile="prom"} 2.935621558e+09 +# HELP resticprofile_backup_status Backup status: 0=fail, 1=warning, 2=success. +# TYPE resticprofile_backup_status gauge +resticprofile_backup_status{profile="prom"} 2 +# HELP resticprofile_backup_time_seconds Last backup run (unixtime). +# TYPE resticprofile_backup_time_seconds gauge +resticprofile_backup_time_seconds{profile="prom"} 1.747673785e+09 +# HELP resticprofile_build_info resticprofile build information. +# TYPE resticprofile_build_info gauge +resticprofile_build_info{goversion="go1.24.3",profile="prom",version="0.31.0"} 1 + + +``` + +## Prometheus Pushgateway + +Prometheus Pushgateway uses the job label as a grouping key. Metrics with the same grouping key are replaced when pushed. To prevent overwriting metrics from different profiles, the default job label is set to `.` (e.g., `root.backup`). + +For more control over the job label, use the `prometheus-push-job` property. This property supports the `$command` placeholder, which is replaced with the executed command's name. + +You can specify the request format using `prometheus-push-format`. The default is `text`, but it can also be set to `protobuf` (see [compatibility with Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/)). + +## User-Defined Labels + +You can add custom Prometheus labels, which will apply to **all** metrics. Example: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[root] + prometheus-save-to-file = "root.prom" + prometheus-push = "http://localhost:9091/" + + [[root.prometheus-labels]] + host = "{{ .Hostname }}" + + [root.backup] + extended-status = true + no-error-on-warning = true + source = [ "/" ] +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +root: + prometheus-save-to-file: "root.prom" + prometheus-push: "http://localhost:9091/" + prometheus-labels: + - host: {{ .Hostname }} + backup: + extended-status: true + no-error-on-warning: true + source: + - / +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"root" = { + "prometheus-save-to-file" = "root.prom" + "prometheus-push" = "http://localhost:9091/" + + "prometheus-labels" = { + "host" = "{{ .Hostname }}" + } + + "backup" = { + "extended-status" = true + "no-error-on-warning" = true + "source" = ["/"] + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "root": { + "prometheus-save-to-file": "root.prom", + "prometheus-push": "http://localhost:9091/", + "prometheus-labels": [ + { + "host": "{{ .Hostname }}" + } + ], + "backup": { + "extended-status": true, + "no-error-on-warning": true, + "source": [ + "/" + ] + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + + +This adds the `host` label to all your metrics. diff --git a/docs/content/configuration/status.md b/docs/content/configuration/status.md new file mode 100644 index 00000000..cd56b4df --- /dev/null +++ b/docs/content/configuration/status.md @@ -0,0 +1,176 @@ +--- +title: "Monitoring - Status file" +slug: status +weight: 11 +tags: [ "monitoring" ] +aliases: + - /status +--- + +If you need to send your backup results to a monitoring system, use the `run-after` and `run-after-fail` scripts. + +For simpler needs, resticprofile can generate a JSON file with details of the latest backup, forget, or check command. For example, I use a Zabbix agent to [check this file](https://github.com/creativeprojects/resticprofile/tree/master/contrib/zabbix) daily. Any monitoring system that reads JSON files can be integrated. + +To enable this, add the status file location as a parameter in your profile. + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[profile] + status-file = "backup-status.json" +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +profile: + status-file: backup-status.json +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"profile" { + "status-file" = "backup-status.json" +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "profile": { + "status-file": "backup-status.json" + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + + +Here is an example of a generated file showing the last `check` failed, while the last `backup` succeeded: + +```json +{ + "profiles": { + "self": { + "backup": { + "success": true, + "time": "2021-03-24T16:36:56.831077Z", + "error": "", + "stderr": "", + "duration": 16, + "files_new": 215, + "files_changed": 0, + "files_unmodified": 0, + "dirs_new": 58, + "dirs_changed": 0, + "dirs_unmodified": 0, + "files_total": 215, + "bytes_added": 296536447, + "bytes_total": 362952485 + }, + "check": { + "success": false, + "time": "2021-03-24T15:23:40.270689Z", + "error": "exit status 1", + "stderr": "unable to create lock in backend: repository is already locked exclusively by PID 18534 on dingo by cloud_user (UID 501, GID 20)\nlock was created at 2021-03-24 15:23:29 (10.42277s ago)\nstorage ID 1bf636d2\nthe `unlock` command can be used to remove stale locks\n", + "duration": 1 + } + } + } +} +``` + +## ⚠️ Extended status + +In the backup section above, you can see fields like `files_new` and `files_total`. This information is available only when resticprofile's output is redirected or when the `extended-status` flag is added to your backup configuration. + +This limitation ensures restic displays terminal output correctly. + +The following fields do **not** require `extended-status` or stdout redirection: +- success +- time +- error +- stderr +- duration + +The `extended-status` flag is **disabled by default because it suppresses restic's output**. + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[profile] + status-file = "/home/backup/status.json" + + [profile.backup] + extended-status = true + source = "/go" + exclude = [ "/**/.git/" ] +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +profile: + status-file: /home/backup/status.json + backup: + extended-status: true + source: /go + exclude: + - "/**/.git/" + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"profile" = { + "status-file" = "/home/backup/status.json" + + "backup" = { + "extended-status" = true + "source" = "/go" + "exclude" = ["/**/.git/"] + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "profile": { + "status-file": "/home/backup/status.json", + "backup": { + "extended-status": true, + "source": "/go", + "exclude": [ + "/**/.git/" + ] + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} From ab64197514a827d2e560ff051eb0ff781ff61d6f Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:18:46 -0500 Subject: [PATCH 08/29] removed the monitoring folder --- docs/content/monitoring/_index.md | 8 - docs/content/monitoring/prometheus.md | 232 -------------------------- docs/content/monitoring/status.md | 176 ------------------- 3 files changed, 416 deletions(-) delete mode 100644 docs/content/monitoring/_index.md delete mode 100644 docs/content/monitoring/prometheus.md delete mode 100644 docs/content/monitoring/status.md diff --git a/docs/content/monitoring/_index.md b/docs/content/monitoring/_index.md deleted file mode 100644 index 667a68c6..00000000 --- a/docs/content/monitoring/_index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -archetype: "chapter" -pre: "5. " -title: "Monitoring" -weight: 5 ---- - -{{% children %}} diff --git a/docs/content/monitoring/prometheus.md b/docs/content/monitoring/prometheus.md deleted file mode 100644 index bde4cf03..00000000 --- a/docs/content/monitoring/prometheus.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "Prometheus" -slug: prometheus -weight: 10 -tags: [ "monitoring" ] ---- - -Resticprofile can generate a Prometheus file or send the report to a Pushgateway. Currently, only the `backup` command generates a report. Below is a configuration example for generating a file and sending it to a Pushgateway: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[root] - prometheus-save-to-file = "root.prom" - prometheus-push = "http://localhost:9091/" - - [root.backup] - extended-status = true - no-error-on-warning = true - source = [ "/" ] -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -root: - prometheus-save-to-file: "root.prom" - prometheus-push: "http://localhost:9091/" - backup: - extended-status: true - no-error-on-warning: true - source: - - / -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"root" = { - "prometheus-save-to-file" = "root.prom" - "prometheus-push" = "http://localhost:9091/" - - "backup" = { - "extended-status" = true - "no-error-on-warning" = true - "source" = ["/"] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "root": { - "prometheus-save-to-file": "root.prom", - "prometheus-push": "http://localhost:9091/", - "backup": { - "extended-status": true, - "no-error-on-warning": true, - "source": [ - "/" - ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -{{% notice style="note" %}} -Set `extended-status` to `true` to access all available metrics. For details, see [Extended status]({{% relref "/monitoring/status/index.html#-extended-status" %}}). -{{% /notice %}} - -Here's an example of a generated prometheus file: - -``` -# HELP restic_build_info restic build information. -# TYPE restic_build_info gauge -restic_build_info{profile="prom",version="0.18.0"} 1 -# HELP resticprofile_backup_added_bytes Total number of bytes added to the repository. -# TYPE resticprofile_backup_added_bytes gauge -resticprofile_backup_added_bytes{profile="prom"} 96167 -# HELP resticprofile_backup_dir_changed Number of directories with changes. -# TYPE resticprofile_backup_dir_changed gauge -resticprofile_backup_dir_changed{profile="prom"} 8 -# HELP resticprofile_backup_dir_new Number of new directories added to the backup. -# TYPE resticprofile_backup_dir_new gauge -resticprofile_backup_dir_new{profile="prom"} 0 -# HELP resticprofile_backup_dir_unmodified Number of directories unmodified since last backup. -# TYPE resticprofile_backup_dir_unmodified gauge -resticprofile_backup_dir_unmodified{profile="prom"} 1060 -# HELP resticprofile_backup_duration_seconds The backup duration (in seconds). -# TYPE resticprofile_backup_duration_seconds gauge -resticprofile_backup_duration_seconds{profile="prom"} 0.986296416 -# HELP resticprofile_backup_files_changed Number of files with changes. -# TYPE resticprofile_backup_files_changed gauge -resticprofile_backup_files_changed{profile="prom"} 2 -# HELP resticprofile_backup_files_new Number of new files added to the backup. -# TYPE resticprofile_backup_files_new gauge -resticprofile_backup_files_new{profile="prom"} 0 -# HELP resticprofile_backup_files_processed Total number of files scanned by the backup for changes. -# TYPE resticprofile_backup_files_processed gauge -resticprofile_backup_files_processed{profile="prom"} 7723 -# HELP resticprofile_backup_files_unmodified Number of files unmodified since last backup. -# TYPE resticprofile_backup_files_unmodified gauge -resticprofile_backup_files_unmodified{profile="prom"} 7721 -# HELP resticprofile_backup_processed_bytes Total number of bytes scanned for changes. -# TYPE resticprofile_backup_processed_bytes gauge -resticprofile_backup_processed_bytes{profile="prom"} 2.935621558e+09 -# HELP resticprofile_backup_status Backup status: 0=fail, 1=warning, 2=success. -# TYPE resticprofile_backup_status gauge -resticprofile_backup_status{profile="prom"} 2 -# HELP resticprofile_backup_time_seconds Last backup run (unixtime). -# TYPE resticprofile_backup_time_seconds gauge -resticprofile_backup_time_seconds{profile="prom"} 1.747673785e+09 -# HELP resticprofile_build_info resticprofile build information. -# TYPE resticprofile_build_info gauge -resticprofile_build_info{goversion="go1.24.3",profile="prom",version="0.31.0"} 1 - - -``` - -## Prometheus Pushgateway - -Prometheus Pushgateway uses the job label as a grouping key. Metrics with the same grouping key are replaced when pushed. To prevent overwriting metrics from different profiles, the default job label is set to `.` (e.g., `root.backup`). - -For more control over the job label, use the `prometheus-push-job` property. This property supports the `$command` placeholder, which is replaced with the executed command's name. - -You can specify the request format using `prometheus-push-format`. The default is `text`, but it can also be set to `protobuf` (see [compatibility with Prometheus](https://prometheus.io/docs/instrumenting/exposition_formats/)). - -## User-Defined Labels - -You can add custom Prometheus labels, which will apply to **all** metrics. Example: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[root] - prometheus-save-to-file = "root.prom" - prometheus-push = "http://localhost:9091/" - - [[root.prometheus-labels]] - host = "{{ .Hostname }}" - - [root.backup] - extended-status = true - no-error-on-warning = true - source = [ "/" ] -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -root: - prometheus-save-to-file: "root.prom" - prometheus-push: "http://localhost:9091/" - prometheus-labels: - - host: {{ .Hostname }} - backup: - extended-status: true - no-error-on-warning: true - source: - - / -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"root" = { - "prometheus-save-to-file" = "root.prom" - "prometheus-push" = "http://localhost:9091/" - - "prometheus-labels" = { - "host" = "{{ .Hostname }}" - } - - "backup" = { - "extended-status" = true - "no-error-on-warning" = true - "source" = ["/"] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "root": { - "prometheus-save-to-file": "root.prom", - "prometheus-push": "http://localhost:9091/", - "prometheus-labels": [ - { - "host": "{{ .Hostname }}" - } - ], - "backup": { - "extended-status": true, - "no-error-on-warning": true, - "source": [ - "/" - ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -This adds the `host` label to all your metrics. \ No newline at end of file diff --git a/docs/content/monitoring/status.md b/docs/content/monitoring/status.md deleted file mode 100644 index de54d714..00000000 --- a/docs/content/monitoring/status.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -title: "Status file" -slug: status -weight: 5 -tags: [ "monitoring" ] -aliases: - - /status ---- - -If you need to send your backup results to a monitoring system, use the `run-after` and `run-after-fail` scripts. - -For simpler needs, resticprofile can generate a JSON file with details of the latest backup, forget, or check command. For example, I use a Zabbix agent to [check this file](https://github.com/creativeprojects/resticprofile/tree/master/contrib/zabbix) daily. Any monitoring system that reads JSON files can be integrated. - -To enable this, add the status file location as a parameter in your profile. - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[profile] - status-file = "backup-status.json" -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -profile: - status-file: backup-status.json -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"profile" { - "status-file" = "backup-status.json" -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "profile": { - "status-file": "backup-status.json" - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -Here is an example of a generated file showing the last `check` failed, while the last `backup` succeeded: - -```json -{ - "profiles": { - "self": { - "backup": { - "success": true, - "time": "2021-03-24T16:36:56.831077Z", - "error": "", - "stderr": "", - "duration": 16, - "files_new": 215, - "files_changed": 0, - "files_unmodified": 0, - "dirs_new": 58, - "dirs_changed": 0, - "dirs_unmodified": 0, - "files_total": 215, - "bytes_added": 296536447, - "bytes_total": 362952485 - }, - "check": { - "success": false, - "time": "2021-03-24T15:23:40.270689Z", - "error": "exit status 1", - "stderr": "unable to create lock in backend: repository is already locked exclusively by PID 18534 on dingo by cloud_user (UID 501, GID 20)\nlock was created at 2021-03-24 15:23:29 (10.42277s ago)\nstorage ID 1bf636d2\nthe `unlock` command can be used to remove stale locks\n", - "duration": 1 - } - } - } -} -``` - -## ⚠️ Extended status - -In the backup section above, you can see fields like `files_new` and `files_total`. This information is available only when resticprofile's output is redirected or when the `extended-status` flag is added to your backup configuration. - -This limitation ensures restic displays terminal output correctly. - -The following fields do **not** require `extended-status` or stdout redirection: -- success -- time -- error -- stderr -- duration - -The `extended-status` flag is **disabled by default because it suppresses restic's output**. - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[profile] - status-file = "/home/backup/status.json" - - [profile.backup] - extended-status = true - source = "/go" - exclude = [ "/**/.git/" ] -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -profile: - status-file: /home/backup/status.json - backup: - extended-status: true - source: /go - exclude: - - "/**/.git/" - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"profile" = { - "status-file" = "/home/backup/status.json" - - "backup" = { - "extended-status" = true - "source" = "/go" - "exclude" = ["/**/.git/"] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "profile": { - "status-file": "/home/backup/status.json", - "backup": { - "extended-status": true, - "source": "/go", - "exclude": [ - "/**/.git/" - ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} From 84baf0e7f81ff278b7389df7c749060b9a04f8ab Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:25:33 -0500 Subject: [PATCH 09/29] Reorganized files within the configuration folder --- .../{examples.md => examples/_index.md} | 0 .../content/configuration/{ => hooks}/copy.md | 0 .../configuration/{ => hooks}/http_hooks.md | 0 .../configuration/{ => hooks}/run_hooks.md | 0 .../content/configuration/jsonschema/index.md | 85 -------------- .../configuration/{ => logging}/logs.md | 0 .../configuration/{ => logging}/prometheus.md | 0 .../configuration/{ => logging}/status.md | 0 .../configuration/{ => logging}/warnings.md | 0 .../configuration/{ => profiles}/include.md | 0 .../{ => profiles}/inheritance.md | 0 .../configuration/{ => profiles}/path.md | 0 .../configuration/{ => profiles}/templates.md | 0 .../configuration/{ => profiles}/variables.md | 0 .../{ => scheduling}/priority.md | 0 .../configuration/{ => scheduling}/sleep.md | 0 docs/content/configuration/v2.md | 109 ------------------ .../jsonschema/jsonschema-vsc.gif | Bin 18 files changed, 194 deletions(-) rename docs/content/configuration/{examples.md => examples/_index.md} (100%) rename docs/content/configuration/{ => hooks}/copy.md (100%) rename docs/content/configuration/{ => hooks}/http_hooks.md (100%) rename docs/content/configuration/{ => hooks}/run_hooks.md (100%) delete mode 100644 docs/content/configuration/jsonschema/index.md rename docs/content/configuration/{ => logging}/logs.md (100%) rename docs/content/configuration/{ => logging}/prometheus.md (100%) rename docs/content/configuration/{ => logging}/status.md (100%) rename docs/content/configuration/{ => logging}/warnings.md (100%) rename docs/content/configuration/{ => profiles}/include.md (100%) rename docs/content/configuration/{ => profiles}/inheritance.md (100%) rename docs/content/configuration/{ => profiles}/path.md (100%) rename docs/content/configuration/{ => profiles}/templates.md (100%) rename docs/content/configuration/{ => profiles}/variables.md (100%) rename docs/content/configuration/{ => scheduling}/priority.md (100%) rename docs/content/configuration/{ => scheduling}/sleep.md (100%) delete mode 100644 docs/content/configuration/v2.md rename docs/content/{configuration => reference}/jsonschema/jsonschema-vsc.gif (100%) diff --git a/docs/content/configuration/examples.md b/docs/content/configuration/examples/_index.md similarity index 100% rename from docs/content/configuration/examples.md rename to docs/content/configuration/examples/_index.md diff --git a/docs/content/configuration/copy.md b/docs/content/configuration/hooks/copy.md similarity index 100% rename from docs/content/configuration/copy.md rename to docs/content/configuration/hooks/copy.md diff --git a/docs/content/configuration/http_hooks.md b/docs/content/configuration/hooks/http_hooks.md similarity index 100% rename from docs/content/configuration/http_hooks.md rename to docs/content/configuration/hooks/http_hooks.md diff --git a/docs/content/configuration/run_hooks.md b/docs/content/configuration/hooks/run_hooks.md similarity index 100% rename from docs/content/configuration/run_hooks.md rename to docs/content/configuration/hooks/run_hooks.md diff --git a/docs/content/configuration/jsonschema/index.md b/docs/content/configuration/jsonschema/index.md deleted file mode 100644 index 94bf722e..00000000 --- a/docs/content/configuration/jsonschema/index.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "JSON schema" -weight: 55 ---- - -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 - -**{{< absolute "jsonschema/config.json" >}}** - -This schema detects config and restic version and redirects to the corresponding [versioned URL](#versioned-urls). -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: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} -``````toml -#:schema {{< absolute "jsonschema/config-2.json" nohtml >}} - -version = "2" - -`````` -{{% /tab %}} -{{% tab title="yaml" %}} -``````yaml -# yaml-language-server: $schema={{< absolute "jsonschema/config.json" nohtml >}} - -version: "2" - -`````` -{{% /tab %}} -{{% tab title="json" %}} -``````json -{ - "$schema": "{{< absolute "jsonschema/config.json" nohtml >}}", - "version": "2" -} -`````` -{{% /tab %}} -{{< /tabs >}} - -{{% notice style="info" %}} -YAML & TOML validation with JSON schema is not supported out of the box. Additional extensions are required, such as 'redhat.vscode-yaml' for YAML and 'tamasfe.even-better-toml' for TOML in Visual Studio Code. -{{% /notice %}} - -**Example** - -{{< figure src="/configuration/jsonschema/jsonschema-vsc.gif" >}} - -**Extension**: `redhat.vscode-yaml` - - -## Versioned URLs - -The following versioned schemas are referenced from `config.json`. Which URL is selected depends -on config and restic version. You may use the URLs directly if you need a self-contained schema -file or to enforce a certain version of configuration format and/or restic flags - -JSON schema URLs for **any** *restic* version: - -* Config V1: {{< absolute "jsonschema/config-1.json" >}} -* Config V2: {{< absolute "jsonschema/config-2.json" >}} - -These universal schemas contain all flags and commands of all known *restic* versions and -may allow to set flags that are not supported by a particular *restic* version. Descriptions -and deprecation markers indicate what is supported and what should no longer be used. - -JSON schema URLs for a **specific** *restic* version (list of [available URLs]({{% relref "reference/json-schema" %}})): - -* `.../config-1-restic-{MAJOR}-{MINOR}.json` -* `.../config-2-restic-{MAJOR}-{MINOR}.json` - -These schemas contain only flags and commands of a specific *restic* version. The schema will -validate a config only when flags are used that the selected *restic* version supports -according to its manual pages. - -{{% notice style="tip" %}} -As an alternative to URLs, schemas can be generated locally with: -`resticprofile generate --json-schema [--version RESTIC_VERSION] [global|v1|v2]` -{{% /notice %}} diff --git a/docs/content/configuration/logs.md b/docs/content/configuration/logging/logs.md similarity index 100% rename from docs/content/configuration/logs.md rename to docs/content/configuration/logging/logs.md diff --git a/docs/content/configuration/prometheus.md b/docs/content/configuration/logging/prometheus.md similarity index 100% rename from docs/content/configuration/prometheus.md rename to docs/content/configuration/logging/prometheus.md diff --git a/docs/content/configuration/status.md b/docs/content/configuration/logging/status.md similarity index 100% rename from docs/content/configuration/status.md rename to docs/content/configuration/logging/status.md diff --git a/docs/content/configuration/warnings.md b/docs/content/configuration/logging/warnings.md similarity index 100% rename from docs/content/configuration/warnings.md rename to docs/content/configuration/logging/warnings.md diff --git a/docs/content/configuration/include.md b/docs/content/configuration/profiles/include.md similarity index 100% rename from docs/content/configuration/include.md rename to docs/content/configuration/profiles/include.md diff --git a/docs/content/configuration/inheritance.md b/docs/content/configuration/profiles/inheritance.md similarity index 100% rename from docs/content/configuration/inheritance.md rename to docs/content/configuration/profiles/inheritance.md diff --git a/docs/content/configuration/path.md b/docs/content/configuration/profiles/path.md similarity index 100% rename from docs/content/configuration/path.md rename to docs/content/configuration/profiles/path.md diff --git a/docs/content/configuration/templates.md b/docs/content/configuration/profiles/templates.md similarity index 100% rename from docs/content/configuration/templates.md rename to docs/content/configuration/profiles/templates.md diff --git a/docs/content/configuration/variables.md b/docs/content/configuration/profiles/variables.md similarity index 100% rename from docs/content/configuration/variables.md rename to docs/content/configuration/profiles/variables.md diff --git a/docs/content/configuration/priority.md b/docs/content/configuration/scheduling/priority.md similarity index 100% rename from docs/content/configuration/priority.md rename to docs/content/configuration/scheduling/priority.md diff --git a/docs/content/configuration/sleep.md b/docs/content/configuration/scheduling/sleep.md similarity index 100% rename from docs/content/configuration/sleep.md rename to docs/content/configuration/scheduling/sleep.md diff --git a/docs/content/configuration/v2.md b/docs/content/configuration/v2.md deleted file mode 100644 index 933a9003..00000000 --- a/docs/content/configuration/v2.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "Configuration v2 proposal" -weight: 60 ---- - -{{% notice style="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. - -{{% /notice %}} - - -## 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: - -```toml -[profile] - -[profile.backup] -source = "some path" - -``` - -Since then, I believe the `yaml` format is preferred over `toml`. - -My proposal is to make a "version 2" of the configuration file, the current file format is "version 1". - -**Both formats will continue to be valid**: - -- if no version is specified, the "version 1" is used. This is the current format -- if a version is specified (`2`) the new format will be expected - -## New format availability - -The new format "version 2" will be available for: -- TOML -- YAML -- JSON - -**It won't be available for HCL**. This may not be definitive, but it's not widely used and it's becoming more and more difficult to support HCL. - -**HCL can still be used as is, "version = 1"** - -## New format specifications - -I will show the specification using the `yaml` as examples, because it's probably the most readable format. - -### version - -```yaml -version: 2 -``` - -### global - -The global section does not change. We'll keep all the global configuration in there. - -```yaml -global: - default-command: snapshots - initialize: false - priority: low - -``` - -### profiles - -All your profiles will be nested under a `profiles` section. Please note the schedules are no longer described inside the profile, but in a separate section `schedules` (see the following example). - -```yaml -version: "2" - -profiles: - default: - env: - tmp: /tmp - password-file: key - repository: /backup - - documents: - inherit: default - backup: - source: ~/Documents - snapshots: - tag: - - documents -``` - -### groups - -The list of profiles will be nested under a `profiles` section, so we can add more configuration to groups later. - -```yaml -version: "2" - -groups: - full: # name of your group - profiles: - - root - - documents - - mysql -``` - -This format leaves more space for improvements later (like a `repos` section maybe?) - -{{% notice style="tip" %}} -You can participate in designing the "version 2" [here](https://github.com/creativeprojects/resticprofile/issues/80) -{{% /notice %}} \ No newline at end of file diff --git a/docs/content/configuration/jsonschema/jsonschema-vsc.gif b/docs/content/reference/jsonschema/jsonschema-vsc.gif similarity index 100% rename from docs/content/configuration/jsonschema/jsonschema-vsc.gif rename to docs/content/reference/jsonschema/jsonschema-vsc.gif From 10e80cd80b8c5a396c558e8953e00f57a3b2ced9 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:27:26 -0500 Subject: [PATCH 10/29] Formatted hooks --- docs/content/configuration/hooks/_index.md | 5 +++++ docs/content/configuration/hooks/copy.md | 4 +--- docs/content/configuration/hooks/http_hooks.md | 3 +-- docs/content/configuration/hooks/run_hooks.md | 3 +-- 4 files changed, 8 insertions(+), 7 deletions(-) create mode 100644 docs/content/configuration/hooks/_index.md diff --git a/docs/content/configuration/hooks/_index.md b/docs/content/configuration/hooks/_index.md new file mode 100644 index 00000000..50268bf6 --- /dev/null +++ b/docs/content/configuration/hooks/_index.md @@ -0,0 +1,5 @@ +--- +title: Hooks +--- + +{{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/hooks/copy.md b/docs/content/configuration/hooks/copy.md index 03903f6e..0b328ec9 100644 --- a/docs/content/configuration/hooks/copy.md +++ b/docs/content/configuration/hooks/copy.md @@ -3,8 +3,6 @@ title: "Copy command" weight: 17 --- - - ## 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: @@ -190,4 +188,4 @@ profile { ``` {{% /tab %}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} diff --git a/docs/content/configuration/hooks/http_hooks.md b/docs/content/configuration/hooks/http_hooks.md index acd1c464..9f497d92 100644 --- a/docs/content/configuration/hooks/http_hooks.md +++ b/docs/content/configuration/hooks/http_hooks.md @@ -1,10 +1,9 @@ --- -title: "HTTP Hooks" +title: "Hooks - HTTP" weight: 22 tags: [ "monitoring", "healthchecks.io" ] --- - ## Send HTTP messages before and after a job As well as being able to run [shell commands]({{% relref "run_hooks" %}}), you can now send HTTP messages before, after (success or failure) running a restic command. diff --git a/docs/content/configuration/hooks/run_hooks.md b/docs/content/configuration/hooks/run_hooks.md index 67c5de3b..f17f1c18 100644 --- a/docs/content/configuration/hooks/run_hooks.md +++ b/docs/content/configuration/hooks/run_hooks.md @@ -1,10 +1,9 @@ --- -title: "Command Hooks" +title: "Hooks - Commands" weight: 20 tags: [ "monitoring" ] --- - ## Run commands before, after success or after failure resticprofile has 2 places where you can run commands around restic: From ee28aebe943b011b5e6e9769f6b7170180703b4e Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:28:46 -0500 Subject: [PATCH 11/29] Formatted monitoring --- .../configuration/{logging/logs.md => monitoring/_index.md} | 0 docs/content/configuration/{logging => monitoring}/prometheus.md | 0 docs/content/configuration/{logging => monitoring}/status.md | 0 docs/content/configuration/{logging => monitoring}/warnings.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename docs/content/configuration/{logging/logs.md => monitoring/_index.md} (100%) rename docs/content/configuration/{logging => monitoring}/prometheus.md (100%) rename docs/content/configuration/{logging => monitoring}/status.md (100%) rename docs/content/configuration/{logging => monitoring}/warnings.md (100%) diff --git a/docs/content/configuration/logging/logs.md b/docs/content/configuration/monitoring/_index.md similarity index 100% rename from docs/content/configuration/logging/logs.md rename to docs/content/configuration/monitoring/_index.md diff --git a/docs/content/configuration/logging/prometheus.md b/docs/content/configuration/monitoring/prometheus.md similarity index 100% rename from docs/content/configuration/logging/prometheus.md rename to docs/content/configuration/monitoring/prometheus.md diff --git a/docs/content/configuration/logging/status.md b/docs/content/configuration/monitoring/status.md similarity index 100% rename from docs/content/configuration/logging/status.md rename to docs/content/configuration/monitoring/status.md diff --git a/docs/content/configuration/logging/warnings.md b/docs/content/configuration/monitoring/warnings.md similarity index 100% rename from docs/content/configuration/logging/warnings.md rename to docs/content/configuration/monitoring/warnings.md From 308dddab948b5ed22ea875e21977b7c06a464ec9 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:30:27 -0500 Subject: [PATCH 12/29] Moved preventing system sleep into schedules, and moved prority into profiles --- docs/content/configuration/{scheduling => profiles}/priority.md | 0 docs/content/{configuration/scheduling => schedules}/sleep.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/content/configuration/{scheduling => profiles}/priority.md (100%) rename docs/content/{configuration/scheduling => schedules}/sleep.md (100%) diff --git a/docs/content/configuration/scheduling/priority.md b/docs/content/configuration/profiles/priority.md similarity index 100% rename from docs/content/configuration/scheduling/priority.md rename to docs/content/configuration/profiles/priority.md diff --git a/docs/content/configuration/scheduling/sleep.md b/docs/content/schedules/sleep.md similarity index 100% rename from docs/content/configuration/scheduling/sleep.md rename to docs/content/schedules/sleep.md From 6a5231d487d812d897ab679f0e693d0f42f5f435 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sat, 15 Nov 2025 23:33:47 -0500 Subject: [PATCH 13/29] Moved schedules into the configuration file section --- .../content/{ => configuration}/schedules/_index.md | 1 - .../{ => configuration}/schedules/commands.md | 0 .../{ => configuration}/schedules/configuration.md | 0 .../{ => configuration}/schedules/examples.md | 0 .../schedules/removable_volume.png | Bin .../schedules/scheduling_methods/_index.md | 5 +++++ .../schedules/scheduling_methods}/cron.md | 0 .../schedules/scheduling_methods}/launchd.md | 0 .../non-root-schedule-in-container.md | 0 .../schedules/scheduling_methods}/systemd.md | 0 .../task_scheduler/administrator.png | Bin .../scheduling_methods}/task_scheduler/index.md | 0 .../scheduling_methods}/task_scheduler/runas.png | Bin .../task_scheduler/unwanted_my_ass.png | Bin docs/content/{ => configuration}/schedules/sleep.md | 0 15 files changed, 5 insertions(+), 1 deletion(-) rename docs/content/{ => configuration}/schedules/_index.md (99%) rename docs/content/{ => configuration}/schedules/commands.md (100%) rename docs/content/{ => configuration}/schedules/configuration.md (100%) rename docs/content/{ => configuration}/schedules/examples.md (100%) rename docs/content/{ => configuration}/schedules/removable_volume.png (100%) create mode 100644 docs/content/configuration/schedules/scheduling_methods/_index.md rename docs/content/{schedules => configuration/schedules/scheduling_methods}/cron.md (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/launchd.md (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/non-root-schedule-in-container.md (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/systemd.md (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/task_scheduler/administrator.png (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/task_scheduler/index.md (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/task_scheduler/runas.png (100%) rename docs/content/{schedules => configuration/schedules/scheduling_methods}/task_scheduler/unwanted_my_ass.png (100%) rename docs/content/{ => configuration}/schedules/sleep.md (100%) diff --git a/docs/content/schedules/_index.md b/docs/content/configuration/schedules/_index.md similarity index 99% rename from docs/content/schedules/_index.md rename to docs/content/configuration/schedules/_index.md index d445e1eb..ea26545f 100644 --- a/docs/content/schedules/_index.md +++ b/docs/content/configuration/schedules/_index.md @@ -1,6 +1,5 @@ +++ archetype = "chapter" -pre = "4. " title = "Schedules" weight = 4 +++ diff --git a/docs/content/schedules/commands.md b/docs/content/configuration/schedules/commands.md similarity index 100% rename from docs/content/schedules/commands.md rename to docs/content/configuration/schedules/commands.md diff --git a/docs/content/schedules/configuration.md b/docs/content/configuration/schedules/configuration.md similarity index 100% rename from docs/content/schedules/configuration.md rename to docs/content/configuration/schedules/configuration.md diff --git a/docs/content/schedules/examples.md b/docs/content/configuration/schedules/examples.md similarity index 100% rename from docs/content/schedules/examples.md rename to docs/content/configuration/schedules/examples.md diff --git a/docs/content/schedules/removable_volume.png b/docs/content/configuration/schedules/removable_volume.png similarity index 100% rename from docs/content/schedules/removable_volume.png rename to docs/content/configuration/schedules/removable_volume.png diff --git a/docs/content/configuration/schedules/scheduling_methods/_index.md b/docs/content/configuration/schedules/scheduling_methods/_index.md new file mode 100644 index 00000000..8d7e88dd --- /dev/null +++ b/docs/content/configuration/schedules/scheduling_methods/_index.md @@ -0,0 +1,5 @@ +--- +title: "Scheduling Methods" +--- + +{{% children sort="weight" depth="2" %}} diff --git a/docs/content/schedules/cron.md b/docs/content/configuration/schedules/scheduling_methods/cron.md similarity index 100% rename from docs/content/schedules/cron.md rename to docs/content/configuration/schedules/scheduling_methods/cron.md diff --git a/docs/content/schedules/launchd.md b/docs/content/configuration/schedules/scheduling_methods/launchd.md similarity index 100% rename from docs/content/schedules/launchd.md rename to docs/content/configuration/schedules/scheduling_methods/launchd.md diff --git a/docs/content/schedules/non-root-schedule-in-container.md b/docs/content/configuration/schedules/scheduling_methods/non-root-schedule-in-container.md similarity index 100% rename from docs/content/schedules/non-root-schedule-in-container.md rename to docs/content/configuration/schedules/scheduling_methods/non-root-schedule-in-container.md diff --git a/docs/content/schedules/systemd.md b/docs/content/configuration/schedules/scheduling_methods/systemd.md similarity index 100% rename from docs/content/schedules/systemd.md rename to docs/content/configuration/schedules/scheduling_methods/systemd.md diff --git a/docs/content/schedules/task_scheduler/administrator.png b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/administrator.png similarity index 100% rename from docs/content/schedules/task_scheduler/administrator.png rename to docs/content/configuration/schedules/scheduling_methods/task_scheduler/administrator.png diff --git a/docs/content/schedules/task_scheduler/index.md b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md similarity index 100% rename from docs/content/schedules/task_scheduler/index.md rename to docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md diff --git a/docs/content/schedules/task_scheduler/runas.png b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/runas.png similarity index 100% rename from docs/content/schedules/task_scheduler/runas.png rename to docs/content/configuration/schedules/scheduling_methods/task_scheduler/runas.png diff --git a/docs/content/schedules/task_scheduler/unwanted_my_ass.png b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/unwanted_my_ass.png similarity index 100% rename from docs/content/schedules/task_scheduler/unwanted_my_ass.png rename to docs/content/configuration/schedules/scheduling_methods/task_scheduler/unwanted_my_ass.png diff --git a/docs/content/schedules/sleep.md b/docs/content/configuration/schedules/sleep.md similarity index 100% rename from docs/content/schedules/sleep.md rename to docs/content/configuration/schedules/sleep.md From 4bb8b8a95a4f2b29fe3daf5b8dfe22aaf86e6c59 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sun, 16 Nov 2025 13:18:34 -0500 Subject: [PATCH 14/29] Updating Makefile to include fixed commands for submodule --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index f12b3d48..8080ca9c 100644 --- a/Makefile +++ b/Makefile @@ -291,6 +291,7 @@ generate-config-reference: build ## Generate the configuration reference documen .PHONY: documentation documentation: generate-jsonschema generate-config-reference $(GOBIN)/hugo ## Generate the documentation site @echo "[*] $@" + git submodule init && git submodule update --depth=1 cd docs && hugo --minify .PHONY: syslog-ng From 04ed3a5fce5d62a1f203c1ce6fffede36e020621 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sun, 16 Nov 2025 13:22:21 -0500 Subject: [PATCH 15/29] Renaming file back to keyfile.md --- docs/content/usage/examples/{GenRandomKeys.md => keyfile.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/content/usage/examples/{GenRandomKeys.md => keyfile.md} (100%) diff --git a/docs/content/usage/examples/GenRandomKeys.md b/docs/content/usage/examples/keyfile.md similarity index 100% rename from docs/content/usage/examples/GenRandomKeys.md rename to docs/content/usage/examples/keyfile.md From 6b2a887b69b3dc7051c98d25e12e49a4aa94ade8 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sun, 16 Nov 2025 15:08:51 -0500 Subject: [PATCH 16/29] Fixing all errors related to relative links --- .../getting_started/{index.md => _index.md} | 6 ++--- .../configuration/monitoring/_index.md | 2 +- .../configuration/monitoring/prometheus.md | 2 +- .../content/configuration/profiles/include.md | 6 ++--- .../configuration/profiles/inheritance.md | 14 +++++------ .../configuration/profiles/variables.md | 6 ++--- .../content/configuration/schedules/_index.md | 10 ++++---- .../configuration/schedules/commands.md | 2 +- .../schedules/scheduling_methods/systemd.md | 2 +- docs/content/features/_index.md | 24 +++++++++---------- docs/themes/hugo-theme-relearn | 2 +- 11 files changed, 38 insertions(+), 38 deletions(-) rename docs/content/configuration/getting_started/{index.md => _index.md} (96%) diff --git a/docs/content/configuration/getting_started/index.md b/docs/content/configuration/getting_started/_index.md similarity index 96% rename from docs/content/configuration/getting_started/index.md rename to docs/content/configuration/getting_started/_index.md index ba72b485..41d85bd2 100644 --- a/docs/content/configuration/getting_started/index.md +++ b/docs/content/configuration/getting_started/_index.md @@ -29,7 +29,7 @@ HCL can be useful if you already use a tool from the Hashicorp stack; otherwise, We'll show you how to get documentation and auto-completion for the **resticprofile** configuration using [Visual Studio Code](https://code.visualstudio.com/). -You can use any other editor that recognizes the [JSON schema]({{% relref "/configuration/jsonschema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. +You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/jsonschema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. ### TOML @@ -138,7 +138,7 @@ default { ## Generate a secure password -**resticprofile** can generate a [secure password file]({{% relref "/usage/keyfile" %}}) for you: +**resticprofile** can generate a [secure password file]({{% relref "/usage/examples/keyfile" %}}) for you: ```shell resticprofile generate --random-key > password.txt @@ -308,7 +308,7 @@ default { {{% /tab %}} {{< /tabs >}} -**resticprofile** can [schedule]({{% relref "/schedules" %}}) work on macOS, Windows, most Unixes and Linux distributions: it is simply adding an entry in the default scheduler of your platform. +**resticprofile** can [schedule]({{% relref "/configuration/schedules" %}}) work on macOS, Windows, most Unixes and Linux distributions: it is simply adding an entry in the default scheduler of your platform. To schedule the backup of the default profile, simply type the command: diff --git a/docs/content/configuration/monitoring/_index.md b/docs/content/configuration/monitoring/_index.md index 1a5cc7ec..25fcc62c 100644 --- a/docs/content/configuration/monitoring/_index.md +++ b/docs/content/configuration/monitoring/_index.md @@ -160,7 +160,7 @@ If specified in different places, here's the priority order for the log destinat ## Send logs to a temporary file -This can be done by using the [template]({{% relref "/configuration/templates" %}}) function `tempFile`. +This can be done by using the [template]({{% relref "/configuration/profiles/templates" %}}) function `tempFile`. This is to cover a special case when you want to upload the logs one by one to a remote location in a `run-finally` or a `run-after-fail` target. diff --git a/docs/content/configuration/monitoring/prometheus.md b/docs/content/configuration/monitoring/prometheus.md index 74c8161c..8291b7e0 100644 --- a/docs/content/configuration/monitoring/prometheus.md +++ b/docs/content/configuration/monitoring/prometheus.md @@ -79,7 +79,7 @@ root: {{< /tabs >}} {{% notice style="note" %}} -Set `extended-status` to `true` to access all available metrics. For details, see [Extended status]({{% relref "/monitoring/status/index.html#-extended-status" %}}). +Set `extended-status` to `true` to access all available metrics. For details, see [Extended status]({{% relref "/configuration/monitoring/status#-extended-status" %}}). {{% /notice %}} Here's an example of a generated prometheus file: diff --git a/docs/content/configuration/profiles/include.md b/docs/content/configuration/profiles/include.md index b5cfaf4d..a2654314 100644 --- a/docs/content/configuration/profiles/include.md +++ b/docs/content/configuration/profiles/include.md @@ -73,7 +73,7 @@ global { 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. -Within included files, the current [configuration path]({{% relref "path/#how-paths-inside-the-configuration-are-resolved" %}}) is not changed. Path resolution remains relative to the path of the main configuration file. +Within included files, the current [configuration path]({{% relref "/configuration/profiles/path/#how-paths-inside-the-configuration-are-resolved" %}}) is not changed. Path resolution remains relative to the path of the main configuration file. {{% notice style="note" %}} Included files cannot include nested files. Specifying `includes` inside an included file has no effect. @@ -81,7 +81,7 @@ Included files cannot include nested files. Specifying `includes` inside an incl ## Configuration Merging -Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/templates" %}}) prior to parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`. This means [variables]({{% relref "variables" %}}) and [templates]({{% relref "/configuration/templates" %}}) must create valid configuration markup that can be parsed or loading will fail. +Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/profiles/variables" %}}) and [templates]({{% relref "/configuration/profiles/templates" %}}) prior to parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`. This means [variables]({{% relref "/configuration/profiles/variables" %}}) and [templates]({{% relref "/configuration/profiles/templates" %}}) must create valid configuration markup that can be parsed or loading will fail. Configuration files are loaded and applied in a fixed order: @@ -89,7 +89,7 @@ Configuration files are loaded and applied in a fixed order: 2. `includes` are iterated in declaration order: * Every item may be a single file path or glob expression * Glob expressions are resolved and iterated in alphabetical order - * All paths are resolved relative to [configuration path]({{% relref "/configuration/path/index.html#how-paths-inside-the-configuration-are-resolved" %}}) + * All paths are resolved relative to [configuration path]({{% relref "/configuration/profiles/path/#how-paths-inside-the-configuration-are-resolved" %}}) Configuration files are loaded in the following order when assuming `/etc/resticprofile/profiles.conf` with `includes = ["first.conf", "conf.d/*.conf", "last.conf"]`: ``` diff --git a/docs/content/configuration/profiles/inheritance.md b/docs/content/configuration/profiles/inheritance.md index aef20532..51e1cbc0 100644 --- a/docs/content/configuration/profiles/inheritance.md +++ b/docs/content/configuration/profiles/inheritance.md @@ -9,11 +9,11 @@ You can use `resticprofile [.]show` (or `resticprofile [--name }} {{% tab title="yaml" %}} @@ -297,7 +297,7 @@ Every use object within the `use` list has the following structure: | `vars`: `` | Set mixin variable `$` | | `` | Set mixin variable `$` (short syntax) | -Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent. +Mixins are applied to the configuration after processing all [includes]({{% relref "/configuration/profiles/include/index.html" %}}) but prior to [profile inheritance](#profile-inheritance) which means the `use` properties are not inherited but the result of applying `use` is inherited instead. What is defined by a mixin in a parent profile can still be overridden by a definition in a derived profile, but derived profiles can not change which mixins apply to their parent. List properties that have been inherited from a parent can be modified (append/prepend) and replaced by a mixin. diff --git a/docs/content/configuration/profiles/variables.md b/docs/content/configuration/profiles/variables.md index aaa0a66a..603211f3 100644 --- a/docs/content/configuration/profiles/variables.md +++ b/docs/content/configuration/profiles/variables.md @@ -8,7 +8,7 @@ weight: 26 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]({{% relref "configuration/include" %}}) are loaded, and [inheritance]({{% relref "/configuration/inheritance" %}}) is resolved. These variables are replaced by their value **before** the configuration is parsed. +- **template variables**: These variables are fixed once the full configuration file is loaded: [includes]({{% relref "/configuration/profiles/include" %}}) are loaded, and [inheritance]({{% relref "/configuration/profiles/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 @@ -514,12 +514,12 @@ default { ## Runtime variable expansion -Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/templates" %}}) that are expanded prior to parsing the configuration file. +Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/profiles/templates" %}}) that are expanded prior to parsing the configuration file. This means they must be used carefully to create correct config markup, but they are also very flexible. There is also unix style variable expansion using the `${variable}` or `$variable` syntax on configuration **values** that expand after the config file was parsed. Values that take a file path or path expression and a few others support this expansion. -If not specified differently, these variables resolve to the corresponding environment variable or to an empty value if no such environment variable exists. Exceptions are [mixins]({{% relref "/configuration/inheritance#mixins" %}}) where `$variable` style is used for parametrisation and the profile [config flag]({{% relref "reference/profile" %}}) `prometheus-push-job`. +If not specified differently, these variables resolve to the corresponding environment variable or to an empty value if no such environment variable exists. Exceptions are [mixins]({{% relref "/configuration/profiles/inheritance#mixins" %}}) where `$variable` style is used for parametrisation and the profile [config flag]({{% relref "reference/profile" %}}) `prometheus-push-job`. ### Example diff --git a/docs/content/configuration/schedules/_index.md b/docs/content/configuration/schedules/_index.md index ea26545f..a45a2e72 100644 --- a/docs/content/configuration/schedules/_index.md +++ b/docs/content/configuration/schedules/_index.md @@ -8,11 +8,11 @@ weight = 4 ## Scheduler resticprofile manages scheduled backups using: -- **[launchd]({{% relref "/schedules/launchd" %}})** on macOS -- **[Task Scheduler]({{% relref "/schedules/task_scheduler" %}})** on Windows -- **[systemd]({{% relref "/schedules/systemd" %}})** on Linux and other BSDs -- **[crond]({{% relref "/schedules/cron" %}})** as a fallback (requires `crontab` binary) -- **[crontab]({{% relref "/schedules/cron" %}})** files (with or without a user column) +- **[launchd]({{% relref "./scheduling_methods/launchd" %}})** on macOS +- **[Task Scheduler]({{% relref "./scheduling_methods/task_scheduler" %}})** on Windows +- **[systemd]({{% relref "./scheduling_methods/systemd" %}})** on Linux and other BSDs +- **[crond]({{% relref "./scheduling_methods/cron" %}})** as a fallback (requires `crontab` binary) +- **[crontab]({{% relref "./scheduling_methods/cron" %}})** files (with or without a user column) On Unix systems (excluding macOS), resticprofile uses **systemd** if available, otherwise it falls back to **crond**. diff --git a/docs/content/configuration/schedules/commands.md b/docs/content/configuration/schedules/commands.md index 90c387a6..c4993e94 100644 --- a/docs/content/configuration/schedules/commands.md +++ b/docs/content/configuration/schedules/commands.md @@ -57,7 +57,7 @@ Starting with `v0.30.0`, the behavior of the `unschedule` command changed: Print the status of all installed schedules for the selected profiles. -The `status` command output varies by OS. See the [examples]({{% relref "/schedules/examples" %}}) for details. +The `status` command output varies by OS. See the [examples]({{% relref "/configuration/schedules/examples" %}}) for details. ### run-schedule command diff --git a/docs/content/configuration/schedules/scheduling_methods/systemd.md b/docs/content/configuration/schedules/scheduling_methods/systemd.md index 352c6db2..731429ce 100644 --- a/docs/content/configuration/schedules/scheduling_methods/systemd.md +++ b/docs/content/configuration/schedules/scheduling_methods/systemd.md @@ -72,7 +72,7 @@ Setting the profile option `schedule-after-network-online: true` ensures schedul ## systemd drop-in files -You can automatically populate `*.conf.d` [drop-in files](https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#main-conf) for profiles, allowing easy overrides of generated services without [modifying service templates]({{% relref "/schedules/systemd/#how-to-change-the-default-systemd-unit-and-timer-file-using-a-template" %}}). For example: +You can automatically populate `*.conf.d` [drop-in files](https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#main-conf) for profiles, allowing easy overrides of generated services without [modifying service templates]({{% relref "./#how-to-change-the-default-systemd-unit-and-timer-file-using-a-template" %}}). For example: {{< tabs groupid="config-with-json" >}} {{% tab title="toml" %}} diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index 7df146f9..6b9493e8 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -10,28 +10,28 @@ Here is a non-exhaustive list of what resticprofile offers: * Create multiple profiles in one configuration file * Profiles can inherit options from other profiles * Create groups of profiles to run sequentially - * Easily [schedule]({{% relref "/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*) - * Use [template syntax]({{% relref "/configuration/templates" %}}) in your configuration file + * Easily [schedule]({{% relref "/configuration/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*) + * Use [template syntax]({{% relref "/configuration/profiles/templates" %}}) in your configuration file * **[new for v0.29.0]** Schedule a group of profiles (configuration `v2` only) * **Automation** * Run the forget command before or after a backup (in a section called *retention*) * Check a repository before or after a backup - * Run [shell commands]({{% relref "/configuration/run_hooks" %}}) before or after running a profile, useful for mounting and unmounting backup disks - * Run a [shell command]({{% relref "/configuration/run_hooks" %}}) if an error occurs + * Run [shell commands]({{% relref "/configuration/hooks/run_hooks" %}}) before or after running a profile, useful for mounting and unmounting backup disks + * Run a [shell command]({{% relref "/configuration/hooks/run_hooks" %}}) if an error occurs * Send a backup stream via _stdin_ - * Start restic at different [priorities]({{% relref "/configuration/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) + * Start restic at different [priorities]({{% relref "/configuration/profiles/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) * Automatically clear [stale locks]({{% relref "/usage/locks" %}}) * **Monitoring** - * Generate a simple [status file]({{% relref "/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly - * Export a [prometheus]({{% relref "/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway + * Generate a simple [status file]({{% relref "/configuration/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly + * Export a [prometheus]({{% relref "/configuration/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway * Run shell commands in the background when non-fatal errors are detected - * Send messages to [HTTP hooks]({{% relref "/configuration/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy) - * Send resticprofile [logs]({{% relref "/configuration/logs" %}}) to a syslog server + * Send messages to [HTTP hooks]({{% relref "/configuration/hooks/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy) + * Send resticprofile [logs]({{% relref "/configuration/monitoring/index" %}}) to a syslog server * **Checks** * Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup * Avoid scheduling a job when the system is on battery * **Misc** - * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}}) - * Automatically [initialize the secondary repository]({{% relref "/configuration/copy" %}}) using the `copy-chunker-params` flag - * Prevent the system from [idle sleeping]({{% relref "/configuration/sleep" %}}) + * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/examples/keyfile" %}}) + * Automatically [initialize the secondary repository]({{% relref "/configuration/hooks/copy" %}}) using the `copy-chunker-params` flag + * Prevent the system from [idle sleeping]({{% relref "/configuration/schedules/sleep" %}}) * View help for both restic and resticprofile via the `help` command or `-h` flag diff --git a/docs/themes/hugo-theme-relearn b/docs/themes/hugo-theme-relearn index e812df03..d9ca8e8d 160000 --- a/docs/themes/hugo-theme-relearn +++ b/docs/themes/hugo-theme-relearn @@ -1 +1 @@ -Subproject commit e812df032eeaf0f4dc8880bce350b9c07be3abf4 +Subproject commit d9ca8e8d8f592909707aef80e9a1a6b5b37b4b78 From 700796c39d5a6518d3051d8b1a0f5abec4ef02b2 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sun, 16 Nov 2025 15:33:47 -0500 Subject: [PATCH 17/29] Moved a couple of files around; created the profiles/index.md; rearranged weights --- docs/content/_index.md | 4 +- docs/content/changelog.md | 2 +- docs/content/configuration/_index.md | 3 +- docs/content/configuration/examples/_index.md | 3 +- .../_index.md => getting_started.md} | 41 +----------------- docs/content/configuration/hooks/_index.md | 2 + .../configuration/monitoring/_index.md | 3 +- .../{getting_started => profiles}/TOML.png | Bin .../{getting_started => profiles}/YAML.png | Bin docs/content/configuration/profiles/_index.md | 23 ++++++++++ .../configuration/profiles/editorConfig.md | 21 +++++++++ .../content/configuration/schedules/_index.md | 3 +- docs/content/contributions/_index.md | 2 +- docs/content/features/_index.md | 1 + docs/content/usage/examples/_index.md | 1 + 15 files changed, 61 insertions(+), 48 deletions(-) rename docs/content/configuration/{getting_started/_index.md => getting_started.md} (80%) rename docs/content/configuration/{getting_started => profiles}/TOML.png (100%) rename docs/content/configuration/{getting_started => profiles}/YAML.png (100%) create mode 100644 docs/content/configuration/profiles/_index.md create mode 100644 docs/content/configuration/profiles/editorConfig.md diff --git a/docs/content/_index.md b/docs/content/_index.md index 70a089d7..58b9c678 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -4,9 +4,9 @@ title: resticprofile description: Configuration profiles manager for restic backup --- -Configuration profiles manager for [restic backup](https://restic.net/) +**resticprofile** is an automation tool for [restic backup](https://restic.net/), also known as a *wrapper*. -**resticprofile** bridges the gap between a configuration file and restic backup. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task. +**resticprofile** bridges the gap between a configuration file and a runner that generates all necessary calls to **restic**. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task. The configuration file supports various formats: * [TOML](https://github.com/toml-lang/toml): files with extensions *.toml* and *.conf* (for compatibility with versions before 0.6.0) diff --git a/docs/content/changelog.md b/docs/content/changelog.md index 4ccf5fdd..7a0e40f0 100644 --- a/docs/content/changelog.md +++ b/docs/content/changelog.md @@ -1,6 +1,6 @@ --- archetype: chapter -pre: 8. +pre: 6. title: Release Notes weight: 8 --- diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md index d56cea79..bf680bb7 100644 --- a/docs/content/configuration/_index.md +++ b/docs/content/configuration/_index.md @@ -5,8 +5,7 @@ title = "Configuration file" weight = 2 +++ - -* A configuration is a set of _profiles_. +* A configuration is a set of [_profiles_]({{% relref "/configuration/profiles" %}}). * Each profile is in a new section that has the name of the profile. * Inside each profile, you can specify different flags for each command. * A command definition is in a subsection of the name of the command. diff --git a/docs/content/configuration/examples/_index.md b/docs/content/configuration/examples/_index.md index 13d854d7..7122f5d2 100644 --- a/docs/content/configuration/examples/_index.md +++ b/docs/content/configuration/examples/_index.md @@ -1,6 +1,7 @@ --- title: "Examples" -weight: 5 +weight: 40 +alwaysopen: false --- So let's say you normally use this simple command: diff --git a/docs/content/configuration/getting_started/_index.md b/docs/content/configuration/getting_started.md similarity index 80% rename from docs/content/configuration/getting_started/_index.md rename to docs/content/configuration/getting_started.md index 41d85bd2..fc08751c 100644 --- a/docs/content/configuration/getting_started/_index.md +++ b/docs/content/configuration/getting_started.md @@ -1,50 +1,13 @@ --- title: "Getting Started" -weight: 2 +weight: 10 +alwaysopen: false --- ## 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]({{% relref "/installation/docker/index.html" %}}), you need to have **restic** [installed on your machine](https://restic.readthedocs.io/en/stable/). -## Choose Your Favorite Format - -The **resticprofile** configuration file can be written in: -* [TOML](https://github.com/toml-lang/toml): configuration file with extension *.toml* or *.conf* -* [YAML](https://en.wikipedia.org/wiki/YAML): configuration file with extension *.yaml* -* [JSON](https://en.wikipedia.org/wiki/JSON): configuration file with extension *.json* -* [HCL](https://github.com/hashicorp/hcl): configuration file with extension *.hcl* - -We recommend using either TOML or YAML. - -JSON is suitable for auto-generated configurations but is not the easiest format for humans to read and write. - -HCL can be useful if you already use a tool from the Hashicorp stack; otherwise, it's another format to learn. - -## Configure Your Text Editor - -We'll show you how to get documentation and auto-completion for the **resticprofile** configuration using [Visual Studio Code](https://code.visualstudio.com/). - -You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/jsonschema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. - -### TOML - -In Visual Studio Code, install an extension that supports completion and syntax validation using a JSON schema. - -For example, install the [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension: - -![TOML extension]({{< absolute "configuration/getting_started/TOML.png" nohtml >}}) - -### YAML - -For YAML, install an extension like the one [provided by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) in Visual Studio Code to understand the shape of your configuration file. - -![YAML extension]({{< absolute "configuration/getting_started/YAML.png" nohtml >}}) - ## Write your first configuration file The configuration file lists profiles containing commands and flags. diff --git a/docs/content/configuration/hooks/_index.md b/docs/content/configuration/hooks/_index.md index 50268bf6..6c0ad0a4 100644 --- a/docs/content/configuration/hooks/_index.md +++ b/docs/content/configuration/hooks/_index.md @@ -1,5 +1,7 @@ --- title: Hooks +weight: 60 +alwaysopen: false --- {{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/monitoring/_index.md b/docs/content/configuration/monitoring/_index.md index 25fcc62c..0cb5a5d0 100644 --- a/docs/content/configuration/monitoring/_index.md +++ b/docs/content/configuration/monitoring/_index.md @@ -1,6 +1,7 @@ --- title: "Logs" -weight: 45 +weight: 50 +alwaysopen: false --- By default **resticprofile** will display all logs (from itself and **restic**) to the console. diff --git a/docs/content/configuration/getting_started/TOML.png b/docs/content/configuration/profiles/TOML.png similarity index 100% rename from docs/content/configuration/getting_started/TOML.png rename to docs/content/configuration/profiles/TOML.png diff --git a/docs/content/configuration/getting_started/YAML.png b/docs/content/configuration/profiles/YAML.png similarity index 100% rename from docs/content/configuration/getting_started/YAML.png rename to docs/content/configuration/profiles/YAML.png diff --git a/docs/content/configuration/profiles/_index.md b/docs/content/configuration/profiles/_index.md new file mode 100644 index 00000000..58918336 --- /dev/null +++ b/docs/content/configuration/profiles/_index.md @@ -0,0 +1,23 @@ +--- +title: Profiles +weight: 30 +alwaysopen: false +--- + +## Choose Your Favorite Format + +The **resticprofile** configuration file can be written in: +* [TOML](https://github.com/toml-lang/toml): configuration file with extension *.toml* or *.conf* +* [YAML](https://en.wikipedia.org/wiki/YAML): configuration file with extension *.yaml* +* [JSON](https://en.wikipedia.org/wiki/JSON): configuration file with extension *.json* +* [HCL](https://github.com/hashicorp/hcl): configuration file with extension *.hcl* + +We recommend using either TOML or YAML. + +JSON is suitable for auto-generated configurations but is not the easiest format for humans to read and write. + +HCL can be useful if you already use a tool from the Hashicorp stack; otherwise, it's another format to learn. + +## Configure Your Text Editor + +A guide on configurating your text editor can be found [here]({{% relref "editorConfig.md" %}}). diff --git a/docs/content/configuration/profiles/editorConfig.md b/docs/content/configuration/profiles/editorConfig.md new file mode 100644 index 00000000..aee418e6 --- /dev/null +++ b/docs/content/configuration/profiles/editorConfig.md @@ -0,0 +1,21 @@ +--- +title: "Configuring your Editor" +--- + +We'll show you how to get documentation and auto-completion for the **resticprofile** configuration using [Visual Studio Code](https://code.visualstudio.com/). + +You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/jsonschema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. + +### TOML + +In Visual Studio Code, install an extension that supports completion and syntax validation using a JSON schema. + +For example, install the [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension: + +![TOML extension]({{< absolute "configuration/getting_started/TOML.png" nohtml >}}) + +### YAML + +For YAML, install an extension like the one [provided by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) in Visual Studio Code to understand the shape of your configuration file. + +![YAML extension]({{< absolute "configuration/getting_started/YAML.png" nohtml >}}) diff --git a/docs/content/configuration/schedules/_index.md b/docs/content/configuration/schedules/_index.md index a45a2e72..361074e4 100644 --- a/docs/content/configuration/schedules/_index.md +++ b/docs/content/configuration/schedules/_index.md @@ -1,7 +1,8 @@ +++ archetype = "chapter" title = "Schedules" -weight = 4 +weight = 40 +alwaysopen = false +++ diff --git a/docs/content/contributions/_index.md b/docs/content/contributions/_index.md index 438b951a..46757a43 100644 --- a/docs/content/contributions/_index.md +++ b/docs/content/contributions/_index.md @@ -1,6 +1,6 @@ +++ archetype = "chapter" -pre = "7. " +pre = "5. " title = "Contributions" weight = 7 +++ diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index 6b9493e8..102eda12 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -1,5 +1,6 @@ --- title: Features +weight: 1 description: Features of resticprofile --- diff --git a/docs/content/usage/examples/_index.md b/docs/content/usage/examples/_index.md index 4a68374e..7ee30235 100644 --- a/docs/content/usage/examples/_index.md +++ b/docs/content/usage/examples/_index.md @@ -1,5 +1,6 @@ --- title: Examples +weight: 20 --- Here are a few examples how to run resticprofile (using the main example configuration file) From 6dc5e1e493d87c9b87cc2a742b91b84aa0c9da1b Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Sun, 16 Nov 2025 15:53:41 -0500 Subject: [PATCH 18/29] Adding links --- docs/content/configuration/examples/_index.md | 2 ++ docs/content/configuration/profiles/_index.md | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/docs/content/configuration/examples/_index.md b/docs/content/configuration/examples/_index.md index 7122f5d2..1aedbf18 100644 --- a/docs/content/configuration/examples/_index.md +++ b/docs/content/configuration/examples/_index.md @@ -102,4 +102,6 @@ resticprofile --dry-run backup 2022/05/18 17:14:07 profile 'default': finished 'backup' ``` +## More Examples + {{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/profiles/_index.md b/docs/content/configuration/profiles/_index.md index 58918336..f42ecc30 100644 --- a/docs/content/configuration/profiles/_index.md +++ b/docs/content/configuration/profiles/_index.md @@ -21,3 +21,7 @@ HCL can be useful if you already use a tool from the Hashicorp stack; otherwise, ## Configure Your Text Editor A guide on configurating your text editor can be found [here]({{% relref "editorConfig.md" %}}). + +## More Information + +{{% children %}} From cf92423fc9ba6040eb931892cf4c566ec5e9e0e3 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 2 Dec 2025 22:21:06 -0500 Subject: [PATCH 19/29] Updating editorConfig with the correct link --- docs/content/configuration/profiles/editorConfig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/configuration/profiles/editorConfig.md b/docs/content/configuration/profiles/editorConfig.md index aee418e6..0f0b546a 100644 --- a/docs/content/configuration/profiles/editorConfig.md +++ b/docs/content/configuration/profiles/editorConfig.md @@ -4,7 +4,7 @@ title: "Configuring your Editor" We'll show you how to get documentation and auto-completion for the **resticprofile** configuration using [Visual Studio Code](https://code.visualstudio.com/). -You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/jsonschema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. +You can use any other editor that recognizes the [JSON schema]({{% relref "/reference/json-schema" %}}). The same JSON schema can be used for JSON, TOML, and YAML file formats. ### TOML From ec341f2537c619aaccf6980751147acf024c382f Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Thu, 18 Dec 2025 22:21:33 -0500 Subject: [PATCH 20/29] Adding shortcode to quick add Table of Contents in a doc --- docs/layouts/shortcodes/toc.html | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/layouts/shortcodes/toc.html diff --git a/docs/layouts/shortcodes/toc.html b/docs/layouts/shortcodes/toc.html new file mode 100644 index 00000000..ba789ee7 --- /dev/null +++ b/docs/layouts/shortcodes/toc.html @@ -0,0 +1 @@ +{{ .Page.TableOfContents }} From 97430c918c7ef801cbe0db52db84ca7274debffb Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Thu, 18 Dec 2025 22:21:53 -0500 Subject: [PATCH 21/29] Updating documentation once more --- docs/content/_index.md | 9 +---- docs/content/installation/_index.md | 1 + docs/content/installation/binaries.md | 53 +++++++++++++++------------ docs/content/installation/linux.md | 1 + 4 files changed, 33 insertions(+), 31 deletions(-) diff --git a/docs/content/_index.md b/docs/content/_index.md index 58b9c678..38b18aaa 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -4,12 +4,7 @@ title: resticprofile description: Configuration profiles manager for restic backup --- -**resticprofile** is an automation tool for [restic backup](https://restic.net/), also known as a *wrapper*. +**resticprofile** is a wrapper for [restic backup](https://restic.net/). It bridges the gap between a configuration file and a runner that generates all necessary calls to **restic**. -**resticprofile** bridges the gap between a configuration file and a runner that generates all necessary calls to **restic**. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task. +Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task. -The configuration file supports various formats: -* [TOML](https://github.com/toml-lang/toml): files with extensions *.toml* and *.conf* (for compatibility with versions before 0.6.0) -* [JSON](https://en.wikipedia.org/wiki/JSON): files with extension *.json* -* [YAML](https://en.wikipedia.org/wiki/YAML): files with extension *.yaml* -* [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl* diff --git a/docs/content/installation/_index.md b/docs/content/installation/_index.md index 7eacf461..a0db45d6 100644 --- a/docs/content/installation/_index.md +++ b/docs/content/installation/_index.md @@ -5,4 +5,5 @@ title = "Installation" weight = 1 +++ +Here are the multiple ways you can install resticprofile: {{% children %}} diff --git a/docs/content/installation/binaries.md b/docs/content/installation/binaries.md index f4a6cad7..bcf468af 100644 --- a/docs/content/installation/binaries.md +++ b/docs/content/installation/binaries.md @@ -7,29 +7,34 @@ Pre-built binaries for resticprofile are available for various operating system You can download the latest versions from the [releases page](https://github.com/creativeprojects/resticprofile/releases). ## Pre-built binaries available: -- darwin/amd64 -- darwin/arm64 -- freebsd/386 -- freebsd/amd64 -- freebsd/armv6 -- freebsd/armv7 -- linux/386 -- linux/amd64 -- linux/arm64 -- linux/armv6 -- linux/armv7 -- linux/mips64 hardfloat -- linux/mips64le hardfloat -- linux/mips hardfloat -- linux/mipsle hardfloat -- linux/ppc64 -- linux/ppc64le -- linux/riscv64 -- linux/s390x +- windows + - 386 + - amd64 + - arm64 +- linux + - 386 + - amd64 + - arm64 + - armv6 + - armv7 + - mips64 hardfloat + - mips64le hardfloat + - mips hardfloat + - mipsle hardfloat + - ppc64 + - ppc64le + - riscv64 + - s390x +- darwin + - amd64 + - arm64 +- freebsd + - 386 + - amd64 + - armv6 + - armv7 +- openbsd + - 386 + - amd64 - netbsd/amd64 -- openbsd/386 -- openbsd/amd64 - solaris/amd64 -- windows/386 -- windows/amd64 -- windows/arm64 🆕 diff --git a/docs/content/installation/linux.md b/docs/content/installation/linux.md index 1eb27952..e405f4e4 100644 --- a/docs/content/installation/linux.md +++ b/docs/content/installation/linux.md @@ -3,6 +3,7 @@ title: "Linux" weight: 10 --- +{{< toc >}} ## Installation via a script From fba3c17507af78a7cd1b849830cc40e9943da320 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Thu, 18 Dec 2025 23:42:00 -0500 Subject: [PATCH 22/29] Updating installation documentation to be more condensed --- docs/content/configuration/_index.md | 6 +++ docs/content/faq.md | 25 ++++++++++ docs/content/installation/_index.md | 3 ++ docs/content/installation/ansible/index.md | 6 ++- docs/content/installation/linux.md | 50 +++++--------------- docs/content/installation/macosx.md | 55 ---------------------- docs/content/installation/shell.md | 24 ---------- docs/content/installation/source.md | 30 +++--------- docs/content/installation/upgrade.md | 26 ---------- 9 files changed, 56 insertions(+), 169 deletions(-) create mode 100644 docs/content/faq.md delete mode 100644 docs/content/installation/macosx.md delete mode 100644 docs/content/installation/shell.md delete mode 100644 docs/content/installation/upgrade.md diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md index bf680bb7..73215d42 100644 --- a/docs/content/configuration/_index.md +++ b/docs/content/configuration/_index.md @@ -5,6 +5,12 @@ title = "Configuration file" weight = 2 +++ +The configuration file supports various formats: +* [TOML](https://github.com/toml-lang/toml): files with extensions *.toml* and *.conf* (for compatibility with versions before 0.6.0) +* [JSON](https://en.wikipedia.org/wiki/JSON): files with extension *.json* +* [YAML](https://en.wikipedia.org/wiki/YAML): files with extension *.yaml* +* [HCL](https://github.com/hashicorp/hcl): files with extension *.hcl* + * A configuration is a set of [_profiles_]({{% relref "/configuration/profiles" %}}). * Each profile is in a new section that has the name of the profile. * Inside each profile, you can specify different flags for each command. diff --git a/docs/content/faq.md b/docs/content/faq.md new file mode 100644 index 00000000..e7433800 --- /dev/null +++ b/docs/content/faq.md @@ -0,0 +1,25 @@ +--- +title: FAQ +pre: "4. " +weight: 4 +--- + +{{< toc >}} + + +## Installation +### Shell Completion + +To generate the shell completion script, use: + +```shell +# bash +eval "$(resticprofile generate --bash-completion)" + +# zsh +eval "$(resticprofile generate --zsh-completion)" +``` + +### My homebrew install failed! + +Homebrew appears to need access to a compiler. If the installation fails, you may need to install gcc. diff --git a/docs/content/installation/_index.md b/docs/content/installation/_index.md index a0db45d6..8b28e190 100644 --- a/docs/content/installation/_index.md +++ b/docs/content/installation/_index.md @@ -7,3 +7,6 @@ weight = 1 Here are the multiple ways you can install resticprofile: {{% children %}} + +## Upgrading +After installation, you can run `resticprofile self-update` to update resticprofile to the latest release. The `-q` or `--quiet` flag updates the application without prompting. diff --git a/docs/content/installation/ansible/index.md b/docs/content/installation/ansible/index.md index b8f8fb13..6b539a94 100644 --- a/docs/content/installation/ansible/index.md +++ b/docs/content/installation/ansible/index.md @@ -3,12 +3,14 @@ title: "Ansible" weight: 15 --- +{{% notice style="caution" %}} +This is a work in progress documentation. +{{% /notice %}} + ## Installation using Ansible Installation using Ansible is not streamlined, but here's the playbook I'm using on my servers: - - {{% notice style="secondary" title="Playbooks" icon="paperclip" %}} * [resticprofile.yml]({{< absolute "installation/ansible/resticprofile.yml" nohtml >}}) {{% /notice %}} diff --git a/docs/content/installation/linux.md b/docs/content/installation/linux.md index e405f4e4..ffb1e956 100644 --- a/docs/content/installation/linux.md +++ b/docs/content/installation/linux.md @@ -1,20 +1,20 @@ --- -title: "Linux" +title: "Linux and MacOS" weight: 10 --- {{< toc >}} ## Installation via a script +Works for: MacOS, Linux -Here's a simple script to download the binary automatically. It works on macOS, FreeBSD and Linux: + +Here's a simple script to download the binary in a `bin` directory under your current directory. ```shell curl -sfL https://raw.githubusercontent.com/creativeprojects/resticprofile/master/install.sh | sh ``` -It should copy resticprofile in a `bin` directory under your current directory. - If you need more control, you can save the shell script and run it manually: ```shell @@ -25,51 +25,23 @@ sudo ./install.sh -b /usr/local/bin It will install resticprofile in `/usr/local/bin/` -## Debian package - -WakeMeOps publishes packages for [restic](https://docs.wakemeops.com/packages/restic/) and [resticprofile](https://docs.wakemeops.com/packages/resticprofile/). - -Learn more: https://docs.wakemeops.com/packages/resticprofile/ - -These packages are managed by a third party. -## Installation with homebrew for Linux +## Installation With Homebrew +Works for: MacOS, Linux -There's a Linux [homebrew](https://brew.sh/) tap for resticprofile: +There's a [homebrew](https://brew.sh/) tap for resticprofile: ```shell brew tap creativeprojects/tap brew install resticprofile -``` - -You can also install `restic` at the same time with `--with-restic` flag: - -```shell +# You can also install `restic` at the same time with `--with-restic` flag: brew install resticprofile --with-restic ``` -You can test that resticprofile is properly installed (make sure you have restic installed or the test will fail): - -```shell -brew test resticprofile -``` - -Upgrading resticprofile installed via homebrew is very easy: - -```shell -brew update -brew upgrade resticprofile -``` - {{% notice style="note" %}} The resticprofile command `self-update` is not available when installed via homebrew. {{% /notice %}} -### Note on installing on Linux via Homebrew - -When testing homebrew after spinning new Linux virtual machines, I noticed resticprofile wouldn't install without a compiler installed on the machine. -Even though resticprofile is distributed as a **binary**, it looks like homebrew needs access to a compiler. - -Depending on your distribution you will need to install gcc: -* `sudo yum install gcc` -* `sudo apt install gcc` +{{% notice style="tip" title="Debian package" %}} +WakeMeOps (a third party) publishes packages for [restic](https://docs.wakemeops.com/packages/restic/) and [resticprofile](https://docs.wakemeops.com/packages/resticprofile/). +{{% /notice %}} diff --git a/docs/content/installation/macosx.md b/docs/content/installation/macosx.md deleted file mode 100644 index 1c6529f0..00000000 --- a/docs/content/installation/macosx.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: "mac OS" -weight: 11 ---- - -## Installation with Homebrew - -There's a [homebrew](https://brew.sh/) tap for resticprofile: - -```shell -brew tap creativeprojects/tap -brew install resticprofile -``` - -You can also install `restic` at the same time with `--with-restic` flag: - -```shell -brew install resticprofile --with-restic -``` - -You can test that resticprofile is properly installed (make sure you have restic installed or the test will fail): - -```shell -brew test resticprofile -``` - -Upgrading resticprofile installed via homebrew is very easy: - -```shell -brew update -brew upgrade resticprofile -``` -{{% notice style="note" %}} -The resticprofile command `self-update` is not available when installed via homebrew. -{{% /notice %}} - -## Installation via a script - -Here's a simple script to download the binary automatically. It works on mac OS X, FreeBSD and Linux: - -```shell -curl -sfL https://raw.githubusercontent.com/creativeprojects/resticprofile/master/install.sh | sh -``` - -It should copy resticprofile in a `bin` directory under your current directory. - -If you need more control, you can save the shell script and run it manually: - -```shell -curl -LO https://raw.githubusercontent.com/creativeprojects/resticprofile/master/install.sh -chmod +x install.sh -sudo ./install.sh -b /usr/local/bin -``` - -It will install resticprofile in `/usr/local/bin/` diff --git a/docs/content/installation/shell.md b/docs/content/installation/shell.md deleted file mode 100644 index 747062e3..00000000 --- a/docs/content/installation/shell.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Shell Completion" -weight: 100 ---- - - -Shell command line completions are provided for `bash` and `zsh`. - -To load the command completions in shell, use: - -```shell -# bash -eval "$(resticprofile generate --bash-completion)" - -# zsh -eval "$(resticprofile generate --zsh-completion)" -``` - -To install them permanently: - -```shell -resticprofile generate --bash-completion > /etc/bash_completion.d/resticprofile -chmod +x /etc/bash_completion.d/resticprofile -``` diff --git a/docs/content/installation/source.md b/docs/content/installation/source.md index 4ebe508f..85b54743 100644 --- a/docs/content/installation/source.md +++ b/docs/content/installation/source.md @@ -4,39 +4,23 @@ weight: 16 --- ## Installation from source +Requirements: `git`, [Go compiler](https://golang.org/dl/), `make` -It's very easy to compile from the source code. - -Ensure your machine has the following: -- `git` (use `git-bash` on Windows) -- [Go compiler](https://golang.org/dl/) -- `GNU Make` (preinstalled on many Unix systems). On Debian-based distributions (e.g., Ubuntu), install the `build-essential` package. - -Compilation: +Clone the repository by running: ```shell git clone https://github.com/creativeprojects/resticprofile.git cd resticprofile -make build ``` -Your compiled binary (`resticprofile` or `resticprofile.exe`) is available in the current folder. - -To install the binary in your user path: +To compile the binary, run: `make build` -```shell -make install -``` +To install the binary in your user path, run `make install` -To build all common platforms (`build-mac`, `build-linux`, `build-pi` & `build-windows`): - -```shell -make build-all -``` +To build the binary for all common platforms (`build-mac`, `build-linux`, `build-pi` & `build-windows`), run: `make build-all` +{{% notice style="tip" %}} Alternatively, a **go-only** build (without `GNU Make`) is accomplished with: - ```shell -git clone https://github.com/creativeprojects/resticprofile.git -cd resticprofile go build -v -o resticprofile . ``` +{{% /notice %}} diff --git a/docs/content/installation/upgrade.md b/docs/content/installation/upgrade.md deleted file mode 100644 index 63409211..00000000 --- a/docs/content/installation/upgrade.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "Upgrade" -weight: 20 ---- - -After installation, upgrade resticprofile to the latest release with this command: - -```shell -resticprofile self-update -``` - -{{% notice style="note" title="Package Managers" %}} -The `self-update` command is generally unavailable when installed through a package manager like Homebrew or Scoop. Use the package manager's upgrade feature instead. -{{% /notice %}} - -Resticprofile checks for new versions from GitHub releases and prompts you to update. Use the `-q` or `--quiet` flag to update automatically without prompting. - -```shell -resticprofile --quiet self-update -``` - -or - -```shell -resticprofile self-update --quiet -``` From 28c7d71a97472a5ca6c8c304b44b84b3fce00516 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Thu, 18 Dec 2025 23:57:46 -0500 Subject: [PATCH 23/29] Think ive cleaned up installation --- docs/content/faq.md | 7 +++ docs/content/installation/ansible/index.md | 2 +- docs/content/installation/docker.md | 72 +++------------------- docs/content/installation/source.md | 4 +- docs/content/installation/windows.md | 2 +- 5 files changed, 20 insertions(+), 67 deletions(-) diff --git a/docs/content/faq.md b/docs/content/faq.md index e7433800..61510d6b 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -23,3 +23,10 @@ eval "$(resticprofile generate --zsh-completion)" ### My homebrew install failed! Homebrew appears to need access to a compiler. If the installation fails, you may need to install gcc. + +## Docker + +### How do I schedule using Docker Compose? + +There's an example in the contribution section how to schedule backups in a long running container. +The configuration needs to specify `crond` as a scheduler. diff --git a/docs/content/installation/ansible/index.md b/docs/content/installation/ansible/index.md index 6b539a94..b232e2e6 100644 --- a/docs/content/installation/ansible/index.md +++ b/docs/content/installation/ansible/index.md @@ -1,6 +1,6 @@ --- title: "Ansible" -weight: 15 +weight: 16 --- {{% notice style="caution" %}} diff --git a/docs/content/installation/docker.md b/docs/content/installation/docker.md index 23c02e3d..804b8dc7 100644 --- a/docs/content/installation/docker.md +++ b/docs/content/installation/docker.md @@ -1,74 +1,20 @@ --- title: "Docker" -weight: 30 +weight: 15 --- +Docker images are available at `creativeprojects/resticprofile:latest` and `ghcr.io/creativeprojects/resticprofile:latest` - -## Using resticprofile from a docker image ## - -You can run resticprofile in a Docker container, which is the easiest way to install and update resticprofile and restic simultaneously. - -However, you must mount your backup source (and local destination, if applicable) as a Docker volume. On macOS, backups may be slower due to the known performance issues with mounted volumes. - -### Registries - -The official image is available on docker hub -```shell -docker pull creativeprojects/resticprofile:latest -``` -as well as on Github Container Registry -```shell -docker pull ghcr.io/creativeprojects/resticprofile:latest -``` - -### Configuration - -By default, the resticprofile container starts at `/resticprofile`. So you can feed a configuration this way: - +To run an instance of resticprofile, run: ```shell docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/resticprofile ``` -You can list your profiles: -```shell -docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/resticprofile profiles -``` - -### Container host name - -Each time a container starts, it is assigned a random name. - -To set a specific hostname, use the `-h` or `--hostname` flag with `docker run`: - -```shell -docker run -it --rm -v $PWD:/resticprofile -h my-hostname ghcr.io/creativeprojects/resticprofile -n profile backup -``` - -### Platforms - -The resticprofile docker image is available in these 2 platforms: -- linux/amd64 -- linux/arm64/v8 (compatible with raspberry pi 64bits) - -### rclone - -The resticprofile docker image also includes the latest version of [rclone][1]. - -### Container imager release cycle - -The Docker image is automatically uploaded to both registries when a new release is published on GitHub. The `latest` tag is updated to match the release. - -Each week, the `latest` image is rebuilt to include updates from Restic, Rclone, and the Alpine base image. - -After every commit to the main branch, another image is updated and tagged as `nightly`. This image may be unstable and is not recommended for production use. - -## Scheduling with docker compose - -There's an example in the contribution section how to schedule backups in a long running container. -The configuration needs to specify `crond` as a scheduler. +{{% notice style="warning" %}} +- You must mount your backup source (and local destination, if applicable) as a Docker volume. +- On macOS, backups may be slower due to the known performance issues with mounted volumes. +{{% /notice %}} -See [contrib][2] +Resticprofile's docker images also include restic and rclone. -[1]: https://rclone.org/ -[2]: https://github.com/creativeprojects/resticprofile/tree/master/contrib/schedule-in-docker +For further reference, consult the [docker reference page](/reference/docker). diff --git a/docs/content/installation/source.md b/docs/content/installation/source.md index 85b54743..6f4d1ff9 100644 --- a/docs/content/installation/source.md +++ b/docs/content/installation/source.md @@ -1,6 +1,6 @@ --- -title: "Source" -weight: 16 +title: "From Source" +weight: 13 --- ## Installation from source diff --git a/docs/content/installation/windows.md b/docs/content/installation/windows.md index 2c5fbbd2..b820b6b7 100644 --- a/docs/content/installation/windows.md +++ b/docs/content/installation/windows.md @@ -3,7 +3,7 @@ title: "Windows" weight: 12 --- - +{{< toc >}} ## Installation using bash From cbbb32466031535dcd3bce5f5b6d6523d3455d49 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 11:12:24 -0500 Subject: [PATCH 24/29] Updating documentation broken links --- docs/content/configuration/profiles/editorConfig.md | 4 ++-- docs/content/configuration/schedules/examples.md | 4 ++-- .../configuration/schedules/scheduling_methods/launchd.md | 4 ++-- .../configuration/schedules/scheduling_methods/systemd.md | 2 +- .../schedules/scheduling_methods/task_scheduler/index.md | 6 +++--- docs/content/installation/docker.md | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/content/configuration/profiles/editorConfig.md b/docs/content/configuration/profiles/editorConfig.md index 0f0b546a..36defc6b 100644 --- a/docs/content/configuration/profiles/editorConfig.md +++ b/docs/content/configuration/profiles/editorConfig.md @@ -12,10 +12,10 @@ In Visual Studio Code, install an extension that supports completion and syntax For example, install the [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml) extension: -![TOML extension]({{< absolute "configuration/getting_started/TOML.png" nohtml >}}) +![TOML extension]({{< absolute "configuration/profiles/TOML.png" nohtml >}}) ### YAML For YAML, install an extension like the one [provided by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) in Visual Studio Code to understand the shape of your configuration file. -![YAML extension]({{< absolute "configuration/getting_started/YAML.png" nohtml >}}) +![YAML extension]({{< absolute "configuration/profiles/YAML.png" nohtml >}}) diff --git a/docs/content/configuration/schedules/examples.md b/docs/content/configuration/schedules/examples.md index ede7727d..6dbf7947 100644 --- a/docs/content/configuration/schedules/examples.md +++ b/docs/content/configuration/schedules/examples.md @@ -342,7 +342,7 @@ Normalized form: *-*-* 22:22:00 In some cases, macOS may request permission to access the network, an external volume (like a USB drive), or a protected directory. A message window will appear while the backup runs in the background. {{% /notice %}} -![access files popup window]({{< absolute "schedules/removable_volume.png" nohtml >}}) +![access files popup window]({{< absolute "configuration/schedules/removable_volume.png" nohtml >}}) You may want to start the task now so you can grant special permissions: @@ -404,4 +404,4 @@ Normalized form: *-*-* 22:22:00 last exit code (*): (never exited) * : since last (re)schedule or last reboot -``` \ No newline at end of file +``` diff --git a/docs/content/configuration/schedules/scheduling_methods/launchd.md b/docs/content/configuration/schedules/scheduling_methods/launchd.md index e2c5dde1..c139bbfd 100644 --- a/docs/content/configuration/schedules/scheduling_methods/launchd.md +++ b/docs/content/configuration/schedules/scheduling_methods/launchd.md @@ -19,10 +19,10 @@ You can wait for the profile to start or start it manually. To start a backup pr Once you grant permission, the profile will run normally until you update resticprofile or restic. This is a macOS limitation. -![access files popup window]({{< absolute "schedules/removable_volume.png" nohtml >}}) +![access files popup window]({{< absolute "configuration/schedules/removable_volume.png" nohtml >}}) ## System permission A launchd daemon is generated when you set `schedule-permission` to `system`. It consists of a `plist` file in `/Library/LaunchDaemons`. -Run resticprofile with sudo to `schedule` and `unschedule` the profile. You can schedule and unschedule system and user profiles simultaneously using the `schedule --all` command. \ No newline at end of file +Run resticprofile with sudo to `schedule` and `unschedule` the profile. You can schedule and unschedule system and user profiles simultaneously using the `schedule --all` command. diff --git a/docs/content/configuration/schedules/scheduling_methods/systemd.md b/docs/content/configuration/schedules/scheduling_methods/systemd.md index 731429ce..a95515d7 100644 --- a/docs/content/configuration/schedules/scheduling_methods/systemd.md +++ b/docs/content/configuration/schedules/scheduling_methods/systemd.md @@ -72,7 +72,7 @@ Setting the profile option `schedule-after-network-online: true` ensures schedul ## systemd drop-in files -You can automatically populate `*.conf.d` [drop-in files](https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#main-conf) for profiles, allowing easy overrides of generated services without [modifying service templates]({{% relref "./#how-to-change-the-default-systemd-unit-and-timer-file-using-a-template" %}}). For example: +You can automatically populate `*.conf.d` [drop-in files](https://www.freedesktop.org/software/systemd/man/latest/systemd-system.conf.html#main-conf) for profiles, allowing easy overrides of generated services without [modifying service templates]({{% relref "#how-to-change-the-default-systemd-unit-and-timer-file-using-a-template" %}}). For example: {{< tabs groupid="config-with-json" >}} {{% tab title="toml" %}} diff --git a/docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md index 597a8e52..c4aa022b 100644 --- a/docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md +++ b/docs/content/configuration/schedules/scheduling_methods/task_scheduler/index.md @@ -15,7 +15,7 @@ Generally, you don't need to worry about this: resticprofile will restart itself ### resticprofile is blocked from restarting in elevated mode -![Unwanted software]({{< absolute "schedules/task_scheduler/unwanted_my_ass.png" nohtml >}}) +![Unwanted software](./unwanted_my_ass.png) I can't prevent this without buying a developer certificate. If you know any free or cheap certificate for open-source software, please let me know. @@ -26,11 +26,11 @@ You'll need to start an elevated shell yourself. - Right-click on `Command Prompt`, `Windows Terminal`, or `Windows Powershell` (choose your favorite) - Click on `Run as administrator` -![Start elevated command prompt]({{< absolute "schedules/task_scheduler/runas.png" nohtml >}}) +![Start elevated command prompt](./runas.png) It's easy to spot a terminal window opened with Administrator privileges: -![Administrator prefix]({{< absolute "schedules/task_scheduler/administrator.png" nohtml >}}) +![Administrator prefix](./administrator.png) > [!IMPORTANT] > Running the schedule command might cause Windows to delete _resticprofile.exe_, treating it as a threat. diff --git a/docs/content/installation/docker.md b/docs/content/installation/docker.md index 804b8dc7..b266ec2a 100644 --- a/docs/content/installation/docker.md +++ b/docs/content/installation/docker.md @@ -17,4 +17,4 @@ docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/res Resticprofile's docker images also include restic and rclone. -For further reference, consult the [docker reference page](/reference/docker). +For further reference, consult the [docker reference page]({{% relref "/reference/docker" %}}). From d34edadd28b97ce20549fc816bb88bedc8e9e285 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 12:12:45 -0500 Subject: [PATCH 25/29] Moving examples out of configuration and into usage, streamlining other sections too --- docs/content/configuration/examples/_index.md | 107 ----- .../content/configuration/hooks/http_hooks.md | 418 ++---------------- docs/content/configuration/hooks/run_hooks.md | 6 +- .../configuration/monitoring/_index.md | 79 +--- .../configuration/monitoring/prometheus.md | 2 +- .../configuration/monitoring/status.md | 2 +- .../monitoring/tempfilelogging.md | 77 ++++ .../configuration/monitoring/warnings.md | 4 +- docs/content/configuration/profiles/_index.md | 4 +- .../configuration/profiles/templates.md | 4 - .../configuration/schedules/commands.md | 4 +- .../configuration/schedules/configuration.md | 143 +----- docs/content/configuration/schedules/sleep.md | 15 - docs/content/faq.md | 6 + docs/content/features/_index.md | 2 +- docs/content/usage/change-schedule.md | 11 + docs/content/usage/examples/_index.md | 110 +++-- .../examples/azure-storage.md | 0 .../examples/configWindows.md | 0 .../examples/configWinheritence.md | 0 .../examples/scheduling-examples.md} | 124 ++++++ .../examples/stdin.md | 0 .../getting_started.md | 6 +- docs/content/usage/hooks/body-template.md | 115 +++++ docs/content/usage/hooks/healthchecks.md | 254 +++++++++++ 25 files changed, 725 insertions(+), 768 deletions(-) delete mode 100644 docs/content/configuration/examples/_index.md create mode 100644 docs/content/configuration/monitoring/tempfilelogging.md delete mode 100644 docs/content/configuration/schedules/sleep.md create mode 100644 docs/content/usage/change-schedule.md rename docs/content/{configuration => usage}/examples/azure-storage.md (100%) rename docs/content/{configuration => usage}/examples/configWindows.md (100%) rename docs/content/{configuration => usage}/examples/configWinheritence.md (100%) rename docs/content/{configuration/schedules/examples.md => usage/examples/scheduling-examples.md} (85%) rename docs/content/{configuration => usage}/examples/stdin.md (100%) rename docs/content/{configuration => usage}/getting_started.md (98%) create mode 100644 docs/content/usage/hooks/body-template.md create mode 100644 docs/content/usage/hooks/healthchecks.md diff --git a/docs/content/configuration/examples/_index.md b/docs/content/configuration/examples/_index.md deleted file mode 100644 index 1aedbf18..00000000 --- a/docs/content/configuration/examples/_index.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Examples" -weight: 40 -alwaysopen: false ---- - -So let's say you normally use this simple command: - -```shell -restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home -``` - -For resticprofile to generate this command automatically for you, here's the configuration file: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -# indentation is not needed but it makes it easier to read ;) -# -version = "1" - -[default] - repository = "local:/backup" - password-file = "password.txt" - - [default.backup] - verbose = true - source = [ "/home" ] -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -default: - repository: "local:/backup" - password-file: "password.txt" - - backup: - verbose: true - source: - - "/home" -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -default { - repository = "local:/backup" - password-file = "password.txt" - - backup = { - verbose = true - source = [ "/home" ] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "default": { - "repository": "local:/backup", - "password-file": "password.txt", - "backup": { - "verbose": true, - "source": [ - "/home" - ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -You may have noticed the `source` flag is accepting an array of values (inside brackets in TOML, list of values in YAML) - -Now, assuming this configuration file is named `profiles.conf` in the current folder (it's the default config file name), you can simply run - -```shell -resticprofile backup -``` - -and resticprofile will do its magic and generate the command line for you. - -If you have any doubt on what it's running, you can try a `--dry-run`: - -```shell -resticprofile --dry-run backup -2022/05/18 17:14:07 profile 'default': starting 'backup' -2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home -2022/05/18 17:14:07 profile 'default': finished 'backup' -``` - -## More Examples - -{{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/hooks/http_hooks.md b/docs/content/configuration/hooks/http_hooks.md index 9f497d92..4448d2fd 100644 --- a/docs/content/configuration/hooks/http_hooks.md +++ b/docs/content/configuration/hooks/http_hooks.md @@ -4,6 +4,8 @@ weight: 22 tags: [ "monitoring", "healthchecks.io" ] --- +{{< toc >}} + ## Send HTTP messages before and after a job As well as being able to run [shell commands]({{% relref "run_hooks" %}}), you can now send HTTP messages before, after (success or failure) running a restic command. @@ -38,257 +40,6 @@ The configuration is the same for each of these 4 types of hooks: | body-template | No | None | Template file to generate the body (in go template format) | -### Example sending monitoring information to healthchecks.io: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[profile] - - [profile.backup] - source = "/source" - exclude = [ "/**/.git/" ] - schedule = [ "*:00,30" ] - schedule-permission = "user" - - # you can have more than one target - - [[profile.backup.send-before]] - method = "HEAD" - url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" - - [[profile.backup.send-before]] - method = "HEAD" - url = "https://httpstat.us/400" - - # you can have more than one target - - [[profile.backup.send-after]] - method = "HEAD" - url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" - - [[profile.backup.send-after]] - method = "HEAD" - url = "https://httpstat.us/500" - - [profile.backup.send-after-fail] - method = "POST" - url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail" - body = "${ERROR}\n\n${ERROR_STDERR}" - - [[profile.backup.send-after-fail.headers]] - name = "Content-Type" - value = "text/plain; charset=UTF-8" - - [profile.check] - schedule = [ "*:15" ] - - [profile.check.send-before] - method = "HEAD" - url = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" - - [profile.check.send-after] - method = "HEAD" - url = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" - - [profile.retention] - after-backup = true - - -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -profile: - - backup: - source: "/source" - exclude: - - "/**/.git/" - schedule: - - "*:00,30" - schedule-permission: user - - # you can have more than one target - send-before: - - method: HEAD - url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start - - method: HEAD - url: https://httpstat.us/400 - - # you can have more than one target - send-after: - - method: HEAD - url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650 - - method: HEAD - url: https://httpstat.us/500 - - send-after-fail: - method: POST - url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail - body: "${ERROR}\n\n${ERROR_STDERR}" - headers: - - name: Content-Type - value: "text/plain; charset=UTF-8" - check: - schedule: - - "*:15" - - send-before: - method: HEAD - url: https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start - - send-after: - method: HEAD - url: https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc - - retention: - after-backup: true - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"profile" { - - "backup" = { - "source" = "/source" - "exclude" = ["/**/.git/"] - "schedule" = ["*:00,30"] - "schedule-permission" = "user" - - "send-before" = { - "method" = "HEAD" - "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" - } - - "send-before" = { - "method" = "HEAD" - "url" = "https://httpstat.us/400" - } - - "send-after" = { - "method" = "HEAD" - "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" - } - - "send-after" = { - "method" = "HEAD" - "url" = "https://httpstat.us/500" - } - - "send-after-fail" = { - "method" = "POST" - "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail" - "body" = "${ERROR}\n\n${ERROR_STDERR}" - "headers" = { - "name" = "Content-Type" - "value" = "text/plain; charset=UTF-8" - } - } - } - - "check" = { - "schedule" = ["*:15"] - - "send-before" = { - "method" = "HEAD" - "url" = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" - } - - "send-after" = { - "method" = "HEAD" - "url" = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" - } - } - - "retention" = { - "after-backup" = true - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "profile": { - "backup": { - "source": "/source", - "exclude": [ - "/**/.git/" - ], - "schedule": [ - "*:00,30" - ], - "schedule-permission": "user", - "send-before": [ - { - "method": "HEAD", - "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" - }, - { - "method": "HEAD", - "url": "https://httpstat.us/400" - } - ], - "send-after": [ - { - "method": "HEAD", - "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" - }, - { - "method": "HEAD", - "url": "https://httpstat.us/500" - } - ], - "send-after-fail": { - "method": "POST", - "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail", - "body": "${ERROR}\n\n${ERROR_STDERR}", - "headers": [ - { - "name": "Content-Type", - "value": "text/plain; charset=UTF-8" - } - ] - } - }, - "check": { - "schedule": [ - "*:15" - ], - "send-before": { - "method": "HEAD", - "url": "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" - }, - "send-after": { - "method": "HEAD", - "url": "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" - } - }, - "retention": { - "after-backup": true - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - A few environment variables will be available to construct the url and the body: - `PROFILE_NAME` - `PROFILE_COMMAND`: backup, check, forget, etc. @@ -305,35 +56,9 @@ The `send-finally` hooks are also getting the environment of `send-after-fail` w Failures in any `send-*` are logged but do not influence environment or return code. -### order of `send-*` - -Here's the flow of HTTP hooks: - -```mermaid -graph TD - LOCK(set resticprofile lock) - UNLOCK(delete resticprofile lock) - LOCK --> SB - SB('send-before') --> RUN - RUN(run restic command, or group of commands) - RUN -->|Success| SA - RUN -->|Error| SAF - SA('send-after') --> SF - SAF('send-after-fail') --> SF - SF('send-finally') - SF --> UNLOCK -``` - -{{% notice style="warning" title="resticprofile lock" %}} -The local resticprofile lock is surrounding the whole process. It means that the `run-after-fail` target is not called if the lock cannot be obtained. This is a limitation of the current implementation. -{{% /notice %}} - +## body-template -### body-template - -You can use a standard go template to build the webhook body. It has to be defined in a separate file (otherwise it would clash with the configuration as a go template itself). - -The object passed as an argument to the template is: +Templates pull from the standard go template to build the webhook body. The object passed as an argument to the template is: - `ProfileName` **string** - `ProfileCommand` **string** @@ -346,117 +71,7 @@ The type **ErrorContext** is available after an error occurred (otherwise all fi - `ExitCode` **string** - `Stderr` **string** -Here's an example of a body file: - - -```json -{ - "profileName": "{{ .ProfileName }}", - "profileCommand": "{{ .ProfileCommand }}", - "exitCode": "{{ .Error.ExitCode }}" -} -``` - -The field `exitCode` will be blank if no error occured. - -And here's an example of a configuration using a body template: - - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[profile] - - [profile.backup] - source = "/source" - - [profile.backup.send-finally] - method = "POST" - url = "https://my/monitoring.example.com/" - body-template = "body-template.json" - - [[profile.backup.send-finally.headers]] - name = "Content-Type" - value = "application/json" - -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -profile: - - backup: - source: "/source" - - send-finally: - method: POST - url: https://my/monitoring.example.com/ - body-template: body-template.json - headers: - - name: Content-Type - value: "application/json" - - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"profile" { - - "backup" = { - "source" = "/source" - - "send-finally" = { - "method" = "POST" - "url" = "https://my/monitoring.example.com/" - "body-template" = "body-template.json" - "headers" = { - "name" = "Content-Type" - "value" = "application/json" - } - } - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "profile": { - "backup": { - "source": "/source", - "send-finally": { - "method": "POST", - "url": "https://my/monitoring.example.com/", - "body-template": "body-template.json", - "headers": [ - { - "name": "Content-Type", - "value": "application/json" - } - ] - } - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -### Self-signed certificates +## Self-signed certificates If your monitoring system is using self-signed certificates, you can import them in resticprofile (and you don't need to rely on the `skip-tls-verification` flag) @@ -529,3 +144,26 @@ global { {{% /tab %}} {{< /tabs >}} + +## order of `send-*` + +Here's the flow of HTTP hooks: + +```mermaid +graph TD + LOCK(set resticprofile lock) + UNLOCK(delete resticprofile lock) + LOCK --> SB + SB('send-before') --> RUN + RUN(run restic command, or group of commands) + RUN -->|Success| SA + RUN -->|Error| SAF + SA('send-after') --> SF + SAF('send-after-fail') --> SF + SF('send-finally') + SF --> UNLOCK +``` + +{{% notice style="warning" title="resticprofile lock" %}} +The local resticprofile lock is surrounding the whole process. It means that the `run-after-fail` target is not called if the lock cannot be obtained. This is a limitation of the current implementation. +{{% /notice %}} diff --git a/docs/content/configuration/hooks/run_hooks.md b/docs/content/configuration/hooks/run_hooks.md index f17f1c18..c9c969df 100644 --- a/docs/content/configuration/hooks/run_hooks.md +++ b/docs/content/configuration/hooks/run_hooks.md @@ -4,6 +4,8 @@ weight: 20 tags: [ "monitoring" ] --- +{{< toc >}} + ## Run commands before, after success or after failure resticprofile has 2 places where you can run commands around restic: @@ -133,7 +135,7 @@ snapshot 3949d2fb saved == run-finally from profile documents after command backup ``` -### Order of `run-*` during a backup +## Order of `run-*` during a backup The commands will be running in this order **during a backup**: - `run-before` from the profile - if error, go to `run-after-fail` @@ -204,7 +206,7 @@ flowchart TB The local resticprofile lock is surrounding the whole process. It means that the `run-after-fail` target is not called if the lock cannot be obtained. This is a limitation of the current implementation. {{% /notice %}} -### Passing environment variables +## Passing environment variables Environment variables can be adjusted and passed between shell commands & restic by writing one or more `VARIABLE=VALUE` into an `env-file` that is configured within the current profile. To simplify this for shell commands, the [template]({{% relref "templates" %}}) function `{{env}}` can be used to get a temporary dotenv file that is automatically appended to the `env-file` list of the current profile and reloaded whenever modified. diff --git a/docs/content/configuration/monitoring/_index.md b/docs/content/configuration/monitoring/_index.md index 0cb5a5d0..6b757b6e 100644 --- a/docs/content/configuration/monitoring/_index.md +++ b/docs/content/configuration/monitoring/_index.md @@ -6,7 +6,9 @@ alwaysopen: false 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. +You can redirect the logs to a local file, [a temporary file]({{< relref "/configuration/monitoring/tempfilelogging" >}}) or a syslog server. + +{{< toc >}} ## Destination @@ -158,78 +160,3 @@ If specified in different places, here's the priority order for the log destinat 2. `schedule-log` in the `profile` section 3. `log` in the `global` section 4. default to the console - -## Send logs to a temporary file - -This can be done by using the [template]({{% relref "/configuration/profiles/templates" %}}) function `tempFile`. - -This is to cover a special case when you want to upload the logs one by one to a remote location in a `run-finally` or a `run-after-fail` target. - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[backup_current] - [backup_current.backup] - verbose = true - no-error-on-warning = true - source = "{{ .CurrentDir }}" - schedule = "*:44" - schedule-log = '{{ tempFile "backup.log" }}' - run-finally = 'cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log' -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -backup_current: - backup: - verbose: true - no-error-on-warning: true - source: "{{ .CurrentDir }}" - schedule: - - "*:44" - schedule-log: '{{ tempFile "backup.log" }}' - run-finally: 'cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log' -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"profile" "backup" { - "verbose" = true - "no-error-on-warning" = true - "source" = "{{ .CurrentDir }}" - "schedule" = "*:44" - "schedule-log" = "{{ tempFile "backup.log" }}" - "run-finally" = "cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log" -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "profile": { - "backup": { - "verbose": true, - "no-error-on-warning": true, - "source": "{{ .CurrentDir }}", - "schedule": "*:44", - "schedule-log": "{{ tempFile "backup.log" }}", - "run-finally": "cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log" - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} diff --git a/docs/content/configuration/monitoring/prometheus.md b/docs/content/configuration/monitoring/prometheus.md index 8291b7e0..bbb8e68a 100644 --- a/docs/content/configuration/monitoring/prometheus.md +++ b/docs/content/configuration/monitoring/prometheus.md @@ -1,7 +1,7 @@ --- title: "Monitoring - Prometheus" slug: prometheus -weight: 10 +weight: 51 tags: [ "monitoring" ] --- diff --git a/docs/content/configuration/monitoring/status.md b/docs/content/configuration/monitoring/status.md index cd56b4df..42ad8d7d 100644 --- a/docs/content/configuration/monitoring/status.md +++ b/docs/content/configuration/monitoring/status.md @@ -1,7 +1,7 @@ --- title: "Monitoring - Status file" slug: status -weight: 11 +weight: 52 tags: [ "monitoring" ] aliases: - /status diff --git a/docs/content/configuration/monitoring/tempfilelogging.md b/docs/content/configuration/monitoring/tempfilelogging.md new file mode 100644 index 00000000..430e5d81 --- /dev/null +++ b/docs/content/configuration/monitoring/tempfilelogging.md @@ -0,0 +1,77 @@ +--- +title: "Monitoring - Temporary File" +weight: 53 +--- + +This can be done by using the [template]({{% relref "/configuration/profiles/templates" %}}) function `tempFile`. + +This is to cover a special case when you want to upload the logs one by one to a remote location in a `run-finally` or a `run-after-fail` target. + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[backup_current] + [backup_current.backup] + verbose = true + no-error-on-warning = true + source = "{{ .CurrentDir }}" + schedule = "*:44" + schedule-log = '{{ tempFile "backup.log" }}' + run-finally = 'cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log' +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +backup_current: + backup: + verbose: true + no-error-on-warning: true + source: "{{ .CurrentDir }}" + schedule: + - "*:44" + schedule-log: '{{ tempFile "backup.log" }}' + run-finally: 'cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log' +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"profile" "backup" { + "verbose" = true + "no-error-on-warning" = true + "source" = "{{ .CurrentDir }}" + "schedule" = "*:44" + "schedule-log" = "{{ tempFile "backup.log" }}" + "run-finally" = "cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log" +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "profile": { + "backup": { + "verbose": true, + "no-error-on-warning": true, + "source": "{{ .CurrentDir }}", + "schedule": "*:44", + "schedule-log": "{{ tempFile "backup.log" }}", + "run-finally": "cp {{ tempFile "backup.log" }} /logs/backup{{ .Now.Format "2006-01-02T15-04-05" }}.log" + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/configuration/monitoring/warnings.md b/docs/content/configuration/monitoring/warnings.md index 8bfe1675..4a5ab4b2 100644 --- a/docs/content/configuration/monitoring/warnings.md +++ b/docs/content/configuration/monitoring/warnings.md @@ -1,6 +1,6 @@ --- title: "Warnings" -weight: 30 +weight: 54 --- ## Warnings from restic @@ -64,4 +64,4 @@ profile: ``` {{% /tab %}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} diff --git a/docs/content/configuration/profiles/_index.md b/docs/content/configuration/profiles/_index.md index f42ecc30..6c30ef5d 100644 --- a/docs/content/configuration/profiles/_index.md +++ b/docs/content/configuration/profiles/_index.md @@ -18,9 +18,9 @@ JSON is suitable for auto-generated configurations but is not the easiest format HCL can be useful if you already use a tool from the Hashicorp stack; otherwise, it's another format to learn. -## Configure Your Text Editor +## Debugging your template and variable expansion -A guide on configurating your text editor can be found [here]({{% relref "editorConfig.md" %}}). +If for some reason you don't understand why resticprofile is not loading your configuration file, you can display the generated configuration after executing the template (and replacing the variables and everything) using the `--trace` flag. ## More Information diff --git a/docs/content/configuration/profiles/templates.md b/docs/content/configuration/profiles/templates.md index 5b1164f4..7cd5bcfc 100644 --- a/docs/content/configuration/profiles/templates.md +++ b/docs/content/configuration/profiles/templates.md @@ -410,10 +410,6 @@ azure-mysql: {{< /tabs >}} -## Debugging your template and variable expansion - -If for some reason you don't understand why resticprofile is not loading your configuration file, you can display the generated configuration after executing the template (and replacing the variables and everything) using the `--trace` flag. We will see it in action in a moment. - ## Limitations of using templates There's something to be aware of when dealing with templates: at the time the template is compiled, it has no knowledge of what the end configuration should look like: it has no knowledge of profiles for example. Here is a **non-working** example of what I mean: diff --git a/docs/content/configuration/schedules/commands.md b/docs/content/configuration/schedules/commands.md index c4993e94..aed6ac73 100644 --- a/docs/content/configuration/schedules/commands.md +++ b/docs/content/configuration/schedules/commands.md @@ -3,6 +3,8 @@ title: "Schedule Commands" weight: 20 --- +{{< toc >}} + resticprofile supports the following commands: - **schedule** - **unschedule** @@ -57,7 +59,7 @@ Starting with `v0.30.0`, the behavior of the `unschedule` command changed: Print the status of all installed schedules for the selected profiles. -The `status` command output varies by OS. See the [examples]({{% relref "/configuration/schedules/examples" %}}) for details. +The `status` command output varies by OS. See the [examples]({{% relref "/usage/examples/scheduling-examples" %}}) for details. ### run-schedule command diff --git a/docs/content/configuration/schedules/configuration.md b/docs/content/configuration/schedules/configuration.md index 04af2472..74cc9e45 100644 --- a/docs/content/configuration/schedules/configuration.md +++ b/docs/content/configuration/schedules/configuration.md @@ -3,6 +3,7 @@ title: "Schedule Configuration" weight: 10 --- +{{< toc >}} The schedule configuration includes several parameters that can be added to each profile: @@ -81,15 +82,9 @@ profile: * *empty*: resticprofile will guess based on how it was started (with sudo or as a normal user). The fallback is `system` on Windows and `user_logged_on` on other platforms. -### Changing schedule-permission - -To change the permission of a schedule, unschedule the profile first. - -Follow this order: - -- Unschedule the job first (before updating the permission in the configuration) -- Change your permission (user to system, or system to user). -- Schedule your updated profile. +{{% notice style="warning" %}} +After changing this setting, you must update the schedule. More information can be found under [Changing Schedule Permissions]({{% relref "/usage/change-schedule" %}}) +{{% /notice %}} ## schedule-run-level @@ -201,128 +196,16 @@ Note: It works only on Windows and makes sense only with `user_logged_on` permis Note: The behavior of `conhost.exe` varies between Windows versions. It has been confirmed to work on Windows 11 (24H2) but not on Windows 10 (1607). -## Example - -Here's an example of a scheduling configuration: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -[default] - repository = "d:\\backup" - password-file = "key" - -[self] - inherit = "default" - - [self.retention] - after-backup = true - keep-within = "14d" - - [self.backup] - source = "." - schedule = [ "Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00" ] - schedule-permission = "user" - schedule-lock-wait = "10m" - - [self.prune] - schedule = "sun 3:30" - schedule-permission = "user" - schedule-lock-wait = "1h" -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -default: - repository: "d:\\backup" - password-file: key - -self: - inherit: default - retention: - after-backup: true - keep-within: 14d - backup: - source: "." - schedule: - - "Mon..Fri *:00,15,30,45" # every 15 minutes on weekdays - - "Sat,Sun 0,12:00" # twice a day on week-ends - schedule-permission: user - schedule-lock-wait: 10m - prune: - schedule: "sun 3:30" - schedule-permission: user - schedule-lock-wait: 1h -``` +## Preventing System Sleep -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"default" = { - "repository" = "d:\\backup" - "password-file" = "key" -} +This feature is available for: +- macOS +- Windows +- Linux with systemd ([logind](https://www.freedesktop.org/software/systemd/man/systemd-logind.service.html)) -"self" = { - "inherit" = "default" +There's a `global` parameter called `prevent-sleep` that you can set to `true`, and resticprofile will prevent your system from idle sleeping. - "retention" = { - "after-backup" = true - "keep-within" = "14d" - } - - "backup" = { - "source" = "." - "schedule" = ["Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00"] - "schedule-permission" = "user" - "schedule-lock-wait" = "10m" - } - - "prune" = { - "schedule" = "sun 3:30" - "schedule-permission" = "user" - "schedule-lock-wait" = "1h" - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "default": { - "repository": "d:\\backup", - "password-file": "key" - }, - "self": { - "inherit": "default", - "retention": { - "after-backup": true, - "keep-within": "14d" - }, - "backup": { - "source": ".", - "schedule": [ - "Mon..Fri *:00,15,30,45", - "Sat,Sun 0,12:00" - ], - "schedule-permission": "user", - "schedule-lock-wait": "10m" - }, - "prune": { - "schedule": "sun 3:30", - "schedule-permission": "user", - "schedule-lock-wait": "1h" - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} +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. diff --git a/docs/content/configuration/schedules/sleep.md b/docs/content/configuration/schedules/sleep.md deleted file mode 100644 index 1bcc114f..00000000 --- a/docs/content/configuration/schedules/sleep.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Preventing system sleep" -weight: 40 ---- - -This feature is available for: -- macOS -- Windows -- Linux with systemd ([logind](https://www.freedesktop.org/software/systemd/man/systemd-logind.service.html)) - -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. diff --git a/docs/content/faq.md b/docs/content/faq.md index 61510d6b..c63787d7 100644 --- a/docs/content/faq.md +++ b/docs/content/faq.md @@ -30,3 +30,9 @@ Homebrew appears to need access to a compiler. If the installation fails, you ma There's an example in the contribution section how to schedule backups in a long running container. The configuration needs to specify `crond` as a scheduler. + +## Usage + +### How do I prevent my system from going into sleep mode? + +Please refer to [preventing system sleep]({{% relref "/configuration/schedules/configuration/#preventing-system-sleep" %}}). diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index 102eda12..e328c92a 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -34,5 +34,5 @@ Here is a non-exhaustive list of what resticprofile offers: * **Misc** * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/examples/keyfile" %}}) * Automatically [initialize the secondary repository]({{% relref "/configuration/hooks/copy" %}}) using the `copy-chunker-params` flag - * Prevent the system from [idle sleeping]({{% relref "/configuration/schedules/sleep" %}}) + * Prevent the system from [idle sleeping]({{% relref "/configuration/schedules/configuration/#preventing-system-sleep" %}}) * View help for both restic and resticprofile via the `help` command or `-h` flag diff --git a/docs/content/usage/change-schedule.md b/docs/content/usage/change-schedule.md new file mode 100644 index 00000000..b104da2a --- /dev/null +++ b/docs/content/usage/change-schedule.md @@ -0,0 +1,11 @@ +--- +title: Changing Schedule Permission +--- + +When you update the `schedule-permission` field, you **must** unschedule and reschedule the profile to implement the change. + +To make this change, follow these steps: + +- Unschedule the job first (before updating the permission in the configuration) +- Change your permission (user to system, or system to user). +- Schedule your updated profile. diff --git a/docs/content/usage/examples/_index.md b/docs/content/usage/examples/_index.md index 7ee30235..1aedbf18 100644 --- a/docs/content/usage/examples/_index.md +++ b/docs/content/usage/examples/_index.md @@ -1,61 +1,107 @@ --- -title: Examples -weight: 20 +title: "Examples" +weight: 40 +alwaysopen: false --- -Here are a few examples how to run resticprofile (using the main example configuration file) - -### See all snapshots of your `default` profile: +So let's say you normally use this simple command: ```shell -resticprofile +restic --repo "local:/backup" --password-file "password.txt" --verbose backup /home ``` -### See all available profiles in your configuration file (and the restic commands where some flags are defined): +For resticprofile to generate this command automatically for you, here's the configuration file: -```shell -resticprofile profiles +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} -Profiles available (name, sections, description): - root: (backup, copy, forget, retention) - self: (backup, check, copy, forget, retention) - src: (backup, copy, retention, snapshots) +```toml +# indentation is not needed but it makes it easier to read ;) +# +version = "1" -Groups available (name, profiles, description): - full-backup: [root, src] +[default] + repository = "local:/backup" + password-file = "password.txt" + [default.backup] + verbose = true + source = [ "/home" ] ``` -### Backup root & src profiles (using _full-backup_ group shown earlier) +{{% /tab %}} +{{% tab title="yaml" %}} -```shell -resticprofile --name "full-backup" backup -``` -or using the alternative syntax: +```yaml +version: "1" -```shell -resticprofile full-backup.backup +default: + repository: "local:/backup" + password-file: "password.txt" + + backup: + verbose: true + source: + - "/home" ``` -Assuming the _stdin_ profile from the configuration file shown before, the command to send a mysqldump to the backup is as simple as: +{{% /tab %}} +{{% tab title="hcl" %}} -```shell -mysqldump --all-databases --order-by-primary | resticprofile --name stdin backup +```hcl +default { + repository = "local:/backup" + password-file = "password.txt" + + backup = { + verbose = true + source = [ "/home" ] + } +} ``` -or using the alternative syntax: -```shell -mysqldump --all-databases --order-by-primary | resticprofile stdin.backup +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "default": { + "repository": "local:/backup", + "password-file": "password.txt", + "backup": { + "verbose": true, + "source": [ + "/home" + ] + } + } +} ``` -### Mount the default profile (_default_) in /mnt/restic: +{{% /tab %}} +{{< /tabs >}} + + +You may have noticed the `source` flag is accepting an array of values (inside brackets in TOML, list of values in YAML) + +Now, assuming this configuration file is named `profiles.conf` in the current folder (it's the default config file name), you can simply run ```shell -resticprofile mount /mnt/restic +resticprofile backup ``` -### Display quick help +and resticprofile will do its magic and generate the command line for you. + +If you have any doubt on what it's running, you can try a `--dry-run`: ```shell -resticprofile --help +resticprofile --dry-run backup +2022/05/18 17:14:07 profile 'default': starting 'backup' +2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home +2022/05/18 17:14:07 profile 'default': finished 'backup' ``` + +## More Examples + +{{% children sort="weight" depth="2" %}} diff --git a/docs/content/configuration/examples/azure-storage.md b/docs/content/usage/examples/azure-storage.md similarity index 100% rename from docs/content/configuration/examples/azure-storage.md rename to docs/content/usage/examples/azure-storage.md diff --git a/docs/content/configuration/examples/configWindows.md b/docs/content/usage/examples/configWindows.md similarity index 100% rename from docs/content/configuration/examples/configWindows.md rename to docs/content/usage/examples/configWindows.md diff --git a/docs/content/configuration/examples/configWinheritence.md b/docs/content/usage/examples/configWinheritence.md similarity index 100% rename from docs/content/configuration/examples/configWinheritence.md rename to docs/content/usage/examples/configWinheritence.md diff --git a/docs/content/configuration/schedules/examples.md b/docs/content/usage/examples/scheduling-examples.md similarity index 85% rename from docs/content/configuration/schedules/examples.md rename to docs/content/usage/examples/scheduling-examples.md index 6dbf7947..513b508d 100644 --- a/docs/content/configuration/schedules/examples.md +++ b/docs/content/usage/examples/scheduling-examples.md @@ -3,6 +3,130 @@ title: "Schedule Examples" weight: 30 --- +## Example + +Here's an example of a scheduling configuration: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +[default] + repository = "d:\\backup" + password-file = "key" + +[self] + inherit = "default" + + [self.retention] + after-backup = true + keep-within = "14d" + + [self.backup] + source = "." + schedule = [ "Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00" ] + schedule-permission = "user" + schedule-lock-wait = "10m" + + [self.prune] + schedule = "sun 3:30" + schedule-permission = "user" + schedule-lock-wait = "1h" +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +default: + repository: "d:\\backup" + password-file: key + +self: + inherit: default + retention: + after-backup: true + keep-within: 14d + backup: + source: "." + schedule: + - "Mon..Fri *:00,15,30,45" # every 15 minutes on weekdays + - "Sat,Sun 0,12:00" # twice a day on week-ends + schedule-permission: user + schedule-lock-wait: 10m + prune: + schedule: "sun 3:30" + schedule-permission: user + schedule-lock-wait: 1h +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"default" = { + "repository" = "d:\\backup" + "password-file" = "key" +} + +"self" = { + "inherit" = "default" + + "retention" = { + "after-backup" = true + "keep-within" = "14d" + } + + "backup" = { + "source" = "." + "schedule" = ["Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00"] + "schedule-permission" = "user" + "schedule-lock-wait" = "10m" + } + + "prune" = { + "schedule" = "sun 3:30" + "schedule-permission" = "user" + "schedule-lock-wait" = "1h" + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "default": { + "repository": "d:\\backup", + "password-file": "key" + }, + "self": { + "inherit": "default", + "retention": { + "after-backup": true, + "keep-within": "14d" + }, + "backup": { + "source": ".", + "schedule": [ + "Mon..Fri *:00,15,30,45", + "Sat,Sun 0,12:00" + ], + "schedule-permission": "user", + "schedule-lock-wait": "10m" + }, + "prune": { + "schedule": "sun 3:30", + "schedule-permission": "user", + "schedule-lock-wait": "1h" + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} ### Examples of scheduling commands under Windows diff --git a/docs/content/configuration/examples/stdin.md b/docs/content/usage/examples/stdin.md similarity index 100% rename from docs/content/configuration/examples/stdin.md rename to docs/content/usage/examples/stdin.md diff --git a/docs/content/configuration/getting_started.md b/docs/content/usage/getting_started.md similarity index 98% rename from docs/content/configuration/getting_started.md rename to docs/content/usage/getting_started.md index fc08751c..f0fcd883 100644 --- a/docs/content/configuration/getting_started.md +++ b/docs/content/usage/getting_started.md @@ -4,6 +4,8 @@ weight: 10 alwaysopen: false --- +{{< toc >}} + ## Prerequisite Unless you're using the **resticprofile** [Docker image]({{% relref "/installation/docker/index.html" %}}), you need to have **restic** [installed on your machine](https://restic.readthedocs.io/en/stable/). @@ -331,7 +333,3 @@ Flags: [...] ``` - -## Next - -Let's have a look at some [examples]({{% relref "/configuration/examples" %}}) diff --git a/docs/content/usage/hooks/body-template.md b/docs/content/usage/hooks/body-template.md new file mode 100644 index 00000000..d446c81b --- /dev/null +++ b/docs/content/usage/hooks/body-template.md @@ -0,0 +1,115 @@ +--- +title: "Message Body Template" +--- + +You can use a standard go template to build the webhook body. It has to be defined in a separate file (otherwise it would clash with the configuration as a go template itself). + +More information can be found under [Hooks - HTTP Hooks]({{% relref "configuration/hooks/http_hooks/#body-template" %}}) + + +```json +{ + "profileName": "{{ .ProfileName }}", + "profileCommand": "{{ .ProfileCommand }}", + "exitCode": "{{ .Error.ExitCode }}" +} +``` + +The field `exitCode` will be blank if no error occured. + +And here's an example of a configuration using a body template: + + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[profile] + + [profile.backup] + source = "/source" + + [profile.backup.send-finally] + method = "POST" + url = "https://my/monitoring.example.com/" + body-template = "body-template.json" + + [[profile.backup.send-finally.headers]] + name = "Content-Type" + value = "application/json" + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +profile: + + backup: + source: "/source" + + send-finally: + method: POST + url: https://my/monitoring.example.com/ + body-template: body-template.json + headers: + - name: Content-Type + value: "application/json" + + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"profile" { + + "backup" = { + "source" = "/source" + + "send-finally" = { + "method" = "POST" + "url" = "https://my/monitoring.example.com/" + "body-template" = "body-template.json" + "headers" = { + "name" = "Content-Type" + "value" = "application/json" + } + } + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "profile": { + "backup": { + "source": "/source", + "send-finally": { + "method": "POST", + "url": "https://my/monitoring.example.com/", + "body-template": "body-template.json", + "headers": [ + { + "name": "Content-Type", + "value": "application/json" + } + ] + } + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} diff --git a/docs/content/usage/hooks/healthchecks.md b/docs/content/usage/hooks/healthchecks.md new file mode 100644 index 00000000..0a4ae1db --- /dev/null +++ b/docs/content/usage/hooks/healthchecks.md @@ -0,0 +1,254 @@ +--- +title: "Sending to healthchecks.io" +--- + +For more information, refer to [Hooks - HTTP]({{% relref "configuration/hooks/http_hooks/#send-http-messages-before-and-after-a-job" %}}) + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[profile] + + [profile.backup] + source = "/source" + exclude = [ "/**/.git/" ] + schedule = [ "*:00,30" ] + schedule-permission = "user" + + # you can have more than one target + + [[profile.backup.send-before]] + method = "HEAD" + url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" + + [[profile.backup.send-before]] + method = "HEAD" + url = "https://httpstat.us/400" + + # you can have more than one target + + [[profile.backup.send-after]] + method = "HEAD" + url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" + + [[profile.backup.send-after]] + method = "HEAD" + url = "https://httpstat.us/500" + + [profile.backup.send-after-fail] + method = "POST" + url = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail" + body = "${ERROR}\n\n${ERROR_STDERR}" + + [[profile.backup.send-after-fail.headers]] + name = "Content-Type" + value = "text/plain; charset=UTF-8" + + [profile.check] + schedule = [ "*:15" ] + + [profile.check.send-before] + method = "HEAD" + url = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" + + [profile.check.send-after] + method = "HEAD" + url = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" + + [profile.retention] + after-backup = true + + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +profile: + + backup: + source: "/source" + exclude: + - "/**/.git/" + schedule: + - "*:00,30" + schedule-permission: user + + # you can have more than one target + send-before: + - method: HEAD + url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start + - method: HEAD + url: https://httpstat.us/400 + + # you can have more than one target + send-after: + - method: HEAD + url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650 + - method: HEAD + url: https://httpstat.us/500 + + send-after-fail: + method: POST + url: https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail + body: "${ERROR}\n\n${ERROR_STDERR}" + headers: + - name: Content-Type + value: "text/plain; charset=UTF-8" + check: + schedule: + - "*:15" + + send-before: + method: HEAD + url: https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start + + send-after: + method: HEAD + url: https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc + + retention: + after-backup: true + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"profile" { + + "backup" = { + "source" = "/source" + "exclude" = ["/**/.git/"] + "schedule" = ["*:00,30"] + "schedule-permission" = "user" + + "send-before" = { + "method" = "HEAD" + "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" + } + + "send-before" = { + "method" = "HEAD" + "url" = "https://httpstat.us/400" + } + + "send-after" = { + "method" = "HEAD" + "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" + } + + "send-after" = { + "method" = "HEAD" + "url" = "https://httpstat.us/500" + } + + "send-after-fail" = { + "method" = "POST" + "url" = "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail" + "body" = "${ERROR}\n\n${ERROR_STDERR}" + "headers" = { + "name" = "Content-Type" + "value" = "text/plain; charset=UTF-8" + } + } + } + + "check" = { + "schedule" = ["*:15"] + + "send-before" = { + "method" = "HEAD" + "url" = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" + } + + "send-after" = { + "method" = "HEAD" + "url" = "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" + } + } + + "retention" = { + "after-backup" = true + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "profile": { + "backup": { + "source": "/source", + "exclude": [ + "/**/.git/" + ], + "schedule": [ + "*:00,30" + ], + "schedule-permission": "user", + "send-before": [ + { + "method": "HEAD", + "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/start" + }, + { + "method": "HEAD", + "url": "https://httpstat.us/400" + } + ], + "send-after": [ + { + "method": "HEAD", + "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650" + }, + { + "method": "HEAD", + "url": "https://httpstat.us/500" + } + ], + "send-after-fail": { + "method": "POST", + "url": "https://hc-ping.com/831e288e-1293-46f8-ac31-70ea7f875650/fail", + "body": "${ERROR}\n\n${ERROR_STDERR}", + "headers": [ + { + "name": "Content-Type", + "value": "text/plain; charset=UTF-8" + } + ] + } + }, + "check": { + "schedule": [ + "*:15" + ], + "send-before": { + "method": "HEAD", + "url": "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc/start" + }, + "send-after": { + "method": "HEAD", + "url": "https://hc-ping.com/e0f62e41-b75f-450f-8cdd-7f25e466d2dc" + } + }, + "retention": { + "after-backup": true + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + From 1fcf0e0072155693a08e8b2b11e605260cf43ecc Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 12:36:33 -0500 Subject: [PATCH 26/29] Updating the configuration variable doc to be its own section --- docs/content/changelog.md | 2 +- docs/content/configuration/_index.md | 4 +- .../configuration/monitoring/_index.md | 2 +- .../monitoring/tempfilelogging.md | 2 +- .../content/configuration/profiles/include.md | 2 +- .../configuration/profiles/inheritance.md | 4 +- .../configuration/profiles/variables.md | 596 ------------------ .../content/configuration/variables/_index.md | 119 ++++ .../variables}/env_vars.md | 24 +- .../{profiles => variables}/templates.md | 0 docs/content/contributions/_index.md | 2 +- docs/content/features/_index.md | 2 +- docs/content/usage/_index.md | 4 +- docs/content/usage/cmdline_ref.md | 42 -- docs/content/usage/hooks/_index.md | 5 + docs/content/usage/variable-example.md | 189 ++++++ docs/content/usage/variables.md | 282 +++++++++ 17 files changed, 630 insertions(+), 651 deletions(-) delete mode 100644 docs/content/configuration/profiles/variables.md create mode 100644 docs/content/configuration/variables/_index.md rename docs/content/{usage => configuration/variables}/env_vars.md (54%) rename docs/content/configuration/{profiles => variables}/templates.md (100%) delete mode 100644 docs/content/usage/cmdline_ref.md create mode 100644 docs/content/usage/hooks/_index.md create mode 100644 docs/content/usage/variable-example.md create mode 100644 docs/content/usage/variables.md diff --git a/docs/content/changelog.md b/docs/content/changelog.md index 7a0e40f0..d79ba579 100644 --- a/docs/content/changelog.md +++ b/docs/content/changelog.md @@ -1,6 +1,6 @@ --- archetype: chapter -pre: 6. +pre: 7. title: Release Notes weight: 8 --- diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md index 73215d42..dbd8de4d 100644 --- a/docs/content/configuration/_index.md +++ b/docs/content/configuration/_index.md @@ -1,8 +1,8 @@ +++ archetype = "chapter" -pre = "2. " +pre = "3. " title = "Configuration file" -weight = 2 +weight = 3 +++ The configuration file supports various formats: diff --git a/docs/content/configuration/monitoring/_index.md b/docs/content/configuration/monitoring/_index.md index 6b757b6e..b03117a6 100644 --- a/docs/content/configuration/monitoring/_index.md +++ b/docs/content/configuration/monitoring/_index.md @@ -6,7 +6,7 @@ alwaysopen: false 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]({{< relref "/configuration/monitoring/tempfilelogging" >}}) or a syslog server. +You can redirect the logs to a local file, [a temporary file]({{% relref "/configuration/monitoring/tempfilelogging" %}}) or a syslog server. {{< toc >}} diff --git a/docs/content/configuration/monitoring/tempfilelogging.md b/docs/content/configuration/monitoring/tempfilelogging.md index 430e5d81..51db561f 100644 --- a/docs/content/configuration/monitoring/tempfilelogging.md +++ b/docs/content/configuration/monitoring/tempfilelogging.md @@ -3,7 +3,7 @@ title: "Monitoring - Temporary File" weight: 53 --- -This can be done by using the [template]({{% relref "/configuration/profiles/templates" %}}) function `tempFile`. +This can be done by using the [template]({{% relref "/configuration/variables/templates" %}}) function `tempFile`. This is to cover a special case when you want to upload the logs one by one to a remote location in a `run-finally` or a `run-after-fail` target. diff --git a/docs/content/configuration/profiles/include.md b/docs/content/configuration/profiles/include.md index a2654314..92609ddb 100644 --- a/docs/content/configuration/profiles/include.md +++ b/docs/content/configuration/profiles/include.md @@ -81,7 +81,7 @@ Included files cannot include nested files. Specifying `includes` inside an incl ## Configuration Merging -Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/profiles/variables" %}}) and [templates]({{% relref "/configuration/profiles/templates" %}}) prior to parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`. This means [variables]({{% relref "/configuration/profiles/variables" %}}) and [templates]({{% relref "/configuration/profiles/templates" %}}) must create valid configuration markup that can be parsed or loading will fail. +Loading a configuration file involves loading the physical file from disk and applying all [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/variables/templates" %}}) prior to parsing the file in a supported format `hcl`, `json`, `toml` and `yaml`. This means [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/variables/templates" %}}) must create valid configuration markup that can be parsed or loading will fail. Configuration files are loaded and applied in a fixed order: diff --git a/docs/content/configuration/profiles/inheritance.md b/docs/content/configuration/profiles/inheritance.md index 51e1cbc0..ec9c866c 100644 --- a/docs/content/configuration/profiles/inheritance.md +++ b/docs/content/configuration/profiles/inheritance.md @@ -191,9 +191,9 @@ Mixins offer an easy way to share pieces of configuration between profiles witho Mixins are declared in section `mixins` as named objects. The contents of these objects are merged into the profile configuration wherever a `use` property references (uses) the mixin. Configuration merging is following the same logic as used in [inheritance](#profile-inheritance) and [includes]({{% relref "/configuration/profiles/include/index.html#configuration-merging" %}}). When `use` references multiple mixins, the mixins apply in the order they are referenced and can override each other (mixins referenced later override what earlier mixins defined). -Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/profiles/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged and for this reason the syntax differs. +Configuration values inside a mixin may be parametrized with variables following the syntax `${variable}` or `$variable`. Defaults for variables can be defined inside the mixin with `default-vars` and `use` can specify variables before merging the mixin. In difference to configuration [variables]({{% relref "/configuration/variables" %}}) that expand prior to parsing, mixin variables expand when the mixin is merged and for this reason the syntax differs. -Unlike configuration [variables]({{% relref "/configuration/profiles/variables" %}}) and [templates]({{% relref "/configuration/profiles/templates" %}}), mixins create parsed configuration structure not config markup that requires parsing. This allows mixins to be defined in one supported config format (`yaml`, `toml`, `json`) while being used in any other supported format when the configuration is split into multiple [includes]({{% relref "/configuration/profiles/include/index.html#configuration-merging" %}}). +Unlike configuration [variables]({{% relref "/configuration/variables" %}}) and [templates]({{% relref "/configuration/variables/templates" %}}), mixins create parsed configuration structure not config markup that requires parsing. This allows mixins to be defined in one supported config format (`yaml`, `toml`, `json`) while being used in any other supported format when the configuration is split into multiple [includes]({{% relref "/configuration/profiles/include/index.html#configuration-merging" %}}). {{< tabs groupid="config-with-mixins" >}} {{% tab title="yaml" %}} diff --git a/docs/content/configuration/profiles/variables.md b/docs/content/configuration/profiles/variables.md deleted file mode 100644 index 603211f3..00000000 --- a/docs/content/configuration/profiles/variables.md +++ /dev/null @@ -1,596 +0,0 @@ ---- -title: "Variables" -weight: 26 ---- - -## 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]({{% relref "/configuration/profiles/include" %}}) are loaded, and [inheritance]({{% relref "/configuration/profiles/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: - -``` -{{ .VariableName }} -``` - -The list of pre-defined variables is: - -| Variable | Type | Description | -|-------------------|--------------------------------------------------|------------------------------------------------------------------| -| **.Profile.Name** | string | Profile name | -| **.Now** | [time.Time](https://golang.org/pkg/time/) object | Now object: see explanation bellow | -| **.StartupDir** | string | Current directory at the time resticprofile was started | -| **.CurrentDir** | string | Current directory at the time a profile is executed | -| **.ConfigDir** | string | Directory where the configuration was loaded from | -| **.TempDir** | string | OS temporary directory (might not exist) | -| **.BinaryDir** | string | Directory where resticprofile was started from (since `v0.18.0`) | -| **.OS** | string | GOOS name: "windows", "linux", "darwin", etc. (since `v0.21.0`) | -| **.Arch** | string | GOARCH name: "386", "amd64", "arm64", etc. (since `v0.21.0`) | -| **.Hostname** | string | Host name | -| **.Env.{NAME}** | string | Environment variable `${NAME}` | - -Environment variables are accessible using `.Env.` followed by the (upper case) name of the environment variable. - -Example: `{{ .Env.HOME }}` will be replaced by your home directory (on unixes). The equivalent on Windows would be `{{ .Env.USERPROFILE }}`. - -Default and fallback values for an empty or unset variable can be declared with `{{ ... | or ... }}`. -For example `{{ .Env.HOME | or .Env.USERPROFILE | or "/fallback-homedir" }}` will try to resolve `$HOME`, if empty try to resolve `$USERPROFILE` -and finally default to `/fallback-homedir` if none of the env variables are defined. - -The variables `.OS` and `.Arch` are filled with the target platform that `resticprofile` was compiled for (see -[releases](https://github.com/creativeprojects/resticprofile/releases) for more information on existing precompiled platform binaries). - -For variables that are objects, you can call all public fields or methods on it. -For example, for the variable `.Now` ([time.Time](https://golang.org/pkg/time/)) you can use: - -- `(.Now.AddDate years months days)` -- `.Now.Day` -- `.Now.Format layout` -- `.Now.Hour` -- `.Now.Minute` -- `.Now.Month` -- `.Now.Second` -- `.Now.UTC` -- `.Now.Unix` -- `.Now.Weekday` -- `.Now.Year` -- `.Now.YearDay` - -Time can be formatted with `.Now.Format layout`, for example `{{ .Now.Format "2006-01-02T15:04:05Z07:00" }}` formats the current time as RFC3339 timestamp. -Check [time.Time#constants](https://pkg.go.dev/time#pkg-constants) for more layout examples. - -The variable `.Now` also allows to derive a relative `Time`. For example `{{ (.Now.AddDate 0 -6 -14).Format "2006-01-02" }}` formats a date that -is 6 months and 14 days before now. - - -#### Example - -You can use a combination of inheritance and variables in the resticprofile configuration file like so: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[generic] - password-file = "{{ .ConfigDir }}/{{ .Profile.Name }}-key" - repository = "/backup/{{ .Now.Weekday }}" - lock = "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" - initialize = true - - [generic.backup] - check-before = true - exclude = [ "/**/.git" ] - exclude-caches = true - one-file-system = false - run-after = "echo All Done!" - run-before = [ - "echo Hello {{ .Env.LOGNAME }}", - "echo current dir: {{ .CurrentDir }}", - "echo config dir: {{ .ConfigDir }}", - "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" - ] - tag = [ "{{ .Profile.Name }}", "dev" ] - - [generic.retention] - after-backup = true - before-backup = false - compact = false - keep-within = "30d" - prune = true - tag = [ "{{ .Profile.Name }}", "dev" ] - - [generic.snapshots] - tag = [ "{{ .Profile.Name }}", "dev" ] - -[src] - inherit = "generic" - - [src.backup] - source = [ "{{ .Env.HOME }}/go/src" ] - - [src.check] - # Weekday is an integer from 0 to 6 (starting from Sunday) - # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 - read-data-subset = "{{ len (printf "a%*s" .Now.Weekday "") }}/7" - -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml ---- -version: "1" - -generic: - password-file: "{{ .ConfigDir }}/{{ .Profile.Name }}-key" - repository: "/backup/{{ .Now.Weekday }}" - lock: "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" - initialize: true - - backup: - check-before: true - exclude: - - /**/.git - exclude-caches: true - one-file-system: false - run-after: echo All Done! - run-before: - - "echo Hello {{ .Env.LOGNAME }}" - - "echo current dir: {{ .CurrentDir }}" - - "echo config dir: {{ .ConfigDir }}" - - "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" - tag: - - "{{ .Profile.Name }}" - - dev - - retention: - after-backup: true - before-backup: false - compact: false - keep-within: 30d - prune: true - tag: - - "{{ .Profile.Name }}" - - dev - - snapshots: - tag: - - "{{ .Profile.Name }}" - - dev - -src: - inherit: generic - - backup: - source: - - "{{ .Env.HOME }}/go/src" - - check: - # Weekday is an integer from 0 to 6 (starting from Sunday) - # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 - read-data-subset: "{{ len (printf "a%*s" .Now.Weekday "") }}/7" - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"generic" = { - "password-file" = "{{ .ConfigDir }}/{{ .Profile.Name }}-key" - "repository" = "/backup/{{ .Now.Weekday }}" - "lock" = "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" - "initialize" = true - - "backup" = { - "check-before" = true - "exclude" = ["/**/.git"] - "exclude-caches" = true - "one-file-system" = false - "run-after" = "echo All Done!" - "run-before" = ["echo Hello {{ .Env.LOGNAME }}", "echo current dir: {{ .CurrentDir }}", "echo config dir: {{ .ConfigDir }}", "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}"] - "tag" = ["{{ .Profile.Name }}", "dev"] - } - - "retention" = { - "after-backup" = true - "before-backup" = false - "compact" = false - "keep-within" = "30d" - "prune" = true - "tag" = ["{{ .Profile.Name }}", "dev"] - } - - "snapshots" = { - "tag" = ["{{ .Profile.Name }}", "dev"] - } -} - -"src" = { - "inherit" = "generic" - - "backup" = { - "source" = ["{{ .Env.HOME }}/go/src"] - } - - "check" = { - # Weekday is an integer from 0 to 6 (starting from Sunday) - # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 - "read-data-subset" = "{{ len (printf "a%*s" .Now.Weekday "") }}/7" - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "generic": { - "password-file": "{{ .ConfigDir }}/{{ .Profile.Name }}-key", - "repository": "/backup/{{ .Now.Weekday }}", - "lock": "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock", - "initialize": true, - "backup": { - "check-before": true, - "exclude": [ - "/**/.git" - ], - "exclude-caches": true, - "one-file-system": false, - "run-after": "echo All Done!", - "run-before": [ - "echo Hello {{ .Env.LOGNAME }}", - "echo current dir: {{ .CurrentDir }}", - "echo config dir: {{ .ConfigDir }}", - "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" - ], - "tag": [ - "{{ .Profile.Name }}", - "dev" - ] - }, - "retention": { - "after-backup": true, - "before-backup": false, - "compact": false, - "keep-within": "30d", - "prune": true, - "tag": [ - "{{ .Profile.Name }}", - "dev" - ] - }, - "snapshots": { - "tag": [ - "{{ .Profile.Name }}", - "dev" - ] - } - }, - "src": { - "inherit": "generic", - "backup": { - "source": [ - "{{ .Env.HOME }}/go/src" - ] - }, - "check": { - "read-data-subset": "{{ len (printf "a%*s" .Now.Weekday "") }}/7" - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -This is obviously not a real world example, but it shows many of the possibilities you can do with variable expansion. - -To check the generated configuration, you can use the resticprofile `show` command: - -```shell -% resticprofile -c examples/template.yaml -n src show - -global: - default-command: snapshots - restic-lock-retry-after: 1m0s - restic-stale-lock-age: 2h0m0s - min-memory: 100 - send-timeout: 30s - -profile src: - repository: /backup/Monday - password-file: /Users/CP/go/src/resticprofile/examples/src-key - initialize: true - lock: /Users/CP/resticprofile-profile-src.lock - - backup: - check-before: true - run-before: echo Hello CP - echo current dir: /Users/CP/go/src/resticprofile - echo config dir: /Users/CP/go/src/resticprofile/examples - echo profile started at 05 Sep 22 17:39 BST - run-after: echo All Done! - source: /Users/CP/go/src - exclude: /**/.git - exclude-caches: true - tag: src - dev - - retention: - after-backup: true - keep-within: 30d - path: /Users/CP/go/src - prune: true - tag: src - dev - - check: - read-data-subset: 2/7 - - snapshots: - tag: src - dev -``` - -As you can see, the `src` profile inherited from the `generic` profile. The tags `{{ .Profile.Name }}` got replaced by the name of the current profile `src`. -Now you can reuse the same generic configuration in another profile. - -You might have noticed the `read-data-subset` in the `check` section which will read a seventh of the data every day, meaning the whole repository data will be checked over a week. You can find [more information about this trick](https://stackoverflow.com/a/72465098). - -### Hand-made variables - -You can also define variables yourself. Hand-made variables starts with a `$` ([PHP](https://en.wikipedia.org/wiki/PHP) anyone?) and get declared and assigned with the `:=` operator ([Pascal](https://en.wikipedia.org/wiki/Pascal_(programming_language)) anyone?). - -{{% notice style="info" %}} -You can only use double quotes `"` to declare the string, single quotes `'` are not allowed. You can also use backticks to declare the string. -{{% /notice %}} - -Here's an example: - -```yaml -# declare and assign a value to the variable -{{ $name := "something" }} - -profile: - # put the content of the variable here - tag: "{{ $name }}" -``` -{{% notice style="note" %}} -Variables are only valid in the file they are declared in. They cannot be shared in files loaded via `include`. -{{% /notice %}} - -Variables can be redefined using the `=` operator. The new value will be used from the point of redefinition to the end of the file. - -```yaml -# declare and assign a value to the variable -{{ $name := "something" }} - -# reassign a new value to the variable -{{ $name = "something else" }} - -``` - -#### Windows path inside a variable - -Windows path are using backslashes `\` and are interpreted as escape characters in the configuration file. To use a Windows path inside a variable, you have a few options: -- you can escape the backslashes with another backslash. -- you can use forward slashes `/` instead of backslashes. Windows is able to use forward slashes in paths. -- you can use the backtick to declare the string instead of a double quote. - -For example: -```yaml -# double backslash -{{ $path := "C:\\Users\\CP\\Documents" }} -# forward slash -{{ $path := "C:/Users/CP/Documents" }} -# backticks -{{ $path := `C:\Users\CP\Documents` }} -``` - -#### Example - -Here's an example of a configuration on Linux where I use a variable `$mountpoint` set to a USB drive mount point: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[global] - priority = "low" - -{{ $mountpoint := "/mnt/external" }} - -[default] - repository = "local:{{ $mountpoint }}/backup" - password-file = "key" - run-before = "mount {{ $mountpoint }}" - run-after = "umount {{ $mountpoint }}" - run-after-fail = "umount {{ $mountpoint }}" - - [default.backup] - exclude-caches = true - source = [ "/etc", "/var/lib/libvirt" ] - check-after = true -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -global: - priority: low - -{{ $mountpoint := "/mnt/external" }} - -default: - repository: 'local:{{ $mountpoint }}/backup' - password-file: key - run-before: 'mount {{ $mountpoint }}' - run-after: 'umount {{ $mountpoint }}' - run-after-fail: 'umount {{ $mountpoint }}' - - backup: - exclude-caches: true - source: - - /etc - - /var/lib/libvirt - check-after: true -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -global { - priority = "low" -} - -{{ $mountpoint := "/mnt/external" }} - -default { - repository = "local:{{ $mountpoint }}/backup" - password-file = "key" - run-before = "mount {{ $mountpoint }}" - run-after = "umount {{ $mountpoint }}" - run-after-fail = "umount {{ $mountpoint }}" - - backup { - exclude-caches = true - source = [ "/etc", "/var/lib/libvirt" ] - check-after = true - } -} - -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{{ $mountpoint := "/mnt/external" }} -{ - "version": "1", - "global": { - "priority": "low" - }, - "default": { - "repository": "local:{{ $mountpoint }}/backup", - "password-file": "key", - "run-before": "mount {{ $mountpoint }}", - "run-after": "umount {{ $mountpoint }}", - "run-after-fail": "umount {{ $mountpoint }}", - "backup": { - "exclude-caches": true, - "source": [ - "/etc", - "/var/lib/libvirt" - ], - "check-after": true - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -## Runtime variable expansion - -Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/profiles/templates" %}}) that are expanded prior to parsing the configuration file. -This means they must be used carefully to create correct config markup, but they are also very flexible. - -There is also unix style variable expansion using the `${variable}` or `$variable` syntax on configuration **values** that expand after the config file was parsed. Values that take a file path or path expression and a few others support this expansion. - -If not specified differently, these variables resolve to the corresponding environment variable or to an empty value if no such environment variable exists. Exceptions are [mixins]({{% relref "/configuration/profiles/inheritance#mixins" %}}) where `$variable` style is used for parametrisation and the profile [config flag]({{% relref "reference/profile" %}}) `prometheus-push-job`. - -### Example - -Backup current dir (`$PWD`) but prevent backup of `$HOME` where the repository is located: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[default] - repository = "local:${HOME}/backup" - password-file = "${HOME}/backup.key" - - [default.backup] - source = "$PWD" - exclude = ["$HOME/**", ".*", "~*"] - -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -default: - repository: 'local:${HOME}/backup' - password-file: '${HOME}/backup.key' - - backup: - source: '$PWD' - exclude: ['$HOME/**', '.*', '~*'] - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -default { - repository = "local:${HOME}/backup" - password-file = "${HOME}/backup.key" - - backup { - source = [ "$PWD" ] - exclude = [ "$HOME/**", ".*", "~*" ] - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "default": { - "repository": "local:${HOME}/backup", - "password-file": "${HOME}/backup.key", - "backup": { - "source": [ "$PWD" ], - "exclude": [ "$HOME/**", ".*", "~*" ] - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -{{% notice style="tip" %}} -Use `$$` to escape a single `$` in configuration values that support variable expansion. E.g. on Windows you might want to exclude `$RECYCLE.BIN`. Specify it as: `exclude = ["$$RECYCLE.BIN"]`. -{{% /notice %}} diff --git a/docs/content/configuration/variables/_index.md b/docs/content/configuration/variables/_index.md new file mode 100644 index 00000000..2d326e71 --- /dev/null +++ b/docs/content/configuration/variables/_index.md @@ -0,0 +1,119 @@ +--- +title: "Variables" +weight: 31 +alwaysopen: false +--- + +{{< toc >}} + +## 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]({{% relref "/configuration/profiles/include" %}}) are loaded, and [inheritance]({{% relref "/configuration/profiles/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 + +The syntax for using a pre-defined variable is: + +``` +{{ .VariableName }} +``` + +The list of pre-defined variables and environment variables can be found in the [reference]({{% relref "/configuration/variables/env_vars" %}}) + +Environment variables are accessible using `.Env.` followed by the (upper case) name of the environment variable. + +Default and fallback values for an empty or unset variable can be declared with `{{ ... | or ... }}`. +For example `{{ .Env.HOME | or .Env.USERPROFILE | or "/fallback-homedir" }}` will try to resolve `$HOME`, if empty try to resolve `$USERPROFILE` +and finally default to `/fallback-homedir` if none of the env variables are defined. + +The variables `.OS` and `.Arch` are filled with the target platform that `resticprofile` was compiled for (see +[releases](https://github.com/creativeprojects/resticprofile/releases) for more information on existing precompiled platform binaries). + +For variables that are objects, you can call all public fields or methods on it. +For example, for the variable `.Now` ([time.Time](https://golang.org/pkg/time/)) you can use: + +- `(.Now.AddDate years months days)` +- `.Now.Day` +- `.Now.Format layout` +- `.Now.Hour` +- `.Now.Minute` +- `.Now.Month` +- `.Now.Second` +- `.Now.UTC` +- `.Now.Unix` +- `.Now.Weekday` +- `.Now.Year` +- `.Now.YearDay` + +Time can be formatted with `.Now.Format layout`, for example `{{ .Now.Format "2006-01-02T15:04:05Z07:00" }}` formats the current time as RFC3339 timestamp. +Check [time.Time#constants](https://pkg.go.dev/time#pkg-constants) for more layout examples. + +The variable `.Now` also allows to derive a relative `Time`. For example `{{ (.Now.AddDate 0 -6 -14).Format "2006-01-02" }}` formats a date that +is 6 months and 14 days before now. + +## Hand-made variables + +You can also define variables yourself. Hand-made variables starts with a `$` ([PHP](https://en.wikipedia.org/wiki/PHP) anyone?) and get declared and assigned with the `:=` operator ([Pascal](https://en.wikipedia.org/wiki/Pascal_(programming_language)) anyone?). + +{{% notice style="info" %}} +You can only use double quotes `"` to declare the string, single quotes `'` are not allowed. You can also use backticks to declare the string. +{{% /notice %}} + +Here's an example: + +```yaml +# declare and assign a value to the variable +{{ $name := "something" }} + +profile: + # put the content of the variable here + tag: "{{ $name }}" +``` +{{% notice style="note" %}} +Variables are only valid in the file they are declared in. They cannot be shared in files loaded via `include`. +{{% /notice %}} + +Variables can be redefined using the `=` operator. The new value will be used from the point of redefinition to the end of the file. + +```yaml +# declare and assign a value to the variable +{{ $name := "something" }} + +# reassign a new value to the variable +{{ $name = "something else" }} + +``` + +### Windows path inside a variable + +Windows path are using backslashes `\` and are interpreted as escape characters in the configuration file. To use a Windows path inside a variable, you have a few options: +- you can escape the backslashes with another backslash. +- you can use forward slashes `/` instead of backslashes. Windows is able to use forward slashes in paths. +- you can use the backtick to declare the string instead of a double quote. + +For example: +```yaml +# double backslash +{{ $path := "C:\\Users\\CP\\Documents" }} +# forward slash +{{ $path := "C:/Users/CP/Documents" }} +# backticks +{{ $path := `C:\Users\CP\Documents` }} +``` + +## Runtime variable expansion + +Variable expansion as described in the previous section using the `{{ .Var }}` syntax refers to [template variables]({{% relref "/configuration/variables/templates" %}}) that are expanded prior to parsing the configuration file. +This means they must be used carefully to create correct config markup, but they are also very flexible. + +There is also unix style variable expansion using the `${variable}` or `$variable` syntax on configuration **values** that expand after the config file was parsed. Values that take a file path or path expression and a few others support this expansion. + +If not specified differently, these variables resolve to the corresponding environment variable or to an empty value if no such environment variable exists. Exceptions are [mixins]({{% relref "/configuration/profiles/inheritance#mixins" %}}) where `$variable` style is used for parametrisation and the profile [config flag]({{% relref "reference/profile" %}}) `prometheus-push-job`. + +{{% notice style="tip" %}} +Use `$$` to escape a single `$` in configuration values that support variable expansion. E.g. on Windows you might want to exclude `$RECYCLE.BIN`. Specify it as: `exclude = ["$$RECYCLE.BIN"]`. +{{% /notice %}} diff --git a/docs/content/usage/env_vars.md b/docs/content/configuration/variables/env_vars.md similarity index 54% rename from docs/content/usage/env_vars.md rename to docs/content/configuration/variables/env_vars.md index 297e955b..3415fea5 100644 --- a/docs/content/usage/env_vars.md +++ b/docs/content/configuration/variables/env_vars.md @@ -1,8 +1,30 @@ --- -title: Environment Variables +title: Variable Reference weight: 7 --- +## Pre-defined Variables + + +| Variable | Type | Description | +|-------------------|--------------------------------------------------|------------------------------------------------------------------| +| **.Profile.Name** | string | Profile name | +| **.Now** | [time.Time](https://golang.org/pkg/time/) object | Now object: see explanation bellow | +| **.StartupDir** | string | Current directory at the time resticprofile was started | +| **.CurrentDir** | string | Current directory at the time a profile is executed | +| **.ConfigDir** | string | Directory where the configuration was loaded from | +| **.TempDir** | string | OS temporary directory (might not exist) | +| **.BinaryDir** | string | Directory where resticprofile was started from (since `v0.18.0`) | +| **.OS** | string | GOOS name: "windows", "linux", "darwin", etc. (since `v0.21.0`) | +| **.Arch** | string | GOARCH name: "386", "amd64", "arm64", etc. (since `v0.21.0`) | +| **.Hostname** | string | Host name | +| **.Env.{NAME}** | string | Environment variable `${NAME}` (see below) | + + +## Environment Variables + +Example: `{{ .Env.HOME }}` will be replaced by your home directory (on unixes). The equivalent on Windows would be `{{ .Env.USERPROFILE }}`. + Most flags for resticprofile can be set using environment variables. If both are specified, command line flags take the precedence. | Flag | Environment variable | Built-In default | diff --git a/docs/content/configuration/profiles/templates.md b/docs/content/configuration/variables/templates.md similarity index 100% rename from docs/content/configuration/profiles/templates.md rename to docs/content/configuration/variables/templates.md diff --git a/docs/content/contributions/_index.md b/docs/content/contributions/_index.md index 46757a43..5aec20fc 100644 --- a/docs/content/contributions/_index.md +++ b/docs/content/contributions/_index.md @@ -1,6 +1,6 @@ +++ archetype = "chapter" -pre = "5. " +pre = "6. " title = "Contributions" weight = 7 +++ diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index e328c92a..69ec9ae1 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -12,7 +12,7 @@ Here is a non-exhaustive list of what resticprofile offers: * Profiles can inherit options from other profiles * Create groups of profiles to run sequentially * Easily [schedule]({{% relref "/configuration/schedules" %}}) backups, retentions, and checks (supports *systemd*, *crond*, *launchd*, and *Windows Task Scheduler*) - * Use [template syntax]({{% relref "/configuration/profiles/templates" %}}) in your configuration file + * Use [template syntax]({{% relref "/configuration/variables/templates" %}}) in your configuration file * **[new for v0.29.0]** Schedule a group of profiles (configuration `v2` only) * **Automation** * Run the forget command before or after a backup (in a section called *retention*) diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index 5a2aa2e1..ddbfec5f 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -1,8 +1,8 @@ --- archetype: "chapter" -pre: "3. " +pre: "2. " title: "Using resticprofile" -weight: 3 +weight: 2 --- A command is either a restic command or a resticprofile own command. diff --git a/docs/content/usage/cmdline_ref.md b/docs/content/usage/cmdline_ref.md deleted file mode 100644 index fdb4bb13..00000000 --- a/docs/content/usage/cmdline_ref.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Command Line Reference -weight: 5 ---- -## Version - -The `version` command displays resticprofile version. If run in verbose mode (using `--verbose` flag) additional information such as OS version, golang version and modules are displayed as well. - -```shell -resticprofile --verbose version -``` - -## Command line reference - -There are not many options on the command line, most of the options are in the configuration file. - -* **[-h | --help]**: Display quick help -* **[-c | --config] configuration_file**: Specify a configuration file other than the default ("profiles") -* **[-f | --format] configuration_format**: Specify the configuration file format: `toml`, `yaml`, `json` or `hcl` -* **[-n | --name] profile_name**: Profile section to use from the configuration file. - You can also use `[profile_name].[command]` syntax instead, this will only work if `-n` is not set. - Using `-n [profile_name] [command]` or `[profile_name].[command]` both select profile and command and are technically equivalent. -* **[--dry-run]**: Doesn't run the restic commands but display the command lines instead -* **[-q | --quiet]**: Force resticprofile and restic to be quiet (override any configuration from the profile) -* **[-v | --verbose]**: Force resticprofile and restic to be verbose (override any configuration from the profile) -* **[--trace]**: Display even more debugging information -* **[--no-ansi]**: Disable console colouring (to save output into a log file) -* **[--stderr]**: Send console output from resticprofile to stderr (is enabled for commands `cat` and `dump`) -* **[--no-lock]**: Disable resticprofile locks, neither create nor fail on a lock. restic locks are unaffected by this option. -* **[--theme]**: Can be `light`, `dark` or `none`. The colours will adjust to a -light or dark terminal (none to disable colouring) -* **[--lock-wait] duration**: Retry to acquire resticprofile and restic locks for up to the specified amount of time before failing on a lock failure. -* **[-l | --log] file path or url**: To write the logs to a file or a syslog server instead of displaying on the console. -The format of the syslog server url is `syslog-tcp://192.168.0.1:514`, `syslog://udp-server:514` or `syslog:`. -For custom log forwarding, the prefix `temp:` can be used (e.g. `temp:/t/msg.log`) to create unique log output that can be fed -into a command or http hook by referencing it with `"{{ tempFile "msg.log" }}"` in the configuration file. -* **[--command-output]**: Sets how to redirect command output when a log target is specified. Can be `auto`, `log`, `console` or `all`. -* **[-w | --wait]**: Wait at the very end of the execution for the user to press enter. -This is only useful in Windows when resticprofile is started from explorer and the console window closes automatically at the end. -* **[--ignore-on-battery]**: Don't start the profile when the computer is running on battery. You can specify a value to ignore only when the % charge left is less or equal than the value. -* **[resticprofile OR restic command]**: Like snapshots, backup, check, prune, forget, mount, etc. -* **[additional flags]**: Any additional flags to pass to the restic command line diff --git a/docs/content/usage/hooks/_index.md b/docs/content/usage/hooks/_index.md new file mode 100644 index 00000000..7632dddb --- /dev/null +++ b/docs/content/usage/hooks/_index.md @@ -0,0 +1,5 @@ +--- +title: "Hooks - Examples" +--- + +{{% children sort="weight" %}} diff --git a/docs/content/usage/variable-example.md b/docs/content/usage/variable-example.md new file mode 100644 index 00000000..c679b6eb --- /dev/null +++ b/docs/content/usage/variable-example.md @@ -0,0 +1,189 @@ +--- +title: "Variables - Examples" +--- + +{{< toc >}} + +## Hand-made variables +Here's an example of a configuration on Linux where I use a variable `$mountpoint` set to a USB drive mount point: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[global] + priority = "low" + +{{ $mountpoint := "/mnt/external" }} + +[default] + repository = "local:{{ $mountpoint }}/backup" + password-file = "key" + run-before = "mount {{ $mountpoint }}" + run-after = "umount {{ $mountpoint }}" + run-after-fail = "umount {{ $mountpoint }}" + + [default.backup] + exclude-caches = true + source = [ "/etc", "/var/lib/libvirt" ] + check-after = true +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +global: + priority: low + +{{ $mountpoint := "/mnt/external" }} + +default: + repository: 'local:{{ $mountpoint }}/backup' + password-file: key + run-before: 'mount {{ $mountpoint }}' + run-after: 'umount {{ $mountpoint }}' + run-after-fail: 'umount {{ $mountpoint }}' + + backup: + exclude-caches: true + source: + - /etc + - /var/lib/libvirt + check-after: true +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +global { + priority = "low" +} + +{{ $mountpoint := "/mnt/external" }} + +default { + repository = "local:{{ $mountpoint }}/backup" + password-file = "key" + run-before = "mount {{ $mountpoint }}" + run-after = "umount {{ $mountpoint }}" + run-after-fail = "umount {{ $mountpoint }}" + + backup { + exclude-caches = true + source = [ "/etc", "/var/lib/libvirt" ] + check-after = true + } +} + +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{{ $mountpoint := "/mnt/external" }} +{ + "version": "1", + "global": { + "priority": "low" + }, + "default": { + "repository": "local:{{ $mountpoint }}/backup", + "password-file": "key", + "run-before": "mount {{ $mountpoint }}", + "run-after": "umount {{ $mountpoint }}", + "run-after-fail": "umount {{ $mountpoint }}", + "backup": { + "exclude-caches": true, + "source": [ + "/etc", + "/var/lib/libvirt" + ], + "check-after": true + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + +## Runtime variable expansion + +Backup current dir (`$PWD`) but prevent backup of `$HOME` where the repository is located: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[default] + repository = "local:${HOME}/backup" + password-file = "${HOME}/backup.key" + + [default.backup] + source = "$PWD" + exclude = ["$HOME/**", ".*", "~*"] + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +default: + repository: 'local:${HOME}/backup' + password-file: '${HOME}/backup.key' + + backup: + source: '$PWD' + exclude: ['$HOME/**', '.*', '~*'] + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +default { + repository = "local:${HOME}/backup" + password-file = "${HOME}/backup.key" + + backup { + source = [ "$PWD" ] + exclude = [ "$HOME/**", ".*", "~*" ] + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "default": { + "repository": "local:${HOME}/backup", + "password-file": "${HOME}/backup.key", + "backup": { + "source": [ "$PWD" ], + "exclude": [ "$HOME/**", ".*", "~*" ] + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + +{{% notice style="tip" %}} +Use `$$` to escape a single `$` in configuration values that support variable expansion. E.g. on Windows you might want to exclude `$RECYCLE.BIN`. Specify it as: `exclude = ["$$RECYCLE.BIN"]`. +{{% /notice %}} diff --git a/docs/content/usage/variables.md b/docs/content/usage/variables.md new file mode 100644 index 00000000..268559e2 --- /dev/null +++ b/docs/content/usage/variables.md @@ -0,0 +1,282 @@ +--- +title: "Using inheritance and variables" +--- +You can use a combination of inheritance and variables in the resticprofile configuration file like so: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[generic] + password-file = "{{ .ConfigDir }}/{{ .Profile.Name }}-key" + repository = "/backup/{{ .Now.Weekday }}" + lock = "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" + initialize = true + + [generic.backup] + check-before = true + exclude = [ "/**/.git" ] + exclude-caches = true + one-file-system = false + run-after = "echo All Done!" + run-before = [ + "echo Hello {{ .Env.LOGNAME }}", + "echo current dir: {{ .CurrentDir }}", + "echo config dir: {{ .ConfigDir }}", + "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" + ] + tag = [ "{{ .Profile.Name }}", "dev" ] + + [generic.retention] + after-backup = true + before-backup = false + compact = false + keep-within = "30d" + prune = true + tag = [ "{{ .Profile.Name }}", "dev" ] + + [generic.snapshots] + tag = [ "{{ .Profile.Name }}", "dev" ] + +[src] + inherit = "generic" + + [src.backup] + source = [ "{{ .Env.HOME }}/go/src" ] + + [src.check] + # Weekday is an integer from 0 to 6 (starting from Sunday) + # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 + read-data-subset = "{{ len (printf "a%*s" .Now.Weekday "") }}/7" + +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +--- +version: "1" + +generic: + password-file: "{{ .ConfigDir }}/{{ .Profile.Name }}-key" + repository: "/backup/{{ .Now.Weekday }}" + lock: "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" + initialize: true + + backup: + check-before: true + exclude: + - /**/.git + exclude-caches: true + one-file-system: false + run-after: echo All Done! + run-before: + - "echo Hello {{ .Env.LOGNAME }}" + - "echo current dir: {{ .CurrentDir }}" + - "echo config dir: {{ .ConfigDir }}" + - "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" + tag: + - "{{ .Profile.Name }}" + - dev + + retention: + after-backup: true + before-backup: false + compact: false + keep-within: 30d + prune: true + tag: + - "{{ .Profile.Name }}" + - dev + + snapshots: + tag: + - "{{ .Profile.Name }}" + - dev + +src: + inherit: generic + + backup: + source: + - "{{ .Env.HOME }}/go/src" + + check: + # Weekday is an integer from 0 to 6 (starting from Sunday) + # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 + read-data-subset: "{{ len (printf "a%*s" .Now.Weekday "") }}/7" + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"generic" = { + "password-file" = "{{ .ConfigDir }}/{{ .Profile.Name }}-key" + "repository" = "/backup/{{ .Now.Weekday }}" + "lock" = "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock" + "initialize" = true + + "backup" = { + "check-before" = true + "exclude" = ["/**/.git"] + "exclude-caches" = true + "one-file-system" = false + "run-after" = "echo All Done!" + "run-before" = ["echo Hello {{ .Env.LOGNAME }}", "echo current dir: {{ .CurrentDir }}", "echo config dir: {{ .ConfigDir }}", "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}"] + "tag" = ["{{ .Profile.Name }}", "dev"] + } + + "retention" = { + "after-backup" = true + "before-backup" = false + "compact" = false + "keep-within" = "30d" + "prune" = true + "tag" = ["{{ .Profile.Name }}", "dev"] + } + + "snapshots" = { + "tag" = ["{{ .Profile.Name }}", "dev"] + } +} + +"src" = { + "inherit" = "generic" + + "backup" = { + "source" = ["{{ .Env.HOME }}/go/src"] + } + + "check" = { + # Weekday is an integer from 0 to 6 (starting from Sunday) + # Nice trick to add 1 to an integer: https://stackoverflow.com/a/72465098 + "read-data-subset" = "{{ len (printf "a%*s" .Now.Weekday "") }}/7" + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "generic": { + "password-file": "{{ .ConfigDir }}/{{ .Profile.Name }}-key", + "repository": "/backup/{{ .Now.Weekday }}", + "lock": "$HOME/resticprofile-profile-{{ .Profile.Name }}.lock", + "initialize": true, + "backup": { + "check-before": true, + "exclude": [ + "/**/.git" + ], + "exclude-caches": true, + "one-file-system": false, + "run-after": "echo All Done!", + "run-before": [ + "echo Hello {{ .Env.LOGNAME }}", + "echo current dir: {{ .CurrentDir }}", + "echo config dir: {{ .ConfigDir }}", + "echo profile started at {{ .Now.Format "02 Jan 06 15:04 MST" }}" + ], + "tag": [ + "{{ .Profile.Name }}", + "dev" + ] + }, + "retention": { + "after-backup": true, + "before-backup": false, + "compact": false, + "keep-within": "30d", + "prune": true, + "tag": [ + "{{ .Profile.Name }}", + "dev" + ] + }, + "snapshots": { + "tag": [ + "{{ .Profile.Name }}", + "dev" + ] + } + }, + "src": { + "inherit": "generic", + "backup": { + "source": [ + "{{ .Env.HOME }}/go/src" + ] + }, + "check": { + "read-data-subset": "{{ len (printf "a%*s" .Now.Weekday "") }}/7" + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + +This is obviously not a real world example, but it shows many of the possibilities you can do with variable expansion. + +To check the generated configuration, you can use the resticprofile `show` command: + +```shell +% resticprofile -c examples/template.yaml -n src show + +global: + default-command: snapshots + restic-lock-retry-after: 1m0s + restic-stale-lock-age: 2h0m0s + min-memory: 100 + send-timeout: 30s + +profile src: + repository: /backup/Monday + password-file: /Users/CP/go/src/resticprofile/examples/src-key + initialize: true + lock: /Users/CP/resticprofile-profile-src.lock + + backup: + check-before: true + run-before: echo Hello CP + echo current dir: /Users/CP/go/src/resticprofile + echo config dir: /Users/CP/go/src/resticprofile/examples + echo profile started at 05 Sep 22 17:39 BST + run-after: echo All Done! + source: /Users/CP/go/src + exclude: /**/.git + exclude-caches: true + tag: src + dev + + retention: + after-backup: true + keep-within: 30d + path: /Users/CP/go/src + prune: true + tag: src + dev + + check: + read-data-subset: 2/7 + + snapshots: + tag: src + dev +``` + +As you can see, the `src` profile inherited from the `generic` profile. The tags `{{ .Profile.Name }}` got replaced by the name of the current profile `src`. +Now you can reuse the same generic configuration in another profile. + +You might have noticed the `read-data-subset` in the `check` section which will read a seventh of the data every day, meaning the whole repository data will be checked over a week. You can find [more information about this trick](https://stackoverflow.com/a/72465098). + +More examples can be found [here]({{% relref "/usage/variable-example" %}}). From d7ed8de212e76c4a6ebb22b32879705c95983cfa Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 18:04:07 -0500 Subject: [PATCH 27/29] Reorganizing the Usage section --- .../content/configuration/profiles/include.md | 2 +- .../configuration/profiles/inheritance.md | 2 +- .../profiles}/locks.md | 2 +- docs/content/configuration/profiles/path.md | 2 +- .../configuration/schedules/commands.md | 2 +- .../configuration/schedules/configuration.md | 2 +- docs/content/features/_index.md | 6 +- docs/content/installation/_index.md | 8 + .../{examples => configuration}/_index.md | 8 +- .../azure-storage.md | 3 +- .../configWindows.md | 3 +- .../configWinheritence.md | 3 +- .../{examples => configuration}/stdin.md | 3 +- .../usage/examples/scheduling-examples.md | 531 ------------------ docs/content/usage/getting_started.md | 2 +- docs/content/usage/hooks/_index.md | 4 +- docs/content/usage/{examples => }/keyfile.md | 1 + docs/content/usage/memory.md | 13 - docs/content/usage/scheduling/_index.md | 131 +++++ .../usage/{ => scheduling}/change-schedule.md | 1 + docs/content/usage/scheduling/linux.md | 208 +++++++ docs/content/usage/scheduling/macos.md | 91 +++ docs/content/usage/scheduling/windows.md | 109 ++++ docs/content/usage/variables/_index.md | 8 + .../inheritance-and-variables.md} | 2 +- .../list-variables.md} | 2 +- 26 files changed, 582 insertions(+), 567 deletions(-) rename docs/content/{usage => configuration/profiles}/locks.md (99%) rename docs/content/usage/{examples => configuration}/_index.md (95%) rename docs/content/usage/{examples => configuration}/azure-storage.md (97%) rename docs/content/usage/{examples => configuration}/configWindows.md (97%) rename docs/content/usage/{examples => configuration}/configWinheritence.md (99%) rename docs/content/usage/{examples => configuration}/stdin.md (97%) delete mode 100644 docs/content/usage/examples/scheduling-examples.md rename docs/content/usage/{examples => }/keyfile.md (98%) delete mode 100644 docs/content/usage/memory.md create mode 100644 docs/content/usage/scheduling/_index.md rename docs/content/usage/{ => scheduling}/change-schedule.md (97%) create mode 100644 docs/content/usage/scheduling/linux.md create mode 100644 docs/content/usage/scheduling/macos.md create mode 100644 docs/content/usage/scheduling/windows.md create mode 100644 docs/content/usage/variables/_index.md rename docs/content/usage/{variables.md => variables/inheritance-and-variables.md} (98%) rename docs/content/usage/{variable-example.md => variables/list-variables.md} (99%) diff --git a/docs/content/configuration/profiles/include.md b/docs/content/configuration/profiles/include.md index 92609ddb..a1ba80c7 100644 --- a/docs/content/configuration/profiles/include.md +++ b/docs/content/configuration/profiles/include.md @@ -1,6 +1,6 @@ --- title: "Includes" -weight: 15 +weight: 32 --- The configuration may be split into multiple files by adding `includes = "glob-pattern"` to the main configuration file. diff --git a/docs/content/configuration/profiles/inheritance.md b/docs/content/configuration/profiles/inheritance.md index ec9c866c..ef1bb5a1 100644 --- a/docs/content/configuration/profiles/inheritance.md +++ b/docs/content/configuration/profiles/inheritance.md @@ -1,6 +1,6 @@ --- title: "Inheritance" -weight: 16 +weight: 33 --- {{% notice style="tip" %}} diff --git a/docs/content/usage/locks.md b/docs/content/configuration/profiles/locks.md similarity index 99% rename from docs/content/usage/locks.md rename to docs/content/configuration/profiles/locks.md index 2a1fcf91..25db603b 100644 --- a/docs/content/usage/locks.md +++ b/docs/content/configuration/profiles/locks.md @@ -1,6 +1,6 @@ --- title: "Locks" -weight: 20 +weight: 34 --- restic is already using a lock to avoid running some operations at the same time. diff --git a/docs/content/configuration/profiles/path.md b/docs/content/configuration/profiles/path.md index e823d7ea..16db4f48 100644 --- a/docs/content/configuration/profiles/path.md +++ b/docs/content/configuration/profiles/path.md @@ -1,6 +1,6 @@ --- title: "Path" -weight: 10 +weight: 31 --- ## How paths inside the configuration are resolved diff --git a/docs/content/configuration/schedules/commands.md b/docs/content/configuration/schedules/commands.md index aed6ac73..3a0930e8 100644 --- a/docs/content/configuration/schedules/commands.md +++ b/docs/content/configuration/schedules/commands.md @@ -59,7 +59,7 @@ Starting with `v0.30.0`, the behavior of the `unschedule` command changed: Print the status of all installed schedules for the selected profiles. -The `status` command output varies by OS. See the [examples]({{% relref "/usage/examples/scheduling-examples" %}}) for details. +The `status` command output varies by OS. See the [examples]({{% relref "/usage/scheduling" %}}) for details. ### run-schedule command diff --git a/docs/content/configuration/schedules/configuration.md b/docs/content/configuration/schedules/configuration.md index 74cc9e45..3e472506 100644 --- a/docs/content/configuration/schedules/configuration.md +++ b/docs/content/configuration/schedules/configuration.md @@ -83,7 +83,7 @@ profile: * *empty*: resticprofile will guess based on how it was started (with sudo or as a normal user). The fallback is `system` on Windows and `user_logged_on` on other platforms. {{% notice style="warning" %}} -After changing this setting, you must update the schedule. More information can be found under [Changing Schedule Permissions]({{% relref "/usage/change-schedule" %}}) +After changing this setting, you must update the schedule. More information can be found under [Changing Schedule Permissions]({{% relref "/usage/scheduling/change-schedule" %}}) {{% /notice %}} ## schedule-run-level diff --git a/docs/content/features/_index.md b/docs/content/features/_index.md index 69ec9ae1..d2ebb1e8 100644 --- a/docs/content/features/_index.md +++ b/docs/content/features/_index.md @@ -21,7 +21,7 @@ Here is a non-exhaustive list of what resticprofile offers: * Run a [shell command]({{% relref "/configuration/hooks/run_hooks" %}}) if an error occurs * Send a backup stream via _stdin_ * Start restic at different [priorities]({{% relref "/configuration/profiles/priority" %}}) (Priority Class in Windows, *nice* in Unix, and/or _ionice_ in Linux) - * Automatically clear [stale locks]({{% relref "/usage/locks" %}}) + * Automatically clear [stale locks]({{% relref "/configuration/profiles/locks" %}}) * **Monitoring** * Generate a simple [status file]({{% relref "/configuration/monitoring/status" %}}) for monitoring software to ensure backups are running smoothly * Export a [prometheus]({{% relref "/configuration/monitoring/prometheus" %}}) file after a backup or send the report to a push gateway @@ -29,10 +29,10 @@ Here is a non-exhaustive list of what resticprofile offers: * Send messages to [HTTP hooks]({{% relref "/configuration/hooks/http_hooks" %}}) before, after a successful or failed job (backup, forget, check, prune, copy) * Send resticprofile [logs]({{% relref "/configuration/monitoring/index" %}}) to a syslog server * **Checks** - * Check for [enough memory]({{% relref "/usage/memory" %}}) before starting a backup + * Check for [enough memory]({{% relref "/installation/#note-about-memory" %}}) before starting a backup * Avoid scheduling a job when the system is on battery * **Misc** - * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/examples/keyfile" %}}) + * Generate cryptographically secure random keys for a restic [key file]({{% relref "/usage/keyfile" %}}) * Automatically [initialize the secondary repository]({{% relref "/configuration/hooks/copy" %}}) using the `copy-chunker-params` flag * Prevent the system from [idle sleeping]({{% relref "/configuration/schedules/configuration/#preventing-system-sleep" %}}) * View help for both restic and resticprofile via the `help` command or `-h` flag diff --git a/docs/content/installation/_index.md b/docs/content/installation/_index.md index 8b28e190..2567e742 100644 --- a/docs/content/installation/_index.md +++ b/docs/content/installation/_index.md @@ -10,3 +10,11 @@ Here are the multiple ways you can install resticprofile: ## Upgrading After installation, you can run `resticprofile self-update` to update resticprofile to the latest release. The `-q` or `--quiet` flag updates the application without prompting. + +## Note about Memory + +restic can be memory hungry. I'm running a few servers with no swap and I managed to kill some of them during a backup. + +For that matter I've introduced a parameter in the `global` section called `min-memory`. The **default value is 100MB**. You can disable it by using a value of `0`. + +It compares against `(total - used)` which is probably the best way to know how much memory is available (that is including the memory used for disk buffers/cache). diff --git a/docs/content/usage/examples/_index.md b/docs/content/usage/configuration/_index.md similarity index 95% rename from docs/content/usage/examples/_index.md rename to docs/content/usage/configuration/_index.md index 1aedbf18..008dc909 100644 --- a/docs/content/usage/examples/_index.md +++ b/docs/content/usage/configuration/_index.md @@ -1,6 +1,6 @@ --- -title: "Examples" -weight: 40 +title: "Configuration Files" +weight: 20 alwaysopen: false --- @@ -101,7 +101,3 @@ resticprofile --dry-run backup 2022/05/18 17:14:07 dry-run: /usr/bin/restic backup --password-file password.txt --repo local:/backup --verbose /home 2022/05/18 17:14:07 profile 'default': finished 'backup' ``` - -## More Examples - -{{% children sort="weight" depth="2" %}} diff --git a/docs/content/usage/examples/azure-storage.md b/docs/content/usage/configuration/azure-storage.md similarity index 97% rename from docs/content/usage/examples/azure-storage.md rename to docs/content/usage/configuration/azure-storage.md index 36fe6b47..fe8d0006 100644 --- a/docs/content/usage/examples/azure-storage.md +++ b/docs/content/usage/configuration/azure-storage.md @@ -1,5 +1,6 @@ --- -title: "Simple Configuration with Azure Storage" +title: "Example: Azure Storage" +weight: 10 --- Here's a simple configuration file using a Microsoft Azure backend. You will notice that the `env` section lets you define environment variables: diff --git a/docs/content/usage/examples/configWindows.md b/docs/content/usage/configuration/configWindows.md similarity index 97% rename from docs/content/usage/examples/configWindows.md rename to docs/content/usage/configuration/configWindows.md index f7827769..063eaef6 100644 --- a/docs/content/usage/examples/configWindows.md +++ b/docs/content/usage/configuration/configWindows.md @@ -1,5 +1,6 @@ --- -title: "Configuration example for Windows" +title: "Example: Windows" +weight: 30 --- {{< tabs groupid="config-with-hcl" >}} diff --git a/docs/content/usage/examples/configWinheritence.md b/docs/content/usage/configuration/configWinheritence.md similarity index 99% rename from docs/content/usage/examples/configWinheritence.md rename to docs/content/usage/configuration/configWinheritence.md index 66e6cbe3..f6bb399e 100644 --- a/docs/content/usage/examples/configWinheritence.md +++ b/docs/content/usage/configuration/configWinheritence.md @@ -1,5 +1,6 @@ --- -title: "Configuration with inheritance" +title: "Example: Using Inheritance" +wieght: 20 --- Here's a more complex configuration file showing profile inheritance and two backup profiles using the same repository: diff --git a/docs/content/usage/examples/stdin.md b/docs/content/usage/configuration/stdin.md similarity index 97% rename from docs/content/usage/examples/stdin.md rename to docs/content/usage/configuration/stdin.md index 0ed295ec..6b9ffd31 100644 --- a/docs/content/usage/examples/stdin.md +++ b/docs/content/usage/configuration/stdin.md @@ -1,5 +1,6 @@ --- -title: "Use stdin in configuration" +title: "Example: stdin" +weight: 40 --- Simple example sending a file via stdin diff --git a/docs/content/usage/examples/scheduling-examples.md b/docs/content/usage/examples/scheduling-examples.md deleted file mode 100644 index 513b508d..00000000 --- a/docs/content/usage/examples/scheduling-examples.md +++ /dev/null @@ -1,531 +0,0 @@ ---- -title: "Schedule Examples" -weight: 30 ---- - -## Example - -Here's an example of a scheduling configuration: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -[default] - repository = "d:\\backup" - password-file = "key" - -[self] - inherit = "default" - - [self.retention] - after-backup = true - keep-within = "14d" - - [self.backup] - source = "." - schedule = [ "Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00" ] - schedule-permission = "user" - schedule-lock-wait = "10m" - - [self.prune] - schedule = "sun 3:30" - schedule-permission = "user" - schedule-lock-wait = "1h" -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -default: - repository: "d:\\backup" - password-file: key - -self: - inherit: default - retention: - after-backup: true - keep-within: 14d - backup: - source: "." - schedule: - - "Mon..Fri *:00,15,30,45" # every 15 minutes on weekdays - - "Sat,Sun 0,12:00" # twice a day on week-ends - schedule-permission: user - schedule-lock-wait: 10m - prune: - schedule: "sun 3:30" - schedule-permission: user - schedule-lock-wait: 1h -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"default" = { - "repository" = "d:\\backup" - "password-file" = "key" -} - -"self" = { - "inherit" = "default" - - "retention" = { - "after-backup" = true - "keep-within" = "14d" - } - - "backup" = { - "source" = "." - "schedule" = ["Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00"] - "schedule-permission" = "user" - "schedule-lock-wait" = "10m" - } - - "prune" = { - "schedule" = "sun 3:30" - "schedule-permission" = "user" - "schedule-lock-wait" = "1h" - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "default": { - "repository": "d:\\backup", - "password-file": "key" - }, - "self": { - "inherit": "default", - "retention": { - "after-backup": true, - "keep-within": "14d" - }, - "backup": { - "source": ".", - "schedule": [ - "Mon..Fri *:00,15,30,45", - "Sat,Sun 0,12:00" - ], - "schedule-permission": "user", - "schedule-lock-wait": "10m" - }, - "prune": { - "schedule": "sun 3:30", - "schedule-permission": "user", - "schedule-lock-wait": "1h" - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - -### Examples of scheduling commands under Windows - -{{% notice note %}} -If you create a task with `user` permission under Windows, you will need to enter your password to validate the task. - -It's a requirement of the task scheduler. I'm inviting you to review the code to make sure I'm not emailing your password to myself. Seriously you shouldn't trust anyone. -{{% /notice %}} - -Example of the `schedule` command under Windows (with git bash): - -```shell -$ resticprofile -c examples/windows.yaml -n self schedule - -Analyzing backup schedule 1/2 -================================= - Original form: Mon..Fri *:00,15,30,45 -Normalized form: Mon..Fri *-*-* *:00,15,30,45:00 - Next elapse: Wed Jul 22 21:30:00 BST 2020 - (in UTC): Wed Jul 22 20:30:00 UTC 2020 - From now: 1m52s left - -Analyzing backup schedule 2/2 -================================= - Original form: Sat,Sun 0,12:00 -Normalized form: Sat,Sun *-*-* 00,12:00:00 - Next elapse: Sat Jul 25 00:00:00 BST 2020 - (in UTC): Fri Jul 24 23:00:00 UTC 2020 - From now: 50h31m52s left - -Creating task for user Creative Projects -Task Scheduler requires your Windows password to validate the task: - -2020/07/22 21:28:15 scheduled job self/backup created - -Analyzing retention schedule 1/1 -================================= - Original form: sun 3:30 -Normalized form: Sun *-*-* 03:30:00 - Next elapse: Sun Jul 26 03:30:00 BST 2020 - (in UTC): Sun Jul 26 02:30:00 UTC 2020 - From now: 78h1m44s left - -2020/07/22 21:28:22 scheduled job self/retention created -``` - -To see the status of the triggers, you can use the `status` command: - -```shell -$ resticprofile -c examples/windows.yaml -n self status - -Analyzing backup schedule 1/2 -================================= - Original form: Mon..Fri *:00,15,30,45 -Normalized form: Mon..Fri *-*-* *:00,15,30,45:00 - Next elapse: Wed Jul 22 21:30:00 BST 2020 - (in UTC): Wed Jul 22 20:30:00 UTC 2020 - From now: 14s left - -Analyzing backup schedule 2/2 -================================= - Original form: Sat,Sun 0,12:* -Normalized form: Sat,Sun *-*-* 00,12:*:00 - Next elapse: Sat Jul 25 00:00:00 BST 2020 - (in UTC): Fri Jul 24 23:00:00 UTC 2020 - From now: 50h29m46s left - - Task: \resticprofile backup\self backup - User: Creative Projects - Working Dir: D:\Source\resticprofile - Exec: D:\Source\resticprofile\resticprofile.exe --no-ansi --config examples/windows.yaml --name self backup - Enabled: true - State: ready - Missed runs: 0 - Last Run Time: 2020-07-22 21:30:00 +0000 UTC - Last Result: 0 - Next Run Time: 2020-07-22 21:45:00 +0000 UTC - -Analyzing retention schedule 1/1 -================================= - Original form: sun 3:30 -Normalized form: Sun *-*-* 03:30:00 - Next elapse: Sun Jul 26 03:30:00 BST 2020 - (in UTC): Sun Jul 26 02:30:00 UTC 2020 - From now: 77h59m46s left - - Task: \resticprofile backup\self retention - User: Creative Projects - Working Dir: D:\Source\resticprofile - Exec: D:\Source\resticprofile\resticprofile.exe --no-ansi --config examples/windows.yaml --name self forget - Enabled: true - State: ready - Missed runs: 0 - Last Run Time: 1999-11-30 00:00:00 +0000 UTC - Last Result: 267011 - Next Run Time: 2020-07-26 03:30:00 +0000 UTC - -``` - -To remove the schedule, use the `unschedule` command: - -```shell -$ resticprofile -c examples/windows.yaml -n self unschedule -2020/07/22 21:34:51 scheduled job self/backup removed -2020/07/22 21:34:51 scheduled job self/retention removed -``` - - -### Examples of scheduling commands under Linux - -With this example of configuration for Linux: - -{{< tabs groupid="config-with-json" >}} -{{% tab title="toml" %}} - -```toml -version = "1" - -[default] - password-file = "key" - repository = "/tmp/backup" - -[test1] - inherit = "default" - - [test1.backup] - source = "./" - schedule = "*:00,15,30,45" - schedule-permission = "user" - schedule-lock-wait = "15m" - - [test1.check] - schedule = "*-*-1" - schedule-permission = "user" - schedule-lock-wait = "15m" -``` - -{{% /tab %}} -{{% tab title="yaml" %}} - -```yaml -version: "1" - -default: - password-file: key - repository: /tmp/backup - -test1: - inherit: default - backup: - source: ./ - schedule: "*:00,15,30,45" - schedule-permission: user - schedule-lock-wait: 15m - check: - schedule: "*-*-1" - schedule-permission: user - schedule-lock-wait: 15m - -``` - -{{% /tab %}} -{{% tab title="hcl" %}} - -```hcl -"default" = { - "password-file" = "key" - "repository" = "/tmp/backup" -} - -"test1" = { - "inherit" = "default" - - "backup" = { - "source" = "./" - "schedule" = "*:00,15,30,45" - "schedule-permission" = "user" - "schedule-lock-wait" = "15m" - } - - "check" = { - "schedule" = "*-*-1" - "schedule-permission" = "user" - "schedule-lock-wait" = "15m" - } -} -``` - -{{% /tab %}} -{{% tab title="json" %}} - -```json -{ - "version": "1", - "default": { - "password-file": "key", - "repository": "/tmp/backup" - }, - "test1": { - "inherit": "default", - "backup": { - "source": "./", - "schedule": "*:00,15,30,45", - "schedule-permission": "user", - "schedule-lock-wait": "15m" - }, - "check": { - "schedule": "*-*-1", - "schedule-permission": "user", - "schedule-lock-wait": "15m" - } - } -} -``` - -{{% /tab %}} -{{< /tabs >}} - - -```shell -$ resticprofile -c examples/linux.yaml -n test1 schedule - -Analyzing backup schedule 1/1 -================================= - Original form: *:00,15,30,45 -Normalized form: *-*-* *:00,15,30,45:00 - Next elapse: Thu 2020-07-23 17:15:00 BST - (in UTC): Thu 2020-07-23 16:15:00 UTC - From now: 6min left - -2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-backup@profile-test1.service -2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer -Created symlink /home/user/.config/systemd/user/timers.target.wants/resticprofile-backup@profile-test1.timer → /home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer. -2020/07/23 17:08:51 scheduled job test1/backup created - -Analyzing check schedule 1/1 -================================= - Original form: *-*-1 -Normalized form: *-*-01 00:00:00 - Next elapse: Sat 2020-08-01 00:00:00 BST - (in UTC): Fri 2020-07-31 23:00:00 UTC - From now: 1 weeks 1 days left - -2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-check@profile-test1.service -2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-check@profile-test1.timer -Created symlink /home/user/.config/systemd/user/timers.target.wants/resticprofile-check@profile-test1.timer → /home/user/.config/systemd/user/resticprofile-check@profile-test1.timer. -2020/07/23 17:08:51 scheduled job test1/check created -``` - -The `status` command shows a combination of `journalctl` displaying errors (only) in the last month and `systemctl status`: - -```shell -$ resticprofile -c examples/linux.yaml -n test1 status - -Analyzing backup schedule 1/1 -================================= - Original form: *:00,15,30,45 -Normalized form: *-*-* *:00,15,30,45:00 - Next elapse: Tue 2020-07-28 15:15:00 BST - (in UTC): Tue 2020-07-28 14:15:00 UTC - From now: 4min 44s left - -Recent log (>= warning in the last month) -========================================== --- Logs begin at Wed 2020-06-17 11:09:19 BST, end at Tue 2020-07-28 15:10:10 BST. -- -Jul 27 20:48:01 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. -Jul 27 21:00:55 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. -Jul 27 21:15:34 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. - -Systemd timer status -===================== -● resticprofile-backup@profile-test1.timer - backup timer for profile test1 in examples/linux.yaml - Loaded: loaded (/home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer; enabled; vendor preset: enabled) - Active: active (waiting) since Tue 2020-07-28 15:10:06 BST; 8s ago - Trigger: Tue 2020-07-28 15:15:00 BST; 4min 44s left - -Jul 28 15:10:06 Desktop76 systemd[2951]: Started backup timer for profile test1 in examples/linux.yaml. - - -Analyzing check schedule 1/1 -================================= - Original form: *-*-1 -Normalized form: *-*-01 00:00:00 - Next elapse: Sat 2020-08-01 00:00:00 BST - (in UTC): Fri 2020-07-31 23:00:00 UTC - From now: 3 days left - -Recent log (>= warning in the last month) -========================================== --- Logs begin at Wed 2020-06-17 11:09:19 BST, end at Tue 2020-07-28 15:10:10 BST. -- -Jul 27 19:39:59 Desktop76 systemd[2986]: Failed to start resticprofile check for profile test1 in examples/linux.yaml. - -Systemd timer status -===================== -● resticprofile-check@profile-test1.timer - check timer for profile test1 in examples/linux.yaml - Loaded: loaded (/home/user/.config/systemd/user/resticprofile-check@profile-test1.timer; enabled; vendor preset: enabled) - Active: active (waiting) since Tue 2020-07-28 15:10:07 BST; 7s ago - Trigger: Sat 2020-08-01 00:00:00 BST; 3 days left - -Jul 28 15:10:07 Desktop76 systemd[2951]: Started check timer for profile test1 in examples/linux.yaml. - - -``` - -And `unschedule`: - -```shell -$ resticprofile -c examples/linux.yaml -n test1 unschedule -Removed /home/user/.config/systemd/user/timers.target.wants/resticprofile-backup@profile-test1.timer. -2020/07/23 17:13:42 scheduled job test1/backup removed -Removed /home/user/.config/systemd/user/timers.target.wants/resticprofile-check@profile-test1.timer. -2020/07/23 17:13:42 scheduled job test1/check removed -``` - -### Examples of scheduling commands under macOS - -Here's an example of scheduling a backup profile named `azure-dev`: - -```shell -% resticprofile -n azure-dev schedule -2025/03/30 18:40:13 using configuration file: profiles.yaml - -Profile (or Group) azure-dev: backup schedule -============================================= - Original form: 22:22 -Normalized form: *-*-* 22:22:00 - Next elapse: Sun Mar 30 22:22:00 BST 2025 - (in UTC): Sun Mar 30 21:22:00 UTC 2025 - From now: 3h41m46s left - -2025/03/30 18:40:13 scheduled job azure-dev/backup created - -``` - -{{% notice info %}} - -In some cases, macOS may request permission to access the network, an external volume (like a USB drive), or a protected directory. A message window will appear while the backup runs in the background. -{{% /notice %}} - -![access files popup window]({{< absolute "configuration/schedules/removable_volume.png" nohtml >}}) - -You may want to start the task now so you can grant special permissions: - -1. Retrieve the task name using the status command: - -```shell -% resticprofile -n azure-dev status -2025/03/30 18:40:21 using configuration file: profiles.yaml - -Profile (or Group) azure-dev: backup schedule -============================================= - Original form: *-*-* 22:22:00 -Normalized form: *-*-* 22:22:00 - Next elapse: Sun Mar 30 22:22:00 BST 2025 - (in UTC): Sun Mar 30 21:22:00 UTC 2025 - From now: 3h41m38s left - - service: local.resticprofile.azure-dev.backup - permission: user - program: /usr/local/bin/resticprofile - working directory: /Users/cp/resticprofile - stdout path: local.resticprofile.azure-dev.backup.log - stderr path: local.resticprofile.azure-dev.backup.log - state: not running - runs (*): 0 - last exit code (*): (never exited) - * : since last (re)schedule or last reboot -``` - -The name of the task can be seen on the line `service: ...` - -2. start the task manually - -```shell -% launchctl start local.resticprofile.azure-dev.backup -``` - -You can check the task is currently running: - -```shell -2025/03/30 18:42:07 using configuration file: profiles.yaml - -Profile (or Group) azure-dev: backup schedule -============================================= - Original form: *-*-* 22:22:00 -Normalized form: *-*-* 22:22:00 - Next elapse: Sun Mar 30 22:22:00 BST 2025 - (in UTC): Sun Mar 30 21:22:00 UTC 2025 - From now: 3h39m52s left - - service: local.resticprofile.azure-dev.backup - permission: user - program: /usr/local/bin/resticprofile - working directory: /Users/cp/resticprofile - stdout path: local.resticprofile.azure-dev.backup.log - stderr path: local.resticprofile.azure-dev.backup.log - state: running - runs (*): 1 - last exit code (*): (never exited) - * : since last (re)schedule or last reboot - -``` diff --git a/docs/content/usage/getting_started.md b/docs/content/usage/getting_started.md index f0fcd883..d515d8de 100644 --- a/docs/content/usage/getting_started.md +++ b/docs/content/usage/getting_started.md @@ -103,7 +103,7 @@ default { ## Generate a secure password -**resticprofile** can generate a [secure password file]({{% relref "/usage/examples/keyfile" %}}) for you: +**resticprofile** can generate a [secure password file]({{% relref "/usage/keyfile" %}}) for you: ```shell resticprofile generate --random-key > password.txt diff --git a/docs/content/usage/hooks/_index.md b/docs/content/usage/hooks/_index.md index 7632dddb..ac13a8d5 100644 --- a/docs/content/usage/hooks/_index.md +++ b/docs/content/usage/hooks/_index.md @@ -1,5 +1,7 @@ --- -title: "Hooks - Examples" +title: "Hooks" +weight: 50 +alwaysopen: false --- {{% children sort="weight" %}} diff --git a/docs/content/usage/examples/keyfile.md b/docs/content/usage/keyfile.md similarity index 98% rename from docs/content/usage/examples/keyfile.md rename to docs/content/usage/keyfile.md index 0bb08381..8e078a96 100644 --- a/docs/content/usage/examples/keyfile.md +++ b/docs/content/usage/keyfile.md @@ -1,5 +1,6 @@ --- title: Generate Random Keys +weight: 60 --- Resticprofile includes a tool to generate cryptographically secure, base64-encoded random keys. Save the key to a file and use it as a strong key for Restic. diff --git a/docs/content/usage/memory.md b/docs/content/usage/memory.md deleted file mode 100644 index 73a62fe6..00000000 --- a/docs/content/usage/memory.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Memory" -weight: 15 ---- - - -## Minimum memory required - -restic can be memory hungry. I'm running a few servers with no swap and I managed to kill some of them during a backup. - -For that matter I've introduced a parameter in the `global` section called `min-memory`. The **default value is 100MB**. You can disable it by using a value of `0`. - -It compares against `(total - used)` which is probably the best way to know how much memory is available (that is including the memory used for disk buffers/cache). diff --git a/docs/content/usage/scheduling/_index.md b/docs/content/usage/scheduling/_index.md new file mode 100644 index 00000000..4672325e --- /dev/null +++ b/docs/content/usage/scheduling/_index.md @@ -0,0 +1,131 @@ +--- +title: "Scheduling" +weight: 20 +alwaysopen: false +--- + +Here's an example of a scheduling configuration: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +[default] + repository = "d:\\backup" + password-file = "key" + +[self] + inherit = "default" + + [self.retention] + after-backup = true + keep-within = "14d" + + [self.backup] + source = "." + schedule = [ "Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00" ] + schedule-permission = "user" + schedule-lock-wait = "10m" + + [self.prune] + schedule = "sun 3:30" + schedule-permission = "user" + schedule-lock-wait = "1h" +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +default: + repository: "d:\\backup" + password-file: key + +self: + inherit: default + retention: + after-backup: true + keep-within: 14d + backup: + source: "." + schedule: + - "Mon..Fri *:00,15,30,45" # every 15 minutes on weekdays + - "Sat,Sun 0,12:00" # twice a day on week-ends + schedule-permission: user + schedule-lock-wait: 10m + prune: + schedule: "sun 3:30" + schedule-permission: user + schedule-lock-wait: 1h +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"default" = { + "repository" = "d:\\backup" + "password-file" = "key" +} + +"self" = { + "inherit" = "default" + + "retention" = { + "after-backup" = true + "keep-within" = "14d" + } + + "backup" = { + "source" = "." + "schedule" = ["Mon..Fri *:00,15,30,45", "Sat,Sun 0,12:00"] + "schedule-permission" = "user" + "schedule-lock-wait" = "10m" + } + + "prune" = { + "schedule" = "sun 3:30" + "schedule-permission" = "user" + "schedule-lock-wait" = "1h" + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "default": { + "repository": "d:\\backup", + "password-file": "key" + }, + "self": { + "inherit": "default", + "retention": { + "after-backup": true, + "keep-within": "14d" + }, + "backup": { + "source": ".", + "schedule": [ + "Mon..Fri *:00,15,30,45", + "Sat,Sun 0,12:00" + ], + "schedule-permission": "user", + "schedule-lock-wait": "10m" + }, + "prune": { + "schedule": "sun 3:30", + "schedule-permission": "user", + "schedule-lock-wait": "1h" + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + +For more examples, refer to: +{{% children sort="weight" %}} diff --git a/docs/content/usage/change-schedule.md b/docs/content/usage/scheduling/change-schedule.md similarity index 97% rename from docs/content/usage/change-schedule.md rename to docs/content/usage/scheduling/change-schedule.md index b104da2a..f41c764a 100644 --- a/docs/content/usage/change-schedule.md +++ b/docs/content/usage/scheduling/change-schedule.md @@ -1,5 +1,6 @@ --- title: Changing Schedule Permission +weight: 30 --- When you update the `schedule-permission` field, you **must** unschedule and reschedule the profile to implement the change. diff --git a/docs/content/usage/scheduling/linux.md b/docs/content/usage/scheduling/linux.md new file mode 100644 index 00000000..b825393b --- /dev/null +++ b/docs/content/usage/scheduling/linux.md @@ -0,0 +1,208 @@ +--- +title: "Example: Linux" +weight: 32 +--- + +With this example of configuration for Linux: + +{{< tabs groupid="config-with-json" >}} +{{% tab title="toml" %}} + +```toml +version = "1" + +[default] + password-file = "key" + repository = "/tmp/backup" + +[test1] + inherit = "default" + + [test1.backup] + source = "./" + schedule = "*:00,15,30,45" + schedule-permission = "user" + schedule-lock-wait = "15m" + + [test1.check] + schedule = "*-*-1" + schedule-permission = "user" + schedule-lock-wait = "15m" +``` + +{{% /tab %}} +{{% tab title="yaml" %}} + +```yaml +version: "1" + +default: + password-file: key + repository: /tmp/backup + +test1: + inherit: default + backup: + source: ./ + schedule: "*:00,15,30,45" + schedule-permission: user + schedule-lock-wait: 15m + check: + schedule: "*-*-1" + schedule-permission: user + schedule-lock-wait: 15m + +``` + +{{% /tab %}} +{{% tab title="hcl" %}} + +```hcl +"default" = { + "password-file" = "key" + "repository" = "/tmp/backup" +} + +"test1" = { + "inherit" = "default" + + "backup" = { + "source" = "./" + "schedule" = "*:00,15,30,45" + "schedule-permission" = "user" + "schedule-lock-wait" = "15m" + } + + "check" = { + "schedule" = "*-*-1" + "schedule-permission" = "user" + "schedule-lock-wait" = "15m" + } +} +``` + +{{% /tab %}} +{{% tab title="json" %}} + +```json +{ + "version": "1", + "default": { + "password-file": "key", + "repository": "/tmp/backup" + }, + "test1": { + "inherit": "default", + "backup": { + "source": "./", + "schedule": "*:00,15,30,45", + "schedule-permission": "user", + "schedule-lock-wait": "15m" + }, + "check": { + "schedule": "*-*-1", + "schedule-permission": "user", + "schedule-lock-wait": "15m" + } + } +} +``` + +{{% /tab %}} +{{< /tabs >}} + + +```shell +$ resticprofile -c examples/linux.yaml -n test1 schedule + +Analyzing backup schedule 1/1 +================================= + Original form: *:00,15,30,45 +Normalized form: *-*-* *:00,15,30,45:00 + Next elapse: Thu 2020-07-23 17:15:00 BST + (in UTC): Thu 2020-07-23 16:15:00 UTC + From now: 6min left + +2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-backup@profile-test1.service +2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer +Created symlink /home/user/.config/systemd/user/timers.target.wants/resticprofile-backup@profile-test1.timer → /home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer. +2020/07/23 17:08:51 scheduled job test1/backup created + +Analyzing check schedule 1/1 +================================= + Original form: *-*-1 +Normalized form: *-*-01 00:00:00 + Next elapse: Sat 2020-08-01 00:00:00 BST + (in UTC): Fri 2020-07-31 23:00:00 UTC + From now: 1 weeks 1 days left + +2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-check@profile-test1.service +2020/07/23 17:08:51 writing /home/user/.config/systemd/user/resticprofile-check@profile-test1.timer +Created symlink /home/user/.config/systemd/user/timers.target.wants/resticprofile-check@profile-test1.timer → /home/user/.config/systemd/user/resticprofile-check@profile-test1.timer. +2020/07/23 17:08:51 scheduled job test1/check created +``` + +The `status` command shows a combination of `journalctl` displaying errors (only) in the last month and `systemctl status`: + +```shell +$ resticprofile -c examples/linux.yaml -n test1 status + +Analyzing backup schedule 1/1 +================================= + Original form: *:00,15,30,45 +Normalized form: *-*-* *:00,15,30,45:00 + Next elapse: Tue 2020-07-28 15:15:00 BST + (in UTC): Tue 2020-07-28 14:15:00 UTC + From now: 4min 44s left + +Recent log (>= warning in the last month) +========================================== +-- Logs begin at Wed 2020-06-17 11:09:19 BST, end at Tue 2020-07-28 15:10:10 BST. -- +Jul 27 20:48:01 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. +Jul 27 21:00:55 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. +Jul 27 21:15:34 Desktop76 systemd[2986]: Failed to start resticprofile backup for profile test1 in examples/linux.yaml. + +Systemd timer status +===================== +● resticprofile-backup@profile-test1.timer - backup timer for profile test1 in examples/linux.yaml + Loaded: loaded (/home/user/.config/systemd/user/resticprofile-backup@profile-test1.timer; enabled; vendor preset: enabled) + Active: active (waiting) since Tue 2020-07-28 15:10:06 BST; 8s ago + Trigger: Tue 2020-07-28 15:15:00 BST; 4min 44s left + +Jul 28 15:10:06 Desktop76 systemd[2951]: Started backup timer for profile test1 in examples/linux.yaml. + + +Analyzing check schedule 1/1 +================================= + Original form: *-*-1 +Normalized form: *-*-01 00:00:00 + Next elapse: Sat 2020-08-01 00:00:00 BST + (in UTC): Fri 2020-07-31 23:00:00 UTC + From now: 3 days left + +Recent log (>= warning in the last month) +========================================== +-- Logs begin at Wed 2020-06-17 11:09:19 BST, end at Tue 2020-07-28 15:10:10 BST. -- +Jul 27 19:39:59 Desktop76 systemd[2986]: Failed to start resticprofile check for profile test1 in examples/linux.yaml. + +Systemd timer status +===================== +● resticprofile-check@profile-test1.timer - check timer for profile test1 in examples/linux.yaml + Loaded: loaded (/home/user/.config/systemd/user/resticprofile-check@profile-test1.timer; enabled; vendor preset: enabled) + Active: active (waiting) since Tue 2020-07-28 15:10:07 BST; 7s ago + Trigger: Sat 2020-08-01 00:00:00 BST; 3 days left + +Jul 28 15:10:07 Desktop76 systemd[2951]: Started check timer for profile test1 in examples/linux.yaml. + + +``` + +And `unschedule`: + +```shell +$ resticprofile -c examples/linux.yaml -n test1 unschedule +Removed /home/user/.config/systemd/user/timers.target.wants/resticprofile-backup@profile-test1.timer. +2020/07/23 17:13:42 scheduled job test1/backup removed +Removed /home/user/.config/systemd/user/timers.target.wants/resticprofile-check@profile-test1.timer. +2020/07/23 17:13:42 scheduled job test1/check removed +``` diff --git a/docs/content/usage/scheduling/macos.md b/docs/content/usage/scheduling/macos.md new file mode 100644 index 00000000..339c6e94 --- /dev/null +++ b/docs/content/usage/scheduling/macos.md @@ -0,0 +1,91 @@ +--- +title: "Example: MacOS" +weight: 33 +--- + +Here's an example of scheduling a backup profile named `azure-dev`: + +```shell +% resticprofile -n azure-dev schedule +2025/03/30 18:40:13 using configuration file: profiles.yaml + +Profile (or Group) azure-dev: backup schedule +============================================= + Original form: 22:22 +Normalized form: *-*-* 22:22:00 + Next elapse: Sun Mar 30 22:22:00 BST 2025 + (in UTC): Sun Mar 30 21:22:00 UTC 2025 + From now: 3h41m46s left + +2025/03/30 18:40:13 scheduled job azure-dev/backup created + +``` + +{{% notice info %}} + +In some cases, macOS may request permission to access the network, an external volume (like a USB drive), or a protected directory. A message window will appear while the backup runs in the background. +{{% /notice %}} + +![access files popup window]({{< absolute "configuration/schedules/removable_volume.png" nohtml >}}) + +You may want to start the task now so you can grant special permissions: + +1. Retrieve the task name using the status command: + +```shell +% resticprofile -n azure-dev status +2025/03/30 18:40:21 using configuration file: profiles.yaml + +Profile (or Group) azure-dev: backup schedule +============================================= + Original form: *-*-* 22:22:00 +Normalized form: *-*-* 22:22:00 + Next elapse: Sun Mar 30 22:22:00 BST 2025 + (in UTC): Sun Mar 30 21:22:00 UTC 2025 + From now: 3h41m38s left + + service: local.resticprofile.azure-dev.backup + permission: user + program: /usr/local/bin/resticprofile + working directory: /Users/cp/resticprofile + stdout path: local.resticprofile.azure-dev.backup.log + stderr path: local.resticprofile.azure-dev.backup.log + state: not running + runs (*): 0 + last exit code (*): (never exited) + * : since last (re)schedule or last reboot +``` + +The name of the task can be seen on the line `service: ...` + +2. start the task manually + +```shell +% launchctl start local.resticprofile.azure-dev.backup +``` + +You can check the task is currently running: + +```shell +2025/03/30 18:42:07 using configuration file: profiles.yaml + +Profile (or Group) azure-dev: backup schedule +============================================= + Original form: *-*-* 22:22:00 +Normalized form: *-*-* 22:22:00 + Next elapse: Sun Mar 30 22:22:00 BST 2025 + (in UTC): Sun Mar 30 21:22:00 UTC 2025 + From now: 3h39m52s left + + service: local.resticprofile.azure-dev.backup + permission: user + program: /usr/local/bin/resticprofile + working directory: /Users/cp/resticprofile + stdout path: local.resticprofile.azure-dev.backup.log + stderr path: local.resticprofile.azure-dev.backup.log + state: running + runs (*): 1 + last exit code (*): (never exited) + * : since last (re)schedule or last reboot + +``` diff --git a/docs/content/usage/scheduling/windows.md b/docs/content/usage/scheduling/windows.md new file mode 100644 index 00000000..cafd502e --- /dev/null +++ b/docs/content/usage/scheduling/windows.md @@ -0,0 +1,109 @@ +--- +title: "Example: Windows" +weight: 31 +--- + +{{% notice note %}} +If you create a task with `user` permission under Windows, you will need to enter your password to validate the task. + +It's a requirement of the task scheduler. I'm inviting you to review the code to make sure I'm not emailing your password to myself. Seriously you shouldn't trust anyone. +{{% /notice %}} + +Example of the `schedule` command under Windows (with git bash): + +```shell +$ resticprofile -c examples/windows.yaml -n self schedule + +Analyzing backup schedule 1/2 +================================= + Original form: Mon..Fri *:00,15,30,45 +Normalized form: Mon..Fri *-*-* *:00,15,30,45:00 + Next elapse: Wed Jul 22 21:30:00 BST 2020 + (in UTC): Wed Jul 22 20:30:00 UTC 2020 + From now: 1m52s left + +Analyzing backup schedule 2/2 +================================= + Original form: Sat,Sun 0,12:00 +Normalized form: Sat,Sun *-*-* 00,12:00:00 + Next elapse: Sat Jul 25 00:00:00 BST 2020 + (in UTC): Fri Jul 24 23:00:00 UTC 2020 + From now: 50h31m52s left + +Creating task for user Creative Projects +Task Scheduler requires your Windows password to validate the task: + +2020/07/22 21:28:15 scheduled job self/backup created + +Analyzing retention schedule 1/1 +================================= + Original form: sun 3:30 +Normalized form: Sun *-*-* 03:30:00 + Next elapse: Sun Jul 26 03:30:00 BST 2020 + (in UTC): Sun Jul 26 02:30:00 UTC 2020 + From now: 78h1m44s left + +2020/07/22 21:28:22 scheduled job self/retention created +``` + +To see the status of the triggers, you can use the `status` command: + +```shell +$ resticprofile -c examples/windows.yaml -n self status + +Analyzing backup schedule 1/2 +================================= + Original form: Mon..Fri *:00,15,30,45 +Normalized form: Mon..Fri *-*-* *:00,15,30,45:00 + Next elapse: Wed Jul 22 21:30:00 BST 2020 + (in UTC): Wed Jul 22 20:30:00 UTC 2020 + From now: 14s left + +Analyzing backup schedule 2/2 +================================= + Original form: Sat,Sun 0,12:* +Normalized form: Sat,Sun *-*-* 00,12:*:00 + Next elapse: Sat Jul 25 00:00:00 BST 2020 + (in UTC): Fri Jul 24 23:00:00 UTC 2020 + From now: 50h29m46s left + + Task: \resticprofile backup\self backup + User: Creative Projects + Working Dir: D:\Source\resticprofile + Exec: D:\Source\resticprofile\resticprofile.exe --no-ansi --config examples/windows.yaml --name self backup + Enabled: true + State: ready + Missed runs: 0 + Last Run Time: 2020-07-22 21:30:00 +0000 UTC + Last Result: 0 + Next Run Time: 2020-07-22 21:45:00 +0000 UTC + +Analyzing retention schedule 1/1 +================================= + Original form: sun 3:30 +Normalized form: Sun *-*-* 03:30:00 + Next elapse: Sun Jul 26 03:30:00 BST 2020 + (in UTC): Sun Jul 26 02:30:00 UTC 2020 + From now: 77h59m46s left + + Task: \resticprofile backup\self retention + User: Creative Projects + Working Dir: D:\Source\resticprofile + Exec: D:\Source\resticprofile\resticprofile.exe --no-ansi --config examples/windows.yaml --name self forget + Enabled: true + State: ready + Missed runs: 0 + Last Run Time: 1999-11-30 00:00:00 +0000 UTC + Last Result: 267011 + Next Run Time: 2020-07-26 03:30:00 +0000 UTC + +``` + +To remove the schedule, use the `unschedule` command: + +```shell +$ resticprofile -c examples/windows.yaml -n self unschedule +2020/07/22 21:34:51 scheduled job self/backup removed +2020/07/22 21:34:51 scheduled job self/retention removed +``` + diff --git a/docs/content/usage/variables/_index.md b/docs/content/usage/variables/_index.md new file mode 100644 index 00000000..302685e6 --- /dev/null +++ b/docs/content/usage/variables/_index.md @@ -0,0 +1,8 @@ +--- +title: "Variables" +weight: 30 +alwaysopen: false +--- + +{{% children sort="weight" %}} + diff --git a/docs/content/usage/variables.md b/docs/content/usage/variables/inheritance-and-variables.md similarity index 98% rename from docs/content/usage/variables.md rename to docs/content/usage/variables/inheritance-and-variables.md index 268559e2..792c81d9 100644 --- a/docs/content/usage/variables.md +++ b/docs/content/usage/variables/inheritance-and-variables.md @@ -279,4 +279,4 @@ Now you can reuse the same generic configuration in another profile. You might have noticed the `read-data-subset` in the `check` section which will read a seventh of the data every day, meaning the whole repository data will be checked over a week. You can find [more information about this trick](https://stackoverflow.com/a/72465098). -More examples can be found [here]({{% relref "/usage/variable-example" %}}). +More examples can be found [here]({{% relref "/usage/variables/list-variables" %}}). diff --git a/docs/content/usage/variable-example.md b/docs/content/usage/variables/list-variables.md similarity index 99% rename from docs/content/usage/variable-example.md rename to docs/content/usage/variables/list-variables.md index c679b6eb..9a90abc4 100644 --- a/docs/content/usage/variable-example.md +++ b/docs/content/usage/variables/list-variables.md @@ -1,5 +1,5 @@ --- -title: "Variables - Examples" +title: "More on Variables" --- {{< toc >}} From 350894a6f56ba04d31dc000ba08ca9d95ed34778 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 18:18:38 -0500 Subject: [PATCH 28/29] Adding ntfy example and slight modification to hooks --- docs/content/usage/hooks/body-template.md | 1 + docs/content/usage/hooks/healthchecks.md | 1 + docs/content/usage/hooks/ntfy.md | 49 +++++++++++++++++++++++ 3 files changed, 51 insertions(+) create mode 100644 docs/content/usage/hooks/ntfy.md diff --git a/docs/content/usage/hooks/body-template.md b/docs/content/usage/hooks/body-template.md index d446c81b..8df72f6a 100644 --- a/docs/content/usage/hooks/body-template.md +++ b/docs/content/usage/hooks/body-template.md @@ -1,5 +1,6 @@ --- title: "Message Body Template" +weight: 30 --- You can use a standard go template to build the webhook body. It has to be defined in a separate file (otherwise it would clash with the configuration as a go template itself). diff --git a/docs/content/usage/hooks/healthchecks.md b/docs/content/usage/hooks/healthchecks.md index 0a4ae1db..5fe2966d 100644 --- a/docs/content/usage/hooks/healthchecks.md +++ b/docs/content/usage/hooks/healthchecks.md @@ -1,5 +1,6 @@ --- title: "Sending to healthchecks.io" +weight: 20 --- For more information, refer to [Hooks - HTTP]({{% relref "configuration/hooks/http_hooks/#send-http-messages-before-and-after-a-job" %}}) diff --git a/docs/content/usage/hooks/ntfy.md b/docs/content/usage/hooks/ntfy.md new file mode 100644 index 00000000..980f1844 --- /dev/null +++ b/docs/content/usage/hooks/ntfy.md @@ -0,0 +1,49 @@ +--- +title: "Using ntfy" +weight: 10 +--- + +This configuration executes the following: +- Makes a template profile called "default" [(learn more)]({{% relref "/configuration/variables/templates/" %}}) +- Creates a `backup` on a schedule every day at 12am [(learn more)]({{% relref "/configuration/schedules/configuration/" %}}) + - After a fail or success, sends a message through the `ntfy` service using a POST request [(learn more)]({{% relref "/configuration/hooks/http_hooks/" %}}) +- Creates a `forget` schedule that runs every day at 12:05am + - Prunes all non-matching entries [(learn more)]({{% relref "/reference/profile/forget/" %}}) + - Keeps every daily backup for the past week (7 backups), every weekly backup for the past month (4 backups), and a monthly backup for 75 years. + +{{< tabs groupid="example-ntfy" >}} +{{% tab title="toml" %}} +```toml +default: + insecure-no-password: true + backup: + schedule: "*-*-* 00:00:00" + schedule-permission: user_logged_on + send-after: + method: POST + url: [[YOUR_URL_HERE]] + headers: + - name: Title + value: "{{.Profile.Name}} ran successfully!" + - name: Priority + value: "low" + send-after-fail: + method: POST + url: [[YOUR_URL_HERE]] + headers: + - name: Title + value: "{{.Profile.Name}} failed!" + - name: Tags + value: "warning" + - name: Priority + value: "high" + forget: + schedule: "*-*-* 00:05:00" + schedule-permission: user_logged_on + keep-within-daily: '7d' + keep-within-weekly: '1m' + keep-within-monthly: '75y' + prune: true +``` +{{% /tab %}} +{{< /tabs >}} From 3e096b3a5db6726a42777fb8fd27327c81c5a6d0 Mon Sep 17 00:00:00 2001 From: Inventhrice <45127310+Inventhrice@users.noreply.github.com> Date: Tue, 30 Dec 2025 18:37:07 -0500 Subject: [PATCH 29/29] Fixing issues brought up by the bot; being mindful of the fact that reference dir is not in the repo --- docs/content/installation/docker.md | 24 ++++++++++++++++++- .../usage/configuration/configWinheritence.md | 2 +- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/content/installation/docker.md b/docs/content/installation/docker.md index b266ec2a..c9381f34 100644 --- a/docs/content/installation/docker.md +++ b/docs/content/installation/docker.md @@ -17,4 +17,26 @@ docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/res Resticprofile's docker images also include restic and rclone. -For further reference, consult the [docker reference page]({{% relref "/reference/docker" %}}). +{{< toc >}} + +## Configuration + +By default, the resticprofile container starts at `/resticprofile`. So you can feed a configuration this way: + +```shell +docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/resticprofile +``` + +## List profiles + +```shell +docker run -it --rm -v $PWD/examples:/resticprofile ghcr.io/creativeprojects/resticprofile profiles +``` + +## Container host name + +To set a specific hostname, use the `-h` or `--hostname` flag with `docker run`: + +```shell +docker run -it --rm -v $PWD:/resticprofile -h my-hostname ghcr.io/creativeprojects/resticprofile -n profile backup +``` diff --git a/docs/content/usage/configuration/configWinheritence.md b/docs/content/usage/configuration/configWinheritence.md index f6bb399e..b793a35e 100644 --- a/docs/content/usage/configuration/configWinheritence.md +++ b/docs/content/usage/configuration/configWinheritence.md @@ -1,6 +1,6 @@ --- title: "Example: Using Inheritance" -wieght: 20 +weight: 20 --- Here's a more complex configuration file showing profile inheritance and two backup profiles using the same repository: