Environment variables

/opt/heimnull/.env holds the server’s settings and secrets. env-template writes it at install; everything else is configured in the web interface. After changing .env, apply it:

cd /opt/heimnull
sudo docker compose up -d --wait

Keep the file readable by root only (chmod 600), and back it up: see Backups and restore.

Image

Variable	Default	What it does
HN_IMAGE	registry.heimnull.com/heimnull	Where the Heimnull image comes from
HN_VERSION	latest	Which release to run: latest, a major (v3), a minor (v3.1) or a release (v3.1.1). See Upgrading

Web

Variable	Default	What it does
HN_HTTP_PORT	80	The web interface’s port, on all the host’s addresses. Not 8080, which the internal API uses
HN_HTTP_TRUSTED_PROXIES	Loopback	Reverse proxies whose X-Forwarded-For and X-Forwarded-Proto headers are believed: comma-separated addresses or CIDRs. A proxy on the same host connecting from 127.0.0.1 needs nothing. See HTTPS

Flow ports

Variable	Default	What it does
HN_NETFLOW_PORT	2055	UDP port for NetFlow v9
HN_IPFIX_PORT	4739	UDP port for IPFIX
HN_SFLOW_PORT	6343	UDP port for sFlow. 0 turns it off
HN_SESSIONLOG_PORT	5514	UDP port for firewall session logs, opened only while an exporter uses them

Every flow port accepts every format.

Sizing

env-template sets these for the machine it runs on.

Variable	Set to	What it does
HN_APP_CPUS	3/4 of the CPUs	CPU ceiling for the heimnull container. 0 means none
HN_CH_CPUS	1/2 of the CPUs	CPU ceiling for ClickHouse, so a heavy search can’t starve ingest
HN_APP_MEM	3/8 of the memory	Memory limit for the heimnull container, for example 6g
HN_CH_MEM	3/8 of the memory	Memory limit for ClickHouse. It stops allocating at 85% of this
HN_PG_MEM	1/16 of the memory, 512 MB to 1 GB	Memory limit for PostgreSQL

Docker refuses a CPU ceiling above the host’s CPU count, so after resizing the server, run env-template again to see the new values, and copy just these five lines into your .env:

sudo docker run --rm registry.heimnull.com/heimnull:latest env-template | grep -E '^HN_(APP|CH|PG)_(CPUS|MEM)='

Secrets

Generated at random by env-template.

Variable	What it is
POSTGRES_PASSWORD	PostgreSQL’s password
CH_ADMIN_PASSWORD, CH_WRITER_PASSWORD, CH_READER_PASSWORD	ClickHouse’s three users: migrations and retention, inserts, and read-only queries
HN_SECRET_KEY	Encrypts the secrets stored in the database: SNMP communities and passwords, BGP MD5 passwords, notification credentials and webhook URLs

Don’t change these after the first start

The database passwords are set when the databases are created, and changing HN_SECRET_KEY makes every stored secret unreadable. Keep .env with your backups: a database restored without its HN_SECRET_KEY loses those secrets.

Optional

Not in the generated file; add them when you need them.

Variable	Default	What it does
HN_DATASETS_OFFLINE	Empty	1 stops every dataset download and the update check. Heimnull uses the copies bundled in its image. See Network
HN_PG_PORT	5432	PostgreSQL’s port on 127.0.0.1
HN_CH_NATIVE_PORT	9000	ClickHouse’s native port on 127.0.0.1
HN_CH_HTTP_PORT	8123	ClickHouse’s HTTP port on 127.0.0.1
HN_API_LISTEN	127.0.0.1:8080	The internal API’s address
HN_GOBGP_API	127.0.0.1:50051	The BGP speaker’s control address
HN_FLOWD_MEMLIMIT, HN_API_MEMLIMIT	55% and 14% of HN_APP_MEM	Memory targets for the flow collector and the API inside the container, for example 3400MiB
POSTGRES_USER, POSTGRES_DB	heimnull	Only at the first start, like the passwords

Change the loopback ports only if something else on the host uses them. See Ports.