IPv6 Networking Support

Sandfly containers can reach IPv6 hosts when the host, the container runtime and its version all support IPv6. The installer and start scripts check these requirements automatically. If any requirement is not met, the container network is created as IPv4 only, and Sandfly continues to work over IPv4.

IPv6 lets the Sandfly node scan hosts by their IPv6 address. When IPv6 is enabled, that network has both an IPv4 and IPv6 subnet, and outbound IPv6 traffic is translated to the host's address, just as IPv4 traffic is.

Checking IPv6 Support (Optional)

You do not need to run a check before you install or start Sandfly, because the install and start scripts check the requirements on this page automatically. To see the result in advance, or to find out why IPv6 was not enabled, you can run the check script. Run it as the same user that runs the Sandfly scripts, because the results for rootless Docker and Podman depend on the user:

cd ~/sandfly-setup/setup/util_scripts
./check_ipv6_support.sh

The script reports each host and container runtime setting as PASS, WARN, or FAIL, shows whether an existing sandfly-net network has IPv6, and ends with RESULT: IPv6 is SUPPORTED on this system or RESULT: IPv6 is NOT SUPPORTED on this system. A WARN does not stop Sandfly from enabling IPv6, but it can stop IPv6 from working, for example when the host has no IPv6 default route. The script checks Podman if it is installed, and Docker otherwise; to check a specific one, run it as CONTAINERMGR=docker ./check_ipv6_support.sh or CONTAINERMGR=podman ./check_ipv6_support.sh. The script only reads settings; it changes nothing on the host.

Host Requirements

These requirements apply to every container runtime. The host must have IPv6 enabled in the kernel and must not have it turned off by sysctl settings:

The host also needs a working IPv6 route to the hosts that Sandfly will scan.

Docker Requirements

Docker 27 or later supports IPv6 with no extra configuration. Docker 20.10 through 26 can support IPv6 but IPv6 specific firewall rules must be turned on in the Docker daemon configuration.

The daemon configuration file is /etc/docker/daemon.json. Rootless Docker uses ~/.config/docker/daemon.json. For Docker 20.10 to 26, it must contain at least:

{
  "experimental": true,
  "ip6tables": true
}

After editing the file, restart Docker with sudo systemctl restart docker, or systemctl --user restart docker for rootless Docker. Without ip6tables, containers get an IPv6 address but cannot reach anything over IPv6, so the installation and start scripts will not enable IPv6 without those settings.

Docker Compose Requirements

The Docker version requirements above are the same for Compose deployments, but generate_compose.sh checks only the host requirements. On Docker 20.10 to 26, configure the daemon as described in the Docker section before running docker compose up.

When the host supports IPv6, all three generated files (docker-compose.yaml, docker-compose-server_only.yaml and docker-compose-node_only.yaml) define the network as follows:

networks:
  sandfly-net:
    enable_ipv6: true
    ipam:
      config:
        - subnet: fd5f:a11d:f1ff::/64
          gateway: fd5f:a11d:f1ff::1

When the host does not support IPv6, the files contain enable_ipv6: false and no ipam section.

Running nodes on another host. The IPv6 setting in docker-compose-node_only.yaml reflects the host where you ran generate_compose.sh, not the host where the node will run. If the node's host does not meet the requirements on this page, set enable_ipv6: false and delete the ipam section before running docker compose up. Otherwise Docker cannot create the network and the node will not start.

Subnet conflicts. Compose always uses fd5f:a11d:f1ff::/64. Docker will not create two networks with the same subnet. If a network from a script-based install is already using it on the same host, remove that network first, or change the subnet in the Compose file to another fd00::/8 range.

Podman Requirements

IPv6 is only supported with Podman 5 or later. Rootless Podman must also use pasta as its network command.

In all supported cases, Podman picks the IPv6 subnet for sandfly-net from a private fd00::/8 range.