Document new configuration arg 'stale-repository-period'

diff --git a/docs/usage.md b/docs/usage.md
index 1508c3d57edecc1bf4a59815ab0fb25a10b127d3..e2b5f5761606cba24ca5bbcb69860cdc81262690 100644 (file)
--- 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=<unsigned integer>]
+        [--asn1-decode-max-stack=<unsigned integer>]
+        [--stale-repository-period=<unsigned integer>]
         [--mode=server|standalone]
         [--server.address=<string>]
         [--server.port=<string>]
@@ -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
                "<a href="#--outputbgpsec">bgpsec</a>": "/tmp/fort/bgpsec.csv"
        },
 
-       "<a href="#--asn1-decode-max-stack">asn1-decode-max-stack</a>": 4096
+       "<a href="#--asn1-decode-max-stack">asn1-decode-max-stack</a>": 4096,
+       "<a href="#--stale-repository-period">stale-repository-period</a>": 43200
 }
 </code></pre>
 

diff --git a/examples/config.json b/examples/config.json
index 9770277d7c2a5d6756c7e49f9add2a6eb67f2ab0..a14df765f7c649e9f72e0326e6fb470e74a033bd 100644 (file)
--- 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 2c1a73af6eb00412202cd575e7e9bf8cc75c3310..d32b4993a8f693d83746a0c2fa4dd102b5558b7a 100644 (file)
--- 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