Datto RMM contains powerful functionality that allows users to create and share components (bundles of code, data and even applications) that can be executed across multiple devices.
A typical component contains a script, written in one of several available languages, and may also contain a program to install or an executable to run. This functionality guarantees that administrators have complete control over the technology they supervise.
A scripting language is a programming language that supports scripts, programs written for a special run-time environment that can interpret (rather than compile) and automate the execution of tasks that could alternatively be executed one-by-one by a human operator.
Datto RMM supports the following scripting languages, which allow you to develop scripts that can be run across a wide range of devices and operating systems:
- Unix (Bash)
Supported versions: PowerShell 2.0 and later
Windows: Python 2.x. Note that Datto RMM relies on the Python 2.7.x installation directory being present in the endpoint's PATH System Environment Variable. Therefore, we recommend installing Python 2.7.x from the MSI provided at www.python.org.
macOS: Python 2.x. Datto RMM will use the Python interpreter that comes pre-installed.
Linux: Python 2.x. Datto RMM will use the Python interpreter that comes pre-installed.
We will discuss the three most widely used scripting languages from that list.
UDF variables enable you to reference platform data in components, and can be used in any scripting language. Use the variable name UDF_X, where X is the number corresponding to the UDF you want to reference (for example, in Batch scripts, %UDF_1%, %UDF_2%, and so forth).
Refer to User-defined fields for information about how to configure UDFs.
By default, all scripts are executed in the Windows LocalSystem Account (otherwise known as NT AUTHORITY\SYSTEM). This has the advantage of running with extensive privileges on the local endpoint, and script execution is possible even if nobody is logged on or the logged on user has Limited User rights.
Points of note for the LocalSystem Account:
- Does not have a visible desktop. Windows generated here will be hidden and cannot be interacted with. For example, installers with "Next" buttons will hang in memory waiting for input that cannot be delivered.
- Does not have a virtual keyboard or mouse, so no macro-based automation is possible.
- Does not have a password, so no network authentication is possible.
- Does not have access to resources defined per user, such as mapped network drives.
Quick jobs always run in the LocalSystem Account but it is possible to force the execution of a script to run in the context of the local logged on user by opting to a Scheduled Job and using the advanced options under Execution. Refer to Execution.
Support covers the following:
- Troubleshoot jobs associated to scripts/components
- Investigate if a script runs successfully outside of Datto RMM but does not run successfully in Datto RMM
Support does not cover custom script/component creation. Customers are advised to contact their Account Manager for a Professional Services engagement if they require assistance with script/component creation.
About Batch scripts
Batch is the most compatible and widely-used scripting language across Windows systems. Although it has been around since MS-DOS times, the syntax and certain commands have remained much the same.
A Batch file is a kind of script file in DOS, OS/2 and Windows. It consists of a series of commands to be executed by the command line interpreter, stored in a plain text file. It is typically created by using a text editor such as Notepad or a word processor in text mode, and then saving it with a .bat extension.
The script could be as simple as a single line, or a more complex process involving loops and subroutines. Generally, scripts that can be run locally can also be executed via Datto RMM, on multiple devices, either one time or on a recurring schedule.
Here is an example:
ECHO Good Morning, Dave!
When executed, the following is displayed:
Good Morning, Dave!
To input a command in Batch format, there are no special considerations – your scripts will not require a header to begin the script, and you are not required to precede execution of your script with any special steps. Simply prepare or paste your Batch scripts in the Command text box.
In addition to UDF variables, Batch scripts support the use of the following variables:
- Windows environment variables (for example, %username% or %logonserver%).
- Variables you define yourself in the script. The user running this script will receive a prompt to use the default value for the variable when running the script, or to enter a different value.
In the above screenshot, we created an input variable called "FileName", with a default value of "Test.txt". When we create a component monitor, for instance, we can specify the value that the component monitor should be set to when it runs:
Define temporary environment variables in the Variables section of the Component page. Refer to Input variables.
Files that have been attached to the component using the file attachment fields beneath the script edit-box can be referenced directly. For example, if your component was to install the Windows Installer file install.msi, your code might look like this:
msiexec /i install.msi /qn
echo Product Installed Successfully
The file install.msi can be referred to without hard links, because the command shell is being launched from the same directory that contains the executable.
Some users might question the use of the command @echo off which precedes the main script. This function hides the commands being executed from the output, so an end-user, or administrator looking through script output using Datto RMM’s StdOut/StdErr viewer won’t see the codes the command shell is running, only the output from them. It's not necessary to include this in any scripts you run, but it does keep the output looking a bit neater.
Its also possible to set up conditions to look for certain text output strings and alert the user if they appear using the Warning Text function at the bottom of the page. This function will look at the output from a script the user has run and generate an alert if anything from the output matches a criteria the user has defined.
If you place the string “ERROR:” (note that it is case sensitive) into the field, then run the script, Datto RMM will spool through the command’s output and, if a string containing “ERROR:” is found, a warning is posted.
These warnings appear as an orange status box (as opposed to the traditional green for success and red for failure) and the caption “Warning” on the Jobs page of the Web Portal.
Please note that Datto RMM spools through the output of the command, and not the script. The virtue of such a system is in its extensibility; by setting a post-condition looking for the string "ERROR:", a user is able to place conditions in the script (presumably using the if function) and echo out the string "ERROR: " only in cases where an error occurs in the script.
Administrators who take advantage of this intelligent output analysis when writing their scripts will receive notifications instantly when a script error occurs, instead of being forced to check command outputs for each execution.
PowerShell is Microsoft's answer to the highly-adaptable terminal systems offered by *nix operating systems.
More extensive than Batch, it is constantly being developed and revised by Microsoft engineers (and 3rd parties) with modern computing tasks in mind. Datto RMM can run PowerShell scripts on devices that support it. Version 2.0 ships with Windows 7 by default. It can be obtained for Windows XP and Windows Server 2003.
Not all PowerShell versions are created equal. Version 2.0 (Windows 7) and version 5.0 (Windows 10) support a different feature set. In cases where scripts are going to be run across a varied selection of Windows Operating Systems, Batch is preferred for its compatibility. When using PowerShell, either take care to ensure the commands being used will run on all versions or introduce a version requirement.
To set a minimum version for your PowerShell script, set "#Requires -Version 3" as the first line. The number can reflect whatever minimum version of PowerShell you are working towards. Versions beneath the set threshold will reject the script without running it.
Much like Batch, the scripts launched from any PowerShell command prompt are launched from the package directory of the respective script. This directory is produced by the agent and typically contains the script itself – PowerShell scripts typically have a .ps1 extension (although when sent via the platform they are sent as .bat files) – along with simple metadata and any files the user has attached.
Because of this, to refer to a file that has been attached to a component, no hardlinks are required, and the file can be referred to without any need to change directories.
If you are writing a script to type the contents of attached document file.txt so it can be read in StdOut, for example, your script would look like this:
Comment lines out in your PowerShell script by placing the "#" character at the beginning of the line and proceeding to type as normal.
You can also define external variables and refer to them in the script using the $ENV: command.
will return the path and directory Windows is installed in.
The following environment variables are also available for use in PowerShell scripting:
- CS_ACCOUNT_UID: The unique identifier for the Datto RMM account managing this device.
- CS_CC_HOST: The control channel uniform resource identifier (URI) used by the Agent to communicate with the Datto RMM platform.
- CS_CC_PORT1: The port through which Agent communications are facilitated: HTTPS 443.
- CS_CSM_ADDRESS: The address for the Web Portal to which this device connects.
- CS_DOMAIN: The local device’s domain, if it is connected to one.
- CS_PROFILE_DESC: The description of the site where this device is located.
- CS_PROFILE_NAME: The name of the site where this device is located.
- CS_PROFILE_PROXY_TYPE: 0 or 1 depending on whether a proxy server is configured for this site.
- CS_PROFILE_UID: The unique identifier for the site where this device is located.
- CS_WS_ADDRESS: The Web Service URI used by the Agent to communicate with the Datto RMM platform.
- UDF_1 - UDF_30: These fields report the data held within the Web Portal for the device’s user-defined fields.
Unix (which includes Linux, as well as a number of other related systems) is less an operating system in and of itself and more a framework built to a set of rigorous standards (“POSIX") from which many compatible forks and projects have been started. Although inconsistencies do exist between *nix projects (referred to in GNU/Linux terminology as “distributions" or “distros"), the scripting technology typically utilized is surprisingly compatible.
macOS is itself based on one of these Unix projects (BSD), and as such we can use Unix scripting to run scripts and deployments to macOS devices.
Datto RMM provides an agent and scripting capabilities for the *nix-based macOS and various Linux versions. For further information, refer to Supported operating systems and Agent requirements.
After you select Unix from the Install command drop-down menu, a line of code will appear in the script field.
This line has been included for your convenience. As part of Datto RMM 's functionality, this line – an operation to choose a command interpreter – must begin any *nix script, including those intended for use on macOS.
The line tells the computer which command interpreter to use – that is to say, it selects a program to manage the lines of the script with. *Nix machines typically have several available, and while certain scripts may demand different interpreters, the Bash interpreter specified in the default line is the most compatible across *nix-based systems.
If you are a novice user or are unsure of this line of code's purpose, please leave it alone. It will not alter the functionality of your code, and removing it may cause your code not to work as you had intended.
Without a code interpreter explicitly selected as the first line of your script, it will not run on your macOS or other *nix-based system.
If you are an experienced user, or your choice of command interpreter differs from the default, please feel free to experiment. You are welcome to edit the initial line of the script; you may even decide to remove it entirely. However, such actions may cause your script to act unpredictably or even fail; you make such alterations at your own risk.
|Need to troubleshoot this? Open the Datto Knowledge Base.|
|Want to talk about it? Head on over to our Community Forum!|
|Forward this topic to others.|
|Provide feedback for the Documentation team.|