An ergonomic UFW wrapper for servers running Docker behind ufw-docker
ufw deny doesn't block published Docker container ports — Docker's rules
sit in FORWARD before ufw's INPUT ever sees the traffic. ufw-docker
solves this by adding rules via ufw route ... to the DOCKER-USER chain;
ufw-manager wraps that workflow to make managing ufw-docker easier, with route mode on by default.
- Route mode on by default — rules go to
FORWARD, so they actually apply to container ports. - Interactive wizards with a preview before execution.
- Safe multi-rule delete — sorted descending so indexes don't shift.
- REPL shell — no more retyping
docker compose run --rm ufw-manager …. - Zero host install in Docker mode (runs ufw via
nsenterin the host's namespaces) — or drop the script standalone on any Linux host. - Template shortcuts —
.tplfiles turnufw pg,ufw ssh, etc. into pre-filled wizards.
- ufw (required) — installed and enabled on the host.
- ufw-docker (recommended) — install it on the host so route-mode rules
land in the
DOCKER-USERchain and actually filter published container ports.
Grab the compose file and start the container in the background:
curl -O https://raw.githubusercontent.com/mahelbir/ufw-manager/main/docker-compose.yaml
docker compose up -dThe compose file runs with pid: host, network_mode: host, and
privileged: true. These are required — the container enters PID 1's mount,
uts, ipc, net, and pid namespaces via nsenter so ufw runs on the host using
the host's own binary and /etc/ufw config. Nothing is bind-mounted;
iptables state lives entirely on the host.
Clone the repo and drop the script into /usr/local/bin:
git clone https://github.com/mahelbir/ufw-manager.git
cd ufw-manager
sudo install -m 755 src/ufw-manager /usr/local/bin/ufw-managerWhen run directly on the host, the script compares its own mount namespace
against PID 1's and, since they match, calls ufw directly — no nsenter,
no Docker required.
Open a REPL on the running container:
docker exec -it ufw-manager ufw shellOr run one-shot commands:
docker exec -it ufw-manager ufw allow
docker exec -it ufw-manager ufw listIf you'd rather not keep a container running, use the disposable form:
docker compose run --rm ufw-manager shell
docker compose run --rm ufw-manager listsudo ufw-manager shell
sudo ufw-manager allow
sudo ufw-manager listTemplates turn repetitive rules into single-word commands. Drop a .tpl
file into the templates folder and ufw <name> opens the wizard with port
and protocol pre-filled — usually only the IP is left for you to type or
pass as an arg:
ufw pg # allow:5432:$1:tcp → prompts for IP
ufw pg 1.2.3.4 # same, IP from argvFull file format, placeholder resolution order, and more examples in TEMPLATES.md.
ufw route ... writes rules to the FORWARD chain, which is what Docker's
published-port traffic passes through. Plain ufw ... writes to INPUT,
which only covers traffic terminating on the host itself. On a server that
mostly manages forwarded container traffic, route mode is what you want
nearly all of the time — and it's the default here.
When route mode is on, every rule verb is transparently prefixed:
allow from 1.2.3.4 to any port 5432 proto tcp
→ ufw route allow from 1.2.3.4 to any port 5432 proto tcp
When route mode is off, the rule is sent to ufw unchanged, and you can
use native shorthand like allow 22/tcp to protect the host's own services.
Toggle at runtime:
ufw route-mode # show current mode
ufw route-mode on # force on
ufw route-mode off # force off
ufw route-mode toggle # flipInside the REPL, the prompt shows the active mode in brackets:
ufw[on]> allow from 1.2.3.4 to any port 5432 proto tcp
ufw[on]> route-mode off
route-mode: off
ufw[off]> allow 22/tcp
Set the initial mode via UFW_ROUTE_MODE env var:
# Docker (one-shot)
docker compose run --rm -e UFW_ROUTE_MODE=off ufw-manager allow 22/tcp
# Docker (exec into running container)
docker exec -it -e UFW_ROUTE_MODE=off ufw-manager ufw allow 22/tcp
# Standalone
sudo UFW_ROUTE_MODE=off ufw-manager allow 22/tcpOr set it permanently in docker-compose.yaml:
services:
ufw-manager:
image: mahelbir/ufw-manager
environment:
UFW_ROUTE_MODE: "on" # or "off"
# ...Accepted values: on (default) or off.
| Command | Description |
|---|---|
allow / deny |
Interactive wizard (port → IP → protocol → preview) |
allow [args] / deny [args] |
Pass args to ufw (route-prefixed when mode is on) |
delete / del |
Interactive wizard — numbers or :port[/proto] |
delete [args] / del [args] |
Pass args to ufw |
list / ls |
Alias for ufw status numbered |
route-mode [on/off/toggle] |
Show or change route mode |
shell |
Interactive REPL |
<name> [args] |
Run <name>.tpl — see TEMPLATES.md |
help |
Built-in help |
Any other command is forwarded to host ufw as-is — with the route prefix applied to rule verbs when route mode is on.
It is recommended to check the latest docker-compose.yaml for any changes before updating.
docker compose pull
docker compose up -d --force-recreatePull the latest changes and reinstall:
git pull
sudo install -m 755 src/ufw-manager /usr/local/bin/ufw-managerIf this project helps you, please consider giving it a Star ⭐️ on GitHub. This will encourage us to continue developing and maintaining this project.
This project is licensed under the MIT License - see the LICENSE file for details.