Docker & IP_Tables - Modules as Dependancies for Why...

The Problem

For the last two days, I have been reconfiguring my personal network infrastructure to create a complete, secure, and coherent solution for my needs. For context, this server is running systemd Gentoo Linux with +march=native and standard stable compile flags, testing packages are not allowed globally, the kernel is manually configured, it was compiled and installed 12/31. Special care was used to ensure I selected compatible kernel options matching the Gentoo Wiki's article on Docker.

This issue took longer than I care to admit because of a couple now glaringly obvious red herrings. I was able to emerge and install Docker without a problem, but when I attempted to run the service I received the following error:

Dec 31 10:34:56 gentoo systemd[1]: Starting Docker Application Container Engine...
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.093036541Z" level=info msg="Starting up"
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.280360174Z" level=info msg="[graphdriver] using prior storage driver: overlay2"
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.280599062Z" level=info msg="Loading containers: start."
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.282787923Z" level=warning msg="Running modprobe bridge br_netfilter failed with message: modprobe: WARNING: Module bridge not f>
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.287999183Z" level=info msg="unable to detect if iptables supports xlock: 'iptables --wait -L -n': `modprobe: FATAL: Module ip_t>
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.340305545Z" level=info msg="stopping event stream following graceful shutdown" error="<nil>" module=libcontainerd namespace=moby
Dec 31 10:34:56 gentoo dockerd[134836]: failed to start daemon: Error initializing network controller: error obtaining controller instance: failed to register "bridge" driver: failed to create >
Dec 31 10:34:56 gentoo dockerd[134836]: iptables v1.8.11 (legacy): can't initialize iptables table `nat': Table does not exist (do you need to insmod?)
Dec 31 10:34:56 gentoo dockerd[134836]: Perhaps iptables or your kernel needs to be upgraded.
Dec 31 10:34:56 gentoo dockerd[134836]:  (exit status 3)
Dec 31 10:34:56 gentoo dockerd[134836]: time="2024-12-31T10:34:56.340724371Z" level=info msg="stopping event stream following graceful shutdown" error="context canceled" module=libcontainerd na>
Dec 31 10:34:56 gentoo systemd[1]: docker.service: Main process exited, code=exited, status=1/FAILURE
Dec 31 10:34:56 gentoo systemd[1]: docker.service: Failed with result 'exit-code'.

This is where I went naive, the error there clearly indicates iptables is not working properly and the docker service can't properly register it's network configuration causing it to fail. Working through that error log from the bottom up, reviewed all the wiki entries on iptables & ip_tables, I emerged iptables again and once it was finished I attempted to run "iptables -L" which met me with another error shown below. One thing I learned through this is that ip_tables, and iptables, are two related but different things (ip_tables is a kernel module and iptables is a front-end for the module).

In hindsight the fix here is glaringly obvious but I was convinced there was no issue with my configuration since I had closely followed the Docker Gentoo Wiki kernel configuration notes. With reluctance I reviewed my kernel configuration and it matched the documentation shown below like I thought.

At this point I made the choice to leave the kernel configuration as it was in regards to IP tables support, since it was clearly compiled in. I began troubleshooting the next error up thinking perhaps that was the cause but after another rabbit hole, it was a module issue and the modules in question were compiled into the kernel.

time="2024-12-31T10:34:56.282787923Z" level=warning msg="Running modprobe bridge br_netfilter failed with message: modprobe: WARNING: Module bridge not found

To some people and myself with hindsight, the issue here is probably immediately noticeable.

The Solution

As best as I can tell, the Wiki article for the kernel configuration is incorrect. This issue may be self-imposed as far as I know or have a better solution which is why I am not daring to modify the Gentoo Wiki and why I'm writing here instead.

For me the proper kernel configuration was something like the following:

[*] Networking support  ---> 
   Networking options  --->
      [*] Network packet filtering framework (Netfilter)  ---> 
           [*] Advanced netfilter configuration 
           [M]   Bridged IP/ARP packets filtering 
              Core Netfilter Configuration  --->
                 [*] Netfilter connection tracking support 
                 [*] Network Address Translation support 
                 [*] MASQUERADE target support 
                 [*] Netfilter Xtables support 
                 [*]    "addrtype" address type match support 
                 [*]    "conntrack" connection tracking match support 
                 [*]    "ipvs" match support (Optional) 
                 [*]    "mark" match support 
           [*] IP virtual server support  ---> (Optional) 
              [*] TCP load balancing support (Optional) 
              [*] UDP load balancing support (Optional) 
              [*] round-robin scheduling (Optional) 
              [*] Netfilter connection tracking (Optional) 
           IP: Netfilter Configuration  --->
              [M] IP tables support 
              [M]    Packet filtering 
              [M]    iptables NAT support 
              [M]      MASQUERADE target support 
              [M]      REDIRECT target support (Optional) 

Simply put, if the error says "unable to load module" it's best to make sure whatever is trying to load a module has a module to load instead of expecting it to be able to handle a compiled-in module.

Hopefully this can help save someone else some time. When I was doing some searches online for the errors I was seeing, I did not get many (any) recent results, nothing with good formatting, and no one who clearly explained how they resolved the issue after experiencing it. Odds are, if I did a web search for it, someone else will too.

;)