Managing the Acronis Agent update using API was a common request from our partners and customers. There are three main requests. To have the possibility to customize Agents update setting, to retrieve downloadable links to the Agent installer packages, and, the last but not least, to force Agents updates. With the last Acronis Cyber Protect Cloud updates, all that functionality are available in our public Cyber Platform API.
Get Filtered Agents List
To manage agents, at least we need to know how to retrieve our Agents list. There is a simple API for that in the Agent Management API:
By default, this API returns all Agents in your scope and underneath. It means, that if you make a request on a partner level you receive an Agents list for all underneath customers. Thus, to filter output, a developer can either use a scoped token as for resources and plan management or use additional requests parameters to filter responses:
tenant_id - identifier of a tenant subtree root. Only agents that belong to tenants of this subtree are returned. If this parameter is missing, tenant identifiers from relevant elements of scope collection of access tokens are used.
unit – name of registered agent unit. If this parameter is provided, only agents that have at least one of the specified units are returned.
up_to_date - Flag specifying whether agents with current or outdated software should only be returned.
online - if true, only responsive agents will be returned. If false, only irresponsive agents will be returned.
os_family - filters registered agents by OS family name they were built for. OS family name is case-insensitive.
As well, the result can be filtered by hostname, ordered, and support pagination.
Here is an example of an Agent item in an Agents list:
{
"id": "d8a7059e-fda4-480e-b400-968ed5ffdd59",
"tenant": {
"id": "1952010",
"name": "Stanislav Pavlov (stas.customer)"
},
"hostname": "test-vm-1",
"host_id": "a57c6c9c-e4e4-4342-9034-a0f2e4bb69f7",
"core_version": {
"current": {
"release_id": "1.9.0",
"build": "290"
}
},
"units": [...],
"meta": {...},
"auto_update": false,
"platform": {
"family": "WINDOWS",
"arch": "X64",
"name": "windows",
"caps": 0,
"product_type": 0,
"service_pack": 0,
"sku": 0,
"suite_mask": 0,
"version_major": 0,
"version_minor": 0
},
"name": "",
"online": false,
"enabled": true,
"registration_date": "Fri, 12 Mar 2021 11:02:28 +0000",
"registration_id": "",
"network": {},
"installer_version": {
"current": {
"release_id": "15.0.1",
"build": "26570",
"major": 15,
"minor": 0,
"patch": 1,
"build_number": 26570
},
"latest": {
"release_id": "15.0.1",
"build": "29250",
"major": 15,
"minor": 0,
"patch": 1,
"build_number": 29250
}
},
"timezone": "UNKNOWN"
}As you can see, a lot of information is available in that response, which might be helpful for a lot of tasks, but for our task the most interesting are tenant/id and agent_id. They provide information regarding tenant that Agent belongs to and this Agent id.
Get and Set Agents Update Settings
You can either request settings for a specific Agent or for a specific tenant. If a specific Agent don't have dedicated settings, update settings used from the nearest tenant with settings present. Thus if you request an Agent update settings and there are not, it might be 2 possible results:
- You have enough rights to read settings from a tenant which settings are used. You receive that settings and tenant id.
- You don't have enough rights to read settings from a tenant which settings are used. You can't receive that settings.
To retrieve settings the following API endpoint is used:
GET /api/agent_manager/v2/agent_update_settings/{id}With the following parameters:
id - if the master query parameter is false or missing, this is a registered agent ID. Otherwise, this is a tenant ID.
master – flag specifying whether master unattended agent update settings should be returned. If the value is true, then id is interpreted as the ID of the tenant the settings belong to. Otherwise, the id is interpreted as the agent ID.
Here is an example of an update settings for an Agent which are inherited from a tenant:
{
"tenant_id": "1952010",
"agent_id": "d8a7059e-fda4-480e-b400-968ed5ffdd59",
"update_channel": "CURRENT",
"automatic": false,
"maintenance_window": {
"time_from": "23:00:00",
"time_to": "08:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
]
},
"inherited_from_tenant_id": "1952004"
}Here is an example of an update settings for that tenant:
{
"tenant_id": "1952004",
"update_channel": "CURRENT",
"automatic": false,
"maintenance_window": {
"time_from": "23:00:00",
"time_to": "08:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
]
}
}To update an Agent update settings on an Agent or tenant level, the following endpoint is used:
PUT /api/agent_manager/v2/agent_update_settingsTo update, you need to build a JSON array items and put updates needed on an Agent or tenant level using the same JSON format as returned and shown above:
{
"items": [
{
"agent_id": "d8a7059e-fda4-480e-b400-968ed5ffdd59",
"update_channel": "CURRENT",
"automatic": false,
"maintenance_window": {
"time_from": "00:00:00",
"time_to": "23:59:59",
"days_of_week": [
"SATURDAY",
"SUNDAY"
]
}
},
{
"tenant_id": "1952004",
"update_channel": "CURRENT",
"automatic": false,
"maintenance_window": {
"time_from": "10:00:00",
"time_to": "19:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY"
]
}
}
]
}Force Agents Updates
Sometimes, it's required to ask the Acronis Cyber Protect Cloud to force Agents updates start. In that case the following endpoint can be used:
POST /api/agent_manager/v2/agents/update:force
Generally, this call is not starting updates immediately, it puts them to an updates queue before maintenance window defined in the settings as much close to requested time as possible.
The input is agent_ids array with agent ids. Note,
- that if an empty agent ID collection is passed with the request, all tenant's agents become a potential subject of update;
- the maximum number of agents being updated simultaneously is limited.
Here is an example of agent_ids array.
{
"agent_ids": [
"17a66004-0a5c-4856-ae9f-f05555fa5e00",
...
"72d47035-0cd6-41cc-8d50-bf94b6926be7"
]
}Get Link to the Agent Installer Packages
In case if we can't wait for an update initiated from the Acronis Cyber Protect Cloud, you can download updates packages and run updates manually on a device. To obtain links to updated the Agents installer packages the following API endpoint can be used:
GET /api/agent_manager/v2/agent_update_referencesWith the following parameters:
update_channel - update channel the agent update belongs to.
os_family – the name of the operating system family the update was built for.
os_arch - CPU architecture of operating system the update was built for.
white_labeled - flag specifying whether information about the update package that installs an agent that does not contain references to Acronis as its manufacturer ought to be returned
For example, to request an installer for Windows, from CURRENT channel for x64 architecture, you will use the following call:.
GET /api/agent_manager/v2/agent_update_references?update_channel=CURRENT&os_family=WINDOWS&os_arch=X64And result will be like this:
{
"update_channel": "CURRENT",
"os_family": "WINDOWS",
"os_arch": "X64",
"white_labeled": false,
"version": {
"release_id": "15.0.1",
"build": "29250"
},
"url": "https://dl.managed-protection.com/u/baas/4.0/15.0.29250/AcronisCyberProtect_AgentForWindows_web.exe"
}Then, you need to download that installer with any tool you normally use for that type of tasks, and providing needed command-line parameters install.
Summary
Now you know how to automate the Acronis Cyber Protection Agent update management using API and have practical examples of how to proceed with this task .
For further API learning, register at our Platform Program or Developer Network on https://developer.acronis.com site.
Find our public Postman API collection for standard automation and integration tasks https://explore.postman.com/grey-rocket-585331 or use our GitHub examples https://github.com/acronis.
About Acronis
Acronis is a Swiss company, founded in Singapore. Celebrating two decades of innovation, Acronis has more than 1,800 employees in 45 locations. The Acronis Cyber Protect Cloud solution is available in 26 languages in over 150 countries and is used by 20,000 service providers to protect over 750,000 businesses.
