8. Servers

This chapter describes operations for creating and managing servers on UpCloud. A server is a single virtual machine instance running on UpCloud.

The server configuration defines which storage devices the server is attached to, which IP addresses can be used and how the server can be reached for remote management. A server must have at least one storage device attached in order to be started. Servers may have from zero to five public IPv4 and IPv6 addresses. All servers have a utility IP address that cannot be removed.

Server states

The server state indicates the server's current status.

State	Description
started	The server is running.
stopped	The server is stopped.
maintenance	The server is in maintenance mode.
error	The server has encountered an error. This means the server is inaccessible due to an error in the cloud service.

The normal server states are started and stopped. The maintenance state is a temporary state used when the cloud service updates the server. If the server is in error state, it will return automatically in the started or stopped state when the issue is resolved.

List server configurations

Returns a list of available server configurations. A server configuration consists of a combination of CPU core count and main memory amount. All servers are created using these configurations.

Request

GET /1.3/server_size HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "server_sizes": {
    "server_size": [
      {
        "core_number": "1",
        "memory_amount": "1024"
      },
      {
        "core_number": "1",
        "memory_amount": "2048"
      },
      ...many more combinations...
      {
        "core_number": "20",
        "memory_amount": "130048"
      },
      {
        "core_number": "20",
        "memory_amount": "131072"
      }
    ]
  }
}

List servers

Returns a list of all servers associated with the current acc

Only the servers' most relevant information is returned by this operation. Further details on individual servers can be requested with the Get server details operation.

It is also possible to filter shown servers with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only servers that match all labels are returned. Label keys are matched case insensitively.

Request

GET /1.3/server HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "servers": {
    "server": [
      {
        "core_number": "1",
        "hostname": "fi.example.com",
        "labels": {
          "label": [
            {
              "key": "env",
              "value": "prod"
            }
          ]
        },
        "license": 0,
        "memory_amount": "2048",
        "plan": "1xCPU-2GB",
        "plan_ivp4_bytes": "34253332",
        "plan_ipv6_bytes": "0",
        "state": "started",
        "tags": {
          "tag": [
            "PROD",
            "CentOS"
          ]
        },
        "title": "Helsinki server",
        "uuid": "00798b85-efdc-41ca-8021-f6ef457b8531",
        "zone": "fi-hel1"
      },
      {
        "core_number": "1",
        "hostname": "uk.example.com",
        "labels": {
          "label": []
        },
        "license": 0,
        "memory_amount": "512",
        "plan": "custom",
        "state": "stopped",
        "tags": {
          "tag": [
            "DEV",
            "Ubuntu"
          ]
        },
        "title": "London server",
        "uuid": "009d64ef-31d1-4684-a26b-c86c955cbf46",
        "zone": "uk-lon1"
      }
    ]
  }
}

Get server details

Returns detailed information about a specific server.

Request

GET /1.3/server/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "server": {
    "boot_order": "disk",
    "core_number": "0",
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "dev"
        }
      ]
    },
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.0.0.00",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "0.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "license": 0,
    "memory_amount": "2048",
    "networking": {
      "interfaces": {
        "interface": [
          {
            "index": 1,
            "ip_addresses": {
              "ip_address": [
                {
                  "address": "94.237.0.207",
                  "dhcp_provided": "yes",
                  "family": "IPv4",
                  "floating": "no"
                }
              ]
            },
            "mac": "de:ff:ff:ff:66:89",
            "network": "037fcf2a-6745-45dd-867e-f9479ea8c044",
            "type": "public",
            "bootable": "no"
          },
          {
            "index": 2,
            "ip_addresses": {
              "ip_address": [
                {
                  "address": "10.6.3.95",
                  "dhcp_provided": "yes",
                  "family": "IPv4",
                  "floating": "no"
                }
              ]
            },
            "mac": "de:ff:ff:ff:ed:85",
            "network": "03000000-0000-4000-8045-000000000000",
            "type": "utility",
            "bootable": "no"
          },
          {
            "index": 3,
            "ip_addresses": {
              "ip_address": [
                {
                  "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
                  "dhcp_provided": "yes",
                  "family": "IPv6",
                  "floating": "no"
                }
              ]
            },
            "mac": "de:ff:ff:ff:cc:20",
            "network": "03c93fd8-cc60-4849-91b8-6e404b228e2a",
            "type": "public",
            "bootable": "no"
          }
        ]
      }
    },
    "nic_model": "virtio",
    "plan": "1xCPU-2GB",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "simple_backup": "0100,dailies",
    "state": "started",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan": "yes",
          "labels": [
            {
              "key": "foo",
              "value": "bar"
            }
          ],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_size": 20,
          "storage_encrypted": "yes",
          "storage_tier": "maxiops",
          "storage_title": "Storage for server1.example.com",
          "type": "disk",
          "boot_disk": "0"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "server1.example.com",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "remote_access_host": "fi-hel1.vnc.upcloud.com",
    "remote_access_password": "aabbccdd",
    "remote_access_port": "3000",
    "zone": "fi-hel1"
  }
}

The license attribute indicates the amount of credits per hour per CPU core required by the server license. The server's license attribute is the sum of all the attached storages' license attributes.

Create server

Creates a new server instance.

There are three ways to create a server:

from a template,
by cloning another server, or,
by installing the server from scratch using an operating system installation media.

New servers are automatically started. By default, the server is not accessible by a remote access software. The remote access via VNC can be enabled by setting remote_access_enabled parameter's value to yes. A remote access password is generated and returned in the output of the create server operation.

The server can be added to a server group. See Server Groups for more information.

Creating from a template

UpCloud provides templates for various operating systems. Servers created from templates are preconfigured. The configurations vary between templates and may include, for example, setting the hostname, resizing the filesystem to fill the storage size and setting a root or other administrative account password.

A list of available templates can be obtained with the following request:

GET /1.3/storage/template HTTP/1.1

See List storages for more information on storage resource listings.

When creating a Linux server from a template, we recommend the use of ssh_keys as the login method. ssh_keys are also the only login method for cloud-init enabled templates - one cannot create a password for these templates. It is possible to define one or more public SSH keys. Without ssh_keys, by default on non-cloud-init templates, we create a one-time password for the administrative account which is returned in the output of the operation. This password is not stored anywhere and cannot be retrieved later. Once the administrative user logs in, they are forced to change this one-time password. To check the template type of a public storage, see List storages for more information.

When creating a Windows server from a template, the administrative account's password is returned in the output of the operation (unless create_password in login_user section is set to "no"). This password is not stored anywhere and cannot be retrieved later. For security reasons, the password should be changed immediately after logging in.

With user_data it is possible to enter any set of commands (usually in a form of a bash script or URL to one) to perform automated initial configuration on server (e.g. installing automatically additional software components from package repository). Note that these commands will be executed with root privileges upon server initialization so special care should be taken to provide only verified data.

Creating a server from a template is an asynchronous operation. While the create operation is running, the server is in maintenance state as the server is being configured. As soon as the server is ready, the state will change to started.

Creation of private templates is possible from any storage device. Private templates can be used in same way as public templates. See Templatize storage for more information.

Request

POST /1.3/server HTTP/1.1

{
  "server": {
    "zone": "fi-hel1",
    "title": "My Debian server",
    "hostname": "debian.example.com",
    "labels": {
      "label": [
        {
          "key": "test",
          "value": ""
        }
      ]
    },
    "plan": "2xCPU-4GB",
    "storage_devices": {
      "storage_device": [
        {
          "action": "clone",
          "labels": [
            {
              "key": "foo",
              "value": "bar"
            }
          ],
          "storage": "01000000-0000-4000-8000-000020030100",
          "encrypted": "yes",
          "title": "Debian from a template",
          "size": 50,
          "tier": "maxiops"
        }
      ]
    },
    "networking": {
      "interfaces": {
        "interface": [
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "public"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "utility"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv6"
                }
              ]
            },
            "type": "public"
          },
          {
            "type": "private",
            "network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4",
                  "address": "10.0.0.50",
                  "dhcp_provided": "yes"
                },
                {
                  "family": "IPv4",
                  "address": "10.0.0.60"
                }
              ]
            }
          }
        ]
      }
    },
    "login_user": {
      "username": "upclouduser",
      "ssh_keys": {
        "ssh_key": [
          "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
          "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
        ]
      }
    }
  }
}

The storage size is initially that of the template. When the server creation is complete, the storage will be resized and the size attribute will be set accordingly.

Cloning another server

An exact copy of another server can be obtained by cloning the server's storage devices. Cloning is a convenient method of creating multiple identical server instances.

The state of the cloned storage must be online.

Request

POST /1.3/server HTTP/1.1

{
  "server": {
    "zone": "fi-hel1",
    "title": "Another Debian server",
    "hostname": "debian2.example.com",
    "core_number": "4",
    "memory_amount": "8192",
    "storage_devices": {
      "storage_device": [
        {
          "action": "clone",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "title": "Storage for another Debian server"
        }
      ]
    },
    "networking": {
      "interfaces": {
        "interface": [
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "public"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "utility"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv6"
                }
              ]
            },
            "type": "public"
          },
          {
            "type": "private",
            "network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4",
                  "address": "10.0.0.50"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Installing a server from scratch

The server's operating system can be installed from a CD-ROM by attaching an empty storage device and loading an operating system installation CD-ROM.

UpCloud provides a variety of installation CD-ROMs for different operating systems. A list of CD-ROMs can be retrieved using the following request:

GET /1.3/storage/cdrom HTTP/1.1

See List storages for more information on storage resource listings. VNC is used to connect to the server during installation.

Request

POST /1.3/server HTTP/1.1

{
  "server": {
    "zone": "fi-hel1",
    "title": "My Debian server",
    "hostname": "debian.example.com",
    "avoid_host": 7653311107,
    "core_number": "4",
    "memory_amount": "8192",
    "storage_devices": {
      "storage_device": [
        {
          "action": "create",
          "size": "20",
          "tier": "maxiops",
          "title": "Debian from scratch"
        },
        {
          "action": "attach",
          "storage": "01000000-0000-4000-8000-000020010301",
          "type": "cdrom"
        }
      ]
    },
    "simple_backup": "0430,monthlies",
    "networking": {
      "interfaces": {
        "interface": [
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "public"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4"
                }
              ]
            },
            "type": "utility"
          },
          {
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv6"
                }
              ]
            },
            "type": "public"
          },
          {
            "type": "private",
            "network": "03b5b0a0-ad4c-4817-9632-dafdb3ace5d9",
            "ip_addresses": {
              "ip_address": [
                {
                  "family": "IPv4",
                  "address": "10.0.0.50"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Attributes

Attribute	Accepted values	Default value	Required	Description
avoid_host	A valid host id		no	Use this to make sure VMs do not reside on specific host. Refers to value from host -attribute. Useful when building HA-environments.
host	A valid host id		no	Use this to start a VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts.
boot_order	disk / cdrom / network or comma separated combination	disk	no	The boot device order.
core_number	A valid combination with memory_amount	smallest possible	no	The number of CPU cores dedicated to the server. See List server configurations.
firewall	on / off	on	no	The state of the server firewall rules.
hostname	A valid hostname		yes	A valid domain name, e.g. host.example.com. The maximum length is 128 characters.
interfaces	An array of 1-10 interface objects.		yes	All interfaces wanted for the server. Interface object is described below.
labels	0-255 `label` blocks		no	Labels contain key-value pairs defined in `label` block to classify the server.
login_user	One valid `login_user` block		no	Define login account and SSH keys
memory_amount	A valid combination with core_number	smallest possible	no	The amount of main memory in megabytes. See List server configurations.
metadata	yes / no	no	no	HTTP-accessible metadata service for the server. See our tutorial for more information.
nic_model	e1000 / virtio / rtl8139	virtio	no	The model of the server's network interfaces. It is recommended to use the default unless there are specific reasons to choose otherwise; others may be subject to bandwidth limitations.
password_delivery	none / email / sms	email	no	The delivery method for the server’s root password.
plan	A valid plan name returned with plan listing, or `custom`	`custom`	no	The pricing plan used. If a plan is selected, the `core_number` and `memory_amount` must match the plan if they are present.
storage_devices	1-16 storage_device blocks		yes	The storage_devices block contains storage_device blocks that define the attached storages.
timezone	A valid timezone identifier UTC		no	A timezone identifier, e.g. Europe/Helsinki. See Timezones.
title	0-255 characters		yes	A short, informational description.
user_data	A valid URL or shell script		no	Defines URL for a server setup script, or the script body itself
video_model	vga / cirrus	vga	no	The model of the server's video interface.
remote_access_type	vnc	vnc	no	The remote access type.
remote_access_enabled	yes / no	no	no	Is the remote access enabled.
remote_access_password	8 characters of a-z, A-Z and 0-9.	randomly generated	no	Remote access password.
simple_backup	HHMM,{daily\|dailies\|weeklies\|monthlies} / no	account default	no	Simple backup time in UTC, followed by daily, dailies, weeklies, or monthlies option separated by comma, or no when disabled.
zone	A valid zone identifier		yes	The zone in which the server will be hosted, e.g. fi-hel1. See Zones.
server_group	Server group UUID		no	Use this to add the VM to a server group

The storage_devices block may contain 1-16 storage devices. Each block can have the following attributes:

Attribute	Accepted values	Default value	Required	Description
action	create / clone / attach		yes	The method used to create or attach the specified storage.
address	ide[:[01]:[01]] / scsi[:0:[0-15]] / virtio[:[0-15]]	Next available address on the virtio bus	no	The device address the storage will be attached to. Specify only the bus name (ide/scsi/virtio) to auto-select next available address from that bus.
size	10-1024	if action is clone, same as original	yes	if action is create The size of the storage device in gigabytes. This attribute is applicable only if action is create or clone.
storage	A valid storage UUID		yes	if action is clone or attach The UUID of the storage device to be attached or cloned. Applicable only if action is attach or clone.
tier	A valid storage tier	plan default if applicable, otherwise `maxiops`	No	The storage tier to use. All tiers may not be available to all server plans. See Storage tiers.
title	0-255 characters		no	A short, informational description for the storage.
type	disk / cdrom	disk	no	The device type the storage will be attached as. See Storage types.
boot_disk	0/1	0	no	If the value is 1 the storage device will be used as a boot disk, unless overridden with the server boot_order attribute.
labels	List of wanted labels for the storage		no	Labels describing the storage, objects with both "key" and "value" defined. Available when the `action` is `create` or `clone`.
encrypted	`yes / no`	`no`	no	All block storage devices can be optionally encrypted at rest.

The interfaces block may contain 1-10 network interfaces. Each block can have the following attributes:

Attribute	Accepted values	Default value	Required	Description
network	A valid network unique ID		(varies)	Virtual network ID to join. Required for `private` interfaces. Setting it in `public` and `utility` interfaces requires special privileges.
type	public / utility / private		yes	Set the type of the network
index	Positive integer	Position in array	no	Interface index
ip_addresses	IP address array, see below		yes	Array of IP addresses under ip_address
source_ip_filtering	yes / no	yes	no	Whether source IP filtering is enabled on the interface. Disabling it is allowed only for SDN private interfaces.
bootable	yes / no	no	no	Whether to try booting through the interface.

Disabling the source IP filtering allows sourcing traffic from other IP addresses than allocated to virtual servers within the network, for example when a virtual server is acting as a NAT gateway or a site-to-site VPN endpoint.

ip_addresses block expects an ip_address-named array with following possible arguments.

Attribute	Accepted values	Default value	Required	Description
family	IPv4 / IPv6	IPv4	yes	Address family of the address. Currently IPv6 is only supported with `public` type interfaces.
address	IPv4 / IPv6 address		no	A valid IP address within the IP space of the network. If not given, the next free address is selected. Specifying an address in `public` and `utility` interfaces requires special privileges.
dhcp_provided	yes / no		no	In case of multiple IP addresses attached to the interface, the one marked with `dhcp_provided` flag is the one offered by the DHCP server. By default, the `dhcp_provided` is set to `yes` for the first IP address in the array.

The login_user block may contain username, create_password attribute and 0-32 SSH keys:

Attribute	Accepted values	Default value	Required	Description
create_password	yes / no	yes	no	If set to "yes", a one-time password will be created. If `ssh_keys` is set this defaults to "no". This option is disabled on cloud-init templates.
username	Valid, non-reserved username	root	no	If set to other than "root", normal user with sudo privileges is created
ssh_keys	1-32 `ssh_key` attributes		no	Each `ssh_key` child attribute defines one SSH-key in OpenSSH format. Requires `create_password` is set to "no" or not provided. This option is required for cloud-init templates.

Note: login_user and user_data attributes are ignored with other than Linux templates.

The labels block may include key-value pairs for classifying the server.

Attribute	Accepted values	Default value	Required	Description
key	2-32 printable ASCII characters (range 0x20-0x7E), must not start with `_`		yes	Label key
value	0-255 characters		yes	Label value

Labels can include specific service labels that cannot be modified. These always start with _ and do not conflict with normal labels.

Normal response

HTTP/1.1 202 Accepted

{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "license": 0,
    "memory_amount": "4096",
    "nic_model": "virtio",
    "password": "aabbccdd",
    "plan": "2xCPU-4GB",
    "plan_ipv4_bytes": "0",
    "plan_ipv6_bytes": "0",
    "simple_backup": "0430,dailies",
    "state": "maintenance",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": 1,
          "storage_tier": "maxiops",
          "storage_title": "Debian from a template",
          "type": "disk",
          "boot_disk": "0"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "remote_access_enabled": "no",
    "remote_access_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	ACTION_INVALID	The attribute action has an invalid value.
400 Bad Request	ACTION_MISSING	The required attribute action is missing from the request.
400 Bad Request	BOOT_ORDER_INVALID	The attribute boot_order has an invalid value.
400 Bad Request	CORE_MEMORY_UNSUPPORTED	The combination of core_number and memory_amount is not supported. See List server configurations.
400 Bad Request	CORE_NUMBER_INVALID	The attribute core_number has an invalid value.
400 Bad Request	CREATE_PASSWORD_INVALID	The attribute create_password cannot be yes when ssh keys is provided.
400 Bad Request	FIREWALL_INVALID	The attribute firewall has an invalid value.
400 Bad Request	HOSTNAME_INVALID	The attribute hostname has an invalid value. Value is case sensitive and must be in lower case.
400 Bad Request	HOSTNAME_MISSING	The required attribute hostname is missing from the request.
400 Bad Request	MEMORY_AMOUNT_INVALID	The attribute memory_amount has an invalid value.
400 Bad Request	NIC_MODEL_INVALID	The attribute nic_model has an invalid value.
400 Bad Request	PASSWORD_DELIVERY_INVALID	The attribute password_delivery has an invalid value.
400 Bad Request	SERVER_TITLE_INVALID	The attribute title in the server block has an invalid value.
400 Bad Request	SERVER_TITLE_MISSING	The required attribute title is missing from the server block.
400 Bad Request	SIMPLE_BACKUP_INVALID	The attribute simple_backup has an invalid value.
400 Bad Request	SIZE_INVALID	The attribute size has an invalid value. If action is clone, size must be greater than the size of the cloned storage.
400 Bad Request	SIZE_MISSING	The required attribute size is missing from the request.
400 Bad Request	STORAGE_DEVICE_INVALID	A malformed storage_device block.
400 Bad Request	STORAGE_DEVICE_MISSING	The storage_device block is missing from the request.
400 Bad Request	STORAGE_DEVICES_INVALID	A malformed storage_devices block.
400 Bad Request	STORAGE_DEVICES_MISSING	The storage_devices block is missing from the request.
400 Bad Request	STORAGE_INVALID	The attribute storage has an invalid value.
400 Bad Request	STORAGE_MISSING	The required attribute storage is missing from a storage_device block.
400 Bad Request	STORAGE_TITLE_INVALID	The attribute title in a storage_device block has an invalid value.
400 Bad Request	STORAGE_TITLE_MISSING	The required attribute title is missing from the storage_device block.
400 Bad Request	TIMEZONE_INVALID	The attribute timezone has an invalid value.
400 Bad Request	TYPE_INVALID	The attribute type has an invalid value.
400 Bad Request	TIER_INVALID	The attribute tier has an invalid value.
400 Bad Request	USER_DATA_INVALID	The attribute user_data has an invalid value.
400 Bad Request	VIDEO_MODEL_INVALID	The attribute video_model has an invalid value.
400 Bad Request	VNC_INVALID	The attribute remote_access_type has an invalid value.
400 Bad Request	VNC_PASSWORD_INVALID	The attribute remote_access_password has an invalid value.
400 Bad Request	ZONE_INVALID	The attribute zone has an invalid value.
400 Bad Request	ZONE_MISSING	The required attribute zone is missing from the request.
400 Bad Request	INVALID_LABEL_KEY	The attribute `key` in a label block has an invalid value.
400 Bad Request	INVALID_LABEL_VALUE	The attribute `value` in a label block has an invalid value.
402 Payment Required	INSUFFICIENT_CREDITS	There are not enough credits to perform the requested action. See Credits.
403 Forbidden	STORAGE_FORBIDDEN	The storage exists, but is owned by another account.
403 Forbidden	HOST_FORBIDDEN	The specified host is not available for the current account.
403 Forbidden	PLAN_CORE_NUMBER_ILLEGAL	The specified `core_number` does not match the selected plan.
403 Forbidden	PLAN_MEMORY_AMOUNT_ILLEGAL	The specified `memory_amount` does not match the selected plan.
403 Forbidden	TRIAL_PLAN	User is in trial mode, trial mode server cannot have a pricing plan.
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.
403 Forbidden	SERVER_CORE_LIMIT_REACHED	Server core account quota limit reached.
403 Forbidden	SERVER_MEMORY_LIMIT_REACHED	Server memory account quota limit reached.
403 Forbidden	HDD_STORAGE_LIMIT_REACHED	Archive storage account quota limit reached.
403 Forbidden	STANDARD_STORAGE_LIMIT_REACHED	Standard storage account quota limit reached.
403 Forbidden	MAXIOPS_STORAGE_LIMIT_REACHED	MaxIOPS storage account quota limit reached.
403 Forbidden	SERVER_IP_LIMIT_REACHED	Server IP account quota limit reached.
403 Forbidden	NETWORK_LIMIT_REACHED	Network account quota limit reached.
403 Forbidden	DETACHED_FLOATING_IP_LIMIT_REACHED	Detached floating IP account quota limit reached.
403 Forbidden	NETWORK_PEERING_LIMIT_REACHED	Network peering account quota limit reached.
409 Conflict	LABEL_LIMIT_REACHED	Maximum number of labels per resource reached.
404 Not Found	STORAGE_NOT_FOUND	The storage does not exist.
404 Not Found	HOST_NOT_FOUND	The host does not exist.
404 Not Found	ZONE_NOT_FOUND	The zone does not exist.
409 Conflict	CDROM_DEVICE_IN_USE	The request has multiple storage_device blocks that attach storages as a CD-ROM. Only one CD-ROM device can be attached per server.
409 Conflict	DEVICE_ADDRESS_IN_USE	The request has multiple storage_device blocks attached to the same device address.
409 Conflict	IP_ADDRESS_RESOURCES_UNAVAILABLE	There were not enough IP addresses available in the specified zone to create the requested server.
409 Conflict	MULTIPLE_TEMPLATES	The request has multiple storage_device blocks referring to templates. Only one storage template can be used to create a server.
409 Conflict	PUBLIC_STORAGE_ATTACH	Attaching a storage of access type public is not allowed. See Storage access types.
409 Conflict	SERVER_RESOURCES_UNAVAILABLE	There are not enough server resources available in the specified zone to create the requested server.
409 Conflict	STORAGE_ATTACHED_AS_CDROM	A storage resource to be attached as a disk is already attached to some server as a CD-ROM.
409 Conflict	STORAGE_ATTACHED_AS_DISK	A storage resource to be attached as a CD-ROM is already attached to some server as a disk.
409 Conflict	STORAGE_DEVICE_LIMIT_REACHED	The request contained more than four storage_device blocks.
409 Conflict	STORAGE_IN_USE	The request has multiple storage_device blocks referring to the same storage resource.
409 Conflict	STORAGE_RESOURCES_UNAVAILABLE	There are not enough storage resources available in the specified zone to create the requested storages.
409 Conflict	STORAGE_STATE_ILLEGAL	The storage is in a state in which it cannot be used. See Storage states.
409 Conflict	STORAGE_TYPE_ILLEGAL	The type of the storage to be attached is illegal. Attaching a cdrom or a template as a disk is not possible. See Storage types.
409 Conflict	STORAGE_TIER_ILLEGAL	The tier of the storage to be attached is illegal for the configuration. See Storage tiers.
409 Conflict	ZONE_MISMATCH	The storage is located in a different zone than the one the server is created in.
409 Conflict	INVALID_USERNAME	The specified `username` is a reserved username in operating system.
409 Conflict	SERVER_CREATING_LIMIT_REACHED	There are too many servers simultaneously being created.
409 Conflict	TOO_MANY_BOOT_DISKS	Too many boot disks: Only one storage can have boot_disk defined.
409 Conflict	WINDOWS_NOT_AVAILABLE	Windows servers cannot be created while in trial mode.
409 Conflict	MS_LMA_REQUIRED	Creation of Windows servers requires acceptance of the Microsoft License Mobility Agreement.
409 Conflict	BACKUP_RULE_CONFLICT	The backup rule of a storage conflicts with the simple backup rule of the server.
409 Conflict	CAN_NOT_CREATE_PASSWORD_FOR_THE_SELECTED_DISTRIBUTION	The attribute create_password cannot be yes for the selected distribution. Please, use SSH keys instead.
409 Conflict	METADATA_DISABLED_ON_CLOUD-INIT	Metadata cannot be disabled when creating a server from a cloud-init template.
409 Conflict	SERVER_RESOURCES_UNAVAILABLE_FOR_STRICT_AA	Conditions for strict anti-affinity policy cannot currently be met. Please try again later or remove the server from the server group.

Rebuild server

The server's operating system can be re-installed or changed to another without losing the server's IP addresses or other resources. The server must be in stopped state before the rebuild can be started.

Choose the storage to be rebuilt by setting its UUID as a value for detach_disk attribute and the new OS will be installed on it. The detached storage can be deleted by setting delete_detached_disk to yes. The attribute clone_source is the UUID of a public template to be used for the rebuild. You can get the list of public templates by using the List storages endpoint. The new storage can be encrypted by setting encrypted to yes.

The server will be in maintenance state during the rebuild process. After the rebuild is done, the server state will be changed back to stopped state.

Request

POST /1.3/server/{uuid}/rebuild HTTP/1.1

{
  "server_rebuild": {
    "storage_title": "new encrypted storage",
    "clone_source": "01000000-0000-4000-8000-000020050100",
    "detach_disk": "0169b4f8-051c-4a86-9484-f5b798249949",
    "delete_detached_disk": "yes",
    "password_delivery": "email",
    "encrypted": "yes",
    "login_user": {
      "create_password": 0,
      "username": "foobar",
      "ssh_keys": {
        "ssh_key": [
          "ssh-ed25519 ..."
        ]
      }
    }
  }
}

Attributes

Attributes	Accepted values	Default value	Required	Description
storage_title	0-255 characters		no	A short, informational description for the storage.
clone_source	A valid storage UUID		yes	The UUID of the storage device to be used as a source for the rebuild.
detach_disk	A valid storage UUID		no	The UUID of the storage device to be detached from the server.
delete_detached_disk	yes / no	no	no	If set to "yes", the detached storage will be deleted.
password_delivery	none / email / sms	email	no	The delivery method for the server’s root password.
encrypted	yes / no	no	no	If set to "yes", the new storage will be encrypted.
login_user	One valid `login_user` block		no	Define login account and SSH keys
create_password	yes / no	no	no	If set to "yes", a one-time password will be created. If `ssh_keys` is set this defaults to "no". This option is disabled on cloud-init templates.
username	Valid username	root	no	If set to other than "root", normal user with sudo privileges is created
ssh_keys	1-32 `ssh_key` attributes		no	Each `ssh_key` child attribute defines one SSH-key in OpenSSH format. Requires `create_password` is set to "no" or not provided. This option is required for cloud-init templates

Normal response

HTTP/1.1 202 Accepted

{
  "server": {
    "boot_order": "disk",
    "core_number": "1",
    "created": 1716400530,
    "firewall": "off",
    "hostname": "my-awesome-server",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.10.15.1",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "150.127.16.103",
          "family": "IPv4",
          "part_of_plan": "yes"
        }
      ]
    },
    "labels": {
      "label": []
    },
    "license": 0,
    "memory_amount": "1024",
    "metadata": "yes",
    "networking": {
      "interfaces": {
        "interface": [
          {
            "bootable": "no",
            "index": 1,
            "ip_addresses": {
              "ip_address": [
                {
                  "address": "150.127.16.103",
                  "dhcp_provided": "yes",
                  "family": "IPv4",
                  "floating": "no"
                }
              ]
            },
            "mac": "de:10:ff:ff:17:79",
            "network": "03030473-8e9a-4f5f-bffe-b3cffe378a28",
            "source_ip_filtering": "yes",
            "type": "public"
          },
          {
            "bootable": "no",
            "index": 2,
            "ip_addresses": {
              "ip_address": [
                {
                  "address": "10.10.15.1",
                  "dhcp_provided": "yes",
                  "family": "IPv4",
                  "floating": "no"
                }
              ]
            },
            "mac": "de:10:ff:ff:17:78",
            "network": "039bd564-c991-4fdd-bedd-37e936fab099",
            "source_ip_filtering": "yes",
            "type": "utility"
          }
        ]
      }
    },
    "nic_model": "virtio",
    "plan": "1xCPU-1GB",
    "plan_ipv4_bytes": "0",
    "plan_ipv6_bytes": "0",
    "remote_access_enabled": "no",
    "remote_access_password": "osd9xRqufdlqwe_1481-7",
    "remote_access_type": "vnc",
    "server_group": null,
    "simple_backup": "no",
    "state": "maintenance",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "0",
          "labels": [
            {
              "key": "_os_architecture",
              "value": "64"
            },
            {
              "key": "_os_brand_name",
              "value": "Debian"
            },
            {
              "key": "_os_brand_version",
              "value": "10.1"
            },
            {
              "key": "_os_main_category",
              "value": "Linux"
            },
            {
              "key": "_os_type",
              "value": "debian"
            },
            {
              "key": "_template_uuid",
              "value": "01000000-0000-4000-8000-000020050100"
            }
          ],
          "part_of_plan": "yes",
          "storage": "0117aae1-b8a9-4aee-affe-89771922cabf",
          "storage_encrypted": "yes",
          "storage_size": 25,
          "storage_tier": "maxiops",
          "storage_title": "my new re-installed os",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "my awesome server",
    "uuid": "00b5d217-3aa8-4820-8b6a-aef77f8e84f5",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status	Error code	Description
400	STORAGE_INVALID	The storage UUID is invalid.
400	INVALID_USER_DATA	Invalid user data.
400	INCORRECT_ENCRYPTED	Attribute encrypted must be 0 or 1.
400	INCORRECT_PASSWORD_DELIVERY	Incorrect password delivery.
400	INVALID_STORAGE_TITLE	Invalid storage title.
409	SERVER_STATE_ILLEGAL	Server state is illegal.
409	STORAGE_ILLEGAL	Source storage is not a template storage.
409	STORAGE_NOT_FOUND	Storage not found.
409	INVALID_STORAGE_TYPE	Invalid storage type.
409	STORAGE_ATTACH_REQUIRED	Storage attach required.
409	STORAGE_DETACH_REQUIRED	A storage to be detached is required.
409	CLONE_STORAGE_TOO_LARGE	The clone source storage is larger than the detach storage.
409	STORAGE_ILLEGAL	Source storage is not a public template storage.
409	STORAGE_ENCRYPTION_REQUIRED	Storage encryption required.
409	WINDOWS_NOT_AVAILABLE	Cannot create Windows servers in trial mode.
409	MS_LMA_REQUIRED	Microsoft License Mobility Agreement required.
400	CREATE_PASSWORD_INVALID	Create password invalid.
400	CAN_NOT_CREATE_PASSWORD_FOR_THE_SELECTED_DISTRIBUTION	Cannot create password for the selected distribution.

Start server

Starts a stopped server. The server state must be stopped.

Request

POST /1.3/server/{uuid}/start HTTP/1.1

{
  "server": {
    "host": 8055964291
  }
}

Attributes

Attributes	Accepted values	Default value	Required	Description
avoid_host	A valid host id		no	Use this to make sure VMs do not reside on specific host. Refers to value from host -attribute. Useful when building HA-environments.
host	A valid host id		no	Use this to start the VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts.
start_type	async, sync	sync	no	Define server start type. With `async`, you need to poll separately when your server is in `started` state.

Normal response

HTTP/1.1 200 OK

{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "labels": {
      "label": []
    },
    "license": 0,
    "memory_amount": "4096",
    "nic_model": "virtio",
    "plan": "2xCPU-4GB",
    "plan_ipv4_bytes": "435376546",
    "plan_ipv6_bytes": "0",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "plart_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": "10",
          "storage_tier": "maxiops",
          "storage_title": "Debian from a template",
          "type": "disk",
          "boot_disk": "0"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "remote_access_enabled": "no",
    "remote_access_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
404 Not Found	HOST_NOT_FOUND	The host does not exist.
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	HOST_FORBIDDEN	The specified host is not available for the current account.
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.
403 Forbidden	SERVER_CORE_LIMIT_REACHED	Server core account quota limit reached.
403 Forbidden	SERVER_MEMORY_LIMIT_REACHED	Server memory account quota limit reached.
403 Forbidden	HDD_STORAGE_LIMIT_REACHED	Archive storage account quota limit reached.
403 Forbidden	STANDARD_STORAGE_LIMIT_REACHED	Standard storage account quota limit reached.
403 Forbidden	MAXIOPS_STORAGE_LIMIT_REACHED	MaxIOPS storage account quota limit reached.
403 Forbidden	SERVER_IP_LIMIT_REACHED	Server IP account quota limit reached.
403 Forbidden	NETWORK_LIMIT_REACHED	Network account quota limit reached.
403 Forbidden	DETACHED_FLOATING_IP_LIMIT_REACHED	Detached floating IP account quota limit reached.
403 Forbidden	NETWORK_PEERING_LIMIT_REACHED	Network peering account quota limit reached.
409 Conflict	LABEL_LIMIT_REACHED	Maximum number of labels per resource reached.
409 Conflict	NO_STORAGES_ATTACHED	There are no storage devices currently attached to the server. A server cannot be started with no storage devices.
409 Conflict	SERVER_RESOURCES_UNAVAILABLE	There are not enough server resources available in the specified zone to start the requested server.
409 Conflict	SERVER_STATE_ILLEGAL	The server is in a state in which it cannot be used. See Server states.

Stop server

Stops a started server.

The server state must be started.

Stopping a server can be done in three different ways:

by hard stopping, or,
soft stopping with a timeout, or,
soft stopping without a timeout.

Hard stopping a server is the equivalent of physically unplugging the server.

Soft stopping a server sends an ACPI signal to the server. If a timeout is set, the timeout period has passed and the server is still running, a hard stop is performed. If no timeout is set, only the ACPI signal is sent.

Request

POST /1.3/server/{uuid}/stop HTTP/1.1

{
  "stop_server": {
    "stop_type": "soft",
    "timeout": "60"
  }
}

Attributes

Attributes	Accepted values	Default value	Required	Description
stop_type	soft / hard	soft	no	Type of stop operation performed on the server.
timeout	1-600		no	The stop timeout in seconds.

Normal response

HTTP/1.1 200 OK

{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": [
      {
        "access": "utility",
        "address": "10.0.0.0",
        "family": "IPv4"
      },
      {
        "access": "public",
        "address": "x.x.x.x",
        "family": "IPv4"
      },
      {
        "access": "public",
        "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
        "family": "IPv6"
      }
    ],
    "labels": {
      "label": []
    },
    "license": 0,
    "memory_amount": "4096",
    "nic_model": "virtio",
    "plan": "2xCPU-4GB",
    "plan_ipv4_bytes": "34543646754",
    "plan_ipv6_bytes": "242432",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": "10",
          "storage_tier": "maxiops",
          "storage_title": "Debian from a template",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "remote_access_enabled": "no",
    "remote_access_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Note: the server's state is still started after the operation. The state will change to stopped once the server has shut down.

Error responses

HTTP status	Error code	Description
400 Bad Request	STOP_TYPE_INVALID	The attribute stop_type has an invalid value.
400 Bad Request	TIMEOUT_INVALID	The attribute timeout has an invalid value.
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
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	SERVER_STATE_ILLEGAL	The server is in a state in which it cannot be used. See Server states.

Restart server

Stops and starts a server. The server state must be started.

A restart can be done in two ways:

by hard stopping, or,
by soft stopping with a timeout.

Hard stopping the server in the equivalent of power cycling the server. The server is then started.

Soft stopping sends an ACPI signal to the server. The API then waits for the server to shut down before starting it. If the server has not shut down within the timeout period, the action indicated by timeout_action is performed. A value of destroy hard stops the server which is then started. A value of ignore stops the operation and the server will not be started.

Request

POST /1.3/server/{uuid}/restart HTTP/1.1

{
  "restart_server": {
    "stop_type": "soft",
    "timeout": "60",
    "timeout_action": "destroy"
  }
}

Attributes

Attributes	Accepted values	Default value	Required	Description
stop_type	soft / hard	soft	no	Restart type
timeout	1-600		yes if type is soft	Stop timeout in seconds
timeout_action	destroy / ignore	ignore	no	Action to take if timeout limit is exceeded.
host	A valid host id		no	Use this to restart the VM on a specific host. Refers to value from host -attribute. Only available for private cloud hosts.

Normal response

HTTP/1.1 200 OK

{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "labels": {
      "label": []
    },
    "license": 0,
    "memory_amount": "4096",
    "nic_model": "virtio",
    "plan": "2xCPU-4GB",
    "plan_ipv4_bytes": "34543646754",
    "plan_ipv6_bytes": "242432",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "plart_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": "10",
          "storage_tier": "maxiops",
          "storage_title": "Debian from a template",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "remote_access_enabled": "no",
    "remote_access_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	STOP_TYPE_INVALID	The attribute stop_type has an invalid value.
400 Bad Request	TIMEOUT_MISSING	The required attribute timeout is missing from the request.
400 Bad Request	TIMEOUT_INVALID	The attribute timeout has an invalid value.
400 Bad Request	TIMEOUT_ACTION_INVALID	The attribute timeout_action has an invalid value.
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
403 Forbidden	HOST_FORBIDDEN	The specified host is not available for the current account.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
404 Not Found	HOST_NOT_FOUND	The host does not exist.
409 Conflict	SERVER_STATE_ILLEGAL	The server is in a state in which it cannot be used. See Server states.

Modify server

Modifies the configuration of an existing server.

Attaching and detaching storages as well as assigning and releasing IP addresses have their own separate operations. See Attach storage, Detach storage, Assign IP address and Release IP address.

In order to change the remote_access_type attribute, or decrease core_number and memory_amount, the server state must be stopped.

Request

PUT /1.3/server/{uuid} HTTP/1.1

{
  "server": {
    "core_number": "8",
    "memory_amount": "16384",
    "plan": "custom"
  }
}

Attributes

Attribute	Accepted values	Default value	Required	Description
boot_order	disk / cdrom / network or comma separated combination	disk	no	The boot device order.
core_number	A valid combination with memory_amount		no	The number of CPU cores dedicated to the server. See List server configurations.
firewall	on / off	on	no	The state of the server firewall rules.
hostname	A valid hostname		no	A valid hostname, e.g. host.example.com. The maximum length is 128 characters.
labels	0-255 `label` blocks		no	Labels contain key-value pairs defined in `label` block above to classify the server.
memory_amount	A valid combination with core_number		no	The amount of main memory in megabytes. See List server configurations.
metadata	yes / no	no	no	HTTP-accessible metadata service for the server. See our tutorial for more information.
nic_model	"e1000 / virtio / rtl8139"	virtio	no	The model of the server's network interfaces. It is recommended to use the default unless there are specific reasons to choose otherwise; others may be subject to bandwidth limitations.
plan	A valid plan name returned with plan listing, or `custom`	`custom`	no	The pricing plan used. If a plan is selected, the `core_number` and `memory_amount` must match the plan if they are present.
simple_backup	HHMM,{daily\|dailies\|weeklies\|monthlies} / no	account default	no	Simple backup time in UTC, followed by daily, dailies, weeklies, or monthlies option separated by comma, or no when disabled.
title	0-255 characters		no	A short, informational description.
timezone	A valid timezone identifier		no	A timezone identifier, e.g. Europe/Helsinki. See Timezones.
video_model	vga / cirrus	vga	no	The model of the server's video interface.
remote_access_type	vnc	vnc	no	The remote access type.
remote_access_enabled	yes / no	no	no	Is the remote access enabled.
remote_access_password	8 characters of a-z, A-Z and 0-9.		no	The remote access password.

Normal response

HTTP/1.1 202 Accepted

{
  "server": {
    "boot_order": "disk",
    "core_number": "8",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "utility",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "labels": {
      "label": []
    },
    "license": 0,
    "memory_amount": "16384",
    "nic_model": "virtio",
    "plan": "custom",
    "plan_ipv4_bytes": "0",
    "plan_ipv6_bytes": "0",
    "simple_backup": "no",
    "state": "stopped",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "plart_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": "10",
          "storage_tier": "maxiops",
          "storage_title": "Debian from a template",
          "type": "disk",
          "boot_disk": "0"
        }
      ]
    },
    "tags": {
      "tag": []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "remote_access_enabled": "no",
    "remote_access_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	BOOT_ORDER_INVALID	The attribute boot_order has an invalid value.
400 Bad Request	CORE_MEMORY_UNSUPPORTED	The combination of core_number and memory_amount is not supported. See List server configurations.
400 Bad Request	CORE_NUMBER_INVALID	The attribute core_number has an invalid value.
400 Bad Request	FIREWALL_INVALID	The attribute firewall has an invalid value.
400 Bad Request	HOSTNAME_INVALID	The attribute hostname has an invalid value.
400 Bad Request	MEMORY_AMOUNT_INVALID	The attribute memory_amount has an invalid value.
400 Bad Request	NIC_MODEL_INVALID	The attribute nic_model has an invalid value.
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
400 Bad Request	SIMPLE_BACKUP_INVALID	The attribute simple_backup has an invalid value.
400 Bad Request	TITLE_INVALID	The attribute title has an invalid value.
400 Bad Request	TIMEZONE_INVALID	The attribute timezone has an invalid value.
400 Bad Request	VIDEO_MODEL_INVALID	The attribute video_model has an invalid value.
400 Bad Request	VNC_INVALID	The attribute remote_access_type has an invalid value.
400 Bad Request	VNC_PASSWORD_INVALID	The attribute remote_access_password has an invalid value.
400 Bad Request	FAILED_TO_ADD_MEMORY	Failed to hot resize memory.
400 Bad Request	INVALID_LABEL_KEY	The attribute `key` in a label block has an invalid value.
400 Bad Request	INVALID_LABEL_VALUE	The attribute `value` in a label block has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
403 Forbidden	PLAN_CORE_NUMBER_ILLEGAL	The specified `core_number` does not match the selected plan.
403 Forbidden	PLAN_MEMORY_AMOUNT_ILLEGAL	The specified `memory_amount` does not match the selected plan.
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.
403 Forbidden	SERVER_CORE_LIMIT_REACHED	Server core account quota limit reached.
403 Forbidden	SERVER_MEMORY_LIMIT_REACHED	Server memory account quota limit reached.
403 Forbidden	HDD_STORAGE_LIMIT_REACHED	Archive storage account quota limit reached.
403 Forbidden	STANDARD_STORAGE_LIMIT_REACHED	Standard storage account quota limit reached.
403 Forbidden	MAXIOPS_STORAGE_LIMIT_REACHED	MaxIOPS storage account quota limit reached.
403 Forbidden	SERVER_IP_LIMIT_REACHED	Server IP account quota limit reached.
403 Forbidden	NETWORK_LIMIT_REACHED	Network account quota limit reached.
403 Forbidden	DETACHED_FLOATING_IP_LIMIT_REACHED	Detached floating IP account quota limit reached.
403 Forbidden	NETWORK_PEERING_LIMIT_REACHED	Network peering account quota limit reached.
409 Conflict	LABEL_LIMIT_REACHED	Maximum number of labels per resource reached.
404 Not Found	SERVER_NOT_FOUND	The server 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	BACKUP_RULE_CONFLICT	The backup rule of a storage conflicts with the simple backup rule of the server.
409 Conflict	HOT_RESIZE_NOT_ENABLED	Hot resize of CPU or memory is not enabled on the server. Please, stop and restart the server to enable hot resize.
409 Conflict	HOT_RESIZE_UNAVAILABLE	Hot resize is currently unavailable for this server, please shutdown the serverl to resize.
409 Conflict	NO_AVAILABLE_MEMORY_SLOTS	No available memory slots. Free memory slots by shutting down the server and restarting it again

Cancel server operation

Cancels a running server operation.

A running server operation can be cancelled if it is e.g. taking too much time or was not intentional. For example, to cancel cloning a server, invoke this method on the new server in progress of being created.

The server state must be 'maintenance'.

Request

POST /1.3/server/{uuid}/cancel HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
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	SERVER_STATE_ILLEGAL	The server is in a state in which operations can not be cancelled.
409 Conflict	UNABLE_TO_CANCEL	The cancellation was not successful.

Delete server

Deletes a server.

The server state must be stopped. Storage devices attached to the server are automatically deleted if storages is truthy and backups to those storages will be handled by backups. Kept storages can be reattached to other servers. IP addresses used by the server are released.

Request

DELETE /1.3/server/{uuid}?storages={storages}&backups={backups} HTTP/1.1

Query parameters

Parameter	Description	Accepted values	Default value
storages	Controls what to do with storages related to the deleted server.	0, 1, true, false	0
backups	If storages are to be deleted, controls what to do with backups related to the storages.	keep, keep_latest, delete	keep

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
400 Bad Request	REQUEST_INVALID	Deleting backups without deleting storages is not allowed.
400 Bad Request	STORAGE_DELETION_POLICY_INVALID	The deletion policy for storages is invalid.
400 Bad Request	BACKUP_DELETION_POLICY_INVALID	The deletion policy for backups is invalid. Allowed values are 'keep', 'keep_latest' and 'delete'.
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	SERVER_STATE_ILLEGAL	The server is in a state in which it cannot be used. See Server states.
409 Conflict	STORAGE_STATE_ILLEGAL	One of the attached storages is in a state in which it cannot be used. See Storage states.

Metadata service

A server can use the UpCloud metadata service to query information about itself. See our tutorial for more information.

Metadata service can be used for deployment automation by allowing initialization scripts to utilise server-specific information for configuring software and applications.

Metadata is available per server basis when enabled at server creation or if enabled at a later time by modifying the server, and only from within the server itself. The server can query the metadata HTTP API available at the IP address 169.254.169.254 to list either the full information in JSON or per single metadata field available as a directory tree.

~# curl http://169.254.169.254/metadata/v1/
cloud_name
instance_id
hostname
platform
subplatform
public_keys
region
network/
storage/
tags
user_data
vendor_data

~# curl http://169.254.169.254/metadata/v1/storage
disks/

~# curl http://169.254.169.254/metadata/v1/storage/disks
1

~# curl http://169.254.169.254/metadata/v1/storage/disks/1
id
serial
size
type
tier

~# curl http://169.254.169.254/metadata/v1/storage/disks/1/id
0187b8c5-7220-4c90-9026-047dff8be0b3

~# curl http://169.254.169.254/metadata/v1.json
{
  "cloud_name": "upcloud",
  "instance_id": "00bf9504-a4cb-4839-88ff-124a2c95e169",
  "hostname": "metadata.example.com",
  "platform": "servers",
  "subplatform": "metadata (http://169.254.169.254)",
  "public_keys": [
    "ssh-rsa AAAAB[...]ud1Cw== [email protected]"
  ],
  "region": "de-fra1",
  "network": {
    "interfaces": [
      {
        "index": 1,
        "ip_addresses": [
          {
            "address": "94.237.90.209",
            "dhcp": true,
            "dns": [
              "94.237.127.9",
              "94.237.40.9"
            ],
            "family": "IPv4",
            "floating": false,
            "gateway": "94.237.90.1",
            "network": "94.237.90.0/24"
          }
        ],
        "mac": "de:ad:be:ef:3f:c5",
        "network_id": "03030473-8e9d-4f4f-bcfe-b2c300391a07",
        "type": "public"
      },
      {
        "index": 2,
        "ip_addresses": [
          {
            "address": "10.199.12.11",
            "dhcp": true,
            "dns": null,
            "family": "IPv4",
            "floating": false,
            "gateway": "10.199.12.1",
            "network": "10.199.12.0/24"
          }
        ],
        "mac": "de:ad:be:ef:9f:ff",
        "network_id": "03318153-4e70-4ba5-8e74-69538582188d",
        "type": "utility"
      },
      {
        "index": 3,
        "ip_addresses": [
          {
            "address": "2a04:3540:1000:811:9809:21ff:fe8b:5962",
            "dhcp": true,
            "dns": [
              "2a04:3540:53::1",
              "2a04:3544:53::1"
            ],
            "family": "IPv6",
            "floating": false,
            "gateway": "2a04:3540:1000:811::1",
            "network": "2a04:3540:1000:811::/64"
          }
        ],
        "mac": "9a:09:21:8b:59:62",
        "network_id": "03000000-0000-4000-8002-000000000000",
        "type": "public"
      }
    ],
    "dns": [
      "94.237.127.9",
      "94.237.40.9"
    ]
  },
  "storage": {
    "disks": [
      {
        "id": "0187b8c5-7220-4c90-9026-047dff8be0b3",
        "serial": "0187b8c572204c909026",
        "size": 25,
        "type": "disk",
        "tier": "maxiops"
      }
    ]
  },
  "tags": [
    "dev",
    "metadata"
  ],
  "user_data": "apt-get update && apt-get -y upgrade",
  "vendor_data": ""
}

Server Groups

Servers can be bundled into a server group. These groups may have an anti-affinity policy in use. The policy can be strict, best-effort, or no policy.

Strict policy doesn't allow servers in the same server group to be on the same host
Best-effort policy tries to put servers on different hosts, but this is not guaranteed
No policy doesn't affect server host affinity

A server can belong to only one group. It must be removed from the group if it is to be moved to another group.

The status of server's anti-affinity can be checked via group info or group list endpoints. If the status is met, the server is the only one on that server host. If the status is unmet, the server is sharing the same server host with another server from the same anti-affinity group.

It is also possible to filter shown server groups with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only server groups that match all labels are returned. Label keys are matched case insensitively.

List all server groups

GET /1.3/server-group

Normal response

HTTP/1.1 200 OK

{
  "server_groups": {
    "server_group": [
      {
        "anti_affinity": "yes",
        "anti_affinity_status": [
          {
            "uuid": "0016dadf-eba4-4331-bd34-a361841f7af1",
            "status": "met"
          },
          {
            "uuid": "00c77bbe-fc0e-436f-a753-37f5b5b76270",
            "status": "met"
          }
        ],
        "labels": {
          "label": [
            {
              "key": "foo",
              "value": "bar"
            }
          ]
        },
        "servers": {
          "server": [
            "0016dadf-eba4-4331-bd34-a361841f7af2",
            "00c77bbe-fc0e-436f-a753-37f5b5b76271"
          ]
        },
        "title": "nameserver group",
        "uuid": "0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0"
      },
      {
        "anti_affinity": "no",
        "anti_affinity_status": null,
        "labels": {
          "label": [
            {
              "key": "foo",
              "value": "bar"
            }
          ]
        },
        "servers": {
          "server": [
            "001789da-3aa4-4431-bd34-b4ad841f23e2"
          ]
        },
        "title": "my group",
        "uuid": "0bebfe54-7532-4ca4-b8c0-0fa294ea9b7a"
      }
    ]
  }
}

Show server group details

GET /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0

Normal response

HTTP/1.1 200 OK

{
  "server_group": {
    "anti_affinity": "yes",
    "anti_affinity_status": [
      {
        "uuid": "0016dadf-eba4-4331-bd34-a361841f7af1",
        "status": "met"
      },
      {
        "uuid": "00c77bbe-fc0e-436f-a753-37f5b5b76270",
        "status": "met"
      }
    ],
    "labels": {
      "label": [
        {
          "key": "foo",
          "value": "bar"
        }
      ]
    },
    "servers": {
      "server": [
        "0016dadf-eba4-4331-bd34-a361841f7af2",
        "00c77bbe-fc0e-436f-a753-37f5b5b76271"
      ]
    },
    "title": "nameserver group",
    "uuid": "0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0"
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.

List servers in a group

GET /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0/servers

Normal response

HTTP/1.1 200 OK

{
  "servers": {
    "server": [
      "0016dadf-eba4-4331-bd34-a361841f7af2",
      "00c77bbe-fc0e-436f-a753-37f5b5b76271"
    ]
  }
}

Error responses

HTTP status	Error code	Description
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.

Create a new server group

POST /1.3/server-group

{
  "server_group": {
    "title": "My brand new server group",
    "servers": {
      "server": [
        "00e2dc05-379d-6b90-a354-e5c3f9293918",
        "00451e12-46ee-41a0-8a52-1aff9039298a",
        "00651e23-44ff-41a0-9a82-2aff9039298b"
      ]
    },
    "labels": {
      "label": [
        {
          "key": "foo",
          "value": "bar"
        }
      ]
    },
    "anti_affinity": "yes"
  }
}

Normal response

HTTP/1.1 200 OK

Attributes

Attributes	Accepted values	Default value	Required	Description
title	0-255 characters		no	Server group title.
server	Server UUID or empty		no	Server UUID
anti_affinity	strict / yes / no	no	no	Anti-affinity policy. Strict, yes (best-effort), no
(label) key	2-32 printable ASCII characters (range 0x20-0x7E), must not start with `_`		no	Label key
(label) value	0-255 characters		no	Label value

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
400 Bad Request	DUPLICATE_LABEL_KEYS	Label keys must be unique.
400 Bad Request	INVALID_LABEL_KEY	Invalid label key in query parameters.
400 Bad Request	INVALID_LABEL_VALUE	Invalid label value in query parameters.
409 Conflict	STRICT_ANTI_AFFINITY_NOT_MET	Can't create a group. Strict anti-affinity is not met

Modify server group

PATCH /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0

{
  "server_group": {
    "title": "New fancy title for the group",
    "servers": {
      "server": [
        "00e2dc05-379d-6b90-a354-e5c3f9293918",
        "00451e12-46ee-41a0-8a52-1aff9039298a"
      ]
    },
    "anti_affinity": "no"
  }
}

Normal response

HTTP/1.1 200 OK

Attributes

Attributes	Accepted values	Default value	Required	Description
title	0-255 characters		no	Server group title
server	Server UUID or empty		no	Server UUID
anti_affinity	strict / yes / no /	no	no	Anti-affinity policy. Strict, yes (best-effort), no
(label) key	2-32 printable ASCII characters (range 0x20-0x7E), must not start with `_`		no	Label key
(label) value	0-255 characters		no	Label value

Labels can include specific service labels that cannot be modified. These always start with _ and do not conflict with normal labels.

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.
400 Bad Request	DUPLICATE_LABEL_KEYS	Label keys must be unique.
400 Bad Request	INVALID_LABEL_KEY	Invalid label key in query parameters.
400 Bad Request	INVALID_LABEL_VALUE	Invalid label value in query parameters.
409 Conflict	ALREADY_IN_SERVER_GROUP	The server (server uuid) is already in a server group (group uuid)
409 Conflict	STRICT_ANTI_AFFINITY_NOT_MET	Can't modify the group. Strict anti-affinity is not met

Delete server group

DELETE /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status	Error code	Description
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.

Add a new server to a server group

POST /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0/servers

{
  "server": {
    "uuid": "00235adf-add4-66f1-ef34-e331516bb6a1"
  }
}

Normal response

HTTP/1.1 204 No Content

Attributes

Attributes	Accepted values	Default value	Required	Description
server	Server UUID or empty		yes	Server UUID

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.
409 Conflict	ALREADY_IN_SERVER_GROUP	The server (server uuid) is already in a server group (group uuid)
409 Conflict	STRICT_ANTI_AFFINITY_NOT_MET	Can't add server to the group. Strict anti-affinity is not met

Remove server from a server group

DELETE /1.3/server-group/0b3d85b4-b3be-46ca-a1e2-3b5d30d60ab0/servers/00235adf-add4-66f1-ef34-e331516bb6a1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status	Error code	Description
400 Bad Request	SERVER_INVALID	The server UUID has an invalid value.
403 Forbidden	SERVER_FORBIDDEN	The server exists, but is owned by another account.
404 Not Found	SERVER_NOT_FOUND	The server does not exist.
400 Bad Request	GROUP_INVALID	The server group UUID has an invalid value.
403 Forbidden	GROUP_FORBIDDEN	The server group exists, but is owned by another account.
404 Not Found	GROUP_NOT_FOUND	The server group does not exist.