Due to lack of time and motiviation, I can't support this project anymore (read: issues opened here won't receive a response). You might want to take a look on the following port instead:
https://github.com/pitkley/dfw
DFWFW, short of Docker Firewall Framework, is a light-weight Perl tool which offers easy administration of the iptables rules of your Docker containers. It reads the event stream of the local Docker daemon so it gets notified of happenings around the containers real-time and is able to maintain the firewall rules on the fly.
DFWFW focuses mostly on the firewall rules of the "main bridge" itself, but it supports injecting firewall rules into the containers' network namespaces as well.
DFWFW supports having different firewall rules for buildtime containers (docker build
) and production ones (docker run
). The rule specification is straight-forward, you can easily target the containers by simply specifying their names or a matching regular expression. The generated firewall ruleset relies on stateful support of iptables.
By default, a white-list based approach is recommended: the default policy drops everything and you can accept the wanted traffic by setting up white-list based firewall rules. Rules can be specified in the following five categories:
- container_to_container
- container_to_wider_world
- container_to_host
- wider_world_to_container
- container_internals
Container aliasing is also supported; DFWFW is able to maintane some entries in /etc/hosts files of your containers with the desired aliases.
Docker versions supported: 1.9.0+ (including 1.10.0).
DFWFW is currently experimental, feedback and contributions are welcome.
DFWFW is intended to be run as a Docker container itself. The repository is linked with the Docker Hub, so the software images can be fetched the standard way:
docker pull irsl/dfwfw
The recommended way of building dfwfw manually is:
docker build -t dfwfw https://github.com/irsl/dfwfw.git
If you prefer to clone this repo manually, then don't forget about the submodules:
git clone --depth 1 --recursive https://github.com/irsl/dfwfw.git
The tool reads the firewall rules from a JSON formatted configuration file from the location /etc/dfwfw/dfwfw.conf
.
It is recommended to cross-mount this file when creating the container. The default configuration file available
in this repository reproduces the behavior of the Docker daemon with the following options:
--iptables=true --icc=false --ip-forward=true
This means only containers being on the same network are able to communicate with each-other and containers can talk to the outside world. (The DNAT based rules are exception of this.)
After you are happy with the rules generated by DFWFW, it is also recommended to run with --restart=always
policy,
so the firewall will be the same even after restart.
The DFWFW container needs access the following resources in order to work as expected:
Normal operation:
- IP forwarding to be enabled (
echo 1 > /proc/sys/net/ipv4/ip_forward
) - It is highly recommended to run the Docker daemon with
--iptables=false
so only DFWFW would tamper your firewall rules - Access to the Docker socket (so the default Unix domain socket cross-mounted or a TCP IP:port)
- Access to network namespace of the host (
--net=host
) - NET_ADMIN capability so iptables can talk to the kernel via the netlink socket (
--cap-add=NET_ADMIN
)
Example command:
docker run \
--name=dfwfw -d \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/your/directory/with/config:/etc/dfwfw/ \
--net=host \
--cap-add=NET_ADMIN \
irsl/dfwfw
Where /path/to/your/directory/with/config
should contain your configuration file, named dfwfw.conf
.
Additional prerequisites for injecting container internal rules:
- Access to the process namespace of the host (
--pid=host
) - SYS_ADMIN capability so entering namespace of the target container is possible (
--cap-add=SYS_ADMIN
)
Example command:
docker run \
--name=dfwfw -d \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /path/to/your/directory/with/config:/etc/dfwfw/ \
--net=host \
--cap-add=NET_ADMIN \
--pid=host \
--cap-add=SYS_ADMIN \
irsl/dfwfw
Additional prerequisites for container aliasing:
- Access to the container directory of Docker
Example command:
docker run \
--name=dfwfw -d \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/docker/containers:/var/lib/docker/containers \
-v /path/to/your/directory/with/config:/etc/dfwfw/ \
--net=host \
--cap-add=NET_ADMIN \
irsl/dfwfw
See the dedicated page about the configuration file and the other with examples.
DFWFW supports the following command line switches:
--dry-run
: No changes are commited to netfilter, they are just displayed (the same way as without this option)--one-shot
: Events are not monitored, current containers are queried from the Docker daemon, rules are generated and then the application terminates
You can see whats happening by attaching to the container (or starting it in an interactive container):
docker attach dfwfw
You can make DFWFW reread the configuration file by sending a HUP signal:
docker kill --signal=HUP dfwfw
The software is free for any purposes, but no responsibility.
- More tests
- IPv6 support