Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Specify an IPv4 CIDR Block for a Private LAN

By default, IONOS CLOUD automatically assigns a /23 IPv4 Classless Inter-Domain Routing (CIDR) block to every private LAN you create. To specify a custom CIDR block instead, use the IONOS CLOUD API or Terraform.

Specify your own CIDR block when you must:

  • Align private LAN addressing with your on-premises subnets.

  • Avoid address overlap between LANs in the same Virtual Data Center (VDC).

  • Control the size of the address pool available to NICs connected to the LAN.

Prerequisites

  • An existing VDC in which to create or update the LAN.

  • A valid IONOS CLOUD API token with write permissions on the target VDC.

  • Familiarity with RFC 1918 private address ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).

Note: To use the platform default, omit ipv4CidrBlock from the request body. The platform automatically assigns a /23 CIDR block, returned in the response under properties.ipv4CidrBlock.

1

Create a private LAN with a custom CIDR

Pass the optional ipv4CidrBlock field in the request body when creating a LAN. The value must be a valid RFC 1918 CIDR block with a prefix length between /23 and /28, aligned to its prefix boundary.

Endpoint: POST /datacenters/{datacenterId}/lans

{
  "properties": {
    "name": "app-tier",
    "public": false,
    "ipv4CidrBlock": "10.5.0.0/24"
  }
}

Note: The ipv4CidrBlock field is valid only on private LANs. Set "public": false. Specifying it on a public LAN returns HTTP 422 with error code 656.

2

Verify the assigned CIDR

Check the properties.ipv4CidrBlock field in the response to confirm the platform accepted your custom CIDR. If you used the platform default, the auto-assigned block appears here.

{
  "properties": {
    "name": "app-tier",
    "public": false,
    "ipv4CidrBlock": "10.5.0.0/24"
  }
}

If the field is absent or returns an error, check the validation rules before proceeding.

3

Assign a NIC IP address in the custom CIDR

Connect an NIC to the LAN using automatic or manual IP assignment.

Create the NIC without specifying the ips field. The platform assigns an IP address from .10 upward within the LAN CIDR.

Endpoint: POST /datacenters/{datacenterId}/servers/{serverId}/nics

{
  "properties": {
    "lan": 3
  }
}

Specify an IP address in the ips field. The address must be within the LAN CIDR.

Endpoint: POST /datacenters/{datacenterId}/servers/{serverId}/nics

{
  "properties": {
    "lan": 3,
    "ips": ["10.5.0.100"]
  }
}

Note: Within each custom CIDR, the following addresses are not auto-assigned by the platform. You can still set them manually.

  • The first address of the block: network address

  • The second through tenth addresses of the block: platform-reserved

  • The last address of the block: broadcast address

  • The second-to-last address of the block, if DHCP is enabled

For example, in 10.5.0.0/24, the platform auto-assigns NIC IP addresses from 10.5.0.10 to 10.5.0.254. If DHCP is enabled, the range ends at 10.5.0.253.

Update a LAN's CIDR

Both PATCH and PUT support changing ipv4CidrBlock on an existing LAN.

Use a PATCH request to update just the ipv4CidrBlock on an existing LAN.

Endpoint: PATCH /datacenters/{datacenterId}/lans/{lanId}

Use a PUT request to update the entire property set of an existing LAN.

Endpoint: PUT /datacenters/{datacenterId}/lans/{lanId}

Reference

Validation rules

The ipv4CidrBlock field is validated when a LAN is created or updated. Invalid values return HTTP 422.

Rule

Error code

Example error message

LAN must be private where "public": false

656

An IPv4 CIDR block can only be assigned to a private LAN.

CIDR must be within RFC 1918

654

The requested LAN IPv4 CIDR block 1.2.3.0/24 is not a private IPv4 CIDR block.

Prefix length must be /23-/28

655

The requested LAN IPv4 CIDR block 10.0.0.0/16 is bigger than the default LAN block: its prefix length must be /23 or longer.

Use the first address of the CIDR block. Example: 10.99.99.0/28, not 10.99.99.5/28.

536

The requested IPv4 block 10.99.99.5/28 is invalid.

CIDR must not overlap with existing LANs in the same VDC

602

The requested LAN IPv4 block 10.0.0.0/25 overlaps with an existing LAN block 10.0.0.0/24 in the VDC <uuid>.

NIC capacity by CIDR size

The number of NIC IP addresses that the platform auto-assigns depends on the prefix length of the custom CIDR. The platform does not auto-assign the network address, the platform-reserved addresses, or the broadcast address, but you can still set them manually.

CIDR

Total addresses

Auto-assigned NIC addresses

/23

512

501

/24

256

245

/25

128

117

/26

64

53

/27

32

21

/28

16

5

The values in the table apply when DHCP is disabled. If DHCP is enabled, the platform also does not auto-assign the second-to-last address of the block, so each CIDR has one fewer auto-assigned NIC address.

Next steps

Last updated

Was this helpful?