From 92692eb0af6f59f4f185df79af49ef7731b411ad Mon Sep 17 00:00:00 2001 From: Jack O'Sullivan Date: Thu, 10 Jun 2021 21:59:21 +0100 Subject: [PATCH] Update README --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 57 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 0453bfc..a178552 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,62 @@ # docker-net-dhcp + `docker-net-dhcp` is a Docker plugin providing a network driver which allocates IP addresses (IPv4 and optionally IPv6) via an existing DHCP server (e.g. your router). When configured correctly, this allows you to spin up a container (e.g. `docker run ...` or `docker-compose up ...`) and -access it on your network as if it was any other machine! +access it on your network as if it was any other machine! _Probably_ not a great idea for production, but it's pretty +handy for home deployment. # Usage + ## Installation + +The plugin can be installed with the `docker plugin install` command: + ``` -$ docker plugin install devplayer0/net-dhcp -Plugin "devplayer0/net-dhcp" is requesting the following privileges: +$ docker plugin install ghcr.io/devplayer0/docker-net-dhcp:release-linux-amd64 +Plugin "ghcr.io/devplayer0/docker-net-dhcp:release-linux-amd64" is requesting the following privileges: - network: [host] - - host pid namespace: [true] - mount: [/var/run/docker.sock] + - mount: [/var/run/docker] - capabilities: [CAP_NET_ADMIN CAP_SYS_ADMIN] Do you grant the above permissions? [y/N] y -latest: Pulling from devplayer0/net-dhcp -: Download complete +release-linux-amd64: Pulling from ghcr.io/devplayer0/docker-net-dhcp Digest: sha256: -Status: Downloaded newer image for devplayer0/net-dhcp:latest -Installed plugin devplayer0/net-dhcp +: Complete +Installed plugin ghcr.io/devplayer0/docker-net-dhcp:release-linux-amd64 $ ``` +## Other tags + +There are a number of supported tags for different architectures and versions, the format is +`--`. For example, `latest-linux-arm-v7` would install the newest build for ARMv7 (e.g. for +Raspberry Pi). + +### Version + +- `release`: The latest release (can be upgraded via `docker plugin upgrade`) +- `x.y.z`: A specific ([semver](https://semver.org/)) release (e.g. `0.1.0`) +- `latest`: Build of the newest commit + +### OS + +Currently only `linux` is supported. + +### Architecture + +- `amd64`: Intel / AMD 64-bit +- `386`: Intel / AMD legacy 32-bit +- `arm64-v8`: ARMv8 64-bit +- `arm-v7`: ARMv7 (e.g. Raspberry Pi) + +Unfortunately Docker plugin images don't support multiple architectures per tag. + ## Network creation In order to create a Docker network using `net-dhcp`, you'll need a pre-configured bridge interface on the host. How you set this up will depend on your system, but the following (manual) instructions should work on most Linux distros: + ``` # Create the bridge $ sudo ip link add my-bridge type bridge @@ -37,26 +68,31 @@ $ sudo ip link set eth0 up $ sudo ip link set eth0 master my-bridge # Get an IP for the host (will go out to the DHCP server since eth0 is attached to the bridge) +# Replace this step with whatever network configuration you were using for eth0 $ sudo dhcpcd my-bridge ``` Once the bridge is ready, you can create the network: + ``` -$ docker network create -d devplayer0/net-dhcp:latest --ipam-driver null -o bridge=my-bridge my-dhcp-net +$ docker network create -d ghcr.io/devplayer0/docker-net-dhcp:release-linux-amd64 --ipam-driver null -o bridge=my-bridge my-dhcp-net $ # With IPv6 enabled # Although `docker network create` has a `--ipv6` flag, it doesn't work with the null IPAM driver -$ docker network create -d devplayer0/net-dhcp:latest --ipam-driver null -o bridge=test -o ipv6=true my-dhcp-net +$ docker network create -d ghcr.io/devplayer0/docker-net-dhcp:release-linux-amd64 --ipam-driver null -o bridge=test -o ipv6=true my-dhcp-net $ ``` + _Note: The `null` IPAM driver **must** be used, or else Docker will try to allocate IP addresses from its choice of subnet - this can cause IP conflicts since the bridge is connected to your local network!_ ## Container creation -Once you've created a network, you can create some containers: + +Once you've set up a network, you can create some containers: + ``` $ docker run --rm -ti --network my-dhcp-net alpine / # ip address show @@ -69,28 +105,31 @@ $ docker run --rm -ti --network my-dhcp-net alpine inet 10.255.0.246/24 brd 10.255.0.255 scope global test0 valid_lft forever preferred_lft forever / # ip route show -default via 10.255.0.123 dev my-bridge0 -10.255.0.0/24 dev my-bridge0 scope link src 10.255.0.246 +default via 10.255.0.123 dev my-bridge0 +10.255.0.0/24 dev my-bridge0 scope link src 10.255.0.246 / # ``` + Note: - It will take a bit longer than usual for the container to start, as a DHCP lease needs to be obtained before creating it - Once created, a persistent DHCP client will renew the DHCP lease (and then update the default gateway in the - container) when necessary - **this client runs separately from the container** + container) when necessary - **this client runs separately from the container** - Use `--mac-address` to specify a MAC address if you've configured reserved IP addresses on your DHCP server, or if - you want a container to re-use an old lease + you want a container to re-use an old lease # Implementation + Fundamentally, the same mechanism is used by `net-dhcp` as Docker's `bridge` driver to wire up networking to containers. That is, a bridge on the host is used as a switch so that containers can communicate with each other - `veth` pairs connect each container's network namespace to the bridge. - While Docker creates and manages its own bridges (and routes and filters traffic), `net-dhcp` uses an existing bridge -on the host, bridged with the desired local network. + on the host, bridged with the desired local network. - Instead of allocating IP addresses from a static pool stored on the Docker host, `net-dhcp` relies on an external DHCP -server to provide IP addresses + server to provide IP addresses ## Flow + 1. Container creation request is made 2. A `veth` pair is created and the host end is connected to the bridge (at this point both interfaces are still in the host namespace) @@ -99,5 +138,5 @@ is provided to Docker by the plugin 4. Docker moves the container end of the `veth` pair into the container's network namespace and sets the IP address - at this point `udhcpc` must be stopped 5. `net-dhcp` starts `udhcpc` on the container end of the `veth` pair in the container's **network namespace** (but -still in the host / plugin **PID namespace** - this means that the container can't see the DHCP client) +still in the plugin **PID namespace** - this means that the container can't see the DHCP client) 6. `udhcpc` continues to run, renewing the lease when required, until the container shuts down