A recent release of the Acronis Cyber Cloud brings one of the highly demanded features - the Agent auto-updating together with corresponding public API to control that updates.
Automatic updates are available for agents version 15.0.26986 (released in May 2021) or later. Older agents must be updated manually to the latest version, first.
Automatic updates are supported on machines running any of the following operating systems:
Windows XP SP 3 and later
Red Hat Enterprise Linux 6 and later, CentOS 6 and later
OS X 10.9 Mavericks and later
The settings for automatic updates are preconfigured on a data center level. A company administrator can customize these settings – for all machines in a company or a unit, or for individual machines. If no custom settings are applied, then the settings from the upper level are used, in this order:
Cyber Protection data center
Company (customer tenant)
Unit
Machine
For example, a unit administrator can configure custom auto-update settings for all machines in the unit, which might differ from the setting applied to the machines on the company level. The administrator can also configure different settings for one or more individual machines in the unit, to which neither the unit settings nor the company settings will be applied.
You can find the most current information on updating agents in documentation https://www.acronis.com/en-us/support/documentation/CyberProtectionService/#updating-agents.html.
Tenants INT and UUID identifiers
All systems are evolving as well as Acronis Cyber Cloud. Historically tenants have unsigned int ids, and it Account Management API V2 they are UUID/GUID. However, in APIs connected to Agent Management, developers can find that unsigned int ids.
So the question is, how to connect that int ids to UUID ids.
In the future, all API will use UUID tenants ids.
This is the historically presented ids, so we use the previous version of Account Management API to convert int ids to UUID ids and vice-versa.
The simplest but not scalable way to convert ids is to call /api/1/group/{any_id} in this call, you can use any id, either int id or UUID id to receive a group/tenant JSON, which contains id field with int id and uuid field with UUID id.
{
"billing": {
....
},
"usage": {
....
},
"language": "en",
"storage": {
....
},
"pricing": {
....
},
"parent_has_access": 1,
"id": 1516165,
"uuid": "531789f2-2be9-42af-8474-18177593c77b",
"contact": {
....
},
"customer_type": 0,
"agents": {},
"brand": null,
"version": 4,
"privileges": {
....
},
"parent_id": null,
....
"name": "Stanislav Pavlov (7551274)",
"default_identity_provider_id": 1,
"grade": 2,
"creation_date": 1590019200,
"kind": 31
}We have the solution, /api/1/group/{any_id}/children call, where you can move massively by your hierarchy and build your mapping table. The has_children field can be used to understand if you need to move deeper in the hierarchy.
{
"items": [
{
"id": 1952004,
"usage": {
....
},
"name": "Cyber Protection Training Lab",
"status": 1,
"parent_has_access": 1,
"mfa_status": "disabled",
"capabilities": 278,
"kind": 31,
"uuid": "e1a4cda1-a798-4878-899b-bca06c2f4f89",
....
"creation_date": 1615420800,
"storage": {
"id": null,
"name": "",
"uuid": null
},
"has_children": 1
},
{
"id": 2035746,
"usage": {
....
},
"name": "Cyber Files Partner",
"status": 0,
"parent_has_access": 1,
"mfa_status": "disabled",
"capabilities": 278,
"kind": 31,
"uuid": "567f2c26-6a0a-4c7c-ade5-5d187bf78379",
...
"creation_date": 1618963200,
"storage": {
"id": null,
"name": "",
"uuid": null
},
"has_children": 1
}
.....
}Now we are ready to proceed with Agents Management API.
Agent Management API Essentials
The Agent Management API as well as all other Acronis Cyber Platform APIs requires you to be authorized to call it. Here we assume that you already know how to deal with that task., if you need more information check that article https://developer.acronis.com/blog/posts/prototyping-acronis-cyber-platform-api-solutions-with-postman-account-management/.
The first call from Agent Management API to know is the call to list agents under specific tenant and their hierarchy (Partner, Customer, Folder, Unit) for which you plan to manage them GET /api/agent_manager/v2/agents?tenant_id={tenant_id_int}
Normally, you don't need to call for that API without specifing tenant_id parameter, as it returns information about all agents underneath your tenant. It means agents for all your partners and customers. Additional parameters to filter that request and enable paging can be found at the documentation https://developer.acronis.com/doc/agents/v2/reference/index#/http/api-endpoints/agents/fetch-agents.
tenant id parameter for that call is INT tenant id.
The result of that call is a JSON array named items, where each item represents an agent and contains all information regarding version, updates, OS, etc.
{
"items": [
{
"id": "f851d328-2158-45f3-a8c4-539cf2334d9c",
"tenant": {
"id": "1480374",
"name": "Stanislav.Pavlov@examples.net"
},
"hostname": "host-O0000000",
"host_id": "f2695469-ae78-4d58-bc9d-976fab83ac46",
"core_version": {
"current": {
"release_id": "1.2.8",
"build": "174"
}
},
"units": [
{
"name": "active_protection",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
},
{
"name": "atp-agent",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
},
"meta": {
"schema_ver": 1,
"format": "json",
"meta": "eyJjb21wb25lbnRzIjpbeyJuYW1lIjoiQUNUSVZFX1BST1RFQ1RJT04iLCJ1cGRhdGVfdGltZSI6Ik1vbiwgMjQgQXVnIDIwMjAgMTg6MDA6NDEgKzAzMDAiLCJ2ZXJzaW9uIjoiMS4wLjAuNjU2In0seyJuYW1lIjoiVlVMTkVSQUJJTElUWV9BU1NFU1NNRU5UIiwidXBkYXRlX3RpbWUiOiJGcmksIDI4IEF1ZyAyMDIwIDE4OjAwOjExICswMzAwIiwidmVyc2lvbiI6IjEwMDguMC4wLjAifSx7Im5hbWUiOiJBTlRJVklSVVNfRU5HSU5FIiwidXBkYXRlX3RpbWUiOiJXZWQsIDAyIFNlcCAyMDIwIDEyOjAxOjAyICswMzAwIiwidmVyc2lvbiI6IjgxNzI4In1dfQ=="
}
},
{
"name": "atp-downloader",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
},
{
"name": "cyber-protect-service",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
},
{
"name": "mms",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
},
{
"name": "sync-unit",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
},
{
"name": "task-manager",
"version": {
"current": {
"release_id": "0.0.0",
"build": "1"
}
}
}
],
"auto_update": true,
"unattended_update": {
"update_channel": "CURRENT",
"automatic": true,
"maintenance_window": {
"time_from": "00:00:00",
"time_to": "23:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
]
},
"inherited_from_tenant_id": "12345",
"status": "OK"
},
"meta": {
"atp": {
"components": [
{
"name": "ACTIVE_PROTECTION",
"update_time": "Mon, 24 Aug 2020 18:00:41 +0300",
"version": "1.0.0.656"
},
{
"name": "VULNERABILITY_ASSESSMENT",
"update_time": "Fri, 28 Aug 2020 18:00:11 +0300",
"version": "1008.0.0.0"
},
{
"name": "ANTIVIRUS_ENGINE",
"update_time": "Wed, 02 Sep 2020 12:01:02 +0300",
"version": "81728"
}
]
}
},
"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": true,
"enabled": true,
"registration_date": "Fri, 10 Apr 2020 08:31:33 +0000"
}
],
"paging": {
"cursors": {}
}
}The next call is to retrieve update settings either for an agent or for a tenant
GET /api/agent_manager/v2/agent_update_settings/{id} where id is a tenant id if the master query parameter is specified and set to true an agent id if non-specified or specified and set to false.
If agent-specific settings are requested, and the caller has access to the tenant that the agent belongs to according to usual tenant accessibility rules, Agent Manager checks if settings stored specifically for this agent exist. If they do, they are returned. Otherwise, Agent Manager returns settings it would return in response to a request for master settings of agent's tenant. The only difference is that if the master settings are found, they have the agent identifier and do not have a tenant identifier on output.
If master settings of a tenant are requested, the Agent Manager behaves differently depending on whether the caller has access to a specified tenant according to usual tenant accessibility rules. If access is granted, but tenant-specific settings are absent, Agent Manager searches for their substitute among tenants up tenant hierarchy and the specified tenant's locator. This locator omits all tenants between the hierarchy root (as seen to Agent Manager), and a tenant with a visibility barrier set nearest to the specified tenant. This way, the caller may retrieve master settings from a tenant beyond its usual access scope.
If the specified tenant is inaccessible to the caller, a search for a substitute is not performed. Settings of the tenant are only returned to the caller if there is a tenant from the caller's access scope.
If a substitute for master settings is found, it has a tenant identifier of the specified tenant in response.
Bellow, the request for a setting for a tenant was successful, but there are no settings for that tenant.
{
"domain": "AGENT_MANAGER",
"code": "UNATTENDED_AGENT_UPDATE_SETTINGS_NOT_FOUND",
"reason": "UNATTENDED_AGENT_UPDATE_SETTINGS_NOT_FOUND",
"context": {
"tenant_id": "5bd64cd2-bd3c-4246-b63e-e5c21a0f864d"
},
"debug": {
"msg": "GET (5bd64cd2-bd3c-4246-b63e-e5c21a0f864d) to /api/agent_manager/v2/agent_update_settings/5bd64cd2-bd3c-4246-b63e-e5c21a0f864d?master=true: fetching master agent update settings: no master unattended agent update settings in the tenant"
},
"message": "GET (4c5d636f41b5cd992bdd27c8c1de465e) to /api/agent_manager/v2/agent_update_settings/5bd64cd2-bd3c-4246-b63e-e5c21a0f864d?master=true: fetching master agent update settings: no master unattended agent update settings in the tenant"
}Bellow, the request for a setting for an agent. It was successful, there are not settings on an agent level, the settings are defined on tenant 123654 level.
{
"tenant_id": "123654",
"agent_id": "650277f7-7259-4bf8-8526-5291d27533a1",
"update_channel": "CURRENT",
"automatic": true,
"maintenance_window": {
"time_from": "00:00:00",
"time_to": "23:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
]
},
"inherited_from_tenant_id": "123654"
}Now, we know how to list agents and how to know their unattended update settings, and where they're defined. If we need to update the settings either for an agent or for a tenant level it can be done by
PUT /api/agent_manager/v2/agent_update_settings call.The input body for that request is items JSON array where each item represents agent update settings either for a tenant or an agent.
Bellow, there is an example of JSON if you need to update settings for an agent and a tenant.
{
"items": [
{
"agent_id": "836fe933-d232-4ed1-b3be-2218f3bbf134",
"update_channel": "CURRENT",
"automatic": true,
"maintenance_window": {
"time_from": "22:15:00",
"time_to": "05:00:00",
"days_of_week": [
"SATURDAY",
"FRIDAY"
]
}
},
{
"tenant_id": "62",
"update_channel": "STABLE",
"automatic": true
}
]
}From time to time, it's required to force an agent update, and Agent Management API provides API for that
POST /api/agent_manager/v2/agents/update:force.The request body is JSON, if that body is empty, the update request is sent to all agents underneath the tenant you authorized to make that call.
Bellow, there is an example of a request body to update two specific agents with provided ids.
{
"agent_ids": [
"d8a7059e-fda4-480e-b400-968ed5ffdd59",
"b757f01e-0b14-4788-b9a0-2671469517d7"
]
}Now, you know all about Agent Management API to create your agent automation.
Agents Reports
The next step of the agents' updates automation is to collect reports. There are no specific reports for that like it's for usage in Account Management API, however, the agents listing requests with filters can help to build sophisticated reports. You need only process a response JSON array to any human-readable format. It can be done even using just Excel.
Agent Unattended Update Status Report
For example, you might want to collect unattended update status. There are only two: OK and SUSPENDED_ON_FAILURES. Excellent addition to that report will be an agent version currently installed on a protected device.
If it's required, you can even build a script to automatically notify you if you have, any agent with suspended status.
"unattended_update": {
"update_channel": "CURRENT",
"automatic": true,
"maintenance_window": {
"time_from": "00:00:00",
"time_to": "23:00:00",
"days_of_week": [
"MONDAY",
"TUESDAY",
"WEDNESDAY",
"THURSDAY",
"FRIDAY",
"SATURDAY",
"SUNDAY"
]
},
"inherited_from_tenant_id": "12345",
"status": "OK"
},
"installer_version": {
"current": {
"release_id": "15.0.1",
"build": "28037",
"major": 15,
"minor": 0,
"patch": 1,
"build_number": 28037
},
"latest": {
"release_id": "15.0.1",
"build": "28156",
"major": 15,
"minor": 0,
"patch": 1,
"build_number": 28156
}
}The installed_versions JSON object contains information about the current version of the agent and if a newer version is available, provide information about the latest.
Agent Installation OS Information Report
The next idea for a report is to collect operation system information, as it's present in agents' listing.
"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": "Test",
"online": false,
"enabled": true,
"network": {
"network_interfaces": [
{
"cidr_notations": [
"fe80::fd52:764e:1c7b:ec52/64",
"192.168.2.158/24"
]
}
]
}Summary
Now you know how to implement agent unattended updates automation and reporting with Acronis Cyber Platform API.
All API calls from that article available in the Acronis public Postman collection. You can look into the full collection of calls and try them out in Acronis Sandbox which is available after registering on Acronis Developer Portal.
Check collections at the Postman API Network:
Account Management API
Task Manager, Activities and Alerts API
Plan and Resource Management API
Cyber Files API
Cyber Notary API
Agents Management API
Get started today, register on Acronis Developer Portal and see the code samples available, you can also review solutions available in the Acronis Cyber Cloud Solutions Portal.
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.
