Installation 0x

Installation (0.x)

For the 0.x line, which ended at 0.5.5. Capture is libpcap only. Running 1.x or later? See Installation.

Requirements

Operating system. Linux. Stage 1 uses libpcap for raw capture and Stage 2 shells out to iptables and ipset, so neither works on macOS or Windows. The installer supports apt and dnf based distributions and installs systemd units.

Privileges. Root, for packet capture and firewall control.

Hardware. Modest. The sensor is a few threads doing arithmetic. What matters is that the machine sits on the traffic path.

The installer handles the package dependencies itself, but for reference:

Component	Needs
Stage 1	Rust toolchain, libpcap headers
Stage 2	Python 3, pip, venv
Enforcement	iptables, ipset, the kernel hashlimit module
TLS	openssl, optional but recommended

Network Placement

This is the part that most often goes wrong, so read it before installing.

FLOD only sees traffic that is routed through it. If the traffic source and the protected host sit on the same bridge and the same subnet, they talk directly at Layer 2. The virtual switch forwards frames between their ports and the gateway never sees a single packet, even if it is configured as their default gateway.

The working layout puts them in different subnets with the gateway routing between:

[ Traffic source ]            [ FLOD gateway ]           [ Protected host ]
   Subnet A                    routes A to B                 Subnet B
      |                             |                            |
   [bridge 1] <-------------> [ingress iface]                    |
                              [egress iface] <-----------> [bridge 2]

Because the two ends are on different subnets, traffic is forced through the gateway. Capture runs on the ingress interface, where traffic first arrives.

The egress interface is optional. Configuring it lets FLOD compare what arrived against what was forwarded, which is how it measures the drop rate its own enforcement is achieving.

Install

Clone the repository and run the installer:

git clone https://github.com/DevInBlack001/ddos-reduction-system.git
cd ddos-reduction-system
sudo bash scripts/install.sh --interface ens19 --victim-ips 10.0.0.3,10.0.0.4

Replace the interface with your ingress interface and the addresses with the hosts you are protecting.

To protect a whole subnet instead of a list:

sudo bash scripts/install.sh --interface ens19 --victim-subnet 10.0.0.0/24

Option	Purpose
--interface <IFACE>	Ingress interface to capture on
--victim-ips <IPs>	Comma separated list of protected hosts
--victim-subnet <CIDR>	Protect an entire range instead
--no-service	Skip systemd unit installation

The installer builds Stage 1 in release mode, which takes a few minutes on first run.

What It Does

1. Installs system packages
2. Installs the Rust toolchain into ~/.cargo if absent
3. Compiles Stage 1 and installs it to /usr/local/bin/ddos_stage1
4. Creates the Python virtual environment and installs dependencies
5. Generates a self signed TLS certificate in /etc/ddos_stage2/tls
6. Writes systemd units for both services

Create the Administrator Account

There is no default password. The account must be created before the dashboard will let anyone in:

cd stage2
sudo venv/bin/python3 setup_admin.py

It prompts for a username and password, and will generate a strong password if you press Enter at the prompt. Write it down; it is stored only as a bcrypt hash.

Start the Services

sudo systemctl enable --now ddos-stage2
sudo systemctl enable --now ddos-stage1

Start Stage 2 first. It owns the socket that Stage 1 connects to.

Check both came up:

systemctl status ddos-stage1 ddos-stage2

Log In

Open https://<gateway-ip>:8000 in a browser.

The certificate the installer generates is self signed, so the browser will warn on first connect. That is expected. Click through, or replace /etc/ddos_stage2/tls/cert.pem and key.pem with a certificate issued for that host.

If no certificate exists, the console falls back to plain HTTP and logs a warning. Credentials and session cookies then travel unencrypted, so do not run that way on a network you do not control.

Verify It Is Working

Watch the sensor:

journalctl -fu ddos-stage1

Every few seconds it prints a capture status line:

Capture: status | interface=ens19 | raw_captured=23535 | timeouts=0 |
parse_failed=0 | non_ip=0 | truncated=0 | forwarded=23535

raw_captured climbing means packets are arriving. forwarded should track it closely; that is the count reaching analysis. If raw_captured stays at zero, traffic is not reaching the interface, and the network placement section above is where to look.

The sensor then spends a warm up period learning your baseline before it will flag anything. Until it finishes, no enforcement happens by design.

Updating

sudo bash scripts/update.sh

Rebuilds Stage 1, updates Python dependencies, migrates the database, and restarts both services.

If you deploy by copying the source tree to another location, exclude the runtime state. The database, the whitelist, the target list, and the saved configuration all live in stage2/ alongside the code, and overwriting them with a development copy will replace your accounts and history:

rsync -avh --exclude="venv" --exclude="target" --exclude=".git" \
      --exclude="*.db*" --exclude="*.log" --exclude="__pycache__" \
      ddos-reduction-system /opt/

Uninstalling

sudo bash scripts/uninstall.sh

Removes binaries, the virtual environment, service units, and the socket. Add --remove-build to clear the build cache, and --remove-rust to remove the toolchain as well.