diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 00000000..be6f651a --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,15 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Run MkDocs", + "type": "python", + "request": "launch", + "program": "${workspaceFolder}/env/Scripts/mkdocs", + "args": [ + "serve" + ], + "preLaunchTask": "Run MkDocs" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json index c3dd0dad..e29bb57e 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,14 +3,17 @@ "Splashtop" ], "cSpell.words": [ + "aarch", "aclcrt", "agentstats", "agentupdate", "allowfullscreen", "Amidaware", "anydesk", + "arecords", "asgi", "ashx", + "Authy", "autoagentupdate", "Axxxxxxx", "backendpool", @@ -37,24 +40,31 @@ "createsuperuser", "CXXXXXXXXXXXXXXXXX", "defaultrule", + "Deno", + "devs", "dinger", "distro", "dnschallenge", + "dnstxt", "dnsutils", "DOMAINNAME", "dontlognull", "DWORD", "entrypoints", + "exitcode", "fontawesome", "forwardfor", "Forwardto", "freepbx", "frontends", "fullchain", + "gantt", "gettingstarted", "grafana", "gravityzone", "healthcheck", + "helpdesk", + "Hetzner", "HKEY", "howitallworks", "httpclose", @@ -62,6 +72,7 @@ "inlinehilite", "INNO", "inspectiondelay", + "irulez", "isnull", "journalctl", "ldez", @@ -79,6 +90,7 @@ "meshrelay", "middlewares", "MITM", + "Moba", "mongod", "mongopass", "mongouser", @@ -95,6 +107,8 @@ "nofile", "nokeepalive", "nopush", + "Nushell", + "onprem", "opnsensetcp", "pidfile", "postgrespass", @@ -106,6 +120,7 @@ "proxying", "proxypass", "psycopg", + "PWSH", "pycparser", "pycryptodome", "pymdownx", @@ -120,8 +135,10 @@ "resetaccount", "rlimit", "RMM's", + "rmmlogin", "sadnub", "screenconnect", + "Sekret", "sendfile", "serverlist", "silversword", @@ -147,6 +164,7 @@ "twemoji", "txnhost", "txnpath", + "txtrecord", "unins", "Upstreams", "urllib", @@ -154,12 +172,14 @@ "usesrc", "uwsgi", "VERYSILENT", + "Vultr", "walkthru", "Webroot", "websockets", "WSGI", "yourdomain", "YOURWANIP", + "Zammad", "Zerotier", "zipp" ] diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000..c9ab888d --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,39 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Activate Python Environment", + "type": "shell", + "command": "python -m venv env; .\\env\\Scripts\\activate", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + }, + { + "label": "Install Requirements", + "type": "shell", + "command": "python -m pip install --upgrade pip; pip install --upgrade setuptools wheel; pip install -r requirements.txt", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + } + }, + { + "label": "Run MkDocs", + "type": "shell", + "command": "Start-Process http://localhost:8005; mkdocs serve", + "problemMatcher": [], + "group": { + "kind": "build", + "isDefault": true + }, + "dependsOn": [ + "Activate Python Environment", + "Install Requirements" + ] + } + ] +} diff --git a/docs/3rdparty_zammad.md b/docs/3rdparty_zammad.md new file mode 100644 index 00000000..6c131759 --- /dev/null +++ b/docs/3rdparty_zammad.md @@ -0,0 +1,64 @@ +### Zammad Setup + +1. **Install Zammad:** + Follow the installation instructions provided in the [Zammad documentation](https://docs.zammad.org/en/latest/). + +2. **Generate API Token:** + - Click on your User Initials in Zammad. + - Navigate to Profile > Token Access. + - Click "Create". + - Name the Token "Tactical RMM" and select "Ticket Agent". + - Click "Create" to generate the token. + +3. **Add Customers and Emails:** + Ensure each customer in Zammad has a corresponding email associated. + +--- + +### Tactical RMM Setup + +1. **Add Custom Field in Sites:** + - Add a custom field under Sites called `Zammad-Email` + - Populate this field with the corresponding email addresses from Zammad to match up with customers. + +2. **Add Webhook:** + + - **URL Pattern:** `https://your_zammad_domain.com/api/v1/tickets` + - **Method:** POST + +3. **Request Headers:** + ```json + { + "Content-Type": "application/json", + "Authorization": "Bearer your_generated_token_here" + } + ``` + +Replace your_generated_token_here with the actual API token generated from Zammad. + +4. **Request Body:** +```json +{ +"title": "{{ alert.severity }} on {{ agent.hostname }}", +"group": "Users", +"customer": "{{ client.Zammad-Email }}", +"article": { + "subject": "{{ alert.severity }} on {{ agent.hostname }}", + "body": "Client: {{agent.site.client.name}}, Site: {{agent.site.name}}: {{ alert.message }} at {{ alert.alert_time }}", + "type": "note", + "internal": false +} +} +``` +- `{{ alert.severity }}`, `{{ agent.hostname }}`, `{{ alert.message }}`, and `{{ alert.alert_time }}` are placeholders that will be replaced with actual data from Tactical RMM alerts. +- `{{ client.Zammad-Email }}` refers to the custom field you added under Sites where you store the corresponding Zammad email for each customer. + +5. **Add Webhook to Alert Policy**: + + - Assign the webhook to the appropriate Alert Policy that is assigned to customers in Tactical RMM. + +### Notes: + +- Ensure that the API token in the Authorization header (Bearer your_generated_token_here) has the necessary permissions (e.g., ticket.agent) to create tickets in Zammad. +- Adjust the title, group, customer, article fields in the request body as per your specific requirements and Zammad's API capabilities. +- Test the integration thoroughly to ensure that alerts from Tactical RMM are correctly creating tickets in Zammad with the expected data. \ No newline at end of file diff --git a/docs/faq.md b/docs/faq.md index 1f08cd46..7635413b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -261,6 +261,25 @@ You can help yourself by running [this](troubleshooting.md#server-troubleshootin If you would like us to do it for you please [contact support](support.md#commercial-support). +## Should I use a Check or a Task? + +Checks + +- Run every 2-1440 mins (1 day max) +- Results are naturally graphed, and not logged to the agents "History" tab + +Tasks + +- Is run using the Windows Task Scheduler on the agent. +- Although multiple times/day can be scheduled it's complicated and will clutter up your "History" tab. +- Best for periodic script runs that run daily/weekly/monthly/onboarding/once + ## Is Tactical RMM vulnerable to Log4j No. + +## Terminology + +Code Signing: A windows .exe cryptographic signing process that can't be forged. The only want to reliably whitelist your TRMM agent is to have a Code signed agent that you can give the signers public key to your security software to whitelist. + +Mac/Linux Pre-Compiled binaries: Are provided by Amidaware so you can install agents on Mac and Linux. This requires [sponsorship](sponsor.md). If you want to test Mac/Linux agents please contact [support](ttps://support.amidaware.com) and open a ticket to request a 7 day hosted trial. diff --git a/docs/functions/alerting.md b/docs/functions/alerting.md index 472890b0..da3b1c52 100644 --- a/docs/functions/alerting.md +++ b/docs/functions/alerting.md @@ -9,25 +9,27 @@ Using Alert Templates also enables additional features like: - Sending notifications when an alert is resolved. - Executing scripts when an alert is triggered or resolved. -[Setting up Email Alert Examples](email_alert.md) +[Setting up Email Alert Examples](emailsms_alert.md) + ## Supported Notifications - **Email Alerts** - Sends email to configured set of email addresses. - **SMS Alerts** - Sends text messages to configured set of numbers. - **Dashboard Alerts** - A notification popup will show up and be visible in the dashboard. +- **Webhooks** - Send an API request. ## Alert Severities !!!info - Agent overdue alerts are always of severity Error. + Agent overdue alerts are always of severity: `Error` -Alert severities are configured directly on the Check or Automated Task. When the Check / Automated Task fails, it will create an alert of the specified severity. The severity types are: +Alert severities are configured directly on the Check or Automated Task. When the Check or Automated Task fails, it will create an alert of the specified severity. The severity types are: - Informational - Warning - Error -## Adding Alert Templates +## Creating Alert Templates To create an alert template, go to **Settings > Alerts Manager**, then click **New**. @@ -40,22 +42,139 @@ The available options are: - **From Email** - Sets the From email address of the notification. If this isn't set the From address from global settings is used. - **SMS Recipients** - Sets the list of text recipients. If this isn't set the sms list from global settings is used. -### Action Settings +### Alert Action Settings + +For optionally triggering an additional task (Send a Web Hook, Run Script on Agent, Run script on TRMM Server) when desired (can be left blank for no action). + +#### Alert Failure Settings / Alert Resolved Settings + +#### Send a Web Hook + +You can create your own webhooks to be sent out on alert failure/resolved events, like a script check or task failing or an agent going overdue. + +You have access to any of the [variables](https://docs.tacticalrmm.com/script_variables/) as well as [custom fields](custom_fields.md) / [global keystore](keystore.md) inside the json payload of the webhook as well as in the URL patter. + +1. Create your [Web Hooks](webhooks.md) + +2. Choose the Web Hook you wish to be ran as the alert failure and/or resolved action. + +#### Run script on Agent + +- **Script** - Runs the selected script once. It attempts to run it on the agent in question, but if not online TRMM selects a random agent to run on. +- **Script arguments** - Optionally pass in arguments to the failure script. +- **Script environment vars** - Optionally pass in env vars to the failure script. +- **Action Timeout** - Sets the timeout for the script. + +#### Run script on Server + +!!!warning + This is a [dangerous feature](../functions/permissions.md#permissions-with-extra-security-implications) and you must ensure permissions are appropriate for your environment. + +
+ +
+ +This runs the script on your TRMM server. To ensure proper execution, you must specify the interpreter for your script using a shebang line at the top of each script. Also make sure that the specified interpreter is installed on your TRMM server. + + + +=== ":material-language-python: Python (included with TRMM)" + + Shell type: `Shell` + + ```py + #!/rmm/api/env/bin/python + + import sys + + print(sys.version) + ``` + +=== ":material-language-python: Python (system python)" + + Shell type: `Shell` + + ```py + #!/usr/bin/python3 + import sys + + print(sys.version) + ``` + +=== ":material-bash: Bash" + + Shell type: `Shell` + + ```bash + #!/usr/bin/env bash + + echo "hello world" + ``` -- **Failure Action** - Runs the selected script once on any agent. This is useful for running one-time tasks like sending an http request to an external system to create a ticket. -- **Failure Action Args** - Optionally pass in arguments to the failure script. -- **Failure Action Timeout** - Sets the timeout for the script. -- **Resolved Action** - Runs the selected script once on any agent if the alert is resolved. This is useful for running one-time tasks like sending an http request to an external system to close the ticket that was created. -- **Resolved Action Args** - Optionally pass in arguments to the resolved script. -- **Resolved Action Timeout** - Sets the timeout for the script. +=== ":material-powershell: Powershell (7 PWSH)" + + To install: + + Shell type: `Powershell` + + ```powershell + #!/usr/bin/pwsh + + Write-Output "Hello World" + ``` + +=== ":material-nodejs: node (included with TRMM)" + + Shell type: `Shell` + + ``` + #!/usr/bin/node + + console.log("Hello World") + ``` + +=== ":simple-deno: deno (must be installed)" + + Shell type: `Deno` + + ``` + #!/usr/bin/env -S /usr/local/bin/deno run --allow-allow + + async function gatherSystemInfo() { + const os = Deno.build.os; + const arch = Deno.build.arch; + const memory = Deno.systemMemoryInfo(); + + + const info = ` + OS: ${os} + Architecture: ${arch} + Total Memory: ${(await memory).total / 1024 / 1024} MB + Free Memory: ${(await memory).free / 1024 / 1024} MB + `; + + console.log(info); + } + + gatherSystemInfo().catch(console.error); + ``` + +- **Script** - Runs the selected script once on the TRMM server. +- **Script arguments** - Optionally pass in arguments to the failure script. +- **Script environment vars** - Optionally pass in env vars to the failure script. +- **Action Timeout** - Sets the timeout for the script. + +#### Run actions only on + +Turn the switch on if you want the above Alert Failure/Alert Resolved script to run on: -#### Run Actions Only On: - **Agents** - If Enabled, will run script failure / resolved actions on agent overdue alerts, else no alert actions will be triggered for agent overdue alerts. - **Checks** - If Enabled, will run script failure / resolved actions on check alerts, else no alert actions will be triggered check alerts. - **Tasks** - If Enabled, will run script failure / resolved actions on automated task alerts, else no alert actions will be triggered automated task alerts. +### Agent Overdue Setting -### Agent / Check / Task Failure Settings +![Agent Overdue](images/alerts_agentoverdue.png) - **Email** - When **Enabled**, will send an email notification and override the Email Alert checkbox on the Agent / Check / Task. When **Not Configured**, the Email Alert checkbox on the Agent / Check / Task will take effect. If **Disabled**, no email notifications will be sent and will override any Email alert checkbox on the Agent / Check / Task. - **Text** - When **Enabled**, will send a text notification and override the SMS Alert checkbox on the Agent / Check / Task. When **Not Configured**, the SMS Alert checkbox on the Agent / Check / Task will take effect. If **Disabled**, no SMS notifications will be sent and will override any SMS Alert checkbox on the Agent / Check / Task. @@ -66,22 +185,31 @@ The available options are: !!!info Alert on Severity needs to be configured for check and task notifications to be sent! -### Agent / Check / Task Resolved Settings +### Check Settings / Automated Task Settings + +![alt text](images/alerts_checks.png) + +![alt text](images/alerts_tasks.png) - **Email** - If enabled, sends an email notification when an alert is resolved. - **Text** - If enabled, sends a text messaged when an alert is resolved. ## Applying Alert Templates -Alert templates can be configured Globally, through an Automation Policy, or set directly on the Client or Site. +Alert templates can be configured: + +- Globally at the [Server Level](global_settings.md#general) +- By [Automation Policy](automation_policies.md) +- Manually at the Client Level +- Manually at the Site Level - To apply **Globally**, navigate to **Settings > Global Settings**. Set the **Alert Template** dropdown and save. - You can configure an alert template on an automation policy by navigating to **Settings > Automation Manager**, and clicking the **Assign Alert Template** click on the policy, or right-clicking the policy and selecting **Assign Alert Template**. -- To configure on a Client or Site, right-click on one in the Client / Site tree view and select **Assign Alert Template**. +- To configure on a Client or Site right-click on one in the Client / Site tree view and select **Assign Alert Template**. ## Alert Template Exclusions -You can exclude Clients, Sites, and Agents from alert templates. To do this you can: +You can exclude Clients, Sites, and Agents from Alert Templates. To do this you can: - Right-click on the **Alert Template** in **Alerts Manager** and select **Exclusions**. - Select the **Alert Exclusions** link in the Alert Template row. @@ -121,4 +249,3 @@ If scripting for alert severities please see below, 2. Setup a script check and fill in the corresponding Warning and Informational codes (don't forget to hit enter). 3. Save script check and you should now have the different Severities. - diff --git a/docs/functions/custom_fields.md b/docs/functions/custom_fields.md index 9a10554b..7f27dd94 100644 --- a/docs/functions/custom_fields.md +++ b/docs/functions/custom_fields.md @@ -1,8 +1,5 @@ # Custom Fields -!!!info - v0.5.0 adds support for custom fields to be used in the dashboard and in scripts. - !!!warning `\` is an escape character, if you want to use that in a custom field you will need to use `\\` instead. diff --git a/docs/functions/database_maintenance.md b/docs/functions/database_maintenance.md deleted file mode 100644 index 863889ed..00000000 --- a/docs/functions/database_maintenance.md +++ /dev/null @@ -1,17 +0,0 @@ -# Database Maintenance - -Tactical RMM ships with data retention defaults that will work fine for most environments. There are situations, depending on the number of agents and checks configured, that these defaults need to be tweaked to improve performance. - -## Adjusting Data Retention - -In the dashboard, go to **Settings > Global Settings > Retention**. - -The options are: - -- **Check History** - Will delete check history older than the days specified (default is 30 days). -- **Resolved Alerts** - Will delete alerts that have been resolved older than the days specified (default is disabled). -- **Agent History** - Will delete agent command/script history older than the days specified (default is 60 days). -- **Debug Logs** - Will delete agent debug logs older than the days specified (default is 30 days). -- **Audit Logs** Will delete Tactical RMM audit logs older than the days specified (default is disabled). - -To disable database pruning on a table, set the days to 0. diff --git a/docs/functions/email_alert.md b/docs/functions/emailsms_alert.md similarity index 75% rename from docs/functions/email_alert.md rename to docs/functions/emailsms_alert.md index 65f358f8..169fd33b 100644 --- a/docs/functions/email_alert.md +++ b/docs/functions/emailsms_alert.md @@ -1,8 +1,10 @@ -# Email Setup +# Email and SMS Setup + +## Email Setup Under **Settings > Global Settings > Email Alerts** -## Setting up Tactical RMM Alerts using Open Relay +### Setting up Tactical RMM Alerts using Open Relay MS 365 in this example @@ -19,7 +21,7 @@ MS 365 in this example 11. Go to Exchange Admin Centre 12. Go to “Connectors” under “Mail Flow” 13. Click to + button -14. In From: select “Your organisations email server” +14. In From: select “Your organizations email server” 15. In To: select “Office 365” 16. Click Next 17. In the Name type in RMM @@ -29,7 +31,7 @@ MS 365 in this example 21. Click Next 22. Click OK -## Setting up Tactical RMM Alerts using username & password +### Setting up Tactical RMM Alerts using username & password Gmail in this example @@ -44,3 +46,13 @@ Gmail in this example 9. Enter your password 10. Change the port to 587 11. Click Save + +## SMS Alerts + +Under **Settings > Global Settings > SMS Alerts** + +Currently Twilio is the only support SMS service + +Setup an Auth Token, and copy the data to the relevant fields + +![twilio](images/trmm_twilio_setup2.png) diff --git a/docs/functions/global_settings.md b/docs/functions/global_settings.md new file mode 100644 index 00000000..3a692c48 --- /dev/null +++ b/docs/functions/global_settings.md @@ -0,0 +1,66 @@ +# Global Settings + +## General + +- Enable agent automatic self update (Recommended setting: Enabled) +- Enable server side scripts +- Enable web terminal +- Default Agent timezone +- Default Date Format +- Default Server Policy +- Default Workstation Policy +- Default Alert Template +- [Receive notifications on](https://www.youtube.com/watch?v=Qh9BfKo2wIg&t=2139s) +- Agent Debug Level +- Clear faults on agents that haven't checked in after (days) +- Reset Patch Policy on Agents + +## Email Alerts + +See [Email Alerts](emailsms_alert.md#email-setup) + +## SMS Alerts + +See [SMS Alerts](emailsms_alert.md#sms-alerts) + +## Meshcentral + +See [Meshcentral](../mesh_integration.md) + +## Custom Fields + +See [Custom Fields](custom_fields.md) + +## (Global) Key Store + +See [Key Store](keystore.md) + +## URL Actions + +See [URL Actions](url_actions.md) + +## Web Hooks + +See [Webhooks](webhooks.md) + +## Retention (TRMM Database) + +These are the settings related to your Tools > Server Maintenance > Prune DB Tables + +Tactical RMM ships with data retention defaults that will work fine for most environments. There are situations, depending on the number of agents and checks configured, that these defaults need to be tweaked to improve performance. + +### Adjusting Data Retention + +The options are: + +- **Check History** - Will delete check history older than the days specified (default is 30 days). +- **Resolved Alerts** - Will delete alerts that have been resolved older than the days specified (default is disabled). +- **Agent History** - Will delete agent command/script history older than the days specified (default is 60 days). +- **Debug Logs** - Will delete agent debug logs older than the days specified (default is 30 days). +- **Audit Logs** Will delete Tactical RMM audit logs older than the days specified (default is disabled). + +To disable database pruning on a table, set the days to 0. + +## API Keys + +See [API](api.md) diff --git a/docs/functions/images/alerts_agentoverdue.png b/docs/functions/images/alerts_agentoverdue.png new file mode 100644 index 00000000..95b5666c Binary files /dev/null and b/docs/functions/images/alerts_agentoverdue.png differ diff --git a/docs/functions/images/alerts_checks.png b/docs/functions/images/alerts_checks.png new file mode 100644 index 00000000..8ec9bd35 Binary files /dev/null and b/docs/functions/images/alerts_checks.png differ diff --git a/docs/functions/images/alerts_tasks.png b/docs/functions/images/alerts_tasks.png new file mode 100644 index 00000000..dc927b2b Binary files /dev/null and b/docs/functions/images/alerts_tasks.png differ diff --git a/docs/functions/images/remote_background_eventlog.png b/docs/functions/images/remote_background_eventlog.png new file mode 100644 index 00000000..27981939 Binary files /dev/null and b/docs/functions/images/remote_background_eventlog.png differ diff --git a/docs/functions/images/remote_background_terminal.png b/docs/functions/images/remote_background_terminal.png new file mode 100644 index 00000000..0a4dc38f Binary files /dev/null and b/docs/functions/images/remote_background_terminal.png differ diff --git a/docs/functions/images/trmm_permissions_scriptnterminal.png b/docs/functions/images/trmm_permissions_scriptnterminal.png new file mode 100644 index 00000000..71b32895 Binary files /dev/null and b/docs/functions/images/trmm_permissions_scriptnterminal.png differ diff --git a/docs/functions/images/trmm_twilio_setup2.png b/docs/functions/images/trmm_twilio_setup2.png new file mode 100644 index 00000000..95a39a8b Binary files /dev/null and b/docs/functions/images/trmm_twilio_setup2.png differ diff --git a/docs/functions/permissions.md b/docs/functions/permissions.md index 1cb68bd1..a1934676 100644 --- a/docs/functions/permissions.md +++ b/docs/functions/permissions.md @@ -16,7 +16,6 @@ Make sure you've setup at least 1 valid (Super User aka Administrator) role unde Once you've set that up a Super User role and assigned your primary user, you can create other Roles with more limited access. - !!!tip If you are only trying to give permissions to one or more sites within a client, but not all of the sites, then leave the "Allowed Clients" field blank and only add sites to "Allowed Sites". If a client is set in "Allowed Clients" that will override any site perms and give access to all sites within that client, regardless of what sites are set. @@ -25,3 +24,32 @@ Once you've set that up a Super User role and assigned your primary user, you ca
+ +## Permissions with extra Security implications + +!!!warning + **DO NOT** use the Web Terminal for running the Tactical [update]() script as it will stop the service running the web terminal and bork your update. + +* Use TRMM Server Web Terminal +* Run Scripts on TRMM Server + +Both of these functions are running under the linux user that you installed TRMM with (usually `tactical` if you followed the docs). + +These have full access to your TRMM server's filesystem and as a result have the ability to become root if you have passwordless sudo enabled. + +These can be very dangerous features if not handled with care so think carefully before you enable/use them. + +These features can be disabled from the web UI in Global Settings. + +![alt text](images/trmm_permissions_scriptnterminal.png) + +They can also be disabled at the filesystem level (which overrides the setting in Global Settings) by adding any of these variables to `/rmm/api/tacticalrmm/tacticalrmm/local_settings.py` + +```py +TRMM_DISABLE_WEB_TERMINAL = True +TRMM_DISABLE_SERVER_SCRIPTS = True +``` + +After adding these make sure they take effect by running `sudo systemctl restart rmm daphne celery celerybeat` + + diff --git a/docs/functions/remote_bg.md b/docs/functions/remote_bg.md index 431043cd..9ee61506 100644 --- a/docs/functions/remote_bg.md +++ b/docs/functions/remote_bg.md @@ -2,7 +2,31 @@ To access: **Right click** on an agent > **Remote Background** -#### Services Tab +## Terminal Tab + +Meshcentral Integration: This will allow you to open a terminal on the remote agent. + +![Terminal Menu](images/remote_background_terminal.png) + +Right-clicking will allow: + +- Admin Shell +- Admin PowerShell +- User Shell +- User PowerShell +- Ask Admin Shell +- Ask Admin PowerShell +- Ask User Shell +- Ask User PowerShell + +!!!tip + If you don't see any Connect button in the top left the problem is either the TRMM user doesn't have meshcentral permissions or the mesh agent is having connectivity problems. Try either the "Recover Connection" button or script "TacticalRMM - Check Mesh Agent for problems" + +## File Browser + +Meshcentral Integration: This will allow you to open a File Manager where you can manage and transfer files to and from the agent. + +## Services Tab Right click on a service to show the context menu where you can start/stop/restart services: @@ -12,10 +36,16 @@ Click *Service Details* to bring up the details tab where you can edit more serv ![service_detail](../images/service_detail.png) -#### Processes Tab +## Processes Tab A very basic task manager that shows real time process usage. **Right click** on a process to end the task: ![taskmanager](../images/taskmanager.png) + +## Event Log + +Allows you to query the Windows Application | System | Security Logs + +![Event Log](images/remote_background_eventlog.png) diff --git a/docs/functions/scripting.md b/docs/functions/scripting.md index 1f9028da..52f691e7 100644 --- a/docs/functions/scripting.md +++ b/docs/functions/scripting.md @@ -18,42 +18,6 @@ Linux/Mac languages supported: - nu - deno (Javascript and TypeScript) -## Writing Your Own Scripts - -Guidelines for Writing Non-Interactive Scripts for Tactical RMM -Tactical RMM can play a crucial role in managing IT infrastructure efficiently. Scripts used should ideally be non-interactive to ensure they can run without manual intervention, streamlining operations and automating routine tasks. Here are some guidelines for writing effective non-interactive scripts for use with Tactical RMM: - -1. Design for Automation -- Non-Interactive Execution: Scripts should execute without requiring user input. Use default values and configuration files to control behaviour instead of interactive prompts. -- Idempotency: Ensure scripts can be run multiple times without causing issues, producing the same results without unintended side effects. -2. Error Handling and Logging -- Comprehensive Error Handling: Anticipate potential errors and handle them gracefully within the script. Avoid crashes or uncontrolled exits. -- Logging: Implement detailed logging mechanisms. Logs should capture key events, errors, and status messages to aid in troubleshooting and auditing. -3. Use Clear, Understandable Code -- Code Readability: Write code that is easy to understand and maintain. Use comments judiciously to explain the purpose of functions and complex logic. -- Modular Design: Break down scripts into functions or modules based on functionality. This enhances readability and reuse. -4. Security Best Practices -- Secure Coding: Avoid common security pitfalls, such as hard-coding sensitive information. Use secure methods to handle credentials and other confidential data. -- Minimize Privileges: Run scripts with the least privilege necessary to accomplish the task. -5. Testing and Validation -- Comprehensive Testing: Test scripts in a controlled environment before deploying them through the Tactical RMM. Consider edge cases and test under different conditions to ensure reliability. Generally test first locally on a test machine, then use Remote Background before adding to script manager. -- Validation: Validate outputs and effects of the script to ensure they align with expectations. Use checks within the script to confirm actions were successful. -6. Documentation -- Internal Documentation: Include header comments in each script detailing its purpose, author, date, and any prerequisites or dependencies. -7. Environment Compatibility -- Cross-Platform Considerations: If scripts are expected to run in diverse environments, account for differences in operating systems, shell versions, and available utilities. -- Dependencies: Clearly document any external dependencies. Prefer built-in tools and commands to minimize dependency issues. -8. Feedback and Reporting -- Status Reporting: Ensure scripts report their completion status back to the Tactical RMM, allowing for automated monitoring and alerting on failures or critical events. -- Feedback Loops: Incorporate feedback from script execution into continuous improvement processes. Refine scripts based on operational experience and evolving requirements. -9. Version Control -- Change Management: Use version control systems (e.g., Git) to manage script versions. Track changes and maintain a history of modifications for audit and rollback purposes. -10. Compliance and Standards -- Follow Standards: Adhere to coding standards and best practices for the scripting languages being used. -- Compliance: Ensure scripts comply with organizational policies and regulatory requirements, especially those handling data privacy and security. - -By following these guidelines, you can create robust, secure, and efficient non-interactive scripts that leverage the full capabilities of Tactical RMM to automate and streamline IT management tasks. - ## 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: @@ -146,7 +110,7 @@ Important: When utilizing PowerShell scripts and manually assigning an exit code ### 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. +Scripts can be triggered when an alert is triggered and resolved. For configuring **Alert Templates**, see [Alerting](./alerting.md) @@ -211,12 +175,43 @@ Command: `Start-Process nohup 'pwsh -noprofile -c "1..120 | % { Write-Host . -No ## Python -Tactical installs Python 3.8 on Windows and uses the default Python on other OS's. It is suggested to write code -[targeting][] Python 3.8 to prevent incompatibilities across platforms. - +### Python on windows +Tactical ships with a portable python distribution on windows. + +| OS | Version | +| --- | --- | +| Windows >= 8.1 | 3.11.9 | +| Windows < 8.1 | 3.8.7 | + +The following 3rd party packages are also bundled with this distribution: + +- [cryptography][] +- [httpx][] +- [msgpack][] +- [psutil][] +- [pysnmplib][] +- [pywin32][] +- [pywin32-ctypes][] +- [requests][] +- [websockets][] +- [WMI][] +- [validators][] + +[cryptography]: https://github.com/pyca/cryptography +[httpx]: https://github.com/encode/httpx +[msgpack]: https://github.com/msgpack/msgpack-python +[psutil]: https://github.com/giampaolo/psutil +[pysnmplib]: https://github.com/pysnmp/pysnmp +[pywin32]: https://github.com/mhammond/pywin32 +[pywin32-ctypes]: https://github.com/enthought/pywin32-ctypes +[requests]: https://github.com/psf/requests +[websockets]: https://github.com/python-websockets/websockets +[WMI]: https://timgolden.me.uk/python/wmi/index.html +[validators]: https://github.com/python-validators/validators + +### Python on posix How do you target a specific version? The [shebang][] can specify the interpreter on macOS and Linux, but since Windows -does not use the shebang, the interpreter needs to be specified by the calling program. This is probably why Python -is installed by TRMM on Windows because it knows where the Python executable is. +does not use the shebang, the interpreter needs to be specified by the calling program. Ok, so how do you use the shebang? Take this hello world script for example. The shebang `#!` in this script will use `/usr/bin/python3`. This is easy enough until you run across a system where the system Python is not the expected @@ -276,7 +271,7 @@ are treated the same. | OS | Python version | Installed by TRMM | | --------------------------------------- | ---------------------------- | ----------------- | -| Windows | 3.8 | Yes | +| Windows | 3.11 | Yes | | Linux, Debian 10 (Buster) (end of life) | 3.7 | No | | Linux, Debian 11 (Bullseye) | 3.9 | No | | Linux, Debian 12 (Bookworm) | 3.12 | No | diff --git a/docs/functions/snmp_checks.md b/docs/functions/snmp_checks.md new file mode 100644 index 00000000..1abd5ec5 --- /dev/null +++ b/docs/functions/snmp_checks.md @@ -0,0 +1,57 @@ +# SNMP Checks + +*Version added: Tactical RMM v0.19.0 / Agent v2.8.0* + +### Video Walkthru + +
+ +
+ +SNMP monitoring can now be done using the `pysnmplib` library included with the [portable python distribution](./scripting.md#python-on-windows) on windows agents. + +Here is a sample script (written by ChatGPT) that can be used to query and monitor a printer. It takes the printer's IP address as the first argument. + +```python +#!/usr/bin/python3 + +import sys +from pysnmp.hlapi import * + +if len(sys.argv) != 2: + print("Missing required argument: snmp device IP address") + sys.exit(1) + +printer_ip = sys.argv[1] +community_string = 'public' + +oids = { + 'Printer Model': '1.3.6.1.2.1.1.1.0', + 'Total Page Count': '1.3.6.1.2.1.43.10.2.1.4.1.1', + 'Toner Level Black': '1.3.6.1.2.1.43.11.1.1.9.1.1', + 'Toner Level Cyan': '1.3.6.1.2.1.43.11.1.1.9.1.2', + 'Toner Level Magenta': '1.3.6.1.2.1.43.11.1.1.9.1.3', + 'Toner Level Yellow': '1.3.6.1.2.1.43.11.1.1.9.1.4', + 'Device Status': '1.3.6.1.2.1.25.3.2.1.5.1', + 'Serial Number': '1.3.6.1.2.1.43.5.1.1.17.1', +} + +for name, oid in oids.items(): + iterator = getCmd( + SnmpEngine(), + CommunityData(community_string, mpModel=0), + UdpTransportTarget((printer_ip, 161)), + ContextData(), + ObjectType(ObjectIdentity(oid)) + ) + + errorIndication, errorStatus, errorIndex, varBinds = next(iterator) + + if errorIndication: + print(f"Error: {errorIndication}") + elif errorStatus: + print(f'Error: {errorStatus.prettyPrint()} at {errorIndex and varBinds[int(errorIndex) - 1] or "?"}') + else: + for varBind in varBinds: + print(f'{name}: {varBind[1]}') +``` \ No newline at end of file diff --git a/docs/functions/web_terminal.md b/docs/functions/web_terminal.md new file mode 100644 index 00000000..52baebe0 --- /dev/null +++ b/docs/functions/web_terminal.md @@ -0,0 +1,7 @@ +# Web Terminal + +## Video Walkthru + +
+ +
diff --git a/docs/functions/webhooks.md b/docs/functions/webhooks.md new file mode 100644 index 00000000..378f8a55 --- /dev/null +++ b/docs/functions/webhooks.md @@ -0,0 +1,127 @@ +## Video Walkthru + +
+ +
+ +To apply and run on Agent overdue and Check/Task failures use [Alert Templates](alerting.md#alert-action-settings) + +`Name`: Name + +`Description`: for notes about webhook. + +`URL Pattern`: For webhooks, you need a URL where the Tactical RMM can send HTTP requests when an event occurs. This URL should be a server endpoint configured to accept HTTP requests. + +### Request Headers + +Request headers allow the server to learn more about the request context. Here are some common headers used in webhook configurations: + +Content-Type: Describes the nature of the data being sent. For JSON data, you use application/json. + +Authorization: If your endpoint requires authentication, you might use a token or other credentials in this header. + +User-Agent: Identifies the application making the request. + +```json +{ + "Content-Type": "application/json" +} +``` + +### Request Body + +The request body must contain valid JSON and can include anything you want. Here are some examples: + +=== ":simple-discord: Discord" + + Discord: Edit a channel > Integrations > Webhooks + + ```json + { + "content": "Agent hasn't checked in for {{agent.overdue_time}} minutes.", + "username": "{{agent.hostname}}", + "avatar_url": "https://cdn3.emoji.gg/emojis/PogChamp.png", + "embeds": [ + { + "title": "Agent {{agent.hostname}} Client: {{agent.site.client.name}}", + "description": "This is an embed", + "color": 15258703, + "fields": [ + { + "name": "Field1", + "value": "Some value", + "inline": true + }, + { + "name": "Field2", + "value": "Another value", + "inline": true + } + ] + } + ] + } + ``` + +=== ":material-code-json: JSON" + + Simple JSON + + ```json + { + "text": "{{agent.hostname}}: {{alert.message}}" + } + ``` + +=== ":material-microsoft-teams: Microsoft Teams" + + [Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=newteams%2Cdotnet) + + Microsoft Teams uses Office 365 Connectors for its incoming webhooks. The format for Teams is slightly more complex, allowing for potentially richer content. + + ```json + { + "@type": "MessageCard", + "@context": "http://schema.org/extensions", + "summary": "Issue 176715375", + "themeColor": "0078D7", + "title": "Issue opened: \"Push notifications not working\"", + "sections": [{ + "activityTitle": "Mona Lisa", + "activitySubtitle": "On Project XYZ", + "activityImage": "https://teamsnodesample.azurewebsites.net/static/img/image5.png", + "facts": [{ + "name": "Assigned to", + "value": "Unassigned" + }, { + "name": "Due date", + "value": "2016-08-29T04:31:32.993Z" + }], + "markdown": true + }] + } + ``` + +=== ":material-slack: Slack" + + [Slack](https://api.slack.com/messaging/webhooks) + + You can also send more complex messages with attachments, buttons, etc., by using Slack’s rich messaging format. + + ```json + { + "text": "Hello, world! This is a line of text.\nAnd this is another one." + } + ``` + +=== ":simple-helpdesk: Ticketing System" + + [Zammad](../3rdparty_zammad.md) + + See above for how to open a ticket in Zammad with a webhook alert. + + + +#### Testing webhooks +Use the test button to make sure your webhook is working. Note: `{{alert.XXX}}` variables will NOT be available in testing mode. + diff --git a/docs/guide_gettingstarted.md b/docs/guide_gettingstarted.md index fd77476f..2388e158 100644 --- a/docs/guide_gettingstarted.md +++ b/docs/guide_gettingstarted.md @@ -5,7 +5,7 @@ Install the server, [choose the best path](install_considerations.md) ## Post Install -* [ ] Setup [Email Alerts](functions/email_alert.md){target=_blank} +* [ ] Setup [Email Alerts](functions/emailsms_alert.md){target=_blank} * [ ] Setup SMS Alerts * [ ] Create a Default Alert Template and assign (either Global, or using Automation Policies) * [ ] Set Server Preferences Under `Global Settings > General` diff --git a/docs/install_server.md b/docs/install_server.md index 3bd5fafc..cd3a3799 100644 --- a/docs/install_server.md +++ b/docs/install_server.md @@ -118,7 +118,7 @@ ufw enable && ufw reload ### Step 4 - Create DNS A records !!!warning - All 3 domain names have to be at the same subdomain level because you only get one LetsEncrypt wildcard cert, and it'll only apply to that level of DNS name. + All 3 domain names MUST be at the same subdomain level because you only get one LetsEncrypt wildcard cert, and it'll only apply to that level of DNS name. We'll be using `example.com` as our domain for this example. diff --git a/docs/roadmap.md b/docs/roadmap.md index cc0dcff1..bbdacaea 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -9,39 +9,24 @@ Thanks go to all you [sponsors](sponsor.md#sponsor-with-stripe-or-paypal) it's y { "title": "Estimated Release Dates", "activities": [ - { - "title": "[Mesh Integration Rework](https://github.com/amidaware/tacticalrmm/issues/182)", - "start": "2024-01-01", - "lasts": "3 months" - }, - { - "title": "[Alerts to Webhooks](https://github.com/amidaware/tacticalrmm/issues/1222)", - "start": "2024-02-01", - "lasts": "5 months" - }, - { - "title": "[Server side](https://github.com/amidaware/tacticalrmm/issues/1316) Scripts", - "start": "2024-02-1", - "lasts": "5 months" - }, { "title": "[SSO](https://github.com/amidaware/tacticalrmm/issues/508) integration", - "start": "2024-06-01", - "lasts": "2 months" + "start": "2024-07-01", + "lasts": "3 months" }, { "title": "[Linux/Mac](https://github.com/amidaware/tacticalrmm/discussions/1692) Tasks", - "start": "2024-05-01", + "start": "2024-07-01", "lasts": "3 months" }, { "title": "[Windows Update](https://github.com/amidaware/tacticalrmm/issues/1188) Rework", - "start": "2024-08-01", + "start": "2024-10-01", "lasts": "3 months" }, { "title": "[White](https://github.com/amidaware/tacticalrmm/issues/463) labeling", - "start": "2024-08-01", + "start": "2024-10-01", "lasts": "3 months" } ] diff --git a/docs/security.md b/docs/security.md index a9a7a81a..1ccc900a 100644 --- a/docs/security.md +++ b/docs/security.md @@ -4,4 +4,4 @@ If you think that you have found a security vulnerability in Tactical RMM, pleas Please do not make vulnerabilities public without notifying us and giving us at least 3 days to respond. -If you are going to write about Tactical RMM's security, please get in touch, so we can make sure that all claims are correct. \ No newline at end of file +If you are going to write about Tactical RMM's security, please get in touch, so we can make sure that all claims are correct. diff --git a/docs/tipsntricks.md b/docs/tipsntricks.md index e79083eb..0b63f552 100644 --- a/docs/tipsntricks.md +++ b/docs/tipsntricks.md @@ -148,7 +148,7 @@ If you're interested in converting your software to Chocolatey managed you will Once you've made your script, that will take existing software and convert it to Chocolatey managed (see what Chocolatey manages on an agent with). ```batch -choco list --local-only +choco list ``` Next, you're going to schedule your updates. diff --git a/docs/update_server.md b/docs/update_server.md index 15b20c2f..0e9b79a8 100644 --- a/docs/update_server.md +++ b/docs/update_server.md @@ -60,6 +60,8 @@ If you are already on the latest version, the update script will notify you of t You can pass the optional `--force` flag to the update script to forcefully run through an update, which will bypass the check for latest version. ```bash +wget -N https://raw.githubusercontent.com/amidaware/tacticalrmm/master/update.sh +chmod +x update.sh ./update.sh --force ``` diff --git a/mkdocs.yml b/mkdocs.yml index df762283..fd5eefb8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,22 +18,25 @@ nav: - "Updating Agents": update_agents.md - Functionality: - "How it all Works": howitallworks.md + - "Global Settings": functions/global_settings.md - "Alerting": functions/alerting.md - "API Access": functions/api.md - "Automated Tasks": functions/automated_tasks.md - "Automation Policies": functions/automation_policies.md - "Custom Fields": functions/custom_fields.md - - "Database Maintenance": functions/database_maintenance.md - "Django Admin": functions/django_admin.md - - "Email Alerts": functions/email_alert.md + - "Email & SMS Alerts": functions/emailsms_alert.md - "Global Keystore": functions/keystore.md - "Maintenance Mode": functions/maintenance_mode.md - "Permissions": functions/permissions.md - "Remote Background": functions/remote_bg.md - "Overriding / Customizing Default Settings": functions/settings_override.md - "Scripting": functions/scripting.md + - "SNMP Checks": functions/snmp_checks.md - "URL Actions": functions/url_actions.md - "User Interface Preferences": functions/user_ui.md + - "Web Hooks": functions/webhooks.md + - "Web Terminal": functions/web_terminal.md - "Reference: Script Variables": script_variables.md - "Examples": functions/examples.md - Reporting: @@ -65,6 +68,7 @@ nav: - "TeamViewer": 3rdparty_teamviewer.md - "BitDefender GravityZone": 3rdparty_bitdefender_gravityzone.md - "BitDefender Total Security": 3rdparty_bitdefender_total_security.md + - "Zammad": 3rdparty_zammad.md - Unsupported Extras: - "Unsupported Guidelines": unsupported_guidelines.md - "Unsupported Configs": unsupported_scripts.md