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