Agent¶

tis-reporter becomes tis-agent

The agent is today's tis-reporter (repository capnet/tis-reporter, moving to tis/tis-agent). It reports block hits; later it is to take over what tis-pull.sh, tis-push.sh and tis-cron.sh do, with one configuration and schedules and forced pulls set from the platform. Names below are the current ones.

tis-reporter counts packets that hit an IPFW blocklist table on FreeBSD and reports the counts to the TIS API (POST /api/v1/hits, see API reference), for the hit statistics in the web GUI. It is a long-running alternative to tis-hits.sh: instead of parsing the ipfw log, it reads the packets from a divert socket.

How it works¶

An ipfw rule sends packets matching the table (filled by tis-pull.sh --ipfw-table) to a divert port.
The reporter reads each packet and finds the table entry its source address falls into (longest prefix), or its destination when the source isn't listed. IPv4 and IPv6 are supported.
The table is re-read with ipfw table <name> list every reload interval.
Counts are kept per hour and table entry and sent every report interval (at is the start of the hour the hits happened in), in chunks of at most 10 000 values.
When a report fails (network error, timeout, HTTP 408/429/5xx), the counts are kept and sent next time, for at most 24 hours. Other HTTP errors drop the report.
On SIGTERM/SIGINT, the remaining counts are sent before exiting.

Requirements¶

FreeBSD 13 or later (amd64) with ipfw and the ipdivert kernel module (kldload ipdivert, or ipdivert_enable="YES" in /etc/rc.conf).
Run as root (divert sockets are raw sockets).
A TIS API token allowed to report hits (the hits ACL rule, see Tokens & ACL).

Installation¶

The FreeBSD package tis-reporter-<version>.pkg is published to the package registry of the platform project. Download it and install it:

pkg add ./tis-reporter-<version>.pkg

It installs /usr/local/bin/tis-reporter, the rc.d script /usr/local/etc/rc.d/tis_reporter and /usr/local/etc/tis-reporter.json.sample.

ipfw rules¶

divert hands the packet to the reporter, which does not re-inject it, so the packet is dropped – the rule works as a deny, even when the reporter isn't running:

ipfw add 4990 divert 8888 ip from 'table(tis-blocklist)' to me

tee sends a copy and lets the original continue, so a separate rule blocks it:

ipfw add 4990 tee 8888 ip from 'table(tis-blocklist)' to me
ipfw add 4991 deny ip from 'table(tis-blocklist)' to me

Configuration¶

Precedence, lowest first: built-in defaults, environment, the JSON file (-config), command-line flags.

Flag	JSON key	Default	Description
`-config`			Path to the JSON configuration
`-port`	`divert_port`	`8888`	Divert port
`-table`	`table_name`	`tis-blocklist`	IPFW table name
`-reporter`	`reporter`	hostname	Reporter name shown in TIS
`-interval`	`report_interval`	`5m`	How often hits are reported
`-reload-interval`	`table_reload_interval`	`5m`	How often the table is re-read
`-endpoint`	`api_endpoint`	`https://tis.cap-net.cz/api/v1/hits`	TIS API endpoint
`-token`	`api_token`	`TIS_TOKEN`	TIS API token (required)
`-buf-size`	`buf_size`	`65535`	Packet buffer size, bytes
`-log-timestamps`	`log_timestamps`	`true`	Date and time in log lines

The token is sent as Authorization: Bearer <token>; give just the token, without the Bearer prefix. Prefer the JSON file (mode 600) or TIS_TOKEN to -token, which other users can see in ps.

Example /usr/local/etc/tis-reporter.json:

{
  "divert_port": 8888,
  "table_name": "tis-blocklist",
  "reporter": "fw-01",
  "report_interval": "5m",
  "table_reload_interval": "5m",
  "api_token": "<token>"
}

Running¶

As a service (the rc.d script loads ipdivert when needed):

sysrc tis_reporter_enable=YES
service tis_reporter start

The rc.d script passes /usr/local/etc/tis-reporter.json when it exists (tis_reporter_config). The settings can also go to /etc/rc.conf: tis_reporter_table, tis_reporter_reporter, tis_reporter_port, tis_reporter_interval, tis_reporter_reload_interval, tis_reporter_endpoint, tis_reporter_buf_size, tis_reporter_token and tis_reporter_flags for anything else.

The service logs to syslog with the tag tis_reporter, by default to the security facility (/var/log/security) with priority notice, and without its own timestamps. Change it with tis_reporter_syslog_facility and tis_reporter_syslog_priority.

By hand:

tis-reporter -config /usr/local/etc/tis-reporter.json
tis-reporter -version

It exits with a non-zero status when the divert socket fails, and with 0 after SIGTERM/SIGINT. Building, testing and releasing are described in the agent's repository.