Setting up a
collector

It sits where your blackhole routes point — either as the sinkhole next-hop itself, or reading NetFlow, IPFIX or sFlow from the router that discards the traffic — and turns every blocked beacon into a named internal host, a named user, and the threat category that put the route there.

It runs entirely on your premises. The only thing it asks BlackHawk is what a destination address is, over ordinary HTTPS to this console. Internal addresses, hostnames and usernames never leave your network.

All of these run the same binary and serve the same dashboard.

Mint a token first — Console → Collectors → Register a collector. It is shown once. Everything below assumes you have it.

Linux

curl -fsSL https://blackhole.blackhawk11.com/install.sh | sudo bash -s -- --token bhc_YOUR_TOKEN

Adds a service account, a systemd unit and configuration under /etc/blackhawk-collector. Re-run it to upgrade; configuration and data are preserved. Add --sinkhole eth1 for sinkhole mode.

Windows

iex "& { $(irm https://blackhole.blackhawk11.com/install.ps1) } -Token bhc_YOUR_TOKEN"

Proxmox

Download the -pct-archive from the console, copy it to your Proxmox host’s template store, then:

pct create 3001 local:vztmpl/blackhawk-collector-v0.3.3-pct-amd64.tar.xz \
  --hostname bhc1 --memory 1024 --unprivileged 1 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp
pct start 3001

VMware / ESXi

Download the .ova and use Deploy OVF Template. It carries the hardware definition — LSI Logic SAS controller, E1000 adapter, 2 vCPU, 2 GB — all of which have in-tree Debian drivers, so it boots and gets an address with no VMware Tools work.

vmkfstools -i blackhawk-collector-v0.3.3.vmdk -d thin collector-disk.vmdk

LXD or Incus

lxc image import blackhawk-collector-v0.3.3-lxc-amd64.tar.xz --alias blackhawk-collector
lxc launch blackhawk-collector bhc1

The dashboard listens on port 8443 over HTTPS with a self-signed certificate. Your browser will warn about it; that is expected on a first boot, and you can replace the certificate later with listen.tls_cert and listen.tls_key.

1. Get a shell

pct enter 3001

lxc exec bhc1 -- bash

# the VM appliance does have SSH; a native install is just the host itself
ssh youruser@<address>

2. Find its address

ip -4 addr show eth0 | awk '/inet /{print $2}'

From the Proxmox host without entering the container: pct exec 3001 -- ip -4 addr show eth0

3. Get the dashboard password

An admin account is generated on first start and its password is printed once, to the service log:

journalctl -u blackhawk-collector | grep 'initial dashboard account'

If that has already scrolled away or the log was rotated, set a new one — this works offline and needs no existing password:

blackhawk-collector passwd --user admin

4. Open it

https://<the address from step 2>:8443/

A collector that is installed but not enrolled captures traffic and cannot classify any of it — it has no credential to ask this console what an address is. The install commands above enrol as they go. If you installed without a token, or you are bringing up an appliance, do it now:

blackhawk-collector enroll --server https://blackhole.blackhawk11.com --token bhc_YOUR_TOKEN
systemctl restart blackhawk-collector

enroll verifies the credential before storing it, so a typo fails here rather than silently every five minutes afterwards.

A freshly enrolled collector shows an empty dashboard, because nothing is reaching it yet. Point your router’s flow export at it.

flow exporter BLACKHAWK
 destination <collector address>
 transport udp 2055
 export-protocol netflow-v9

The collector listens on 2055/udp for NetFlow v5, v9 and IPFIX, and 6343/udp for sFlow. Both are enabled by default.

Then tell it what your internal address space actually is. The defaults are the RFC 1918 ranges, which is wrong if you use public addressing internally — and it is what separates “one of ours reached out” from the rest of the internet talking to you. Edit /etc/blackhawk-collector/collector.yml:

network:
  internal:
    - 10.0.0.0/8
    - 192.168.0.0/16

dns:
  enabled: true
  # Your resolvers. The system stub usually cannot answer for internal
  # reverse zones, and then no host ever gets a name.
  servers:
    - 10.10.0.10

Flow mode tells you a conversation happened. Sinkhole mode gives you the packets: every attempt, with source port, destination port and timing, at packet granularity. It is the higher-fidelity answer and it is fully supported.

Nothing changes on our side. Blackhole routes are already advertised to you with a discard next-hop — 192.0.2.1 for IPv4 and 100::1 for IPv6. Normally you point that at a discard interface and the traffic dies there. Point it at the collector instead and the same traffic arrives somewhere that can identify who sent it.

1. Repoint the discard route

This is the whole change, and it happens on your router.

ip route 192.0.2.1 255.255.255.255 Null0

ip route 192.0.2.1 255.255.255.255 <collector address>

set routing-options static route 192.0.2.1/32 next-hop <collector address>

ip route add 192.0.2.1/32 via <collector address>

2. Put the collector on that path

The collector must be reachable at the address you just pointed at, on an interface it can capture from. Install it in sinkhole mode:

curl -fsSL https://blackhole.blackhawk11.com/install.sh | sudo bash -s -- --token bhc_YOUR_TOKEN --sinkhole eth1

Or set it in the config directly:

sensors:
  sinkhole:
    enabled: true
    interface: "eth1"

3. Confirm packets are arriving

Work down this list. Each step tells you whether the problem is above or below it, and none of them needs a packet capture tool inside the container.

a. Is the sinkhole sensor even running?

journalctl -u blackhawk-collector | grep -i sinkhole

sinkhole sensor capturing — it is running; the problem is upstream, keep going.
AF_PACKET socket: operation not permitted — the container is unprivileged and cannot capture. Recreate it with --unprivileged 0.
Nothing at all — the sensor is not enabled. This is the common one: routing traffic at the collector does not switch capture on, and nothing reports an error because nothing was asked to capture. Uncomment the sinkhole block in /etc/blackhawk-collector/collector.yml and restart.

b. Are packets reaching the container at all?

No tcpdump needed — the kernel counts every frame. Run it twice a few seconds apart and compare RX.

ip -s link show eth0

RX climbing while the dashboard stays empty means capture is the problem — go back to (a). RX flat means nothing is arriving, so the problem is the network — continue.

c. Capture from the Proxmox host instead

The host has tcpdumpand can see the container’s veth directly, so you never need to install anything inside it. Find the interface, then watch it:

# on the Proxmox host
grep -H '' /sys/class/net/veth*/ifindex | head        # or: brctl show vmbr0
tcpdump -ni veth3001i0 -c 20

Traffic on the host’s veth but not in the container is unusual and points at the container’s own configuration. Nothing on the veth means it is not getting that far — check the bridge itself with tcpdump -ni vmbr0 host <collector address>.

d. Or just install it

apt-get update && apt-get install -y tcpdump
tcpdump -ni eth0 -c 20

journalctl -u blackhawk-collector | grep -i sinkhole
# and, on the collector, watch the interface you named

Hosts appear on the collector dashboard within a minute of the first blocked beacon. If nothing arrives, the discard route is still pointing at Null0 somewhere upstream — that is nearly always what it is.

Three things, in order.

systemctl status blackhawk-collector

journalctl -u blackhawk-collector | grep -i upstream

# the console is the authority here

Open Console → Collectors. A collector that has checked in shows Online with a last-heartbeat time, its version and its platform. “Awaiting first heartbeat” means it has not yet reached us — that is an enrolment or connectivity problem, not a capture problem.

Still stuck? The service log is the first thing we will ask for: journalctl -u blackhawk-collector -n 200 --no-pager