skip to content

On docker network create, what do the --ip-range and --aux-address flags do beyond --subnet?

level: middleimportance: nice to knowfreq 20%

answer

  1. Two of the flags reserve, one declares
  2. The network still owns the whole block
  3. Automatic allocation versus manual assignment
  4. Something else on the wire already has that address
  5. Fixed at creation time, never edited later

basics

~20 s

In docker network create, --subnet declares the whole address block, --ip-range narrows the slice Docker's IPAM may hand out automatically, leaving the remainder free for manual assignment, and --aux-address reserves individual addresses inside the subnet that Docker must never allocate.

solid answer

~40 s

`--subnet` is the network's full CIDR and also what the addresses are validated against; `--gateway` picks which address inside it the bridge interface takes, defaulting to the first usable one. `--ip-range` must be a subset of the subnet and restricts **automatic** allocation to that slice, so the addresses outside it stay free for containers you start with an explicit `docker run --ip`. `--aux-address` takes `name=address` pairs and marks single addresses as already spoken for, so IPAM steps over them — the classic use is a network sharing a physical LAN where a router, a NAS or a printer already owns those addresses. All three are recorded under `IPAM.Config` and are visible in `docker network inspect`.

code

bash · 10 lines
bash
docker network create \
  --driver bridge \
  --subnet 10.42.7.0/24 \
  --gateway 10.42.7.1 \
  --ip-range 10.42.7.128/25 \
  --aux-address "nas=10.42.7.20" \
  --aux-address "printer=10.42.7.21" \
  checkout-net

docker network inspect checkout-net -f '{{json .IPAM.Config}}'

go deeper

for a junior

Know that docker network create --subnet lets you choose the addresses a network uses instead of accepting whatever Docker picks, and that docker network inspect shows you what a network actually got.

for a middle

Be able to separate the three roles cleanly: the subnet is the whole block, the gateway is one address inside it, and the range bounds only what the allocator hands out automatically while the rest stays available for explicit assignment.

for a senior

Explain when reservations are actually necessary — a Docker network sharing address space with real devices — and describe the duplicate-address symptom you get when the allocator is not told about them.

for a principal

Frame it as a policy question: addressing that must be predictable belongs in the definition that creates the network, because IPAM settings are immutable and fixing them later means tearing the network down.

### The four flags together `docker network create` accepts a small IPAM vocabulary that is easy to confuse because three of the flags all take addresses inside the same block: ``` docker network create \ --driver bridge \ --subnet 10.42.7.0/24 \ --gateway 10.42.7.1 \ --ip-range 10.42.7.128/25 \ --aux-address "nas=10.42.7.20" \ --aux-address "printer=10.42.7.21" \ checkout-net ``` **`--subnet`** declares the address space the network owns. Supplying it turns off the automatic pool search entirely for this network: you have said which block to use, and the daemon only checks that it does not overlap an existing Docker network. It is also the validation boundary — every other address you pass must fall inside it. **`--gateway`** chooses the address the network's gateway takes. On a bridge network that is the address put on the host-side bridge interface, and it is what containers on the network get as their default route. Omit it and the first usable address in the subnet is used, so 10.42.7.0/24 yields 10.42.7.1. You would set it explicitly when the subnet is shared with hardware that already expects the router to live somewhere specific. **`--ip-range`** is the one people misread. It does **not** shrink the network. The network still owns the whole `--subnet`, routes are still written for the whole subnet, and an address outside the range is still a valid, reachable address on this network. What the range limits is *automatic* allocation: containers that do not ask for a particular address are only handed addresses from inside it. Everything outside the range becomes a reservation you manage yourself, typically with `docker run --ip 10.42.7.9 --network checkout-net …`. It is the clean way to split one subnet into "Docker's to give away" and "mine to assign". The range must be a subset of the subnet; give it a block that does not fit and the daemon rejects the creation. **`--aux-address`** reserves individual addresses rather than a slice. Each value is a `name=address` pair, where the name is only a label for humans — nothing resolves it, and it is not a DNS entry. The address is recorded in the network's IPAM configuration as auxiliary, and the allocator simply skips it. You can pass the flag more than once. ### Where the reservations actually matter On an ordinary user-defined bridge, the whole subnet is private to the host and there is nothing else in it to collide with, so `--aux-address` rarely earns its keep. It matters when the Docker network overlaps address space that other things already live in — a network attached to a physical LAN segment where a gateway appliance holds 10.42.7.1, a storage box holds 10.42.7.20 and a couple of printers hold the addresses after it. Without the reservations, Docker's allocator has no idea those devices exist: it will eventually hand 10.42.7.20 to a container, and you get a duplicate-address conflict that shows up as intermittent, one-sided connectivity, which is a miserable thing to debug from inside a container. `--ip-range` earns its keep for a different reason: predictability. If a handful of components must sit at addresses that are written down somewhere — a legacy client with a hardcoded target, a firewall rule keyed on an address — you carve those out of automatic allocation once, at network creation, instead of hoping the allocator never reaches them. ### Reading it back Everything lands in `IPAM.Config`: ``` docker network inspect checkout-net -f '{{json .IPAM.Config}}' ``` which returns the subnet, the gateway, the range and an `AuxiliaryAddresses` map. That output is the fastest way to answer "why did this container get that address" — if the address is outside the configured range, it was assigned explicitly, not allocated. ### The limits worth stating None of this is dynamic. IPAM settings are fixed at network creation: there is no command that edits the subnet, range or auxiliary addresses of an existing Docker network, so changing them means removing the network and creating it again, which requires disconnecting everything attached to it. That immutability is the reason it is worth getting the numbers right the first time, and the reason teams that need particular addressing declare it in the file that creates the network rather than fixing it by hand afterwards.

  • If a container is given an address outside --ip-range, is it still reachable on that network?
    Yes. The network owns the entire `--subnet`; the range only bounds what the allocator gives out on its own. An address outside the range but inside the subnet is a perfectly normal address on the network — that is exactly the point of carving the range out, so those addresses stay available for containers started with an explicit `docker run --ip`.
  • Can you change the subnet or the auxiliary addresses of a network after it exists?
    No. IPAM settings are set at creation and there is no command to edit them. Changing addressing means disconnecting everything attached, removing the network and creating it again with the new values. That is why the addressing belongs in whatever file or script creates the network, not in a one-off command someone typed once.
  • What does the name part of --aux-address do?
    Nothing functional — it is a label stored alongside the reserved address in the network's IPAM configuration and shown by `docker network inspect`. It does not create a DNS record and nothing inside a container can resolve it. Its only job is to remind the next person why that address is off-limits, so use names that identify the real device holding it.

saying these in an interview costs you the question

  • Thinks --ip-range shrinks the network's subnet
  • Believes --aux-address creates a resolvable name
  • Expects addresses outside the range to be unreachable
  • Assumes the subnet can be edited after creation
  • Passes an --ip-range that is not inside the subnet

context

resolving links…