SystemSh0cker/gocsaf
1
0
Fork 0
mirror of https://github.com/gocsaf/csaf.git synced 2025-12-22 11:55:40 +01:00
Code Issues Releases Activity Actions

Improve aggregator docs and config

Browse source 
* Fix that TOML key `update_interval` can be processed on top level.
 * Add missing keys to top level and provider entries.
 * Move explanations to first mention of keys.
 * Describe overriding ability and defaults early on and only once.
This commit is contained in:
Bernhard Reiter 2023-02-28 14:53:36 +01:00 • committed by Sascha L. Teichmann
parent 704a98ab38
commit 1bdf207e4b
2 changed files with 43 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

2
cmd/csaf_aggregator/config.go
View file

@ -87,7 +87,7 @@ type config struct {
// UpdateInterval is used for publishers as the mandatory field // UpdateInterval is used for publishers as the mandatory field
// 'update_interval'. // 'update_interval'.
UpdateInterval *string UpdateInterval *string `toml:"update_interval"`
keyMu sync.Mutex keyMu sync.Mutex
key *crypto.Key key *crypto.Key

83
docs/csaf_aggregator.md
View file

@ -77,43 +77,43 @@ Each _key_ in the following table is optional and
can be used directly in the file. If given it overrides the internal default. can be used directly in the file. If given it overrides the internal default.
```go ```go
workers // number of parallel workers to start (default 10) workers // number of parallel workers to start (default 10)
folder // target folder on disc for writing the downloaded documents (default "/var/www") folder // target folder on disc for writing the downloaded documents (default "/var/www")
web // directory to be served by the webserver (default "/var/www/html") web // directory to be served by the webserver (default "/var/www/html")
domain // base url where the contents will be reachable from outside (default "https://example.com") domain // base url where the contents will be reachable from outside (default "https://example.com")
rate // overall downloading limit per worker (default: no limiting) rate // downloading limit per worker in HTTPS req/s (default: no limiting)
insecure // do not check validity of TLS certificates insecure // do not check validity of TLS certificates
write_indices // write index.txt and changes.csv write_indices // write index.txt and changes.csv
openpgp_private_key // OpenPGP private key (must have no passphrase set, if update_interval // to indicate the collection interval for a provider (default ""on best effort")
// you want to be able to run unattended, e.g. via cron.) create_service_document // write a service.json to the ROLIE feed docs for a provider (default false)
openpgp_public_key // OpenPGP public key categories // configure ROLIE category values for a provider
passphrase // passphrase of the OpenPGP key openpgp_private_key // OpenPGP private key (must have no passphrase set, if
lock_file // path to lockfile, to stop other instances if one is not done // you want to be able to run unattended, e.g. via cron.)
interim_years // limiting the years for which interim documents are searched (default 0) openpgp_public_key // OpenPGP public key
verbose // print more diagnostic output, e.g. https request passphrase // passphrase of the OpenPGP key
allow_single_provider // debugging option lock_file // path to lockfile, to stop other instances if one is not done (default no locking)
interim_years // limiting the years for which interim documents are searched (default 0)
verbose // print more diagnostic output, e.g. https requests (default false)
allow_single_provider // debugging option (default false)
``` ```
Next we have two TOML _tables_: Next we have two TOML _tables_:
``` ```
remote_validator // table use remote validation checker aggregator // basic infos for the aggregator object
aggregator // table with basic infos for the aggregator object remote_validator // config for optional remote validation checker
```
[see the provider config](csaf_provider.md#provider-options) about
how to configure `remote_validator`.
At last there is the TOML _array of tables_:
```
providers // each entry to be mirrored or listed
``` ```
and a TOML _array of tables_: where at least 2 providers have to be configured.
``` With each _table_ allowing:
providers // array of tables, each entry to be mirrored or listed
```
At least 2 providers have to be configured.
Rates are specified as floats in HTTPS operations per second.
0 means no limit. The rates can be specified per provider. Any provider
which has no specified rate will use the configured default. If
no default was configured, the internal default with no limits is used.
`providers` is an array of tables, each allowing
``` ```
name name
domain domain
@ -122,36 +122,35 @@ insecure
write_indices write_indices
category category
update_interval update_interval
create_service_document
categories
``` ```
Any provider needs a valid name and domain. The other Where valid `name` and `domain` settings are required.
options are optional.
If you want an entry to be listed instead of mirrored If you want an entry to be listed instead of mirrored
in a `aggregator.category == "aggregator"` instance, in a `aggregator.category == "aggregator"` instance,
set `category` to `lister` in the entry. set `category` to `lister` in the entry.
Otherwise it is recommended to not set `category` for entries. Otherwise it is recommended to not set `category` for entries.
If a provider's `domain` starts with `https://` it is considered a publisher. The remaining _keys_ per entry in the _table_ `providers`
These publishers are added to the `csaf_publishers` list, written are optional and will take precedence instead
to the resulting `aggregator.json`. of the directly given _keys_ in the TOML file and the internal defaults.
Each publisher must announce an `update_interval` there.
This can be configured for each entry, by the config option with the same name.
If not given it is taken from the configured default
Otherwise, the internal default "on best effort" is used.
If a provider's `create_service_document` option is set to true, If a provider's `domain` starts with `https://` it is considered a publisher.
a `service.json` will be written listing its ROLIE feed documents. These publishers are added to the `csaf_publishers` list, which is written
If it is not set or set to false, then no `service.json` will be written. to the `aggregator.json`.
To offer an easy way of assorting CSAF documents by criteria like To offer an easy way of assorting CSAF documents by criteria like
document category, languages or values of the branch category within document category, languages or values of the branch category within
the product tree, ROLIE category values can be configured. This can either the product tree, ROLIE category values can be configured in `categories`.
This can either
be done using an array of strings taken literally or, by prepending `"expr:"`. be done using an array of strings taken literally or, by prepending `"expr:"`.
The latter is evaluated as JSONPath and the result will be added into the The latter is evaluated as JSONPath and the result will be added into the
categories document. For a more detailed explanation and examples, categories document. For a more detailed explanation and examples,
[refer to the provider config](csaf_provider.md#provider-options). [refer to the provider config](csaf_provider.md#provider-options).
#### Example config file #### Example config file
<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/examples/aggregator.toml) --> <!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/examples/aggregator.toml) -->
<!-- The below code snippet is automatically added from ../docs/examples/aggregator.toml --> <!-- The below code snippet is automatically added from ../docs/examples/aggregator.toml -->