Skip to content

Latest commit

 

History

History
161 lines (108 loc) · 5.46 KB

GETTING-STARTED-iptables.md

File metadata and controls

161 lines (108 loc) · 5.46 KB

Getting started - iptables firewall backend

Preparing your host

  • Configure Docker daemon

    When you want DFW to manage your firewall, it is essential that you disable the iptables-features integrated in the Docker daemon. Probably the easiest way to do this is to modify (or create) the file /etc/docker/daemon.json and add the following contents:

    {
    "iptables": false
}

    Be sure to restart your Docker daemon afterwards. (You might also have to remove any rules the Docker-daemon might have already created in iptables. The easiest way to do this is to reboot your host.)

  • Migrate any custom iptables-rules you have to DFW.

    DFW is only able to work with iptables if it manages the entire firewall ruleset. To still enable you to have custom rules, you can specify the backend_defaults.initialization.{v4,v6} keys in your configuration.

    The configuration-keys allow you to add rules to any valid table. The only thing important is that the rules are valid iptables-syntax.

    Example:

    [backend_defaults.initialization.v4]
filter = [
    "-A INPUT -p tcp --dport 22 -j ACCEPT"
]
nat = [
    # Any rule you might want to add to the NAT-table...
]
[backend_defaults.initialization.v6]
filter = [
    "-A INPUT -p tcp --dport 22 -j ACCEPT"
]

Configuration

The general configuration happens across six categories:

  • global_defaults

    This category defines global, default values to be used by DFW and the other categories.

    Field reference.

  • backend_defaults

    This category defines configuration values that are specific to the firewall-backend used.

    Field reference for iptables.

  • container_to_container

    This controls the communication between containers and across Docker networks.

    Field reference.

  • container_to_wider_world

    This controls if and how containers may access the wider world, i.e. what they can communicate across the OUTPUT chain on the host.

    Field reference.

  • container_to_host

    To restrict or allow access to the host, this section is used.

    Field reference.

  • wider_world_to_container

    This controls how the wider world, i.e. whatever comes in through the INPUT chain on the host, can communicate with a container or a Docker network.

    Field reference.

  • container_dnat

    This category allows you to define specific rules for destination network address translation, even or especially across Docker networks.

    Field reference.

See the examples and configuration types for detailed descriptions and examples of every configuration section.

Running DFW

You have a few options of running DFW:

  • Using the official Docker image (preferred!).
  • Using a pre-built binary directly on your host.
  • Install DFW through crates.io.
  • Build from source.

Using the official Docker image

$ docker pull pitkley/dfw:1.3.0
$ docker run -d \
      --name=dfw \
      -v /var/run/docker.sock:/var/run/docker.sock:ro \
      -v /path/to/your/config:/config \
      --net host --cap-add=NET_ADMIN \
      pitkley/dfw:1.3.0 --firewall-backend iptables --config-path /config

This will download a lightweight image, coming in at around 20 MB, and subsequently run it using your configuration. The image supports multiple architectures: amd64, arm64, armv7 (specifically armhf).

Please note that you can also pull the image from the GitHub container registry, GHCR, if you want to avoid potential pull-limitations Docker Hub has put in place:

$ docker pull ghcr.io/pitkley/dfw:1.3.0
$ docker run ... ghcr.io/pitkley/dfw:1.3.0 ...

Using a pre-built binary directly on your host.

You can retrieve the latest pre-built binary from the GitHub releases page:

Install DFW through crates.io.

For this you need to first install Rust and then install DFW using cargo:

$ cargo install dfw
$ dfw --help
dfw 1.3.0
Docker Firewall Framework, in Rust
...

Build from source.

For this you need to first install Rust. You can then check out the repository and build the binary:

$ git checkout https://github.com/pitkley/dfw
$ cd dfw/
$ cargo build --release
$ target/release/dfw
Docker Firewall Framework, in Rust
...