From: Alberto Leiva Popper Date: Mon, 27 May 2019 23:26:30 +0000 (-0500) Subject: Further documentation proofreading X-Git-Tag: v0.0.2~21 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b4e1aa3f39fbda57e9d3518a4df7ab688e31994a;p=thirdparty%2FFORT-validator.git Further documentation proofreading --- diff --git a/deconf.sh b/deconf.sh index cc40fc03..6f089d0d 100755 --- a/deconf.sh +++ b/deconf.sh @@ -4,4 +4,5 @@ git clean -dfx \ -e .settings \ -e .metadata \ -e Debug/ \ + -e tal/arin.tal \ -e tmp diff --git a/docs/doc/installation.md b/docs/doc/installation.md index 4d972e5f..28f5c8ae 100644 --- a/docs/doc/installation.md +++ b/docs/doc/installation.md @@ -34,7 +34,7 @@ I haven't actually tried this in all the Debian-based distributions. Tested in U {% highlight bash %} ########### normal dependencies ########### # autoconf 2.69 or higher, please. -sudo apt install autoconf libjansson-dev libssl-dev rsync +sudo apt install autoconf build-essential libjansson-dev libssl-dev pkg-config rsync unzip ############### libcmscodec ############### mkdir libcmscodec @@ -70,20 +70,12 @@ cd ../../ > > For now, I'm working around this by running the `autogen.sh`s in Debian. It probably needn't be fixed, since the releases are going to ship with the `autogen.sh`s already executed anyway. -> TODO: test this again - {% highlight bash %} ########### normal dependencies ########### su -# OpenBSD ships with LibreSSL -# autoconf 2.69 or higher, please. -pkg_add autoconf automake jansson libexecinfo rsync unzip +pkg_add jansson libexecinfo rsync unzip # OpenBSD ships with LibreSSL exit -# Adjust depending on the choices you made above. -export AUTOCONF_VERSION=2.69 -export AUTOMAKE_VERSION=1.9 - ############### libcmscodec ############### mkdir libcmscodec cd libcmscodec/ @@ -103,8 +95,8 @@ cd fort/ ftp https://github.com/NICMx/FORT-validator/archive/master.zip # tar xvzf fort-{{ site.fort-latest-version }}.tar.gz unzip master.zip -cd FORT* -ksh ./autogen.sh +cd FORT-validator-master +./autogen.sh # Run this elsewhere # clang is needed because of gnu11. env CC=clang CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure make diff --git a/docs/doc/intro-fort.md b/docs/doc/intro-fort.md index c344aa48..2a1df0de 100644 --- a/docs/doc/intro-fort.md +++ b/docs/doc/intro-fort.md @@ -12,7 +12,9 @@ Fort is an MIT-licensed RPKI Relying Party. It is a service that performs the va ![../img/design.svg](../img/design.svg) -It is a command line application intended for UNIX operating systems. (It requires a C compiler that supports `-std=gnu11`.) +The Validator is a timer that resynchronizes its [local cache](usage.html#--local-repository), validates the resulting [RPKI trees](intro-rpki.html) and stores the resulting ROAs in memory every [certain amount of time](usage.html#--servervalidation-interval). The RTR [Server](usage.html#--serveraddress) (which is part of the same binary) delivers these ROAs to any requesting routers. + +Fort is a command line application intended for UNIX operating systems, written in C. (It requires a compiler that supports `-std=gnu11`.) ## Standards Compliance @@ -50,7 +52,9 @@ These constitute the approximate missing 25%. ### RFC 6488 (Signed Objects) -6488 mandates that all signed objects must be DER-encoded. Fort's current parser cannot tell the difference between BER and DER. +6488 mandates that all signed objects must be DER-encoded. Fort's current parser cannot tell the difference between DER and (its superset) BER. + +Unfortunately, the parser also currently unavoidably [rejects certain technically valid BER objects](https://github.com/vlm/asn1c/blob/master/skeletons/ber_decoder.c#L215-L221). (Although these are not valid DER.) ### RFC 8182 (RRDP) diff --git a/docs/doc/slurm.md b/docs/doc/slurm.md index 98d86d48..2a3a4406 100644 --- a/docs/doc/slurm.md +++ b/docs/doc/slurm.md @@ -19,11 +19,9 @@ Note that, with the exception of the following section, most of this document is ## Handling of SLURM Files -The SLURM files are defined by the [`--slurm`](usage.html#--slurm) flag. If the flag points to a file, the configuration is extracted from that single file. If it points to a directory, the configuration is the aggregation of its contained files' contents. +The SLURM files are defined by the [`--slurm`](usage.html#--slurm) flag. If the flag points to a file, the configuration is extracted from that single file. If it points to a directory, the configuration is the aggregation of the contents of its contained `.slurm` files. -> TODO: are the children filtered by extension? - -None of the entries of the SLURM configuration are allowed to collide with each other. If there is a collision, the overall SLURM configuration is rejected. +None of the entries of the SLURM configuration are allowed to collide with each other. If there is a collision, the overall SLURM configuration is invalidated. Fort reloads the SLURM files during every validation cycle. If the new configuration is invalid, **it is treated as nonexistent**. Note that this means that an isolated mistake will temporarily drop all your SLURM overrides. This is intended to change in a future revision of Fort, in which the validator will fall back to the previous valid SLURM configuration on error. diff --git a/docs/doc/usage.md b/docs/doc/usage.md index 6e4f4a2f..416acc62 100644 --- a/docs/doc/usage.md +++ b/docs/doc/usage.md @@ -267,14 +267,14 @@ See the corresponding manual page from your operating system (likely `man 2 list - **Type:** Integer - **Availability:** `argv` and JSON -- **Default:** 60 -- **Range:** 60--7200 +- **Default:** 3600 +- **Range:** 60--[`UINT_MAX`](http://pubs.opengroup.org/onlinepubs/9699919799/) Number of seconds the server will sleep between validation cycles. The timer starts counting every time a validation is finished, not every time it begins. The actual validation loop is, therefore, longer than this number. -> TODO rationale of default value and range? +"Validation cycle" includes the rsync update along with the validation operation. Because you are taxing the global repositories every time the validator performs an rsync, it is recommended not to reduce the validation interval to the point you might be contributing to DoS'ing the global repository. The minimum value (60) was taken from the [RRDP RFC](https://tools.ietf.org/html/rfc8182#section-3.1), which means it's not necessarily a good value for heavy rsyncs. ### `--slurm` @@ -307,6 +307,10 @@ If enabled, the logging output will contain ANSI color codes. Meant for human co Decides which version of file names should be printed during most debug/error messages. +- `global-url`: Prints the global name of the file; the URL that can be used to download it. (Always starts with `rsync://`.) +- `local-path`: Prints a path that points to the local cached version of the file. (Always starts with [`--local-repository`](#--local-repository)'s value.) +- `file-name`: Strips prefixes, leaving only the base name of the file (including extension). + Suppose a certificate was downloaded from `rsync://rpki.example.com/foo/bar/baz.cer` into the local cache `repository/`: - `global-url`: Will print the certificate's name as `rsync://rpki.example.com/foo/bar/baz.cer`. @@ -314,14 +318,14 @@ Suppose a certificate was downloaded from `rsync://rpki.example.com/foo/bar/baz. - `file-name`: Will print the certificate's name as `baz.cer`. {% highlight bash %} -$ {{ page.command }} --output-file-name-format global-url --local-repository tmp/repository/ (...) -ERR: rsync://rpki.afrinic.net/repository/arin/uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired +$ {{ page.command }} --output-file-name-format global-url --local-repository repository/ (...) +ERR: rsync://rpki.example.com/foo/bar/baz.cer: Certificate validation failed: certificate has expired -$ {{ page.command }} --output-file-name-format local-path --local-repository tmp/repository/ (...) -ERR: tmp/repository/rpki.afrinic.net/repository/arin/uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired +$ {{ page.command }} --output-file-name-format local-path --local-repository repository/ (...) +ERR: repository/rpki.example.com/foo/bar/baz.cer: Certificate validation failed: certificate has expired -$ {{ page.command }} --output-file-name-format file-name --local-repository tmp/repository/ (...) -ERR: uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired +$ {{ page.command }} --output-file-name-format file-name --local-repository repository/ (...) +ERR: baz.cer: Certificate validation failed: certificate has expired {% endhighlight %} ### `--configuration-file` diff --git a/docs/img/design.svg b/docs/img/design.svg index 422393b3..ad98fd2b 100644 --- a/docs/img/design.svg +++ b/docs/img/design.svg @@ -239,9 +239,9 @@ borderopacity="1.0" inkscape:pageopacity="0.0" inkscape:pageshadow="2" - inkscape:zoom="1" - inkscape:cx="484.64395" - inkscape:cy="285.177" + inkscape:zoom="2.8284271" + inkscape:cx="443.93358" + inkscape:cy="397.96053" inkscape:document-units="px" inkscape:current-layer="layer1" showgrid="true" @@ -278,7 +278,7 @@ image/svg+xml - + @@ -291,10 +291,10 @@ + width="42.333317" + height="105.83336" + x="97.366661" + y="186.93336" /> + Fort