Update to Documentation!

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

docs/content/_index.md

@@ -4,40 +4,7 @@ title: resticprofile
 description: Configuration profiles manager for restic backup
 ---
 
-Configuration profiles manager for [restic backup](https://restic.net/)
+**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 restic backup. Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority.
+Although creating a configuration file for restic has been [discussed](https://github.com/restic/restic/issues/16), it remains a low priority task.
 
-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)
-
-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*

docs/content/changelog.md

@@ -1,6 +1,6 @@
 ---
 archetype: chapter
-pre: <b>8. </b>
+pre: <b>7. </b>
 title: Release Notes
 weight: 8
 ---

docs/content/configuration/_index.md

@@ -1,12 +1,17 @@
 +++
 archetype = "chapter"
-pre = "<b>2. </b>"
+pre = "<b>3. </b>"
 title = "Configuration file"
-weight = 2
+weight = 3
 +++
 
+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_.
+* 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.
@@ -65,106 +70,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  %}}

docs/content/configuration/hooks/_index.md

@@ -0,0 +1,7 @@
+---
+title: Hooks
+weight: 60
+alwaysopen: false
+---
+
+{{% children sort="weight" depth="2" %}}

docs/content/configuration/copy.md → 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 >}}
+{{< /tabs >}}

docs/content/configuration/hooks/http_hooks.md

@@ -0,0 +1,169 @@
+---
+title: "Hooks - HTTP"
+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.
+
+The sections that allow sending HTTP hooks are:
+- backup
+- copy
+- check
+- forget
+- prune
+
+{{% notice tip %}}
+You might notice that's the same sections that can also be scheduled
+{{% /notice %}}
+
+Each of these commands can send 4 different types of hooks:
+
+- send-before
+- send-after
+- send-after-fail
+- send-finally
+
+The configuration is the same for each of these 4 types of hooks:
+
+| Name | Required | Default | Notes |
+|:-----|:---------|:--------|:------|
+| url | Yes | None | URL of your Webhook |
+| method | No | GET | This is the HTTP method (GET, POST, HEAD, etc.) |
+| skip-tls-verification | No | False | **This is not recommended**: Use only if you're using your own server with a self-signed certificate |
+| headers | No | User-Agent set to resticprofile | This is a subsection with a list of `name` and `value` |
+| body | No | Empty | Used to send data to the Webhook (POST, PUT, PATCH) |
+| body-template | No | None | Template file to generate the body (in go template format) |
+
+
+A few environment variables will be available to construct the url and the body:
+- `PROFILE_NAME`
+- `PROFILE_COMMAND`: backup, check, forget, etc.
+
+Additionally, for the `send-after-fail` hooks, these environment variables will be available:
+- `ERROR` containing the latest error message
+- `ERROR_COMMANDLINE` containing the command line that failed
+- `ERROR_EXIT_CODE` containing the exit code of the command line that failed
+- `ERROR_STDERR` containing any message that the failed command sent to the standard error (stderr)
+
+URL encoding is applayed for variables `ERROR`, `ERROR_COMMANDLINE` and `ERROR_STDERR` if they are used in URL.
+
+The `send-finally` hooks are also getting the environment of `send-after-fail` when any previous operation has failed (except any `send` operation).
+
+Failures in any `send-*` are logged but do not influence environment or return code.
+
+## body-template
+
+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**
+- `Error`          **ErrorContext**
+- `Stdout`         **string**
+
+The type **ErrorContext** is available after an error occurred (otherwise all fields are blank):
+- `Message`     **string**
+- `CommandLine` **string**
+- `ExitCode`    **string**
+- `Stderr`      **string**
+
+## 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)
+
+The parameter is in the `global` section and is called `ca-certificates`: it contains a list of certificate files (PEM).
+
+### timeout
+
+The default timeout for all HTTP requests is 30 seconds.
+
+You can change the default timeout in the `global` section with a parameter called `send-timeout`.
+
+The format is like:
+- 30s
+- 2m
+- 1m20s
+
+### global configuration example
+
+
+{{< tabs groupid="config-with-json" >}}
+{{% tab title="toml" %}}
+
+```toml
+version = "1"
+
+[global]
+  send-timeout = "10s"
+  ca-certificates = [ "ca-chain.cert.pem" ]
+```
+
+
+{{% /tab %}}
+{{% tab title="yaml" %}}
+
+```yaml
+version: "1"
+
+global:
+  send-timeout: 10s
+  ca-certificates:
+    - ca-chain.cert.pem
+
+```
+
+{{% /tab %}}
+{{% tab title="hcl" %}}
+
+```hcl
+
+global {
+  send-timeout = "10s"
+  ca-certificates = "ca-chain.cert.pem"
+}
+```
+
+{{% /tab %}}
+{{% tab title="json" %}}
+
+```json
+{
+  "version": "1",
+  "global": {
+    "send-timeout": "10s",
+    "ca-certificates": [
+      "ca-chain.cert.pem"
+    ]
+  }
+}
+```
+
+{{% /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 %}}