November 11, 2021

Customize Unattended Acronis Agent Installation on macOS

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

Secure your workloads with the Acronis Cyber Protection

You can find more details on how to use API and the Management Console UI to generate the Agent registration tokens https://developer.acronis.com/blog/posts/automate-acronis-agent-installations-with-protection-plan-applying/.

Install the Agent on macOS

The installation on macOS is less customizable, however, it's still possible to install the agent unattended, hide the agent tray appearance, and apply a protection plan.

Unattended Installation

By default, Acronis Agent is installed and registered in the account specified during installation. When you need to install agents without registration and register them manually later.

At first, you need to download the installation package (.dmg file). You need to select the appropriate processor architecture ARM64 or X86_64.

This package should be mounted to manually/unattended start the agent installation. Open Terminal and create a temporary DMG mount directory.

mkdir dmg_mount

Now the package can be mounted with the following command (still in the Terminal)

hdiutil attach AcronisCyberProtect_AgentForMac_arm64.dmg -mountpoint dmg_mount

And start the installation of the agent

sudo installer -pkg dmg_mount/AcronisBackupClientMacOSARM64.pkg -target LocalSystem

To unmount the dmg package after the installation

hdiutil detach dmg_mount/

After the manual agent installation, it's not registered on the Acronis Cyber Cloud.

To register the agent using account and password after the installation

sudo /Library/Application\ Support/BackupClient/Acronis/RegisterAgentTool/RegisterAgent -o register -t cloud -a {dc-url} -u {login} -p {password}

An example

sudo /Library/Application\ Support/BackupClient/Acronis/RegisterAgentTool/RegisterAgent -o register -t cloud -a https://dev-cloud.acronis.com -u stas.pavlov@nowhere.com -p ItisaVeryStrongPassword1991?

To register the agent using a token after the installation

sudo /Library/Application\ Support/BackupClient/Acronis/RegisterAgentTool/RegisterAgent -o register -t cloud -a {dc-url} --token {token}

An example

sudo /Library/Application\ Support/BackupClient/Acronis/RegisterAgentTool/RegisterAgent -o register -t cloud -a https://dev-cloud.acronis.com --token 0454-BAA1-4A1F

There are KB artilce about unattended installations and the agent registration for macOS https://kb.acronis.com/content/58154 and https://kb.acronis.com/content/55244

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

Specifically for that task Acronis created a simple scripting utility tray_control.sh and publish corresponding KB - https://kb.acronis.com/content/59678.

Download and unpack tray_control.sh on the Mac machine where the Acronis Cyber Protection Agent is installed and grant execution right to the script by running this command:

sudo chmod a+x ./tray_control.sh

To disable the Acronis Cyber Protection Agent monitor, run the following command

sudo ./tray_control.sh disable

If you need to re-enable the monitor, run the following command

sudo ./tray_control.sh disable

As this utility is a bash script, if you don't want to upload to your endpoint additional files, it's possible to take actual disabling/enabling code end to integrate into your unattended installation scripts.

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 a bash script 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, for example, you can pull a resource id from the config file until you have it.

################################################
# Variables
################################################

_reg_token={put_the_agent_registratio_toke_with_a_protection_plan_included_here|example:0454-BAA1-4A1F}

_base_url={put_your_DC_Url_here_ending_with_backslash|example:https://dev-cloud.acronis.com/}

################################################
# Helper functions
################################################

# XML config file needs to be parsed to find resource id
# We will use a simple example from https://stackoverflow.com/questions/893585/how-to-parse-xml-in-bash
# As it's well documented in that post 

_read_dom () {
    local IFS=\>
    read -d \< ENTITY CONTENT
    local RET=$?
    TAG_NAME=${ENTITY%% *}
    ATTRIBUTES=${ENTITY#* }
    return $RET
}

# Read config file, find value tag with name InstanceID and echo CONTENT
_parse_dom () {
    if [[ $TAG_NAME = "value" ]] ; then
        eval local $ATTRIBUTES
        if [[ $name = "InstanceID" ]] ; then
            echo $CONTENT
            exit
        fi
     fi
}

# Below you can find some helper functions to call Acronis REST API
# Print errors info to STDERR and exit execution
_die() { printf ":: %s\n\n" "$*" >&2; exit 1; }


# Pipe JSON from file, extract JSON property, remove quotas from the property's value
_get_access_token_from_file(){ jq '.access_token' < "${1}" | sed -e 's/^"//' -e 's/"$//'; }

# POST API call with Bearer Authentication
# $1 - an API endpoint to call
# $2 - Content-Type
# $3 - urlencoded data 1st param
# $4 - urlencoded data 2st param
_post_api_call_bearer_urlencoded () {

  local _response_body
  local _response_code

  curl	-s \
		-X POST \
		--url "${_base_url}${1}" \
		-H "Authorization: Bearer ${_access_token}" \
		-H "Accept: application/json" \
		-H "Content-type: ${2}" \
		--data-urlencode "${3}" \
		--data-urlencode "${4}" \
		-w "\n%{http_code}" | {
			read -r _response_body
			read -r _response_code

			_response "${_response_body}"

			if [[ $_response_code = 20* ]] ; then
  				echo "${_response_body}"
			else
				_die "The POST API Call with the endpoint ${1} is unsuccessful with response code: ${_response_code}." "${_response_body}"
			fi
		}
}

# POST API call with Bearer Authentication
# $1 - an API endpoint to call
# $2 - Content-Type
# $3 - POST data
_post_api_call_bearer () {

  local _response_body
  local _response_code

  curl	-s \
		-X POST \
		--url "${_base_url}${1}" \
		-H "Authorization: Bearer ${_access_token}" \
		-H "Accept: application/json" \
		-H "Content-type: ${2}" \
		--data-raw "${3}" \
		-w "\n%{http_code}" | {
			read -r _response_body
			read -r _response_code

			_response "${_response_body}"

			if [[ $_response_code = 20* ]] ; then
  				echo "${_response_body}"
			else
				_die "The POST API Call with the endpoint ${1} is unsuccessful with response code: ${_response_code}." "${_response_body}"
			fi
		}
}

################################################
# Actual flow for applying a protection plan
################################################

# You need appropriate right to read /Library/Application Support/Acronis/Registry/BackupAndRecovery.config file
# Put resource id to the file for the script debug simplicity
while _read_dom; do
    _parse_dom
done < /Library/Application\ Support/Acronis/Registry/BackupAndRecovery.config > ~/resourceId.txt

# Remove quotas and put resource id into the variable
_resource_id=$(cat ~/resourceId.txt | sed -e 's/^"//' -e 's/"$//';)

# Exchange registration token to authorization token
_post_api_call_bearer_urlencoded "idp/token" \
					"application/x-www-form-urlencoded" \
					"grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer"  \
					"assertion=${_reg_token}"  \
					 > ~/access_token.json

# Get access_token from file
_access_token=$(_get_access_token_from_file "~/access_token.json")

# Construct JSON to apply a protection plan
_json='{
     "context": {
         "items": [
             "'$_resource_id'"
         ]
     }
}'

# To apply a protection plan
# POST API call using function defined in basis_functions.sh
# with following parameters
# $1 - an API endpoint to call
# $2 - Content-Type
# $3 - POST data
# The result is stored in results.json file
_post_api_call_bearer "api/policy_management/v4/applications" \
					"application/json" \
					"${_json}" > "~/results.json"

Summary

Now you know how to customize the Acronis Cyber Agent installation on macOS. The Windows article can be found here https://developer.acronis.com/blog/posts/customize-unattended-acronis-cyber-agent-installation-on-windows/ and the Linux article -- here https://developer.acronis.com/blog/posts/customize-unattended-acronis-cyber-agent-installation-on-linux/.

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 February 9, 2022