Archives/docker-net-dhcp
2
0
Fork 0
mirror of https://github.com/devplayer0/docker-net-dhcp synced 2024-10-30 09:20:28 +00:00
Code Issues Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Jack O'Sullivan 2021-06-10 21:59:21 +01:00
parent e3b1529aca
commit 92692eb0af
1 changed files with 57 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -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
<some id>: Download complete
release-linux-amd64: Pulling from ghcr.io/devplayer0/docker-net-dhcp
Digest: sha256:<some hash>
Status: Downloaded newer image for devplayer0/net-dhcp:latest
Installed plugin devplayer0/net-dhcp
<some id>: 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
`<version>-<os>-<architecture>`. 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
<some network id>
$
# 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
<some network id>
$
```
_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