README_en.md

iptables Web Management

iptables-web is a lightweight management console for both iptables and ip6tables. It bundles a UI, REST API, and utilities into a single binary that fits daily operations as well as learning scenarios.

Table of Contents

• Features
• Prerequisites
• Installation
  • Docker (recommended)
  • Binary
• Configuration
• Running & Monitoring
• Web UI Guide
• REST API
• FAQ
• Additional Docs
• License

Features

• Dual-stack management – first-class support for iptables and ip6tables; switch protocols via UI/REST.
• Embedded UI – static assets are baked into the binary, allowing rule browsing, insertion/deletion, and import/export without extra servers.
• REST-first – every UI action has an HTTP endpoint for automation and integration.
• Command helper – execute raw commands or inspect iptables-save results directly in the console.

Only Linux is supported. The service must run with privileges that allow managing the host firewall (root or an equivalent capability; Docker requires privileged mode).

Prerequisites

Requirement	Description
OS	Linux with netfilter/iptables enabled.
Privileges	Root or CAP_NET_ADMIN; Docker needs --privileged --net=host.
Runtime deps	iptables, iptables-save, iptables-restore (IPv6 counterparts included automatically).
Go toolchain (build only)	Go 1.19+ (follow go.mod).

Installation

Docker (recommended)

docker run -d \
  --name iptables-web \
  --privileged=true \
  --net=host \
  -e IPT_WEB_USERNAME=admin \
  -e IPT_WEB_PASSWORD=admin \
  -e IPT_WEB_ADDRESS=:10001 \
  -p 10001:10001 \
  pretty66/iptables-web:latest

• --privileged --net=host lets the container manipulate the host firewall.
• IPT_WEB_ADDRESS defaults to :10001; change to 127.0.0.1:10001 to limit exposure.
• Swap the image tag to match your release or registry.

Binary

git clone https://github.com/pretty66/iptables-web.git
cd iptables-web
make release   # requires Go
./iptables-server -a :10001 -u admin -p admin

Use nohup, systemd, or supervisor to keep it in the background. The default Makefile injects build metadata through -ldflags.

Configuration

Description	CLI flag	Env	Default
Listen address	-a	IPT_WEB_ADDRESS	:10001
Username	-u	IPT_WEB_USERNAME	admin
Password	-p	IPT_WEB_PASSWORD	admin

Priority: CLI > env vars > defaults. Since the service uses Basic Auth for every endpoint, change the credentials in production and place it behind HTTPS/a reverse proxy if possible.

Running & Monitoring

On startup you should see:

listen address: :10001
Build Version:  <commit>  Date:  <yyyy-mm-dd hh:mm:ss>

Open http://<host>:10001 and authenticate via Basic Auth. If the log reports missing ip6tables, the binary is absent on the host—install it or operate in IPv4-only mode.

Web UI Guide

1. Protocol switch – radio buttons (IPv4/IPv6) at the top decide which backend to call; switching refreshes the current table.
2. Tables/chains – tabs cover raw/mangle/nat/filter; visualize system/custom chains and navigate via the right-side directory.
3. Chain actions – insert (-I), append (-A), zero counters (-Z), flush (-F), refresh, and view raw commands (iptables-save snippet).
4. Global actions – clear rules or counters (all/current table), delete empty custom chains, inspect current table output, run arbitrary commands, and import/export rules (save/restore with temporary files created using mode 0600).

REST API

All endpoints require Basic Auth. Optional protocol can be ipv4 (default) or ipv6.

Path	Method	Params	Description
/version	GET	-	Underlying binary version string.
/listRule	POST	table, chain	List chains or a single chain's rules.
/listExec	POST	table, chain	Return iptables-save output or lines containing the chain.
/flushRule	POST	table, chain	Flush the specified table/chain; empty values flush every table.
/flushMetrics	POST	table, chain, id	Reset counters for a rule, chain, or entire table.
/deleteRule	POST	table, chain, id	Delete a rule by its line number.
/getRuleInfo	POST	table, chain, id	Fetch the iptables-save line for the rule.
/flushEmptyCustomChain	POST	-	Remove all empty custom chains.
/export	POST	table, chain	Export rules as text.
/import	POST	rule	Import rule text via iptables-restore.
/exec	POST	args	Execute arbitrary iptables arguments.

FAQ

1. “ipv6 iptables not available” – the host lacks ip6tables or privileges. IPv4 still works; install ip6tables if needed.
2. Authentication prompt loops – double-check the URL and credentials.
3. Rules not applied – run the command directly on the host to confirm there are no nftables conflicts or syntax errors.
4. Import failures – inspect logs for iptables-restore errors (often module dependencies or IPv4/IPv6 mismatch).

Additional Docs

• docs/usage-guide.md – Chinese usage guide (mirrors this README).
• docs/iptables-command-reference.md – iptables/ip6tables command cheatsheet.
• docs/dev-plan.md – development workflow.

License

iptables-web is released under the Apache 2.0 License. See LICENSE for details.