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 publiv 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

GET /1.3/ip_address

Normal response

HTTP/1.0 200 OK
{
  "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

GET /1.3/ip_address/0.0.0.0

Normal response

HTTP/1.0 200 OK
{
  "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.

Request

POST /1.3/ip_address
{
  "ip_address": {
    "family": "IPv4",
    "mac": "mm:mm:mm:mm:mm:m1"
  }
}

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.

POST /1.3/ip_address
{
  "ip_address": {
    "family": "IPv4",
    "mac": "mm:mm:mm:mm:mm:m1",
    "floating": "yes"
  }
}

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

HTTP/1.0 201 Created
{
  "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.
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

PATCH /1.3/ip_address/0.0.0.0
{
  "ip_address": {
    "mac": "mm:mm:mm:mm:mm:m1",
    "ptr_record": "hostname.example.com"
  }
}

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

HTTP/1.0 202 Accepted
{
  "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.
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

DELETE /1.3/ip_address/0.0.0.0

Normal response

HTTP/1.0 204 No Content

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.