Configuration reference#

Kapkan is configured by a single YAML file passed with -config. The repository ships two starting points: configs/dev.yaml for local development (test prefixes, loopback bind, dry_run: true) and engine/deploy/config.example.yaml for production, which carries authoritative inline comments and defaults. Copy the production example to /etc/kapkan/config.yaml and adapt it to your network.

The file is reloadable at runtime. Send SIGHUP (systemctl reload kapkan) or POST /api/v1/config/reload and Kapkan re-reads the file and applies the new settings without dropping flow ingestion. Almost everything reloads live, including dry_run, thresholds, networks, hostgroups, baselines, notification settings and sampling.default_rate. Seven things are fixed at startup — a reload that changes any of them is rejected (not silently ignored), so you must restart the daemon to change them:

• the listen addresses;
• BGP identity (bgp.local_asn, bgp.router_id);
• api.listen;
• the samples settings;
• storage settings;
• geoip settings;
• the data-plane attachment and map sizing (dataplane.enabled, interfaces, xdp_mode, pin_path, on_exit and everything under limits) — none of these can change under a loaded XDP program. The static policy in the same block — allowlist, static_rules, ratelimit_profiles — reloads live.

Validating the configuration#

Before you reload or go live, check a file with the engine's own validator:

kapkan -check-config /etc/kapkan/config.yaml

It runs the exact same parse and validation the daemon does — including the cross-field rules a form cannot express (no overlapping networks, hostgroup prefixes contained by a protected network, monotonic escalation ladders) — then prints the resolved configuration (mode, protected networks, and the effective mitigation per hostgroup) and exits 0. On any problem it prints the exact error and exits 1, so it drops cleanly into CI or a pre-deploy check.

kapkan -dump-schema prints the configuration's JSON schema to stdout; the config builder consumes that schema to validate fields in your browser as you type. Both flags, and every other one the binary accepts, are listed in the CLI reference.

Secrets and environment variables#

Secrets are never written in the config file. Each one names an environment variable, and Kapkan reads the value from the process environment at load time:

• notify.telegram.token_env — the Telegram bot token.
• notify.email.username_env / notify.email.password_env — SMTP credentials.
• storage.clickhouse.username_env / password_env — ClickHouse credentials.
• api.token_env (or each api.tokens[].token_env) — the REST API / dashboard bearer token(s).

With the systemd unit, these live in an EnvironmentFile such as /etc/kapkan/kapkan.env with 0600 permissions:

KAPKAN_TG_TOKEN=123456:abc...
KAPKAN_API_TOKEN=a-long-random-string

Top-level keys#

Every top-level key, its meaning, and its default. For the larger subsystems, a one-line summary points to the dedicated page.

Thresholds detail#

The three base thresholds — pps, mbps, flows_per_sec — are mandatory and must all be > 0. The per-protocol limits are optional refinements: tcp_syn_pps counts pure SYNs (SYN set, ACK clear) and frag_pps counts non-first IP fragments. Detection uses OR semantics — any single crossed threshold trips the attack. All values are expressed in real, unsampled units (see Sampling correction).

flows_per_sec is meaningful only for NetFlow/IPFIX exporters. sFlow exports one sample per packet (no flow aggregation), so sFlow-sourced hosts always report flows_per_sec = 0 and that threshold never trips for them — use pps/tcp_syn_pps/udp_pps instead. See Detection.

A complete example#

A realistic production config, adapted from engine/deploy/config.example.yaml:

dry_run: true                       # keep until detection is validated

listen:
  sflow: ":6343"
  netflow: ":2055"                  # NetFlow v5/v9 + IPFIX share this socket

sampling:
  default_rate: 1000                # used only when an exporter omits its own rate
  # boundary: optional interface-boundary counting (deduplicates a flow seen at
  # several vantage points). List each exporter's external/uplink interfaces;
  # set egress_sampling only if calibration shows that ifIndex double-counts (see
  # Sampling correction) — not just because the device samples on egress.
  # boundary_debug: false
  # boundary:
  #   - exporter: "10.1.32.2"
  #     external_ifindexes: [1000025]
  #     egress_sampling: false   # true only if boundary_debug shows ~2x

networks:                           # detection applies ONLY inside these prefixes
  - "203.0.113.0/24"
  - "2001:db8::/32"

protected_whitelist:                # never banned, regardless of traffic
  - "203.0.113.1"                   # gateway / router
  - "203.0.113.2"                   # authoritative nameserver

thresholds:                         # per destination host, after sampling correction
  pps: 80000
  mbps: 1000
  flows_per_sec: 35000
  tcp_syn_pps: 5000                 # optional per-protocol; 0/absent disables
  udp_pps: 60000

thresholds_outgoing:                # detect compromised hosts attacking outward
  pps: 50000
  udp_pps: 20000

dataplane:                          # optional; needs Linux 5.15+ and the systemd drop-in
  interfaces: ["eth0"]              # required; at least one NIC (restart to change)
  # xdp_mode: auto                  # auto (default) | native | generic
  # pin_path: /sys/fs/bpf/kapkan    # bpffs dir; mode 0700, owned by the daemon's uid
  # on_exit: keep                   # keep (default) stays attached and enforcing on shutdown
  # drop_malformed: false           # default: unparseable frames pass and are counted
  allowlist:                        # SOURCE prefixes that always pass, checked first
    - "198.51.100.7"                # monitoring (a bare address is a host route)
    - "192.0.2.0/24"                # management network
  ratelimit_profiles:               # named ceilings; set pps, mbps or both
    - {name: icmp_cap, mbps: 10}
    - {name: handshake_cap, pps: 20}
  static_rules:                     # always-on, before any rule the detector installs
    - name: drop_chargen
      match: {proto: udp, src_port: 19}
      action: drop
    - name: cap_icmp
      match: {proto: icmp}
      action: ratelimit
      profile: icmp_cap             # must name a declared profile
    - name: cap_tls_handshakes      # per-source ceiling on new TLS handshakes
      match: {proto: tcp, dst_port: 443, payload: tls_client_hello}
      action: ratelimit
      profile: handshake_cap
  # limits:
  #   max_dynamic_rules: 4096       # must be >= ban.max_active_bans * 8
  #   max_static_rules: 256
  #   max_ratelimit_sources: 1048576  # per-source token buckets (kernel memory)

ban:
  ttl_seconds: 600                  # every ban auto-withdraws after this
  unban_hysteresis_seconds: 120     # stay below threshold this long before unban
  max_active_bans: 50               # refuse new bans past this cap
  # fallback: blackhole             # degrade a rejected flowspec/divert announce to RTBH (default)
  # max_banned_fraction: 0.05       # never blackhole more than 5% of protected space (per family)
  # max_bans_per_window: 100        # storm guard: at most 100 new bans per window
  # ban_window_seconds: 60          # the window for max_bans_per_window

bgp:
  local_asn: 65001
  router_id: "10.0.0.1"             # must be an IPv4 dotted-quad
  next_hop: "192.0.2.1"             # IPv4 blackhole (discard) next-hop
  next_hop6: "100::1"               # IPv6 blackhole next-hop
  community: "65000:666"            # RTBH community your upstream honors
  neighbors:
    - address: "10.0.0.254"
      remote_asn: 65000

notify:
  telegram:
    token_env: "KAPKAN_TG_TOKEN"    # token read from this env var, never the file
    chat_id: "-1001234567890"
  slack:
    webhook_url: ""                 # optional Slack incoming webhook
  email:
    smtp_host: ""                   # "mail.example.com:587"; empty disables
    from: ""
    to: []
    username_env: "KAPKAN_SMTP_USER"
    password_env: "KAPKAN_SMTP_PASS"
    require_tls: false              # STARTTLS auto-required when credentials are set

api:
  listen: "127.0.0.1:8080"          # default localhost bind needs no auth
  dashboard: true                   # embedded web UI at /; false = JSON API only
  # token_env: "KAPKAN_API_TOKEN"   # REQUIRED before exposing beyond localhost

The hostgroups, baseline and samples blocks are omitted here for brevity. See the dedicated pages for their full schemas:

• Hostgroups — per-prefix thresholds, ban: false, and calculation: total.
• Baselines — factor, half_life_seconds, warmup_seconds, floor.
• The samples block: enabled (default true), buffer_flows (default 65536, max 1048576) and flows_per_attack (default 20). These control the continuous flow ring used to attach dominant sources, ports and protocols to each attack the moment it trips. Changing the sizing requires a restart.

The dataplane block above is shown for shape. It is not self-sufficient: a host with dataplane.enabled: true fails at startup unless the kernel is 5.15 or newer and the shipped kapkan-dataplane.conf systemd drop-in is installed, because the hardened unit grants none of the three capabilities the XDP program needs. Install the drop-in with the config change, not after the first failed start — In-kernel data plane covers the host preparation, the map memory to budget for, and what each startup error means.

Sampling correction#

Flow telemetry is sampled — a router exports one record per N packets. Kapkan multiplies every observed rate by the exporter's sampling rate so thresholds are expressed in real, unsampled traffic units. The rate comes from the flow packet when the exporter reports it, otherwise from sampling.default_rate.

This means a threshold like pps: 80000 is the real attack rate you want to act on, not a sampled count. If your exporter samples at 1:1000 and does not advertise the rate, set sampling.default_rate: 1000 so a single sampled packet-per-second is correctly counted as 1000 real packets-per-second.

Counting each packet once#

Correction assumes each packet is observed once. When the same packet is sampled at more than one vantage point — redundant exporters (e.g. an MLAG pair), ingress and egress sampling on one device (Arista sflow sample output), or transit/peer links — Kapkan would otherwise sum every copy and over-count pps, mbps and flows_per_sec by a constant factor.

Interface-boundary counting fixes this without changing the exporter. Classify each exporter's external (uplink/border) interfaces; a flow is then counted toward a protected host only when it crosses the boundary — inbound on an external input interface, outbound on an external output one. Exporters without a boundary entry keep counting every sample, so you can enable this one exporter at a time.

sampling:
  default_rate: 2500
  boundary:
    - exporter: "10.1.32.2"          # one entry per flow exporter (sampler/agent IP)
      external_ifindexes: [1000025]  # the uplink/border interface ifIndex values
      egress_sampling: false         # only if calibration shows this ifIndex double-counts (see below)

To discover which interfaces are external, set sampling.boundary_debug: true briefly and read kapkan_engine_boundary_debug_bytes_total broken down by exporter and interface.

Related#

• Detection & thresholds — what counts as an attack, per-protocol limits and outgoing detection.
• Hostgroups — per-prefix policies and total-traffic groups.
• Baselines — continuous learned thresholds.
• Mitigation — BGP, RTBH, TTLs and ban caps.
• In-kernel data plane — the dataplane block in full: host preparation, evaluation order and map memory.
• Authentication — securing the API and dashboard.
• Going live — validate, then turn off dry-run.