Customize Unattended Acronis Cyber Agent Installation on Windows

Starting the agent for the Acronis Cyber Cloud 9.0, it's possible to customize the Acronis Cyber Agent installation using command line parameters. In this article, we'll navigate common customization scenarios for the Windows system.

Secure your workloads with the Acronis Cyber Protection

Secure your workloads with the Acronis Cyber Protection

Install the Agent on Windows

When you call the agent installer with the --help parameter, you receive the full list of available setup program parameters.

.\AcronisCyberProtect_AgentForWindows_x64.exe --help

Either full installer (used here in all examples) or web installer can be used. The web installer downloads needed components before install.

For your reference, we put the complete list of these parameters below. If you are interested in specific scenarios, please skip that table.

Parameter Description
--help Shows the complete list of available setup program parameters.
--quiet Runs the setup program without showing the user interface (the unattended installation).
--log-dir=<path> Path to a folder where the installation logs will be saved.
--language=<code> The language that the product and its components will use.
en - English      bg - Български
cs - Čeština      da - Dansk   
de - Deutsch    es - Espańol
fr - Français      ko - 한국어
id - Bahasa Indonesia
it - Italiano        hu - Magyar
ms - Bahasa Melayu
nl - Dutch          ja - 日本語
nb - Norsk         pl - Polski
pt - Portuguęs   
pt_BR - Portuguęs brasileiro
ru - Русский       fi - Suomi
sr - Српски         sv - Svenska
tr - Türkçe           zh - 简体中文
zh_TW - 繁體中文
--register-only Skips the installation and shows the registration page only (the OAuth 2.0 registration). Do not use with --quiet.
--anti-tamper-password=<password> Anti-tamper password. It might be required to modify some of the installed components.
--installation-files=<path/url> URL or file-system path to the installation files.
--skip-https-cert-verification Skip server certificate verification when downloading the installation files.
--skip-file-trust-verification Skip trust verification of the downloaded installation files.
--attempts-number=<number> Number of attempts to download an installation file. The default value is '1'.
--cache-directory=<path> Path to a local folder where the installation files will be cached before installation.
--add-components=<component1,component2,...,componentN> Components and groups of components to be added to the product being installed.

If this parameter is not specified, the product will be installed with the default set of components, based on the setup program purpose.

If the product is already installed, it will be repaired or updated based on the setup program version.

If this parameter is specified, the product will be installed with the components and groups of components listed in the value (you can combine components and groups in a value). Specified components that are already installed will be repaired or updated, based on the setup program version.

Supported component values:
agentForAd - Agent for Active Directory
agentForAmp - Agent for Antimalware protection and URL filtering
agentForDlp - Agent for Data Loss Prevention
agentForExchange - Agent for Exchange
agentForHyperV - Agent for Hyper-V
agentForOffice365 - Agent for Office 365
agentForOracle - Agent for Oracle
agentForSql - Agent for SQL
agentForWindows - Agent for Windows
commandLine - Command-Line Tool
mediaBuilder - Bootable Media Builder
trayMonitor - Cyber Protect Monitor
agentForEsx - Agent for VMware (Windows)

Supported group values:
all - This group combines all components. allAgents - This group combines all agents.
--remove-components=<component1,component2,...,componentN> Components and groups of components to be uninstalled.

Using this parameter, you can uninstall the product components only. To completely uninstall the product, go to 'Control Panel', and then select 'Programs and Features' > 'Acronis Backup' > 'Uninstall'.

For the supported values, see the description of the --add parameter.
--install-dir=<path> Path to a folder where the product and its components will be installed. If the folder does not exist, it will be created.
--reg-address=<url> management server URL.
--reg-login=<login> Login for the management server. Do not use with --reg-token. Specifying this parameter makes --registration optional.
--reg-password=<password> Password for the management server. Do not use with --reg-token. Specifying this parameter makes --registration optional.
--reg-token=<token> Registration token. Do not use with --reg-login or --reg-password. Specifying this parameter makes --registration optional.
--registration=[skip | by-credentials | by-token | device-flow] Type of the agent registration after the installation.

To skip the registration, specify 'skip'. To register agents by credentials or a token, specify by-credentials or by-token, and then specify appropriate parameters.

To register agents by using the OAuth 2.0 protocol, specify device-flow - the setup program will show the registration page after the installation completes.

Do not use --registration=device-flow with --quiet.
--agent-account-login=<login> Login for the service account.
--agent-account-password=<password> Password for the service account.
--agent-account=[system | new | custom] Account under which the Cyber Protect Agent service will run.

To use Service User Accounts, specify system.

To create a new account, specify new.

To use an existing account, specify custom or omit.
--http-proxy-address=<host>:<port> Name/IP and port of the custom HTTP proxy server.
--http-proxy-login=<login> Login for the custom HTTP proxy server.
--http-proxy-password=<password> Password for the custom HTTP proxy server.
--http-proxy=[none | system | custom] Instructs whether to use an HTTP proxy server for backup to and recovery from the cloud storage over the Internet.

If no proxy server should be used, specify none.

To use a system-wide proxy server, specify system.

To use any other proxy server, specify custom, and then specify its address and credentials in the appropriate parameters.
--esxi-address=<host> Host name or IP address of the vCenter Server or ESXi.
--esxi-login=<login> Login for the vCenter Server or ESXi.
--esxi-password=<password> Password for the vCenter Server or ESXi.

A lot of customization can be realized using those parameters. However, there are common ones that we explain in detail below.

Unattended Installation

The classic customization of the agent installation is an unattended installation. The simplest way to do it is just specified --quiet parameter. However, it's not enough as the agent should be registered to the Acronis Cyber Cloud to work. There are two options for that. The first is normal registration from UI and user interaction, for that scenario, the --registration=skip parameter and then initialize registration process after the installation using --register-only parameter. The second option is an automated registration using either a user name and password or a registration token.

To only install the agent with the no-UI show and skip the registration.

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --registration=skip

To show registration UI page only providing a user option to register the agent.

.\AcronisCyberProtect_AgentForWindows_x64.exe --register-only

Another option to register the agent is the registration utility from the installed agent. Please, note, that commandLine component should be selected to have this utility installed.

Open Command prompt and navigate to
cd "%ProgramFiles%\BackupClient\RegisterAgentTool"
To register the client machine using account and password:
register_agent.exe -o register -t cloud -a {data-center-url} -u {login} -p {password}
To register the client machine using a token:
register_agent.exe -o register -t cloud -a {data-center-url} --token {token}

To install the agent unattended and register with user name and password. The agent is registered for that specific user.

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --reg-address={url} --reg-login={login} --reg-password={password}

An example

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --reg-address=https://dev-cloud.acronis.com --reg-login=stas.pavlov@nowhere.com --reg-password=ItisaVeryStrongPassword1991?

To install the agent unattended and register with a token. The agent is registered according to the parameters used to generate a token.

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --reg-address={url} --reg-token={token}

An example

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --reg-address=https://dev-cloud.acronis.com --reg-token=0454-BAA1-4A1F

The token can be generated either from the Management Console Add device form or using Acronis Cyber Platform API. It can be either only with user information or as well with protection plan information. Please, see details here https://developer.acronis.com/blog/posts/automate-acronis-agent-installations-with-protection-plan-applying/.

Hide the Agent System Tray Appearance

The next common request is to have not had the agent present in the system tray. There are two options as well. You can either specify only needed components to install with --add-components omitting trayMonitor or after the installation remove that component with  --remove-components.

For the first option, you need to know well, what components you need on that device. For the second option, the agent appears in the system tray after the installation before removal.

Install the only agent for Windows component and skip the registration, no tray appiarance

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --add-components=agentForWindows --registration=skip

Install the only agent for Windows component and register the agent using a token, no tray appearance

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --add-components=agentForWindows --reg-address=https://dev-cloud.acronis.com --reg-token=0454-BAA1-4A1F

Remove the trayMonitor component after any installation of the agent

.\AcronisCyberProtect_AgentForWindows_x64.exe --quiet --remove-components=trayMonitor

Register the Agent and Apply a Protection Plan

After the agent is registered in the Acronis Cyber Cloud, a protection plan should be applied to a device protected. It can be done with different approaches. However, when any endpoint-centric RMM is already in use, it might raise a demand to not only install and register the agent but apply a plan as well from a device.

To implement that approach you need to use a token registration process with the token included a protection plan.

This is a two-step process. The first step is the unattended agent installation and registration with a token which is included a protection plan. The second step is using that token and PowerShell to apply the included in the token protection plan to the device. 

The unattended installation is covered above, so we only focus on the second scripting part.

During the agent registration, a new resource is registered in the Acronis Cyber Cloud. After that, it's possible to apply a protection plan to that resource.

Below you can find an example without error handling. As well, you need somehow to know that the agent installer is finished their tasks. It might be done in many ways. Suppose you don't want to drill into Windows system interactions or analyze logs, etc. In that case, you can implement the registry pulling as it guarantees that the installer is finished and a resource is registered.

Pleaese, notice, that the registry path HKLM:\SOFTWARE\Acronis\BackupAndRecovery\Settings\MachineManager doesn't exist if the agent is not installed, and you may receive a non-existent error if you directly try to read it.

# read recource id from registry
$resourceId = Get-ItemProperty -Path "HKLM:\SOFTWARE\Acronis\BackupAndRecovery\Settings\MachineManager" | Select-Object -ExpandProperty InstanceID


# At first we need to exchange registration token to an authorization token
# Use param to tell type of credentials we request
$postParams = @{ grant_type = "urn:ietf:params:oauth:grant-type:jwt-bearer&assertion" ; assertion = $regToken}

# Set the content type
$headers = @{ Content-Type = "application/x-www-form-urlencoded"}

# Exchanhe the token
$token = Invoke-RestMethod -Method Post -Uri "${baseUrl}idp/token" -Headers $headers -Body $postParams

$accessToken = $token.access_token

# Body JSON, to apply policy included into the registration token
# policy id doesn't need as it included into the installation token
$json = @"
{
     "context": {
         "items": [
             "${resourceId}"
         ]
     }
}"@

$bearerAuthValue = "Bearer $accessToken"
$headers = @{ "Authorization" = $bearerAuthValue }
$headers.Add("Content-Type", "application/json")

$result = Invoke-RestMethod -Method Post -Uri "${baseUrl}api/policy_management/v4/applications" -Headers $headers -Body $json

There is a dedicated article for that topic with more details explained.  Please, see details here https://developer.acronis.com/blog/posts/automate-acronis-agent-installations-with-protection-plan-applying/.  

Summary

Now you know how to customize the Acronis Cyber Agent installation on Windows. In the following articles, we'll discuss the same topics for Linux and macOS.

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.

Updated
Stas Pavlov
Technology Evangelist
Acronis Cyber Agent
Acronis Cyber Platform