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 addresses are only visible to servers under the same UpCloud account. A server has a minimum of one and a maximum of five public IPv4 and IPv6 addresses. Every server can have one private IPv4 address only. The UpCloud API assigns the IP addresses automatically. IP addresses cannot be reserved for later use.

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 a private network. If the server has an IPv6 address configured it will use the third network interface. DHCP service is provided on all IPv4 network interfaces 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.

List IP addresses

Returns a list of all IP addresses assigned to servers on the current user account.

Request

GET /1.2/ip_address

Normal response

HTTP/1.0 200 OK
{
  "ip_addresses": {
    "ip_address": [
      {
        "access": "private",
        "address": "10.0.0.0",
        "family": "IPv4",
        "ptr_record": "",
        "server": "0053cd80-5945-4105-9081-11192806a8f7"
      },
      {
        "access": "private",
        "address": "10.0.0.1",
        "family": "IPv4",
        "ptr_record": "",
        "server": "006b6701-55d2-4374-ac40-56cc1501037f"
      },
      {
        "access": "public",
        "address": "x.x.x.x",
        "family": "IPv4",
        "part_of_plan": "yes",
        "ptr_record": "x.x.x.x.zone.host.upcloud.com",
        "server": "0053cd80-5945-4105-9081-11192806a8f7"
      },
      {
        "access": "public",
        "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
        "family": "IPv6",
        "ptr_record": "xxxx-xxxx-xxxx-xxxx.v6.zone.host.upcloud.com",
        "server": "006b6701-55d2-4374-ac40-56cc1501037f"
      }
    ]
  }
}

Get IP address details

Returns detailed information about a specific IP address.

Request

GET /1.2/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",
  }
}

Assign IP address

Assigns a new IP address to a server.

Only public IP addresses can be added. There is always exactly one private IP address per server. There is a maximum of five public IP addresses per server.

The server state must be stopped.

Request

POST /1.2/ip_address
{
  "ip_address": {
    "family": "IPv4",
    "server": "009d64ef-31d1-4684-a26b-c86c955cbf46"
  }
}

Attributes

Attribute Accepted values Default value Required Description
access private / public public yes Is address for private or public network.
family IPv4 / IPv6 IPv4 no The address family of new 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.host.upcloud.com",
    "server": "009d64ef-31d1-4684-a26b-c86c955cbf46"
  }
}

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. The PTR record can only be set to public IP address.

Request

PUT /1.2/ip_address/0.0.0.0
{
  "ip_address": {
    "ptr_record": "hostname.example.com"
  }
}

Attributes

Attribute Accepted values Default value Required Description
ptr_record DNS PTR record value yes 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"
  }
}

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.
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 private IP address.

Release IP address

Removes an IP address from a server.

Request

DELETE /1.2/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 private network cannot be deleted.