Adding and Managing Computers
      Back to home
      1. SiteManager Platform
      2. SiteBackup
      3. Adding and Managing Computers

      Agent User Scripting

      - Overview

      - Setting Up Scripting

      - Running the Script

      - Script Output

      - Viewing Script Results

      - Security

      Overview

      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 that is displayed in the 'Computers' table of SiteBackup and can be used to disable scheduled backups in SiteBackup.

      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 non-standard information specific to each computer, and to provide a mechanism for the SiteBackup administrator to disable backups based on installation-specific details. An example of this would be a script that 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 SiteBackup 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 SiteBackup Agent will run the script and send the results to the SiteBackup server under the following conditions:

      • When the SiteBackup 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 possible return codes are shown below:
      Return Code Operating Mode Description
      0 Normal The SiteBackup Agent is running normally, and all scheduled backups are being run.
      -1 Ignoring scheduled backups

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

      When the SiteBackup 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 SiteBackup 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 Normal 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 SiteBackup Agent computer.

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

      image2021-5-25_0-42-23.png

      The script results will be shown in these columns, similar to the example below:

      image2021-5-21_15-16-43.png

      This example was created using the script below:

      @echo off
      echo Example Custom Agent Status
      exit -1

      Security

      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 SiteBackup 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.