10. IP Addresses
The UpCloud network has public and private IP addresses.
Public IP addresses are used to connect to the server from the Internet.
Private Utility network addresses are available for all servers within a single account, and can communicate with each other globally as long as the servers have the utility network interfaces configured. This is added to servers by default.
A server has a minimum of zero and a maximum of five public IPv4 and IPv6 addresses. Every server can have one utility network IPv4 address only, and must have at least one IP address. The UpCloud API assigns the IP addresses automatically in networks configured to use DHCP. IP addresses cannot be reserved for later use, except for floating IPs that can be reserved and switched from server to another freely within their specific zone.
The operating system running on the server will see a separate network interface per IP address. On a typical server, there are three network interfaces. The first network interface is assigned to the public network and the second to the Utility network. If the server has an IPv6 address configured it will use the third network interface. DHCP service is provided on all public IPv4 network interfaces and all private DHCP-enabled networks for automatic configuration of the correct IP address. IPv6 network interfaces should use stateless address autoconfiguration (SLAAC) with IPv6 privacy extensions disabled. On IPv6-only server DNS parameters can be obtained with stateless DHCPv6.
Additionally, there are floating IP's: IPv4 addresses that can be attached to any IPv4 interface in their specific zone (eg. de-fra1 or fi-hel2). Floating IP addresses can be instantly switched from one server to another when doing maintenance or dealing with technical issues. More information on floating IPs and their configuration can be found from our tutorials.
List IP addresses
Returns a list of all IP addresses assigned to servers on the current user account.
Request
Normal response
{
"ip_addresses": {
"ip_address": [
{
"access": "utility",
"address": "10.0.0.0",
"family": "IPv4",
"ptr_record": "",
"server": "0053cd80-5945-4105-9081-11192806a8f7",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "no",
"zone": "fi-hel2"
},
{
"access": "utility",
"address": "10.0.0.1",
"family": "IPv4",
"ptr_record": "",
"server": "006b6701-55d2-4374-ac40-56cc1501037f",
"mac": "mm:mm:mm:mm:mm:m2",
"floating": "no",
"zone": "de-fra1"
},
{
"access": "public",
"address": "x.x.x.x",
"family": "IPv4",
"part_of_plan": "yes",
"ptr_record": "x-x-x-x.zone.upcloud.host",
"server": "0053cd80-5945-4105-9081-11192806a8f7",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"zone": "de-fra1"
},
{
"access": "public",
"address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
"family": "IPv6",
"ptr_record": "xxxx-xxxx-xxxx-xxxx.v6.zone.upcloud.host",
"server": "006b6701-55d2-4374-ac40-56cc1501037f",
"mac": "mm:mm:mm:mm:mm:m3",
"floating": "no",
"zone": "fi-hel1"
},
{
"access": "public",
"address": "y.y.y.y",
"family": "IPv4",
"ptr_record": "y.y.y.y.zone.host.upcloud.com",
"floating": "yes",
"zone": "nl-ams1"
}
]
}
}
Get IP address details
Returns detailed information about a specific IP address.
Request
Where address specifies the IP address. eg. 127.0.0.1
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"part_of_plan": "yes",
"ptr_record": "test.example.com",
"server": "009d64ef-31d1-4684-a26b-c86c955cbf46",
"mac": "mm:mm:mm:mm:mm:m5",
"floating": "no",
"zone": "sg-sin1"
}
}
Assign IP address
Assigns a new IP address to a server.
There is a maximum of five public IP addresses per server.
If a MAC address is specified, the server where the corresponding interface is must be in stopped state.
Floating IPs are attached with the Modify IP address operation.
Request
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| access | utility / public | public | no | Is address for utility or public network. |
| family | IPv4 / IPv6 | IPv4 | no | The address family of new IP address. |
| address | IPv4 address | no | Assign a specific address. Requires special privileges and is supported for IPv4 only. | |
| server | Server UUID | yes | UUID of a server for which the address is assigned. |
Creating Floating IPs
Floating IPs can be directly attached to servers by specifying
a MAC address to one of their public interfaces. If mac is not
specified, the address is created without attaching it to any server.
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| access | utility / public | public | no | Is address for utility or public network. |
| family | IPv4 / IPv6 | IPv4 | no | The address family of new IP address. |
| floating | yes / no | no | no | Whether the address to be assigned is a floating one. |
| address | IPv4 address | no | Assign a specific address. Requires special privileges and is supported for IPv4 only. | |
| mac | MAC address | (varies) | MAC address of server interface to assign address to. Required for non-floating addresses. | |
| zone | Zone identifier | (varies) | Zone of address, required when assigning a detached floating IP address. |
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"ptr_record": "xxxx-xxxx-xxxx-xxxx.v6.zone.upcloud.host",
"server": "009d64ef-31d1-4684-a26b-c86c955cbf46",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"zone": "fi-hel2"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | SERVER_INVALID | The attribute server has an invalid value. |
| 402 Payment Required | INSUFFICIENT_CREDITS | There are not enough credits to perform the requested action. See Credits. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 403 Forbidden | ADDRESS_SELECTION_FORBIDDEN | The address selection feature is not available for this account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | IP_ADDRESS_LIMIT_REACHED | The maximum number of IP addresses are already attached to the server. |
| 409 Conflict | IP_ADDRESS_RESOURCES_UNAVAILABLE | There are not enough IP addresses available in the specified zone. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
Modify IP address
Modifies the reverse DNS PTR record corresponding to an IP address,
and modifies attachment of a floating IP. Attaching a floating IP to
an interface detaches it from its previous interface, if any. To
detach a floating IP without attaching it to another interface, pass
explicit null or empty string as mac value. The PTR record can
only be set to a public IP address.
Request
Where address specifies the IP address. eg. 127.0.0.1
Attributes
| Attribute | Accepted values | Default value | Required | Description |
|---|---|---|---|---|
| mac | MAC address | no | MAC address of server interface to attach floating IP to. | |
| ptr_record | DNS PTR record value | no | A fully qualified domain name. |
Normal response
{
"ip_address": {
"access": "public",
"address": "0.0.0.0",
"family": "IPv4",
"ptr_record": "hostname.example.com",
"server": "009d64ef-31d1-4684-a26b-c86c95c5bf46",
"mac": "mm:mm:mm:mm:mm:m1",
"floating": "yes",
"zone": "sg-sin1"
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | IP_ADDRESS_INVALID | The attribute ip_address has an invalid value. |
| 400 Bad Request | PTR_RECORD_INVALID | The attribute ptr_record has an invalid value. |
| 400 Bad Request | MAC_INVALID | The attribute mac has an invalid value. |
| 403 Forbidden | IP_ADDRESS_FORBIDDEN | The IP address exists, but belong to another user. |
| 403 Forbidden | TRIAL_SERVER_LIMIT_REACHED | Trial mode server limit reached. |
| 403 Forbidden | TRIAL_CORE_LIMIT_REACHED | Trial mode core limit reached. |
| 403 Forbidden | TRIAL_NETWORK_LIMIT_REACHED | Trial mode network limit reached. |
| 403 Forbidden | TRIAL_DETACHED_FLOATING_IP_LIMIT_REACHED | Trial mode detached floating IP limit reached. |
| 403 Forbidden | TRIAL_MEMORY_LIMIT_REACHED | Trial mode memory limit reached. |
| 403 Forbidden | TRIAL_STORAGE_LIMIT_REACHED | Trial mode storage limit reached. |
| 403 Forbidden | TRIAL_STORAGE_SIZE_LIMIT_REACHED | Trial mode storage size limit reached. |
| 403 Forbidden | TRIAL_IP_LIMIT_REACHED | Trial mode IP limit reached. |
| 404 Not found | IP_ADDRESS_NOT_FOUND | The IP address does not exist. |
| 409 Conflict | PTR_RECORD_NOT_SUPPORTED | A PTR record was tried to set on a utility IP address. |
| 409 Conflict | FLOATING_IP_NOT_AVAILABLE | The floating IP operation is not available for the specified IP address. |
Release IP address
Removes an IP address from a server.
Request
Where address specifies the IP address. eg. 127.0.0.1
Normal response
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | IP_ADDRESS_INVALID | The attribute ip_address has an invalid value. |
| 403 Forbidden | IP_ADDRESS_FORBIDDEN | The IP address exists, but is assigned to another account. |
| 404 Not Found | IP_ADDRESS_NOT_FOUND | The IP address does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
| 409 Conflict | CANNOT_DELETE_PRIVATE_ADDRESS | The IP address on the utility network cannot be deleted. |