CIDR Notation

CIDR (Classless Inter-Domain Routing) notation is the standard way to describe a range of IP addresses. You supply a CIDR block when creating a private network so hzel knows which IP addresses to allocate to your containers.

Reading a CIDR block

A CIDR block looks like this:

10.42.0.0/24

It has two parts separated by a /:

• Network address (10.42.0.0) — the starting IP of the range. All addresses in the block share the same prefix up to the /.
• Prefix length (24) — the number of bits that are fixed. The remaining bits identify individual hosts within the block.

An IPv4 address is 32 bits long. With a /24 prefix, 24 bits are fixed (the network part) and 8 bits are free (the host part). That gives 2⁸ = 256 total addresses in the block.

Network and broadcast addresses

Two addresses in every block are reserved and cannot be assigned to a host:

• Network address — the first address in the block (all host bits zero). Identifies the network itself.
• Broadcast address — the last address in the block (all host bits one). Used to address all hosts on the network simultaneously.

For 10.42.0.0/24 that leaves 254 usable host addresses: 10.42.0.1 through 10.42.0.254.

The general formula: usable hosts = 2^(32 − prefix) − 2.

Calculating the host range

Given a CIDR block, the host range is straightforward:

The prefix length and the number of available addresses move in opposite directions — a smaller prefix means more hosts, a larger prefix means fewer.

RFC 1918 private address space

Private networks on hzel must use one of the three address ranges reserved for private use by RFC 1918. These ranges are not routed on the public internet, which keeps overlay traffic isolated from external networks.

Any CIDR block you supply to hzel must fall entirely within one of these ranges. For example, 10.42.0.0/24 is valid; 203.0.113.0/24 is not.

hzel constraints

hzel accepts CIDR blocks with a prefix length between /16 and /28:

Blocks outside these bounds are rejected at the API with a 400 Validation Error.

Common block sizes

A /24 block is a practical default for most deployments — it provides 254 usable IPs, stays within a predictable third octet, and maps cleanly to a single Class C subnet.

Avoiding overlap

Each network you create must use a non-overlapping CIDR block. Two blocks overlap when one contains addresses that also appear in the other.

For example, 10.42.0.0/24 and 10.42.0.0/25 overlap — the /25 block (10.42.0.0–10.42.0.127) is entirely contained within the /24 block. A safe pair would be 10.42.0.0/24 and 10.42.1.0/24.

A simple way to avoid overlap is to increment the third octet for each new network when using /24 blocks:

10.42.0.0/24   ← network 1
10.42.1.0/24   ← network 2
10.42.2.0/24   ← network 3

Worked examples

Example 1 — 10.42.5.0/24

• Network address: 10.42.5.0
• Broadcast address: 10.42.5.255
• Usable range: 10.42.5.1 – 10.42.5.254
• Usable hosts: 254

Example 2 — 192.168.10.0/28

• Network address: 192.168.10.0
• Broadcast address: 192.168.10.15
• Usable range: 192.168.10.1 – 192.168.10.14
• Usable hosts: 14

Example 3 — 172.16.0.0/20

• Network address: 172.16.0.0
• Broadcast address: 172.16.15.255
• Usable range: 172.16.0.1 – 172.16.15.254
• Usable hosts: 4 094

Further reading

• Private Networks — how hzel uses CIDR blocks to assign IPs to containers.
• RFC 1918 — the standard that defines private address space.