moby/moby

Networking (libnetwork)

Purpose

daemon/libnetwork/ is the daemon's networking subsystem. It implements the Container Network Model (CNM): a small set of objects (NetworkController, Network, Endpoint, Sandbox) that drivers plug into. The same controller serves single-host bridge networking and multi-host overlay networking on swarm clusters.

libnetwork used to be a separate repository (github.com/docker/libnetwork); it lives in-tree now under daemon/libnetwork/.

CNM in one diagram

graph LR
  subgraph Container["Container 1"]
    SB1[Sandbox]
  end
  subgraph Container2["Container 2"]
    SB2[Sandbox]
  end
  subgraph Network1["Network: my-net"]
    EP1[Endpoint]
    EP2[Endpoint]
  end
  SB1 --- EP1
  SB2 --- EP2
  EP1 --> Driver1[bridge driver]
  EP2 --> Driver1

A Sandbox is a container's network namespace + DNS + routing config. An Endpoint is the wiring (e.g. a veth pair) between a sandbox and a network. A Network is owned by a driver. The full design is documented in daemon/libnetwork/docs/design.md.

Controller

Controller (daemon/libnetwork/controller.go, ~34K LOC) is the entry point. It registers drivers, persists state, runs the agent (for swarm-attached overlays), exposes the DNS resolver, and tracks sandboxes. The daemon creates exactly one Controller at startup.

Important state:

Driver registry (drvregistry/) holding network and IPAM drivers.
Datastore (datastore/) — a key/value abstraction over an in-process bbolt DB.
Network DB (networkdb/) — a gossiping eventually-consistent KV store used by overlay networks across a swarm. Built on hashicorp/memberlist.

Drivers

Built-in network drivers under drivers/:

Driver	Code	What it does
bridge	`drivers/bridge/`	Default Linux bridge networking. Uses Linux bridges + iptables/nftables.
host	`drivers/host/`	Reuse host network namespace.
null	`drivers/null/`	No networking.
overlay	`drivers/overlay/`	VXLAN overlay, used by swarm.
macvlan	`drivers/macvlan/`	Direct MAC-VLAN attachments.
ipvlan	`drivers/ipvlan/`	IP-VLAN L2/L3 attachments.
windows	`drivers/windows/`	HCS-backed Windows networking (nat, l2bridge, transparent, ...).
remote	`drivers/remote/`	Plugin RPC bridge — talks to v1 network plugins over a Unix socket.

IPAM drivers live under ipams/ (default, null, windowsipam, remote). Port mapping is platform-specific via portmappers/.

Bridge driver internals

The bridge driver is the most-touched code in libnetwork. drivers/bridge/bridge_linux.go (~1900 LOC) handles:

Allocating and configuring the Linux bridge (docker0 by default).
iptables (or nftables via internal/nftabler/) rules for masquerading, isolation, port forwarding.
Userland proxy spawn (docker-proxy) for port publishing — see docker-proxy.
Hairpin NAT for container-to-self via published port.

Firewall backend selection happens in firewall_linux.go and internal/nftabler/.

Sandbox lifecycle

Container start
  -> NewSandbox(containerID, options)
  -> for each network: CreateEndpoint + Endpoint.Join(sandbox)
  -> Sandbox writes /etc/{hosts,hostname,resolv.conf} via [resolvconf/](../../daemon/libnetwork/resolvconf), [etchosts/](../../daemon/libnetwork/etchosts)
  -> Daemon tells containerd to use the sandbox's network namespace path
Container stop
  -> Endpoint.Leave -> Endpoint.Delete
  -> Sandbox.Delete -> namespace torn down

The Linux sandbox is implemented in sandbox_linux.go and osl/ (operating-system layer). The Windows sandbox is in sandbox_windows.go.

Embedded DNS

resolver.go is libnetwork's embedded DNS server. Each sandbox gets its own resolver instance bound to a loopback IP inside the container. It answers names of containers and services attached to the same user-defined networks and forwards everything else upstream.

NetworkDB and overlay

When a node joins a swarm, libnetwork starts a networkdb instance (networkdb/networkdb.go) that gossips per-network membership and service records via hashicorp/memberlist. The overlay driver consumes these updates to program VXLAN tunnels and service VIPs.

Diagnostics

diagnostic/ exposes an HTTP server (separate from the Engine API) for troubleshooting networkdb, iptables rules, and sandbox state. Disabled by default; turned on with --diagnostic-addr.

Tests

Unit tests live next to source files.
A large integration suite is in integration/networking/ and integration/network/.

Entry points for modification

New driver: implement driverapi.Driver, register via the controller, place under drivers/<name>/.
New IPAM allocator: implement ipamapi.Ipam and register similarly.
Firewall changes: see firewall_linux.go and iptables/.
Embedded DNS changes: resolver.go.