How to manage scheduled backups with Site Manager Agent user scripting
If you’re working with Macrium Site Manager, one of your primary concerns will be having control over your Macrium agents. This is now more important than ever with the huge increase in employees working from home as a result of current Coronavirus measures. Administrators will likely have concerns about reducing traffic load on VPNs to make remote working as seamless and pain-free as possible.
Agent user scripting is an extremely helpful technique that can be performed within Site Manager for managing challenges like this. Put simply, it allows you to perform a number of different tasks with relative ease. In this blog post, we’ll show you how Agent scripting in Site Manager can be used to selectively disable backups for a variety of scenarios, including when laptops are connected via VPN, as well as provide examples to help you get started.
What is Agent User Scripting?
Macrium Site Manager v7.1.3268 and later allows you to place user scripts on Macrium agents that can be run periodically This script can produce a user description that will be displayed in the computer’s table within Site Manager. From here, you can then disable scheduled backups under certain conditions. One of the most common situations we see this being done is when a computer is connected to a VPN — with your remote workforce likely to be connecting via a VPN, this, as you can imagine is a very useful tool to have up your sleeve in the present environment.
How to set up the script and when it runs
In order to run the script, Macrium Agent will look at this path:
This script is executed as a batch file. However, the batch file itself can be used to execute any type of script orf executable file. The output of this script will then be sent back to the Site Manager.
The Agent will run the script under the following conditions:
- When the Macrium Agent service starts.
- When any file in C:\Program Files\Macrium\Agent\Scripts folder changes.
- When any value is written to the HKEY_LOCAL_MACHINE\SOFTWARE\Macrium\CMCAgent\UserScripts registry key.
- Every 30 minutes.
As an admin, the output of your user agent scripts provide you with the information you need to properly understand what’s happening across your distribution of agents. That gives you everything you need to decide how to act.
There are two important elements to your script outputs:
- 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.
Things to consider
When using the batch file located in C:\Program Files\Macrium\Agent\Scripts\script.cmd to execute a PowerShell script it is important to consider how the output of the script will be passed back to the batch file. For example:
C:\Program Files\Macrium\Agent\Scripts\script.cmd -
exit /b powershell ./script.ps1
In this example, powershell.exe will return a 0 if the ps1 file returns 0, else powershell.exe will 1 if the ps1 file returns anything else (if the script exits with -1, powershell.exe will return 1). To have powershell.exe return the code unchanged from the ps1 file, it should be executed like so:
C:\Program Files\Macrium\Agent\Scripts\script.cmd -
exit /b powershell -File script.ps1
Basic Agent user scripting
This is the most basic example of Agent user scripting. This simply sets the user description to whatever is defined by the echo command. You can then set an exit code that will either allow or block backups. This example will block backups.
The example shown below will change the error level of the script depending on the time of day. This can be used to manually set working times on an Agent to prevent a backup happening. Once this time has elapsed, the deferred backup will take place. This can be used at times when it’s essential that a backup cannot take place (e.g. early in the day when meetings are taking place).
VPN Detection with Ipconfig
There are many reasons why you would not want a backup to take place over a VPN; the most likely is the strain it can put on the limited bandwidth.
As noted earlier, this has become particularly relevant with current emergency measures. If remote workers connect via a VPN to your work network using a laptop, scheduled backups will put extra strain on an already taxed VPN.
This example shows a simple batch script that will exit with a certain error code depending on whether the value “VPN” can be found in the output of an ipconfig command. The value “VPN” can be changed to any value that indicates whether you are connected to a VPN or not in an ipconfig (e.g. reserved IP address scope for VPN). Not all VPNs will be displayed in ipconfig. You will need a different script to detect these.
We can also block backups from taking place if a ‘marker’ file is present in a directory of our choosing. A basic version of this script is shown below:
This example will set the output of the batch file depending on the presence of a marker file that is placed in the root of C:\.
Some VPN software allows for the execution of scripts when the VPN connects or disconnects. If your VPN software supports this then we can create a batch file that creates a marker file when you connect.
This will write a blank marker file called “VPNMarkerFile.txt”. We can create a second script that will delete this file when the VPN disconnects.
By doing this, we have configured the marker file to only exist while the computer in question is connected to the VPN. We can then create a third file that is placed in C:\Program Files\Macrium\Agent\Scripts\script.cmd that will detect whether or not the marker file is present, and block backups accordingly.
Note: If the marker file is written to C:\Program Files\Macrium\Agent\Scripts then script.cmd will be run as soon as the change is made.
By searching the ‘tasklist’, it is possible to find whether a process is running or not, and then change the output of the batch file accordingly.
There are many reasons why you may want to block a backup if a process is running. An example of this is if there is a critical, resource-intensive task and you cannot afford to have Macrium Agents running simultaneously. Some VPNs will also have a task running when the user is connected to it. By changing ‘process.exe’ to the name of the process that is running, we can block the backups from taking place when connected to the VPN.
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.
More information on security about scripting and Macrium Reflect can be found at the link below:
Whatever you need to do to manage resources and maintain user access to the network, agent user scripting inside Macrium Site Manager is just one of many techniques and tools you can use to ensure safety doesn’t compromise productivity.