From 4dcbe3c89a648912d7edf9398c49b0015eee27e5 Mon Sep 17 00:00:00 2001 From: pcarana Date: Wed, 20 May 2020 23:09:59 -0500 Subject: [PATCH] Document new configuration arg 'stale-repository-period' --- docs/usage.md | 55 +++++++++++++++++++++++++++++++------------- examples/config.json | 3 ++- man/fort.8 | 33 +++++++++++++++++++++++++- 3 files changed, 73 insertions(+), 18 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 1508c3d5..e2b5f576 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -38,24 +38,25 @@ command: fort 27. [`--http.ca-path`](#--httpca-path) 28. [`--output.roa`](#--outputroa) 29. [`--output.bgpsec`](#--outputbgpsec) - 20. [`--asn1-decode-max-stack`](#--asn1-decode-max-stack) - 31. [`--configuration-file`](#--configuration-file) - 32. [`--rrdp.enabled`](#--rrdpenabled) - 33. [`--rrdp.priority`](#--rrdppriority) - 34. [`--rrdp.retry.count`](#--rrdpretrycount) - 35. [`--rrdp.retry.interval`](#--rrdpretryinterval) - 36. [`--rsync.enabled`](#--rsyncenabled) - 37. [`--rsync.priority`](#--rsyncpriority) - 38. [`--rsync.strategy`](#--rsyncstrategy) + 30. [`--asn1-decode-max-stack`](#--asn1-decode-max-stack) + 31. [`--stale-repository-period`](#--stale-repository-period) + 32. [`--configuration-file`](#--configuration-file) + 33. [`--rrdp.enabled`](#--rrdpenabled) + 34. [`--rrdp.priority`](#--rrdppriority) + 35. [`--rrdp.retry.count`](#--rrdpretrycount) + 36. [`--rrdp.retry.interval`](#--rrdpretryinterval) + 37. [`--rsync.enabled`](#--rsyncenabled) + 38. [`--rsync.priority`](#--rsyncpriority) + 39. [`--rsync.strategy`](#--rsyncstrategy) 1. [`strict`](#strict) 2. [`root`](#root) 3. [`root-except-ta`](#root-except-ta) - 39. [`--rsync.retry.count`](#--rsyncretrycount) - 40. [`--rsync.retry.interval`](#--rsyncretryinterval) - 41. [`rsync.program`](#rsyncprogram) - 42. [`rsync.arguments-recursive`](#rsyncarguments-recursive) - 43. [`rsync.arguments-flat`](#rsyncarguments-flat) - 44. [`incidences`](#incidences) + 40. [`--rsync.retry.count`](#--rsyncretrycount) + 41. [`--rsync.retry.interval`](#--rsyncretryinterval) + 42. [`rsync.program`](#rsyncprogram) + 43. [`rsync.arguments-recursive`](#rsyncarguments-recursive) + 44. [`rsync.arguments-flat`](#rsyncarguments-flat) + 45. [`incidences`](#incidences) ## Syntax @@ -71,6 +72,8 @@ command: fort [--work-offline] [--shuffle-uris] [--maximum-certificate-depth=] + [--asn1-decode-max-stack=] + [--stale-repository-period=] [--mode=server|standalone] [--server.address=] [--server.port=] @@ -568,6 +571,25 @@ ASN1 decoder max allowed stack size in bytes, utilized to avoid a stack overflow This check is merely a caution, since ASN1 decoding functions are recursive and might cause a stack overflow. So, this argument probably won't be necessary in most cases, since the RPKI ASN1 objects don't have nested objects that require too much stack allocation (for now). +### `--stale-repository-period` + +- **Type:** Integer +- **Availability:** `argv` and JSON +- **Default:** 43200 (12 hours) +- **Range:** 0--[`UINT_MAX`](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/limits.h.html) + +Time period that must lapse to warn about a stale repository (the messages will be sent to the operation log). The time lapse starts once the repository download has been retried (see [`--rsync.retry.count`](#--rsyncretrycount) and [`--rrdp.retry.count`](#--rrdpretrycount)) and failed after such retries. + +A repository is considered stale if its files can't be fetched due to a communication error and this error persists across validation cycles. This kind of issues can be due to a local misconfiguration (eg. a firewall that blocks incoming data) or a problem at the server (eg. the server is down). + +Despite who's "fault" is, FORT validator will try to work with the local files from [`--local-repository`](#--local-repository). + +The communication errors sent to the operation log, are those related to "first level" RPKI servers; commonly this are the servers maintained by the RIRs. + +Currently **all** the communication errors are logged at the validation log. This argument (`--stale-repository-period`) is merely to send this error messages also to the operation log. + +A value **equal to 0** means that the communication errors will be logged at once. + ### `--configuration-file` - **Type:** String (Path to file) @@ -666,7 +688,8 @@ The configuration options are mostly the same as the ones from the `argv` interf "bgpsec": "/tmp/fort/bgpsec.csv" }, - "asn1-decode-max-stack": 4096 + "asn1-decode-max-stack": 4096, + "stale-repository-period": 43200 } diff --git a/examples/config.json b/examples/config.json index 9770277d..a14df765 100644 --- a/examples/config.json +++ b/examples/config.json @@ -87,5 +87,6 @@ "roa": "/tmp/fort/roas.csv", "bgpsec": "/tmp/fort/bgpsec.csv" }, - "asn1-decode-max-stack": 4096 + "asn1-decode-max-stack": 4096, + "stale-repository-period": 43200 } diff --git a/man/fort.8 b/man/fort.8 index 2c1a73af..d32b4993 100644 --- a/man/fort.8 +++ b/man/fort.8 @@ -817,6 +817,36 @@ By default, it has a value of \fI4096\fR (4 kB). .RE .P +.B \-\-stale-repository-period=\fIUNSIGNED_INTEGER\fR +.RS 4 +Time period that must lapse to warn about a stale repository (the messages will +be sent to the operation log). The time lapse starts once the repository +download has been retried (see \fI--rsync.retry.count\fR and +\fI--rrdp.retry.count\fR) and failed after such retries. +.P +A repository is considered stale if its files can't be fetched due to a +communication error and this error persists across validation cycles. This kind +of issues can be due to a local misconfiguration (eg. a firewall that blocks +incoming data) or a problem at the server (eg. the server is down). +.P +Despite who's "fault" is, FORT validator will try to work with the local files +from \fI--local-repository\fR. +.P +The communication errors sent to the operation log, are those related to +"first level" RPKI servers; commonly this are the servers maintained by the +RIRs. +.P +Currently \fBall\fR the communication errors are logged at the validation log. +This argument (\fB--stale-repository-period\fR) is merely to send this error +messages also to the operation log. +.P +A value \fBequal to 0\fR means that the communication errors will be logged at +once. +.P +By default, it has a value of \fI43200\fR (12 hours). +.RE +.P + .SH EXAMPLES .B fort \-t /tmp/tal \-r /tmp/repository \-\-server.port 9323 .RS 4 @@ -946,7 +976,8 @@ to a specific value: "roa": "/tmp/fort/roas.csv", "bgpsec": "/tmp/fort/bgpsec.csv" }, - "asn1-decode-max-stack": 4096 + "asn1-decode-max-stack": 4096, + "stale-repository-period": 43200 } .fi .RE -- 2.47.2