From abc8b109882528996c799ffe249200c6383c4466 Mon Sep 17 00:00:00 2001 From: "Bernhard E. Reiter" Date: Tue, 17 Oct 2023 18:53:53 +0200 Subject: [PATCH] docs: improve timerange documentation (#482) * docs: improve timerange documentation * add a documentation section to the downloader docs for the timerange-option. * point aggregator and checker docs to the downloader section for timerange. * docs: use a better example for timerange minutes --- docs/csaf_aggregator.md | 2 +- docs/csaf_checker.md | 33 ++++---------------------- docs/csaf_downloader.md | 51 +++++++++++++++++++++++------------------ 3 files changed, 34 insertions(+), 52 deletions(-) diff --git a/docs/csaf_aggregator.md b/docs/csaf_aggregator.md index 08cbae07..9769b27d 100644 --- a/docs/csaf_aggregator.md +++ b/docs/csaf_aggregator.md @@ -109,7 +109,7 @@ client_cert // path to client certificate to access access-protected client_key // path to client key to access access-protected advisories client_passphrase // optional client cert passphrase (limited, experimental, see downloader doc) header // adds extra HTTP header fields to the client -timerange // Accepted time range of advisories to handle. See checker doc for details. +timerange // Accepted time range of advisories to handle. See downloader docs for details. ``` Next we have two TOML _tables_: diff --git a/docs/csaf_checker.md b/docs/csaf_checker.md index 9541b5f4..1db8292a 100644 --- a/docs/csaf_checker.md +++ b/docs/csaf_checker.md @@ -69,35 +69,10 @@ type 2: error The checker result is a success if no checks resulted in type 2, and a failure otherwise. -The option `timerange` allows to only check advisories from a given time interval. -It is only allowed to specify one off them. -There are following variants: - -1. Relative. If the given string follows the rules of being a [Go duration](https://pkg.go.dev/time@go1.20.6#ParseDuration) - the time interval from now minus that duration till now is used. - E.g. `"3h"` means checking the advisories that have changed in the last three hours. - -2. Absolute. If the given string is an RFC 3339 date timestamp the time interval between - this date and now is used. - E.g. `"2006-01-02"` means that all files between 2006 January 2nd and now going to be - checked. - Accepted patterns are: - - `"2006-01-02T15:04:05Z"` - - `"2006-01-02T15:04:05+07:00"` - - `"2006-01-02T15:04:05-07:00"` - - `"2006-01-02T15:04:05"` - - `"2006-01-02T15:04"` - - `"2006-01-02T15"` - - `"2006-01-02"` - - `"2006-01"` - - `"2006"` - - Missing parts are set to the smallest value possible in that field. - -3. Range. Same as 2 but separated by a `,` to span an interval. e.g `2019,2024` - spans an interval from 1st January 2019 to the 1st January of 2024. - -All interval boundaries are inclusive. +The option `timerange` allows to only check advisories from a given time +interval. It can only be given once. See the +[downloader documentation](csaf_downloader.md#timerange-option) for details. + You can ignore certain advisories while checking by specifying a list of regular expressions[^1] to match their URLs by using the `ignorepattern` diff --git a/docs/csaf_downloader.md b/docs/csaf_downloader.md index 37bc248d..74060712 100644 --- a/docs/csaf_downloader.md +++ b/docs/csaf_downloader.md @@ -79,17 +79,39 @@ forward_queue = 5 forward_insecure = false ``` +If the `folder` option is given all the advisories are stored in a subfolder +of this name. Otherwise the advisories are each stored in a folder named +by the year they are from. + +You can ignore certain advisories while downloading by specifying a list +of regular expressions[^1] to match their URLs by using the `ignorepattern` +option. + +E.g. `-i='.*white.*' -i='*.red.*'` will ignore files which URLs contain +the sub strings **white** or **red**. +In the config file this has to be noted as: +``` +ignorepattern = [".*white.*", ".*red.*"] +``` + +#### Timerange option + The `timerange` parameter enables downloading advisories which last changes falls into a given intervall. There are three possible notations: -1. Relative. If the given string follows the rules of being a [Go duration](https://pkg.go.dev/time@go1.20.6#ParseDuration) - the time interval from now minus that duration till now is used. - E.g. `"3h"` means downloading the advisories that have changed in the last three hours. - -2. Absolute. If the given string is an RFC 3339 date timestamp the time interval between - this date and now is used. +1. Relative. If the given string follows the rules of a + [Go duration](https://pkg.go.dev/time@go1.20.6#ParseDuration), + the time interval from now going back that duration is used. + Some examples: + - `"3h"` means downloading the advisories that have changed in the last three hours. + - `"30m"` .. changed within the last thirty minutes. + - `"72h"` .. changed within the last three days. + - `"8760h"` .. changed within the last 365 days. + +2. Absolute. If the given string is an RFC 3339 date timestamp + the time interval between this date and now is used. E.g. `"2006-01-02"` means that all files between 2006 January 2nd and now going to being - downloaded. + downloaded. Accepted patterns are: - `"2006-01-02T15:04:05Z"` - `"2006-01-02T15:04:05+07:00"` @@ -108,21 +130,6 @@ into a given intervall. There are three possible notations: All interval boundaries are inclusive. -If the `folder` option is given all the advisories are stored in a subfolder -of this name. Otherwise the advisories are each stored in a folder named -by the year they are from. - -You can ignore certain advisories while downloading by specifying a list -of regular expressions[^1] to match their URLs by using the `ignorepattern` -option. - -E.g. `-i='.*white.*' -i='*.red.*'` will ignore files which URLs contain -the sub strings **white** or **red**. -In the config file this has to be noted as: -``` -ignorepattern = [".*white.*", ".*red.*"] -``` - #### Forwarding The downloader is able to forward downloaded advisories and their checksums, OpenPGP signatures and validation results to an HTTP endpoint.