Server
Virtual servers are the core of ECS services. This page lists all the operations available on the servers.
Create a new server.
Very little information is needed to create a basic server, you just need:
- A Plan
- An Image or a Template
- A Region or Location
- A Label
HTTP Request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server"
}
HTTP Response
{
"status": "ok",
"action": 35,
"server": {
"name": "ec200001",
"ipv4": "",
"ipv6": "",
"plan": "ECS6",
"location": "it-fr2",
"os": "debian-12",
"status": "Booting",
"progress": 10
...
}
}
You can monitor the Action creation status to know when a server is ready or if the operation has failed.
!!! warning “Warning” Server creation can easily fail due to lack of resources, to avoid this behavior it is recommended that you to check the availability of the Plan before attempting to create a server in a given data center.
List all servers.
To list all your servers you can easily use the following endpoint:
HTTP request
GET /ecs/v2/servers
HTTP Response
{
"status": "ok",
"count":5,
"server":[
{
"name": "ec200001",
"ipv4": "127.0.0.1",
"ipv6": "fe80::1",
"group": "eg100001",
"plan": "ECS6",
"plan_size": {
"core": 12,
"ram": 24576,
"disk": 400,
"gpu": 0,
"gpu_label": "",
"host_type": "ECS"
},
"reserved_plans": [],
"is_reserved": false,
"reserved_until": "",
"support": null,
"location": "it-fr2",
"location_label": "frosinone",
"notes": "my-server",
"so": "debian-12",
"so_label": "Debian 12",
"creation_date": "2024-10-10 12:00...",
"deletion_date": null,
"active_flag": true,
"status": "Booted",
"progress": 100,
"api_version": "v4",
"user": "eCS99999",
},
...
]
}
Getting a specific server
To get only a specific server, you can add the server name to the URL as follows:
HTTP request
GET /ecs/v2/servers/{servername}
HTTP Response
{
"status": "ok",
"server": {
"name": "ec200001",
"ipv4": "127.0.0.1",
"ipv6": "fe80::1",
"group": "eg100001",
"plan": "ECS6",
"plan_size": {
"core": 12,
"ram": 24576,
"disk": 400,
"gpu": 0,
"gpu_label": "",
"host_type": "ECS"
},
"reserved_plans": [],
"is_reserved": false,
"reserved_until": "",
"support": null,
"location": "it-fr2",
"location_label": "frosinone",
"notes": "my-server",
"so": "debian-12",
"so_label": "Debian 12",
"creation_date": "2024-10-10 12:00...",
"deletion_date": null,
"active_flag": true,
"status": "Booted",
"progress": 100,
"api_version": "v4",
"user": "eCS99999",
}
}
Change server label.
If you want to change a label for a specific server, you can use the following request:
HTTP request
PUT /ecs/v2/servers/{servername}
{
"note": "my-new-server-label"
}
HTTP Response
{
"status": "ok"
}
Confidential period.
Subscribing to a reserved period is a good choice if you face challenges that require high labor intensity for medium to long periods.
By doing so, you can receive significant discounts based on the duration of the period while disabling the ability to destroy the server.
Add a Reserved Period during creation
To subscribe to a Reserved Period During Server Creation, you can add the “reserved_plan” field in your request as follows:
HTTP Request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"reserved_plan": "M24PECS6"
}
The reserved_plan field consists of:
M{plan duration}P{Plan name}
where the duration of the plan can be 3, 6, or 12 months
Add a Reserved Period on to an existing server
To add a Reserved Period on to an existing server, the following request must be used:
HTTP request
POST /api/v2/servers/{servername}/reserved
{
"reserved_plan": "M24PECS6"
}
HTTP Response
{
"reserved_plan": 50,
"reserved_month": 24,
"plan": 7,
"discount": 20,
"start_date": "2024-10-10 12:34...",
"end_date": "2026-10-10 12:34...",
"server": "ec200001"
}
You may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 400 | Invalid formula to define reserved plan: use id or MxxPxxxx (M12PECS1) | You tried to select a reserved plan without using plan id or reserved plan formula |
| 404 | Reserved plan not found | Right formula but no plan found |
| 400 | Can't add a reserved plan to a server with a different resource plan | The entered Reserved Plan is only available for a different resource plan |
| 400 | Topic 'reserved_plan' required | 'Reserved_plan' field missing in json body |
| 400 | Reserved Plans are not available for your profile | Your account is not authorized to use the Reserved Plan |
Support
Choosing a support plan for your server allows you to get help directly from our experienced engineers; several support plans are available; for more information you can consult our website.
Add a Support Plan During Creation
To add a Support Plan During Server Creation, you can add the “support” field in your request as follows:
HTTP Request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"support": "global"
}
The “support” field can be: “basic” or “global.”
To activate “proactive” support, we suggest you visit the our site and contact our offices.
Adding a support plan to an existing server
To add or modify a Support Plan to an existing server, you can use the following request:
HTTP Request
POST /ecs/v2/servers/{server-name}/support
{
"code": "global"
}
HTTP Response
{
"status": "ok",
"support": {
"support_title": "global",
"support_code": "global",
"immutable": false,
"start": "2024-10-10 17:03...",
"start": null,
"may_downgrade": false,
"weigth": 2,
"days": 30,
"cancelled": false,
"cancelled_at": null,
}
}
You can also use this endpoint to update or downgrade your support plan.
You may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 400 | You cannot edit an immutable support plan | If your support plan is immutable you cannot downgrade it |
| 400 | Support code not found | Support code not found, try another |
| 400 | You cannot downgrade a support plan, plan not yet finished... | You can downgrade the support plan only after it is finished |
Remove a support plan
To remove a support plan (and set up unmanaged support), simply use the following request:
HTTP request
DELETE /ecs/v2/servers/{server-name}/support
HTTP Response
{
"status": "ok"
}
You may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 400 | You cannot modify an immutable support plan | If your support plan is immutable, you cannot downgrade it |
| 400 | You cannot downgrade a support plan, unfinished plan... | You can downgrade the support plan only after it is finished |
Groups
Groups allow you to have a split view of your servers via the Ermes Web Panel, they can also be configured via the following API endpoints:
Info
For more information on creating groups, see the Group Page.
Add a Server to a Group during creation.
To add your server to a group during creation, you can use the “group” field:
HTTP Request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"group": "eg-000001"
}
Add an Existing Server to a Group
To add an existing server to a group, you can use the server management endpoint:
HTTP Request
PUT /ecs/v2/servers/{servername}
{
"group": "eg-000001"
}
HTTP Response
{
"status": "ok"
}
You may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 404 | group not found | Unable to find requested group |
Remove a Server from a Group
To remove a server from a group, use the following request:
HTTP request
PUT /ecs/v2/servers/{servername}
{
"group": "nogroup"
}
HTTP Response
{
"status": "ok"
}
Cloud Script
Cloud Script is a very powerful feature that allows you to run a remote script during server installation, for more information about Cloud Script go to the Cloud Script Page.
You can use a Cloud Script during server creation you can use a Temporary Script or an existing script from your library.
The 'use of the script library is strongly recommended, especially for use via API.
Temporary Script
Using a Temporary Script or “otf” means sending all the script content during the server creation request:
HTTP request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"user_customize": "#!/bin/bash\necho \"il mio script\" > /root/out.txt"
}
Script Library and environment variables.
Using the Script Library requires that a Cloud Script is already written in your Script Library;.
It can then be called during creation:
Take, for example, the following Script with id 2:
#!/bin/bash
echo "i'm $NAME, i work in $WORK !!!" > /root/presentation.txt
You can use it via:
HTTP request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"user_customize": 2,
"user_customize_env": "NAME=\"bob\"\nWORK=\"seeweb\""
}
Environment variables (user_customize_env) allow you to write the contents of the script and change only the values you need, moreover, they are treated as sensitive information and obscured as such.
Environment variables must follow this syntax to work: “VARNAME1=VARCONTENT1\nVARNAME2=VARCONTENT2...”
You may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 400 | powershell script cannot be used in linux servers | you can only use powershell scripts with windows servers |
| 400 | Invalid env variable format | check 'user_customize_env' field, remember to use '\n' |
| 400 | Cannot use relative path in user script | relative paths and home paths ex: '~/' are not supported |
Use SSH Keys.
To use authentication via SSH Keys via API, you must first register your public SSH key and use it via the following field during server creation:
HTTP request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-first-server",
"ssh_key": "my-key-label"
}
Isolation
Isolation is a very interesting feature that allows you to isolate physical hardware resources between two servers in the same datacenter.
This allows you to secure multiple instances at the physical resource level.
Set up Isolation
You can isolate a server by adding the following field during its creation:
HTTP request
POST /ecs/v2/servers
{
"plan": "ECS6",
"image": "debian-12",
"location": "it-fr2",
"notes": "my-isolated-server",
"isolate_from": [
"ecs000001",
"ecs000002"
]
}
This forces the new server to start on a physical host other than ecs000001 and ec000002.
Obtain all isolations for a server
To get all active isolations for a server you can use the following request:
HTTP request
/ecs/v2/servers/{servername}/isolations
HTTP Response
{
"status": "ok",
"isolations": [
{
"name": "ec000001",
"notes": "my-isolated-server"
},
{
"name": "ec000002",
"notes": "my-faboulus-isolated-server"
}
]
}
Obtaining the status of the server.
To get the running status of the server, you can use the following endpoint:
HTTP request
GET /ecs/v2/servers/{servername}/status
HTTP Response
{
"status": "ok",
"server": {
"name": "ec000001",
"current_status": "Running"
}
}
you may receive the following errors:
| Status Code | Message | Explanation |
|---|---|---|
| 400 | Unable to retrieve server status | Server status is exported by the libvirt exporter tool so errors may occur in retrieving it |
Metrics
The ECS service exports various performance information and metrics about your server, you can get CPU, Disk and Network consumption via the following endpoint:
HTTP request
GET /ecs/v2/servers/{servername}/metrics
HTTP Response
{
"metrics": {
"resource": "ec000001",
"core": [
{
"t": "2024-10-17 08:25:58",
"y": "0.00"
},
{
"t": "2024-10-17 08:30:58",
"y": "0.00"
},
...
],
"disk": {
"reads": [
{
"t": "2024-10-17 08:35:58",
"y": "28.45"
},
{
"t": "2024-10-17 08:40:58",
"y": "0.00"
},
...
],
"writes": [
{
"t": "2024-10-17 08:35:58",
"y": "2.37"
},
{
"t": "2024-10-17 08:40:58",
"y": "0.00"
},
...
]
},
"network": {
"received": [
{
"t": "2024-10-17 08:35:58",
"y": "0.00"
},
{
"t": "2024-10-17 08:40:58",
"y": "0.00"
},
...
],
"transmitted": [
{
"t": "2024-10-17 08:35:58",
"y": "0.00"
},
{
"t": "2024-10-17 08:40:58",
"y": "0.00"
},
...
]
}
}
}
Delete a Server
To delete a Server is available the following endpoint:
HTTP request
DELETE /ecs/v2/servers/{servername}
HTTP response
{
"status": "ok",
"action": {
"id": 39,
"status": "in-progress",
"user": "foo",
"created_at": "2019-04-30T16:33:03.317800+00:00",
"started_at": "2019-04-30T16:33:03.317019+00:00",
"completed_at": null,
"resource": "ec200016",
"resource_type": "ECS",
"type": "delete_server",
"progress": 0
}
}