> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/specify-ipv4-cidr-block.md).

# Specify an IPv4 CIDR Block for a Private LAN

Specify a custom IPv4 CIDR block for a private LAN via the IONOS CLOUD API.

By default, <code class="expression">space.vars.ionos\_cloud</code> automatically assigns a `/23` IPv4 Classless Inter-Domain Routing (CIDR) block to every private [<mark style="color:blue;">LAN</mark>](https://docs.ionos.com/cloud/support/general-information/glossary-of-terms#local-area-network-lan) you create. To specify a custom CIDR block instead, use the [<mark style="color:blue;">IONOS CLOUD API</mark>](https://docs.ionos.com/cloud/api-reference/cloud-api-v6/lans/create-lans) or [<mark style="color:blue;">Terraform</mark>](https://docs.ionos.com/cloud/tools-terraform/resources/lan#example-usage-with-a-custom-ipv4-cidr-block).

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 [<mark style="color:blue;">NICs</mark>](https://docs.ionos.com/cloud/support/general-information/glossary-of-terms#nic) connected to the LAN.

## Prerequisites

* An existing [<mark style="color:blue;">VDC</mark>](https://docs.ionos.com/cloud/support/general-information/glossary-of-terms#vdc) in which to create or update the LAN.
* A valid <code class="expression">space.vars.ionos\_cloud</code> API token with write permissions on the target VDC.
* Familiarity with [<mark style="color:blue;">RFC 1918</mark>](https://www.rfc-editor.org/info/rfc1918/) private address ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`).

{% hint style="info" %}
**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`.
{% endhint %}

{% stepper %}
{% step %}

### 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 [<mark style="color:blue;">RFC 1918</mark>](https://www.rfc-editor.org/info/rfc1918/) CIDR block with a prefix length between `/23` and `/28`, aligned to its prefix boundary.

**Endpoint:** `POST /datacenters/{datacenterId}/lans`

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

{% hint style="info" %}
**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.
{% endhint %}
{% endstep %}

{% step %}

### 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.

```json
{
  "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](#reference) before proceeding.
{% endstep %}

{% step %}

### Assign a NIC IP address in the custom CIDR

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

{% tabs %}
{% tab title="Automatic 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`

```json
{
  "properties": {
    "lan": 3
  }
}
```

{% endtab %}

{% tab title="Manual assignment" %}
Specify an IP address in the `ips` field. The address must be within the LAN CIDR.

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

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

{% hint style="info" %}
**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`.
{% endhint %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Result:**

You have configured a custom IPv4 CIDR block for your private LAN. The platform assigns NIC IPs from your specified range, starting at `.10`. If you update the CIDR block later, NIC IPs may be reassigned. Update any application configuration, DNS records, or firewall rules that depend on specific NIC IPs after the change completes.
{% endhint %}

## Update a LAN's CIDR

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

{% hint style="warning" %}
**Important:** Changing `ipv4CidrBlock` re-allocates NIC IP addresses within the new CIDR block. NIC UUIDs and MAC addresses are preserved, but NIC IP addresses may change. After the operation completes, update any application configuration, DNS records, and firewall rules that reference the old NIC IP addresses.
{% endhint %}

{% tabs %}
{% tab title="PATCH" %}
Use a `PATCH` request to update just the `ipv4CidrBlock` on an existing LAN.

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

```json
{
  "ipv4CidrBlock": "10.5.0.0/24"
}
```

{% endtab %}

{% tab title="PUT" %}
Use a `PUT` request to update the entire property set of an existing LAN.

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

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

{% endtab %}
{% endtabs %}

## 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 [<mark style="color:blue;">RFC 1918</mark>](https://www.rfc-editor.org/info/rfc1918/) | 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

* [<mark style="color:blue;">Configure a Private LAN</mark>](https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/configure-private-lan.md)
* [<mark style="color:blue;">Add Internet Access</mark>](https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/add-internet-access.md)
* [<mark style="color:blue;">Merge Private LANs</mark>](https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/merge-private-lan.md)
* [<mark style="color:blue;">Split a Private LAN</mark>](https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/split-private-lan.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ionos.com/cloud/network-services/vdc-networking/lan/how-tos/specify-ipv4-cidr-block.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
