From 4700e8765329e3de93b54f6efd0157191b168f76 Mon Sep 17 00:00:00 2001
From: Stefan Tatschner <stefan.tatschner@aisec.fraunhofer.de>
Date: Fri, 28 Oct 2022 13:30:21 +0200
Subject: [PATCH] docs: Add documentation about gallia.toml and hooks

---
 docs/config.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md  |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 docs/config.md

diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 000000000..65da5def5
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,48 @@
+<!--
+SPDX-FileCopyrightText: AISEC Pentesting Team
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Configuration
+
+## gallia.toml
+
+All `gallia` settings stem from the commandline interface.
+The documentation for all available settings per subcommand is available via `-h/--help`.
+Frequently used settings can be put in a configfile which is called `gallia.toml`.
+Settings from the config file set the **default** of the respective commandline option.
+The config can always be overwritten by manually setting the relevant cli option.
+
+The configuration file `gallia.toml` is written in [TOML](https://toml.io/en/). 
+Inheritence is not supported; the first file is loaded.
+The `gallia.toml` file is loaded from these locations (in this particular order):
+
+* path specified in the env variable `GALLIA_CONFIG`; see {doc}`../env`.
+* current directory
+* current Git root (if the current directory is a Git repository)
+* `$XDG_CONFIG_HOME/gallia/gallia.toml`
+* `~/.config/gallia/gallia.toml`
+
+Only some cli options are exposed to the config file.
+The available config settings can be obtained from `gallia --template`.
+The output of `--template` is maintained to be up to date and is intended as a starting point.
+
+## Hooks
+
+`gallia` supports hooks for preparation or cleanup/postprocessing tasks.
+Alternatively, they can be useful for e.g. sending notifications about the exit_code via e.g. matrix or ntfy.sh.
+Hooks are shell scripts which are executed before (= pre-hook) or after (= post-hook) the `main()` method.
+These scripts can be specified via `--pre-hook` or `--post-hook` or via `gallia.toml` as well.
+
+The hook scripts have these environment variables set:
+
+GALLIA_HOOK
+: Either `pre` or `post`.
+
+GALLIA_ARTIFACTS_DIR
+: Path to the artifactsdir for the current testrun.
+
+GALLIA_EXIT_CODE
+: Only set for post-hooks; is set to the exit_code which `gallia` will use after the hook terminates.
+  For instance GALLIA_EXIT_CODE different from zero means that the current testrun failed.
diff --git a/docs/index.md b/docs/index.md
index 12c039b97..ac16794ba 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -25,6 +25,7 @@ Acting as a generic interface, the [logging](https://fraunhofer-aisec.github.io/
 
 setup
 automation
+config
 transports
 env
 logging