Skip to content

Getting Started

This guide walks you from a fresh server to a fully operational flowwler deployment with flow ingestion and BGP mitigation.

Prerequisites

  • Debian/Ubuntu server (amd64 or arm64)
  • A customer/edge router that will accept blackhole/FlowSpec routes from flowwler and discard the traffic locally or propagate mitigation routes to upstream providers
  • A router or switch that can export NetFlow v9/IPFIX or sFlow v5 toward the flowwler server

Step 1 - Install flowwler

Add the APT repository

sudo mkdir -p /etc/apt/keyrings /etc/apt/auth.conf.d

curl -fsSL https://mirror.level66.services/apt/flowwler.gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/flowwler.gpg

sudo tee /etc/apt/sources.list.d/flowwler.sources >/dev/null <<'EOF'
Types: deb
URIs: https://mirror.level66.services/apt/flowwler
Suites: stable
Components: main
Architectures: amd64 arm64
Signed-By: /etc/apt/keyrings/flowwler.gpg
EOF

sudo chmod 0644 /etc/apt/keyrings/flowwler.gpg

Configure repository credentials

Credentials are issued per customer. Replace youruser and yourpassword with the values provided to you:

sudo tee /etc/apt/auth.conf.d/flowwler.conf >/dev/null <<'EOF'
machine mirror.level66.services
login youruser
password yourpassword
EOF

sudo chmod 0600 /etc/apt/auth.conf.d/flowwler.conf

Install

sudo apt update
sudo apt install flowwler

The package installs the following:

Path Description
/usr/bin/flowwler Daemon binary
/lib/systemd/system/flowwler.service systemd unit
/usr/share/flowwler/config.example.yaml Annotated example configuration
/etc/flowwler/config.yaml Active configuration (written from example on first install only)

The flowwler system user, /etc/flowwler, and /var/lib/flowwler are created automatically.

Step 2 - Open firewall ports

flowwler needs inbound UDP for flow export and outbound TCP 179 for BGP:

# NetFlow / IPFIX
sudo ufw allow 2055/udp

# sFlow
sudo ufw allow 6343/udp

# BGP
sudo ufw allow 179/tcp

Step 3 - Add your first protected group

Edit /etc/flowwler/config.yaml. Add a groups: block with the subnets you want to protect and a basic escalation ladder. The example below activates a FlowSpec discard at 500 Mbps and escalates to a full host blackhole at 2 Gbps:

groups:
  - name: "my-network"
    subnets:
      - "203.0.113.0/24"
      - "2001:db8::/48"
    escalation:
      - level: 1
        condition:
          bps: 500m      # 500 Mbps
        mitigation:
          type: flowspec
          flowspec:
            action: discard
        escalate_after: 2m
      - level: 2
        condition:
          bps: 2g        # 2 Gbps
        mitigation:
          type: blackhole
          blackhole:
            community: "65535:666"
        escalate_after: 0s

BGP peer configuration is added in Step 7. You can reload with an incomplete peer list - flowwler will start and wait for BGP connectivity.

Step 4 - Reload the service

Validate the config and apply it without restarting:

flowwler validate /etc/flowwler/config.yaml  # check for errors first
sudo systemctl reload flowwler               # sends SIGHUP
sudo journalctl -u flowwler -f               # confirm successful reload

A successful reload logs:

{"level":"info","msg":"config reloaded successfully","log_level":"info"}

Step 5 - Configure flow-export on your router

Point your routers flow-export at the flowwler server IP. Example configurations are in the Router Configuration reference.

Step 6 - Verify flow data is being received

Wait 60–90 seconds after applying the router config (templates arrive first, data sets follow). Then check the metrics endpoint:

curl -s http://localhost:9731/metrics | grep flowwler_router_flows_received_total

You should see a non-zero and growing counter keyed to your router's IP:

flowwler_router_flows_received_total{protocol="netflow",router="192.0.2.1"} 4821

Also confirm the router is marked up:

curl -s http://localhost:9731/metrics | grep flowwler_router_up
# flowwler_router_up{protocol="netflow",router="192.0.2.1"} 1

If the counter stays at zero, see Troubleshooting - No flows being detected.

Step 7 - Configure BGP peering in flowwler

Add the gobgp: block to /etc/flowwler/config.yaml. flowwler acts as the BGP speaker - your customer/edge router is the peer:

gobgp:
  local_asn: 65000              # flowwler's ASN
  router_id: "192.0.2.100"     # flowwler's IP address
  peers:
    - neighbor_address: "192.0.2.1"
      peer_asn: 65001           # customer router's ASN

For multiple routers, add one entry per peer under peers:.

Step 8 - Reload the configuration

flowwler validate /etc/flowwler/config.yaml
sudo systemctl reload flowwler

flowwler will immediately attempt to establish the BGP session. Check the log for the connection attempt:

sudo journalctl -u flowwler | grep bgp

Step 9 - Configure BGP on the router

The router must accept routes from flowwler and apply blackhole/FlowSpec actions. Example configurations are in the Router Configuration reference.

Step 10 - Verify BGP and check readiness

Check BGP session state

curl -s http://localhost:9731/api/v1/bgp/peers

A healthy session looks like:

[{"neighbor_address":"192.0.2.1","peer_asn":65001,"established":true,"sent_routes":0,"received_routes":4}]

Or via Prometheus:

curl -s http://localhost:9731/metrics | grep flowwler_bgp_peer_up
# flowwler_bgp_peer_up{peer="192.0.2.1"} 1

Confirm groups are loaded

curl -s http://localhost:9731/api/v1/groups
curl -s http://localhost:9731/metrics | grep flowwler_group_up
# flowwler_group_up{group="my-network"} 1

Check traffic is being measured

curl -s http://localhost:9731/metrics | grep flowwler_group_bps
# flowwler_group_bps{group="my-network"} 1.24e+09

flowwler is now running, receiving flow data, and ready to announce BGP mitigations when thresholds are exceeded.

Next steps

  • Configuration Reference - full YAML reference for escalation levels, FlowSpec rules, per-group BGP attributes, notifications, and more
  • Rule Examples - ready-to-use rules for common attack patterns (SYN floods, UDP amplification, fragment floods, and more)
  • Administration Guide - hot-reload, upgrades, and routine maintenance
  • Metrics Reference - Prometheus metrics and recommended alerts
  • Web UI - install flowwler-web for a browser-based dashboard to monitor escalations, mitigations, BGP peers, and routers