First-time setup

After the install, sign in as the admin and work through these steps in order. Each one builds on the one before: Heimnull can’t tell inbound from outbound until it knows your networks, and it can’t mitigate anything until BGP is set up.

Configuration lives under Configure at the bottom of the left rail. Every change takes effect within seconds, without a restart.

1. Networks

Configure → Networks. Add every prefix that’s yours, IPv4 and IPv6: the address space you announce and your customers use. Add private ranges too (RFC 1918, CGNAT, ULA) if you want their hosts on host pages.

This list decides everything else:

• Direction. Traffic to one of your addresses is inbound, from one is outbound. Traffic with neither side in your networks is transit.
• What can be mitigated. Heimnull never announces a blackhole or FlowSpec rule for an address outside your networks.

Later, the page’s Possibly missing networks list shows address space that looks like yours (it arrives on an interface facing the internet) but isn’t listed. See Networks.

2. Your routers

Point each router’s flow export at the Heimnull server. The router guides have the full configuration, with the settings that matter for detection:

• Juniper MX: IPFIX packet sampling (inline monitoring), RTBH and FlowSpec.
• Juniper EX: sFlow.
• Juniper SRX: J-Flow, plus session logs to name hosts behind NAT.
• MikroTik: NetFlow v9 and blackholes.

Leave the BGP part of each guide for step 8.

3. Exporters

Configure → Exporters. A router shows up here within a minute of its first datagram.

• Approve it. New exporters wait as pending: Heimnull learns their templates but drops their flows until an admin approves them. To approve new exporters automatically, turn on “Approve new exporters automatically” under Settings → Ingest and lookups.
• Name it, so pages and alerts read “edge-1” rather than an address.
• Check the sampling rate. The exporter shows the rate it detected from the router and where it came from. If the router doesn’t send one, enter it as “Rate until detected” (or “Override rate” to ignore what the router says).
• Add SNMP (v2c community, or v3 user and passwords) to get interface names, speeds and counters. “Test SNMP” polls once and reports what it found.

See Exporters for every option.

4. Interface settings

Configure → Interface settings. Give each of your routers’ interfaces a role:

Role	For
Transit	Links to your transit providers
Peering	Links to internet exchanges and private peers
Internal	Links toward your customers, core or LAN
Other	Anything else

Transit and Peering mean “faces the internet”: traffic entering on one of them and leaving on any other interface is inbound, even when neither address is in your networks yet. These roles also drive capacity planning and the transit view.

Turn on Show on the Interfaces page for the links you want to watch, and set a subscribed rate for links whose commit is below the port speed (for example 2G on a 10G port).

5. Check the System page

System (left rail). Check that:

• every component shows ok;
• each exporter is receiving, with records arriving and little or no sequence loss;
• each exporter’s sampling rate is the one you configured on the router.

Then open Live. Within a minute or two you should see your traffic, split inbound and outbound. If the rates look wrong, compare them with an interface’s SNMP counters on the Interfaces page: a flows-to-SNMP ratio far from 1 usually means a wrong sampling rate. See Common problems.

6. Hostgroups

Configure → Hostgroups. A hostgroup is a set of your prefixes with its own attack limits and its own action. Start with groups that behave differently: subscribers, hosting, infrastructure.

For each hostgroup:

• Prefixes. One per line. An address belongs to the most specific hostgroup prefix that covers it.
• Limits. Inbound and outbound, per host and for the whole group (the group limits catch carpet bombing, where many hosts each get a little). The defaults per host are 2 Gbit/s, 300 kpps, 50 kpps of SYN, 20 kpps of fragments, 500 Mbit/s of amplification and 50 kpps of ICMP inbound. Use the tuning preview to see how many attacks a limit would have caught over your recorded history before you save it.
• Baselines. On by default, in observe mode: after 14 days of history, Heimnull learns each host’s normal peak per hour of the week and reports traffic well above it, without acting.
• Action. What happens when an attack is detected. The default is notify: nothing is announced until you choose a blackhole or FlowSpec action (step 8).

See Hostgroups and Detection.

7. Notifications

Configure → Notifications.

1. Channels. Add where alerts go: email (SMTP), Slack, Microsoft Teams, Telegram, ntfy or a webhook. “Send test” sends a sample attack alert.
2. Routing. Choose which events go to which channel: globally, or per hostgroup. Attacks detected, mitigations applied or refused, BGP sessions, silent exporters, ingest problems and Heimnull’s own health are all separate events.
3. Base URL and server name (Settings → Notifications). The base URL makes the links in messages work (https://heimnull.example.net). The server name goes into every subject, which tells several Heimnull servers apart in one chat.

See Notifications.

8. BGP and mitigation (optional)

To block attacks automatically:

1. Configure → BGP. Set the local AS and router ID, and the default blackhole communities (we recommend RFC 7999’s blackhole, 65535:666).
2. Add a session for each router: its address, AS, optionally an MD5 password, and the IPv4 and IPv6 next hops it should use for blackholes. Turn on Announce mitigations to this session, and IPv4 and IPv6 FlowSpec if the router takes FlowSpec.
3. On the router, set up the session and a strict import policy: see your router’s guide.
4. Try it. Mitigations → Mitigate an address → Preview shows exactly what each router would receive. Then mitigate a test address with Dry run on, then for real, and check the route on the router.
5. Hostgroups → Action. Choose Blackhole, FlowSpec, or FlowSpec, escalating to a blackhole for the hostgroups you want protected. Turn on Dry run first if you want to watch what would be announced for a while.

Also add addresses that must never be blackholed (your DNS resolvers, your routers’ own addresses) under Configure → Whitelist.

See Mitigation and BGP.

9. Users and backups

• Configure → Users. Add accounts for your team: viewer (sees traffic, attacks and most of the configuration, and changes nothing), operator (also mitigates by hand, withdraws and extends mitigations, edits the whitelist and host names, and can withdraw all mitigation in an emergency) or admin (also changes the configuration). See Users and API tokens.
• Back up .env and the database: see Backups and restore.