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

All UpCloud servers have dedicated virtual CPU cores in order to provide maximal and predictable performance.

Request

GET /1.2/server_size

Normal response

HTTP/1.0 200 OK
{
  "server_sizes": {
    "server_size": [
      {
        "core_number": "1",
        "memory_amount": "512"
      },
      {
        "core_number": "1",
        "memory_amount": "768"
      },
      ... many more combinations ...
      {
        "core_number": "10",
        "memory_amount": "65024"
      },
      {
        "core_number": "10",
        "memory_amount": "65536"
      }
    ]
  }
}

List servers

Returns a list of all servers associated with the current account.

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.

Request

GET /1.2/server

Normal response

HTTP/1.0 200 OK
{
  "servers": {
    "server": [
      {
        "core_number": "1",
        "hostname": "fi.example.com",
        "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",
        "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.2/server/00798b85-efdc-41ca-8021-f6ef457b8531

Normal response

HTTP/1.0 200 OK
{
  "server": {
    "boot_order": "disk",
    "core_number": "0",
    "firewall": "on",
    "host" : 7653311107,
    "hostname": "server1.example.com",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "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",
    "nic_model": "virtio",
    "plan" : "1xCPU-2GB",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan" : "yes",
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_size": 20,
          "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",
    "vnc" : "on",
    "vnc_host" : "fi-hel1.vnc.upcloud.com",
    "vnc_password": "aabbccdd",
    "vnc_port": "00000",
    "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 accessible using VNC. A VNC password is generated and returned in the output of the create server operation.

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.2/storage/template

See List storages for more information on storage resource listings.

When creating a 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 as soon as possible.

With Linux templates it is possible to define one or more public SSH keys which can be used for passwordless login with matching private keys.

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 maxiops storage. Private templates can be used in same way as public templates. See Templatize storage for more information.

Request

POST /1.2/server
{
  "server": {
    "zone": "fi-hel1",
    "title": "My Debian server",
    "hostname": "debian.example.com",
    "plan": "2xCPU-4GB",
    "storage_devices": {
      "storage_device": [
        {
          "action": "clone",
          "storage": "01000000-0000-4000-8000-000020030100",
          "title": "Debian from a template",
          "size": 50,
          "tier": "maxiops"
        }
      ]
    },
    "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.2/server
{
  "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"
        }
      ]
    }
  }
}

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.2/storage/cdrom

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

Request

POST /1.2/server
{
  "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"
        }
      ]
    },
    "ip_addresses": {
      "ip_address": [
        { "access": "private", "family": "IPv4" },
        { "access": "public", "family": "IPv4" },
        { "access": "public", "family": "IPv6" }
      ]
    }
  }
}

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.
boot_order disk / cdrom / disk,cdrom / cdrom,disk disk no The storage device boot 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.
ip_addresses 1-10 ip_address blocks. One IPv4 and one IPv6 address block no The ip_addresses block contains ip_address blocks that define the network interfaces.
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.
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-8 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-64 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.
vnc on / off off no Is VNC service enabled.
vnc_password 8-32 characters of a-z, A-Z and 0-9. randomly generated no The VNC remote access password.
zone A valid zone identifier yes The zone in which the server will be hosted, e.g. fi-hel1. See Zones.

The storage_devices block may contain 1-8 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-7]] / virtio[:[0-7]] The next available 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 hdd / maxiops hdd No The storage tier to use. See [Storage tiers].
title 0-64 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.

The ip_addresses block may contain 1-11 IP addresses. Each block can have the following 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 for new address. Private addresses can be only IPv4.

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 "no", user can login only with SSH key
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

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

Normal response

HTTP/1.0 202 Accepted
{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "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",
    "state": "maintenance",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan" : "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": 1,
          "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",
    "vnc" : "off",
    "vnc_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 FIREWALL_INVALID The attribute firewall has an invalid value.
400 Bad Request CORE_NUMBER_INVALID The attribute core_number 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 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 VIDEO_MODEL_INVALID The attribute video_model has an invalid value.
400 Bad Request VNC_INVALID The attribute vnc has an invalid value.
400 Bad Request VNC_PASSWORD_INVALID The attribute vnc_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 USER_DATA_INVALID The attribute user_data 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 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.
404 Not Found STORAGE_NOT_FOUND The storage 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 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.

Start server

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

Request

POST /1.2/server/00c78863-db86-44ea-af70-d6edc4d162bf/start

Normal response

HTTP/1.0 200 OK
{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "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",
    "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_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",
    "vnc" : "off",
    "vnc_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.
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.
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.2/server/00c78863-db86-44ea-af70-d6edc4d162bf/stop
{
  "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.0 200 OK
{
  "server" : {
    "boot_order" : "disk",
    "core_number" : "2",
    "firewall" : "on",
    "hostname" : "debian.example.com",
    "host" : 8055964291,
    "ip_addresses" : [
      {
        "access" : "private",
        "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",
    "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_title" : "Debian from a template",
          "type" : "disk"
        }
      ]
    },
    "tags" : {
      "tag" : []
    },
    "timezone" : "UTC",
    "title" : "My Debian server",
    "uuid" : "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model" : "cirrus",
    "vnc: " : "off",
    "vnc_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.2/server/00c78863-db86-44ea-af70-d6edc4d162bf/restart
{
  "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.

Normal response

HTTP/1.0 200 OK
{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "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",
    "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_title": "Debian from a template",
          "type": "disk"
        }
      ]
    },
    "tags" : {
      "tag" : []
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "vnc" : "off",
    "vnc_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.
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.

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 core_number or memory_amount attributes, the server state must be stopped.

Request

PUT /1.2/server/00c78863-db86-44ea-af70-d6edc4d162bf
{
  "server" : {
    "core_number": "8",
    "memory_amount": "16384",
    "plan" : "custom"
  }
}

Attributes

Attribute Accepted values Default value Required Description
boot_order disk / cdrom / disk,cdrom / cdrom,disk no The storage device boot 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.
memory_amount A valid combination with core_number no The amount of main memory in megabytes. See List server configurations.
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.
title 0-64 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.
vnc on / off off no The state of the VNC remote access service.
vnc_password 8-32 characters of a-z, A-Z and 0-9. no The VNC remote access password.

Normal response

HTTP/1.0 202 Accepted
{
  "server": {
    "boot_order": "disk",
    "core_number": "8",
    "firewall": "on",
    "hostname": "debian.example.com",
    "host": 8055964291,
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "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": "16384",
    "nic_model": "virtio",
    "plan" : "custom",
    "plan_ipv4_bytes" : "0",
    "plan_ipv6_bytes" : "0",
    "state": "stopped",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "plart_of_plan" : "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": "10",
          "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",
    "vnc" : "off",
    "vnc_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 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 vnc has an invalid value.
400 Bad Request VNC_PASSWORD_INVALID The attribute vnc_password 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.
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.

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.2/server/00c78863-db86-44ea-af70-d6edc4d162bf/cancel

Normal response

HTTP/1.0 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 detached and can be reattached to other servers. IP addresses used by the server are released.

Request

DELETE /1.2/server/00c78863-db86-44ea-af70-d6edc4d162bf

Normal response

HTTP/1.0 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 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.

Delete server and storage

The server state must be stopped. Storage devices attached to the server are automatically detached and deleted. IP addresses used by the server are released.

Request

DELETE /1.2/server/00c78863-db86-44ea-af70-d6edc4d162bf/?storages=1

Normal response

HTTP/1.0 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 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.