Requirements

Quick Install

The installer runs these steps in order:

1. Packages — nftables, dnsmasq, WireGuard, Python 3, Flask, Gunicorn, Suricata, CrowdSec
2. Network — disables NetworkManager, configures ifupdown static WAN/LAN, creates aegisgate-net-setup.service
3. nftables — default firewall: input (drop), forward (drop), postrouting (NAT), blacklist/allowlist/CrowdSec/IPBL sets, Suricata NFQ rule
4. dnsmasq — DNS/DHCP server with blocklist streaming config, per-list files, validates entries (strips CSS selectors, URL paths)
5. Suricata — IPS mode (engine-mode: ips), NFQ queue 0, ct state new, local-bridge.rules with 5 drop + 6 alert rules
6. WireGuard — VPN server interface with ACL system
7. Dashboard — Flask + Gunicorn on :8080
8. Systemd — all services enabled and started

First Login

1. Open http://gateway-ip:8080 in your browser
2. Log in with the credentials printed at the end of the install script
3. Go to Settings → Change Password and set a strong password
4. Configure WAN/LAN roles in Network → Interfaces
5. Start the VPN in VPN → Start
6. Enable DNS blocklists in DNS → Blocklists

Architecture

AegisGate is a Python Flask application (app.py) served by Gunicorn, managing nftables, dnsmasq, WireGuard, Suricata, CrowdSec and QoS through dedicated modules.

Boot Sequence

1. networking.serviceBrings up interfaces with ifupdown static config
2. aegisgate-net-setup.serviceSets interface roles (WAN/LAN/WiFi), VLANs, routes
3. nftables.serviceApplies firewall rules: input, forward, postrouting chains + Suricata NFQ rule
4. aegisgate-restore.serviceRestores saved state: security toggles, QoS, custom rules, IP sets, blocklists
5. dnsmasq.serviceDNS/DHCP server starts with conf-file= chain, blocklists, per-client policies
6. suricata.serviceIPS engine starts in NFQ mode (-q 0 --set engine-mode=ips)
7. crowdsec + bouncerThreat intelligence feeds nft sets
8. nft-dashboard.serviceGunicorn serves Flask dashboard on :8080

Config Files

All persistent state is stored under /opt/nft-dashboard/data/ and restored at boot by restore-state.py:

{
  "wan_interface": "eth0",
  "lan_interface": "eth1",
  "wan_ip": "31.172.140.234",
  "lan_ip": "172.24.1.2",
  "listen_addr": "172.24.1.2",
  "listen_port": 8080
}

{ "users": { "admin": { "password_hash": "pbkdf2:...", "role": "admin" } } }

-- dns_rules (blocklist entries, groups, policies, services)
-- dns_lists (blocklist sources, update timestamps)
-- dns_queries (query log, latency, client info)
-- dns_custom_services (service bundle definitions)

dnsmasq config chain:

Systemd Services

Aegis DNS / AdBlock

Aegis DNS is a network-wide ad and malware blocker powered by dnsmasq. Every device on the network — phones, TVs, laptops, IoT — inherits the same filtering without any per-device configuration.

• 680k+ domains blocked via HaGeZi Ultimate + custom lists
• Block modes: 0.0.0.0 (null_ip, default), NXDOMAIN, REFUSED, or custom IP
• Per-list files: blocklists stored in aegisgate-blocklists/ directory, one file per source (streaming, no memory spikes)
• Validation: CSS selectors (##), URL paths (/path/to/script.js), and bare / prefixes are automatically rejected — no more accidental domain blocks like ukr.net##div
• DNS hijack: redirect all port 53 traffic to the gateway DNS
• DoH bypass protection: block known DNS-over-HTTPS providers
• DHCP integration: per-client DNS policy assignment via dnsmasq set: tags

Blocklists

AegisGate ships with HaGeZi Ultimate (~660k domains) and supports custom lists. Lists are stored per-source in aegisgate-blocklists/ and streamed from the SQLite database to avoid memory spikes.

• Add a list: DNS → Blocklists → Add URL or upload a file
• Update: Automatic daily at 04:17 via cron, or manual refresh from the UI
• Validation: Entries with ##, [, ], or URL paths after TLD are automatically disabled — they would block entire domains in dnsmasq

Client Groups & Policies

Assign devices to groups with different filtering levels. Each group can have its own blocked services, blocklists, and upstream DNS.

• Kids: block YouTube, TikTok, social media, adult content, gambling
• IoT: block telemetry, ad/tracker domains
• Guest: block ads, malware; allow social media
• Work: minimal blocking, allow all work services

Service Bundles

One-click blocking of popular services. Each bundle contains domains, wildcards, and known alternate domains for the service.

DNS Hijack & DoH

DNS hijack redirects all port 53 traffic (TCP/UDP) on the LAN interface to the gateway dnsmasq. This prevents clients from bypassing filtering by manually setting a different DNS server.

DoH bypass protection blocks known DNS-over-HTTPS provider domains and IPs so clients cannot tunnel DNS queries over HTTPS.

Local Records & Rewrites

• Local records: map myserver.lan → 192.168.1.100
• Rewrites: map app.example.com → custom IP or NXDOMAIN / REFUSED
• Wildcards: *.example.com for whole-domain overrides

DNS Dashboard

Pi-hole-style dashboard with real-time KPIs: total queries, blocked count, block rate, unique clients, top blocked domains, top clients, query log with period filter (5m/1h/6h/12h/24h/7d/all).

nftables Firewall

The AegisGate firewall is built on nftables with a strict default-drop policy on both input and forward chains. All traffic passes through multiple security layers.

• Input chain (policy: drop): Suricata NFQ → established/related → invalid drop → blacklist/CrowdSec/IPBL → allowlist/trusted → DNS/DHCP/SSH/HTTP/HTTPS accept
• Forward chain (policy: drop): established → invalid → blacklist/CrowdSec/IPBL → allowlist/trusted → hostname rules → accept
• Postrouting: masquerade for VPN and LAN → WAN, DNAT port forwarding

IP Sets

Hostname Firewall Rules

DNS Clients table includes a Track Hostname checkbox and a Firewall dropdown (Allow/Drop). When set to Drop, the hostname's resolved IPs are added to the forward chain as drop rules. This lets you block specific devices from accessing the internet while still allowing DNS.

NAT, DNAT & Masquerade

Port forwarding (DNAT) publishes internal services to the WAN. VPN masquerade ensures VPN clients can reach the internet. All NAT rules are managed from the dashboard.

Security Rules

11 toggleable security rules with one-click enable/disable:

Suricata IPS

AegisGate runs Suricata in IPS mode using NFQ (NetFilter Queue). This means Suricata doesn't just detect — it drops malicious packets before they reach the target.

• Engine mode: ips (set in suricata.yaml and systemd override)
• NFQ: queue 0, mode: accept, fail-open: yes, queue-length: 1024
• NFQ rule: nft insert rule inet filter input iifname "eth0" ct state new queue flags bypass to 0 — first rule in input chain
• ct state new: mandatory; without it Suricata drops established packets (stream_midstream errors)
• action-order: pass, drop, reject, alert

Drop & Alert Rules

/etc/suricata/rules/local-bridge.rules:

Plus Emerging Threats rules (~49k alert rules) from the suricata-et package.

IPS Dashboard

The dashboard Suricata tab shows:

• IPS Stats: Accepted / Blocked / Alerts (from suricatasc dump-counters)
• Alerts table: period-filtered (5m/1h/6h/12h/24h/7d/all), with DROP (red) and ALERT (yellow) tags
• Local drop SIDs (9000xxx) displayed as DROP even though Suricata 7 NFQ logs action=allowed
• Real-time: auto-refresh every 60s via AJAX

WireGuard VPN

Built-in WireGuard VPN server with per-peer ACL, QR provisioning, bandwidth tracking and connection events.

• One-click start/stop from the dashboard
• Per-peer ACL: Internet, LAN, DMZ, or custom networks
• QR codes for instant mobile provisioning
• Bandwidth per peer: live TX/RX stats
• VPN NAT: masquerade rules auto-managed for internet access
• Download client: wireguard.com/install

ACL Modes

QR Provisioning

Each peer has a "QR" button that generates a scannable WireGuard config QR code. Scan it with the WireGuard mobile app (Android/iOS) to import the tunnel instantly — no manual config needed.

Download Client

Download the official WireGuard client for your platform:

DHCP Server

Full dnsmasq DHCP server integrated with DNS policies. Leases, static assignments, and per-client DNS tags are all managed from the dashboard.

• Static leases: MAC → IP assignment with hostname tracking
• DNS tags: each static lease gets a set:ClientName tag for per-client DNS policy
• Duplicate protection: seen_ips set prevents duplicate IPs in generated config
• Config order: dhcp.conf loaded before clients.conf to ensure default options come first

QoS / Traffic Shaping

Bandwidth management with pre-built profiles and manual rules. Supports CAKE, fq_codel, HTB and HFSC algorithms.

• Profiles: Gaming (latency priority), Streaming (bandwidth), Office (balanced), IoT (minimal), Custom
• Speed test: built-in with real-time SVG gauges
• Manual rules: per-port, per-protocol, per-IP shaping
• Auto-apply: profile applies tc/queue disciplines on the WAN interface

Network

Complete interface management with ifupdown static config, VLAN CRUD, static routes, and Multi-WAN.

• Interface roles: WAN, LAN, WiFi, VPN with live status
• VLANs: create/delete 802.1Q VLANs on any interface
• Static routes: custom routing for VPN, DMZ, or specific networks
• Conntrack: live connection tracking table with filtering

Monitoring Dashboard

Real-time dashboard with period filter (5m/1h/6h/12h/24h/7d/all):

• Drops: total dropped packets, unique sources, by rule, by port
• Blacklist: manual blacklist IPs with timeouts
• CrowdSec: auto-banned IPs from community threat intel, deduplicated
• Suricata: IPS stats (Accepted/Blocked/Alerts), alerts table with period filter, DROP/ALERT tags
• SSH attempts: failed/success logins
• Services: status and uptime for nftables, dnsmasq, WireGuard, Suricata, CrowdSec
• Auto-refresh: dashboard stats every 30s, DNS top stats every 60s

GeoIP

Geographic threat analysis using MaxMind GeoLite2 databases and CrowdSec blacklist data. Shows attack origins by country, ASN, and IP.

System Health

CPU usage, RAM, CPU temperature, conntrack table occupancy, disk usage, and per-interface bandwidth graphs with live updates.

Policy Modes

One-click security posture profiles that configure all security rules at once:

CrowdSec Integration

CrowdSec provides community-driven threat intelligence. When CrowdSec detects an attack pattern, it automatically adds the offending IP to the crowdsec-blacklists nft set. AegisGate then drops all packets from that IP in both input and forward chains.

• Auto-ban: decisions are deduplicated by IP — only the longest-duration decision per IP is kept
• nft sets: crowdsec-blacklists (IPv4) and crowdsec6-blacklists (IPv6) with interval+timeout
• Dashboard: shows CrowdSec decisions, IP, scenario, duration and remaining TTL
• 33k+ IPs blocked at any given time from community threat intelligence

IP Blocklists

External IP blocklists are loaded into nft sets ipbl_ipv4 and ipbl_ipv6 with interval, timeout, auto-merge flags. These sets are checked in both input and forward chains.

• 18k+ IPv4 entries from curated threat lists
• Automatic updates via cron (every 6 hours)
• Custom entries: add individual IPs or CIDRs from the dashboard
• Logged: DROP_IPBL_SADDR_INPUT, DROP_IPBL_SADDR_INPUT, DROP_IPBL4_SRC, DROP_IPBL4_DST

GeoIP

Geographic threat analysis using MaxMind GeoLite2 databases (City + ASN). Shows attack origins by country and ASN. CrowdSec blacklist IPs are overlaid on the map.

• Country breakdown: attacks by country with flag emojis
• ASN breakdown: top ISPs and organizations
• IP details: click any IP to see country, city, ASN, ISP

Reports & Export

Export security reports in HTML format for auditing or compliance. Reports include:

• 11 export sections: nft drops, SSH attempts, blacklisted IPs, CrowdSec decisions, Suricata alerts (with DROP/ALERT tags and IPS stats), QoS bandwidth, DHCP leases, VPN peers, GeoIP, system health
• Period-filtered data matching the dashboard period selector
• Flag emojis for country codes
• Standalone HTML files with embedded CSS — no server needed to view

Multi-WAN

Configure multiple WAN interfaces with failover and policy routing. Each WAN can have its own gateway, metric, and routing rules.

• Failover: automatic switch to backup WAN when primary goes down
• Policy routing: route specific traffic (VPN, LAN) through specific WAN
• FRR/BGP support: optional BGP/OSPF routing protocols
• Status monitoring: real-time WAN status, latency, and packet loss

Cron Jobs

AegisGate sets up the following scheduled tasks:

Troubleshooting

• DNS not resolving: Check dnsmasq --test for config errors. Verify conf-file= (not conf-dir=) in /etc/dnsmasq.conf. Blocklist entries with ##, [, or URL paths are auto-stripped.
• Suricata not blocking: Verify engine-mode: ips in suricata.yaml and -q 0 --set engine-mode=ips in systemd override. NFQ rule must be FIRST in input chain (nft insert rule, not nft add rule). Must have ct state new.
• DNS blocks whole domain: Caused by invalid entries like address=/domain.com##div/0.0.0.0 or address=/domain.com/path/0.0.0.0. AegisGate auto-strips these on config generation. Run the installer's DB cleanup to disable existing bad entries.
• VPN can't reach internet: Check POSTROUTING masquerade rules for wg0. Each peer ACL must allow internet (0.0.0.0/0 allowed_ips).
• Hostnames not resolving: DHCP tags require dhcp.conf loaded before clients.conf. The conf-file= chain ensures this order.
• Dashboard shows only 2 rules: Period filter (1h default) may exclude rules with few hits. Change to "All" to see all 6+ rules. Excluded networks (LAN, bogon) are filtered from the dashboard.