Address pool and VM addressing

When to use

Use this procedure to control which network addresses can be assigned to virtual machines: reserve an address for physical hardware or an external service, restore a previously excluded address, find a machine by its address, or check whether available addresses are running low.

This guide works with an existing network. Network creation is covered in a separate guide: How to create and manage a network.

Prerequisites

• The network is created and assigned to a virtual data center (VDC).
• To view the pool contents, the View IP Pool Details privilege.
• You know which network's pool you are working with: find it by the ID column in the All Networks list.
• vStack Center version 3.0.4.

How a machine receives an address

An address is allocated when a network interface is added to a machine: on the VM card, this is the Add network button. vStack Center takes a free address from the selected network's pool and assigns it to the machine; on a dual-stack network, the machine receives addresses from both families. The assigned address is shown in the same place, in the Networks section on the machine card, in the IP column next to MAC and the slot number.

The pool determines which addresses are eligible for assignment at all. For IPv4, it is a list of allowed addresses; for IPv6, it is a list of reservations, or exclusions. This accounts for the dual behavior of the operations below: "exclude an address" removes a record from the pool for IPv4 and adds a reservation record for IPv6. For more about this asymmetry, see Cluster networks: types, dual-stack, and address pools.

Viewing the pool contents

1. Open Provider Data Center → All Networks and go to the network card.

2. Expand the IPPool space section. Its header shows the network subnet, with a grid of addresses in that subnet below it. The grid is based on the IPv4 subnet: IPv6 reservations are not shown in it.

3. Read address states using the three filter buttons above the grid. Each displays a counter and leaves only its own addresses in the grid; clicking it again removes the filter.

   Filter	Addresses shown	Can be assigned to a machine
   N free IP address	The address is in the pool and is not used by anyone	Yes, it will be assigned to the next machine
   N used IP address	The address is already assigned to a machine	No, it is in use
   N absent IP address	The address is within the subnet but is not in the pool	No, until you return it to the pool

4. Find the address you need: the Search IP address field above the grid searches for a substring, and the selector below the grid changes the number of addresses per page (24 by default).

5. Click an address to open a window with the subnet (Subnet address:), the address itself (IP address:), a menu of available actions, and the Comment field.

The third state, absent, follows directly from IPv4 allowlist logic: the address is within the subnet but cannot be assigned until it is added to the pool. The Comment field is especially useful for these addresses: a note is saved in your settings and reminds you why the address was excluded from assignment.

If the pool is not displayed

Code	Cause	Action
-403 "Access denied"	The View IP Pool Details privilege is missing	Request the privilege from the cluster administrator
-25503 "network_id param does not exist", -25504 "network_id param is null"	The network was not identified: the request was sent without an ID	Return to All Networks and reopen the network card
-25505 "network_id param is not numeric"	The network ID was not passed as a number; this occurs only in programmatic requests	Pass a numeric ID
-25501 "Params section does not exist", -25502 "Params section is null"	The request was sent without parameters; this occurs only in programmatic requests	Add a parameters section with the network ID
-7	Database error	Retry; if that does not help, contact support

Excluding an address from assignment

This removes an address from automatic allocation, for example, to assign it to a physical server or reserve it for a future service.

1. In the IPPool space section, enable the N free IP address filter and click the address you need.

2. In the actions menu, select Delete from IP pool.

3. Confirm deletion in the dialog. It asks about a specific address: check it and click Delete; the Cancel button closes the dialog without changes.

4. Verify that the address moves to the absent category: the N absent IP address counter increases, and the address is visible under this filter. A notification with the address and network number also indicates success.

An address in the used state has no actions in its menu: an address in use cannot be excluded from assignment. Conversely, exclusion does not take an address away from a machine that has already received it: the operation affects only future assignments.

For IPv6, the same operation adds the address to the reservation list; the result is the same: the address can no longer be assigned to a machine.

If an address cannot be excluded

Code	Cause	Action
-25722 "The address doesn't match network cidr"	The address is outside the network subnet	Check the address against the network's CIDR
-25724 "The address does not exist"	The address is already outside the pool and is shown under the absent filter	No action is needed
-25727 "The address is already reserved"	The IPv6 address is already reserved	No action is needed
-25725 "The network does not support IPv4"	The network has no IPv4 subnet	Use this network's IPv6 addresses
-25726 "The network does not support IPv6"	The network has no IPv6 subnet	Use this network's IPv4 addresses
-25708 "address param is not valid"	The address cannot be parsed	Correct the address format
-25720 "The network does not exist"	The network with this ID no longer exists	Refresh the All Networks list

Making an address available for assignment again

This is the reverse operation: the address becomes available to machines again.

1. In the IPPool space section, enable the N absent IP address filter and click the address you need.

2. In the actions menu, select Add. This operation does not ask for confirmation.

3. Verify that the address moves to the free category: the N free IP address counter increases, and the address is visible under this filter.

For IPv6, the same operation removes the reservation.

If an address cannot be returned to the pool

Code	Cause	Action
-25622 "The address doesn't match network cidr"	The address is outside the network subnet	Check the address against the network's CIDR
-25623 "The address exists already"	The address is already in the pool and is shown under the free filter	No action is needed
-25626 "The address is not reserved"	The IPv6 address is already unreserved	No action is needed
-25624 "The network does not support IPv4"	The network has no IPv4 subnet	Use this network's IPv6 addresses
-25625 "The network does not support IPv6"	The network has no IPv6 subnet	Use this network's IPv4 addresses
-25608 "address param is not valid"	The address cannot be parsed	Correct the address format
-25620 "The network does not exist"	The network with this ID no longer exists	Refresh the All Networks list

Finding which addresses are used and by whom

1. Open the network card and expand the IPPool usage section. The table with ID, VDC name, and Used IP Addresses breaks down used addresses by VDC and answers the first question: which VDC has used this network's addresses.

2. Go down to the machine level. Open the relevant VDC → Virtual Machines and check the Networks section on machine cards: the IP column shows the address received by the interface.

3. Verify that you found the address on the correct interface: in the Networks section, IP appears alongside Slot, Port, and MAC.

The interface traces the relationship to the VDC, rather than directly to the machine: the API provides the complete network → VDC → machine → address chain. The methods are listed at the end of this page.

Checking address availability

Address availability is shown in three places, each answering a different question.

Where to look	What it shows
Provider Data Center → All Networks	Used IP Addresses and Free IP Addresses columns for each cluster network; the CSV button exports the entire table
Network card, IPPool space section	free, used, and absent counters for this network's subnet
VDC → Networks, IP Data tab	Used IP addresses by this vDC, Used IP Addresses, Free IP Addresses, and Addrs limit: usage by a specific VDC and its limit

The interface counters count IPv4 addresses: Free IP Addresses means addresses in the pool that are not used by anyone. Free IPv6 addresses are counted differently, and for broad subnets their number is not calculated at all. For the reason, see Cluster networks: types, dual-stack, and address pools.

See also

• Cluster networks: types, dual-stack, and address pools— why IPv4 and IPv6 pools work differently.
• How to create and manage a network—creating a network and assigning it to a VDC.

API methods

The API operations covered on this page are net-ippool-show, net-ippool-add, net-ippool-delete, net-ippool-usage, and net-ippool-free. See the API reference.