Skip to end of metadata
Go to start of metadata


As of version 7.1.3268, a user script may be placed on the agent which the agent will run periodically. This script can produce a user description which is displayed in the computers table of Site Manager and can be used to disable scheduled backups in Site Manager. 

The intended use for this script is to provide a mechanism for user scripting to display useful information to the server such as asset IDs and other nonstandard information specific to each computer and to provide a mechanism for the Site Manager administrator to disable backups based on installation specific details. An example of this would be a script which detects that a laptop is connected to the network via a VPN and disables backups until the computer is back in the office. 

Setting Up Scripting

The Agent will look for a script at the path C:\Program Files\Macrium\Agent\Scripts\script.cmd 

This script is executed as a Windows batch file/command script. Powershell scripts, executable files or any other sort of script may be called from this script.cmd file. 

Running the Script

The Agent will run the script and send the results to the Site Manager server under the following conditions:

      • When the Macrium Agent service starts up
      • When any file in the C:\Program Files\Macrium\Agent\Scripts folder changes
      • When any value is written to the HKEY_LOCAL_MACHINE\SOFTWARE\Macrium\CMCAgent\UserScripts registry key
      • When a device is added or removed from the system (to assist in scripts that depend on USB disk presence or laptop docking station connection)
      • When the IP addresses for the computer change (to assist in scripts that depend on VPN or WiFi changes)
      • Every 30 minutes

Script activity is logged in the c:\programdata\Macrium\SiteManager\AgentUserScript.log file

Script output

The script should produce the following output:

      • User description - any text outputted to standard out (e.g. with the 'echo' command) will be shown in Site Manager in the "User Description" column of the Computers table
      • Operating Mode - the return code of the script determines the user-set operating mode of the agent. The following
Script Return ValueOperating ModeDescription
0NormalThe Agent is running normally and all scheduled backups are being run
-1Ignoring scheduled backups

The Agent should not run backups. When this error code is returned, Site Manager will defer all scheduled backups for the agent until the user script starts returned normal status again.

When the agent returns to normal status, any missed backups will be executed immediately as if the computer had been offline and Defer Missed Backups was set in the Site Manager schedule.

This can be used for computers which move between networks and should not perform backups if they're connected over VPN or WiFi

Any other valueNormalAny other value is assumed to be an error code in the user script and the script execution is ignored

Viewing Script Results

For debugging purposes, script activity is logged in c:\programdata\Macrium\SiteManager\AgentUserScript.log on the agent computer.

The results of the script execution can be shown in the Computers table in Site Manager by enabling the "User Script Message" and "Operating Mode" columns which are hidden by default:

These columns will show the script results:

This output was produced from the user script below:

@echo off
echo Example Custom Agent Status
exit -1


For security reasons, scripts must be placed in the C:\Program Files\Macrium\Agent\Scripts folder. This folder has write access to Administrator users only by default. If the permissions on this folder are manually changed by a system administrator, non-privileged users may be able to set or modify the script being run.

The Agent service runs the script as a non-privileged process using the Network Service account, regardless of what user the Agent service is configured to run as. This is to prevent any possibility of a user script being executed with Administrator privileges. 

  • No labels