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
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 Value
|The Agent is running normally and all scheduled backups are being run
|Ignoring 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 to return 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 that move between networks and should not perform backups if they're connected over VPN or WiFi
|Any other value
|Any 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:
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.