One line in. Text out.

voidgatectl

Drop reasons: 1 manual, 2 policy, 3 aggregate.

Config

One key = value per line; # starts a comment. Every key is optional, and the defaults below are also what ships in configs/voidgate.conf. The commented file explains each one in more depth.

live: voidgatectl reload applies it. restart: fixed when the daemon starts. The built-in allow list is 169.254.169.254/32, 127.0.0.0/8, ::1/128, fe80::/10, ff02::/16.

Prometheus

When metrics_port is positive, the daemon listens on localhost and serves GET /metrics:

# TYPE voidgate_armed gauge
voidgate_armed 0
# TYPE voidgate_rx_packets_total counter
voidgate_rx_packets_total 0
# TYPE voidgate_rx_bytes_total counter
voidgate_rx_bytes_total 0
# TYPE voidgate_dropped_packets_total counter
voidgate_dropped_packets_total 0
# TYPE voidgate_map_full_total counter
voidgate_map_full_total 0
# TYPE voidgate_drop_prefixes gauge
voidgate_drop_prefixes 0
# TYPE voidgate_rx_pps gauge
voidgate_rx_pps 0

OpenResty client

voidgate is not a WAF. Let OpenResty, or a gateway built on it such as Kong or APISIX, decide who is abusive and push that address down to XDP with a timed drop. lua/resty/voidgate.lua talks to the socket over a non-blocking cosocket. Install it with sudo make install-lua (OpenResty's site lualib, or set LUA_DIR), and add the worker user to the group voidgate, which the shipped unit gives the socket to with -g voidgate, so nginx can reach it: commonly nobody for OpenResty, kong for Kong, and nobody or apisix (Docker image) for APISIX.

lua_shared_dict voidgate_ban 1m;

location / {
    limit_req zone=api burst=20 nodelay;
    limit_req_status 429;
    log_by_lua_block {
        if ngx.status == 429 then
            require("resty.voidgate").ban(ngx.var.remote_addr, 600,  -- 10m
                                          { dict = "voidgate_ban" })
        end
    }
}

ban(ip, ttl, opt) works from every phase but init_by_lua*, log included, and sends one ban per address per window. ban_now(ip, ttl) sends at once and returns the daemon's answer, in rewrite, access, content or timer context. Every drop from Lua needs a ttl: a permanent drop is voidgatectl drop's job. The other methods (status(), stats(), drops(), drop(cidr, ttl), undrop(), arm(), disarm(), reload()) run in rewrite, access, content or timer context and return nil, err on failure. stats() returns 64-bit counters as decimal strings.

ACTIVE policy, short

Each tick, remotes over threshold become /32 or /128. Dense clusters become /24 or /64. Userspace will not install a prefix that covers the VM itself or the allow list. On disarm, remote_* stays; the next arm re-baselines snapshots so leftover counters are not a phantom flood.