Add proxy and Prometheus to documentation

diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index 2b96e0de95cacf4973316cffa111176ab21dcc75..9d22562b79f98ff81375253122e995d54566b2b4 100644 (file)
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -58,6 +58,7 @@
                                                <li><a class="item-menu{% if page.url == '/installation.html' %} active{% endif %}" href="installation.html">Compilation and Installation</a></li>
                                                <li><a class="item-menu{% if page.url == '/run.html' %} active{% endif %}" href="run.html">Basic Usage</a></li>
                                                <li><a class="item-menu{% if page.url == '/usage.html' %} active{% endif %}" href="usage.html">Program Arguments</a></li>
+                                               <li><a class="item-menu{% if page.url == '/stats.html' %} active{% endif %}" href="stats.html">Stats</a></li>
                                                <li><a class="item-menu{% if page.url == '/logging.html' %} active{% endif %}" href="logging.html">Logging</a></li>
                                                <li><a class="item-menu{% if page.url == '/slurm.html' %} active{% endif %}" href="slurm.html">SLURM</a></li>
                                                <li><a class="item-menu{% if page.url == '/incidence.html' %} active{% endif %}" href="incidence.html">Incidences</a></li>

diff --git a/docs/intro-fort.md b/docs/intro-fort.md
index 1c1662a4b09c985cca81b7e87d5c8013bb9ddfbb..3f94bc36ad240ab9c3dc427e73dd7826cd28800f 100644 (file)
--- a/docs/intro-fort.md
+++ b/docs/intro-fort.md
@@ -24,9 +24,9 @@ Fort is a command-line application intended for UNIX operating systems, written
 | [issue149](https://github.com/NICMx/FORT-validator/issues/149) | Lock the cache during updates | <span class="urgency-high">High</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/12">2.0.0</a> |
 | [issue113](https://github.com/NICMx/FORT-validator/issues/113) | Detect and properly respond to subtler RRDP session desynchronization | <span class="urgency-medium">Medium</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/12">2.0.0</a> |
 | [issue124](https://github.com/NICMx/FORT-validator/issues/124) | Atomize output files (`--output.roa` and `--output.bgpsec`) | <span class="urgency-medium">Medium</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/12">2.0.0</a> |
+| [issue129](https://github.com/NICMx/FORT-validator/issues/129) | Rethink the thread pools | <span class="urgency-medium">Medium</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/12">2.0.0</a> |
 | [issue114](https://github.com/NICMx/FORT-validator/issues/114) | Support automatic TA key rollover | <span class="urgency-very-high">Very High</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/13">2.0.1</a> |
-| [issue50](https://github.com/NICMx/FORT-validator/issues/50) | Provide prometheus endpoint | <span class="urgency-very-high">Very High</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/14">2.0.2</a> |
-| [issue58](https://github.com/NICMx/FORT-validator/issues/58) | Fort's validation produces no router keys | <span class="urgency-very-high">Very High</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/15">2.0.3</a> |
+| [issue58](https://github.com/NICMx/FORT-validator/issues/58) | Fort's validation produces no router keys | <span class="urgency-very-high">Very High</span> | <a href="https://github.com/NICMx/FORT-validator/milestone/14">2.0.2</a> |
 | [issue116](https://github.com/NICMx/FORT-validator/issues/116) | SLURM review | <span class="urgency-high">High</span> | - |
 | [issue118](https://github.com/NICMx/FORT-validator/issues/118) | Implement validation re-reconsidered | <span class="urgency-high">High</span> | - |
 | [issue119](https://github.com/NICMx/FORT-validator/issues/119) | Review IRIs to file names transition | <span class="urgency-high">High</span> | - |
@@ -42,7 +42,6 @@ Fort is a command-line application intended for UNIX operating systems, written
 | [issue126](https://github.com/NICMx/FORT-validator/issues/126) | Exhaustive URL validation | <span class="urgency-medium">Medium</span> | - |
 | [issue127](https://github.com/NICMx/FORT-validator/issues/127) | Stream RRDP files | <span class="urgency-medium">Medium</span> | - |
 | [issue128](https://github.com/NICMx/FORT-validator/issues/128) | Reuse TCP connections for HTTP requests to same server | <span class="urgency-medium">Medium</span> | - |
-| [issue129](https://github.com/NICMx/FORT-validator/issues/129) | Rethink the thread pools | <span class="urgency-medium">Medium</span> | - |
 | [issue130](https://github.com/NICMx/FORT-validator/issues/130) | Improve documentation | <span class="urgency-medium">Medium</span> | - |
 | [issue151](https://github.com/NICMx/FORT-validator/issues/151) | [Enhancement]: Add ability to set ACLs for router connections | <span class="urgency-medium">Medium</span> | - |
 | [issue152](https://github.com/NICMx/FORT-validator/issues/152) | compliance issue: Fort accepts GeneralizedTime with fractional seconds | <span class="urgency-medium">Medium</span> | - |

diff --git a/docs/stats.md b/docs/stats.md
new file mode 100644 (file)
index 0000000..28491eb
--- /dev/null
+++ b/docs/stats.md
@@ -0,0 +1,42 @@
+---
+title: Stats
+---
+
+# {{ page.title }}
+
+Enable the Prometheus server with [`--prometheus.port`](usage.html#--prometheusport) and [`--mode=server`](usage.html#--mode):
+
+```bash
+$ fort --mode=server --prometheus.port=8000 /path/to/tal
+$ curl localhost:8000/metrics
+fort_rtr_ready 1 1757646873
+fort_rtr_current_connections 0 1757646873
+fort_valid_vrps_total{ta="test",proto="ipv4"} 44 1757646873
+fort_valid_vrps_total{ta="test",proto="ipv6"} 66 1757646873
+# EOF
+```
+
+The implementation is still very fresh, and prioritizes minimal monitoring over exhaustive reporting. Therefore, there are not many stats yet. Please request your preferred values via the [issue tracker](https://github.com/NICMx/FORT-validator/issues).
+
+## `fort_rtr_ready`
+
+- Type: Gauge (effectively boolean)
+
+Starts as 0, becomes 1 when the validator has a complete VRP table to serve via RTR.
+
+## `fort_rtr_current_connections`
+
+- Type: Gauge
+
+Number of presently open connections with RTR clients.
+
+## `fort_valid_vrps_total{ta="<TA>",proto="<IP>"}`
+
+- Type: Gauge
+
+Total number of VRPs generated from TA `<TA>` and protocol `<IP>` during the previous validation cycle.
+
+Labels:
+
+- `<TA>` is the TAL's file name, minus extension. (The `<TA>` of "`/etc/fort/tal/ripe-ncc.tal`" would be `ripe-ncc`.)
+- `IP` is either `ipv4` or `ipv6`.

diff --git a/docs/usage.md b/docs/usage.md
index 1e51477bca727b54c1c856795baede1558f408c5..aa1b09a0a15c6da8384f6b549327c7f5ff69c4b9 100644 (file)
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -29,6 +29,7 @@ description: Guide to use arguments of FORT Validator.
        17. [`--server.interval.retry`](#--serverintervalretry)
        18. [`--server.interval.expire`](#--serverintervalexpire)
        18. [`--server.deltas.lifetime`](#--serverdeltaslifetime)
+       18. [`--prometheus.port`](#--prometheusport)
        19. [`--slurm`](#--slurm)
        20. [`--log.enabled`](#--logenabled)
        21. [`--log.level`](#--loglevel)
@@ -56,6 +57,7 @@ description: Guide to use arguments of FORT Validator.
        41. [`--http.low-speed-time`](#--httplow-speed-time)
        41. [`--http.max-file-size`](#--httpmax-file-size)
        42. [`--http.ca-path`](#--httpca-path)
+       42. [`--http.proxy`](#--httpproxy)
        43. [`--output.roa`](#--outputroa)
        44. [`--output.bgpsec`](#--outputbgpsec)
        45. [`--output.format`](#--outputformat)
@@ -100,6 +102,7 @@ description: Guide to use arguments of FORT Validator.
        [--server.interval.retry=<unsigned integer>]
        [--server.interval.expire=<unsigned integer>]
        [--server.deltas.lifetime=<unsigned integer>]
+       [--prometheus.port=<unsigned integer>]
        [--rsync.enabled=true|false]
        [--rsync.priority=<unsigned integer>]
        [--rsync.retry.count=<unsigned integer>]
@@ -117,6 +120,7 @@ description: Guide to use arguments of FORT Validator.
        [--http.low-speed-time=<unsigned integer>]
        [--http.max-file-size=<unsigned integer>]
        [--http.ca-path=<directory>]
+       [--http.proxy=<HTTPS URL>]
        [--log.enabled=true|false]
        [--log.output=syslog|console]
        [--log.level=error|warning|info|debug]
@@ -461,6 +465,21 @@ During each validation cycle, Fort generates a new snapshot, as well as the delt
 
 If a router lags behind, to the point Fort has already deleted the deltas it needs to update the router's snapshot, Fort will have to fall back to fetch the entire latest snapshot instead.
 
+### `--prometheus.port`
+
+- **Type:** Integer
+- **Availability:** `argv` and JSON
+- **Default:** `NULL`
+- **Range:** [1, 65535]
+
+TCP port the Prometheus server will be bound to.
+
+The Prometheus server requires `--prometheus.port` to be defined, and [`--mode`](#--mode) to be `server`. Otherwise it will not start.
+
+Stats are served in openmetrics format. See [stats](stats.html).
+
+Unlike [`--server.port`](#--serverport), `--prometheus.port` is strictly a number. (It will not be resolved.)
+
 ### `--slurm`
 
 - **Type:** String (path to file or directory)
@@ -792,6 +811,26 @@ Useful when the CA from the peer isn't located at the default OS certificate bun
 
 The value specified is utilized in libcurl's option [CURLOPT_CAPATH](https://curl.haxx.se/libcurl/c/CURLOPT_CAPATH.html).
 
+### `--http.proxy`
+
+- **Type:** String (HTTPS URL)
+- **Availability:** `argv` and JSON
+- **Default:** `NULL` (disabled)
+
+Set a proxy to use for HTTP transfers.
+
+It can be a hostname, a dotted numerical IPv4 address or a numerical IPv6 address enclosed in brackets. The port defaults to 1080; append `:<port>` to override.
+
+Alternatively, invoke the usual environment variable (EV):
+
+```
+https_proxy=https://example.com:1234 fort --tal=/path/to/tal
+```
+
+`--http.proxy` takes precedence over the `https_proxy` EV, which in turn takes precedence over the `HTTPS_PROXY` EV.
+
+> There's no `--rsync.proxy` counterpart. For rsync connections, use the `RSYNC_PROXY` EV as usual.
+
 ### `--output.roa`
 
 - **Type:** String (Path to file)

diff --git a/man/fort.8 b/man/fort.8
index 08ee75b5e1abb00bdea3d74a66d316a26ad4ef34..71b62b6d3b6b90add4e0a65d34bc54bc99d8e6a5 100644 (file)
--- a/man/fort.8
+++ b/man/fort.8
@@ -452,6 +452,16 @@ If a router lags behind, to the point Fort has already deleted the deltas it nee
 .RE
 .P
 
+.B \-\-prometheus.port=\fIUNSIGNED_INTEGER\fR
+.RS 4
+TCP port the Prometheus server will be bound to.
+.P
+The Prometheus server requires \fI--prometheus.port\fR to be defined, and \fI--mode\fR to be \fIserver\fR. Otherwise it will not start.
+.P
+Stats are served in openmetrics format.
+.RE
+.P
+
 .B \-\-log.enabled=\fItrue\fR|\fIfalse\fR
 .RS 4
 Enables the operation logs.
@@ -854,6 +864,15 @@ By default, the path has a NULL value.
 .RE
 .P
 
+.B \-\-http.proxy=\fIURL\fR
+.RS 4
+.P
+Set a proxy to use for HTTP transfers.
+.P
+It can be a hostname, a dotted numerical IPv4 address or a numerical IPv6 address enclosed in brackets. The port defaults to 1080; append \fI:<port>\fR to override.
+.RE
+.P
+
 .B \-\-rsync.enabled=\fItrue\fR|\fIfalse\fR
 .RS 4
 Enables RSYNC requests.