Skip to content

Latest commit

 

History

History
151 lines (102 loc) · 5.63 KB

README.md

File metadata and controls

151 lines (102 loc) · 5.63 KB
Raw

DFWFW is deprecated

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

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.

Installation

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

The configuration file (dfwfw.conf) and examples

See the dedicated page about the configuration file and the other with examples.

Command line options and signals

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

Licence

The software is free for any purposes, but no responsibility.

TODO

  • More tests
  • IPv6 support