Skip to content
Tutorials Center
My learning

Topics

Lesson 54 of 111 ยท Networking

Host, None, Macvlan and Overlay

Understand every Docker network driver: bridge, host, none, macvlan, ipvlan and overlay. See when each one fits, the host networking caveats, and what overlay needs Swarm for.

So far you have used the bridge driver, which fits almost everything. Docker ships a handful of other network drivers for special cases: sharing the host's network directly, having no network at all, giving containers their own address on your LAN, or connecting containers across several machines. You rarely need them on day one, but you should know what each one does, because the wrong choice can quietly break port publishing or open your containers to the world.

This lesson tours the drivers, runs the ones a single laptop can run, and labels the rest as read-only examples. Outputs were captured on Docker Desktop for Windows (Linux containers), and the differences from a native Linux host are called out.

The drivers at a glance

CONSOLE
$ docker network ls --format 'table {{.Name}}\t{{.Driver}}\t{{.Scope}}' --filter name=bridge --filter name=host --filter name=none
NAME      DRIVER    SCOPE
bridge    bridge    local
host      host      local
none      null      local

Every Docker installation has these three built-in networks. The driver column tells you the mechanism:

Driver What it does Typical use
bridge Private virtual switch on one host, with NAT to the outside Default; most apps and Compose projects
host Container shares the host's network stack, no isolation Performance-sensitive or port-heavy tools
none Only a loopback interface Offline batch jobs, maximum isolation
macvlan Container gets its own MAC and a real LAN address Legacy apps that must look like physical hosts
ipvlan Like macvlan, but shares the parent's MAC Same, when switches limit MAC addresses
overlay Virtual network spanning several Docker hosts Swarm clusters

The scope column says where the network exists: local means one host, swarm means a cluster. You choose a driver with docker network create -d <driver> or the --network <name> flag on docker run.

The host driver

With --network host the container does not get its own network namespace. It uses the host's interfaces, addresses and ports directly. A server listening on port 8080 inside the container is listening on port 8080 of the host. There is no NAT and no -p needed.

Run a small web server that way and reach it from another host-network container:

CONSOLE
$ docker run -d --name hostweb --network host python:3-alpine python -m http.server 18081 --bind 127.0.0.1
$ docker run --rm --network host alpine:3 wget -qO- http://127.0.0.1:18081 | head -3
<!DOCTYPE HTML>
<html lang="en">
<head>

Both containers share one network stack, so they see each other on 127.0.0.1. A normal bridge container does not:

CONSOLE
$ docker run --rm alpine:3 wget -T2 -qO- http://127.0.0.1:18081
wget: can't connect to remote host (127.0.0.1): Connection refused

Inside a bridge container, 127.0.0.1 is the container's own loopback, not the host's. This is the source of a classic beginner bug: "my app cannot reach the service on localhost". With host mode the answer changes; with bridge you need the host's address or host.docker.internal.

Caveats of host networking

  1. Published ports are ignored. Docker warns you:

    CONSOLE
    $ docker run --rm --network host -p 127.0.0.1:18082:80 alpine:3 true
    WARNING: Published ports are discarded when using host network mode
    
  2. No isolation. The container can bind any port, see all interfaces, and reach services bound to the host's loopback. A compromised container has much more to attack.

  3. Port collisions. Two containers that both listen on port 80 cannot both run in host mode.

  4. No name resolution between containers. There are no user-defined networks and no embedded DNS. You use localhost or real addresses.

  5. Docker Desktop is different. On Docker Desktop, containers run inside a small Linux VM, so host means that VM, not your Windows or macOS machine. In the example above, curl http://127.0.0.1:18081 run on the Windows host got no answer at all, because the server lives in the VM's network. Recent Docker Desktop versions offer an opt-in host-networking feature in settings that bridges this, but do not count on it in a tutorial or a team setup.

  6. Linux only, in the classic sense. On a native Linux server it behaves as described, which is where it is mostly used.

Host mode removes one of the main safety nets of containers. Use it only when you have measured a need (very high packet rates, a tool that must see the host's interfaces such as a network monitor, or an application that opens thousands of ports) and you trust the image.

The none driver

--network none gives the container a loopback interface and nothing else:

CONSOLE
$ docker run --rm --network none alpine:3 ip -o addr
1: lo    inet 127.0.0.1/8 scope host lo\       valid_lft forever preferred_lft forever
1: lo    inet6 ::1/128 scope host \       valid_lft forever preferred_lft forever
$ docker run --rm --network none alpine:3 ping -c1 -W1 8.8.8.8
PING 8.8.8.8 (8.8.8.8): 56 data bytes
ping: sendto: Network unreachable

No eth0, no route out, no way in. Use it for jobs that process local files and must never touch the network (a document converter, a data scrubber, a build step you want to prove is hermetic). It is also the base for hand-wiring: tools like CNI plugins start containers with none and attach interfaces afterward.

You can see the mode Docker recorded:

CONSOLE
$ docker inspect offline --format '{{.HostConfig.NetworkMode}} {{len .NetworkSettings.Networks}}'
none 1

For a default container the same field reads bridge.

Sharing another container's network

There is one more mode, --network container:<name>, that is not a driver but is very useful. The new container joins the network namespace of an existing one, so both see the same interfaces and IP:

CONSOLE
$ docker run -d --name app alpine:3 sleep 120
$ docker run --rm --network container:app alpine:3 ip -o -4 addr show eth0 | awk '{print $2,$4}'
eth0 172.17.0.7/16
$ docker exec app ip -o -4 addr show eth0 | awk '{print $2,$4}'
eth0 172.17.0.7/16

Same address, same ports. This is how you attach a debugging toolbox (tcpdump, curl, dig) to a container that does not contain those tools, without changing its image. Kubernetes pods are built on the same idea: containers in a pod share one network namespace. See Troubleshooting Networks for hands-on use.

The macvlan driver

A macvlan network makes each container appear as a separate physical device on your LAN, with its own MAC address and an IP from your real subnet. Other machines on the LAN can reach the container directly, with no port publishing.

Terminal
# read-only example: needs a real Ethernet interface and a router you control
docker network create -d macvlan \
  --subnet 192.168.1.0/24 \
  --gateway 192.168.1.1 \
  -o parent=eth0 \
  lan-net

docker run -d --name cam-gateway --network lan-net --ip 192.168.1.50 my-legacy-app

Facts that surprise people:

  • It needs a parent interface. In our test, docker network create -d macvlan name succeeded without any warning and without recording a parent (docker network inspect showed empty options), so Docker will not tell you that you forgot it. Always set -o parent=... explicitly, and remember that on Docker Desktop the interface lives inside the VM, not on your real LAN.
  • The host cannot talk to its own macvlan containers over the parent interface (a kernel rule). You need a separate macvlan sub-interface on the host as a workaround.
  • Many switches and cloud networks limit the number of MAC addresses per port and drop traffic from unknown ones. Wi-Fi adapters usually refuse it altogether.
  • You must manage the addresses yourself: reserve a range with --ip-range so Docker does not collide with your DHCP server.

The ipvlan driver is the sibling for networks where extra MAC addresses are a problem: containers share the parent's MAC but get their own IPs.

Use macvlan only when software truly insists on a LAN identity (some discovery protocols, old network appliances, systems that whitelist IPs). For ordinary services, a bridge plus published ports is simpler and safer.

The overlay driver

An overlay network connects containers on different Docker hosts as if they shared one bridge. Traffic between hosts travels inside VXLAN tunnels, and DNS by container or service name works across the cluster. Overlay is the networking layer of Docker Swarm.

A single, ordinary Docker engine cannot create one:

CONSOLE
$ docker network create -d overlay demo
Error response from daemon: This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again.

On a Swarm manager, the commands look like this (read-only example, no cluster is available here):

Terminal
docker network create -d overlay --attachable backend
docker service create --name api --network backend --replicas 3 my-api:1.0

--attachable lets stand-alone docker run containers join the overlay too, which helps with debugging. Overlay networks can encrypt traffic with -o encrypted, at a CPU cost. You will meet them again in Docker Swarm Basics. If you run Kubernetes instead, its own network plugins (CNI) replace overlay entirely.

How a container is wired to the bridge: veth pairs

A bridge network is a virtual switch inside the host's kernel. To plug a container into it, Docker creates a veth pair: two virtual network interfaces joined like the two ends of a cable. One end is moved into the container's network namespace and renamed eth0; the other end stays in the host namespace and is attached to the bridge. Whatever enters one end leaves the other, so the container's eth0 is effectively a port on the switch.

You can see the pairing from inside any container. The @if194 in the name is the interface index of the peer on the other side, and iflink holds the same number:

CONSOLE
$ docker run --rm alpine:3 sh -c 'ip -o link show eth0; cat /sys/class/net/eth0/iflink'
2: eth0@if194: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP    link/ether 46:7c:56:06:bf:d5 brd ff:ff:ff:ff:ff:ff
194

Your numbers and MAC address will differ. On a Linux host, ip link shows the other half as an interface named veth followed by random characters, with master docker0 (or master br-<id> for a user-defined bridge) and the index from iflink. On Docker Desktop the host side lives inside the hidden VM, so you do not see it from Windows or macOS. Two consequences: every running container on a bridge adds one veth device to the host, and traffic between two containers on the same bridge never leaves the machine, because the kernel switches it.

Choosing a driver

TEXT
Need containers to talk by name on one machine?      -> user-defined bridge (default choice)
Need no network at all?                              -> none
Need to inspect or debug another container's net?    -> --network container:<name>
Need extreme throughput on a native Linux server?    -> host (accept the loss of isolation)
Need containers to have LAN addresses?               -> macvlan / ipvlan
Need containers on several hosts to talk by name?    -> overlay (Swarm)

When unsure, stay on a user-defined bridge. Every other choice trades away isolation or portability.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A container started with --network host and -p 8080:80 is running. What happens to the -p option?

    In host mode the container already uses the host's ports directly, so Docker prints 'Published ports are discarded when using host network mode' and carries on.
  2. 2. Which network option is the best fit for a batch job that must never use the network?

    With none the container has only a loopback interface, so any attempt to reach the outside fails with 'Network unreachable'.
  3. 3. Why does 127.0.0.1 not reach a service running on your machine from inside an ordinary bridge container?

    Each container has its own network namespace, so its loopback is private. Only --network host (or a shared namespace) makes 127.0.0.1 mean the host.
  4. 4. What is the main limitation of the overlay driver on a single Docker engine?

    Overlay networks span several hosts and rely on Swarm's key-value store and control plane. A stand-alone engine answers 'This node is not a swarm manager'.
  5. 5. What does --network container:app do?

    Both containers then see exactly the same interfaces and IP address, which is ideal for attaching debugging tools to a minimal image.

Summary

  • Docker's built-in networks are bridge, host and none; user-defined networks add macvlan, ipvlan and (with Swarm) overlay.
  • host shares the host's network stack: no NAT, no isolation, -p ignored, port collisions possible, and on Docker Desktop it means the VM.
  • none leaves only loopback, ideal for offline jobs.
  • --network container:<name> shares another container's namespace, perfect for debugging.
  • macvlan gives containers LAN addresses but needs a parent interface, careful addressing and a cooperative switch.
  • overlay connects containers across hosts and needs Swarm.
  • Default to a user-defined bridge unless you have a clear reason not to.

Next: Containers Talking to Each Other