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 zero and a maximum of five public IPv4 and IPv6 addresses. Every server can have one private IPv4 address only, and must have at least one IP address. 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.upcloud.host",
        "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.upcloud.host",
        "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 at most 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	no	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.upcloud.host",
    "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.