From 5c6b106f68cbd5442dca22efb0fbda523495c10f Mon Sep 17 00:00:00 2001 From: sadnub Date: Mon, 26 Apr 2021 23:15:53 -0400 Subject: [PATCH] adding docs for Custom Fields, Scripting, Collector Tasks, and KeyStore --- docs/docs/functions/automated_tasks.md | 9 ++ docs/docs/functions/custom_fields.md | 49 +++++++++-- docs/docs/functions/keystore.md | 9 ++ docs/docs/functions/scripting.md | 110 +++++++++++++++++++++++++ docs/docs/script_variables.md | 39 +++++++++ docs/mkdocs.yml | 3 + 6 files changed, 213 insertions(+), 6 deletions(-) create mode 100644 docs/docs/functions/automated_tasks.md create mode 100644 docs/docs/functions/keystore.md create mode 100644 docs/docs/functions/scripting.md create mode 100644 docs/docs/script_variables.md diff --git a/docs/docs/functions/automated_tasks.md b/docs/docs/functions/automated_tasks.md new file mode 100644 index 00000000..2d7a2e8e --- /dev/null +++ b/docs/docs/functions/automated_tasks.md @@ -0,0 +1,9 @@ +# Automated Tasks + +## Collector Tasks + +Collector tasks allow saving data from script output directly to a custom field. The collector task will only save the last line of standard output of the script. + +You can create collector tasks by adding it to an Automation Policy or adding it directly to an agent. During creation, select the **Collector** checkbox and select the custom field to save to. You can only save to agent custom fields at this time. + +See [Custom Fields](custom_fields.md) and [Scripting](scripting.md) for more information \ No newline at end of file diff --git a/docs/docs/functions/custom_fields.md b/docs/docs/functions/custom_fields.md index 7019ad33..15a8c622 100644 --- a/docs/docs/functions/custom_fields.md +++ b/docs/docs/functions/custom_fields.md @@ -1,16 +1,53 @@ # Custom Fields -**Settings > Global Settings > Custom Fields** +!!!info + v0.5.0 adds support for custom fields to be used in the dashboard and in scripts. -v0.5.0 adds support for custom fields to be used in scripts. +#### Adding Custom Fields -It also exposes some pre-defined fields that are already in the database. +In the dashboard, go to **Settings > Global Settings > Custom Fields** and click **Add Custom Field**. -Please check the following video for examples until proper docs are written: +The following options are available to configure on custom fields: -[https://www.youtube.com/watch?v=0-5jGGL3FOM](https://www.youtube.com/watch?v=0-5jGGL3FOM) +- **Model** - This is the object that the custom field will be added to. The available options are: + - Agent + - Site + - Client +- **Name** - Sets the name of the custom field. This will be used to identify the custom field in the dashboard and in scripts. +- **Field Type** - Sets the type of field. Below are the allowed types. + - Text + - Number + - Single select dropdown + - Multi-select dropdown + - Checkbox + - DateTime +- **Input Options** - *Only available on Single and Multiple-select dropdowns*. Sets the options to choose from. +- **Default Value** - If no value is found when looking up the custom field; this value will instead be supplied. +- **Required** - This makes the field required when adding new Clients, Sites, and Agents. *If this is set a default value will need to be set as well* +- **Hide in Dashboard** - This will not show the custom field in Client, Site, and Agent forms in the dashboard. This is useful if the custom field's value is updated by a collector task and only supplied to scripts. +#### Using Custom Fields in the Dashboard +Once the custom fields are added, they will show up in the Client, Site, and Agent Add/Edit forms. +#### Using Custom Fields in Scripts - \ No newline at end of file +Tactical RMM allows for passing various database fields for Clients, Sites, and Agents in scripts. This includes custom fields as well! + +!!!warning + The characters within the brackets is case-sensitive! + +In your script's arguments, use the notation `{{client.AV_KEY}}`. This will lookup the client for the agent that the script is running on and find the custom field named `AV_KEY` and replace that with the value. + +The same is also true for `{{site.no_patching}}` and `{{agent.Another Field}}` + +For more information see SCRIPTING PAGE + +#### Populating Custom Fields automatically + +Tactical RMM supports automatically collecting information and saving them directly to custom fields. This is made possible by creating **Collector Tasks**. These are just normal Automated Tasks, but instead they will save the last line of the standard output to the custom field that is selected. + +!!!info + To populate a multiple select custom field, return a string with the options separated by a comma `"This,will,be,an,array"` + +For more information See [Collector Tasks](automated_tasks.md#Collector Tasks) diff --git a/docs/docs/functions/keystore.md b/docs/docs/functions/keystore.md new file mode 100644 index 00000000..d78ec73d --- /dev/null +++ b/docs/docs/functions/keystore.md @@ -0,0 +1,9 @@ +# Global Key Store + +The key store is used to store values that need to be referenced from multiple scripts. This also allows for easy updating of values since scripts reference the values at runtime. + +To Add/Edit values in the Global Key Store, browse to **Settings > Global Settings > KeyStore**. + +You can reference values from the key store in script arguments by using the {{global.key_name}} syntax. + +See [Scripts](scripting.md) for more information. \ No newline at end of file diff --git a/docs/docs/functions/scripting.md b/docs/docs/functions/scripting.md new file mode 100644 index 00000000..dbe51ab0 --- /dev/null +++ b/docs/docs/functions/scripting.md @@ -0,0 +1,110 @@ +# Scripting + +Tactical RMM supports uploading existing scripts or adding new scripts right in the dashboard. Languages supported are: + +- Powershell +- Windows Batch +- Python + +## Adding Scripts +In the dashboard, browse to **Settings > Scripts Manager**. Click the **New** button and select either Upload Script or New Script. The available options for scripts are: + +- **Name** - This identifies the script in the dashboard +- **Description** - Optional description for the script +- **Category** - Optional way to group similar scripts together. +- **Type** - This sets the language of the script. Available options are: + - Powershell + - Windows Batch + - Python +- **Script Arguments** - Optional way to set default arguments for scripts. These will autopopulate when running scripts and can be changed at runtime. +- **Default Timeout** - Sets the default timeout of the script and will stop script execution if the duration surpasses the configured timeout. Can be changed at script runtime +- **Favorite** - Favorites the script. + +## Downloading Scripts + +To download a Tactical RMM Script, click on the script in the Script Manager to select it. Then click the **Download Script** button on the top. You can also right-click on the script and select download + +## Community Script + +These are script that are built into Tactical RMM. They are provided and mantained by the Tactical RMM community. These scripts are updated whenever Tactical RMM is updated and can't be modified or deleted in the dashboard. + +### Hiding Community Scripts +You can choose to hide community script throughout the dashboard by opening **Script Manager** and clicking the **Show/Hide Community Scripts** toggle button. + +## Using Scripts + +### Manual run on agent + +In the **Agent Table**, you can right-click on an agent and select **Run Script**. You have the options of: + - **Wait for Output** - Runs the script and waits for the script to finish running and displays the output. + - **Fire and Forget** - Starts the script and does not wait for output. + - **Email Output** - Starts the script and will email the output. Allows for using the default email address in the global settings or adding a new email address. + +There is also an option on the agent context menu called **Run Favorited Script**. This will essentially Fire and Forget the script with default args and timeout. + +### Bulk Run on agents + +Tactical RMM offers a way to run a script on multiple agents at once. Browse to **Tools > Bulk Script** and select the target for the script to run. + +### Automated Tasks + +Tactical RMM allows scheduling tasks to run on agents. This leverages the Windows Task Scheduler and has the same scheduling options. + +See [Automated Tasks](automated_tasks.md) for configuring automated tasks + +### Script Checks + +Scripts can also be run periodically on an agent and trigger an alert if it fails. + +### Alert Failure/Resolve Actions + +Scripts can be triggered when an alert is triggered and resolved. This script will run on any online agent and supports passing the alert information as arguments. + +For configuring **Alert Templates**, see [Alerting](../alerting.md) + +See below for populating dashboard data in scripts and the available options. + +## Using dashboard data in scripts + +Tactical RMM allows passing in dashboard data to scripts as arguments. The below powershell arguments will get the client name of the agent and also the agent's public IP address + +``` +-ClientName {{client.name}} -PublicIP {{agent.public_ip}} +``` + +!!!info + Script variables are case-sensitive! + +See a full list of available options [Here](../script_variables.md) + +### Getting Custom Field values + +Tactical RMM supports pulling data from custom fields using the {{model.custom_field_name}} syntax. + +See [Using Custom Fields in Scripts](custom_fields.md#Using Custom Fields in Scripts) + +### Getting values from the Global Keystore + +Tactical RMM supports getting values from the global key store using the {{global.key_name}} syntax + +See [Global Keystore](keystore.md). + +### Example Powershell Script + +The below script takes five named values. The arguments will look like this: `-SiteName {{site.name}} -ClientName {{client.name}} -PublicIP {{agent.public_ip}} -CustomField {{client.AV_KEY}} -Global {{global.API_KEY}}` + +```powershell +param ( + [string] $SiteName, + [string] $ClientName, + [string] $PublicIp, + [string] $CustomField, + [string] $Global +) + +Write-Output "Site: $SiteName" +Write-Output "Client: $ClientName" +Write-Output "Public IP: $PublicIp" +Write-Output "Custom Fields: $CustomField" +Write-Output "Global: $Global" +``` diff --git a/docs/docs/script_variables.md b/docs/docs/script_variables.md new file mode 100644 index 00000000..440c7e43 --- /dev/null +++ b/docs/docs/script_variables.md @@ -0,0 +1,39 @@ +# Script Variables + +Tactical RMM allows passing dashboard data into script as arguments. This uses the syntax `{{client.name}}`. + +See below for the available options. + +## Agent + +- **{{agent.version}}** - Tactical RMM agent version +- **{{agent.operating_system}}** - Agent operating system example: *Windows 10 Pro, 64 bit (build 19042.928)* +- **{{agent.plat}}** - Will show the platform example: *windows* +- **{{agent.hostname}}** - The hostname of the agent +- **{{agent.public_ip}}** - Public IP address of agent +- **{{agent.total_ram}}** - Total RAM on agent. Returns an integer - example: *16* +- **{{agent.boot_time}}** - Uptime of agent. Returns unix timestamp. example: *1619439603.0* +- **{{agent.logged_in_user}}** - Username of logged in user +- **{{agent.monitoring_type}}** - Returns a string of *workstation* or *server* +- **{{agent.description}}** - Description of agent in dashboard +- **{{agent.mesh_node_id}}** - The mesh node id used for linking the tactical agent to mesh. +- **{{agent.choco_installed}}** - Boolean to see if Chocolatey is installed +- **{{agent.patches_last_installed}}** - The date that patches were last installed by Tactical RMM. +- **{{agent.needs_reboot}}** - Returns true if the agent needs a reboot +- **{{agent.time_zone}}** - Returns timezone configured on agent +- **{{agent.maintenance_mode}}** - Returns true if agent is in maintenance mode + +## Client +- **{{client.name}}** - Returns name of client + +## Site +- **{{site.name}}** - Returns name of Site + +## Alert + +!!!info + Only available in failure and resolve actions on alert templates! + +- **{{alert.alert_time}}** - Time of the alert +- **{{alert.message}}** - Alert message +- **{{alert.severity}}** - Severity of the alert *info, warning, or error* diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3bf70e56..57ca045d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -12,6 +12,9 @@ nav: - "Updating the RMM (Docker)": update_docker.md - "Updating Agents": update_agents.md - Functionality: + - "Automated Tasks": functions/automated_tasks.md + - "Scripting": functions/scripting.md + - "Global Keystore": functions/keystore.md - "Custom Fields": functions/custom_fields.md - "Remote Background": functions/remote_bg.md - "Maintenance Mode": functions/maintenance_mode.md