From: Alberto Leiva Popper Date: Tue, 21 May 2019 00:09:26 +0000 (-0500) Subject: Update a good chunk of the documentation X-Git-Tag: v0.0.2~28 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e3ca9909f280cb1ade6ea9786c92c61dc4918ea3;p=thirdparty%2FFORT-validator.git Update a good chunk of the documentation --- diff --git a/docs/_config.yml b/docs/_config.yml index 02fde189..8faf1f35 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,8 +1,11 @@ markdown: kramdown -baseurl: /FORT-validator +baseurl: /fort defaults: - scope: path: "" # an empty string here means all files in the project values: layout: "default" + +fort-latest-version: 0.0.1 +libcmscodec-latest-version: beta1 diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html index 25384c2e..8dbc985c 100644 --- a/docs/_layouts/default.html +++ b/docs/_layouts/default.html @@ -12,7 +12,7 @@
-WARNING Warning: This documentation is still under construction. A good chunk of it will already be obsolete by the time FORT v1.0.0 is released. +WARNING Warning: This documentation is still under construction. It's too succint for comfort still.
{{ content }} diff --git a/docs/doc/index.md b/docs/doc/index.md index b445e8b6..ff39861e 100644 --- a/docs/doc/index.md +++ b/docs/doc/index.md @@ -7,6 +7,5 @@ title: Documentation Index 1. [Introduction to RPKI](intro-rpki.html) 2. [Introduction to Fort](intro-fort.html) 3. [Compilation and Installation](installation.html) -4. [Running the package](run.html) -5. [Validator usage](validator.html) -6. [RTR Server usage](rtr-server.html) +4. [Running Fort](run.html) +5. [Validator usage](usage.html) diff --git a/docs/doc/installation.md b/docs/doc/installation.md index 0c85daa6..7e08df77 100644 --- a/docs/doc/installation.md +++ b/docs/doc/installation.md @@ -4,72 +4,110 @@ title: Compilation and Installation # {{ page.title }} +> TODO update with proper .tar.gz releases, once they are created + ## Index -1. [Install dependencies](#install-dependencies) - 1. [libcrypto](#libcrypto) - 2. [tomlc99](#tomlc99) - 3. [rsync](#rsync) -2. [Install Fort](#install-fort) - 1. [libcmscodec](#libcmscodec) - 2. [Validator](#validator) - 3. [RTR Server](#rtr-server) +1. [Dependencies](#dependencies) +2. [Debian-based distributions](#debian-based-distributions) +3. [OpenBSD](#openbsd) + +## Dependencies -## Install dependencies +> Note: I'm only including this section in case you intend to install Fort in an unlisted OS (and therefore need a little research). For Debians and OpenBSD, just follow the steps in the sections below. -### libcrypto +The dependencies are -Either [LibreSSL](http://www.libressl.org/) or [OpenSSL](https://www.openssl.org/) +1. [jansson](http://www.digip.org/jansson/) +2. [libcmscodec](https://github.com/NICMx/libcmscodec) +3. libcrypto (Either [LibreSSL](http://www.libressl.org/) or [OpenSSL](https://www.openssl.org/)) +4. [rsync](http://rsync.samba.org/) -### tomlc99 +There's also [autoconf](https://www.gnu.org/software/autoconf/) and unzip (or [git](https://git-scm.com/)), but those are only needed for installation paperwork. -[tomlc99](https://github.com/cktan/tomlc99) +## Debian-based distributions -### libcmscodec +I haven't actually tried this in all the Debian-based distributions. Tested in Ubuntu 18. {% highlight bash %} -git clone https://github.com/ydahhrk/libcmscodec.git -cd libcmscodec -./autogen.sh +########### normal dependencies ########### +# autoconf 2.69 or higher, please. +sudo apt install autoconf libjansson-dev libssl-dev rsync + +############### libcmscodec ############### +mkdir libcmscodec +cd libcmscodec/ +wget https://github.com/NICMx/libcmscodec/releases/download/beta1/libcmscodec-beta1.tar.gz +tar xvzf libcmscodec-beta1.tar.gz +cd libcmscodec-beta1/ ./configure make sudo make install -{% endhighlight %} - -### rsync - -[rsync](http://rsync.samba.org/) - -## Install Fort - -There are no packages just yet. - -{% highlight bash %} -git clone https://github.com/ydahhrk/rpki-validator.git -cd rpki-validator +sudo ldconfig +cd ../.. + +################## fort ################### +mkdir fort +cd fort +wget https://github.com/NICMx/FORT-validator/archive/master.zip +# tar xvzf fort-{{ site.fort-latest-version }}.tar.gz +unzip master.zip +cd FORT-validator-master/ ./autogen.sh ./configure make sudo make install +cd ../.. {% endhighlight %} ## OpenBSD +> TODO: The autotools are weird in this OS. +> +> They require some global variables the installer doesn't setup on its own for some reason, and then spew error messages encouraging long deprecated macros. WTF? +> +> 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 %} -# pkg_add libexecinfo jansson rsync -$ -$ ftp -$ tar xvzf libcmscodec-.tar.gz -$ cd libcmscodec -$ ./configure -$ make -# make install -$ cd .. -$ ftp -$ tar xvzf fort-.tar.gz -$ cd fort -$ # clang is needed because of gnu11. -$ env CC=clang CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure -$ make -# make install +########### normal dependencies ########### +su +# OpenBSD ships with LibreSSL +# autoconf 2.69 or higher, please. +pkg_add autoconf automake jansson libexecinfo rsync unzip +exit + +# Adjust depending on the choices you made above. +export AUTOCONF_VERSION=2.69 +export AUTOMAKE_VERSION=1.9 + +############### libcmscodec ############### +mkdir libcmscodec +cd libcmscodec/ +ftp https://github.com/NICMx/libcmscodec/releases/download/beta1/libcmscodec-{{ site.libcmscodec-latest-version }}.tar.gz +tar xvzf libcmscodec-{{ site.libcmscodec-latest-version }}.tar.gz +cd libcmscodec-{{ site.libcmscodec-latest-version }}/ +./configure +make +su +make install +exit +cd ../.. + +################## fort ################### +mkdir fort +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 +# clang is needed because of gnu11. +env CC=clang CFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib ./configure +make +su +make install +exit +cd ../.. {% endhighlight %} diff --git a/docs/doc/intro-fort.md b/docs/doc/intro-fort.md index 5cf92873..d1ff63c0 100644 --- a/docs/doc/intro-fort.md +++ b/docs/doc/intro-fort.md @@ -1,18 +1,16 @@ --- -title: Introduction to FORT +title: Introduction to Fort --- # {{ page.title }} ## Design -FORT is an RPKI Relying Party. It is a service that performs the validation of the entire RPKI repository, and which prepares the ROAs for easy access by your routers. +Fort is an MIT-licensed RPKI Relying Party. It is a service that performs the validation of the entire RPKI repository, and which serves the resulting ROAs for easy access by your routers. ![../img/design.svg](../img/design.svg) -It is currently made out of two separate binaries. One of them is a command line application that can be used to perform manual validations, and a server that takes the output of the former and communicates it to the routers. - -So the idea is to routinely run the command line application in a cron job, and serve its output through the server. +It is a command line application intended for UNIX operating systems. (It requires a C compiler that supports `-std=gnu11`.) ## Standards Compliance diff --git a/docs/doc/intro-rpki.md b/docs/doc/intro-rpki.md index db72a68f..609aa0ae 100644 --- a/docs/doc/intro-rpki.md +++ b/docs/doc/intro-rpki.md @@ -32,4 +32,4 @@ So the whole infrastructure functions like a tree-shaped trust network (one for In the RPKI, all of these files are required to be publicly-available, so anyone can verify them. -This is, however, too much work for a router, so the validation work is deferred to a trusted _Relying Party_ (RP). That's where [FORT](intro-fort.html) comes in. +This is, however, too much work for a router, so the validation work is deferred to a trusted _Relying Party_ (RP). That's where [Fort](intro-fort.html) comes in. diff --git a/docs/doc/rtr-server.md b/docs/doc/rtr-server.md deleted file mode 100644 index efba6b6e..00000000 --- a/docs/doc/rtr-server.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: RTR Server arguments -command: rpki_validator ---- - -# {{ page.title }} - -## Index - -1. [Syntax](#syntax) -1. [Arguments](#arguments) - 1. [`-f`](#-f) -1. [Configuration file](#configuration-file) - 1. [`listen`](#listen) - 1. [`address`](#address) - 1. [`port`](#port) - 1. [`queue`](#queue) - 1. [`vrps`](#vrps) - 1. [`location`](#location) - 1. [`checkInterval`](#checkinterval) - -## Syntax - -``` -{{ page.command }} - [-f] -``` - -If an argument is declared more than once, the last one takes precedence: - -{% highlight bash %} -$ {{ page.command }} -f="/foo.bar" # f is "foo.bar" -$ {{ page.command }} -f="/foo.bar" -f="/bar.baz" # f is "bar.baz" -$ {{ page.command }} -f="/foo.bar" -f="/bar.baz" -f="/baz.qux" # f is "baz.qux" -{% endhighlight %} - - -## Arguments - -### `-f` - -- **Type:** String (Path to file) -- **Required:** Yes - -Path to the configuration file. The configuration file must be in JSON format and with the structure as stated in [Configuration file](#configuration-file). - -## Configuration file - -The configuration file must be in JSON format, and must have the following structure: - -```javascript -{ - "listen": { - "address": "", - "port": "", - "queue": - }, - "vrps": { - "location": "", - "checkInterval": - } -} -``` - -The server has default values for the configuration, all of them stated at each of the following sections. - -If a property is set at the configuration file, its value will override the default value. If a property is required, then its value MUST be set at the configuration file. - -### `listen` - -Property to set values related to the service that'll be configured to listen RTR clients (routers). It has 3 attributes: -- [`address`](#address) -- [`port`](#port) -- [`queue`](#queue) - -#### `address` - -- **Type:** String -- **Default:** `NULL` -- **Required:** No - -Hostname or numeric host address where the server will be binded, listening to client requests. - -If the address is left with 'NULL' value (default value), the service will be binded to `INADDR_ANY` or `IN6ADDR_ANY_INIT`. - -#### `port` - -- **Type:** String -- **Default:** `323` -- **Required:** No - -Port or service where the server will be binded. A service alias can be set as a valid value; the alias are commonly located at `etc/services` (read more using '`$ man services`'). - -> ![../img/warn.svg](../img/warn.svg) If the default port will be used to start the server, a superuser MUST start the service since this is a privileged port. - -#### `queue` - -- **Type:** Numeric (integer value) -- **Default:** `10` -- **Required:** No - -Number of client connections that will be queued before starting to refuse new ones. - -The value must be between 1 and `SOMAXCONN` (read more using '`$ man listen`'). - -### `vrps` - -Property to set values related to the main RTR server input: the validated ROAs generated by the FORT validator. It has 2 attributes: -- [`location`](#location) -- [`checkInterval`](#checkinterval) - -#### `location` - -- **Type:** String -- **Default:** `NULL` -- **Required:** Yes - -Path to the CSV file with validated ROAs. This file is the one generated by the FORT validator. - -#### `checkInterval` - -- **Type:** Numeric (integer value) -- **Default:** `60` -- **Required:** No - -Time interval in seconds to seek for updates at the `vrps.location` configured, must have a value between 60 and 7200 (2 hours). - -The default value (and minimum value as well) is set to honour RFC 6810 requirement on Serial Notify PDUs: - -> "The cache MUST rate limit Serial Notifies to no more frequently than one per minute" - diff --git a/docs/doc/run.md b/docs/doc/run.md index d5e22934..f5bc903d 100644 --- a/docs/doc/run.md +++ b/docs/doc/run.md @@ -1,102 +1,17 @@ --- -title: Running the package +title: Running Fort --- # {{ page.title }} -> Note: The separation between Validator and RTR server is a temporal arrangement for the Beta version. -> -> For the sake of performance and ease of use, the two binaries will be merged by the time version 1.0.0 is released. These instructions will become obsolete then. - -Create file `~/fort/update-rpki.sh`, and drop the following content into it: +This is probably all you need: {% highlight bash %} -#!/bin/bash - -# TODO I'm assuming the file names will not contain whitespace for now. - -# First argument: Directory containing all the TALs -TAL_DIRECTORY=$1 -# Second argument: File we share with the RTR server -# (The script will also temporarily manage a file called -# "$OUTPUT_FILE.tmp") -OUTPUT_FILE=$2 -# Third argument: Working directory. -# We'll store the repository and temporal files here. -WORKING_DIR=$3 - -# Directory where we'll store temporal ROA files, used to assemble -# $OUTPUT_FILE.tmp. -TMP_ROA_DIR=$WORKING_DIR/roa -# The local repository cache -CACHE_DIR=$WORKING_DIR/repository - - -mkdir -p $TMP_ROA_DIR -mkdir -p $CACHE_DIR - -echo "Updating and validating the repository..." -# TODO we'd probably gain a lot of performance by running these in -# parallel -for TAL_FILE in $TAL_DIRECTORY/*; do - echo " Handling TAL $TAL_FILE..." - /usr/local/bin/rpki_validator \ - --tal $TAL_FILE \ - --local-repository $CACHE_DIR \ - --roa-output-file $TMP_ROA_DIR/$(basename $TAL_FILE .tal).roa.tmp \ - > /dev/null -done - -echo "Joining all the generated ROA files..." - -# Make sure it exists. Otherwise the mv explodes -touch $OUTPUT_FILE.tmp -# Make sure $TMP_ROA_DIR/*.tmp expands, even if there are no files. -shopt -s nullglob - -for TMP_ROA_FILE in $TMP_ROA_DIR/*.tmp; do - echo " Joining file $TMP_ROA_FILE..." - cat $TMP_ROA_FILE >> $OUTPUT_FILE.tmp - rm $TMP_ROA_FILE -done - -echo "Replacing old ROA file with new one..." -# (Needs to be done last for the sake of atomicity.) -mv $OUTPUT_FILE.tmp $OUTPUT_FILE - -echo "Done." +fort \ + --tal \ + --local-repository \ + --server.address + --server.port {% endhighlight %} -Grant it executable permissions: - -{% highlight bash %} -$ chmod +x ~/fort/update-rpki.sh -{% endhighlight %} - -Place your `.tal` files in `~/fort/tal`: - -{% highlight bash %} -$ mv ~/fort/tal -{% endhighlight %} - -Then create a cron job (`crontab -e`), running the script above every hour: - - 0 * * * * ~/fort/update-rpki.sh ~/fort/tal /tmp/fort/roas.csv /tmp/fort - -Now the RTR Server can serve the ROAs: - -{% highlight bash %} -$ cat rtr-config.json -{ - "listen": { - "address": "::1", - "port": "8323", - "queue": 10 - }, - "vrps": { - "location": "/tmp/fort/roas.csv", - "checkInterval": 60 - } -} -$ rtr_server -f rtr-config.json -{% endhighlight %} +See [usage](usage.html) for more details. diff --git a/docs/doc/validator.md b/docs/doc/usage.md similarity index 55% rename from docs/doc/validator.md rename to docs/doc/usage.md index 8e7a125d..3f75defc 100644 --- a/docs/doc/validator.md +++ b/docs/doc/usage.md @@ -1,6 +1,6 @@ --- title: Validator Usage -command: rpki_validator +command: fort --- # {{ page.title }} @@ -14,37 +14,47 @@ command: rpki_validator 3. [`--version`](#--version) 4. [`--tal`](#--tal) 5. [`--local-repository`](#--local-repository) - 6. [`--roa-output-file`](#--roa-output-file) - 7. [`--sync-strategy`](#--sync-strategy) + 6. [`--sync-strategy`](#--sync-strategy) 1. [`off`](#off) 2. [`strict`](#strict) 3. [`root`](#root) 4. [`root-except-ta`](#root-except-ta) + 7. [`--shuffle-uris`](#--shuffle-uris) 8. [`--maximum-certificate-depth`](#--maximum-certificate-depth) - 9. [`--shuffle-uris`](#--shuffle-uris) - 10. [`--color-output`](#--color-output) - 11. [`--output-file-name-format`](#--output-file-name-format) - 12. [`--configuration-file`](#--configuration-file) - 13. [`rsync.program`](#rsyncprogram) - 14. [`rsync.arguments-recursive`](#rsyncarguments-recursive) - 15. [`rsync.arguments-flat`](#rsyncarguments-flat) + 9. [`--server.address`](#--serveraddress) + 10. [`--server.port`](#--serverport) + 11. [`--server.backlog`](#--serverbacklog) + 12. [`--server.validation-interval`](#--servervalidation-interval) + 13. [`--slurm`](#--slurm) + 14. [`--log.color-output`](#--logcolor-output) + 15. [`--log.file-name-format`](#--logfile-name-format) + 16. [`--configuration-file`](#--configuration-file) + 17. [`rsync.program`](#rsyncprogram) + 18. [`rsync.arguments-recursive`](#rsyncarguments-recursive) + 19. [`rsync.arguments-flat`](#rsyncarguments-flat) ## Syntax + + ``` {{ page.command }} - [--help] + [--help] [--usage] [--version] [--configuration-file=] + [--tal=] [--local-repository=] [--sync-strategy=off|strict|root|root-except-ta] - [--maximum-certificate-depth=] - [--tal=] [--shuffle-uris] - [--color-output] - [--output-file-name-format=global-url|local-path|file-name] - [--roa-output-file=] + [--maximum-certificate-depth=] + [--server.address=] + [--server.port=] + [--server.backlog=] + [--server.validation-interval=] + [--slurm=] + [--log.color-output] + [--log.file-name-format=global-url|local-path|file-name] ``` If an argument is declared more than once, the last one takes precedence: @@ -61,7 +71,7 @@ $ {{ page.command }} --tal="foo" --tal="bar" --tal="qux" # tal is "qux" ### `--help` - Type: None -- Availability: `argv` only. +- Availability: `argv` only Prints medium-sized usage message. @@ -86,7 +96,7 @@ The slightly larger usage message is `man {{ page.command }}` and the large usag ### `--usage` - Type: None -- Availability: `argv` only. +- Availability: `argv` only Prints small-sized help message. @@ -104,7 +114,7 @@ Usage: {{ page.command }} ### `--version` - Type: None -- Availability: `argv` only. +- Availability: `argv` only Prints small-sized usage message. @@ -116,19 +126,17 @@ $ {{ page.command }} --version ### `--tal` - Type: String (Path to file) -- Availability: `argv` and TOML +- Availability: `argv` and JSON -Path to the _Trust Anchor Locator_ (TAL). +Path to the _Trust Anchor Locator_ (TAL), or to a directory that contains TALs. -The TAL is a file that points to the _Trust Anchor_ (TA). (The TA is the self-signed certificate that serves as the root of the tree you want validated.) +A TAL is a file that points to a _Trust Anchor_ (TA). A TA is a self-signed certificate that serves as root of an RPKI tree you want validated. -The reason why you provide a TAL instead of a TA is to allow the TA to be updated without needing to redistribute it. +The reason why you provide locators instead of anchors is to allow anchors to be officially updated without the need to awkwardly redistribute them. -Whichever registry serves as root of the tree you want to validate is responsible for providing you with its TAL. FORT currently ships with the TALs of most of the five RIRs. +Whichever registry serves as root of the tree you want to validate is responsible for providing you with its TAL. For convenience, Fort currently ships with the TALs of four of the five RIRs. (The exception is ARIN's, since you need to read and accept an [agreement](https://www.arin.net/resources/manage/rpki/tal/) before you can use it.) If you are paranoid, however, you'd be advised to get your own. -> TODO state where they are and which is the missing one. - -the TAL file format has been standardized in [RFC 7730](https://tools.ietf.org/html/rfc7730). It is a text file that contains a list of URLs (which serve as alternate access methods for the TA), followed by a blank line, followed by the Base64-encoded public key of the TA. +The TAL file format has been standardized in [RFC 7730](https://tools.ietf.org/html/rfc7730). It is a text file that contains a list of URLs (which serve as alternate access methods for the TA), followed by a blank line, followed by the Base64-encoded public key of the TA. Just for completeness sake, here's an example on what a typical TAL looks like: @@ -147,31 +155,19 @@ LQIDAQAB ### `--local-repository` - Type: String (Path to directory) -- Availability: `argv` and TOML +- Availability: `argv` and JSON - Default: `/tmp/fort/repository` -> TODO I just came up with the default value. Commit it. - -Path to the directory where FORT will store a local cache of the repository. - -RPKI repositories are typically accessed by way of [rsync](https://en.wikipedia.org/wiki/Rsync). During the validation cycle, FORT will literally invoke an `rsync` command (see `rsync.program` and `rsync.arguments`), which will download the files into `--local-repository`, and validate the result. - -Because rsync uses delta encoding, keeping this cache around significantly speeds up subsequent validation cycles. +Path to the directory where Fort will store a local cache of the repository. -### `--roa-output-file` - -- Type: String (Path to file) -- Availability: `argv` and TOML -- Default: `NULL` +Right now, Fort accesses RPKI repositories by way of [rsync](https://en.wikipedia.org/wiki/Rsync). (The alternate protocol [RRDP](https://tools.ietf.org/html/rfc8182) is in the road map.) During each validation cycle, Fort will literally invoke an `rsync` command (see [`rsync.program`](#rsyncprogram) and [`rsync.arguments-recursive`](#rsyncarguments-recursive)), which will download the files into `--local-repository`. Fort's validation operates on the resulting copy. -Path to a file where FORT will dump successfully validated ROAs (in CSV format). If `NULL`, the ROAs will be printed in standard error. - -This file is meant to be consumed by the beta version of the RTR Server. (In subsequent releases, this will no longer be required.) +Because rsync uses delta encoding, you're advised to keep this cache around. It significantly speeds up subsequent validation cycles. ### `--sync-strategy` - Type: Enumeration (`off`, `strict`, `root`, `root-except-ta`) -- Availability: `argv` and TOML +- Availability: `argv` and JSON - Default: `root` rsync synchronization strategy. Commands the way rsync URLs are approached during downloads. @@ -195,7 +191,7 @@ For example, suppose the validator gets certificates whose caRepository access m A validator following the `strict` strategy would download `bar`, download `qux`, skip `bar`, download `corge/grault`, download `corge` and skip `corge/waldo`. -Though this strategy is the only "strictly" correct one, it is also extremely slow. Its usage is _not_ recommended, unless your repository contains lots of spam files, awkward permissions or can't be found in a repository rooted in a URL that follows the pattern `rsync://.+/.+/`. +Though this strategy is the only "strictly" correct one, it is also extremely slow. Its usage is _not_ recommended, unless your repository contains lots of spam files, awkward permissions or can't be found in a repository rooted in a URL that follows the regular expression "`rsync://.+/.+/`". #### `root` @@ -214,21 +210,81 @@ Synchronizes the root certificate (the one pointed by the TAL) in `strict` mode, Useful if you want `root`, but the root certificate is separated from the rest of the repository. Also useful if you don't want the validator to download the entire repository without first confirming the integrity and legitimacy of the root certificate. -### `--maximum-certificate-depth` - ### `--shuffle-uris` -- Availability: `argv` and TOML +- Availability: `argv` and JSON -If enabled, FORT will access TAL URLs in random order. This is meant for load balancing. If disabled, FORT will access TAL URLs in sequential order. +If enabled, Fort will access TAL URLs in random order. This is meant for load balancing. If disabled, Fort will access TAL URLs in sequential order. -(Regardless of this flag, FORT will stop iterating through the URLs as soon as it finds one that yields a successful traversal.) +(Regardless of this flag, Fort will stop iterating through the URLs as soon as it finds one that yields a successful traversal.) Of course, this is only relevant if the TAL lists more than one URL. -### `--color-output` +### `--maximum-certificate-depth` + +> TODO; unfinished code + +### `--server.address` + +- Type: String +- Availability: `argv` and JSON +- Default: `NULL` + +Hostname or numeric host address the RTR server will be bound to. Must resolve to (or be) a bindable IP address. IPv4 and IPv6 are supported. + +If this field is omitted, Fort falls back to perform an in-place standalone RPKI validation. Presently, this is only intended for debugging. + +### `--server.port` + +- Type: String +- Availability: `argv` and JSON +- Default: `"323"` + +TCP port or service the server will be bound to. + +This is a string because a service alias can be used as a valid value. The alias are commonly located at `/etc/services`. (See '`$ man services`'.) + +> ![../img/warn.svg](../img/warn.svg) The default port is privileged. To improve security, either change or jail it. + +### `--server.backlog` + +- Type: Integer +- Availability: `argv` and JSON +- Default: [`SOMAXCONN`](http://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/sys_socket.h.html) +- Range: 1--`SOMAXCONN` + +RTR server's listen queue length. It's the second argument of [`listen()`](http://pubs.opengroup.org/onlinepubs/9699919799.2008edition/functions/listen.html): + +> The backlog argument provides a hint to the implementation which the implementation shall use to limit the number of outstanding connections in the socket's listen queue. Implementations may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog argument value shall result in a larger or equal length of the listen queue. Implementations shall support values of backlog up to SOMAXCONN, defined in . + +See the corresponding manual page from your operating system (likely `man 2 listen`) for specific implementation details. -- Availability: `argv` and TOML +### `--server.validation-interval` + +- Type: Integer +- Availability: `argv` and JSON +- Default: 60 +- Range: 60--7200 + +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? + +### `--slurm` + +- Type: String (path to file or directory) +- Availability: `argv` and JSON +- Default: `NULL` + +[SLURM](https://tools.ietf.org/html/rfc8416) file, or directory containing SLURM files. + +> TODO this is somewhat involved, and needs a dedicated page. The format is standard, though. + +### `--log.color-output` + +- Availability: `argv` and JSON If enabled, the logging output will contain ANSI color codes. Meant for human consumption. @@ -240,10 +296,10 @@ If enabled, the logging output will contain ANSI color codes. Meant for human co CRT: Programming error: Array size is 1 but array is NULL. -### `--output-file-name-format` +### `--log.file-name-format` - Type: Enumeration (`global-url`, `local-path`, `file-name`) -- Availability: `argv` and TOML +- Availability: `argv` and JSON - Default: `global-url` Decides which version of file names should be printed during most debug/error messages. @@ -266,68 +322,97 @@ ERR: uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate ### `--configuration-file` - Type: String (Path to file) -- Availability: `argv` - -Path to a TOML file from which additional configuration will be read. - -The configuration options are mostly the same as the ones from the `argv` interface. Here's a full configuration file example: - -
[root]
-local-repository = "/tmp/fort/repository"
-sync-strategy = "root"
-maximum-certificate-depth = 32
-
-[tal]
-tal = "/tmp/fort/example.tal"
-shuffle-uris = true
-
-[rsync]
-program = "rsync"
-arguments-recursive = [ "--recursive", "--times", "$REMOTE", "$LOCAL" ]
-arguments-flat = [ "--times", "$REMOTE", "$LOCAL" ]
-
-[output]
-color-output = true
-output-file-name-format = "file-name"
-roa-output-file = "/tmp/fort/roas.csv"
+- Availability: `argv` only
+
+Path to a JSON file from which additional configuration will be read.
+
+The configuration options are mostly the same as the ones from the `argv` interface. (See the "Availability" metadata of each field.) Here's a full configuration file example:
+
+
{
+	"tal": "/tmp/tal/test.tal",
+	"local-repository": "tmp/repository",
+	"sync-strategy": "root",
+	"shuffle-uris": true,
+
+	"server": {
+		"address": "192.0.2.1",
+		"port": "8323",
+		"backlog": 16,
+		"validation-interval": 120
+	},
+
+	"slurm": "test.slurm",
+
+	"log": {
+		"color-output": true,
+		"file-name-format": "file-name"
+	},
+
+	"rsync": {
+		"program": "rsync",
+		"arguments-recursive": [
+			"--recursive",
+			"--times",
+			"$REMOTE",
+			"$LOCAL"
+		],
+		"arguments-flat": [
+			"--times",
+			"$REMOTE",
+			"$LOCAL"
+		]
+	},
+
+	"incidences": [
+		{
+			"name": "signature algorithm has parameters",
+			"action": "ignore"
+		}
+	]
+}
 

 
 The file acts as a collection of equivalent `argv` arguments; precedence is not modified:
 
 {% highlight bash %}
-$ cat cfg.toml
-[tal]
-tal = "bar"
-$ {{ page.command }} --tal="foo"                                              # tal is "foo"
-$ {{ page.command }} --tal="foo" --configuration-file="cfg.toml"              # tal is "bar"
-$ {{ page.command }} --tal="foo" --configuration-file="cfg.toml" --tal="qux"  # tal is "qux"
+$ cat cfg.json
+{
+	"tal": "bar"
+}
 
-$ cat a.toml
-[root]
-local-repository = "a"
-sync-strategy = "root"
-maximum-certificate-depth = 1
-
-$ cat b.toml
-[root]
-sync-strategy = "strict"
-maximum-certificate-depth = 2
-
-$ cat c.toml
-[root]
-maximum-certificate-depth = 4
+$ {{ page.command }} --tal="foo"                                              # tal is "foo"
+$ {{ page.command }} --tal="foo" --configuration-file="cfg.json"              # tal is "bar"
+$ {{ page.command }} --tal="foo" --configuration-file="cfg.json" --tal="qux"  # tal is "qux"
+
+$ cat a.json
+{
+	"local-repository": "a",
+	"sync-strategy": "root",
+	"maximum-certificate-depth": 1
+}
+
+$ cat b.json
+{
+	"sync-strategy": "strict"
+	"maximum-certificate-depth": 2
+}
+
+$ cat c.json
+{
+	"maximum-certificate-depth": 4
+}
 
 $ {{ page.command }} \
-	--configuration-file="a.toml" \
-	--configuration-file="b.toml" \
-	--configuration-file="c.toml"
+	--configuration-file="a.json" \
+	--configuration-file="b.json" \
+	--configuration-file="c.json"
 $ # local-repository is "a", sync-strategy is "strict" and maximum-certificate-depth is 4
 {% endhighlight %}
 
 ### rsync.program
 
 - Type: String
-- Availability: TOML
+- Availability: JSON
 - Default: `"rsync"`
 
 Name of the program needed to invoke an rsync file transfer.
@@ -335,19 +420,19 @@ Name of the program needed to invoke an rsync file transfer.
 ### rsync.arguments-recursive
 
 - Type: String array
-- Availability: TOML
+- Availability: JSON
 - Default: `[ "--recursive", "--delete", "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
 
 Arguments needed by [`rsync.program`](#rsyncprogram) to perform a recursive rsync.
 
-FORT will replace `"$REMOTE"` with the remote URL it needs to download, and `"$LOCAL"` with the target local directory where the file is supposed to be dropped.
+Fort will replace `"$REMOTE"` with the remote URL it needs to download, and `"$LOCAL"` with the target local directory where the file is supposed to be dropped.
 
 ### rsync.arguments-flat
 
 - Type: String array
-- Availability: TOML
+- Availability: JSON
 - Default: `[ "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
 
 Arguments needed by [`rsync.program`](#rsyncprogram) to perform a single-file rsync.
 
-FORT will replace `"$REMOTE"` with the remote URL it needs to download, and `"$LOCAL"` with the target local directory where the file is supposed to be dropped.
+Fort will replace `"$REMOTE"` with the remote URL it needs to download, and `"$LOCAL"` with the target local directory where the file is supposed to be dropped.
diff --git a/src/config.c b/src/config.c
index 8faf9e7d..d79b506e 100644
--- a/src/config.c
+++ b/src/config.c
@@ -460,7 +460,7 @@ set_default_values(void)
 
 	rpki_config.tal = NULL;
 
-	rpki_config.local_repository = strdup("repository/");
+	rpki_config.local_repository = strdup("/tmp/fort/repository");
 	if (rpki_config.local_repository == NULL) {
 		error = pr_enomem();
 		goto revert_port;
diff --git a/src/object/certificate.c b/src/object/certificate.c
index 60a6c3b4..1570d2dc 100644
--- a/src/object/certificate.c
+++ b/src/object/certificate.c
@@ -2,7 +2,6 @@
 
 #include 
 #include  /* SIZE_MAX */
-#include 
 #include 
 #include 
 
diff --git a/src/rtr/rtr.c b/src/rtr/rtr.c
index 22ff38c1..8e19c1c1 100644
--- a/src/rtr/rtr.c
+++ b/src/rtr/rtr.c
@@ -124,11 +124,6 @@ handle_accept_result(int client_fd, int err)
 	 * (Linux).
 	 */
 
-	/*
-	 * TODO (whatever) print error messages?
-	 * "Connection acceptor thread interrupted" sounds pretty unhelpful.
-	 */
-
 #if __linux__
 	/*
 	 * man 2 accept (on Linux):