Configuring fingerd

fingerd stores its configuration in the environment. For commodity, a .env configuration is proposed, install the python-dotenv module and copy the .env.template file into .env and edit it following its comments.

BIND

This variable is mandatory and contains the endpoints to bind on, separated with commas (,). Each endpoint can have the following format:

example.com

Bind on all addresses that example.com resolve as (IPv4 and IPv6), port 79.

example.com:1234

Bind on all addresses that example.com resolve as (IPv4 and IPv6), port 1234.

1.2.3.4 or [1.2.3.4]

Bind on 1.2.3.4 (IPv4), port 79.

1.2.3.4:1234 or [1.2.3.4]:1234

Bind on 1.2.3.4 (IPv4), port 1234.

::1:2:3:4 or [::1:2:3:4]

Bind on ::1:2:3:4 (IPv6) port 79.

[::1:2:3:4]:1234

Bind on ::1:2:3:4 (IPv6) port 1234.

For example, localhost usually binds on 127.0.0.1:79 (IPv4) and [::1]:79 (IPv6).

FINGER_HOST

The host as which fingerd identifies itself (domain name), LOCALHOST by default.

FINGER_TYPE

The interface type, or where the displayed data comes from. There are several interface types:

DUMMY

There is no data (no users, no sessions).

NATIVE

The data is gathered from the system.

SCENARIO

The data is gathered from a scenario (see Scenario (scripted actions) below).

LIVE

The data is gathered from actions given in an IPC endpoint (see Live actions).

By default, the interface type is NATIVE.

If the interface type is SCENARIO, then the following variable is required:

FINGER_SCENARIO

The scenario path (see Actions for the format).

FINGER_INCOMING

The finger live action source (see Live actions).

The finger server should be available through the TCP port 79, which can only be opened by root on UNIX-like machines. Instead of using this port directly, which forces the use of the root user to manage the service, you can redirect the incoming transmissions from an interface on TCP port 79 to another TCP port which you can open as a user (port number over 1024) by appending a rule in iptables:

iptables -t nat -A OUTPUT -p tcp [-s <source ip>] [-d <destination ip>] \
        --dport 79 -j DNAT --to '<ip:port>'

Where <source ip> is the source IP address or network that are redirected, <destination ip> is the destination IP address or network for which the requests are redirected and <ip:port> is the IP and port you want to forward the packets to, e.g. 127.0.0.1:4000.

For example, for running the server locally on port 3999 and only accepting requests from the same machine (on IPv4 and IPv6):

iptables -t nat -A OUTPUT -p tcp -s 127.0.0.1 -d 127.0.0.1 \
        --dport 79 -j DNAT --to 127.0.0.1:3999
ip6tables -t nat -A OUTPUT -p tcp -s ::1 -d ::1 \
        --dport 79 -j DNAT --to '[::1]:3999'

Actions

While interfaces provide still information to the server, some use actions underneath. In this section, the actions themselves are described.

Scenario (scripted actions)

Scenarios, represented by the SCENARIO server type, are scripted sequences of actions.

Scenarios use a TOML document describing actions, which are points in time where something happens. Every action has a time offset, using a TOML array section ([[something]]), and properties describing what’s happening. Time offsets are represented the following way:

-?(<weeks>w)?(<days>[jd])?(<hours>h)?(<minutes>m)?(<seconds>s)?

Where negative times, starting with a dash (-), are the initial situation, what is supposed to have happened before the beginning.

For example, -1w5d2h means “1 week, 5 days and 2 hours before the origin” and 2j means “2 days after the origin”. So if we want to make an action that takes place 5 seconds after the origin, the first line of the action will be the following one:

[[5s]]

All actions have a type represented by the type property, and other properties depending on the type. Types and related properties are described in the Actions section.

Live actions

TODO