Add aggregator docs with crontab

docs/csaf_aggregator.md

@@ -15,31 +15,64 @@ Help Options:
   -h, --help               Show this help message
 ```
 
-Usage example:
+Usage example for a single run, to test if the config is good:
-``` ./csaf_aggregator -c docs/examples/aggregator.toml ```
+```bash
+./csaf_aggregator -c docs/examples/aggregator.toml
+```
+
+Once the config is good, you can run the aggregator periodically
+in two modes. For instance using `cron` on Ubuntu and after placing
+the config file in `/etc/csaf_aggregator.toml`:
+
+```bash
+mkdir /var/log/csaf_aggregator
+mkdir ~www-data/bin
+cp bin-linux-amd64/csaf_aggregator ~www-data/bin/
+chown www-data.www-data -R ~www-data/bin /var/log/csaf_aggregator
+
+# list current crontab
+crontab -u www-data -l
+# edit crontab (add lines like example below)
+crontab -u www-data -e
+```
+
+Crontab example, running the full mode one a day and updating
+interim advisories every 60 minutes:
+
+```crontab
+SHELL=/bin/bash
+# run full mode in the night at 04:00
+0 4 * * * $HOME/bin/csaf_aggregator --config /etc/csaf_aggregator.toml >> /var/log/csaf_aggregator/full.log 2>&1
+# run in interim mode once per hour at 30 minutes, e.g. 00:30, 01:30, ...
+30 0-23 * * * $HOME/bin/csaf_aggregator --config /etc/csaf_aggregator.toml --interim >> /var/log/csaf_aggregator/interim.log 2>&1
+```
+
 
 ### config options
 
-*todo*
+The following options can be used in the config file in TOML format:
 
 ```
-workers
+workers  // number of parallel workers to start (default 10)
-folder
+folder   // target folder on disc for writing the downloaded documents
-web
+web      // directory to be served by the webserver
-domain
+domain   // base url where the contents will be reachable from outside
-rate
+rate     // overall downloading limit per worker
-insecure
+insecure // do not check validity of TLS certificates
-aggregator
+aggregator    // table with basic infos for the aggregator object
-providers
+providers     // array of tables, each entry to be mirrored or listed
-key
+key           // OpenPGP key
-openpgp_url
+openpgp_url   // URL where the OpenPGP public key part can be found
-passphrase
+passphrase    // passphrase of the OpenPGP key
-allow_single_provider
+lock_file     // path to lockfile, to stop other instances if one is not done
-lock_file
+interim_years // limiting the years for which interim documents are searched
-interim_years
+allow_single_provider // debugging option
 ```
 
-`providers` is a list of tables, each allowing
+Rates are specified as floats in HTTPS operations per second.
+0 means no limit.
+
+`providers` is an array of tables, each allowing
 ```
 name
 domain
@@ -47,3 +80,6 @@ rate
 insecure
 ```
 
+#### Example config file
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/examples/aggregator.toml) -->
+<!-- MARKDOWN-AUTO-DOCS:END -->

docs/examples/aggregator.toml

@@ -1,9 +1,11 @@
 workers = 2
-folder = "/var/csaf-aggregator"
+folder = "/var/csaf_aggregator"
-web = "/var/csaf-aggregator/html"
+lock_file = "/var/csaf_aggregator/run.lock"
+web = "/var/csaf_aggregator/html"
 domain = "https://localhost:9443"
 rate = 10.0
 insecure = true
+
 [aggregator]
   category = "aggregator"
   name = "Example Development CSAF Aggregator"
@@ -26,8 +28,7 @@ insecure = true
 #key =
 #passphrase =
 
-# for testing, the specifiation requires at least two
+# specification requires at least two providers (default),
+# to override for testing, enable:
 # allow_single_provider = true
 
-
-