Welcome to the NetLock RMM user manual. This site covers everything an IT administrator or MSP technician needs to install, configure, and operate a fleet of devices with NetLock RMM, from the first login through advanced automation and reporting.
The manual is organised into five parts. Start with Part I if you are new to the product; jump directly to Part II or Part III if you already know the core concepts and want a specific feature or task.
Task-oriented recipes. Each guide is short, prescriptive, and links back into Part II for concept reference.
The guides cover deploying the first agent, building and applying a policy, configuring Windows Defender, setting up patching, writing a PowerShell script, deploying software with App Hub, restricting USB devices, configuring notifications, enabling SSO, branding the Console, running compliance reports, remote-controlling a device via relay, upgrading NetLock RMM, replacing the Members Portal API key, installing the server with Docker, monitoring a device with SNMP, debugging an agent with on-device logs, installing the web console as an app, using script variables and custom fields in scripts, and writing custom field values back from a script.
Deeper reference material for system operators. Covers licensing, updates, database management, security (SSO, IP whitelist, country restriction, rate limiting), globalization, whitelabeling, remote screen control, notification channels, logging, system settings, AI / LLM configuration, and content defaults.
UI labels, routes, and permission flags appear in backticks: Settings → SSO, collections_application_control_manage.
Navigation paths use → to separate menu levels.
Callouts flag important information:
Note: Background information.
Tip: Shortcut or recommendation.
Warning: Action you probably do not want to take by accident.
Optional module: Content only applies when a particular module is enabled.
Keyboard shortcuts use <kbd> tags, for example Ctrl + K.
NetLock RMM is a remote monitoring and management (RMM) platform for IT administrators and managed service providers (MSPs). You use it to deploy an agent to the devices you manage, see their status in real time, apply policies, schedule automations, push patches, run scripts, distribute software, hand out remote-control sessions, and keep an auditable record of everything that happens along the way.
The product is delivered as a web Console backed by a server and an agent you install on each managed device. All three components are covered in this manual; the Console is the main surface you interact with.
IT admins inside a single organisation. You manage a single fleet of workstations, laptops, and servers. You typically use one tenant, a small number of locations, and a handful of user accounts for your colleagues.
MSP technicians managing multiple customer organisations. You create one tenant per customer, organise their devices into locations and groups, apply policies that differ per customer, and scope user permissions so that technicians see only the tenants they are assigned to.
Both audiences use the same Console. The difference is scale (one tenant or a hundred), not the feature set.
It is not a replacement for a dedicated SIEM. The Audit trail records admin actions, but large-scale security event aggregation belongs in a SIEM you forward events into.
It is not an identity provider. You can sign in with SSO (OpenID Connect), but NetLock RMM consumes identities; it does not issue them.
It is not a backup product. File Server distributes files to agents; it does not perform image-level backups of managed devices.
NetLock RMM is easier to learn if you read the vocabulary first. The product uses a small number of terms very consistently, and almost every chapter in Part II assumes you already understand the ones introduced here.
The agent is a small piece of software installed on every device you want to manage. It reports status, runs jobs you schedule, enforces policies, and provides the endpoint for remote shells and file transfers. Once installed it talks to the server on a regular schedule.
The server is the central component. It holds configuration, receives data from agents, runs the web Console, and mediates remote-access sessions. In cloud deployments the vendor runs it; in self-hosted deployments you run it.
The Console is the browser-based user interface you spend your day in. It reads and writes configuration to the server; it does not talk to agents directly.
In every feature, the Console tells the server what should happen, and the agent carries it out.
NetLock RMM organises managed devices into a three-level hierarchy. Every device belongs to exactly one group, which belongs to exactly one location, which belongs to exactly one tenant.
A tenant is the top-level container. For an in-house IT team this usually maps to "the company". For an MSP it maps to one customer organisation.
A location is a subdivision of a tenant, usually a physical site or office. A small tenant might have one location; a multi-site customer will have several.
A group is a subdivision of a location. Groups typically reflect how devices should be configured rather than where they physically are, for example Servers, Workstations, Kiosks.
The hierarchy is primarily an organisational structure for devices and for scoping what users can see. Policies are not attached directly to a tenant, location, or group. Instead, they are routed to devices by Automations, which match devices by attributes such as their tenant, location, or group name.
See Chapter 4 for the full reference on managing this hierarchy.
Tip: Group devices by how they should be configured, not just where they live. "Every laptop, regardless of site" is a better group than "every device in the Berlin office" if your policies differ primarily by device type.
A device is a managed computer: a workstation, laptop, or server. When you install the agent on a new device, it contacts the server and registers itself as an unauthorized device: present on the network, but not yet accepted into a tenant. An administrator reviews unauthorized devices in Devices → Unauthorized, chooses the tenant, location, and group to assign them to, and approves them. From that moment the device is an authorized device and appears in the main device list.
Note: A device that does not appear in the device list is usually waiting for approval. The First-Run Walkthrough covers the approval flow in detail.
Devices also carry a label (a free-form human-readable name), custom fields defined at the Collections level, and any number of per-device settings. Chapter 3 is the canonical reference for everything device-related.
A policy is a named bundle of desired configuration for a device. Examples: "managed laptops (strict)", "kiosk devices", "server baseline". A single policy can configure:
General agent behaviour (sync interval, auto-update).
Tray Icon branding and visibility.
Windows Defender Antivirus (exclusions, scan jobs, notifications).
Windows Application Control and USB Device Control rulesets.
Linux UFW firewall.
SNMP sensors to collect on devices.
Scheduled Jobs to run on devices.
Patch Management rollout rules, per platform (Windows, Linux, macOS, Docker).
Which App Hub apps are exposed in the Tray Icon.
Policies are edited in the Policy Settings page and stored in the server database. The agent picks up changes on its next sync (5-1440 min, configurable per policy).
Important: NetLock RMM does not keep a policy version history and does not support rolling back to a previous policy state. Edits apply in place. If you need a safety net, clone a policy before making a risky change.
A device is assigned at most one policy at a time. Policies are not layered or merged.
In NetLock RMM, an automation is a rule that decides which policy gets assigned to which device, and which sensors and jobs a device gets on top of that policy, based on a list of conditions:
IF all of these conditions hold for a device THEN assign policy <name> and/or add sensors and jobs
A condition compares one fact of the device: the device itself, its tenant, location or group, its internal IP address or domain, its platform, a device attribute such as the device name, the operating system or the label compared with an operator (equals, contains, starts with, wildcard pattern, regular expression), a service or an installed application of its inventory, or a custom field value. A rule has at least one condition, all of them have to hold, and any of them can be negated. Every rule has a priority number and an enabled switch.
An automation has no event, schedule, or manual trigger. Its only actions are assigning a policy and adding sensors and jobs (see Chapter 5.6). It does not run scripts itself, send notifications, create tickets, or chain steps; it routes policies, sensors, and jobs to devices.
When a device syncs, the server takes the enabled rules whose conditions all hold for the device, orders them by priority (the lower number wins), then by the number of conditions (more first), then by age (older first), and assigns the policy of the first one. If no rule matches, the device receives the default policy when one is marked on the Policies page; otherwise it has no policy. The dialog proposes a priority from the rule's most specific organisation condition (device 100, internal IP 200, domain 300, group 400, location 500, tenant 600, otherwise 700), so a rule for one device beats a rule for its group, which beats a rule for its tenant, unless you choose otherwise. Adding, editing, enabling, disabling, or deleting an automation forces the affected devices to re-evaluate immediately.
To give devices a policy, you need both a Policy and at least one Automation whose condition matches those devices. A policy without a matching automation is not applied to any device. The exception is the default policy: marked on the Policies page, it covers every device that no automation reaches.
For event-driven work, such as "run a script when a disk fills up" or "open a ticket when a sensor breaches a threshold", NetLock RMM uses Sensors (with action scripts) and Jobs (scheduled scripts), not Automations. See Chapter 8 — Collections.
Collections is the umbrella term for reusable building blocks you create once and reference from many places. Eight kinds of Collection item exist:
Item
Purpose
Script
A PowerShell or Bash snippet you run on one or many devices.
Job
A scheduled background task that runs on the agent.
Sensor
A custom metric the agent reports back on an interval, such as CPU, memory, or a specific application's health.
Custom Field
A per-device attribute (text, dropdown, date, checkbox) added to every device inventory.
App Hub entry
A packaged application from Winget (Windows) or Flathub (Linux), or a manual package, available for deployment.
Application Control ruleset
Rules that whitelist applications by hash or path.
Device Control entry
Rules that whitelist USB and peripheral devices.
Software Deployment
A packaged deployment of one or more App Hub entries or manual packages to a target set of devices.
Collections items are cross-referenced: an automation may add jobs and sensors that run scripts, a policy may include an Application Control ruleset, a software deployment may use App Hub entries. Chapter 8 documents each in detail.
NetLock RMM uses a role-based permissions model. Each user holds a set of permission flags that gate access to Console features. The common flag shapes are:
*_enabled: whether the user sees the feature at all (for example collections_enabled).
*_add: whether the user can create new items in the feature.
*_manage: whether the user can open existing items; saving and deleting take *_edit and *_delete.
Permission flags control which items appear in the navigation menu on the left and which buttons are visible on a page. A user without dashboard_enabled will not see the Dashboard menu item; a user with collections_application_control_enabled but without collections_application_control_edit can open rulesets but not save changes.
Permission names appear throughout this manual in backticks, for example collections_application_control_manage. See Users & Roles for how to assemble permissions into roles, and the Permission reference appendix for a full list.
Several parts of the Console update in real time using a persistent connection to the server. Device status, script and job execution results, and policy deployment notifications all flow in without a page refresh.
This chapter takes you from your first login all the way to a managed device that is online, labelled, and has a policy applied. It assumes the server is already running (whether cloud or self-hosted).
The steps below use the terms introduced in Core Concepts.
Open the Console in your browser. The login screen accepts your username and password, or a configured single-sign-on provider if your organisation has enabled SSO.
Enter your username in the Username field.
Enter your password in the Password field and sign in.
If your account has two-factor authentication enabled, enter the current code from your authenticator app on the next screen.
If your organisation uses SSO, click the SSO button on the login page instead and complete the provider's flow.
You land on /account/home, a small personal dashboard showing your profile information, navigation order menu and email signature configuration for the ticketing system.
Note: On a new self-hosted deployment, sign in with the username admin and the password admin. The Console makes you choose a new password at the first sign-in.
The first time an administrator visits the Dashboard page, the Setup Wizard opens automatically. Every step is saved as soon as you continue. It walks you through the basic settings:
Choose your design.
Check the connection to the backend.
Set the date and time format.
Set how many agent installations and updates may run at the same time.
Optionally turn on two-factor authentication for your account.
Enter your personal information.
On a self-hosted deployment, enter the backend address the agents connect to. The Console then generates the agent installers for every tenant and location.
The last screen offers Deploy your first agent, which opens Agent Installers with the ready-built installers. Tenants, locations and groups are created on the Tenants page (Step 3).
Tip: Choose the name of your first tenant with care. It is common to use the company or customer name. You can rename it later, but external integrations (for example reports emailed to stakeholders) use the name you set here.
On the Tenants page, click the add button and fill in the tenant name and basic details. Save.
Open the new tenant with the row action Manage. The Manage tenant page opens.
In its Locations table, add a location, typically a physical site such as "Berlin HQ" or "Remote Workers".
Open the location with the row action Manage and, on the Manage location page, add one or more groups. Groups should reflect how devices will be configured; a good starter set is Workstations, Laptops, and Servers.
See Chapter 4 for the full reference on the tenant page and its dialogs.
With the tenant and location in place, the Console has installers ready that register the agent into that tenant and location. NetLock RMM ships the agent as a single self-contained executable per platform and architecture, with the server configuration embedded.
Open Agent Installers: Deploy Agent in the navigation, or Install Agent on the Devices page while no device is enrolled.
Select the Tenant and Location.
Under Automatic device authorization, choose whether new devices of this location are authorized automatically and until which date. Devices that register later, or while the option is off, wait in Unauthorized Devices.
In the installer table, pick the row of the target platform and architecture (win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64). Once it shows Ready, click Download installer for the .zip, or Copy command for a one-line install that downloads and runs it on the device.
Optionally download or copy the installation script of that row (Install-NetLockAgent.ps1 for Windows, Install-NetLockAgent.sh for Linux or macOS), which installs the agent only where it is missing.
Warning: Treat agent installers like secrets: anyone who has one can register a device into the configured tenant and location. If an installer authorizes devices automatically, set an end date; after that date, devices that register with it wait in Unauthorized Devices.
With no arguments the installer uses its embedded config; on macOS (3.3.0.11 and later) it uses the server_config.json next to it in the package. For manual re-configuration or repair, the installer also accepts positional modes: clean "<path-to-server_config.json>" for a fresh install with an external config, fix "<path>" to repair while preserving the existing server config, and uninstall to remove the agent.
The installer registers the agent as a background service (Windows service, systemd on Linux, LaunchDaemon on macOS) and starts it. On macOS the agent additionally registers the User Process and the tray icon as LaunchAgents in the session of every signed-in user (agent 3.3.0.11 and later). Within a minute or two the agent contacts the server.
Note: NetLock RMM does not ship native .msi, .deb, .rpm, or .pkg packages; a single binary is used across all distributions.
Back in the Console, a device that registers before the location's Automatically authorize devices until date appears directly in Devices. After that date it appears in Unauthorized Devices instead, and an administrator must approve it before it is managed.
In the navigation, open Devices → Unauthorized Devices.
Locate the new entry. It shows the device's hostname, operating system, and the tenant / location / group the agent was configured for.
Select the entry and approve it. Optionally adjust the target group before approval if the agent was configured against the wrong one. An entry marked Name already exists belongs to a device you already manage (its operating system was reinstalled) and is continued with the row action Adopt as reinstall instead; see Chapter 3.2.
Give the new device a human-readable label using the Edit Label dialog, for example MARKETING-LAPTOP-01 becomes Anna's laptop.
The device now appears in the main Devices list and reports status in real time. See Chapter 3 for the full Devices reference.
With the device authorised, give it a policy. This takes two pieces in NetLock RMM: the policy itself (what should be enforced), and an automation rule that routes the policy to the right devices.
On Manage Policies, click Add. Enter a name and description, for example Starter Workstations. Save.
Click Manage on the new row to open Policy Settings.
The default settings enforce the agent configuration but do not yet configure Antivirus, Application Control, Patch Management, or any other opt-in feature. Configure the settings you need now; you can add sensors and jobs later.
Under If …, leave the condition type at Group and pick the group you created in step 3, for example Workstations.
Under Then …, select the policy Starter Workstations.
Leave Priority at the value the dialog proposes (400 for a group rule).
Confirm.
The server immediately re-evaluates the devices of that group against the new automation and pushes the matching policy. The device receives the policy within the agent's next poll interval.
Note: When several automations match a device, the one with the lower priority number wins. At equal numbers, the rule with more conditions wins, then the older one. The dialog proposes a priority from the rule's most specific condition, so a rule for one device beats a rule for its group, which beats a rule for its tenant. See Chapter 5.
See Chapter 6 for the full Policies reference, Chapter 5 for the Automations reference, and Guide H.4 for a step-by-step walk-through.
A tenant with one location and at least one group.
One managed device, labelled and approved.
A policy routed to the group by an automation.
That is the smallest meaningful deployment of NetLock RMM. Patch management, scripts, reporting, and the other features build on this foundation. The next chapter, Navigating the Console, describes the Console layout.
The Console has a consistent layout across every page. This chapter describes the fixed elements: the navigation menu, the tenant selector, the global search, the theme toggle, and the help dialog.
The navigation menu on the left is built dynamically: the items you see depend on your permissions, the modules enabled on the deployment, and the order you chose to display them in. Two users with different permission sets on the same deployment will see different menus.
The default top-level groups, in their default order, are:
Dashboard
Devices Quick Access, with All devices, Unauthorized, Deploy Agent, World Map, and Topology sub-items.
File Server & Monitoring: File Server, Relay Server, Website Uptime, Port Scanner.
Tickets(only if the Ticket System is enabled)
Reports
Management: Events, Audit, Users.
Settings: 16 sub-pages covering administration.
Each group expands to reveal its sub-pages. Selecting a sub-page loads it into the main content area.
Note: Menu visibility is gated by roughly twenty permission flags at the top level, plus additional flags per sub-page. See the Permission reference appendix.
The Console stores a per-user menu order in your account. The default order is the one listed above, and the server loads your personal order on every login. You can edit the order under /home.
If the deployment is unlicensed, a gold Go Pro button appears in the navigation. Clicking it opens the upgrade / licensing flow. Once the deployment is licensed, the button disappears.
Many pages, such as Manage tenant, Manage location, the Devices page, and most Collections pages, act on a currently selected tenant, location, and group. You pick them with the selector in the header.
Click the selector in the header to open a tenant / location / group picker.
Choose the tenant, then narrow to a specific location or group if desired.
The selection persists across the session and is used by every context-sensitive page you open afterwards.
A few pages also show the selected context inline near the top of the content area, so you always know what you are acting on.
Tip: If a page says "no tenant selected" or shows an empty state unexpectedly, open the header selector first and pick a tenant.
The header carries a search box (on phones, a magnifier icon that opens the results page). Press Ctrl+K (Cmd+K on macOS) or / on any Console page to jump into it. Type at least two characters and the suggestions appear grouped by category while you type. Every group lists the first five matches and ends with a link to the full results; the last row opens the results page for the whole term.
Use ↑ and ↓ to move through the suggestions, Enter to open the highlighted one (or the results page when nothing is highlighted) and Esc to close the list. The suggestions appear after 1.5 seconds at the latest. A category whose search is still running is marked as searching and fills in when it finishes; the results page always waits for every category.
Operators. A term can start with an operator, an English word followed by a colon, that narrows the search to one field or one category. The word is matched in any case, a space after the colon is allowed, and singular and plural are both accepted (ticket: and tickets:). A word that is not an operator stays part of the term, so http://example is searched as typed, and the remainder after the operator has to be at least two characters long. The help icon next to the search box lists the operators with an example each.
Operator
Searches
serial:ABC123
the serial number of devices
hwid:4C4C4544
the hardware ID of devices
ip:192.168.
the internal and external IP address of devices, and the IPv4 address of network adapters by prefix
mac:AA:BB
the MAC address of network adapters in any spelling, also for a short fragment such as mac:0a1b
country:DE, country:germany
the country of devices: a two-letter term is matched whole against the country code, anything else as part of the country name in English or in any console language, so country:deutschland finds the same devices
only that category, with the same columns as without the operator; software: is the installed software of the devices, app: the App Hub
An operator never widens what an account may see: a category the account may not search, or a field of such a category, returns no results.
Recent searches. While the search box is focused and empty, it lists the last eight searches that were submitted or whose hit was opened in this browser. A row runs that search again, Clear empties the list, and the arrow keys move through the rows as through suggestions. The list is stored in the browser only, not on the server, and nothing is stored while typing.
What is searched:
Devices: name, label, serial number, internal and external IP address, the country of the external address (by its name in English or in any console language), operating system, domain, last active user, hardware ID, manufacturer, model, and the names of tenant, location and group. A suggestion shows the device, its tenant and location and, when the term was found somewhere other than the name, which field matched (for example Serial number: 5CD1234XYZ or Country: Germany).
Custom fields: the values stored in custom fields of devices, shown as Custom field <key>: <value>. Fields of type secret are never searched, whatever their value.
Software, Services, Drivers and Network adapters: the inventory of the devices, one suggestion per distinct entry (a software name with its version and vendor, a service with its service name and status, a driver with its version and status, an adapter with its MAC and IPv4 address) together with the number of your devices that hold it, for example Google Chrome · 128.0.6613.120 · Google LLC · on 37 devices.
Names are matched by word, so chrome finds Google Chrome; a service name such as wuauserv matches by prefix. For adapters, a term that looks like a MAC address matches the stored address in any spelling (AA:BB:CC, aa-bb-cc and aabbcc all find AA:BB:CC:DD:EE:FF), and a term of digits and dots matches the IPv4 address by prefix (192.168.1). On the results page each entry expands to the list of devices that hold it (up to 50), each linking to the device. A device appears in these four categories once it has sent its inventory.
Tickets: number, title, contact name, contact e-mail and assignee, and on the results page the description as well; a suggestion shows the ticket number, the customer and the status and priority chips of the tickets list. Merged tickets are not listed, and only the departments you may see are searched.
Customers: company name, contact name, contact e-mail and phone of the ticket customers; a hit opens the customer details page.
Contacts: first and last name, e-mail, phone and position of the customer contacts; a hit opens the contact for editing.
Policies: name and author, and on the results page the description; the default policy carries a chip. A hit opens the settings page of the policy.
Scripts, Jobs and Sensors: name, description, label, author and platform, plus the shell of a script (and on the results page the script body itself, shown as an excerpt) and the type of a job; a sensor shows its category, a hidden job carries a chip. A hit opens the list with that entry and, for an account that may edit, its edit dialog.
Automations: name, description, author and assigned policy of the rules on the automations page, with an enabled or disabled chip. A hit opens the rule for editing; the dialog applies the tenant rules of the automations page.
App Hub apps: name, publisher, version, the winget, Flathub and Chocolatey package ids and the tags, and on the results page the description; the suggestion shows the source and the target operating system. A hit opens the app for editing when the account may manage apps, otherwise the list narrowed to the app.
Software deployments: name and author, and on the results page the description, with the status and mode chips of the deployments list; a hit opens the deployment. A deployment is found when at least one of its targets belongs to your tenants, as the deployments list shows it.
Tenants and Locations: name, description, company and contact persons of a tenant, name, description and author of a location (shown with its tenant); tenants marked for deletion are left out. A hit opens the settings page of the tenant or location.
Users: username, e-mail, first and last name and phone of the console accounts, shown with their role; a disabled account carries a chip. A hit opens the settings page of the account.
SNMP devices: name, IP address, system name, location, contact and device type, and on the results page the system description and the notes, with the status chip of the SNMP list. A hit opens the Devices page in its SNMP view with the device selected.
Unauthorized devices: name, internal and external IP address, country, domain, operating system and last active user of the devices waiting for authorization. A hit opens the unauthorized devices page listing every such device of your tenants, narrowed to that name; authorizing still requires a click there.
Opening a device hit lands on the Devices page with that device selected and its detail panel open; a ticket hit opens the ticket dialog, a customer hit the customer details page and a contact hit the edit dialog of the contact. A hit of a management category opens the entry the same way its own page does: the settings page for policies, tenants, locations and users, the edit dialog (or the narrowed list, without the edit permission) for scripts, jobs, sensors, automations and App Hub apps, the detail page for a deployment. An App Hub hit names the source of the app (Script, File from the file server, Winget, Chocolatey or Flatpak) and its target system.
The results page at /search lists up to 50 matches per category, with a chip per category to narrow the list, and a note when a category holds more than that. Such a category shows 50+ until its chip is clicked; the exact number is then counted once and shown in the chip and in the card title, and the total of the All categories chip becomes exact once every such category has been counted. An inventory entry opened from a suggestion lands on the results page with its category selected and its device list already open.
Results follow the signed-in account. A category is only searched and shown when the account holds the permissions of the page it links to (the devices permission for devices and the four inventory categories, plus the custom fields permission for custom fields, the software permission for software, services and drivers, the general device permission for network adapters, the tickets permission for tickets, the customer management permission for customers and contacts, and for the management categories the permissions of the policies, scripts, jobs, sensors, automations, App Hub, software deployment, tenants, locations, users, SNMP and unauthorized devices pages).
Device hits and the device counts of the inventory categories are limited to the tenants the account is assigned to, tickets to the departments it may see, and customers and contacts to its tenants, where an entry without a tenant is visible to everyone. Tenants, locations, SNMP devices and unauthorized devices are limited to the assigned tenants as well, and software deployments to those with a target in one of them; policies, scripts, jobs, sensors, automations, App Hub apps and users have no tenant and are listed for every account with the page permission. An account without any tenant sees the search box but gets no device hits. Entries outside that scope are not shown in any form, so two users typing the same term can get different lists.
Deployment-wide, the box can be hidden from the header on the AppBar & Effects tab of the whitelabeling settings (Global search); the results page stays reachable at /search.
A theme toggle in the header switches between light and dark mode. Your preference is stored in your user account, so the theme is consistent across devices and sessions.
If the deployment has been whitelabeled (see A.6 Whitelabeling & themes), the brand colours apply in both modes. Custom community themes imported via the whitelabeling settings also respect the light/dark split.
The header gives access to help and status information:
Contact support: the in-app support dialog, a form for contacting our support team.
Update available: when a new version is available, the app bar shows an Update available icon and the account menu shows Update available (v…); both open a short summary.
Subscription reminder: shows subscription renewal information on deployments that require it.
For deeper issues, the Troubleshooting appendix lists common failure modes with diagnostics.
Short-lived status messages appear as toast notifications in a corner of the screen, for example "Policy saved" after saving a policy, or an error after a failed bulk action. Toasts disappear after a few seconds; for historical records, check Events or Audit.
Real-time Console features (device status, script execution results, policy deployment feedback) use a persistent connection to the server. If toasts or status indicators stop updating, refresh the page to re-establish the connection.
The Console defines two global keyboard shortcuts: Ctrl+K (Cmd+K on macOS) and / focus the global search box in the header, or the box on the results page when that page is open. / is ignored while the cursor is in a text field, a script editor, a terminal or the ticket editor, and while a dialog is open, so a slash typed there arrives as usual. Inside the search box, the arrow keys, Enter and Esc control the suggestion list. Dark mode and save/close actions have no global shortcut. Other keyboard handling is page-local, for example pressing Enter submits the login form, and the remote control window binds function keys relevant to that session. Each per-page shortcut is noted in the chapter that documents that page.
The Dashboard is the default landing page for most users. It is a grid of panels, configurable widgets that display information from the Console's database: device counts, sensor values, event slices, and anything else you can express as a SQL query. Each user can create multiple dashboards, each with its own set of panels, and arrange them in an explicit layout mode.
Requires permission: the dashboard must be enabled for your user. A user without this permission does not see the Dashboard menu entry.
The Dashboard page sits at /dashboard. At the top is a bar of dashboards you have created; the active dashboard shows below it as a grid of panels. Dialogs handle creating and deleting dashboards and adding or configuring panels.
The first time a newly provisioned administrator opens the Dashboard, the Setup Wizard opens automatically. It walks through the minimum configuration needed to make the product useful: creating a first tenant, location, and group, and optionally downloading an agent installer. See First-Run Walkthrough for the full sequence.
You can close the wizard and reopen it from the help area later. If your environment is already set up, dismiss it and proceed directly to the empty dashboard.
A fresh user starts with one empty default dashboard. You can create more so that different roles or different periods of the day get their own view (for example a "morning triage" dashboard and a "server health" dashboard).
Click the add button in the dashboard bar to open the Add Dashboard dialog.
Enter a name in the dashboard bar.
Save. The new dashboard is active and empty, ready for panels.
Dashboards are per-user. Two users do not share each other's dashboards unless an administrator configures defaults (see A.12 Content defaults).
Panels are the individual widgets that make up a dashboard. Use the Panel Builder to add or reconfigure them.
On the active dashboard, click Add Panel.
The Panel Builder opens.
Choose a panel type: chart or table. For chart, also pick a chart sub-type: bar, line, area, pie, doughnut, or radar.
Build the data query. Pick a catalog widget, or write your own SQL statement. For your own statement the Panel Builder offers a SQL query builder with:
aggregate functions COUNT, SUM, AVG, MIN, MAX, and DISTINCT;
filter operators =, !=, <, >, <=, >=, LIKE, NOT LIKE, IS NULL, IS NOT NULL;
joins INNER JOIN, LEFT JOIN, RIGHT JOIN;
ORDER BY direction ASC or DESC.
The query builder lists exactly the tables and columns the MySQL user for SQL access can read; you can also type the statement directly. See SQL panels and SQL access below.
For chart panels, configure the label column and value column that map the query rows onto the chart axes or slices.
Configure display settings: colours, legend position, legend visibility, axis labels, fill (area / line), line tension (line / area).
Configure the panel size in the dashboard grid: Width in grid columns (1-12) and Height in pixels (200-1200).
Save. The panel appears on the dashboard and renders from its query.
A panel with its own SQL statement (typed directly or generated by the query builder, including its preview in the Panel Builder) runs only over the MySQL user configured under Settings → SQL access. That user's grants decide which tables and columns the statement can read. Setting it up is described in Set up SQL access for reports, dashboards and custom fields; on cloud instances SQL access is not available.
Creating and changing SQL panels needs the permission dashboard_sql_panels and assignment to every tenant of the instance.
On save, the statement is checked with EXPLAIN over that user (syntax, tables and columns it may read). When MySQL refuses it, its message is shown.
A panel that was added from one of the shipped panel templates and still carries the template statement unchanged runs without SQL access, like the built-in report templates. Once its statement is edited, it needs SQL access.
Without SQL access, all other SQL panels are locked with a notice, on the dashboard and in the TV view. The Panel Builder shows a notice with a link to Settings → SQL access and offers neither the query builder, the SQL field nor the AI SQL assistant. Catalog widget panels are not affected.
The Sensor status widget of the Monitoring category is a chart with the sensors of your devices that are OK, failing or offline. It is not part of the standard dashboard; add it to a dashboard of your own. When a dashboard carries it, the TV view shows its three counters in its header. The widget needs the sensors permission of the Collections area and counts only the devices of the tenants your account is assigned to.
The state comes from the events the sensors reported. A sensor is failing while an unread sensor event of its device names it and no newer "Sensor Resolved" event of that sensor exists. Reading the event on the Events page acknowledges the failure and the sensor returns to OK, and so does a resolved event the agent writes when the check passes again. Failed sensor runs ("... failed") count as failing as well. Sensors of offline devices are counted as offline, not as failing. The sensors a device is expected to run follow its policy, its automation rules and the SNMP devices it monitors, the same way the agent receives them. Each sensor event carries the id of the sensor, so renamed sensors and sensors with the same name are matched exactly. OK also means that no failure was reported at all.
Every dashboard can be shown full screen on a wall display or an office monitor. On the Dashboard page, select the dashboard and click Open TV view. The view opens in a window of its own without the menu, the app bar and the editing controls, refreshes its panels by itself and shows the time of the last refresh, a countdown to the next one and a clock in its header.
The address of the view is /dashboard/tv/<id>, where 0 is the standard dashboard and any other id is a dashboard you can see. The view is always dark, whatever theme the console uses. One optional query parameter adjusts it:
refresh=<seconds> sets how often panels without an interval of their own are refreshed. The default is 60 seconds, the minimum 15, the maximum 3600. A panel with its own refresh interval keeps that interval. Panels with their own SQL statement are never refreshed more often than every 300 seconds, the smallest interval the Panel Builder offers for them, whatever this parameter says.
The view follows the sharing of the dashboard and the permissions of the signed-in account. It needs the dashboard permission, a dashboard of another user is only shown while it is shared with the account or visible to everyone, and a widget the account may not see stays locked, as on the dashboard page. The panel definitions are read again once per refresh interval, so panels added, changed or removed on the dashboard page appear on the TV without a reload; a dashboard that is deleted or unshared while the view is open is replaced by a notice.
The TV view menu on the Dashboard page offers Open this dashboard, Open playlist and TV settings. The settings dialog holds the playlist of your account: the dashboards the rotating view shows in order (the standard dashboard can be one of them), how long each stays on screen (30 seconds to 5 minutes) and how often the panels are refreshed. The dialog also shows the address of the playlist view, /dashboard/tv, with a copy button, so it can be typed into the browser of the TV device. Every account has one playlist of its own.
The playlist view rotates through the entries, shows the position and the next dashboard in its header and reads the playlist again after every full round, so changes made in the dialog appear without a reload. An entry you may no longer see is skipped, and the view shows a notice when the playlist is empty. The refresh query parameter takes precedence over the stored setting.
Sign in with Remember me on the device that shows the view. The open view keeps the session from idling out, but every session ends when its absolute lifetime is reached; the view then shows a notice with a Sign in again link instead of redirecting on its own, so the screen never ends up on the sign-in page unattended. The sign-in page brings the account straight back to the TV address it came from, whether the sign-in is done with a password or through SSO; only a TV address is accepted for that return. The notices mean:
No permission: the account does not hold the dashboard permission.
Dashboard not available: the dashboard was deleted, or it is no longer shared with the account.
Session expired: the session has ended; sign in again and the view comes back on its own.
Playlist is empty: the playlist has no entry you may see; add dashboards in the TV settings.
The unread events list appears below the panels when the dashboard is set up to show it and the account may see events.
If a dashboard has grown unwieldy, create a new one and delete the old one. Panels are quick to recreate with the Panel Builder, and you keep only the panels you use.
Access to the Dashboard is gated by a user-level permission. Users without it do not see the page or the menu entry.
The panels you can add depend on the data you are permitted to see. For example, a user scoped to a single tenant will only see that tenant's devices in a device-count panel, regardless of how the panel is configured.
The Setup Wizard is only shown on the administrator's first visit to the Dashboard and can be dismissed.
The Devices section is where most day-to-day RMM work happens. It covers the inventory of managed devices, the queue of agents waiting to be approved, device detail views with status and events, bulk operations such as remote shell commands or moving devices, remote desktop sessions, and a world map showing where your devices are located geographically.
The section is a top-level menu group with three sub-pages:
Page
Route
Purpose
Devices
/devices
Inventory of authorized devices.
Unauthorized Devices
/unauthorized_devices
Queue of agents pending approval.
Device World Map
/device-world-map
Geographic view of device locations.
All three pages respect the currently selected tenant, location, and group context from the header selector. See Navigating the Console for how the context works.
The Devices page lists every authorized device for the selected tenant / location / group. Each row shows status, identifying information, and quick actions.
Online: the agent is currently connected to the server.
Online + Remote connected (pulsing): the agent is currently connected to the server and has a remote connection established.
Offline: the agent has not checked in within the expected interval.
Status changes appear without a page refresh (the page uses the Console's real-time update channel). If status updates stop arriving, a page reload re-establishes the connection.
A device that rate limiting on the server has blocked shows a red chip Blocked until <time> next to its name. Its requests are refused until that time, so the device goes Offline as well; the tooltip of the chip names the reason (for example Request rate above the limit for a sustained period) and the request class. With the permission settings_rate_limiting_enabled the chip is a link to the Rate limiting tab, where the block can be released. Blocks recorded in observe mode do not show a chip.
A device with an open security incident, or a device that is isolated after one, is shown with a red row and the chip 🕵️ Script kiddie alert; an isolated device also carries the chip Isolated. See 3.8 Security incidents.
The Devices list offers two filter controls: a free-text search box and an online-only toggle.
The search box performs a case-insensitive contains match across 14 fields at once. Rows where any of the following fields contains the search text remain visible:
device name and label
tenant, location, and group name
agent version and last-access timestamp
IP address, operating system, and domain
country, by its name in the language of your console (a two-letter term matches the country code whole)
antivirus solution and firewall status
last active user
The online-only toggle, when enabled, restricts the list to devices whose status is currently Online + Remote connected. Combined with a search term, it narrows the list to online devices matching the search text.
The column button (tooltip Configure columns) at the right end of the toolbar above the list opens the column chooser. It lists every column of the table: tick a column to show it, untick it to hide it, and drag a row or use its arrows to change the order (the arrows are the way on touch devices). The Name column is always shown and only its position can be changed. Reset to default restores the standard order and the standard set of visible columns. The column Endpoint protection is hidden by default.
The order and the visible columns are stored with your user account, not in the browser, and apply in every browser you sign in with; each table keeps its own layout. The same chooser is available on the SNMP tab of the list and on Unauthorized Devices (there the checkbox column and the actions column stay in place). Hiding a column only changes the view: the search box still matches the values of hidden columns, and the exports of the list always contain every column. Columns added by later releases appear visible at the end of the list.
The Country column shows the flag and the name of the country the device's external IP address belongs to, in the language of your console. The list sorts by it, the search box matches the name (or the exact two-letter code), and the column can be moved or hidden in the column chooser like the others (see Columns). The exports of the list (CSV, JSON, HTML) carry the country as country_code (ISO 3166-1 alpha-2) and country_name (the English name).
The country is determined by the server at every check-in, from the address the device connects from, against the GeoIP database bundled with the server; no lookup leaves the installation. A device that reaches the server through a private address (on the LAN of an on-premises server, through a VPN into the server's network, or on a single-host Docker installation) has no country and shows an empty cell. A device that leaves through a VPN or a proxy shows the country of that exit. The same value feeds the global search (country: operator), the public API (geoCountryCode and geoCountryName, see X.9.8), the Devices by country tile of the country restriction tab and the country restriction of the server.
Every device belongs to exactly one group, in exactly one location, in exactly one tenant. To move a device between groups, use the Move Device dialog. Moving a device may change which policy it receives, because policy assignment is driven by Automations that match on device attributes such as group name. Policy changes take effect within the device's sync interval.
An agent that successfully contacts the server but has not yet been approved appears in Unauthorized Devices, not in the main Devices list. This keeps unknown or misconfigured agents out of your inventory until an administrator approves them.
Next to the internal and external IP address of an entry, the queue shows the flag of the country the external address resolves to, so an agent that registers from an unexpected place stands out before it is approved; the country is resolved the same way as for authorized devices (see Country of a device).
The approval flow is:
The agent is installed on a device with configuration that targets a specific tenant / location / group.
The agent contacts the server and registers as unauthorized.
An administrator reviews the entry in /unauthorized_devices: confirm the hostname, operating system, and the target tenant / location / group are correct.
If the row carries the chip Name already exists, an authorized device of the same name exists in your tenants and the entry is most likely that device after a reinstall of its operating system (a reinstalled system gets a new hardware ID and, with a fresh installer, a new access key). Use the row action Adopt as reinstall instead of approving.
The dialog lists the devices of that name with tenant and location, last contact, external IP address and online state, and preselects the device of the same tenant that is offline with the oldest contact. The chosen device takes over the new agent's access key and hardware ID and keeps its tenant, location, group, policy, label and history; the unauthorized entry is removed. Approving instead creates a second device. The action needs the same permission as approving. If the previous device still shows as online, the reinstalled agent also appears here for you to adopt.
Adjust the target group if needed.
Approve the entry. The device is created in the authorized inventory and begins receiving policies and automations.
Optionally set a label immediately after approval using the Edit_Label dialog.
Entries that reported a security incident are shown in red with the chip 🕵️ Script kiddie alert, and the row action Show security incident opens the incident (see 3.8 Security incidents). Check such an entry before you approve it.
Rejecting an unauthorized device removes it from the queue; the agent re-registers on its next poll and reappears unless you block it at the network or agent level.
Selecting a device in the list opens its detail view. The detail view shows everything the Console knows about the device:
Identifying information: hostname, label, tenant / location / group assignment, operating system, last-seen timestamp, IP addresses reported by the agent. The hardware section lists the manufacturer and model of every device; desktop agents report them from 3.3.0.11 on (Windows, Linux, and macOS as Apple with Model Name (Model Identifier)), older agents show Not reported.
Geo location: below the external IP address, the line Geo location shows the flag, the city, the region and the country of the external address. City and region are resolved against the GeoIP database of the Web Console when the device is opened; the country stored with the device is used when the database has no record. The line appears only for a public external address; a device behind a private address shows Geo location: Not available for a private address instead, and a device that leaves through a VPN shows the location of the VPN exit, as on the world map.
Status: current online / offline / error state, and the agent version.
Custom fields: values for every custom field defined in Collections, editable per device. Each field is one Label: value line like the other device details: a multiline value keeps its line breaks, a long value is shortened to four lines with Show more, an empty field shows -, and the copy button next to a value copies it. A manual field without a device value shows the value inherited from the group, location, tenant or global level greyed out, with an icon whose tooltip reads Inherited from …; a value written by a script or the public API has an icon with the tooltip Set by script on … or Set by API on …. On phones and touch devices these texts appear under the value instead. A Secret field shows a mask and a Reveal secret button for accounts with the reveal permission.
Events: recent operational events scoped to this device; a link into the full Events page is available.
Policy: the single policy currently assigned to the device (or - if no automation matched and no default policy is set). A policy that comes from the default policy is marked Default policy.
A +N chip next to the policy in the list counts the sensors and jobs that automation rules add on top of it; its tooltip names them and the rule each comes from. The detail view lists them under Assigned policy as Additional sensors and Additional jobs, expandable to name and rule, and warns when rules would add items to a device that has no policy, because nothing is handed out then. Only items the device actually receives are shown: a sensor for the device's platform, a job for its platform or platform System.
The list and the detail show the state the device last received from the server (the decision of its last evaluation), not a fresh evaluation of the rules. A device that has no stored state yet, while rules on services, applications or custom fields exist, shows - with an hourglass and the tooltip Evaluated at the device's next sync. See Chapter 5 — Automations for how assignment works, Chapter 5.2.2 for when a change shows up and Chapter 5.6 for the items.
Actions: per-device operations (remote control, remote shell, file browser, registry editor, event log viewer, service manager, wake-on-LAN, uninstall application, SNMP tools) and the bulk actions covered in 3.4 and 3.5.
The per-device actions open the dialogs below. Each dialog targets the currently selected device (or the set selected for bulk actions):
Service Editor (Windows), Service Editor (Linux / macOS)
Diagnostics and tools
Event Details, SNMP Tools, Uninstall Application
Network
Wake on LAN
The exact availability of some dialogs depends on the device's operating system: for example, the Registry Editor is Windows-only, and the Linux / macOS Service Editor applies only to Linux and macOS devices.
Open the device detail view and the tab or section the definition contributes.
Click the pencil next to the value. The field opens for editing on its line; a Secret value is typed into an empty password field.
Save with the check mark, or press Enter (Ctrl+Enter in a Multiline field). Escape or the cross discards the change. Leaving the field does not save it, and an empty value cannot be saved.
To let the device inherit the group, location, tenant or global value again, open the editor, click Remove device value and confirm. The device's own value is deleted and the inherited value appears greyed out with its Inherited from … icon; without an inherited value the field shows -.
Reveal secret next to a secret field shows the stored value. It requires collections_custom_fields_reveal_secrets and writes an audit entry each time.
Editing needs collections_custom_fields_edit; without it no pencil is shown and the fields are read-only. Only Manual fields can be edited; Job Result and SQL Select fields are read-only for every account. Every saved value marks the device for a policy re-sync, so scripts that use the value receive it at the next check-in. When an automation rule compares the field, the rules are evaluated for the device right away and the device is pushed when its assignment changed (see Chapter 5.2.2). Defining which custom fields exist, and setting values on tenant, location, group or global level, happens at the Collections level; see Chapter 8.4 — Custom Fields. Scripts read the values through variables and can write them back; see Script variables and custom fields in scripts and Write custom field values from a script.
The detail view shows the Events feed filtered to the events of this device. This is usually where you go first to diagnose why an action did not take effect: a failed policy deployment, a script that did not run, a sensor without readings.
The USB Devices tab of a Windows device lists the whitelist entries that apply to the device and the devices it reported as blocked. Above the list, a status line shows the device's Device Control learning state:
Status line
Meaning
Learning connected devices until …
A learning period runs. Every device connected in this time is whitelisted for this device.
Learning the devices connected when learning started (at the latest until …)
A period of the kind Devices connected when learning starts runs.
Learning requested; it starts at the next policy sync of the device
A re-learn was requested and starts when the device fetches its policy.
Connected devices learned on … under policy …
The last learning period has ended.
Learned under the policy-wide auto-whitelist of an earlier version; no learning period is running
The device learned before 3.3.0.11.
Connected devices have not been learned on this device
No learning has happened yet.
Two actions sit next to the status line:
Re-learn connected devices: the device learns the devices connected to it again, for the learning period of its policy, starting at its next policy sync. The sync is requested right away, so a connected device starts within moments. The device's policy must have Device Control on; otherwise the console says so and nothing is changed.
End learning now: shown while a period runs or is requested. It ends the period at once; devices connected afterwards are blocked unless a whitelist entry applies to them.
Both actions ask for confirmation and, where it is set up, for the same additional sign-in confirmation as the other remote tools. They require the permission devices_usb_learning and access to the device's tenant, and each one is written to the audit log. devices_usb_learning is part of the built-in Administrator role and of the Technician template; the Helpdesk, Read-only and Reporting templates do not include it. For the learning options of a policy, see Chapter 6.8. To let several devices re-learn at once, use Re-learn connected devices on the Whitelist tab of Device Control (see Chapter 8.7).
The Devices page can run one operation on many selected devices at once:
Bulk remote shell: execute a command on every selected device and collect the results.
Move devices: move the selected devices to another group with the Move Devices dialog.
Only one selection mode is active at a time: switching on moving devices or bulk remote shell switches the other off and clears the selection.
The bulk remote shell flow uses two dialogs:
Bulk Remote Shell: pick the command to run, confirm the target set, and launch.
Bulk Remote Shell Results: display per-device results as they arrive, including stdout, stderr, and exit status.
Each device in the bulk dialog shows a status:
Status
Meaning
Pending
Nothing has been executed yet.
Executing
The command was sent and the device has not answered yet.
Completed
The device returned its output. An answer that arrives after the timeout is still shown and switches the device to Completed.
Timeout
The device did not answer within the timeout set in the dialog.
Not connected
The device has no connection to the remote agent. The command is not sent to it.
Rejected
The command was not executed because the device's policy disables the remote shell or your account may not use the remote shell on this device. The output names the reason.
Failed
The command could not be sent or delivered, or the connection between the console and the NetLock RMM server was lost before the device answered.
"Online" in the device list is not the same as "remote connected". A device counts as online while its Comm agent checks in, but remote shell commands go through the Remote agent's connection to the server. A device whose Remote agent is stopped, still reconnecting or blocked by rate limiting, as well as every Android and iOS device, can show as online and still be "Not connected". The dialog checks the remote connection when it opens and again when you execute, lists how many devices are skipped, and counts them as done in the progress counter. The pulsing green status icon in the device list marks devices whose Remote agent is connected.
Warning: Bulk actions run on every selected device without further per-device confirmation. Double-check the selection before you launch a bulk command on a production fleet.
Tip: For repeatable work, save the command as a script in Collections and invoke the script rather than typing the command every time.
Individual devices support remote access via the Console:
Remote shell: a fire-and-forget shell session on the device (PowerShell on Windows, Bash or the default shell on Linux and macOS), opened from the Remote Shell dialog. Every completed classic remote shell command writes an event "Remote shell command executed." (type Remote Shell) on the device with the output; the command text itself is not stored.
Real-Time Remote shell: an interactive shell session on the device (PowerShell on Windows, Bash or the default shell on Linux and macOS), opened from the Remote Shell dialog.
Remote control: a graphical remote-control session to the device's desktop, opened from the Remote Control window.
Remote control in NetLock RMM does not use VNC or RDP. The agent captures the device's screen and streams it as JPEG frames through the NetLock server to the viewer; mouse, keyboard and clipboard travel the same way back. Remote Control on the device opens the remote control window, which connects to the server and starts the session; there is no transport to choose.
The same session can be opened from the Relay App and the NetLock app with a relay API key. What each viewer offers, how a session starts on Windows, Linux and macOS devices, recording, the clipboard and pasting files are described in A.7 Remote screen control; the stream modes are in A.7.5, the viewers in A.7.9. For the Relay App see Remote-control a device with the Relay App.
The Device_World_Map page at /device-world-map visualises your fleet geographically. Each device is plotted on a world map based on IP-geolocation data captured when it reports to the server.
Use cases include:
Confirming a device claims to be where you expect it to be (an unexpected pin in another country deserves a closer look).
Assessing the impact of a regional issue, for example how many devices are on a specific coast during a power event.
Communicating fleet spread to non-technical stakeholders in a single screenshot.
The map respects your tenant / location / group context: selecting a tenant in the header narrows the map to that tenant's devices only.
Note: Map accuracy depends on the quality of IP geolocation for the device's external IP. Devices behind a VPN will appear at the VPN exit rather than the physical device location. The IP lookup happens locally on your NetLock RMM server; no lookup leaves the server. The details drawer of a marker shows the flag of the country next to the resolved place. The Country column of the devices list and the Geo location line of the device details use the same database (see Country of a device), and so does the country restriction of the Web Console and the server.
Many devices carry a web interface of their own: the management pages of a printer, a switch, a UPS, a NAS, or a web server running on the device itself. Web interface opens such a page in a browser window of its own, without a VPN and without a Relay App. The agent fetches the page and the NetLock server serves it to your browser through a temporary relay session, so the page appears under the address of your NetLock server.
For a device with an agent, the entry sits in two places:
Context menu: right-click the device row. The Web interface sub menu offers HTTPS (443), HTTP (80) and Custom…. The first two open the interface of the device itself straight away; Custom… opens the dialog.
Device details: the Web interface button in the action bar of the selected device opens the dialog.
The dialog asks for the target, the scheme and the port:
Web interface on this device: the interface the device serves itself (the agent connects to 127.0.0.1).
Remote host reachable from this device: a host on the device's network, given as hostname or IP address without scheme, path or port. The device acts as a jump host, as it does for a relay session.
HTTPS / HTTP: switching the scheme moves the port between 443 and 80 as long as the port is still one of the two defaults; a custom port stays.
Port: 1 to 65535.
Open opens a new browser window. The window checks your permissions and the device, asks the server for the session and then shows the device page. The first request can take up to 20 seconds while the agent opens the connection.
The SNMP list of the devices page offers the same action for printers, switches and other SNMP devices. The Actions column of the list and the Web interface button in the detail panel open the dialog with the address of the SNMP device filled in. Because an SNMP device has no agent, one of the agents that know the device carries the connection: the agent that monitors it, the agent that discovered it, or any agent that has reported it in a discovery scan. The dialog lists these agents, online agents first, with the monitoring agent preselected. An SNMP device that no agent monitors, discovered or reported has no agent to carry the connection; the action is shown disabled and the tooltip says why.
Every web interface opened this way is a web access session: a temporary relay session of kind "Web" that is listed on the Relay Server page and can be closed there (see Chapter 9.2 — Web access sessions). What to expect:
The session ends after 15 minutes without a request or WebSocket traffic, or after 8 hours at the latest, whichever comes first. Closing the browser tab does not end it; the idle timeout does. Opening the same target again while the session is alive reuses it.
Only the account that opened the session can use the window. The link the window follows works once and for 60 seconds; afterwards a browser cookie bound to the session is required, so the address cannot be handed to somebody else.
Device pages with self-signed certificates work. The connection between your browser and the NetLock server keeps its own certificate.
Downloads (logs, configuration backups) and uploads (firmware) are streamed. Behind your own reverse proxy make sure request bodies are not limited and read timeouts allow long uploads.
Pages that load their assets from absolute paths, redirect, set cookies, ask for a password (Basic or Digest authentication) or use WebSockets work. WebSockets are forwarded like any other request, also when the page opens them on an absolute root path (wss://<server>/api/...), which single-page interfaces of NAS systems, hypervisors and network controllers do. A page that only talks over its WebSocket after loading counts as active; the idle timeout starts once the socket is quiet.
Pages that declare a base address (<base href="/">, usual for Blazor, Angular and many other single-page interfaces) are delivered with the base address inside the session, so their links, scripts, sockets and client-side navigation stay in the session. Sign-in forms of such applications, including their protection cookies, work as well. Pages that set their base address from a script or build addresses from the server root keep using the redirect of absolute paths described above.
Two limits of WebSockets on absolute root paths: a socket whose handshake needs a cookie the device set works only when the page opens it under the session address (device cookies are scoped to the session; a socket on a root path carries none), and with two device pages open in the same browser such a socket goes to the page that was shown last.
Web app manifests (site.webmanifest) are fetched by browsers without cookies and therefore answered with 404 through the proxy; the page itself is not affected.
Two device pages in two tabs work.
Every opened interface is written to the audit trail with scheme, host, port and the device that carried the connection, and the step-up authentication of the remote tools applies.
The NetLock agent recognizes signs that it is being analyzed or tampered with on a device, for example tools for analyzing or modifying software, an attempt to inspect the agent's own components while they run, signs that the agent's connection is intercepted or redirected, traces of such tools on the device, and signs that the device is operated as an analysis or sandbox environment. When it finds them, it sends an encrypted report to your NetLock server, and only to your server. The detection applies to authorized and unauthorized devices.
A report describes the finding and the state of the device at that moment:
Reason: one or more of analysis tools, inspection of the agent, interception of the connection, traces of analysis tools, a device that appears to be operated as an analysis or sandbox environment.
Findings: the tool name, the kind of finding (process, shortcut, folder, proxy, certificate and similar), path, user, start time and whether the file is signed.
Network: configured proxies, local listeners, interception certificates, network adapters with addresses, gateways and DNS servers.
System: device name, domain, operating system and build, architecture, last boot, time zone, manufacturer and model, virtual machine hint, antivirus and firewall state.
Sessions: signed-in users with session type and logon time (client name and address for remote sessions), and the local administrators.
Processes: a compact list of running processes (name, process ID, parent, user, path).
New software: programs installed within the last 30 days.
Agent: installation time, installer package and authorization state.
A report contains no file contents, credentials, browser data or history, screenshots, keystrokes, clipboard contents, e-mails or document names. The server adds the public IP address the report came from. The content comes from the device and is treated as untrusted: the Web Console shows it as plain text only.
Click the chip, use Security incidents in the right-click menu of /devices, or the row action on /unauthorized_devices. The dialog shows the device, its tenant and location, the status (open, acknowledged, whitelisted, isolated), first and last report and the number of reports. For each incident it shows the reason, the findings, the data the agent deleted (for an isolated device, see below) and the context sections listed above. A device with several incidents has a selector; the newest is preselected.
Actions:
Export JSON: downloads all incidents of the device with their full reports (security-incident-<device>-<date>.json). The export is written to the audit log.
Acknowledge: marks the open incidents as acknowledged. The row is no longer red unless the device is isolated; a new report marks it again.
Whitelist device: the server no longer stores reports of this device and never isolates it. Open incidents are acknowledged and an active isolation is released. Use it for technician machines that legitimately run analysis tools. Remove from whitelist reverts it.
Unless the device is whitelisted or the automatic isolation is switched off, a device with a new incident is isolated:
It receives no policy, no jobs, sensors or scripts, no software deployments and no files from the server. Automations, App Hub, SNMP results and NetMesh links are refused for it as well.
The agent deletes locally cached data that came from the server (jobs, sensors, scripts, policy, App Hub data, logs and similar) and resets its local settings to defaults. Its connection to the server, its identity and the Endpoint Protection state stay in place. Device Control and App Control keep running with their last known state. The agent reports what it deleted, reset, kept and could not delete; the dialog shows this as Data deleted by the agent.
The device moves to the location Isolated of its tenant (Isolated (NetLock) if the tenant already has a location of that name). The system creates this location on first use; it cannot be renamed or deleted and no installers are built for it. The previous location and group are kept for the release. Technicians of the tenant keep seeing the device.
An unauthorized device stays unauthorized and remains on /unauthorized_devices. To analyze it, use Release for analysis in the incident dialog: the device is authorized, so remote shell, file browser and the other remote functions become available, but it stays isolated, stays in the location Isolated and still receives no policy, scripts or files. Releasing the isolation later returns it to the unauthorized state. Approving such a device the normal way keeps the isolation as well; that approval is kept when the isolation is released.
Remote functions (shell, file browser, task manager, services, screen control, event log and registry) stay available for an analysis, subject to the usual permissions, Endpoint Protection rules and audit log. Treat everything that comes from the device as untrusted and open downloaded files only in an analysis environment.
Release isolation acknowledges the open incidents, returns the device to its previous location and group, restores its previous authorization state and marks it for a sync; the agent leaves the isolation with its next status check and receives its policy again. The device is isolated again only if the agent reports new tools; to stop the reports entirely, whitelist the device. If the previous location no longer exists, the device stays in Isolated and has to be moved manually; a device that was moved out of Isolated by hand keeps its location.
The dialog names the installer package the agent was installed with and how many devices were installed with it. If the installer has leaked, two options are available:
Block new registrations only: the package can no longer register new devices; devices already installed with it keep working. This works for every package, including packages created through the agent download. Allow new registrations again reverts it.
Revoke and regenerate package: for managed packages only. The package ID is revoked and a new one is created, with new installers built in the background. Every device installed with the old package loses its connection and has to be installed again; a warning lists the number and the names of the affected devices first. This additionally needs the permission agent_installers_enabled.
Settings → Security → Security incidents has two switches, both on by default: Detect security incidents (off: the server stores no reports and isolates no devices) and Isolate automatically on an incident. Changing them needs the permission of the rate limiting settings.
Each incident writes one event of the type Script kiddie alert with the reason, the isolation and the deleted data, available in the event list and the dashboard event widgets.
The Web interface action needs relay_server_enabled and relay_web_access from the Relay Server group; for SNMP devices the sensors permission that shows the SNMP list as well.
Security incidents: devices_security_incidents_view opens the incident dialog and the JSON export, devices_security_incidents_manage acknowledges, whitelists, releases a device for analysis, releases an isolation and blocks the installer package. The red row and the chip are visible to everyone who sees the list.
Android devices: devices_remote_control covers viewing their screen and, when the policy allows it, controlling it (A.7.12); devices_mobile_locate locates a device and lets it ring, devices_mobile_message sends it a message.
Tenant-scoped users only see devices in tenants they have access to.
NetLock RMM organises every managed device into a three-level hierarchy: tenant, location, group. This chapter describes how to create and manage that hierarchy. Policies, automations and permissions are scoped along it, so plan it early in the deployment.
A tenant is the top-level organisational container. For an in-house IT team this usually maps to the company; for an MSP it maps to a customer.
A location is a subdivision of a tenant, typically a physical site or office.
A group is a subdivision of a location. It typically reflects how devices should be configured (Workstations, Servers, Laptops) rather than where they physically sit.
Every device belongs to exactly one group. Policies are assigned through automations, and an automation condition can name a tenant, a location or a group: a rule on a tenant matches every device in every location and every group of that tenant (see Chapter 5).
Tip: Keep groups focused on configuration intent. If a single policy applies to every device regardless of site, one group per location is plenty. If policies differ by device type, create device-type groups inside each location.
The Tenants page at /tenants is the entry point. It lists every tenant you have permission to see, along with summary information (device counts, last activity).
Open a tenant with the row action Manage to reach its Manage tenant page. From there you can rename it, change its contact information, or adjust tenant-wide settings (covered in 4.3). Editing a tenant does not affect its devices or their assignments; only the tenant metadata changes.
The tenant has no active devices you still care about.
No reports or scheduled deliveries reference the tenant.
You have archived any customer data you may need later: device inventory from the Devices page, events from Events & Audit, and any reports from Reports. (The tenant-list export at 4.5 only captures tenant metadata, not the data under the tenant.)
The delete dialog lists the automation rules that name the tenant or one of its locations, groups or devices: how many will be deleted and how many switched off, with the names of those you can see. They change when the server finally removes the tenant, after its agents are uninstalled (see §5.7).
Tenant-level configuration lives on the Manage tenant page at /tenant_settings. The page requires a tenant to be selected in the header context; if none is selected, choose one first.
The page has five sections:
General Information: editable fields for the tenant's name, company, and description. This is the metadata the rest of the Console refers back to (the name shown in reports, in exports, in the navigation selector).
Contact Persons: five contact-person slots with editable details. These are used as recipients and fallback contacts for tenant-scoped notifications and reports.
Report contacts: mail addresses, separated by commas, that receive the reports made for this tenant when a report schedule sends to the report contacts of its tenants (Chapter 11.10). Each address is checked when the settings are saved.
Locations: a searchable table listing every location under this tenant, with a Manage action on each row that opens the location's detail view (see 4.4). You can add a new location directly from this table.
Custom Fields: the values this tenant holds for inheritable custom fields, with the effective value per field. Devices of the tenant without a value of their own inherit them. See Chapter 8.4 — Scope and inheritance.
The Manage tenant page has no settings for branding, notifications, integrations or agent configuration. These are configured as follows:
Tenant metadata and contact persons are isolated per tenant: editing them in one tenant has no effect on another. For system-wide defaults that populate new tenant records, see A.12 Content defaults.
Enter a location name that reflects the site, for example Berlin HQ, Remote Workers, Datacenter A.
Save.
Locations are freeform; use as many as the geography of your deployment warrants. An MSP managing a customer with three offices typically creates three locations.
Locations are edited and deleted with the usual edit and delete actions. Deleting a location removes its groups; any devices in those groups lose their group assignment and must be reassigned before configuration flows to them again.
Change the group of the device on the Devices page (see Chapter 3). The agent picks up the new assignment on its next poll and any policies attached to the new group take effect.
Note: Moving a device between groups does not trigger a device reboot or re-authorisation. The agent starts receiving a different policy set.
The Export Data dialog, opened from the Tenants page, exports the list of tenants you are permitted to see. It is not a full tenant archive.
What is exported. One row per tenant, with these fields: id, tenant_name, guid, date (creation date), author (who created the record), description, and company. Devices, policies, events, audit entries, custom-field values and deployment histories are not part of this export; they are described in their own chapters and exported from there if needed.
Scope. Every tenant that matches your tenants permission list. If you are scoped to specific tenants, the export contains only those. The dialog always exports the full visible list; it has no option for a single tenant.
Formats. The dialog asks you to pick one output format:
JSON
XLSX (spreadsheet)
XML
HTML
Permissions. Any user with access to the Tenants page can run the export. The export needs no separate permission flag.
Steps:
Open Tenants.
Click the export action to open the Export Data dialog.
Pick the output format and confirm. The file downloads to your browser immediately.
If you need to archive more than the tenant list, for example a customer's full device inventory or audit trail before offboarding, run the relevant exports from Reports or Events & Audit, or use the export functions of the pages that hold that data.
Tenant, location, and group operations are gated by a tenant-management permission group. In addition, tenant-scoped user accounts (see Chapter 14 — Users & Roles) only see the tenants they are explicitly permitted to access, which also restricts every other feature area to those tenants.
Automations decide which policy a device receives and which sensors and jobs it gets on top of that policy. Event-driven and scheduled work, such as scripts started by a trigger, ticket creation or notifications, is covered in §5.9.
IF all of these conditions hold for a device THEN assign policy <name> and/or add sensors and jobs
A rule consists of:
a name and an optional description;
an enabled switch: a disabled rule is kept but never applies;
a priority, a number: when several rules match a device, the rule with the lower number wins (see §5.3);
a list of conditions, at least one: all of them have to hold (AND), and each condition can be negated (NOT);
the policy the rule assigns, and/or the sensors and jobs it adds to the device on top of that policy (see §5.6). A rule needs at least one of these actions.
A rule has a single step: it sets the device's policy and adds items to it.
Note: A policy on its own does nothing. Devices only receive configuration when a rule matches them and names a policy, or when a default policy is set. If no rule matches a device, the device receives the default policy marked on the Manage Policies page, if any; otherwise it has no policy and the Console shows - as its policy.
Automations are managed on the Manage Automations page at /automations.
A condition compares one fact of the device with what you configure. There are eleven condition types. The first four target an entity you pick from a list (the rule stores the entity's identity, not its display name). The next four compare the device record against values you type or choose. The last three look at the device's inventory and its custom fields (see §5.2.1).
Condition
What you pick or type
Holds when
Device
A specific device from the device list.
The device is that device.
Tenant
A tenant from the tenant list.
The device belongs to that tenant.
Location
One or more locations of one tenant.
The device belongs to that location, or to one of the selected locations.
Group
One or more groups of one tenant.
The device belongs to that group, or to one of the selected groups.
Internal IP-Address
The device's reported LAN IP.
The reported internal address equals the value.
Domain
The Windows or DNS domain name.
The reported domain equals the value. A device that reports no domain never matches.
Platform
One or more of Windows, Linux, MacOS, Android, iOS.
The device's platform is one of the selected ones.
Device attribute
An attribute, an operator and a value.
The attribute compares as the operator says (below).
Service
A service name or display name, an operator, a value and a status.
A service of the device's inventory has that name and that status.
Application
An operator and a name, optionally a version comparison.
An application of that name, and version, is installed on the device.
Custom field
A field definition, an operator and a value.
The device's effective value of the field compares as the operator says.
Entity conditions (Device, Tenant, Location, Group) are not affected by renaming. If you rename the tenant Acme to Acme Corp, every rule that targets it keeps working, because the rule does not store the name. A rule may carry at most one non-negated condition per entity type (one tenant, one location, one group, one device); a negated one ("NOT group Servers") may be combined freely.
Several locations or groups in one condition. A Location or Group condition can name more than one entry, up to 500. It then reads "Group is one of: A, B, C" and holds when the device is in any of them; negated it reads "Group is none of: A, B, C" and holds when the device is in none of them. This way one rule covers, for example, the "No print" group of each of thirty locations instead of thirty rules with the same policy.
All entries of one condition have to belong to the same tenant, and they have to lie inside the tenant or location the rule names elsewhere (a group outside the rule's location could never match); the dialog and the public API refuse anything else. Such a rule belongs to that tenant: it is visible to, and changeable by, accounts with access to it, like a rule with a single group. Device and tenant conditions always name exactly one entry.
What happens when the picked entity is deleted is described in §5.7.
Internal IP-Address and Domain compare the device's reported value to the value you type, after both sides are trimmed of surrounding whitespace and lower-cased. For the Internal IP-Address condition, an ::ffff: IPv4-mapped IPv6 prefix is also stripped before comparison, so a device reporting ::ffff:10.0.0.5 matches a rule expecting 10.0.0.5. These two conditions are exact matches and do not support CIDR notation or ranges. For patterns, use a Device attribute condition.
Device attribute compares one of the following columns of the device record, as the agent reported it at its last sync: device name, operating system, label, serial number, device class (Computer or Mobile, offered as a choice), architecture, manufacturer, model, mainboard, CPU, GPU, agent version, last active user, time zone, antivirus solution. The operators are:
Operator
Meaning
equals
The attribute equals the value.
contains
The attribute contains the value.
starts with
The attribute begins with the value.
matches pattern
Wildcard pattern: * stands for any run of characters, ? for exactly one (SRV-*, WS-??-BER).
matches regex
A .NET regular expression, matched case-insensitively. A pattern that does not compile is refused when the rule is saved.
All attribute comparisons ignore case and surrounding whitespace. A hostname pattern is therefore Device attribute → Device name → matches pattern; an operating-system version is Device attribute → Operating system → starts with.
Tip:NOT turns a single condition around, not the whole rule. Tenant = Acme AND NOT Device name matches pattern SRV-* covers every Acme device except the servers. A negated entity condition does not narrow the rule to that entity's tenant: NOT Tenant = Acme reaches every other tenant, which matters for the tenant rule in §5.5.
These three types read what the agent reported in its last inventory upload and the custom field values of the device. They let a rule follow a role rather than an organisation: "every device running the SQL Server service gets the database sensors", "every device with 7-Zip below version 23 gets the update job", "every device whose site_code field is BER gets the Berlin policy".
Service. Pick whether the Name or the Display name of the service is compared, the operator (equals, contains, matches pattern), the value and the status the service has to be in: any status, running or stopped. Names are compared case-insensitively, and a Linux unit name matches with or without its .service suffix, on both sides: a rule for sshd matches the unit sshd.service and the other way round. The status is mapped per platform: Windows reports Running and Stopped; Linux reports running or active (counted as running) and dead, inactive, failed or exited (counted as stopped); macOS reports Running and Stopped. A state outside these, such as Paused or activating, is matched only by any status. The condition holds when at least one service with the name has the status.
Application. Pick the operator on the application name (equals, contains, matches pattern) and the name. Optionally add a version comparison: equals, at least, below or starts with a version you type. Versions are compared numerically on up to four dotted components: 23 is read as 23.0.0.0, so at least 23 matches 23.01. A version that is not numeric is compared as text.
Custom field. Pick a field definition (secret fields are not offered; a secret is never compared), the operator (equals, contains, matches regex, is empty) and, except for is empty, the value. The condition reads the device's effective value: its own value, or, for an inheritable field without one, the value of its group, location, tenant or the global value, in that order (see Chapter 8.4). is empty holds when no level provides a value.
A device that has not uploaded an inventory yet, such as a freshly enrolled device or a mobile device, matches no service or application condition. The rule does not apply to it until the first upload; it is not an error, the rule simply does not match yet.
The server evaluates every rule against the device record, the last inventory upload and the custom field values it has stored; the Console's Check matching devices reads the same data. Because the inventory lives on the server, an inventory change reaches the rules without a Console click:
After every inventory upload of a device, and after every custom field write that concerns it (on the device page, through a script, through the public API or on one of its levels), the server evaluates the rules for that device only. When the result (the policy, the sensors and the jobs) differs from what the device last received, the device is marked out of sync and pushed at once. The change reaches an online device within seconds, otherwise it arrives at the next check-in. When nothing changed, nothing happens.
A rule on a service or an application therefore takes effect at the device's next inventory upload, which happens at its sync interval, not at the moment the rule is saved. A rule on a custom field takes effect when a value of that field is written, or at the device's next sync.
The devices page shows the state the device last received (see Chapter 3.3): the policy, its origin and the added sensors and jobs as the server decided them at the last evaluation. A device that has no stored state yet, while rules with inventory or custom field conditions exist, shows - with an hourglass and the tooltip Evaluated at the device's next sync; a device without such rules is evaluated live.
When a device syncs with the server, the server evaluates the rules and assigns the policy of the winning one:
Only enabled rules are considered. A rule matches the device when all of its conditions hold (a negated condition holds when its comparison does not). A rule with no conditions never matches.
The matching rules are ordered by priority (lower number first), then by the number of conditions (more conditions first), then by age (the older rule first).
The first rule in that order that assigns a policy decides the policy. Matching rules without a policy are skipped for this decision; they only contribute their sensors and jobs.
When no matching rule assigns a policy, the device receives the default policy marked on the Manage Policies page, if any. The devices list marks such an assignment with a globe icon next to the policy name, and the device detail names it as Default policy. Without a default policy the device has no policy.
The sensors and jobs of every matching rule are added to the device, each once (see §5.6).
The default policy never overrides a rule. Policies never layer or combine: a device runs exactly one policy at a time (see Chapter 6); sensors and jobs do add up.
The priority is a number on every rule; the lower number wins. When you create a rule, the dialog fills the priority in from the most specific organisation condition the rule carries and shows the value it chose:
Most specific organisation condition
Default priority
Device
100
Internal IP-Address
200
Domain
300
Group
400
Location
500
Tenant
600
none of these (only Platform, Device attribute)
700
The defaults keep the natural order (a rule for one device beats a rule for its group, which beats a rule for its tenant) and put rules without an organisation condition below every organisation rule, so Platform = Linux → Linux baseline applies only where no tenant, location or group rule sets a policy. A negated organisation condition does not count for the default.
You can type any number. To make a rule win over the organisation rules, for example "every device running the SQL Server service pattern gets the database policy, whatever its tenant says", give it a smaller number such as 50. The dialog keeps recomputing the default while you change the conditions until you edit the number yourself; Reset to default returns to the computed value. The Manage Automations page lists the rules in evaluation order and the Priority column is sortable.
Two matching rules with the same priority are separated by their number of conditions: the rule with more conditions is the more specific one and wins. Tenant = Acme AND Platform = Windows → Acme Windows (two conditions) beats Tenant = Acme → Acme fallback (one condition) at the same priority. With the same count, the older rule (the one created first) wins. A negated condition counts like any other.
Specific beats general by default. The default priorities follow the order device → internal IP → domain → group → location → tenant, so a setup that only uses one condition per rule behaves exactly as the defaults suggest.
The number is the order. Rules are reordered only through their numbers, not by dragging or moving them. To promote a rule, lower its priority number; to demote it, raise it. Two rules that should be ranked explicitly get two different numbers.
Combine instead of stacking. One rule with three conditions (Tenant = Acme, Platform = Linux, Device name matches pattern SRV-*) expresses "Acme's Linux servers", and its condition count makes it win over the plain tenant rule at the same priority.
Overlap is allowed but not merged. If two rules both match, only the first in the order applies.
A disabled rule is ignored by the evaluation. Use the switch on the list to take a rule out without deleting it.
No match is a valid outcome. A device that matches no rule receives the default policy if one is set; otherwise it runs without a policy.
The page at /automations lists every rule the account can see, in evaluation order:
Column
Content
Name
The rule's name. An Inactive chip marks a rule the evaluation can never apply as it is: one of its targets was deleted, or it neither assigns a policy nor adds a sensor or job (see §5.7).
Enabled
A switch. Turning it off keeps the rule but takes it out of the evaluation; turning it on puts it back. Needs automation_edit.
Priority
The number; the list is sorted by it, ascending, by default.
If
The conditions in words, for example Tenant: Acme AND Platform: Linux AND NOT Device name matches pattern "SRV-*". Hover for the full text.
Then
The policy the rule assigns, or No policy, and one chip per item type (+2) for the sensors and jobs it adds; the tooltip names them.
Author, Date
Who created or last changed the rule, and when.
Actions
Edit, Duplicate and Delete (each behind its permission).
Double-clicking a row opens the edit dialog. The search box matches the name, the description, the condition text, the policy name and the names of the sensors and jobs. Export data writes the list as JSON, CSV or HTML with the columns above plus the sensor and job names. Duplicate creates a copy named <name> (Copy) with the same conditions, priority, policy, sensors, jobs and enabled state.
When AI is enabled in Settings → AI/LLM, the AI Assistant button on the page explains which policy a device gets and helps plan rule sets; it works on the rules, policies, tenants and devices the account can see and does not change anything.
Name, Description, Enabled and Priority at the top. The priority shows its default and a Reset to default link once you have changed it (see §5.3.1).
If …: the list of conditions. Every line has a condition type, the inputs for that type, a NOT checkbox and a remove button. The inputs are a picker for entity conditions (for locations and groups a selection dialog, see below), a text field for the address and the domain, a multi-select for platforms, and attribute + operator + value for attribute conditions. Add condition appends a line. All conditions must hold; the dialog says so above the list. Problems are shown under the line, and the rule cannot be saved while one exists: a missing target, an empty value, two non-negated conditions of the same entity type, entries of different tenants in one condition, or a regular expression that does not compile.
Selecting locations and groups. The value field of a Location or Group line opens a selection dialog: a searchable list (name, tenant, location) with a checkbox per entry, Select all shown, and for groups a location filter with Select all groups of this location. Once an entry is selected the list shows only the entries of its tenant. The line then shows the selection (3 groups selected) and one chip per entry, which removes it with its close button. The list page names up to three entries of such a condition plus +n; the tooltip, the search and the export carry all of them.
Then …: the policy to assign, or Do not assign a policy; below it, for an account with the sensors or jobs permission of Collections, a multi-select of sensors and a multi-select of jobs the rule adds (name and platform). A rule needs at least one of the three. The dialog notes that items reach only devices with a policy, flags a job of platform System (handed out, never executed), and warns when a selected item runs on a platform the rule's platform condition excludes. See §5.6.
Check matching devices evaluates the conditions right now against the authorized devices within your tenants and lists the matches. For service, application and custom field conditions it reads the stored inventory and custom field values of every candidate on the click. It answers "does this rule match the device", not "would it win against the other rules"; the priority and the other rules decide that at sync time.
AI Assistant (when AI is enabled) proposes a rule from a natural-language description and fills the dialog with Apply Config. It only writes into the dialog's fields; you still review and save.
Tenant rule. Every tenant, location, group or device a condition names has to lie in your tenants. A rule without any tenant, location, group or device condition (only platform, attribute, address or domain conditions) reaches every tenant; only an account with access to every tenant can create, change, duplicate, enable or disable such a rule. Other accounts see it in the list and can open it read-only.
Delete removes the rule and its item assignments after a confirmation. The devices it covered fall back to whatever other rule matches them, or to the default policy, or to no policy, and lose the sensors and jobs only this rule added.
Note: Adding, editing, enabling, disabling, duplicating or deleting a rule marks every device out of sync and pushes a force-sync to the online devices the rule can affect. Devices do not wait for their next scheduled poll to re-evaluate their policy assignment; the change takes effect right away.
Note: Deleting a policy from the Policy Settings editor deletes every automation that only assigns it; an automation that also adds sensors or jobs keeps them and continues without a policy. The Delete Policy dialog shows both numbers before you confirm (see Chapter 6.3 and §5.7).
Besides a policy, or instead of one, a rule can add sensors and jobs from the Collections library to every device it matches. This is how one sensor reaches "all Linux servers of every tenant" or "every device running the SQL Server service pattern" without touching the policies of those devices.
Additive. The sensors and jobs of every matching rule are added, in evaluation order, each item once. They come on top of the sensors and jobs of the device's policy; an item that is both in the policy and in a rule runs once. Disabling or deleting a rule removes what only that rule added at the device's next sync; an item the policy also carries stays.
Only with a policy. Items are handed out only to a device that has a policy, from a rule or from the default policy. A device without a policy receives nothing, because the agent runs no sensors and jobs without a policy; the device detail says so when rules would add items to such a device.
Platform. A sensor is handed out only to devices of its platform; a job to devices of its platform or, for platform System, to every device, where such a job is handed out but never executed. The dialog warns when a selected item can never reach a device because of the rule's platform condition.
Discovery sensors. Sensors the SNMP discovery manages are not offered; they belong to their discovery.
Permissions. The sensor picker appears with collections_enabled and collections_sensors_enabled, the job picker with collections_jobs_enabled. An account without the permission sees neither, and saving the rule leaves the stored items of that type untouched.
Where it shows. The Then column on /automations counts the items (+2) and names them in the tooltip. On /devices a +N chip next to the policy counts the items the server hands out to the device, and the detail view lists them under Assigned policy with the rule each one comes from (see Chapter 3.3).
Tip: The priority of a rule that only adds items does not matter. Its number does not compete with the policy rules, because only rules that assign a policy are used for the policy decision. Leave it at the proposed value.
Rules follow the organisation and the library. When a tenant, location, group or device is deleted (in the Console, through the public API, or by the server's deferred tenant deletion), every rule that names it is adjusted:
The condition naming the deleted entity is removed from the rule. A Location or Group condition that names several entries only loses the deleted one and the rule stays enabled: the list gets shorter, so the rule reaches fewer devices, never more. When only one entry is left the condition is stored in its single-entry form again; when the last entry goes, the condition is removed as described below.
A negated condition is dropped: the devices it excluded are gone, so the rule means the same without it and stays enabled.
A non-negated condition was what narrowed the rule to that entity. Without it the remaining conditions would reach devices the rule was never meant for: Tenant = Acme AND Platform = Linux would turn into Platform = Linux for every tenant. What happens next depends on what is left:
The rule still names another tenant, location, group or device without negation (Tenant = Acme AND Device = SRV-01, the device is deleted): the rule is disabled and stays off until you have looked at it.
The rule names no other tenant, location, group or device (Device = SRV-01 AND Platform = Linux, the device is deleted): the rule is deleted. Its tenant came only from that condition; kept, it would turn into a rule for every tenant that only accounts with access to every tenant could still change.
A rule left with no condition at all is deleted as well, whether the removed condition was negated or not.
Every rule deleted or disabled this way gets an entry in the audit log (/audit, entity automation, action delete or update), recorded under the account, API token account or system (automatic deletion by the server) that deleted the entity.
The affected devices are brought back in sync.
The confirmation for deleting a group, location or tenant, for uninstalling an agent and for deleting unauthorized devices shows how many rules will be deleted or switched off and names the ones you can see (up to five per outcome; rules of tenants you cannot access are only counted, and without access to Automations you see the numbers only). It also says when the rules change:
for a group or an unauthorized device, right away;
for a device, once it is removed after the agent uninstall;
for a location, partly right away (the location and its groups) and partly as its devices are removed;
for a tenant, when it is finally removed.
A rule that was disabled this way shows the Inactive chip on the list. Open it, give it the conditions it should have now, and enable it again.
When a sensor or a job is deleted, it is removed from every rule that adds it; a rule left with neither a policy nor an item is switched off and shows the Inactive chip. When a policy is deleted, the rules that only assign it are deleted with it, while the rules that also add sensors or jobs keep those and continue without a policy; the Delete Policy dialog shows both numbers before you confirm.
The only results of a rule are a policy and added sensors and jobs (see §5.3). In particular:
Triggers. A rule is not started by an event ("when a disk fills up, run this"), a schedule ("every Sunday at 02:00, do X"), a webhook or a "Run now" button. The public API can create and change rules (see X.9.5), but a rule still only assigns a policy and adds sensors or jobs.
Scripts. An automation does not execute a script itself. It can add a scheduled job to a device, which the agent then runs on the job's own schedule.
Notifications and tickets. An automation does not send an email, Teams message, Telegram message or webhook, and does not open a ticket.
One step, AND only. One rule has one list of conditions that all have to hold and one set of actions: the policy and/or the items. Two alternatives are two rules. The only "or" is inside a Location or Group condition that names several entries (§5.2).
Stored data only. A rule can look at the last inventory upload and at custom field values (§5.2.1), not at the online state, a running process, the current load or the time of day.
History. Automations have no history view of their own. Policy changes that result from rule evaluation are recorded in general Events (see Chapter 12) and reflected in the device detail panel's Assigned policy field; changes to the rules themselves are in the Audit log.
Automations assign policies, sensors and jobs. Work of the kind "when X happens, do Y" belongs to other features, mainly these three:
Sensors (see Chapter 8.3) are the right tool when you want the agent to watch a metric and react. A sensor samples its category on a schedule, raises a notification when the notification threshold is crossed, and runs an action script when the action threshold is crossed. This is how you express "when CPU exceeds 90% for five samples, run a cleanup script".
Jobs (see Chapter 8.2) are the right tool when you want a script to run on a device on a timetable. A job picks a script and assigns it one of the twelve supported schedules (boot, one-shot date, recurring interval, recurring on specific weekdays, and so on). This is how you express "every Friday at 18:00, rotate the backup script".
Patch Management installs approved patches on a schedule without an automation. See Chapter 7 for the approval queue and Chapter 6.12 for the per-policy rollout rules.
Automations do not call a sensor, run a job or start a deployment. They decide the policy a device runs under, which in turn can include jobs, sensors and patch rules, and can add further sensors and jobs from the library on top. What those sensors and jobs do is defined in Collections, not in the rule.
Consider an MSP managing three tenants, each with a small office and a mix of workstations and servers. A reasonable, minimal rule set, shown with the priorities the dialog assigns by default:
Priority
Conditions
Policy
100
Device = ACME-DC01
Acme Domain Controller
400
Group = Acme / Berlin / Servers
Acme Server Baseline
400
Group = Acme / Berlin / Workstations
Acme Workstation Baseline
400
Group = Globex / HQ / Servers
Globex Server Baseline
400
Group = Globex / HQ / Workstations
Globex Workstation Baseline
400
Group = Initech / Remote / Laptops
Initech Laptop Baseline
600
Tenant = Acme AND Platform = Linux
Acme Linux Baseline
600
Tenant = Acme
Acme Fallback
600
Tenant = Globex
Globex Fallback
600
Tenant = Initech
Initech Fallback
How this resolves in practice:
ACME-DC01 syncs. The device rule (100) and the Acme tenant rule (600) both match; the lower number wins and the device receives Acme Domain Controller.
A new workstation joins Acme / Berlin / Workstations. The group rule (400) and the tenant rule (600) match; the group rule wins and the device receives Acme Workstation Baseline.
A Linux box lands in tenant Acme in a group without a rule. Two rules at 600 match: Tenant = Acme AND Platform = Linux has two conditions, Tenant = Acme has one, so the Linux rule wins and the device receives Acme Linux Baseline. A Windows box in the same situation receives Acme Fallback.
A device outside all three tenants. No rule matches. Unless a default policy is set on the Manage Policies page, the device receives no policy and the Console shows - as its policy. To change that, add a tenant rule or a default policy.
Tip: Keep the tenant fallback rules explicit. A tenant-level catchall is easier to troubleshoot than a setup where some devices get no policy because no rule happened to match, and it makes the order (group 400 → tenant 600) visible in the list. The default policy on the Manage Policies page is the alternative catchall: it needs no rule, sits below every automation, and the devices list marks the devices that got their policy from it.
Tip: To take one role out of the organisation order, for example "every device whose name starts with SQL- runs the database policy, in every tenant", create Device name matches pattern SQL-* → Database Servers and give it a priority below 400, for example 50. Left at its default of 700 it would only apply to devices no organisation rule covers. If those servers should keep their organisation policy and only get a database sensor on top, create the same rule with Do not assign a policy and the sensor instead; the priority then does not matter.
Editing a policy and editing an automation have different effects:
Editing a policy changes what every device already assigned to it will receive at next sync. The set of devices is unchanged.
Editing an automation changes the set of devices a policy is routed to, or the sensors and jobs added to them. Every affected device re-evaluates its assignment immediately.
You will rarely need to touch automations once the routing is stable. Day-to-day configuration changes happen inside the policies themselves (Chapter 6).
automation_enabled: master flag. A user without this flag does not see the Automations navigation entry and cannot reach /automations.
automation_add: ability to create a new automation and to duplicate one.
automation_edit: ability to edit an existing automation and to switch it on or off.
automation_delete: ability to delete an automation.
A user with automation_enabled but neither _add, _edit, nor _delete has read-only access and can view the rules without changing them. On top of these flags, the tenant rule of §5.5 applies: rules are visible and editable within the account's tenants, and rules without an organisation condition can only be changed by an account with access to every tenant. The sensor and job pickers of the dialog need the Collections permissions collections_sensors_enabled and collections_jobs_enabled (see §5.6).
A policy is the central configuration unit in NetLock RMM. Almost every feature you can tune on a device lives inside a policy: antivirus behaviour, firewall rules, remote-access capabilities, tray branding, patch rollout, scheduled jobs and monitoring sensors. This chapter is the reference for the policy object, the Policies list page, and every tab of the Policy Settings editor.
Windows-specific controls (Microsoft Defender Antivirus, Application Control, USB Device Control).
Linux-specific controls (UFW firewall).
Sensors and Jobs attached to the policy.
Patch Management rollout rules per platform.
Which App Hub apps the tray icon exposes on devices under the policy.
These rules apply to every policy:
A device is assigned at most one policy at a time. Policies do not layer, merge, or inherit. The agent runs the one policy assigned to it, or no policy at all.
Policies do not attach to tenants, locations, groups, or devices directly. Every assignment goes through an automation (see Chapter 5). The Policies, Groups and Devices pages have no button that applies a policy.
Policies have no templates. A new policy starts with the editor's default settings, also when it is created through the Public API. To base a new policy on an existing one, duplicate it.
Policies have no version history. Edits apply in place and cannot be rolled back. Duplicate the policy first if you want a copy to return to.
The Author column is for information only. It records who created the policy. Edit and delete access depend on the policies_edit and policies_delete permission flags: any user with those flags can edit or delete any policy, whoever created it. Whether the row is visible depends on policies_enabled.
Tip: Make it a habit to duplicate a policy before you edit it. Without a rollback, the copy is the only way back from a bad change, and duplicating takes about two clicks.
The Manage Policies page at /policies lists every policy in the system. The table shows:
Column
Sortable
Notes
Name
Yes
The policy name used by automations to reference this policy. The default policy carries a Default policy chip next to its name.
Description
Yes
Free-text description set at creation.
Author
Yes
The user who created the policy.
Created
Yes
Creation timestamp.
Actions on the page (toolbar above the table):
Add opens the Add Policy dialog. Fields: Name, Description. Save creates a policy that starts with the editor's default settings: every tab is at its default state, the same as for a policy created through the Public API.
Manage navigates to the Policy Settings editor for the selected policy (/policy_settings). Duplicate and Delete are in that editor, not on this list (see §6.3).
Set as default policy (star icon in the actions column, requires policies_edit) marks the policy as the default: every device that no automation assigns a policy to receives it, including the devices of tenants created later. At most one policy is the default; marking another one moves the mark. On the current default the icon becomes Remove default policy. Both directions ask for confirmation first, because they change the policy of potentially many devices, and then trigger a fleet-wide policy sync. A caption above the table states the rule.
Export (download icon) opens the export dialog. It exports the policy list as JSON, XML, or HTML, one row per policy with the columns above. The export contains the list only; the settings in the tabs of each policy are not included.
Note: The list page has no Delete or Duplicate button. To delete or duplicate a policy, open it with Manage first.
The Policy Settings editor at /policy_settings is a tabbed workspace. Eight top-level tabs cover everything a policy can configure. A tab stays loaded once opened, so you can switch between tabs and keep your unsaved edits until you save or leave the page.
Above the tab strip sits the editor toolbar:
Back returns to the Manage Policies list without saving.
Save (visible when policies_edit is granted) commits all in-progress edits across every tab in one go. Until you click Save, your changes are held in the editor's in-memory state and are lost on a hard reload.
End-user text language (also policies_edit) fills every end-user text of the policy from a language preset, see §6.5.1.
Duplicate (also policies_edit) opens the Duplicate Policy dialog. The dialog pre-fills the new name as <original> (Copy), which you can override; it then copies the policy as a new row. Duplicating is the only way to base a new policy on an existing one. The copy is never the default policy, even when the source is.
Delete (requires policies_delete) opens the Delete Policy confirmation. Deletion cannot be undone. Every automation that only assigns the policy is deleted with it. An automation that also adds sensors or jobs keeps them and continues without a policy. The dialog shows both numbers before you confirm. The devices those automations assigned the policy to fall through to the next matching rule or the default policy, or have no policy when neither exists (the Console shows - as their policy). If the policy is the default policy, the dialog says so as well. The default mark is removed with the row, and devices that no automation assigns a policy to have no policy afterwards.
Warning: Deleting a policy also deletes the automations that assign nothing but it, and the default policy mark disappears with the row. Check the numbers in the dialog before you confirm, and route the affected devices to a replacement policy afterwards if they should stay managed.
The eight tabs:
Agent. General agent behaviour and remote-control capability toggles. Every policy touches this tab.
Tray Icon. End-user tray behaviour and branding. Applies to every device under the policy.
Windows. Windows-only features, grouped into three sub-sections: Microsoft Defender Antivirus, Application Control, USB Device Control. Settings in this tab have no effect on Linux or macOS devices.
Sensors. SNMP sensor configuration attached to the policy.
Jobs. Scheduled job definitions attached to the policy.
Patch Management. Rollout rules for Windows, Linux, macOS and Docker, each with its own sub-tabs for general settings, approval filtering, deployment rings, schedule, reboot, notifications, and retry.
App Hub. Which apps from the global App Hub appear in the tray icon for devices under this policy.
The Agent tab controls the behaviour of the agent process itself. It has two sub-tabs: General and Remote Control.
General. The agent's own settings and those of Android devices:
Sync interval: how often the agent polls the server, in minutes. The allowed range is 5 to 1440 (one day). Short intervals keep the Console responsive to configuration changes; long intervals reduce server load for large fleets.
Mobile sync interval (minutes): how often an Android device reports in. Android runs periodic work no more often than every 15 minutes, so shorter values are raised to 15.
Removal PIN (mobile devices): the PIN the user has to enter on the device before the app removes its enrollment, 4 to 8 digits; empty allows removal without a PIN.
Auto-update agent: whether the agent installs new agent versions as soon as the server offers them. On by default. Leave it on unless you maintain a golden image; older agents may become incompatible over time. Unchecking the option asks for confirmation (Keep enabled / Disable anyway), and while it is off a warning stays below the checkbox. How many agents update at the same time is set in Settings → Updates.
Remote Control. A master toggle and a set of per-capability switches:
Enable remote service: master switch for all remote operations on the device. Everything below depends on it.
Remote Shell: permits interactive shell sessions.
File Browser: permits remote file transfer.
Task Manager: permits remote process management.
Service Manager: permits remote service start/stop/restart.
Registry Editor (Windows only): permits remote Windows registry editing.
SNMP Tools: permits SNMP GET / Walk / Monitor operations from the Console.
Remote Screen Control: the switch Enable permits remote screen sessions. The Access mode dropdown has two values:
Attended (user confirmation required & tray icon needs to be enabled!): the on-device user must approve each session, and the tray icon must be enabled in §6.5 for the approval prompt to render.
Unattended (no user confirmation required): the session starts without user interaction.
Allow audio calls: lets operators with the Audio call permission call the signed-in user of a Windows device from the end user chat (see A.7.7). On by default; the switch is disabled while Remote Screen Control is off, because calls need Remote Screen Control. Calls are not recorded.
Note: Remote Screen Control streams JPEG frames from the agent through the NetLock server; it is not VNC or RDP. See A.7 Remote screen control for the deployment-wide defaults.
Android devices: The Enable switch of Remote Screen Control also decides whether an Android device can be controlled. With it on, accounts with devices_remote_control tap, swipe, use the system buttons and type from the web console (A.7.12). Access mode does not apply there: every session needs the user's consent on the phone and the remote control service switched on in the app. Viewing the screen of an Android device does not depend on this switch. The server reads it when a session starts, the app with its next sync.
Disable the individual capabilities for high-sensitivity devices where you want, for example, a remote shell but not file transfer.
The Tray Icon tab shapes what end users see on their device. Branding is set per policy, so a single deployment can present different branding to different customers.
A master Enabled switch at the top of the tab controls everything below. If it is off, the tray icon does not run on devices under this policy.
General. A single field:
Tray Icon Title: text shown in the tray window's title bar.
Buttons. Per-entry visibility for the built-in tray menu items. The user opens the tray menu with either mouse button on the tray icon; a second click on the icon closes it again:
Show About Button: shows the About entry. When on, the About Button Title field sets the menu label.
Show Exit Button: lets the user close the tray icon. When on, the Exit Button Title field sets the menu label. Hide the exit button for managed devices where the tray is mandatory.
App Hub. Controls whether the App Hub window is reachable from the tray, and customises the labels inside that window:
Show App Hub in tray context menu: master toggle for the App Hub entry. The Context menu label sets the label shown in the tray menu.
App Hub window text overrides (all leave-blank-for-default, or filled from a language preset, see §6.5.1):
Note: This section only governs visibility and labels of the App Hub in the tray. The actual catalogue of apps offered to devices under this policy is curated in §6.13.
AI Chat. Controls the optional end-user AI assistant reachable from the tray; its conversation history is stored encrypted (see Chapter 13). The chat is off until you enable it here, and every user-facing string can be branded:
Show AI Chat in tray context menu: master toggle for the AI Chat entry, with a Context menu label.
Registration. A terms/privacy text the user must accept before entering credentials, the accept-checkbox label, a confirm-password label, and a customisable "forgot your password and your chats cannot be recovered" warning.
Identity. Whether the username must be an email address; when off, the tray prompts for a free-form Username instead.
Password rules. Minimum length and whether an uppercase letter, lowercase letter, number, and/or special character are required.
Default monthly token limit: the starting per-user limit applied to newly registered accounts (operators adjust it later in the Customer AI dialog).
Additional texts. Every remaining label, button, and status/error message in the tray chat can be overridden (all leave-blank-for-default, or filled from a language preset, see §6.5.1).
The accounts themselves (activation, per-user and per-tenant token limits, auto-activation and statistics) are managed in the Console's Customer AI dialog. See Chapter 13.6.
Support chat. Lets end users ask the administrators for a chat from the tray menu (entry Chat with support). Off until enabled here. It needs Remote Screen Control on the Agent tab (§6.4): the editor warns while that is off, and the agent rejects every request without it.
Allow end users to start a chat: master toggle for the entry, with a Context menu label.
Let the user describe the problem: shows an optional message field (up to 500 characters); the text becomes the first message of the chat the administrator opens.
Request window texts. Window title, message placeholder, the request / cancel / retry buttons, the waiting text, the text once an administrator was notified, the accepted text ({0} is the administrator's name) and the text shown when nobody is available. Empty fields use the English defaults shown as placeholders; a language preset fills them in another language (§6.5.1).
A request reaches every administrator who is signed in to the web console, holds the End user chat permission (devices_remote_chat), has access to the device's tenant and has not paused chat requests with the switch in the header of the console. The first who accepts gets the end user chat of the device with the user's session pre-selected, the others see who took it. Without such an administrator the user is told right away that nobody is available, and a request ends after 120 seconds without an answer. Every outcome is written as an event of type End user chat on the device and kept in the request history for 30 days.
Support tickets. Lets end users open a support ticket from the tray menu (entry Support) and follow it there. Off until enabled here. The tickets land in the console's ticket system (Chapter 10.2), which has to be switched on there for technicians to work with them:
Show support tickets in tray menu: master toggle for the entry, with a Context menu label.
Target department: the department the tickets are filed into. Only enabled departments are offered; without one the entry is shown but the window tells the user that requests are not available. A department that was deleted later leaves a warning here until another one is chosen.
Customer: Automatic files the ticket under the customer of the device's tenant: created when the tenant has none yet; with several, the one that already has a contact of this device, otherwise the oldest. A fixed customer overrides that.
Default priority, Let the user choose the priority, Offer "Critical": the priority of a new ticket, and whether the window shows the four urgency choices at all.
Categories: one per line; leaves the category field out when empty.
Type is required: the types offered are the active types of the target department.
E-mail address is required: on by default, so the department's auto reply and the technicians' public replies reach the user by mail as well.
Allow attachments, Allow screenshots: up to three files per request (PNG, JPG, GIF, WebP, PDF, TXT, LOG, 5 MB each). A screenshot covers every monitor and is scaled to 1920 pixels. Attachments from devices are stored in the database.
Show "My tickets": the list of the user's own tickets from this device with the public conversation of each. Off leaves only the form and the confirmation.
User may reply, User may mark a ticket as resolved: the reply box and the My problem is solved button in the ticket detail. A reply reopens a resolved or closed ticket like an e-mail reply would.
Notify the user about replies: a small notice on the device when a technician answers publicly or resolves the ticket, while the device is online; otherwise the tray icon picks the change up at its next check.
Window texts. Every label, button, status and message of the window (menu label, window title, the field labels, the four urgency texts, the confirmation with {0} for the ticket number, the not-available, saved-as-draft and rate-limited texts, the notice title, the five status words). Empty fields use the English defaults shown as placeholders; a language preset fills them in another language (§6.5.1).
The user sees only the tickets created from this device under their own Windows account, and never internal notes. The server enforces every switch above; a request that arrives while the department is missing or the section is off is refused. Requests from one device are rate limited (5 tickets per hour and 20 per day, 30 replies per hour, 20 uploads or 20 MB per hour). What the ticket looks like on the console side is described in Chapter 10.6.
Logo & Icon. A single upload widget accepting PNG, ICO, or JPG up to 256 KB. The uploaded image replaces the default tray icon.
About Interface. Branding for the About window that opens from the tray's About button:
Enable: master switch for the About window.
Window Title, Title, Description: free-text fields shown to the user.
Show Version, Show Copyright: toggles for the standard footer lines.
Close Button Title: text on the dismiss button.
Chat interface. Branding for the end-user support chat window that the tray opens when an operator starts a chat from the device's remote tools (see Chapter 3.5) or accepts a chat request of the user. This is not the AI Chat above:
Input Field Placeholder: placeholder text in the user input box.
Enable Settings: exposes a settings menu inside the chat window, with sub-toggles Allow Export Chat History, Allow Copy Chat History, and Show About.
Remote Screen Control. Text shown to the on-device user when a remote screen session is requested or active:
Request Title, Request Message, Accept Button Title, Decline Button Title: the approval dialog shown for attended sessions (see §6.4).
Stop Button Title, Support Agent Connected Message: shown while a session is active so the user can end it.
Audio Call. Texts of the incoming call window the tray icon shows when an operator calls the signed-in user (see Allow audio calls on the Agent tab and A.7.7). All fields are leave-blank-for-default, or filled from a language preset (§6.5.1):
Title, Message: the incoming call window; {operator} in the message is replaced by the operator's name.
Accept Button Title, Decline Button Title: the two answers of the incoming call window.
Hang Up Button Title: the button of the call window while the call is on.
Power Action Notice. Texts of the warning window the tray icon shows to signed-in users before an administrator restarts or shuts down the device from the Console. The message itself is entered when the action is sent; the policy sets the frame around it:
Window Title: title of the warning window.
Reboot text, Shutdown text: the line under the message, depending on the action.
Close Button Title: the button that closes the window; the action still runs when the countdown ends.
Buttons (custom). A managed table of custom tray-menu entries. Each row has Name, Description, Author, Date, Action, Action details. Use Add, Edit, Delete to maintain entries; each entry adds one item to the tray menu mapped to an action (script, URL, etc.).
Logos, icons, labels, and custom buttons are pushed to the agent at the next sync; they do not change mid-session for a user already logged in.
the notifications of Application Control (§6.7) and USB Device Control (§6.8)
Branding and content of your own are never touched by a preset: the tray icon title, the title and description of the About window, the title and subtitle of the chat window, the AI Chat terms text, the ticket categories and the custom buttons.
There are two ways to apply a preset, both shown only with policies_edit:
Per section. Each of these sections has a Text language menu next to its heading. It fills all texts of that section, including fields that are currently switched off. The menu is disabled only while every field of the section is disabled. Patch notifications have one menu per platform, at the top of its Notifications sub-tab; Application Control and USB Device Control have theirs next to Tray icon notifications.
Whole policy.End-user text language in the editor toolbar fills every section at once.
The menus list English first, then every other language whose language file translates all preset texts (see A.5.3), each shown with its name and code, for example German (de-DE).
What happens when you choose a language:
The texts are copied into the fields of the page. Empty fields are filled as well, so the policy does not rely on the built-in English defaults afterwards.
Nothing is stored yet. Review the texts, change any of them, and click Save; on a policy with signed definitions use Save and sign as after any other change (A.13).
If some texts were changed by hand (not empty and not equal to a preset text in any language), a dialog asks first. Replace all overwrites them with the preset, Keep my texts fills only the other fields, Cancel changes nothing.
A message names the number of texts set and the language.
Each section shows a small chip with the language of its texts: the language name, Custom when at least one text was changed by hand, or Mixed when the texts come from different languages.
A policy keeps its texts until you apply a preset and save. New policies start with the English texts.
The presets translate only the texts that are stored in the policy. Some texts on the device stay English in every language:
{time} in the patch pre-warning is always inserted as English words ("15 minutes"). The non-English presets therefore use {minutes}, which is only the number.
{actions} in the Application Control and USB Device Control messages is inserted in English (for example "Process terminated"), and so is {device_type}.
On Windows, the patch notification may add a line in English that counts the operating system updates.
A few fixed texts of the tray icon have no policy field and stay English. Examples: the countdown line of the remote screen control prompt, the status line of the remote control overlay, and the labels of the call window during an audio call.
The Windows tab groups three Windows-only feature areas. The largest is Microsoft Defender Antivirus; this section covers its two sub-tabs. Application Control and USB Device Control follow in 6.7 and 6.8.
At the top of the Configuration sub-tab sits the Manage Defender settings switch. When it is off, every field on the Configuration sub-tab is disabled. The Console still stores your configuration, but the agent does not apply any of it, runs none of the scan jobs and skips the hourly signature check. When it is on, the agent synchronises the settings below with Microsoft Defender on every sync interval. The switch covers the Configuration sub-tab only: Defender notifications have their own switch on the Notifications sub-tab (see 6.6.2) and work with or without Defender management.
The Configuration sub-tab is organised into four sections.
General Settings. Settings that do not fit the scanner-specific categories:
User Interaction: Show Windows Security Center icon, Show Windows Security Center tray icon. Control whether end users see these Windows Security Center icons.
Updates: Check signatures hourly, Allow metered updates. The first forces hourly signature polling; the second lets signature downloads run over connections the operating system classifies as metered.
Other: Delete quarantine older than 6 months. A retention switch for the Defender quarantine.
Scanner Settings. Behaviour for real-time and on-access scanning:
Direction dropdown: Inbound & Outbound, Inbound, or Outbound. Scopes which traffic direction the network-aware parts of the scanner examine.
File System: Hash computing, Block at first seen (not configurable), Scan archives, Scan emails. These toggles control the deep-scan behaviours most often tuned for performance.
Network: Scan network files, Filter incoming connections, Datagram processing. Network scanning options, most useful for servers.
Parser: per-protocol toggles for TLS, RDP, SSH, HTTP, DNS, and DNS over TCP. Enable or disable Defender's parsing of each protocol.
Exclusions. A managed list of paths and process patterns the scanner skips.
The table has columns Exclusion, Type, Description, Date. Actions on the toolbar:
Add opens the Add Exclusion dialog. Fields: Type (one of File, Directory, File Type (extension), or Process), the Exclusion value matching that type, and an optional Description.
Edit opens the Edit Exclusion dialog, pre-populated.
Delete removes the selected row.
Export exports the exclusion list.
Exclusion types in detail:
File: an exact file path.
Directory: a folder path; everything under it is excluded.
File Type (extension): a file extension, for example .bak.
Process: a running process image; files accessed by that process are excluded.
Scan Jobs. Scheduled on-demand scans.
The table columns: Status, Name, Date, Description, Schedule Type, Time, Monday through Sunday day toggles, Scan Mode, CPU Usage %, Scan on Battery, Network Drives, Removable Disks, Update Signatures.
Actions:
Add opens the Add Scan Job dialog. You set: Enabled, Name, Description, schedule type, day-of-week toggles, time, scan mode, CPU-usage cap, and the battery / network / removable toggles.
Edit opens the Edit Scan Job dialog, pre-populated.
Delete removes the selected row.
Export exports the scan-job list.
Each scan job targets a list of directories. Use the Add Directory and Edit Directory dialogs from inside the scan-job editor to maintain the directory list.
The Notifications sub-tab decides which Defender events the Console reports as notifications. Its first element is the Enable notifications switch. It works independently of the Manage Defender settings switch on the Configuration sub-tab: with notifications on and management off, the agent only reads the Defender event log and reports the selected events; it changes no Defender setting. When the switch is off, every toggle on this sub-tab is disabled and the agent reports none of these events. Below the switch are ten sections, nine Defender event categories and the NetLock channel selector:
Antivirus
Antispyware
Behaviour
Configuration
Platform
Quarantine
Real-time Protection
Scan
Signatures
NetLock: channel selector for the events above. The five toggles (E-mail, Microsoft Teams, Telegram, NTFY.SH, Webhook) decide which deployment-wide channels carry this policy's Defender notifications. The channels themselves (server addresses, recipients, tokens) are configured globally in Settings → Notifications (see A.8 Notifications deep dive).
Each Defender category contains a list of per-event toggles, for example Antivirus enabled, Antivirus disabled, Behaviour detected, An element has been deleted from quarantine.. Toggling an individual event controls whether that specific Defender event generates a notification through the Console's notification system.
The Quarantine section has three toggles: An element has been deleted from quarantine. (Defender event 1011), An element has been restored from quarantine. (1009) and The malware history has been deleted. (1013). The last one is off by default. Defender writes event 1013 whenever it purges its protection history, including its own automatic clean-up of history and quarantine (for example with Delete quarantine older than 6 months on the Configuration sub-tab), so leave it off unless you want to see every purge.
Note: Silencing a noisy event category here does not disable the underlying Defender behaviour on the endpoint. It only stops the Console from forwarding the event as a notification. Defender continues to act normally and log the event locally.
The Application Control sub-section of the Windows tab (on-screen heading Application Control (Whitelisting)) controls how a policy enforces application allowlisting on its devices. The rulesets with the actual allow rules are maintained in Chapter 8.6. This tab decides which ruleset to apply and how the agent reacts when an unknown process appears.
Top-level configuration:
Enabled: master switch for this policy.
Ruleset: single-select dropdown picking one ruleset (None is the default).
Auto-whitelist (agent automatically adds running processes to whitelist) with Auto-whitelist until date: during this window the agent records every running process into the whitelist; after the date passes, only the collected list is enforced.
Actions on unknown process. What the agent does when a process not matched by the ruleset is detected. Toggle any combination:
Terminate process
Suspend process
Delete binary
Backup binary
Dump process memory
Note:Terminate process and Suspend process complement each other: enable both so that a process which cannot be terminated is at least frozen. Delete binary, Backup binary and Dump process memory are meant for forensic follow-up, not for stopping the process.
Actions on parent process. The same five actions, applied to the parent of the offending process. Use them to respond to the program that started it, for example to terminate a launcher that spawned the unknown child.
Matching Filters. Which attributes of a binary are compared against the ruleset. Twelve toggles:
The selected attributes decide how precisely a running process has to match a rule: a process is allowed as soon as one selected attribute matches a rule of the ruleset. Selecting only attributes that change with every update, such as File Version, File Product Version or the hashes, is strict: an updated legitimate application no longer matches and is blocked until it is approved again. File Company, File Product or Certificate Owner are more tolerant and survive updates.
Special Filters.
Auto-allow applications with Microsoft in the copyright or product name: bypass the ruleset for any binary whose file copyright or product name contains Microsoft.
Other Settings.
Periodic check interval (minutes): how often the agent checks again (5–1440).
Tray icon notifications: show the on-device user a notification when something is blocked. When enabled, set Notification title and Notification message. The message supports the placeholders {process_name}, {process_path}, {actions}, and {count}; the agent inserts {actions} in English. Both texts can be filled from a language preset (§6.5.1).
Blocked launch attempts land on the Blocked Applications tab of the Application Control rulesets page in Collections, where an admin can approve them into a ruleset. To author rulesets, edit rules, or approve blocked entries, see Chapter 8.6.
The USB Device Control sub-section of the Windows tab (on-screen heading USB Device Control (Whitelisting)) controls how this policy enforces USB allowlisting on its devices. The whitelist itself is maintained in Chapter 8.7. Its entries are shared by all policies and scoped by device, tenant, location, group or global; this tab holds no whitelist entries.
Top-level configuration:
Enabled: master switch for this policy.
Learn connected devices on devices newly assigned to this policy: a device learns the devices connected to it once, either when it receives this policy for the first time or when it moves to this policy from another policy. Every device of a monitored class that is connected to it during its learning period is whitelisted for that device only (scope device, author Auto-Whitelist (Agent: <device name>)). Devices that are already on the policy are not affected and keep blocking unknown devices.
Learning period: how long a device learns. The choices are Devices connected when learning starts, 15 minutes, 1 hour, 4 hours (default), 1 day, 7 days and 14 days.
Learning new devices.
The learning period is kept per device and starts when the device receives the policy. Its end is the same moment on the server and on the agent, whatever the time zone of the device.
With Devices connected when learning starts, only the devices attached when the policy reaches the device are learned. Devices connected later are blocked and appear on the Blocked Devices tab, where they can be approved. Agents older than 3.3.0.11 learn for 15 minutes instead.
A connected device counts as learned only once the server has stored the whitelist entry (agent 3.3.0.11 or later; older agents allow a reported device at once). While the agent waits for that answer, the device stays usable; if the server cannot be reached, the agent keeps asking until the learning period ends. A device the server does not learn is handled like any other unknown device.
A device that returns to a policy it has already learned under does not learn again. Moving it to another policy with this option on starts a new learning period.
Switching the option off ends the learning periods the policy started. A period started from the device itself continues.
The USB Devices tab of a device shows its learning state and offers Re-learn connected devices and End learning now; several devices can re-learn at once from the Whitelist tab of Device Control. See Chapter 3.3 and Chapter 8.7.
Note: In block mode (Eject / disable device on), device control is only enforced on a device once at least one whitelist entry applies to it (device, tenant, location, group or global scope) or the device is in its learning period. With an empty rule set nothing is enforced, because every device would otherwise be blocked, including keyboard and mouse. Devices the agent disabled earlier are enabled again, right after a learning period ends or at the next policy change (agent 3.3.0.11 or later).
In log-only mode (Eject / disable device off), unknown devices are reported even without whitelist entries and none is disabled (agent 3.3.0.11 or later). The policy page and the whitelist page show this note; on the whitelist page it becomes a warning while the list is empty.
Actions on unknown device. What the agent does when a device that does not match an approved whitelist entry is plugged in or found by the periodic check:
Eject / disable device: the agent disables the device in Windows, the same way Device Manager does. The disabled state is stored with the device, so it survives re-plugging and restarts. A device that is already disabled is left alone and not reported again.
Log device event: the detection is written as an event and reported to the Blocked Devices tab.
With Eject / disable device off, the policy runs in log-only mode: unknown devices are reported and none is disabled. Each unknown device is reported once while it stays connected, and again after it is plugged in again or after the next policy change; the agent re-applying an unchanged policy does not report it again.
The Actions Taken value of the event and of the Blocked Devices row names the actual outcome:
Value
Meaning
disabled
The device was disabled and verified as stopped.
disabled_pending_reboot
The disabled state was written, but the device was in use (for example a drive held open in File Explorer) and could not be stopped. The agent dismounts the drive's volumes and retries once; if the device still cannot be stopped, it finishes disabling at the next restart and comes up disabled when re-plugged. The event names what held the device (veto type and name).
disable_failed
Windows refused the request or the device kept running. The error is in the event and in the agent's Error.txt; the agent tries again at the next check.
logged
The detection was recorded (Log device event).
The event details carry an Enforcement section with the result, the veto, the steps taken (for example dismounted volumes) and the Windows build.
Re-enabling. The agent remembers which devices it disabled and enables them again as soon as the policy no longer blocks them: when the device is approved into the whitelist or learned during a learning period, when its device type filter is turned off, when device control is disabled for the policy, or when no whitelist entry applies to the device any more. This happens at the next policy sync; re-plugging is not required. A device that was disabled while unplugged is enabled at the next periodic check after it is plugged in again. Each re-enable is reported as an info event (Device re-enabled). Devices disabled by the agent are also re-enabled when the agent is uninstalled.
Device Type Filters. Which classes of USB device this policy monitors. Each class has two toggles: the class itself, and Include Instance ID, which switches to strict matching (specific port / instance) instead of vendor / product matching.
Class
Notes
Mouse
Classic computer mice.
Keyboard
Classic keyboards.
HID Class
Unspecific input devices such as drawing pens; also higher-end mice and keyboards, for example gaming peripherals.
USB
Unspecific USB devices such as docking stations and dongles.
Disk Drive
Classic USB sticks and USB hard drives.
WPD (Portable Devices)
Smartphones, and also newer USB sticks and USB hard drives that present themselves as portable devices.
CD-ROM
Optical drives (CD, DVD, Blu-ray).
Media
Headsets, microphones and other audio devices.
Network Adapter
External network adapters, but also VPN adapters.
Xbox Composite
Xbox controllers and compatible gamepads.
Caution with network adapters: a VPN adapter that is not whitelisted is disabled like any other device. The VPN connection then stops working until the adapter is whitelisted and the agent enables it again; some VPN clients need a repair or reinstall afterwards. Whitelist the VPN adapters of your VPN software before enabling the Network Adapter filter.
Other Settings.
Periodic check interval (minutes): the agent reacts to newly connected devices in real time; the periodic check is a fallback that re-scans all connected devices at this interval (1–1440).
Tray icon notifications: show the on-device user a notification when a device is blocked. When enabled, set Notification title and Notification message. The message supports the placeholders {device_name}, {device_type}, {actions}, and {count}; the agent inserts {device_type} and {actions} in English. Both texts can be filled from a language preset (§6.5.1).
Blocked devices land on the Blocked Devices tab in Collections, where an admin can approve them at one of five whitelist scope levels (device, tenant, location, group, or global). See Chapter 8.7 for the scope model and approval flow.
The Linux tab covers UFW, the Uncomplicated Firewall.
The UFW section has two master toggles, a default-policy block, and two separate rule tables.
Master toggles:
Enabled: enables UFW management by this policy.
UFW active on device: sets UFW's own active/inactive state on devices under this policy.
Default Policies:
Default incoming: Deny, Allow, or Reject.
Default outgoing: Allow, Deny, or Reject.
Simple Rules. Inline table for common port-based rules:
Column
What it holds
Action
Allow / Deny / Reject
Port
A single port, a range, or a comma-separated list
Protocol
TCP / UDP / Any
Comment
Free text
An Add Rule button above the table creates a new row. Rows are edited inline, without a separate dialog.
Advanced Rules. Inline table for rules that need source / destination specifics:
Column
What it holds
Action
Allow / Deny / Reject
Direction
In / Out
Protocol
TCP / UDP / Any
Source IP
for example 10.0.0.0/8
Source Port
A single port
Dest IP
Destination address or any
Dest Port
A single port
Comment
Free text
Same Add Rule and inline-editing pattern as Simple Rules.
Enforcement model. On every sync cycle the agent rebuilds UFW from the rules defined here and removes any existing rule that is not in this policy. The agent also monitors UFW for external changes and re-applies the policy rules on the next check (tamper protection). Two outbound safety rules for NetLock RMM communication and remote-control endpoints are always injected automatically, so a misconfigured ruleset cannot lock the agent out.
Caution: Enabling UFW with Default incoming = Deny and no matching simple rule will block every inbound connection except the agent's own safety paths. Build the ruleset first, then switch UFW active on device on.
Note: UFW must be installed on the target device (apt install ufw). On devices without UFW the agent does not apply these settings.
Settings here have no effect on Windows or macOS devices.
The Sensors tab attaches sensors from the Sensors library to the policy. Server sensors (category Server) are evaluated by the server and are not offered here. Sensor categories, severity levels, notification and action thresholds and action scripts are documented in Chapter 8.3.
Within this tab you pick from sensors already defined in Collections and toggle them on for the policy. Devices assigned the policy run the selected sensors on their schedule, evaluate thresholds on the agent, and report readings back to the Console for dashboards, events, and action-script execution. Sensor-specific configuration (category, thresholds, action script) lives in the sensor definition itself, not here.
A device can run sensors from two places: the policy's Sensors tab and the automation rules that match the device and add sensors on top (see Chapter 5.6). Both sets are merged on the server; a sensor listed in both runs once. The device detail on /devices shows which sensors came from a rule.
The Jobs tab attaches jobs from the Jobs library to the policy. The twelve schedule types, hidden jobs and the script reference are documented in Chapter 8.2.
You pick jobs that should run on devices under this policy. Each job carries its own schedule from the job definition; the policy is the attachment point that decides which devices receive which jobs. Jobs flagged hidden do not appear in the Events view and are typically used to collect data for Custom Fields (see Chapter 8.4).
Automation rules can add further jobs to the devices they match, on top of the policy's Jobs tab (see Chapter 5.6); a job listed in both runs once.
The Patch Management tab configures how the devices of a policy install approved patches. It complements the global approval queue in Chapter 7: Chapter 7 decides which patches may be installed at all, this tab decides when and how these devices install the approved patches.
The tab has five sub-tabs: Global, Windows, Linux, macOS and Docker. Global holds cross-platform defaults. Each platform sub-tab configures the rollout of its platform and does not inherit from the others.
Windows, Linux and macOS share one set of sub-tabs; Docker has its own:
Platform
Sub-tabs
Windows
General, Approval & Filtering, Deployment Rings, Schedule, Reboot, Notifications, Retry
Linux
General, Approval & Filtering, Deployment Rings, Schedule, Reboot, Notifications, Retry
macOS
General, Approval & Filtering, Deployment Rings, Schedule, Reboot, Notifications, Retry
Docker
General, Behavior, Schedule, Registries
The common Windows / Linux / macOS sub-tabs configure:
General. Sets the patch management mode for this platform. The mode applies to every source of the platform, not only to the operating system's own updates:
Disabled: no scheduled patch run on this platform. The schedule installs nothing from any source (on Windows: Windows Update, Winget and Chocolatey) and holds nothing back either.
Informational: scheduled runs only report. Available updates of every source appear in the console; the schedule installs nothing.
Managed: scheduled runs install the sources ticked below, within the schedule, filters and approval of this policy.
Patch Now from the console installs in every mode: it is an explicit request and does not look at the mode. The policy editor shows a description of the selected mode under the selection.
Below the mode are the source toggles of the platform. They can be changed in Managed mode only. In the other modes they are greyed out and keep their saved values, so switching back to Managed shows the earlier selection. Windows has Install OS patches (Windows Update), Install application patches (Winget) and Install application patches (Chocolatey), Linux has Install OS packages (apt/dnf/yum), and macOS has its own OS-source toggles. Windows additionally has the Disable Windows built-in automatic updates (take control via NetLock RMM) switch and, under Install OS patches (Windows Update), the option Include updates for other Microsoft products (Microsoft Update); both are described below.
Disable Windows built-in automatic updates locks Windows Update down on the device, so updates install only through NetLock RMM:
Windows' own automatic updates are turned off (NoAutoUpdate).
The controls of the Windows Update settings page are removed (SetDisableUXWUAccess); Windows then shows "Some settings are managed by your organization".
The Windows Update icon in the notification area is hidden (TrayIconVisibility).
The lock also greys out the Windows settings Receive updates for other Microsoft products and Get me up to date on the device; use the Microsoft Update option below for the former. The switch also takes effect in Informational mode when it is ticked there; in Disabled mode it has no effect and is greyed out. The agent applies the settings at its patch management check every five minutes and records them as its own.
Turning the switch off, assigning a policy without patch management settings, or uninstalling the agent removes them again; see Uninstall an agent. If a domain group policy configures the same Windows Update values, turning the switch off or uninstalling removes those as well, until the next group policy refresh writes them again.
The switch is not tied to the mode: it is pre-selected when a policy is switched to Managed and can be turned off again. The policy editor warns about two combinations:
Windows Update locked while the policy installs no Windows updates (mode Informational, or Managed without Install OS patches (Windows Update)). The devices then receive no Windows updates at all until the mode is Managed with that option ticked or the lock is turned off.
Managed with Install OS patches (Windows Update) while the lock is off. Windows keeps installing updates on its own as well, so restarts can happen outside the maintenance window and without the restart behaviour of this policy.
To patch only third-party applications through NetLock RMM and leave Windows updates to Windows, set the mode to Managed, untick Install OS patches (Windows Update), leave the lock off and tick Winget and/or Chocolatey.
Include updates for other Microsoft products (Microsoft Update) (Windows, off by default) registers Microsoft Update with the Windows Update Agent on the device, the same as the Windows setting Receive updates for other Microsoft products. Updates for other Microsoft products (SQL Server, Exchange, Visual Studio, .NET Framework, Office and more) are then reported and installed like Windows updates, within the filters, approval and schedule of this policy. They appear with the source OS-Mandatory in Patch Management and count towards the compliance of the device, so the compliance figures of an existing fleet change once the option is turned on.
The option takes effect in Informational and Managed mode and requires agent 3.3.0.11; older agents ignore it. Devices whose Automatic Updates point at a WSUS server (UseWUServer) keep WSUS: the agent does not register Microsoft Update there and notes it in its patch management log. The agent records a registration it made itself and only removes that one: turning the option off, assigning a policy without patch management settings, or uninstalling the agent removes it, while a registration made by a user, a group policy or before the agent stays. With the lock on, the Windows settings page shows Receive updates for other Microsoft products greyed out and on once the registration is in place.
Approval & Filtering.
Approval Gate: Only install patches that have been approved in Patch Management. When on, only Approved patches install; Pending, Rejected, and Deferred are skipped. This links the policy to the approvals in Chapter 7.
Allowed Update Types (Windows): Security, Regular, Definition, Rollup, Service Pack, Feature, Driver, Other, all ticked in a new policy. Definition covers updates such as the Microsoft Defender antimalware platform and the Windows Security platform; the Defender security intelligence (signature) updates are never installed by patch management, whatever is ticked (see 7.4). Windows policies saved with version 3.3.0.10 have Definition unticked: tick it and save the policy if these updates should be installed. Linux and macOS expose a Preferred Update Source selector (Auto-detect / APT / DNF / YUM on Linux; equivalent on macOS) instead.
Allow upgrades to a new major version of macOS in scheduled runs (macOS, off by default): decides whether a scheduled run may install an upgrade such as macOS 26 to macOS 27. Off: the upgrade is held back with the reason Major upgrade not allowed by the policy, even when it is approved. On: the usual severity, type, approval and deployment-ring rules apply to it. Patch Now installs a major upgrade only when it is selected and the confirmation in the dialog is accepted; Patch All leaves it out. Needs agent 3.3.0.11; see macOS in Chapter 7.
Allow package removal (full upgrade) (Linux, apt only): lets apt remove packages that block an upgrade (a renamed library, a replaced package), the same as apt full-upgrade / dist-upgrade. Off by default: apt then keeps such packages back and the patch job lists them as Skipped together with the packages a full upgrade would remove. Proxmox VE hosts need this on. The option sits next to the Configuration file conflicts option and is shown when the package manager is apt or auto-detected; see Chapter 7.7.
Deployment Rings. Per-severity scheduling. For each of critical, high, medium, low, unspecified, informational, pick a Ring Type:
Immediate: no waiting time after the update's release. Immediate does not override the schedule: the allowed patch days, the maintenance window and the one-run-per-window rule still apply. Only Patch Now bypasses the schedule, the rings and the retry budget.
After N days: install N days after the patch becomes eligible (N from a paired numeric field).
Patch Tuesday + N days: install N days after the most recent second-Tuesday Microsoft release.
First weekend after Patch Tuesday.
Second weekend after Patch Tuesday.
Rings apply per severity within one policy, not to groups of devices.
Schedule.
Allowed patch days: seven day-of-week checkboxes, Monday to Friday by default. On an unticked day no scheduled run happens, not even as a catch-up run.
Maintenance window: From and To times (set them equal for a 24/7 window with no time restriction). The agent checks every five minutes; inside the window the run starts at the next check. There is one scheduled run per window occurrence: after a run the agent installs nothing more until the next window opens (once per day for a 24/7 window), whatever the outcome of that run was. The reason a run is waiting, and the next possible run, are shown in the Scheduled patching line of the device's detail view on /devices (agent 3.3.0.5 or later). The window decides when a run starts, not when it ends: on Windows a run that started inside the window begins no further update after the window has ended (or after 60 minutes, whichever is later), and an update that is already installing is finished; see Chapter 7.7 (agent 3.3.0.12 or later).
Catch up a missed maintenance window: on by default. With the checkbox on, the first check after the policy arrives on the device, or the first check after a missed maintenance window, starts the run right away, even outside the window, but only on an allowed patch day. With the checkbox off, a run starts inside the maintenance window only.
Smart Maintenance Window: Enable smart maintenance window (auto-detect ideal patch time). When on, optional sub-conditions: Require user idle + Idle duration (minutes) (15–480), Require AC power (for laptops), No active RDP sessions.
Reboot.Reboot behavior after patch installation with three values:
Automatic reboot: reboot without prompting. On Windows, a scheduled run that started inside its maintenance window and ends more than 60 minutes after it does not restart the device at that moment. The restart then happens in the next maintenance window of the policy, which is the next allowed patch day (agent 3.3.0.12 or later); see Chapter 7.7.
Ask user (with maximum deferral): prompt the user; Maximum deferral (hours) (1–168) caps the delay. If nobody is signed in decides what a device does when nobody is signed in and therefore nobody can answer the prompt: Do not reboot (wait for a user) (the default), Reboot in the maintenance window or Reboot immediately. Needs agent 3.3.0.4 or later.
With agent 3.3.0.5 or later two more fields control how often the user is asked:
Re-prompt interval (minutes) (5–1440, default 30): a user who chose Later or did not answer is asked again after this time. One last reminder comes 15 minutes before the maximum deferral ends (or one interval before, if the interval is shorter).
Unanswered prompt counts as deferred after (minutes) (1–240, at most the re-prompt interval, default 10): closing the restart window counts as Later right away; a minimized or ignored window counts as Later after this time.
Both fields, like Maximum deferral (hours), are disabled unless Ask user is selected.
The maximum deferral counts from the first prompt that reached somebody (a connected tray icon, or on Windows a signed-in user), not from the first Later. A prompt that reached nobody waits until a tray icon connects and starts the clock then. When the maximum deferral ends, the device restarts at that moment, whether or not a reminder was due. The prompt, the deferrals and the deadline survive a restart of the agent service; a restart of the device, or a policy that no longer uses Ask user, ends the prompt. Older agents keep their built-in reminder steps and ignore both fields.
Do not reboot: leave reboot to the user / next maintenance cycle.
The sub-tab also has Install all pending patches before rebooting. Chapter 7 has no reboot controls; what the user sees when a restart is due is configured on the Notifications sub-tab.
An outstanding restart is a gate for the Windows updates of the next run. While a restart from an earlier update run is outstanding, a scheduled run on Windows installs no Windows updates; the Winget and Chocolatey updates are still installed in such a run when the policy enables them. Patch Now still installs Windows updates too.
The device's detail view shows Last patch run: … – restart pending, Windows updates held back and its tooltip names how many application updates the run installed, failed or held back; the Restart pending since … banner names this policy's restart behaviour, and the blocked run is recorded once as an event of type Patch management on the device.
With Do not reboot, or with Ask user on a device where nobody is signed in and If nobody is signed in left at its default, the restart has to happen another way (a user or the Console restarts the device, or you change the option), and scheduled runs keep installing no Windows updates until then. The policy editor repeats this as a note under the restart behaviour on the Windows Reboot sub-tab only, because only Windows has the restart gate.
The gate is checked when the run starts and holds back only the Windows stage of that run. A restart that the Windows stage of the run itself leaves outstanding does not stop the Winget and Chocolatey stages of the same run either: the application updates are installed after the Windows updates, and the restart then follows this policy's restart behaviour. Installing application updates while a restart is outstanding requires agent 3.3.0.11 or later.
Notifications. End-user tray notifications during patch operations. They are separate from the deployment-wide notification channels in A.8 Notifications deep dive. The installation, restart and pre-warning notifications each have their own switch, so the installing popup can be turned off while the restart prompt stays on (or the other way round):
Installation notification.Notify user when updates are being installed with Installing — title / Installing — message, Show update category to end user, Show individual update names and, on Windows, per-category suppression checkboxes (Security, Regular, Definition, Rollup, Feature, Driver, Service Pack, Other, Application (Winget)).
Restart notification.Notify user via Tray Icon when reboot is required plus the texts of the restart window: Restart required — title, Reboot required — message, Button — restart now, Button — later and Automatic restart — message. The prompt (title, message, both buttons) is what the user answers under Ask user. The automatic-restart message replaces the prompt message when the device restarts on its own: after an automatic reboot, a forced reboot from the console, or when the maximum deferral is reached (the restart is forced exactly when the maximum deferral ends). The window then shows a single OK button, and the restart follows 60 seconds later. While the Reboot sub-tab is set to Ask user, the switch is shown on and locked: the prompt is how the user accepts or defers the restart, so it is always sent in that mode. In the other cases the switch decides whether the notice appears.
Pre-warning.Show pre-warning notification before updates start, minutes before start, Pre-warning — title and the message template. Placeholders: {time} is the remaining time as text, always in English (for example "15 minutes"), {minutes} the number of minutes alone. For a message in another language use {minutes}.
Update needs the user (macOS). Title, message and button of the window that asks the signed-in user to install macOS updates the agent does not install itself (on Macs with Apple Silicon, see macOS in Chapter 7). The window lists the updates and its button opens System Settings > General > Software Update. It is not repeated within a day for the same updates and has no switch of its own. Needs agent and tray icon 3.3.0.11.
All of these texts are free text per policy and per platform, with English defaults. The Text language menu of the sub-tab fills them from a language preset in any language of the Console (§6.5.1); the texts stay editable afterwards. The title, buttons, automatic-restart message and pre-warning title need agent 3.3.0.4 or later; an older agent keeps its built-in English wording for them and shows the policy message only.
Retry.Retry count for failed patches (0–10) and Retry delay (minutes) (10–1440).
The Docker sub-tab is structured differently. Docker patch management is supported on Linux hosts running Docker Engine only; Windows and macOS, including Docker Desktop and Docker in WSL, are not supported. Agents on those systems skip the Docker checks and do not call the Docker CLI.
General.Docker Mode: Disabled, Informational (inventory and update check only) or Managed (pull updated images and optionally recreate containers).
Behavior.
Auto-pull updated images: pull a newer image when the registry digest differs from the local one.
Auto-recreate containers after pull: replace running containers of that image with a new container on the pulled image. The new container is started with its name and image only, so the agent recreates only containers that carry no further configuration. A container is skipped if it has published ports, volumes or bind mounts, environment variables beyond those of the image, a custom command or entrypoint, a restart policy, a network other than the default bridge, extra labels, privileged mode, devices or resource limits. Every such container is left untouched and logged as skipped; the image stays pulled and is used the next time the container is recreated by its owner (for example with docker compose up -d).
Skip compose-managed containers: never recreate containers that belong to a Docker Compose project.
Only update approved image digests: the approval gate; only images approved in Patch Management are pulled and recreated.
Schedule.Scan interval (hours), allowed patch days and a maintenance window. The day and window checks apply in Managed mode only.
Registries.Allowed registries: a comma-separated allow-list of image repository prefixes (for example ghcr.io/myorg/, registry.internal.lan/). When set, only images whose repository starts with one of the prefixes are pulled; leave it empty to allow any registry. The prefix is compared with the repository as docker image ls shows it, where Docker Hub images appear without docker.io/ (for example nginx). This field holds no registry credentials: the agent pulls with the credentials Docker Engine already has on the host (docker login).
Note: The per-platform structure lets you run a tight maintenance window on Windows servers and a looser one on Linux workstations from the same policy. Platforms do not inherit from each other: Linux patching uses the Linux sub-tabs, whatever Windows is configured to do.
Every sub-tab is self-contained; you do not have to fill in all of them before a policy is usable. A minimal patch configuration is often just General (mode = Managed, source toggles) plus Schedule (a maintenance window).
The App Hub tab curates which apps from the global App Hub catalogue are visible in the tray icon for devices under this policy.
Each app is listed with its source: Script, File from the file server, or the package manager by name (Winget, Chocolatey, Flatpak). For each app in the catalogue you can toggle:
Whether the app appears in the tray window for devices under this policy.
Whether the agent auto-updates the app when a new version is available in the catalogue.
This tab decides what the end user sees in the tray; it does not deploy apps. Deployment happens through Software Deployment in Chapter 8.8, which is independent of any policy.
The App Hub catalogue itself (manual app entries, catalogue browsers for Winget / Flathub / Chocolatey, Refresh catalogs sync) lives in Chapter 8.5.
A policy is not applied to a device, group or tenant directly. Automations assign policies to devices. To put this policy on a device:
Identify the facts of the device that should select this policy: its tenant, location, group or the device itself, its platform, an attribute such as the name, a service or application of its inventory, or a custom field value.
Create an automation whose conditions match those facts and whose policy is this policy.
Check that no other matching rule has a lower priority number: the rule with the lowest number wins, and the dialog proposes the number from the rule's most specific organisation condition (see Chapter 5.3.1). Change the number to reorder.
The Policies, Groups and Devices pages have no action that sets a policy. Chapter 5 describes automations in detail, with a worked example.
The only exception is the default policy: Set as default policy on the Manage Policies page marks the policy that reaches every device that no automation assigns a policy to (see §6.2). It is a fallback below every automation, not a way to override one.
Tip: The Policy column of /devices shows the policy of each device; a globe icon next to the name marks a policy that comes from the default policy.
policies_enabled: master flag. A user without this flag does not see the Policies navigation entry and cannot reach /policies or /policy_settings.
policies_add: create a new policy from the Manage Policies page.
policies_manage: click Manage on a policy row to open Policy Settings for editing.
policies_edit: save changes in the Policy Settings editor.
policies_delete: delete a policy.
Permissions for features that live inside a policy (Antivirus, Application Control, Device Control, Patch Management, Sensors, Jobs, App Hub) are covered in their own Collections sections in Chapter 8 and in Chapter 14.
The Patch Management page is the Console's view of the fleet-wide patching pipeline. It answers two questions: which patches are approved for installation anywhere in the fleet, and how compliant the fleet is against the patches that exist. When the devices of a policy install updates, and how they restart, is configured in the policy itself.
Patch Management in NetLock RMM is split across two places:
The Patch Management page at /patch-management, the subject of this chapter, is global. It shows every patch the system knows about, holds the approval state for each, tracks compliance against SLA thresholds and configures deployment-wide patch defaults.
The Policy Settings → Patch Management tab, documented in Chapter 6.12, applies per policy. It decides when and how the devices assigned to a given policy install the patches that have been approved on this page. That is where the per-platform rollout rules, deployment rings, maintenance windows, reboot behaviour, notifications, and retry configuration live.
Rollout scheduling and reboot controls are not on this page.
Patch Management is a single page with these tabs across the top:
Tab
Purpose
Overview
Fleet health rated by security relevance and SLA state, the compliance figures, the tiles and the top tables. Every figure follows the compliance scope of the Settings tab.
Devices Not Up To Date
Every device with listed updates still open, with the Last scheduled run column; updates outside the compliance scope are marked Not scored.
Update Approval
The main queue — every known patch with its approval state, compliance counts, and SLA status.
Update History
A history view of update installs, successes, and failures per patch and device.
Patch history
Patch Now and uninstall jobs together with the scheduled patch runs of the agents. See 7.5.
Auto-Approval
Rules that approve patches automatically. Shown only to accounts with the permission patch_auto_approval_manage.
Settings
SLA thresholds, the compliance scope (sources, update types, severities, approval state, grace period), history cleanup. Saving needs the permission described under Permissions.
On the Overview and Devices Not Up To Date tabs a tenant selector appears when the account may read more than one tenant. It narrows every figure of the two tabs, including the dialogs opened from them, to one tenant. The selection is a view only: the compliance scope of the Settings tab applies to every tenant, the other tabs are not affected, and the selection is not kept across page loads.
The page opens on the Overview tab as soon as the permissions and the settings are known. Every other tab loads its data when it is first opened and keeps it while the page stays open. The Update Approval, Update History and Patch history tables are paged: the rows per page are chosen at the bottom of the table (10 to 500), the counter above the table shows how many entries match the filters and reads more than 10000 entries beyond that cap, and the search box needs at least two characters before it filters. Sorting by the Status or Platform column of the approval queue and by the Action column of the history follows the order of the values in the matching filter list, not the alphabet.
Most actions happen inline through row actions and toolbar buttons. The entries of the Patch history tab open in a details dialog.
Every patch in the Update Approval tab is in one of four states:
Pending: newly discovered; no admin decision yet.
Approved: eligible for installation anywhere the policy-level rules allow it.
Rejected: explicitly blocked fleet-wide; no device will install it.
Deferred: postponed. The default defer period is 7 days; after the timer expires the patch returns to Pending.
From the table toolbar you can act on one or many selected rows. The checkbox in the table header selects the rows of the current page; unticking it clears the selection on every page. Rows stay selected while you page through the table, and the toolbar shows how many rows are selected. Every action clears the selection once it has run. Group by type groups the rows of the current page by update type, with the page ordered by type first. Available actions:
Approve: set state to Approved.
Reject: set state to Rejected. A confirmation is shown ("Are you sure?") because rejection is a fleet-wide block.
Defer: postpone for N days (default 7).
Reset to Pending: revert from any other state.
Every state change triggers an immediate re-sync of every device. Devices do not wait for their next scheduled poll; the updated approval set reaches every agent as soon as the server can deliver it.
Important: Approval on this page is global: it applies to every device, group, location and tenant at once. Narrowing a patch's rollout to a subset of the fleet is done with the Approval & Filtering and Deployment Rings sub-tabs inside a policy (see Chapter 6.12).
Every update the console knows is either listed, scored or neither:
An update is listed when its approval state qualifies (see below) and it is not a Defender security intelligence update. Listed updates appear in the Devices Not Up To Date tab, in the device dialogs, in the Devices missing OS patches / software updates tiles and in the Updates tab of a device.
An update is scored when it is listed and lies inside the compliance scope configured on the Settings tab: its source, its update type and its severity bucket are selected, and its grace period has passed. Only scored updates count toward the compliance percentage, the fleet and device health ratings, the SLA figures, the donuts, the top tables, the dashboard widgets and the critical tile.
Defender security intelligence updates (the signature updates of Microsoft Defender Antivirus, KB2267602, and of the older Microsoft Endpoint Protection, Microsoft Security Essentials and Windows Defender products) are never reported, listed, scored or installed. Windows republishes them several times a day and Defender keeps them current through its own updater; monitor their state with the sensor Microsoft Defender Antivirus status. Rejected updates, updates whose deferral is still running and updates blocked by the automatic rollback are never scored.
The update type of a Windows update is Microsoft's own classification (Security Updates, Critical Updates, Updates, Definition Updates, Update Rollups, Service Packs, Feature Packs, Upgrades, Drivers, Tools). It does not depend on the display language of the device (agent 3.3.0.11 or later). Updates of the Definition type other than the security intelligence updates, for example the Microsoft Defender antimalware platform (KB4052623) or the Windows Security platform (KB5007651), are managed like any other update: they are listed, scored when the compliance scope includes Definition, and installed when the policy allows the Definition type.
A listed update that is not scored carries the chip Not scored wherever it is shown, and the SLA column of the Update Approval tab reads Not scored for it. A device whose open updates all lie outside the scope is up to date for every compliance figure; the Devices Not Up To Date tab still lists it, marked with the chip, so the backlog does not disappear.
The default scope scores the operating system channels (OS-Mandatory, Apt, Dnf, Yum, MacOS), every update type except Driver, every severity and approved updates only, without a grace period. Winget and Chocolatey updates are listed but not scored until you add the two sources to the scope.
The approval state of the scope is either Approved updates only (the default) or Approved and pending updates. The second option scores pending updates and deferred updates whose deferral has expired as well, which shows the real exposure of a fleet that is not approved by hand.
The grace period (0 to 60 days) delays scoring: an update is scored only once it has been in the catalog for that many days, counted from First seen. It keeps Patch Tuesday from colouring the fleet red for the day or two before the scheduled runs have installed the new updates. The grace period has to be shorter than the SLA deadline for Critical, so a critical update can never be overdue before it is scored; the Settings tab refuses to save otherwise.
An update is security-relevant when its update type is Security, or its severity is Critical, High or Important, or its catalog row carries at least one CVE. This definition is fixed and not part of the configurable scope. It drives the headline figure and the health ratings below. A monthly Malicious Software Removal Tool rollup without CVEs or a driver update is not security-relevant.
The headline figure of the Overview is the security compliance: the percentage of reporting devices without an open security-relevant scored update. A device reports once the server has received an update inventory of it in which every operating system source answered (Windows Update, apt, dnf, yum or softwareupdate); only authorized devices are counted.
Linux and macOS report pending updates only, so a fully patched Linux or macOS device reports without any catalog row and counts as fully patched. An inventory in which the operating system source failed changes nothing: a device that reported before keeps reporting with its last known updates, a new device stays not reporting. A Linux device with a package manager NetLock does not patch (zypper, pacman) never reports.
The second line, X of Y devices fully patched, counts the devices without any open scored update. The colour of the headline follows the tier thresholds: 90 % and above green, 75 % and above amber, below red.
The fleet health rating takes the first matching row:
Tier
Condition
No data
No device reports.
Critical
A scored critical update is overdue, or the security compliance is below 50 %.
Needs attention
A scored critical update is open within its SLA, a security-relevant update is overdue, or the security compliance is below 75 %.
Fair
A security-relevant update is open within its SLA, an installation failed in the last 30 days (updates in the catalog scope only), or any scored update is overdue.
Good
Only updates that are not security-relevant are open, all within their SLA.
Excellent
Nothing scored is open.
The reason line under the rating names the security compliance, the fully patched count and every figure above zero.
The smiley in the Patch status column of /devices rates one device on the same scale:
A device that never reported its update state is grey.
A device without an open scored update is Up to date, whatever its last job did. The tooltip names the listed updates that are not scored and the updates not approved yet.
Up to two open scored updates are Good, up to five Fair, more need attention. A backlog without a security-relevant update stops at Fair.
An overdue critical update is Critical; an open critical update within its SLA or an overdue security-relevant update is at least Needs attention.
A Patch Now job that finished in the last 14 days lowers the rating when it failed, but only for failed items whose update lies in the catalog scope.
An outstanding restart that pauses the scheduled runs with operating system updates open is at least Fair.
Each row in the Update Approval tab carries three compliance indicators in addition to its approval state:
Installed: count of devices that already have the patch installed.
Devices pending: count of devices where the patch is available but not yet installed.
SLA: one of Compliant, At Risk, Overdue or Not scored.
SLA status is computed per row based on the patch's severity and how long it has been known. The threshold for each severity is the number of days after first discovery within which a device is expected to have installed the patch:
Severity
Default days
Field under SLA Compliance Deadlines
Critical
7
Critical (days)
High, Important
15
High (days)
Medium, Moderate
30
Moderate (days)
Other / Low / Unspecified
60
Other (days)
SLA state transitions:
Compliant: within SLA. The deadline has not passed.
At Risk: three days or fewer to the deadline.
Overdue: the deadline has passed.
Not scored: the compliance scope does not score the update, so no SLA applies to it.
Grace period and SLA both count from First seen: the grace period decides when an update starts to count, the SLA deadline when it is overdue.
Widgets that make a compliance or health statement follow the scope: Patch compliance, Patch SLA status, Most missing updates and Missing updates by platform. Widgets that break down the inventory show every approved update regardless of the scope: Pending approved updates by severity, Available updates by type and Update approval status; the history and job widgets do not depend on the scope. The description of each widget says which rule it follows.
The Patch history tab lists what was installed or removed on the devices, and why a run installed nothing. It shows two kinds of entries in one list, newest first:
Jobs.Patch Now and uninstall jobs that an operator started. The Action column reads Install or Uninstall, and Triggered by names the operator.
Scheduled runs. The runs an agent started on its own from the patch schedule of its policy. The Action column reads Scheduled run, and Triggered by reads Schedule. Scheduled runs are reported by agents 3.3.0.5 and newer. Runs of older agents appear only as the Last patch run line on the device.
The same list exists for a single device as the Patch history tab next to Updates in the device's detail view on /devices.
The columns are Device, Tenant, Location, Action, Status, Triggered by, Created, Finished, Items and Actions. For a job, Items shows how many updates were installed (removed) and failed, an orange count of skipped updates when there are any, and the total. For a scheduled run, Created is the start of the run and Items shows how many updates were installed, failed and held back. A skipped run has no items.
The status of a scheduled run follows its result:
Status
Meaning
Completed
The run installed updates, or found updates and none of them failed.
Partially completed
Some updates were installed and some failed.
Failed
Updates failed and none was installed.
Nothing pending
The run found nothing to install.
Waiting for restart
An outstanding restart from an earlier run blocked the Windows updates; from agent 3.3.0.11 Winget and Chocolatey updates are still installed in such a run and show their own decision.
Skipped
No run started. The reason stands next to the chip, for example Insufficient disk space or Patch management is disabled in the policy of this device. A run that held every update back (filters, approval, deferral, updates that need a user at the device) and installed nothing is Skipped as well; the number of held-back updates stands next to the chip.
The toolbar filters the list:
Status accepts several statuses at once. With none selected every entry is listed, including Skipped. Select every other status to leave the skipped entries out.
Trigger switches between All entries, Patch Now & uninstall and Scheduled runs.
Action narrows the list to Install or Uninstall. Scheduled runs count as installations: Install lists them together with the Patch Now jobs, Uninstall hides them.
Period loads Last 7 days, Last 30 days, Last 90 days or All time. The default is Last 30 days.
The search box matches the stored values, not the translated text shown in the table: the device, tenant and location names, who started a job, the action word of a job (install, uninstall), the note of a run and the stored outcome keyword of a run (for example nothing_pending or disk_space). It needs at least two characters. Statuses are filtered with the Status select, not with the search box.
The counter above the list shows how many entries of both kinds match the filters, at most 10,000.
Double-click an entry or use View full details in the Actions column to open its details. A job opens Patch Job Details (see Details of a job). A scheduled run opens Scheduled patch run, which shows:
The device, tenant and location.
Started on the clock of the instance, and underneath Device time: … on the device's own clock. Finished carries the duration of the run.
Maintenance window: Inside the maintenance window (…) or Catch-up of a missed maintenance window (…), followed by the window of the policy, or no time restriction when From equals To.
The status, the agent version, the note of the run and the counts of installed, failed and held-back updates, with Reboot required when the run left a restart outstanding.
A notice when Winget and Chocolatey updates were not checked because Windows updates wait for a restart (agents before 3.3.0.11 skip the application stages of a run whose Windows stage leaves a restart outstanding; from 3.3.0.11 the application updates are installed in the same run), and when the agent reported only part of the updates of a very large run.
One row per update with Source, Name, Status, Reason and Details. The chips above the table filter the rows by All, Failed, Installed and Held back.
The status of an update is Installed, Installed, restart pending, Failed, Held back (held back for one of the reasons below) or Skipped (nothing to do). Details carries the error text, for Windows updates the error code Windows Update returned, and for Linux the package manager's message. The reason is one of:
Reason
Meaning
Installed / Failed / Skipped
The result of the installation.
Installed, waiting for restart
Windows installed the update; it takes effect after the next restart.
Blocked by severity filter
The severity filter of the policy excludes the update.
Blocked by update type filter
The update type filter of the policy excludes the update.
Not approved
The update is not approved for this device.
Deployment ring until …
The deployment ring of the device holds the update back until that time.
Retry after …
The update failed before and waits for the retry delay of the policy.
Needs user input
The update cannot install without someone at the device. On macOS: a macOS update on a Mac with Apple Silicon, or an update for which softwareupdate asked for a password; see macOS.
Major upgrade not allowed by the policy
macOS: an upgrade to a new major version (for example macOS 26 to 27) that the policy does not allow in scheduled runs, or that Patch All left out.
Deferred to a later run
The policy installs one update per run; this one follows in a later run.
Framework package, updated with its app
A Winget framework package that is updated together with the app that uses it.
No upgrade available
Winget had nothing to install for the package.
Already up to date
Chocolatey found the package current.
Package manager query failed in the last run
Winget or Chocolatey could not be queried when the run started, so the run could not decide about the updates of that source; the note of the run names the failed query. Shown on the device's Updates tab, not on the items of a run.
Replaced by another package
Linux: the upgrade replaced the package with another one.
Kept back by the package manager
Linux: apt keeps the package back, usually because the upgrade would remove another package.
On hold in the package manager
Linux: the package is on hold (apt-mark hold).
Dependencies cannot be resolved
Linux: the package manager cannot resolve the dependencies of the update.
With agent 3.3.0.11 or later, the Last run chip on the device's Updates tab also shows the decision of the last scheduled run for Winget and Chocolatey updates, in the same way as for Windows updates: Installed, Failed, Retry after …, Not approved, Deferred to a later run, No upgrade available, Package manager query failed in the last run or Not offered in last run. A Retry after … reason names the time of the next allowed attempt. An older agent reports no decision for these rows, so their chip stays empty.
Patch Job Details shows the device, the action, the status, who started the job, when it was created, started and finished, the note of the job, and one row per update with Name, KB ID, Source, Status and Details.
Above the rows, Items counts the updates: Installed (on an uninstall job: removed), Failed, Skipped and the total. When some installed updates still wait for a restart, an extra chip reads of which restart pending: n. The counts of a finished job are taken from its rows, so the header, the list and the rows always agree.
The status of an update is one of:
Status
Meaning
Pending
The job has not reached the update yet.
Installing / Removing
The agent is working on the update.
Installed / Removed
The update was installed (on an uninstall job: removed).
Installed, restart pending
Windows Update installed the update; it takes effect after the next restart of the device. It counts as installed. The row keeps this status after the restart, because it records what the job did; the device's Updates tab shows the update as Installed once the device has restarted and sent its next inventory. Windows updates of Patch Now jobs get this status from agent 3.3.0.11, and so do macOS updates that softwareupdate prepared for the restart (see macOS). Most cumulative and driver updates need a restart, so this status is common.
Failed
The update failed; Details carries the error.
Skipped
Nothing was done for the update. Details names the reason, for example that the update is no longer offered. Skipped with the detail not processed by agent means that no result for this update reached the server before the job ended.
Cannot be removed
Windows does not allow removing the update.
The agent keeps the results of a job on the device until the server has received them. When the agent or the device restarts during a job, or before the completion report reached the server, the agent reports the job after the restart with the results it had reached: with its decided outcome, or as Partially installed (some updates installed) or Failed with the note The agent restarted while this job was running. Updates it had not finished read Skipped with the detail not processed by agent.
The agent checks every five minutes whether a scheduled run may start. Not every check creates an entry:
A run that reached the installation always creates one entry, including runs with the result Nothing pending or Waiting for restart.
Insufficient disk space and informational mode create a Skipped entry at most once per day. Neither uses up the maintenance window.
Patch management disabled in the policy, no patch settings on the device yet and an incomplete maintenance window create a Skipped entry when the state changes, not at every check.
Waiting for an allowed patch day, waiting for the maintenance window and already ran in the current window never create an entry. The device's Scheduled patching line in the detail view shows these states with the next possible run.
A link to /patch-management?run=<id> opens the details of a scheduled run, and /patch-management?job=<id> the details of a job; both open the Patch history tab. /patch-management?tab=jobs opens the tab, and &status=Skipped or another status preselects the status filter. An entry outside the selected period still opens; the tenant scope of the account applies.
Scheduled runs are deleted after 90 days by default. The retention is set under Scheduled Patch Run History Cleanup on the Settings tab, separately from the update history. Jobs are not affected by it.
The Settings tab holds the configuration of the page. These settings are deployment-wide: they affect the whole Patch Management page, not a particular policy.
Setting
Default
Meaning
SLA Compliance Deadlines: Critical (days)
7
SLA threshold for Critical-severity patches.
SLA Compliance Deadlines: High (days)
15
SLA threshold for High-severity patches.
SLA Compliance Deadlines: Moderate (days)
30
SLA threshold for Moderate-severity patches.
SLA Compliance Deadlines: Other (days)
60
SLA threshold for remaining severities.
Compliance scope: Sources
OS channels on, Winget and Chocolatey off
Which update sources are scored: Windows Update, Apt, Dnf, Yum, macOS and the package managers Winget and Chocolatey.
Compliance scope: Update types
all except Driver
Which update types are scored, as the agents classify them. Defender security intelligence updates are never scored, whatever is selected.
Compliance scope: Severities
all
Which severity buckets are scored: Critical, High (High, Important, RequiresRestart), Medium (Medium, Moderate, Recommended), Low (Low, Optional), Unspecified (Unspecified, Informational, None). Winget, Chocolatey and driver updates carry no severity and fall under Unspecified.
Compliance scope: Approval
Approved updates only
Whether pending updates (and deferred updates whose deferral has expired) are scored as well.
Compliance scope: Grace period (days)
0
Days after First seen before an update is scored; has to be shorter than the Critical SLA days.
Update History Cleanup (Auto-cleanup enabled, Keep history (days))
on, 90 days
Deletes update history entries once they are older than the number of days set.
Scheduled Patch Run History Cleanup
on, 90 days
Deletes scheduled patch runs of the Patch history tab and their per-update results once they are older than the number of days set. Patch Now and uninstall jobs are not affected.
Changes apply once saved: the overview, the Devices Not Up To Date tab, the dialogs, the Patch status column of the devices list and the dashboard widgets read the saved values within a few seconds. The Save Settings button of the Settings tab and the one of the Auto-Approval tab save the same settings; both need the permission described under Permissions. Without it the fields are read-only and a hint names the required permission.
The Update Approval tab filters by platform and by source. The platform dropdown supports:
Windows
Linux
MacOS
Docker
The source dropdown supports:
Source
Platform
Notes
OS-Mandatory
Windows, macOS
Native OS-provided updates.
Winget
Windows
Windows Package Manager updates.
Chocolatey
Windows
Chocolatey package updates.
Apt
Linux
Debian / Ubuntu package updates, and derivatives such as Proxmox VE.
Dnf
Linux
Fedora / modern RHEL package updates.
Yum
Linux
Older RHEL / CentOS package updates.
Docker
Docker
Container image updates on Linux hosts running Docker Engine.
MacOS
macOS
Native macOS updates.
Approval is per patch regardless of source. An Approved patch from Winget installs under the same rules as an Approved patch from OS-Mandatory. The per-policy Approval & Filtering sub-tab decides which sources the devices of a particular policy accept.
On Apt systems, a package update can ask what to do with a configuration file that was modified on the device. The agent answers this automatically according to the policy's Configuration file conflicts option (Linux tab, Approval & Filtering): by default the currently installed file is kept; alternatively the package maintainer's version is installed. Dnf and Yum never ask (rpm writes .rpmnew / .rpmsave files instead), so the option does not apply to them.
On Apt systems the agent also decides how the packages are handed to apt. When the run covers everything apt has pending (no severity, type, approval or deployment-ring filter drops a package), apt resolves the upgrade itself: apt-get upgrade --with-new-pkgs by default, which installs new dependencies but never removes a package, or apt-get dist-upgrade when the policy option Allow package removal (full upgrade) (Linux tab, Approval & Filtering, shown for apt) is on. With the option off, packages that apt can only upgrade by removing another one (a renamed library such as libzfs6linux to libzfs7linux on Proxmox VE) are kept back and listed in the job as Skipped, together with the packages a full upgrade would remove; Proxmox VE hosts need the option on.
A filtered selection installs the named packages only (--no-remove unless removal is allowed) and, if apt rejects the set as a whole, is retried package by package. apt waits up to five minutes for a package lock held by another process. When apt fails, its E: lines are shown in the item details of the job, in the job note and in the agent's Error.txt. A kernel update marks the device as reboot-required as soon as a kernel newer than the running one is installed in /boot, so the reboot policy applies on Debian and Proxmox VE hosts as well.
On Dnf and Yum systems (Fedora, RHEL and its rebuilds such as Rocky Linux and AlmaLinux, CentOS) the agent refreshes the repository metadata with dnf makecache / yum makecache before it reads what is pending. Pending updates are listed once per package, with the exact version dnf offers, and once per advisory, with the advisory's type and severity and its packages in the description; a package an advisory covers appears in both. On Fedora 41 and later (dnf5) the advisories are read with dnf advisory list.
When the run covers everything dnf has pending, dnf resolves the upgrade itself with dnf upgrade, which also handles obsoleted packages, kernels installed next to the running one and every advisory. A filtered selection installs exactly the approved package versions (name-version-release.arch) in one transaction and the approved advisories (--advisories= on dnf, --advisory on yum) in a second one. A package dnf cannot use (excluded by excludepkgs in dnf.conf, or a version the repository no longer offers) fails with dnf's own message (No match for argument, matches only excluded packages) and the other packages are installed in a second run; a transaction dnf rejects as a whole is retried update by update.
After the run the agent asks rpm what is installed: a package item is Success only when the approved version is installed (in a full upgrade, also a newer one), an advisory item only when dnf no longer lists the advisory as pending. dnf's error lines are shown in the item details of the job, in the job note and in the agent's Error.txt.
The agent installs Windows updates through Windows Update, one update after the other. With agent 3.3.0.12 or later the rules below apply. The limits are fixed; there is no policy setting for them.
Time limit per update. Every update has 6 hours for its download and installation. When an update is still running after that, the agent stops waiting for it and ends the run. The update is listed as Failed with the detail The update did not finish installing within 360 minutes, so the agent stopped waiting for it and ended the installation run. It counts as a failed attempt, so Retry count for failed patches and Retry delay (minutes) of the policy apply to it. Windows may still complete such an installation on its own; the device then reports the update as Installed or Installed, restart pending at its next synchronisation, next to the Failed result of the run. Updates that finished earlier in the same run keep their result, including a required restart. Updates the run had not started are Skipped with the detail The installation run ended before this update was started; it is attempted in the next cycle., and the note of the run or job names the limit.
Starting further updates. A run starts no further update once 60 minutes have passed since it began installing. A scheduled run that started inside its maintenance window keeps starting updates until the window ends, when that is later than the 60 minutes. An update that is already downloading or installing at that point is not interrupted, so a run can end after the window. A run that ends up to 60 minutes after its window restarts the device as usual. When it ends later than that, the device is not restarted automatically at that moment: with Automatic reboot (and with Ask user and Reboot immediately on a device where nobody is signed in) the restart stays outstanding, and the next scheduled run inside the maintenance window of the policy carries it out. With one allowed patch day per week that is the following week; until then the update is installed but not in effect, and the device shows the pending restart. The note of the run says that the restart was left to the next maintenance window. Updates that were not started are Skipped with the detail The run reached its time limit before this update was started; it is attempted in the next cycle. Catch-up runs outside the window and Patch Now use the 60 minutes.
Windows is installing something else. Before the agent hands an update to Windows Update, it checks whether Windows has an installation in progress, for example one that Windows started itself or one that an earlier run started. It waits up to 10 minutes for it. When Windows is still busy after that, the run starts no installation: the updates are Skipped with the detail Windows is still installing updates that were started earlier, so this run did not start another installation., and the next run tries again.
Long installations in a Patch Now job. The job stays Running for as long as an update installs. An update reads Pending until its turn comes, Installing while it is worked on, and gets its result as soon as it is finished, not at the end of the job. A Patch Now that is started while a scheduled run is still installing waits for that run for up to 60 minutes and then ends as Failed with Another patch run was still active on this device after 60 minutes.; start it again once the run has ended.
Agent updates during a run. A new agent version is not installed while a patch run or an installation started by the agent is in progress; the agent updates itself after the run, at the latest after 12 hours.
Agents before 3.3.0.12. The whole run (search, download and all updates) has 60 minutes. When they are used up, every update of the run is Failed with The installation run timed out after 60 minutes and was terminated., including updates that had already finished.
The status of a Windows update on the device's Updates tab (Available, Installed, Installed, restart pending) is what Windows Update on the device reports at each device synchronisation. It is not taken from the result of a run; a run records its own result in the Last run chip and in the patch history. The two can differ, for example Installed next to Last run: Failed when an update failed in a run and was installed another way later.
Dates in the update history. The History action of an update on the Updates tab opens its update history. Under the status, the dialog shows when the device last reported it (Reported by the device on …), and under Last run when that decision was taken (Decided on …).
Several updates under one KB number. When Windows Update lists more than one update under the same KB number, the update is Installed only when all of them are installed (server 3.3.0.12 or later, with any agent version). A run reports such a KB as installed on the same condition; when only part of its updates went in, the item is Skipped and its detail says so.
Rolled back. The update history records Rolled back when an update was waiting for the restart and is offered again without a pending restart, or when the device had reported it as installed and Windows offers it again (server 3.3.0.12 or later). The status stays Available, so the update counts as open. A newer update that Microsoft publishes under the same KB number, such as the monthly Malicious Software Removal Tool, is not recorded as rolled back.
With agent 3.3.0.11 or later, the agent installs macOS updates one at a time with softwareupdate -i <label>, in this order: first the updates that are not macOS itself (for example Safari), then at most one macOS update per run. The rules:
Proof of installation. An update counts as installed only when softwareupdate no longer offers it and either reported it done or lists it in its installation history. A failure message, an exit code other than 0, output without such proof, or a run without output for too long ends the update as Failed, with the output of softwareupdate in Details. Every update the agent handles gets its own result in the run history and in the job; with Patch All, updates the policy filters leave out are not listed in the job.
Open apps.softwareupdate quits the apps an update replaces, for example Safari during a Safari update, and waits when one of them does not quit. A run that stays waiting is stopped by the time limits and the update is Failed with that reason; the next run tries again.
Macs with Apple Silicon. A macOS update on Apple Silicon has to be approved by a user who owns the startup disk; the agent runs as root and has no such credentials. It therefore does not start macOS updates on these Macs. They are listed with the reason Needs user input, and the tray icon asks the signed-in user to install them from System Settings > General > Software Update (window texts on the macOS Notifications sub-tab of the policy). The window is not repeated within a day for the same updates; when one of them is due again, it lists all updates that are still open. Other updates, such as Safari, are installed by the agent. A Patch Now job in which some updates were installed and others need the user ends as Partially installed; one in which all updates need the user ends as Failed with a note that names them.
Intel Macs. The agent starts the macOS update itself. When softwareupdate reports it prepared, the update is listed as Installed, restart pending and the restart follows the Reboot sub-tab of the policy, or the reboot choice of Patch Now. After the restart the agent compares the installed macOS version with the update and records the result in the next scheduled run: Installed, or Failed with Not installed by the restart. A macOS update that the restart did not install is not prepared again by scheduled runs or Patch All; it is left to the user, or an admin selects it in Patch Now.
Major upgrades. An update to a newer major version of macOS than the one installed on the device (for example 26 to 27) is a major upgrade and is listed with the update type Feature. Scheduled runs install it only when the policy option Allow upgrades to a new major version of macOS in scheduled runs is on; Patch All never includes it; Patch Now installs it when it is selected and the confirmation is accepted.
Whether an update is a major upgrade is decided per device. When a macOS update of the installed version and a major upgrade are both due, only the first one runs; the upgrade follows after the restart. An approval, manual or by an auto-approval rule, only makes the upgrade eligible; the policy option on each device decides whether it installs. The Software Update page of macOS can still offer the upgrade to the user, also when the policy holds it back; without an MDM, NetLock cannot hide it there.
Restart. The agent requests a restart only when it prepared a macOS update or installed an update that softwareupdate marks as requiring a restart. A Patch Now job with Reboot if required that installed nothing does not restart the Mac.
Compliance. A major upgrade that the policy holds back is still an open update: it counts as pending in the compliance figures when the compliance scope includes its update type (Feature). Unticking Feature in the compliance scope of the Settings tab leaves such upgrades out, and Windows feature updates with them. The update type in the catalog is shared by all devices and is the one the last reporting device sent: an upgrade such as macOS 27.2 shows as Feature when a Mac on macOS 26 reported it last, and as a regular update when a Mac already on macOS 27 did.
Several controls that other RMMs place on their patch management page are part of the policy in NetLock RMM.
Per-device or per-group exclusion lists. A patch is Rejected fleet-wide or not at all. To exclude a subset, use the Approval & Filtering sub-tab inside the relevant policy (Chapter 6.12), or move those devices to a different policy with stricter filters.
Rollout scheduling (maintenance windows, allowed days, time ranges). Configured on the Schedule sub-tab inside a policy's Patch Management tab.
Deployment rings. Configured on the Deployment Rings sub-tab inside a policy's Patch Management tab.
Reboot behaviour and user prompts. Configured on the Reboot sub-tab inside a policy's Patch Management tab.
Retry on failure. Configured on the Retry sub-tab inside a policy's Patch Management tab.
Notifications. Per-event patch notifications are toggled on the Notifications sub-tab inside a policy's Patch Management tab; the channels and recipients those notifications are sent through are configured in A.8 Notifications deep dive.
Patch management makes one global decision ("may this patch install anywhere?") and many per-policy decisions ("how do these particular devices install the things that are allowed?").
patch_management_enabled: master flag. Users without this flag do not see the Patch Management navigation entry and cannot reach /patch-management. A user who has the flag can approve, reject, defer and delete updates and read every tab.
Patch management: auto-approval rules and settings (patch_auto_approval_manage): shows the Auto-Approval tab and allows saving the auto-approval rules, the auto-approval master controls and the Settings tab (SLA thresholds, compliance scope, history cleanup). Because these settings apply to the whole instance, saving them additionally requires that the account has access to every tenant.
The figures of the page follow the tenant scope of the account: an account assigned to a subset of the tenants sees the devices and updates of those tenants only, in every tab and dialog.
Collections is the menu group for eight reusable libraries used across the product. Scripts, Jobs, Sensors and Custom Fields are programmable building blocks that you combine into larger tasks. App Hub, Application Control and Device Control are catalogues of packages, application rules and USB devices. Software Deployment rolls out App Hub entries to devices on demand.
Five of the eight Collections sub-sections are also referenced from inside Policy Settings. This chapter documents the library, that is how you author and manage the building blocks. Chapter 6 documents how a policy picks from the library and which devices run or enforce the result.
Scripts, Custom Fields and Software Deployment have no policy tab. Scripts are called by Jobs and Sensors; Custom Fields and Software Deployment stand alone.
The lists of Scripts, Jobs and Sensors share three list features:
Label. Every script, job and sensor can carry one free-text label of up to 64 characters, set in the add, edit and duplicate dialogs. The field suggests the labels already used in the same list; any other text becomes a new label, an empty field removes it. The label only organises the list: it is not part of what the agents receive, and changing only the label does not make the devices re-sync.
Grouping. As soon as one entry has a label, the list is grouped by label (case-insensitive, entries without a label last, each group collapsible). A Filter by label selector next to the search shows one label or only the entries without a label; the search also matches the label.
Selection. Accounts with the edit or the delete permission of the list see a checkbox per row, one in the header for all visible entries and one per label group. While entries are selected, the toolbar shows the number selected and Set label (edit permission; sets or, when left empty, removes the label of all selected entries), Delete selected (delete permission) and Deselect all. Only visible entries stay selected: changing the search or the label filter drops the hidden ones from the selection.
Delete selected asks once for all selected entries. For scripts the question also says how many jobs and sensors use them: those keep their settings but run no script until another one is set. Deleted jobs and sensors are removed from the automation rules that add them, exactly as with a single delete. Each entry is deleted on its own, so one that fails does not stop the others; the result message says how many of the selected entries were deleted.
Add Script creates a new script and Edit Script changes an existing one. Both dialogs share the same fields:
Name: required.
Description: free text.
Default timeout: the script's default wall-clock timeout, in minutes (1 to 9999). The agent terminates the script if the timeout expires.
Platform: one of Windows, Linux, MacOS, or System.
Shell: gated on Platform.
Platform and Shell pair up exactly as follows; other combinations are not supported:
Platform
Allowed Shells
Windows
PowerShell, Python3
Linux
Bash, Python3
MacOS
Zsh, Python3
System
MySQL
The System platform runs server-side database operations, not endpoint scripts. It is typically used by SQL-backed Custom Fields and some reporting workflows.
Python3 scripts run in Python's isolated mode (python3 -I): PYTHONPATH, the user site folder and modules placed next to the script are not loaded, so import only what the interpreter ships or what is installed machine-wide (pip install as administrator or root into the interpreter's own installation), or extend sys.path inside the script. On Windows the agent uses a machine-wide Python from the registry (HKLM\SOFTWARE\Python\PythonCore) or the py launcher; per-user installations under C:\Users are not used. On Linux the interpreter is /usr/bin/python3 or /usr/local/bin/python3, on macOS /usr/bin/python3, /opt/homebrew/bin/python3 or /usr/local/bin/python3.
The body of each dialog is a Monaco code editor with language-specific syntax highlighting driven by the selected shell. These helpers sit next to the editor:
Templates dropdown: starter examples for the current shell. Picking a template replaces the editor contents.
AI Assistant: shown only when AI is enabled in Settings → AI/LLM. Opens a chat panel that can draft or refactor the script in place.
Insert variable: a searchable menu of the device built-ins, the manual custom fields, their per-level forms and the write-back helper calls; a click inserts the token at the cursor. Disabled for the System platform.
Preview for device: in the button row of the dialog; renders the script for a chosen device and shows the resolved variables, the prelude line and the delivered text.
The Scripts library can share scripts with the community. Five dialogs cover it:
Community Scripts browser: lists scripts published to the community repository. Filter by platform, shell, or keyword; preview the source; click Import to copy a script into your library.
Import from GitHub: imports directly from a GitHub URL when the script is not in the community repository.
Publish: pushes one of your own scripts to the community repository. It is started from the script's edit dialog, so it needs collections_scripts_edit, and the script must have a description.
Report: reports a community script as abusive or incorrect.
View: detailed metadata view for a community script before import.
Imported scripts are regular entries in your Scripts library and can be edited like any other.
Tip: Set Default timeout conservatively. A script that never ends ties up the agent until the limit is reached, so a five-minute default is safer than the maximum.
Jobs pick a Script as the thing to execute on a schedule. See 8.2.
Sensors reference a Script in two ways: as the monitoring source for the PowerShell / Python3 / Bash / Zsh categories, and as the action script to run when thresholds are breached. See 8.3.
Scripts are not called from Automations (Automations assign policies and add sensors and jobs, which in turn reference scripts; see Chapter 5) and are not used by Software Deployment (deployment jobs execute install scripts stored on the App Hub entry, not library Scripts).
Manage Jobs at /manage_jobs is the library of scheduled tasks. A Job wraps a Script with a schedule and a platform. The Script is the "what"; the Job is the "when".
List columns: Name, Description, Platform, Type, Author, Date, and a hidden-status icon column (shown only on hidden jobs, with tooltip "Hidden — not shown in Events").
The Add Job and Edit Job dialogs share these fields:
Name, Description.
Timeout: 1 to 9999 minutes. Independent of the underlying Script's default timeout; the Job's value wins.
Schedule: dropdown of 12 options (see below).
Platform: Windows, Linux, or MacOS.
Type: PowerShell, Bash, Zsh, or Python3; the dropdown is filtered to what the selected Platform supports.
Script: the Script to execute, populated from matching scripts in your library.
Hidden: toggle. Hidden jobs do not appear in the Events view. The typical use is a background collection job that feeds a Custom Field and should not fill the Events view.
Jobs support twelve scheduling patterns. The same set is used by Sensors (see 8.3). Each is an entry in the Schedule dropdown:
System Boot: runs once per device on boot.
Date/Time: one-shot execution at a specific date and time.
Every X seconds: recurring interval in seconds.
Every X minutes: recurring interval in minutes.
Every X hours: recurring interval in hours.
Starting on Date, every X seconds: seconds-recurring interval that begins at a specified date.
Starting on Date, every X minutes: minutes-recurring interval that begins at a specified date.
Starting on Date, every X hours: hours-recurring interval that begins at a specified date.
On specific days at time: a single time plus Monday-through-Sunday checkboxes, so the job runs at the chosen time on each enabled weekday.
On specific days every X seconds: seconds-recurring on selected weekdays only.
On specific days every X minutes: minutes-recurring on selected weekdays only.
On specific days every X hours: hours-recurring on selected weekdays only.
Intervals in seconds exist for tight monitoring-style jobs; day-limited intervals are the usual choice for maintenance tasks that should only run during business hours.
A Script is a reusable piece of code. A Job is a scheduling wrapper that picks a Script. Several Jobs can use the same Script with different schedules, for example an "hourly quick disk check" and a "daily deep disk audit" that run the same script with different timeouts and intervals.
Jobs attach to policies through the Jobs tab of Policy Settings (see Chapter 6.11), or to the devices an automation rule matches, in addition to their policy (see Chapter 5.6). A job with neither attachment exists in the library but does not run anywhere. Deleting a job removes it from every policy and every automation rule that uses it; a rule left without any action is switched off.
Manage Sensors at /manage_sensors is the library of monitoring sensors. A Sensor samples a metric on a schedule, evaluates thresholds, and can run an action Script when a threshold is reached. Sensors of the category Server are the exception: the NetLock server evaluates them itself when something happens on the server side, and they never reach a device (see Server sensors below).
List columns: Name, Description, Platform, Category, Sub-Category, Severity, Author, Date. A server sensor shows Server as its platform and its kind as the sub-category.
Severity takes one of four values: Critical, High, Moderate, Low. Severity is set on the sensor and shown on notifications and on the Dashboard.
The Add Sensor and Edit Sensor dialogs share the core fields Name, Description, Platform, Severity, Schedule (the same twelve options Jobs use) and Category. Below them, the dialog shows the Sub-Category and Rule fields of the chosen category.
Sensors come in eleven categories. The first ten run on the device; the eleventh, Server, is evaluated by the NetLock server:
Utilization: host-level metrics. Six sub-categories:
Processor: CPU usage threshold.
RAM: memory usage threshold.
Drive: disk space or IO threshold.
Process CPU Usage (%): CPU percentage consumed by a named process.
Process RAM Usage (%): memory percentage consumed by a named process.
Process RAM Usage (MB): memory bytes consumed by a named process.
Rule configuration uses a threshold slider (5 to 100 percent, step 5) for the Processor / RAM / Drive variants, and a Process Name field for the Process-CPU / Process-RAM variants. The Notification Threshold Max value (0 to 9999) is not a usage limit but the number of consecutive hits after which the notification is sent, as described under Thresholds and actions below.
Windows Eventlog: match entries in the Windows event log against a query. Useful for specific event IDs that represent failures you care about.
PowerShell: the data source is a PowerShell script. The agent runs the script on schedule; the script's numeric output is the sample value.
Python3: same model, Python3 as the language.
Bash: same model, Bash as the language.
Zsh: same model, Zsh as the language.
Service: the state of a Windows or Linux service. Breaches when the service is not in the expected state.
Ping: ICMP reachability of a host. Breaches on loss.
SNMP: SNMP GET, Walk, or Monitor operation against a network device. The sensor stores credentials and queries per-sensor.
Other: ready-made checks picked from a template catalogue, among them the file, directory and registry sensors described in the next section.
Server: events the NetLock server raises about devices: Unauthorized device and Device country. See Server sensors.
A server sensor is not run by an agent. The NetLock server evaluates it at the moment the event happens: when a new device registers, an authorized device is reinstalled, a device reports a changed hardware ID or the license limit takes an authorization away, or when a device connects from a country that the country restriction does not list. Server sensors have two kinds, Unauthorized device and Device country.
Creating one. In the Add Sensor dialog, choose the platform Server, or pick the template Unauthorized device (server) or Device country (server) from the template catalogue; the template appears whatever platform is selected. The dialog then shows the server sensor form:
Name, Description, Label, Severity and the notification channels, as for every sensor. Without a channel the event only appears on the Events page.
The kind.
Triggers: the situations the sensor reports. At least one is required.
The tenants the sensor covers, or All tenants (including tenants created later). Only accounts that are assigned to every existing tenant can select all tenants.
Schedule, thresholds, action script, suppression, the live test and the AI assistant do not apply and are not shown.
A server sensor is active as soon as it is saved; to stop it, delete it. A new or changed sensor takes effect within a minute. The kind of a saved server sensor cannot be changed, and a server sensor cannot be turned into an agent sensor or the other way round; duplicating one keeps its kind and triggers.
What every server sensor has in common.
It reports devices of the tenants it covers. A device without a tenant is never reported.
Each sensor that matches a device writes its own event with its own severity, notification channels and sensor id. Several matching sensors therefore write several events. Without a matching sensor, no event is written.
The events are delivered through the notification channels like any other sensor event.
Server sensors are never assigned to policies or automation rules and are never sent to agents. The Sensors tab of a policy does not offer them.
An account restricted to some tenants only selects tenants within its access. A server sensor that covers tenants outside the account's access shows a lock instead of its actions and cannot be edited or deleted by that account.
The public API lists server sensors read-only with serverSensor { allTenants, triggers }; they are created and changed in the web console (see X.9.9).
Writes an event of the type Device authorization when a new device registers, an authorized device is reinstalled, a device reports a changed hardware ID or the license limit takes an authorization away. The triggers, all selected for a new sensor:
New device awaiting authorization: a new device registered and waits in the unauthorized devices list (see Chapter 3.2).
Authorized device reinstalled (new access key): a reinstalled agent took over an authorized device under a new access key.
Hardware ID changed: an authorized device reported a different hardware ID; the server stores the new ID and the device stays authorized.
License limit reached: the license limit check took the authorization away.
A device that ends up authorized automatically is not reported, and neither is a device an administrator deauthorizes by hand. Hardware ID changed is the one trigger of this kind whose device stays authorized, and its event says so; the other events name the device, its tenant and where to approve it.
Reports devices by the country of the address they connect from. The measure is the server list of the country restriction under Settings → Security → Country restriction; the sensor has no country list of its own. The form shows the current server list read-only as flags, states whether the restriction for the server is on or off, and offers a link to the settings page to accounts that may open it. Addresses from private networks are never looked up and never count, for any trigger.
The triggers:
Device connects from a country outside the list (restriction off): outside_countries. For the monitoring mode: the server list is maintained, but its switch is off. A device that checks in from a country outside the list keeps working, and an event is written. This shows which devices a restriction would cut off before it is turned on. An address the GeoIP database has no country for counts as outside only when Allow addresses the GeoIP database has no country for is off; the event then names the country as unknown.
Device refused by the country restriction (restriction on): refused. The switch of the server list is on and the server refused a request because of its country. The server identifies the device from the refused request: its access key and hardware ID must match an authorized device. The request is answered with 403 at once; the event is written in the background. A refusal event is only written while the restriction for the server is on. The event states that the device cannot sync until its country is added to the server list or the restriction is turned off.
Requests without such an identity (browsers, the Relay App, the Console App, unknown or unauthorized devices) produce no event and are visible only in the log and in the connection statistics. A device installed in a refused country for the first time has never registered with the server and therefore cannot be reported.
Country of the device changed: country_changed. Independent of any list; see below.
A new sensor has the first two triggers selected. country_changed is not selected by default, because roaming laptops and phones report many changes. While the server list is empty, outside_countries and refused cannot fire and the form shows a warning; country_changed still reports.
Reporting once, not on every check-in. Each device is reported once per country and trigger: a device that stays outside the list is not reported again at every check-in. The report is re-armed when the device checks in from a listed country. Even then, the same country is reported again no earlier than 24 hours after the last event for it, so a laptop that switches its VPN back and forth is reported at most once a day. A move to another country outside the list is reported at once. When an administrator turns the restriction on for a device already reported as outside, the refusal is reported again, because the device now stops working.
Country changed. The server keeps the last known country of every device and compares each check-in with it; a refused request of an identified device is compared as well.
Only a country the GeoIP database resolves counts. A check-in from a private network or from an address without a country is not a change and leaves the last known country as it is, so Germany → (office LAN) → Germany reports nothing, and Germany → (VPN into the server network) → United States reports one change.
The first check-in with a known country records the country without an event. A newly registered device and a reinstalled agent also only record their country.
A move back and forth between the same two countries is reported once per 24 hours: Germany → United States reports, United States → Germany and further moves between these two within 24 hours do not; after 24 hours the next move between them is reported once. Germany → United States → France reports both moves.
An update of the GeoIP database can assign an address to another country; affected devices then report one change.
A device that moves into a country outside the list, covered by a sensor with both country_changed and outside_countries (or refused), raises two separate events: the change from the old to the new country and the fact that the new country is not listed.
The state is kept per device, not per sensor. A sensor created after a device has been reported does not report that device again for the same country; the first sensor created reports devices that are already outside the list at their next check-in.
The events have the type Device country and are reported by Device country. Their titles read, followed by the sensor name in brackets:
Device connected from a country outside the allowed list: United States (US).
Device refused by the country restriction: United States (US).
Device changed country: Germany (DE) → United States (US).
The description lists the reason, the sensor, the new and the previous country, the external IP address, the allowed countries and the state of the restriction (or the tenant and location for a country change), the platform, the operating system and the agent version. Device country events also appear on the device's Events tab.
Update the Web Console before the server; until then the server evaluates no device country sensor.
The path fields of the file and directory sensors in the Other category (File change, Directory change, File exists, File age, File size, Directory size, Directory files count, Directory permission drift, Equal folder, Last log keyword, Log directory keyword) accept two kinds of placeholders, and the key path of the Registry change watch sensor accepts a third one. All of them are resolved on the device by the agent when the sensor runs; the value stored in the sensor stays as you typed it.
Environment variables
%NAME% works on every platform, including names with parentheses such as %ProgramFiles(x86)%.
$env:NAME (PowerShell style) and ${NAME} work on every platform as well. A bare $NAME is not expanded, so a $ inside a file name is left alone.
Only the path fields are expanded. User names, passwords, patterns and keywords are taken literally.
A variable that is not set is left in the path unchanged; the sensor then reports the path as not existing, and the unresolved token is visible in the event text.
The agent runs as SYSTEM on Windows and as root on Linux and macOS. User-specific variables such as %APPDATA%, %USERPROFILE%, %LOCALAPPDATA% or ${HOME} therefore resolve to the system account, not to the user who is signed in. For per-user paths use the {user_profiles} placeholder below.
{user_profiles}
A path that starts with {user_profiles} is checked once for every local user profile on the device, with the rest of the path appended to each profile root:
Windows: the profiles listed under HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\ProfileList for real user accounts (S-1-5-21-…), typically C:\Users\<name>. Service and system profiles are not included.
Linux: the home directories of the accounts in /etc/passwd with a uid between 1000 and 65533.
macOS: the directories under /Users, without Shared, Guest and hidden or service entries.
Rules:
The placeholder must be the first segment of the path and may appear only once. {user_profiles} alone, {user_profiles}\<rest> and {user_profiles}/<rest> are valid; C:\{user_profiles}\x is rejected with an error event. It is not case-sensitive.
Environment variables in the remainder are expanded before the profile roots are joined.
Directory change, File change, File exists, File age and File size support the placeholder. Directory size, Directory files count, Directory permission drift, Equal folder, Last log keyword and Log directory keyword do not and report "The {user_profiles} placeholder is not supported by this sensor."
Directory change and File change keep a separate baseline per profile. A profile whose folder or file does not exist is skipped without an alarm and gets no baseline. A profile that appears later (a new user signs in) gets its baseline on the next run without an alarm. A profile that disappears drops out of the baseline without an alarm.
A folder or file that existed when the baseline was recorded and is gone on a later run raises an alarm once. With {user_profiles}, an empty folder is not an error (for a single path it still is). A change is reported for exactly the profile it happened in, with the usual added / removed / changed lists.
File exists with {user_profiles} alarms when any profile is in the unexpected state (file missing while it should exist, or present while it should be absent) and lists the affected profiles.
File age and File size evaluate the matches of all profiles together against the configured thresholds.
Editing the path, the pattern or the recursion of a Directory change or File change sensor records a fresh baseline on the next run instead of comparing the new location against the old baseline.
Unauthenticated UNC paths and the placeholder cannot be combined, because the placeholder has to be the first segment.
Example: watch all autostart entries
Two Directory change sensors cover the per-user and the all-users startup folders on Windows:
Path {user_profiles}\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup: one baseline per user; a shortcut dropped into one user's Startup folder raises an event naming that user.
Path %ProgramData%\Microsoft\Windows\Start Menu\Programs\Startup: the all-users startup folder.
On Linux the equivalent per-user location is {user_profiles}/.config/autostart.
{user_sids}
A key path of the Registry change watch sensor that starts with {user_sids} is watched once in every user hive that is currently loaded under HKEY_USERS, with the rest of the path appended to each SID:
Windows only. The hives of real user accounts are used: local and domain accounts (S-1-5-21-…) and Entra ID accounts (S-1-12-1-…).
The service hives (.DEFAULT, S-1-5-18, S-1-5-19, S-1-5-20), the per-user class stores (<SID>_Classes) and the .bak leftovers of a profile repair are not included.
Each SID is resolved to its account name (DOMAIN\user or MACHINE\user). When the account cannot be looked up - a deleted account or an unreachable domain controller - the profile folder name is shown instead, and if that is unavailable too the raw SID. The resolved name is remembered per sensor, so the lookup normally runs once per user.
Rules:
The placeholder must be the first segment of the key path and may appear only once. {user_sids}\<rest> is valid; SOFTWARE\{user_sids}\x is rejected with an error event. It is not case-sensitive.
The hive selection of the sensor is implied by the placeholder and ignored, because HKEY_USERS\<SID> is by definition the root of a user hive. The event body names the key that was actually watched.
Only hives that are currently loaded can be read. A user who is signed off has no hive under HKEY_USERS; those profiles are listed in the event as not evaluated, so it is visible who was left out. The agent never mounts a NTUSER.DAT of its own.
Each user keeps a separate baseline. A hive seen for the first time (a user signs in) gets its baseline without an alarm; a hive that is no longer loaded (the user signs off) is reported for information and keeps its baseline for the next sign-in. Neither raises an alarm.
A change is reported for exactly the user it happened in, with the usual added / removed / modified lists. All users share one event.
The value limit applies per user hive, not to the run as a whole. A hive over the limit is reported on its own and the remaining hives are still evaluated.
Changing the hive, the key path, the recursion or the value limit of a Registry change watch sensor records a fresh baseline on the next run instead of comparing the new location against the old baseline. This applies to a single key as well as to {user_sids}.
Environment variables are not expanded in a registry key path.
Agents without support for the placeholder report The registry key was not found: <hive>\{user_sids}\…; update the agent.
Example: watch the autostart entries of every signed-in user
A Registry change watch sensor with the key path {user_sids}\Software\Microsoft\Windows\CurrentVersion\Run covers the per-user Run key of everyone who is signed in; an entry added for one user raises an event naming that user. The machine-wide counterpart is a second sensor with the hive HKEY_LOCAL_MACHINE and the key path SOFTWARE\Microsoft\Windows\CurrentVersion\Run.
Every sensor defines two thresholds. Neither is a value limit: both count how many times in a row the sensor's condition has to be met (a hit) before something happens.
Notification Threshold Max: the number of consecutive hits after which the event is raised and the notifications are sent. 0 or 1 means on the first hit, 3 means on the third consecutive hit.
Action Threshold Max: the number of consecutive hits after which the configured action Script runs, counted the same way and independently of the notification threshold.
A run in which the sensor does not trigger ends the streak and resets both counters to zero, so a threshold of 3 only fires after three consecutive runs with a hit; a hit, a miss and two further hits do not reach it. Windows Eventlog sensors count each matched event as one hit, so several matching events found in one run advance the counters by that number; the action script itself still runs at most once per run.
The action section exposes a Script dropdown, populated from Scripts that match the sensor's Platform and runtime. When the action threshold is reached, the agent executes the selected script on the device that reported the hits. This is the usual pattern for "when the disk reaches 95%, run the cleanup script": the percentage is the sensor's own condition, the thresholds decide after how many consecutive breaches the script runs.
Sensor readings are one of the Dashboard's queryable data sources (see Chapter 2), and sensor breaches appear in Events (see Chapter 12).
Agent sensors attach to policies through the Sensors tab of Policy Settings (see Chapter 6.10), or to the devices an automation rule matches, in addition to their policy (see Chapter 5.6). Sensors the SNMP discovery manages cannot be added through a rule. Deleting a sensor removes it from every policy and every automation rule that uses it; a rule left without any action is switched off. Server sensors are not attached anywhere; they apply to the tenants they cover.
collections_enabled, collections_sensors_enabled, collections_sensors_add, collections_sensors_edit, collections_sensors_delete. Server sensors use the same permissions, limited to the tenants of the account as described under Server sensors.
Manage Custom Fields at /manage_custom_fields is the library of Custom Field definitions. Custom Fields can add whole tabs and sections to the device detail page, filled from several data sources.
List columns: Name, Description, Author, Date, Tabs (count of tabs this definition contributes).
One dialog, the Custom Field Builder, handles both Add and Edit. The builder is a visual editor with several panels in which you design a whole part of the device detail page.
The builder has the following structure.
Definition panel (top).Name and Description of the Custom Field set.
Header Action Buttons. A list of buttons injected into the device detail header next to the standard controls (Screen Control, Shell, and so on). Each button has:
Label: what the button says.
Type: URL Handler.
Icon: autocomplete over the icon set.
URL Handler buttons open a URL template. The template supports placeholder tokens {device_id} and {field_key}, which are substituted at click time.
Tabs. The top-level containers on the device detail page that this definition contributes to. Each tab has:
Target: New Tab, Existing Tab, or Existing Section. New Tab creates a fresh tab; the other two inject into a tab or section that already exists elsewhere in the detail page.
Tab Name and Icon: shown for New Tab.
Sections. Inside each tab, one or more sections, each with a Section Name, appear as labelled blocks on the device page.
Fields. Inside each section, one or more fields. Every field has:
Key: the programmatic identifier used in placeholders and in scripts. A key starts with a lowercase letter and continues with lowercase letters, digits and underscores, at most 64 characters, and it must be unique across all definitions. The builder rejects a new or renamed key that breaks either rule. Keys outside this rule stay reachable in scripts through their environment name (NL_FIELD_ plus the key in upper case, with every other character turned into an underscore); the builder reports them when the definition is saved. When two definitions share a key, scripts read and write the definition that was created first.
Label: the human-readable name.
Type: one of Text, Multiline, Table, or Secret. Secret is available with the Manual data source only; see Secrets below.
Data Source: one of Manual, Job Result, or SQL Select.
Inheritable: a checkbox for Manual fields. An inheritable field can hold values on group, location, tenant and global level, and a device without a value of its own inherits the nearest one. See Scope and inheritance below.
Data sources in detail:
Manual: the field is free for users to edit on the device detail page. The value is stored per device.
Job Result: the value is auto-populated from a Job's output. The builder asks for a Job Name; if you need to pluck part of the output, supply a Parse Regex. Jobs used to feed Custom Fields are typically flagged Hidden to keep them out of the Events view (see 8.2). For a value a script computes itself, the write-back helper is the more direct route; see Write custom field values from a script.
SQL Select: the value is the result of a SQL query. Two modes:
Visual Query Builder: pick a table, pick columns (with aggregates COUNT, SUM, AVG, MIN, MAX, DISTINCT), add joins (INNER, LEFT, RIGHT), add WHERE filters with device_id already available as a placeholder, set ORDER BY and LIMIT.
Direct SQL: lets you enter SQL directly, with {device_id} as the available placeholder (bound as a parameter).
Both modes, and the preview in the builder, run only over the MySQL user configured under Settings → SQL access; the visual builder lists exactly the tables and columns that user can read. On save, the statement is checked with EXPLAIN over that user and MySQL's message is shown when it is refused. Without SQL access, the builder shows a notice with a link to Settings → SQL access and offers neither the query builder, the SQL field nor the AI SQL assistant, and existing SQL fields show (SQL access not configured) on the device page. Creating and editing such fields needs collections_custom_fields_add / collections_custom_fields_edit. See Set up SQL access for reports, dashboards and custom fields.
Section Action Buttons. Each section can carry its own buttons, with the same shape as Header Action Buttons but scoped to the section. Use them for actions that belong to the data shown in that section.
Values are stored per device: every device covered by a Custom Field definition has its own value set, and the field metadata (keys, labels, types, queries) is shared.
A Manual field marked Inheritable can additionally hold one value per tenant, per location, per group, and one global value. A device reads the first value found in this order: its own value, then its group, its location, its tenant, and finally the global value. A field without the flag has device values only. The device page shows an inherited value greyed out, with an icon whose tooltip names the level it comes from. The same effective value, with its level, is what a script variable and the public API receive; see Script variables and custom fields in scripts and X.9 — Public API.
Removing a value deletes its row. On the device page, Remove device value in the editor of the field deletes the device's own row after a confirmation, so the device inherits again; Clear value in a level editor deletes that level's row.
Level values are edited where the level lives:
Tenant: the Custom Fields section on the Manage tenant page (Tenants → tenant → Manage).
Location: the Custom Fields section on the Manage location page of the location.
Group: the Custom Fields section in the group's edit dialog.
Global: Settings → Custom Fields, section Global values.
Note: On the Manage location page the section is shown only to accounts that hold tenants_locations_edit or tenants_locations_delete; the tenant page and the group dialog have no such condition.
All four places show the same editor: one row per inheritable manual field with the definition, the field, the key, the value on this level, the effective value with its source, who changed it last and when, and the row actions Set value, Reveal secret / Hide secret (secret fields only) and Clear value. A key outside the naming rule is marked with the environment name scripts use.
Viewing a level needs collections_custom_fields_enabled and access to the tenant; changing a value needs collections_custom_fields_edit; the Global values section needs settings_custom_fields_enabled in addition. Every change is written to the audit log with the level and the field, never with the value.
Changing a value on any level marks the affected devices for a policy re-sync, so jobs and sensors that use the value through a script variable pick it up at the next check-in: a device value marks that device, a level value the devices below it, a global value every device. When an automation rule compares the field (Chapter 5.2.1), the rules are evaluated again for the affected devices and the online ones are pushed at once; this applies to values written on the device page, on a level, by a script and through the public API. Deleting a tenant, a location, a group or a definition removes the values stored for it.
A field of type Secret holds a value that should not be readable in the console by default: an enrolment token, an API key, a password an install script needs. Secret fields are Manual fields only, and they can be inheritable like any other manual field.
Values are stored encrypted, on devices and on every level.
The device page, the level editors and the script preview show a mask. A new value is typed into an empty password field.
Reveal secret shows the stored value to accounts with collections_custom_fields_reveal_secrets. Every reveal writes an audit entry. The permission is granted under Users → account → Collections → Custom fields; administrator accounts hold it.
The public API never returns the value of a secret field (value: null, isSecret: true).
A script that refers to the field receives the plain text on the device; see the security notes.
Changing a field's type from Secret to Text keeps the stored values encrypted. Enter them again after such a change.
The device detail page shows every tab, section and field a Custom Field Definition declares (see Chapter 3). A manual field shows where its value comes from: an icon with the tooltip Inherited from … for a level value, and one with Set by script on … or Set by API on … for a value written by a script or the public API.
The public API reads and writes device values and level values; see X.9 — Public API.
Dashboard panels can query the same underlying storage via the Panel Builder's SQL query builder, which lets you aggregate custom-field data across the fleet. This needs SQL access.
Reports do not expose custom-field values as a selectable data source in the Report Builder. Custom fields appear in Reports only as optional, cosmetic key-value entries on the cover-page footer of a brand template. To include custom-field data in a report, write a direct SQL query against the underlying storage; this needs SQL access (see Chapter 11.3).
collections_custom_fields_edit also gates changing values on devices and on tenant, location and group level; settings_custom_fields_enabled is needed in addition for the Global values tab.
collections_custom_fields_reveal_secrets: reveal the stored value of a Secret field. Every reveal is written to the audit log.
Manage Apps at /app_hub_manage_apps is the catalogue of installable packages. This page maintains the list of available apps; Software Deployment installs them on devices (see 8.8).
List columns: Icon, Name, Publisher, Version, Source (colour-coded chip: winget, flatpak, chocolatey, script, file), Target OS, and per-row Edit and Delete actions. A file app whose file is missing on the File Server or was changed there outside of NetLock RMM is marked File missing or File changed next to its source chip.
For winget, Chocolatey and Flathub apps the Version column shows the current version from the synced catalogue, not the version recorded when the app was added; hovering the version shows the recorded one when the two differ. Apps that are not in the catalogue (for example a winget app from the msstore source or a Chocolatey app from a private feed) keep the recorded version, shown dimmed. Script and file apps always show their own Version.
Winget: Windows Package Manager feeds, used for Windows apps.
Flathub: the Flatpak catalogue, used for Linux apps.
Chocolatey: Chocolatey feeds, used for Windows apps.
Script: manual entries backed by install / update / uninstall / detection scripts you write.
File from the file server: manual entries that run an installer file uploaded to the File Server (.msi, .exe, .msu, .ps1, .deb, .rpm, .sh, .pkg) with parameters per action, a required detection script and the SHA-512 of the file pinned in the app. See Deploy an installer file from the file server.
Script: Install script, Update script, Uninstall script, Detection script, Detection window (seconds), and a Script Shell selector.
File from the file server: Choose file (with its SHA-512), Install arguments, Update arguments, Uninstall (None, This file with arguments, Script) with Uninstall arguments or the uninstall script, the Detection Script (required) and the detection window. The target system follows the file type. Choosing or changing the file needs file_server_enabled; such apps always run with elevation.
The Edit App dialog presents the same fields pre-populated against an existing entry. The Version field is only shown for script apps; for winget, Chocolatey and Flathub apps the version follows the catalogue.
On Windows, Linux and macOS, an install, update or uninstall script fails when it exits with a code other than 0, when its output starts with Error, or after 30 minutes. Update and Uninstall are only offered for a script app that has the matching script.
The Detection script is optional and tells whether the app is installed: exit code 0 and at least one line of output means installed, anything else not installed. The first output line should carry the installed version (for example 2.4.1). The script runs before and after every install, update and uninstall, in the app's context (SYSTEM/root, or the signed-in user for apps without elevation on Windows), with a 5-minute timeout per run.
Before the action, an install of an installed app and an update or uninstall of an app that is not installed are skipped (Skipped); a failing detection script lets the action run. After a successful action, the script runs again (right away, after 5, 10, 20 and 30 seconds, then every 30 seconds) until it reports the expected state or the Detection window (default 300 seconds, 0 = no check after the action) ends. A result that is not confirmed means Failed; a detection that fails on every check means Detection error.
The detected version drives Update available in the tray icon's App Hub and the auto-update of script apps, which only runs when the detected version is lower than the catalogue Version. See Deploy custom applications with scripts for a full walkthrough.
Winget, Flathub and Chocolatey each have a browser dialog: Winget Catalog Browser, Flathub Catalog Browser and Chocolatey Catalog Browser. Each is a searchable table of the remote catalogue with a metadata preview pane. Select a row, click Add to Catalog, and the app is copied into your local App Hub with its identifiers pre-filled.
The page has a Refresh catalogs button that triggers an asynchronous sync of all three remote catalogues. Progress is shown in the page's status area; the button reports when the sync completes. Refreshing pulls the latest catalogues from NetLock; the catalogue browsers and the Version column of package-manager apps then show the new data. The catalogues are only used for browsing and display: agents install and update winget, Chocolatey and Flatpak apps with the newest version the package manager offers on the device, unless a software deployment pins a version.
The App Hub tab inside Policy Settings (see Chapter 6.13) decides which catalogue apps are visible to end users in the tray icon under a given policy. Selecting apps in the policy only decides what the tray offers; it does not install anything.
Application Control is an allowlist system for executables on Windows devices. Rulesets live at /application_control_manage_rulesets. The ruleset detail page is at /application_control_ruleset.
Add Ruleset: create a ruleset (Name, Description).
Edit Ruleset: rename or redescribe.
Delete Ruleset: delete.
Click a ruleset to open its detail page, which lists the rules inside it. The detail page has Back, Save, Edit and Delete buttons at the top and Add, Edit, Delete actions on the rule list.
Each rule identifies one allowed executable by any combination of file and certificate attributes. The Add Rule and Edit Rule dialogs share these fields (Name is required; everything else is optional). A process is allowed as soon as one attribute of a rule matches, and only attributes whose filter is active in the policy count, so a value in a field whose filter is off has no effect:
File attributes:
File Path: exact absolute path to the executable, or a folder rule ending in \* (see Folder rules).
A rule matches when at least one attribute that is filled in and whose filter is active equals the value of the running executable. Empty fields and - are skipped. Path and hash values ignore upper and lower case; version-info values are case-sensitive and ignore leading and trailing spaces; Certificate Owner and Certificate Issuer match when the rule's value is contained in the certificate's. Certificate Begin, Certificate End, Certificate Public Key and Certificate Serial Key are stored with the rule for information and are not compared. Any executable not matched by any rule in a ruleset attached to a device is blocked.
Saving a ruleset, approving blocked applications into it and deleting it sync the devices of the policies that use the ruleset right away.
Tip: A SHA256 or SHA512 hash rule is the strongest form and does not need other fields. Path-only rules are the weakest, because any file at that path matches, whatever its contents. File Product and File Company are tolerant of updates but weaker than a hash or a certificate, because whoever builds a file can set these values freely.
A File Path value ending in \* covers the folder and all its subfolders, for example C:\Program Files\*. C:\Program Files and C:\Program Files (x86) are separate folders and need one rule each. A value without \* stays one exact path. No other wildcards exist.
Folder rules require agent 3.3.0.11 or later. Older agents treat the value as an exact path that never matches, so they keep blocking.
Both exact paths and folder rules are compared in normalized form: short (8.3) names, .., forward slashes and the \\?\ prefix make no difference. Machine-wide environment variables such as %ProgramFiles% are expanded. Variables of a user profile such as %LOCALAPPDATA% are not supported, because the agent runs as SYSTEM and would resolve them to its own profile.
The agent ignores a folder rule on a drive root (C:\*), on a network share root, or in \Users\. It writes the reason to its Application Control log, which is only written in debug mode, and a blocked application's event states how many rules were ignored.
A folder rule does not allow a file if the file or any folder from there up to the rule's folder can be changed by non-administrators, or if these permissions cannot be read.
Accounts that count as administrators are SYSTEM, the local Administrators group, TrustedInstaller, the built-in Administrator, Domain Admins and Enterprise Admins. An owner outside this list counts as a non-administrator, because an owner can always change the permissions. Some applications create subfolders below Program Files that normal users can write to; a file there is blocked unless another rule allows it, and the event names the folder rule that was not applied. A change of these permissions takes effect within five minutes, or when the agent loads the ruleset again.
When the agent blocks a launch attempt, the attempt is logged and appears on the Blocked Applications tab. List columns: Policy (the ruleset name), Count (instance count for this blocked entry), Date, Device, Process, Path, Company, Product.
From this tab you operate on selections with two actions:
Approve Selected: inserts the blocked entries as allowed rules into the associated ruleset. The server deduplicates by SHA512 so repeat approvals do not clutter the ruleset.
Delete Selected: removes the log entries without whitelisting.
Every entry carries a status: Pending approval, Approved, or Dismissed. Approving moves an entry to Approved and adds a rule; dismissing moves it to Dismissed without adding a rule.
Application Control rulesets attach to devices through the Windows → Application Control sub-section of Policy Settings (see Chapter 6.7). A ruleset with no policy attachment exists in the library but enforces nothing.
USB Device Control is an allowlist system for removable peripherals. The same page is reachable from two routes, /device-control/whitelist and /device-control/blocked, each opening with a different tab selected.
List columns: Device Name, Manufacturer, Device ID (truncated with a tooltip showing the full ID), Scope chip (device, tenant, location, group, or global), Scope Target, Author, Date, Status (enable/disable toggle), and a per-row Delete action.
Entries a device learned during its learning period have the scope device and the author Auto-Whitelist (Agent: <device name>); see Chapter 6.8. The author shows the device's current name, so it follows a rename of the device the same way Scope Target does; for an entry whose device was deleted, the name the device had when the entry was learned is shown.
The Device ID encodes vendor-id, product-id and serial number. Together they identify a specific USB device, or a specific model, depending on how the entry is scoped.
Re-learn connected devices above the whitelist opens a list of the devices a re-learn can be requested for: the Windows computers of your tenants whose policy has Device Control on. Search by device, tenant, location or policy, tick the devices or use Select all shown, then start the re-learn with Re-learn on N device(s). Each selected device learns the devices connected to it again, for the learning period of its policy, starting at its next policy sync. This works like Re-learn connected devices on the USB Devices tab of a single device.
A run takes at most 500 devices. After the confirmation and, where it is set up, the additional sign-in confirmation, each selected device is checked against your tenant access before its re-learn is stored. Devices that are no longer Windows computers with Device Control on in their policy are skipped. The first 25 devices are told to sync right away; the others start at their own next regular policy sync, so not every device learns at the same moment. The button shows the progress, and a summary names how many devices were requested, skipped and delayed. Each device that got the re-learn is written to the audit log. The button is shown only with the permission devices_usb_learning.
When the agent blocks a USB device, the event appears on the Blocked Devices tab.
List columns: Count, Date, Reporting Device, USB Device, Manufacturer, Type (device class: Mouse, Keyboard, HID, USB, DiskDrive, WPD, CDROM, Media, Network, XboxComposite), Device ID, Actions Taken (disabled, disabled_pending_reboot, disable_failed, logged; their meaning is in Chapter 6.8), Status chip (Pending, Approved, Dismissed), and a context-menu actions column.
Whitelist entries cannot be created in a dialog of their own. They are added in two ways: a device learns the devices connected to it during its learning period (see Chapter 6.8 and the USB Devices tab of a device), or an administrator approves a pending row on the Blocked Devices tab. Click the row's menu icon and pick:
Approve for this device: the whitelist entry applies only to the specific device that reported the block.
Approve for tenant: applies to every device in the tenant.
Approve for location: applies to every device in the location.
Approve for group: applies to every device in the group.
Approve globally: applies to every device in the deployment. Offered only to accounts with access to all tenants.
Dismiss: records that the block was reviewed but should not be whitelisted.
Approving at any of the five scopes inserts a row into the whitelist with the corresponding scope type and scope target. Dismissing closes the event without adding a whitelist row.
A whitelist entry matches a USB device by vendor-id, product-id, and serial (encoded in Device ID), plus device class. Serial-level matching identifies one specific physical device; vendor-and-product-only matching accepts an entire model family. The choice follows from the approval: the pending row carries the device's actual identifiers, and the resulting whitelist entry takes them over.
USB Device Control is enabled per policy through the Windows → USB Device Control sub-section of Policy Settings (see Chapter 6.8). Approving an entry or toggling its status forces an immediate re-sync so endpoints pick up the change.
collections_enabled and collections_device_control_enabled: open the page with both tabs.
collections_device_control_manage: approve a blocked device and switch a whitelist entry on or off.
collections_device_control_delete: delete whitelist entries and dismiss blocked devices.
devices_usb_learning: re-learn and end learning on a device from its USB Devices tab (see Chapter 3.3), and re-learn on several devices at once from the Whitelist tab (see above). This permission belongs to the Devices group.
Software Deployment installs, updates and removes App Hub packages on devices. The feature has three routes:
Software Deployment at /software_deployment: the list of deployment jobs.
New Deployment at /software_deployment/new: the four-step creation wizard.
The deployment detail page at /software_deployment/{id}: the detail view for a single deployment job.
Deployments are started on demand, not by policies. Each deployment is created, run and tracked as a job of its own; Policy Settings has no deployment tab.
List columns: ID, Name, Author, Created, Mode (Interactive or Bulk), Status (Pending, Running, Completed, Completed with errors, Cancelled), Progress (format succeeded/failed of target_count, with an error chip when failures exist), and Actions (View, Cancel, Retry, Rename, Clone, Delete).
Step 1: Packages. Autocomplete-search the App Hub catalogue. Only apps that are available for deployment appear in the wizard; apps added in the console always are. Each added package has an action dropdown (install, uninstall or update); for a script app without an update or uninstall script that action is disabled. A single deployment may include multiple packages with mixed actions. When the deployment is saved, every package is read from its App Hub app: the script of the chosen action, the detection script and the detection window.
Step 2: Targets. Choose the devices that should receive the deployment. You can add devices directly, or select groups, locations, or tenants; a dynamic-membership flag keeps a group target live as devices enter or leave the group.
Step 3: Options. Per-deployment settings:
Start date (optional) and Start time: when execution may begin.
Expires at (optional) and Expires time: when unstarted targets are abandoned.
Force reinstall: install even if the detection script reports the package as installed. Only the check before an install is skipped; the check after the install still runs.
Abort remaining packages on first failure: on a device, skip the remaining packages after the first package that fails.
Max attempts per device: the most attempts a target gets, the first one included.
Backoff between retries (minutes): minimum minutes between retries.
The wizard creates deployments that run in the background (bulk). Deployments with real-time feedback (interactive) come from the single-device Deploy Software dialog.
Step 4: Review. A summary view of the chosen packages, targets, and configuration. Confirming creates the deployment. If the start is in the past or unset, the deployment begins running immediately.
The detail view shows four info cards across the top (Status, Progress, Author & Created, Scheduled / Expires), followed by a per-device results table. Action buttons at the top of the page: Back, Cancel (available while the status is Pending or Running), Retry (available when any target has failed), Rename, Clone, Delete.
Each row in the per-device table is a target device; its attempt history is shown in the per-device results dialog. The items table lists the packages of the deployment with their action; its Arguments column shows the arguments of a file item and the winget switches of a winget item.
The per-device results dialog shows every attempt the deployment made on one device. Per attempt it displays:
Job Item ID, Attempt number.
Outcome: Success, Failed, Skipped, Detection error, Timeout or Cancelled. Skipped means the detection before the action decided there was nothing to do (the app is already installed for an install, not installed for an update or uninstall); it counts as a success. Failed also covers a script that succeeded while the detection script did not confirm the result within the detection window. Timeout means the script ran longer than 30 minutes (the file of a file app: 60 minutes), or a step without elevation got no result from the tray icon in time.
The detection state next to the outcome (Detected, Not detected or Detection failed) when a detection script ran.
Exit code, Duration, Started and Finished timestamps.
Error summary: an alert block if the attempt raised a specific error.
stdout tail and stderr tail: trimmed output from the script. Lines starting with [detection] explain what the detection script decided before and after the action.
A step without elevation on Windows runs in the signed-in user's session through the tray icon; the deployment waits for its result and reports it like every other step.
Use this view to analyse failed deployments. Exit codes and stderr tails show whether the failure is a package problem, a permissions problem or a temporary network issue.
The Retry button on the detail page re-queues every failed target in the deployment. Retries respect Max attempts per device and Backoff between retries (minutes) from the original configuration and increment the attempt counter. Successful targets are not touched. To recover from failures, fix the cause, then press Retry.
The Deploy Software dialog is a compact single-device version of the wizard, launched from outside the main Software Deployment page (for example from a device detail view). It carries the selected device's identity along with a package autocomplete and an action dropdown. Run Now creates the job and starts it immediately without the full wizard.
App Hub defines what can be installed; Software Deployment installs it. A deployment takes the metadata from App Hub (package identifiers per source, install and detection scripts, elevation requirement) and adds targets, scheduling, retry rules and per-device tracking.
This chapter covers four independent features that share a menu group in the navigation. They work without Collections or Policies, and each one has its own section.
File Server is a centralised storage hub for binaries, scripts, packages, and any other file you want agents or technicians to pull from a single known location.
Relay Server lets you reach a device's TCP service (Remote Desktop, SSH, a web admin UI, a database port) through a relay tunnel when a direct connection to the device is not possible.
Website Uptime Monitoring checks external URLs from the server on a schedule and raises events when availability, performance, SSL certificates, or content falls outside thresholds.
Port Scanner scans a manually maintained list of targets for open TCP ports and compares the findings with an allowlist.
Manage Files at /manage_files is the product's file distribution hub. Use it to publish anything your agents, scripts, or technicians need to download from a fixed place: installers, configuration bundles, intermediate artefacts a script produces on one device and another consumes, or documentation that a URL in the tray icon points to.
Uploads go through the Upload File action in the page toolbar. The action opens the native file picker, then streams the selected file to the File Server with a progress indicator. A single upload can carry up to 10 GB. Larger artefacts must be split before upload.
Downloads are initiated from a file's context menu. The download URL of a public file contains the file's GUID; Copy download link in the context menu copies it. Private files have no shareable URL and are downloaded from the Console.
Delete is also on the context menu. Deleting a folder removes its contents after the standard delete prompt, without a separate confirmation for the contents.
A file that an App Hub app of the source File from the file server or an open software deployment (draft, pending or running) uses cannot be deleted, and a folder that contains such a file cannot be deleted either. Uploading a file of the same name into the same folder is refused as well, because it would replace the file the app runs. The Console names the apps and deployments that use the file; the public API answers 409 with file_in_use. Choose another file in those apps, or finish or cancel the deployments, first. To publish a new release, upload it under a new name and choose it in the app.
Renaming and moving such a file is allowed, and so is renaming the folder it lies in: the file keeps its GUID, and apps, deployments and download links keep working.
A folder named /netlock at the root is gated by a dedicated permission, file_server_netlock. Users without that permission see an empty view when they open it and cannot upload into it. Use /netlock for files that technicians with File Server access should not see.
Every file shows its SHA512 hash in the list. When a script or an agent downloads the file, you can compare that value to the hash of the received bytes to confirm the content arrived intact and was not modified in transit. The hash is computed by the server on upload and does not change unless the file is replaced.
Devices download files with resume support: a broken transfer continues where it stopped. Downloads of App Hub file apps share a limited number of parallel transfers per server instance, 50 by default. A device that asks for one more is told to try again a little later and waits on its own. Change the limit with File_Server:Max_Parallel_App_Downloads in the server's appsettings.json (see Changing a value in appsettings.json) and restart the server. Downloads of the file browser, of files pasted into a screen session and of backstage do not count against the limit.
Agents and scripts. A PowerShell or Bash script on a device fetches a file by its download URL, checks the returned hash against the published SHA512, then acts on the content. This is the standard way to distribute a large binary that would be awkward to embed in a script.
Technicians. The download URL of a public file lets you hand a customer one link to an installer or log bundle without giving them access to the rest of the File Server.
Create Directory: enter a folder name to create a subdirectory in the currently open path.
Rename: rename the selected file or folder. A file keeps its GUID when it is renamed, and the files in a renamed folder keep theirs as well, so download links and App Hub apps keep working.
Uploads use the native file picker instead of a dialog of their own.
The Relay Server at /relay_server lists the relay sessions of the tenants you manage. A relay session forwards a single TCP port on a managed device, or on a host the device can reach, to a local port on your workstation, so you can open a Remote Desktop, SSH, web admin, or database connection to a machine that is not directly reachable from your network.
A session has three parties. The NetLock RMM Relay App runs on your workstation, signs in with a relay API key and opens a local port for each session it connects. The server holds the session and carries the tunnel. The agent on the target device opens the connection to the configured port, either on the device itself or on a remote host reachable from the device when the device acts as a jump host.
A session carries one TCP port and passes the bytes through unchanged, whatever the protocol (SSH, RDP, HTTP or another). UDP is not relayed.
Every session is stored in the database and keeps its session ID for as long as it exists. It survives a server restart, and the Enabled switch turns it off and on again.
Name: the session name, with its description beneath.
Device: device name, with the owning tenant name beneath.
Target: the port on the device, or host:port with "via device" for a jump-host session.
Protocol: TCP.
Status: one of the lifecycle states above.
Streams: connections currently carried through the tunnel, not the number of administrators. Click the count to see who is connected.
Enabled: switch. Turning a session off closes the connections that are open through it at once.
Actions: per-row controls.
The search above the table matches name, description, device, tenant, target host, port, protocol and status. Double-clicking a row opens the edit form.
Create relay session in the toolbar and Edit session on a row open the same form.
Fields, in order:
Target device: search by device name, tenant, location, group or internal IP. Only authorized Windows, Linux and macOS devices are offered.
Name: required, at most 255 characters. It is how the session appears on this page, in the Relay App and in the public API.
Description: optional, at most 500 characters.
Local port on target device or Remote host via target device (jump host): whether the agent connects to a port on the device itself or to a host on the device's network.
Remote host: jump-host sessions only: a hostname or IP address reachable from the device, without scheme, path or port.
Target port: a list of common services (RDP, SSH, HTTP, HTTPS, VNC, MySQL, PostgreSQL, and others), or any port from 1 to 65535 in the field below it.
Protocol: TCP, the only supported protocol.
Administrators allowed to connect: see below.
Enabled: edit only.
A new session is enabled. If the target device's agent is connected, it shows Ready to connect straight away; otherwise it shows Device offline until the agent connects.
Changing the route. Target device, local port or remote host, port and protocol make up the route of a session. When you save a change to any of them, every connection that is open through the session is closed, and the next connection goes to the new target. The session ID stays the same, so the Relay App keeps the local port and the auto-connect setting of the session. The connection tool it last opened the session with ("Open with") is kept too, so check it after moving a session to a different service, for example from RDP to SSH. Changing only the name, description or administrators leaves open connections running.
Changing the route needs relay_server_add in addition to relay_server_edit. Without it, the route fields are disabled and a note in the form says why; name, description, administrators and the enabled state can still be changed.
Every session carries a list of accounts that may open a tunnel through it. The list only decides who may connect; who may see and change the session follows the relay_server_* permissions and the tenant scope. The picker offers the accounts that hold relay_server_enabled and are assigned to the tenant of the target device. When a session is moved to a device in another tenant, accounts that are not assigned to that tenant are removed from the list. A session with nobody on the list exists, but nobody can connect to it.
The Relay App lists the sessions your account may connect to. Each session is one line: its name (or the device name while it has none), the device, target, protocol and tenant beneath, the status, and a Connect or Disconnect button. Click the arrow or the name to expand an entry. It then shows the description, session ID, local endpoint, organization, throughput, Copy and Open with, and the settings for the local port, auto-connect and tool commands. Entries start collapsed, and the app remembers which ones you expanded. The search matches name, description, device, session ID, organization and port.
When a session is changed, turned off or closed in the console while you are connected, the Relay App disconnects and shows the reason.
The Relay App signs in with a relay API key. Manage API Keys on the Relay Server page lists the keys of your account, and Connection tools holds the command templates behind "Open with"; both need relay_server_manage.
A web access session is a temporary relay session the server opens when an operator uses Web interface on the devices page (see Chapter 3.7). Instead of a Relay App, the server itself is the client of the tunnel: it fetches the device's web pages through the agent and serves them to the operator's browser under https://<server>/relay/web/<session>/…. The session appears in the list with a Web chip next to its name, its target as https://host:port, and the account that opened it as its creator.
What is different from a regular session:
It is not created here and cannot be edited. The devices page decides device, host, scheme and port when it is opened.
The Enabled switch is not available. The session ends by itself after 15 minutes without a request or WebSocket traffic, after 8 hours at the latest, or when it is closed here. Closing the browser tab does not end it.
Close session is offered to the account that opened it and to accounts with relay_server_delete. Closing ends the tunnel and removes the session.
The Streams count and the connections dialog show the server as the connected party, named after the account that opened the session and marked Web interface.
The Relay App never lists it, and it is not part of the public API's relay sessions.
Sessions do not survive a server restart; the tab then shows that the session has ended.
The server passes the device pages on unchanged, except for the base address a page declares (<base href="/">, common in Blazor, Angular and many single-page interfaces). The server moves it into the session address, so such pages load their relative addresses and client-side routes directly inside the session.
Device pages with self-signed certificates work. Redirects, cookies, absolute paths, Basic or Digest authentication and WebSockets of the device page are handled. Downloads and uploads are streamed without a size limit of their own.
A WebSocket the page opens on an absolute root path (wss://<server>/api/...) is forwarded to the session as well. With several device pages open in one browser, it goes to the session whose page was shown last. A socket whose handshake relies on a cookie the device set works only under the session address. Traffic through an open WebSocket counts as activity, so a page that only uses its socket is not ended as idle while it is in use.
Reverse proxy in front of the server. A web access session runs through the same public address as agents and the Relay App, so nothing has to be opened. Check these points on a reverse proxy of your own:
Requests to /relay/web/ and to any other path have to reach the server: device pages load their assets from absolute paths (/images/logo.gif), and the server redirects such requests into the session. A proxy that forwards only selected paths to the server breaks these pages.
Do not limit request bodies (nginx: client_max_body_size 0; proxy_request_buffering off;), or firmware and configuration uploads fail.
Allow long read timeouts for uploads (nginx: proxy_read_timeout 3600s;; Traefik: respondingTimeouts.readTimeout=24h on the entry points, as in the documented docker-compose). Traefik v3 stops reading a request after 60 seconds by default.
Pass X-Forwarded-Proto so the session cookie is marked Secure behind TLS termination. The documented Traefik setup does this already.
Allow WebSocket upgrades to the server. Traefik does this by default. nginx needs the Upgrade and Connection headers passed on the location that reaches the server (proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; with the usual map $http_upgrade $connection_upgrade block), and its proxy_read_timeout applies to a quiet socket as well.
The server accepts devices that only support TLS 1.0 or 1.1 or old cipher suites. If the OpenSSL policy of the server image refuses such a handshake, the tab shows "The device did not answer" with the TLS reason. In that case, lower the OpenSSL security level of the server container for that device class.
Website Uptime Monitoring at /website-uptime-monitoring watches external URLs from the server side. The server sends HTTP requests to each configured target at an interval, evaluates the response against a set of rules, and raises events when thresholds are breached. Use it for public-facing sites, customer portals and any HTTP endpoint whose availability or performance matters as seen from outside the device fleet.
Checks run on the server. No agent is involved, so a monitor sees the target from the server's network, not from inside a customer's LAN. This matches how an external visitor reaches a public site. For internal-only URLs, consider a device-side sensor instead (see Chapter 8.3).
Monitors: the list of configured targets, their current status, and the add / edit / delete controls.
Details: historical timeline for a selected monitor: response time, DNS lookup time, SSL certificate, and content-check results over the chosen window.
Incidents: the chronological list of raised incidents across all monitors, with start time, duration, and the reason that triggered the incident.
Each monitor performs a single HTTP request per interval and evaluates the response in several ways:
HTTP status. A target has an Expected Status Code (default 200). Anything else is a failure.
SSL certificate. If SSL monitoring is enabled, the monitor inspects the certificate chain for valid-from and valid-to dates, the issuer, subject, and thumbprint. Expiry raises a warning at the configurable warning-threshold days and critical at the critical-threshold days. The monitor keeps one entry per certificate it has observed, with the date it was first seen, the issuer, subject, validity and thumbprint; the public API lists these entries.
Response time. The monitor records round-trip time, time-to-first-byte, and the DNS lookup time of the request in milliseconds. A configurable threshold raises a Degraded status when exceeded.
Content presence. With content monitoring enabled, the monitor checks the response body for a configured Keyword and for a configured CSS Selector. Either missing raises a content error.
Defacement detection. When enabled, the monitor stores a SHA hash of the response content and alerts when the hash changes unexpectedly.
The outcome of each check is written to the monitor's history and, where thresholds are breached, produces an event under the Uptime Monitoring type (see Chapter 12.2).
The monitor dialog is organised into seven sections:
General: Tenant, Name, URL, Enabled.
HTTP Settings: HTTP Method (GET, POST, HEAD, PUT) and Expected Status Code.
Intervals & Timeouts: Check Interval (default 300 s, range 30 to 86400 s), Timeout (default 30 s, range 1 to 120 s), and Retry Count (default 3, range 1 to 10).
Redirects: Follow Redirects and Max Redirects (default 5).
SSL Monitoring: enable, warning threshold days (default 30), critical threshold days (default 7).
Content Monitoring: enable, Keyword, CSS Selector, and the Defacement Detection hash toggle.
Performance Thresholds: Response Time Alert (default 2000 ms), Load Time Alert (default 5000 ms), and SLA Target (default 99.90%).
Notifications: per-channel checkboxes for Email, Microsoft Teams, Telegram, ntfy.sh, and Webhook. Each channel must be configured in Settings → Notifications first.
The same dialog covers add and edit; the title changes based on which action opened it.
The Incidents tab lists all raised incidents in time order. An incident starts when the first failing check crosses its threshold and closes when the target recovers. Each row shows the triggering reason (for example Down, SSL Error, Degraded), the monitor, the duration, and the recovery time.
Access is granted for the whole page; there are no separate add / edit / delete flags. Tenant scoping applies through the standard tenant-list permission.
Port Scanner at /port-scanner scans a manually configured list of targets for open TCP ports and compares the findings with an allowlist. Use it to detect changes on internet-facing hosts, such as a newly opened port, a forgotten staging service exposed to the internet, or a changed Server banner of a web server.
The Port Scanner is not available in NetLock Cloud; it is offered on self-hosted installations only.
Targets are added one at a time from the Custom Targets tab. Each target has a Tenant, Name, Host (hostname or IP address), and Description, plus an enabled/disabled toggle. The scanner only sweeps enabled targets.
The set of tested ports is global and applies to every target. The Ports tab lets you add a port (1–65535), give it a Name (the service label shown against findings), and a Details field for notes. Each port can be enabled or disabled. A disabled port is skipped during scans but kept in the catalogue for later.
To review one target, filter the results by the Target column.
The Whitelist tab is the allowlist. A whitelist entry has Tenant, Name, Host (or * for any host), Port (or 0 for any port), and Description. A finding that matches a whitelist entry is treated as expected and is not reported as a finding on the Scan Results tab.
Use * host plus a specific port for "this port is always OK to be open anywhere", and a specific host plus 0 for "any port being open on this host is OK".
The Ticket System turns NetLock RMM into a lightweight helpdesk. Tickets capture requests and incidents raised by end users or ingested from email, carry a status through to resolution, and record every action on the ticket. The module has its own contact list, its own SLA engine and its own history log on each ticket. Ticket changes are not written to the Events log; creating, changing, assigning and deleting a ticket is also recorded in the Audit log (entity type ticket).
Operators work on three pages: the Tickets list at /tickets, Time Tracking at /tickets/time-tracking, and Statistics at /tickets/statistics. Configuration sits under the same menu group (Departments, Customers, Contacts, Templates), with dialogs for Labels & Types, SLA, and per-department Webhooks. Global defaults live on Settings → Ticket System.
The module is off by default. An operator sees the Tickets menu only when two conditions are met: the module must be turned on globally, and the operator must hold the tickets_enabled permission.
The master toggle is at Settings → Ticket System on the General tab, labelled Ticket System Enabled. One other setting on the same tab applies deployment-wide:
Blocked File Extensions: a chip input with one file extension per chip. Attachments with these extensions are stripped from inbound email before the ticket is created, and an internal note on the ticket names the files that were blocked. Extensions are normalised to lowercase with a leading dot, so .EXE, exe, and .exe all match.
Ticket numbers are not configured here. They come from the prefix on the customer record when the ticket belongs to a customer that sets one (see 10.11), and otherwise from the built-in default numbering, which produces identifiers such as TKT-12345678.
The Settings page itself is gated by settings_system_enabled. The two extra tabs on the same page (Labels & Types and SLA) manage the same data as the dialogs reachable from inside a ticket.
Route: /tickets. The list opens on the Open tab by default, refreshes every 60 seconds in the background, and shows a toast whenever a new inbound email or reply arrives on a ticket the current user can see.
The list carries nine columns: Ticket #, Subject, Contact, Status, Priority, Last Contact (direction badge plus a relative time), SLA (a colour-coded urgency chip), Updated, and Assigned To. Drag a column header to change the column order. The order is stored in the browser's local storage, so it is kept across sessions in the same browser but is not shared between machines.
Six tabs sit above the table: All, Open, In Progress, Waiting, Resolved, Closed. Each tab shows a live count for the current filter set; switching tabs swaps the underlying query but preserves filters, search, and column order. On the All tab, closed rows are dimmed.
Five filter dropdowns narrow the query:
Department: All Departments or a named department. Users without tickets_view_all_departments see only their own department regardless of this control.
Priority: All, Critical, High, Medium, or Low.
Assigned To: All, Unassigned, or any operator by username.
Type: options drawn from Labels & Types (see 10.14).
Label: All or any colour-coded label.
Filters combine. A single search field searches Ticket #, Title, Contact Email, Contact Name, and the Assigned To username at once.
Selecting one or more rows reveals a toolbar with Close Selected, Delete Selected, and Deselect All. Close Selected moves every chosen ticket straight to Closed without asking for a closing comment. To record one, use the detail dialog (see 10.4). Delete Selected is gated by tickets_delete and deletes the tickets permanently.
Clicking a row opens the ticket detail dialog. Its title shows the ticket number followed by a coloured chip for the current status. The body is a six-tab editor: Conversation, Details, Time Tracking, History, Attachments, and AI.
The Conversation tab is the main working area. A toggle at the top switches between Chat View (bubbles with alternating alignment) and List View (a denser CRM-style list). Both render the same messages in chronological order.
Every message carries a direction badge that also determines its styling:
Internal note: left-aligned, tinted for internal use, marked with a lock icon. Not sent to the customer.
Outbound: right-aligned, tinted blue, with an arrow-out icon. A public message; it is mailed to the contact through the department's SMTP when the ticket has a department with an SMTP server and a valid contact email (see below).
Inbound: left-aligned, tinted green, with an arrow-in icon. Ingested from the department's IMAP mailbox.
A note added through the public API keeps its line breaks when it is plain text and is shown formatted when it contains HTML; see X.9.18.
A composer sits at the bottom of the tab with three editor modes: Rich Text, HTML, and Plain Text. Regardless of mode, both a rich-text rendering and a plain-text fallback are persisted, so replies display correctly for recipients that strip HTML. A lock/globe icon toggles the outgoing message between Internal note and Outbound before sending, and a Template Picker button inserts a saved response (see 10.13); the text stays editable after insertion.
A public reply is mailed with the department and contact email saved on the ticket. When it cannot be mailed, a hint above the editor names the reason before you send: the ticket has no contact email, the contact email is not a valid address, the ticket has no department, or the department has no SMTP server. If you changed Support Department or Contact Email on the Details tab without saving, a second hint asks you to save first; until then the reply still uses the saved values. After sending, the result is shown and recorded in the History tab:
Mailed: Reply sent.; history Reply sent to <address>.
Not mailed: a warning; history Reply saved, not mailed: <reason>. On a ticket from the tray icon the reply is still shown on the device (Reply sent to the device.).
Sending failed (SMTP error): a warning naming the address; history Reply saved, mail to <address> failed. The cause is in the error log, module Tickets.EmailService.
Files attached with Attach are stored on the ticket and mailed with a public reply under their original names. Files with a blocked extension (see 10.2) are neither stored nor mailed. If the attachments of one reply exceed 20 MB together, the reply is mailed without them, a warning says so and the history reads Reply sent to <address> without attachments (too large); the files remain on the Attachments tab. A single file can be up to 25 MB.
The Details tab exposes every metadata field on the ticket:
Title.
Status: Open, In Progress, Waiting, Resolved, or Closed.
Priority: Low, Medium, High, or Critical.
Assigned To Operator.
Support Department.
Contact Name: read-only when a contact is linked; edit the contact on the Contacts page to change it.
Contact Email: an autocomplete-searchable input when editable. If the entered email has no matching contact, a Create Contact action appears next to it, so the operator can create one without leaving the dialog.
Type: a clearable dropdown.
Labels: multi-select with the colour of each label previewed inline.
Created / Source: captions rather than editors. Source reads Manual for tickets created from the UI and Email for tickets ingested from a department mailbox.
Edit rights split across two flags. Every field on this tab except Assigned To Operator is gated by tickets_edit; the assignee dropdown alone is gated by tickets_assign. A user who can reassign but not edit sees every other field disabled and the assignee dropdown live.
The per-ticket Time Tracking tab opens with an alert reporting the state of the auto-timer: when the department has automatic time tracking enabled (see 10.10), opening this ticket starts a timer, and the timer pauses after the department's configured idle timeout.
A collapsible Add Entry form books time manually with Date, Start Time, End Time (24-hour clock), and Notes; Duration is computed read-only. Below the form, a table lists every entry on the ticket with User, Date, Start, End, Duration, Rounded (reflecting the department's rounding step), Notes and a Delete action. A footer shows the raw and rounded totals.
The History tab is the ticket's own audit log. Every status change, assignee change, field edit, and comment addition appends an entry automatically. Each row captures the author, the date and time, the field that changed, and the old and new values. Ticket changes do not appear in /events; the Audit log records them with less detail (see 10.17).
The Attachments tab lists every file attached to the ticket (on a comment, as an inbound email attachment, or by direct upload) in a single table with File Name, Size, Type (MIME), Uploaded By, Date, and Actions.
Every attachment offers Download. A second action, View, appears for text-like types (.txt, .log, .json, .xml, .csv, and anything with a text/* MIME) and renders the file in an inline viewer so operators can read logs, JSON, or XML without leaving the dialog.
The AI tab is present only when the AI module is enabled globally (see Chapter 13). It offers Summarize Ticket, which produces a short summary of the conversation so far, and a free-form question field for chat-style Q&A scoped to this ticket. Output renders in paper-style cards. Both features use the provider and model configured in the AI & LLM settings.
A ticket moves through five statuses: Open, In Progress, Waiting, Resolved, and Closed. Any status can change to any other, so an operator can move a ticket from Closed back to Open in a single step.
Three routes lead to Closed:
Change Status to Closed on the Details tab and save.
Open the Close Ticket confirmation. It asks for an optional Closing Comment, which is stored as an internal note on the ticket.
Select rows on the list and use Close Selected in the bulk toolbar. This route does not ask for a closing comment.
Closing a ticket never deletes it. Closed tickets remain visible in the Closed tab and in All, slightly dimmed. To reopen a ticket, set Status back to Open or In Progress and save. The Reopened Tickets metric on the Statistics page tracks how often that happens.
Tickets can also be closed automatically by a scheduled sweep; the per-department Cleanup settings control how long a ticket must be inactive before it is closed (10.10).
The New Ticket button on the list opens the create dialog. Creation is gated by tickets_create.
One field is required: Title. Submitting an empty title raises a Title is required validation error. Every other field is optional:
Department: preselected with the department chosen in the list's Department filter, otherwise the first department you are a member of, otherwise None. A ticket without a department has no mailbox, no auto reply and no notification recipients, and its contact cannot be mailed, so pick one when department notifications or mails to the contact are expected. A ticket created through the public API (POST /v1/tickets, departmentId optional) behaves the same.
Priority: defaults to Medium.
Contact: autocomplete over existing contacts; typing searches name, email, and company.
Contact Email: can be entered directly without selecting a contact. A contact can be created later from the detail dialog using Create Contact on the Details tab.
Assigned To: the initial assignee.
Type.
Description: the operator's description of the request. If provided, it is stored as the first comment on the ticket as an Internal note authored by the creator; it is never mailed to the contact.
Notify contact by email: off by default. Available when the selected department has an SMTP server and Contact Email holds a valid address; otherwise the checkbox is disabled and a line below it names what is missing. When checked, a Message to the contact field appears and must be filled.
Only this message is mailed: through the department's SMTP, from its From Address, with the ticket title and number as subject (<Title> [TKT-…]) and your e-mail signature appended. It is stored as an Outbound comment, and the contact's answer to the mail is added to the ticket like any reply that reaches the department's mailbox. If the mail cannot be sent, the ticket is still created; a warning names the address and the history reads Message to contact to <address> not sent, see the error log (otherwise Message to contact sent to <address>).
A ticket created through the public API (POST /v1/tickets) also gets its description as the first comment, styled as Inbound and authored by the contact, or by the token's account when no contact is named.
Creating the ticket auto-fills the following:
Ticket #: generated from the customer's prefix plus a sequential number when the matched contact belongs to a customer that sets one, otherwise from the built-in default numbering.
Source: Manual (Email is reserved for tickets ingested from a mailbox).
Status: Open.
Created Date and Created By: set from the current session.
SLA: if the contact's email resolves to a customer with an SLA attached, the SLA's deadlines are computed and stored on the ticket.
The ticket_created webhook fires on save (see 10.16).
The form has no device field. Tickets reach devices through the contact: a contact can have linked devices in their tenant, and those devices appear on the Details tab once the ticket is saved. See Chapter 3 for the device side of that linkage.
End users can open a ticket from the tray icon of their device when the device's policy enables it (Policy Settings → Tray Icon → Support tickets, Chapter 6.5). The tray menu then carries a Support entry that opens a small window: the user describes the problem, optionally picks a category, a type and how urgent it is, gives a name and an e-mail address, adds a screenshot or a file and sends the request. The ticket number is shown right away. A request that cannot be sent (device offline, server unreachable) is kept as a draft on the device and sent again with the same request id, so a retry never files a second ticket.
Such a ticket is filed into the department chosen in the policy with Source = Tray and carries what the console would otherwise need entered by hand:
Requested from device and Windows user on the Details tab: the device (linked to its page for accounts that may open it) and the Windows account (DOMAIN\user) that filed the request. The account is determined by the agent on the device, not entered by the user.
Customer: the customer of the device's tenant, or the one fixed in the policy. A tenant without a customer gets one created, named after the tenant.
Contact: matched by the e-mail address inside that customer, otherwise by the device and the name, otherwise created; the contact is linked to the device.
Created By = Tray Icon, the opening message as the first comment (Inbound), the history entries created and requester.
Attachments uploaded from the device are stored in the database rather than on the console's file system; the Attachments tab shows them with a database icon and downloads them like any other.
The department's auto reply, notifications, webhooks, SLA and automation rules apply as for any other ticket; the auto reply is sent to the user's e-mail address by the console's reminder service through the department's SMTP settings. In the tickets list a computer icon in front of the title marks a ticket from a device.
What the user sees on the device: only the tickets created from that device under their own Windows account, with the public conversation. Internal notes are not sent to the device. Under My tickets the user reads the public replies, answers them (which reopens a resolved or closed ticket like an e-mail reply) and can mark the ticket as solved (Resolved, with a system comment). Resolved, closed and merged tickets stay visible on the device for 30 days. Which of these options the window offers, whether an e-mail address is required and every text of the window come from the policy.
A ticket's Assigned To Operator is set manually by default: an operator with tickets_assign picks an assignee from the dropdown. Round-robin or weighted distribution is not available.
The only automated path to an assignee is Auto-assign on open, a per-department switch on the Departments admin page. When enabled, an unassigned ticket of that department is assigned to the first operator who opens it in the web console; opening the detail dialog triggers the assignment.
Who is assigned: an operator with both tickets_edit and tickets_assign who can see the ticket (an account with tickets_view_all_departments, or a member whose department view is the ticket's department). Read-only accounts open the ticket without taking it.
Which tickets: only open tickets (Open, In Progress, Waiting) without an assignee. Resolved, Closed and Merged tickets and tickets without a department are never assigned this way. Tickets created, read or changed through the Public API, the tray icon or the mailbox poll are not assigned either; only opening in the web console counts.
Several operators at once: when two operators open the same ticket at the same moment, exactly one becomes the assignee.
What it records: the operator sees a short notice, the history shows the change of the assignee, the audit log records it, and the department's webhooks and notification mails report it like a manual assignment (ticket_updated and ticket_assigned).
Auto-assigned flag: the ticket is marked as auto-assigned (Public API field and filter autoAssigned). Any later change of the assignee, in the console or through the Public API, clears the mark. A ticket that is set back to unassigned is assigned again the next time an operator opens it.
SLA escalation sends notifications and webhooks and does not change the ticket. Tickets under an SLA carry a deadline and the list shows the current urgency as a coloured chip. When the deadline crosses a warning threshold the department's Notifications fire sla_warning, and on breach they fire sla_breached. Those events drive email notifications and webhooks (10.16). Tickets whose SLA is at risk are not reassigned automatically.
Route: /tickets/time-tracking. The page is a single-day calendar showing every time entry across every ticket the operator can see.
A vertical 24-hour timeline runs from midnight to midnight with half-hour gridlines. Entries are rendered as coloured rectangles positioned by their start and end times. The colour encodes origin: manual entries are blue, automatic entries (booked by the auto-timer) are green. On today's view, a red indicator tracks the current time.
A sidebar lists the same day's entries in chronological order with a delete button on each row. Navigation across days uses Previous, Next, a date picker, and a Today shortcut.
Each entry records Date, Start Time, End Time, Duration (computed), Rounded Duration, and Notes, plus an internal flag noting whether it was booked manually or automatically. The rounded duration applies the department's Rounding (minutes, 0 = exact) step; with 0 the rounded value equals the raw duration.
Automatic tracking is driven by three department settings:
Idle Timeout (minutes): after this many minutes without activity on the ticket, the timer pauses. The next interaction resumes it as a new entry.
Confirm Timeout (minutes): after this many minutes, the operator is prompted to confirm they're still working on the ticket. Without a confirmation the current entry stops.
Rounding (minutes, 0 = exact): the increment the Rounded Duration snaps to.
The page has no export; aggregate figures are on the Statistics page.
Route: /tickets/statistics. The page is a tabbed dashboard covering activity over a chosen time window.
A filter row at the top controls scope for every tab: a date-range picker (defaulting to the last 30 days), plus Department, Customer, and Operator dropdowns, and an Apply button that re-runs the query.
Five tabs group the metrics by category:
Overview: volume and quality indicators across the whole scope: totals, per-status counts, average resolution and first-response times, SLA compliance, priority and source breakdowns, busiest day and hour, reopens, and so on.
Departments: one row per department with the key volume and SLA figures.
Customers: one row per customer with volumes, hours, and SLA compliance.
Operators: one row per operator with workload and outcome figures, plus an operator-by-customer hours matrix.
Route: /tickets/departments. Departments are the organisational and technical unit of the ticket system. They carry their own mailbox, their own notification recipients, their own time-tracking behaviour, their own webhooks, and their own membership list.
The list columns are Name, Description, IMAP Server, SMTP Server, Members, Last poll, Enabled, and row-level actions. Last poll shows the result (Success, Partial or Error) and the time of the latest mailbox poll; for a failed poll, hovering over it shows the cause, for example a refused certificate or a failed sign-in.
The create and edit dialogs share the same field set, grouped into sections:
General: Name, Description, IMAP Server, IMAP Port, IMAP Username, IMAP Password, SMTP Server, SMTP Port, SMTP Username, SMTP Password, From Address, From Name, Enabled, and Auto-assign on open.
TLS certificate validation (in the General block, below the SMTP fields): the setting applies to both the IMAP and the SMTP connection of the department, for polling, replies, automatic replies, follow-up reminders and the mailbox search alike:
Full validation (recommended): the server certificate must be issued by a trusted authority, be valid and carry the server name entered in the dialog.
Encrypt, but ignore a host name mismatch: as full validation, but the certificate does not have to carry the server name. Use it when the server is reached under an internal name.
Encrypt, accept any certificate: the connection is encrypted, the certificate is not checked.
In the first two modes the web console also checks whether the certification authority has revoked the certificate. For that it downloads the authority's revocation list over HTTP (port 80) from the address named in the certificate. If that address cannot be reached, the connection is still made and a warning is written to the web console log, at most once per server and hour. A certificate the authority has revoked is always refused.
Test connection signs in to the IMAP and the SMTP server with the values currently in the dialog, saved or not, and opens the inbox read-only; no mail is read or sent. Both servers are tested, also when the first one fails. The result for each server stays below the button until the next test and names the cause of a failure, for example an untrusted, expired or revoked certificate, a failed sign-in or a server that cannot be reached. A success with a warning means the revocation list could not be downloaded (see X.3.6).
Auto-Reply Email: Subject, Body (HTML), and an enabled toggle. Two placeholders resolve at send time: {{ticket_number}} and {{subject}}. Fires once per new ticket created from an inbound mail or from the tray icon of a device (tickets created in the console use Notify contact by email in the New Ticket dialog instead); sent through the department's SMTP settings and marked as an automatic reply (Auto-Submitted) so out-of-office and other automatic responders do not answer it.
Follow-Up Reminder Email: Send after X days without reply, Subject, Body (HTML), and an enabled toggle. Fires once per ticket when the customer has not replied for the configured number of days.
Time Tracking: Idle Timeout (minutes), Confirm Timeout (minutes), Rounding (minutes, 0 = exact), and an enabled toggle. Drives the auto-timer described in 10.8.
Cleanup: Close tickets inactive for (days), Auto-close tickets with these statuses (checkboxes for Open, In Progress, and Waiting), Internal note added to auto-closed tickets, Delete closed tickets older than (days), and Also delete attachment files from disk.
Notifications: Notification Recipients (comma-separated email addresses) plus an event-checkbox list: Ticket Created, Ticket Updated, Ticket Closed, Ticket Assigned, Comment Added, SLA Warning, SLA Breached, and Auto-Closed. Each selected event sends a plain-text email to every listed recipient.
These mails are sent through the global e-mail settings under Settings > Notifications > E-Mail, not through the department's mailbox. Without global e-mail settings nothing is sent, and a ticket without a department sends nothing. The sender name is Tickets | NetLock with the global From address. Events raised through the public API are notified as well.
Each notification mail carries the headers Auto-Submitted: auto-generated and X-NetLock-Ticket-Notification: <event>. A department mailbox that receives such a mail leaves it unread and does not turn it into a ticket or a comment. A recipient may therefore be the department's own mailbox, though a separate address is the cleaner setup.
Webhooks: a Manage Webhooks button opens the webhook dialog scoped to this department. See 10.16.
Members: a multi-select of the operators in this department. Membership combines with tickets_view_all_departments to determine who sees which tickets.
Email ingestion is per department. Each department polls its own IMAP mailbox; inbound messages create tickets in that department, and outbound replies are sent through that department's SMTP. To accept mail for several addresses, set up several departments. Deletions are hard deletes.
Every mail NetLock RMM sends carries the ticket number in square brackets in the subject, for example Re: Printer offline [ACME-000123]. With that number, an incoming mail becomes a comment on the existing ticket instead of a new ticket. These rules apply:
The number has to be in square brackets. The part before the last hyphen is the prefix, the part after it has to be at least six digits, the length of every generated number. Numbers of the built-in default numbering (TKT-…) are recognised with or without brackets.
A prefix that belongs to a customer is tried before one that does not, and within each group the number closest to the end of the subject comes first. A prefix a customer has since renamed therefore still resolves, as long as the ticket itself is still there.
The ticket has to be reachable from the mailbox that received the mail: it belongs to the polling department, or the sender is the ticket's contact address, or the sender is a contact of the ticket's customer.
If the ticket was merged into another one, the mail is added to the ticket the conversation was merged into.
In all other cases, for example with a rewritten subject, a deleted number or a number that matches no ticket, the mail creates a new ticket. Replies stay on their ticket as long as the subject is left intact, as common mail clients do when replying. With logging enabled, each mail that does not match writes one line to debug.log naming the reason. NetLock RMM's own notification mails, recognised by their X-NetLock-Ticket-Notification header, are the only messages the poll leaves untouched; every other unread mail is imported.
Route: /tickets/customers. Customers are the company records of the ticket system. The detail page at /tickets/customers/details edits one customer in depth.
List columns: Company, Tenant, SLA, Prefix, and a contacts count. Creating a customer uses the Add Company dialog with these fields:
Company Name.
Address.
Linked Tenant: the RMM tenant this customer maps to. The linkage scopes which devices can later be attached to the customer's contacts.
SLA: picks an entry from the SLA library; see 10.15.
Ticket Number Prefix: gives this customer's tickets their own numbering, PREFIX-000123. If it is empty, the customer's tickets use the default TKT- numbering. Use something short and recognisable, such as ACME.
Notes.
The customer detail page lets an admin edit the same fields and also shows the company's departments, contacts, and tickets in one place, with device links attached to each contact visible inline.
Warning: Deleting a customer is a hard delete with cascade. All departments tied to that customer, all its contacts, and the device links on those contacts are removed permanently. Remove customers only when you are sure they are gone for good.
Route: /tickets/contacts. Contacts are the individual people tickets are tied to. Every ticket references a contact; the contact in turn belongs to a customer, which is how the customer's SLA and prefix reach the ticket.
List columns: Last Name, First Name, Email, Phone, Position, Company, Department, and a linked-devices count. Create and edit fields are First Name, Last Name, Email, Phone, Position / Role, Company, Department, Notes, and Linked Devices. Device linking is a multi-select that is available only after a company is chosen. The device list is limited to the devices of the company's linked tenant.
Contacts are also maintained inside the customer detail page. The flat /tickets/contacts page is an alternative view of the same records, convenient when you are looking for one person without knowing which customer they belong to. Deletions are hard deletes.
Route: /tickets/templates. Templates are saved responses reusable across tickets. List columns: Name, Type (Email or Ticket), Subject, Author, Date, and an actions column.
Create and edit fields are Name, Type, Subject, and Body. The body editor offers the same three modes as the ticket composer (Rich Text, HTML and Plain Text). Both a rich-text rendering and a plain-text fallback are stored, so the message displays correctly in any mail client.
The Type field reflects where the template is meant to be used: Email templates for outbound replies, Ticket templates for internal notes and descriptions on newly created tickets. Both types appear in the Template Picker; the type only helps to organise templates.
The Template Picker is available from the ticket composer and from the new-ticket dialog. Picking a template populates the subject and body of the composer and leaves both fully editable. Deletions are hard deletes.
Labels and Types are managed in two places: a Labels & Types dialog reachable from the ticket detail dialog and from the Settings area, and a Labels & Types tab on Settings → Ticket System. Both edit the same data.
Labels are colour-coded tags. Each label has a Label Name and a Color chosen from a hex picker. A ticket can have several labels; the label picker on the Details tab is multi-select. Labels do not affect routing or SLA behaviour. They help you filter and categorise the list.
Types are single-value categorisations. Each type has a Type Name and a Description. A ticket has at most one type.
Note: Types are user-defined. NetLock RMM does not ship a pre-configured list, and in particular does not provide the ITIL set (Incident, Service Request, Change, Problem) out of the box. Define whatever set fits your workflow.
Deleting a label or type is permanent and has no confirmation prompt.
SLAs are managed from an SLA Management dialog and from the SLA tab on Settings → Ticket System. Both edit the same records.
List columns: Name, Response (h), Resolution (h), Priority Override, Description, and an actions column.
Each SLA carries:
Name.
Response Time (hours): the deadline for the first outbound response to the customer.
Resolution Time (hours): the deadline to reach a resolved status.
Priority Override: one of None, Low, Medium, High, or Critical. Acts as a minimum priority: tickets under this SLA cannot drop below the override.
Description: free text.
SLAs attach to customers on the Customers page (see 10.11). When a ticket is created from a contact of that customer, the SLA's response and resolution deadlines are computed from the creation time and stored on the ticket. The SLA chip in the list changes through ok, warning, critical, and breached colours as the deadline approaches.
Note: SLA timers are wall-clock hours. Business hours are not taken into account: a 4-hour response time means four real hours, including nights and weekends. Set the thresholds accordingly.
SLA timer changes trigger notifications and webhooks through the sla_warning and sla_breached events. Deletions are hard deletes.
Requires permission:tickets_manage_departments to reach the department form, and tickets_manage_webhooks for the webhook dialog and everything in it.
Webhooks are configured per department, not globally. From the department edit form, Manage Webhooks opens the webhook dialog, which lists the department's webhooks and offers create, edit, test, and delete actions.
Each webhook has the following fields:
Name: shown in the list.
Description: free text.
URL: required; the endpoint the request is sent to.
Method: one of GET, POST, PUT, DELETE, or PATCH.
Request Body: a JSON document edited in an embedded Monaco editor, with placeholder substitution at send time.
Request Headers: a JSON object edited in Monaco. Defaults to {"Content-Type": "application/json"}.
Events: zero or more trigger events. Selecting none means the webhook fires for every event.
Enabled: toggle.
Sign requests: off by default. When on, every request carries the header X-NetLock-Signature, computed over exactly the body it sends after the placeholders were replaced. Switching it on generates a secret and shows it once; Rotate secret on a saved webhook replaces it at once. The header name is reserved and cannot be set under Request Headers. Slack, Microsoft Teams, Discord and ntfy ignore signatures. X.10 shows how a receiver verifies them.
The eight event triggers are ticket_created, ticket_updated, ticket_closed, ticket_assigned, comment_added, sla_warning, sla_breached, and auto_closed.
Ten placeholder tokens are substituted in the request body: {{ticket_number}}, {{subject}}, {{status}}, {{priority}}, {{assigned_to}}, {{customer}}, {{department}}, {{event}}, {{timestamp}}, and {{url}}.
{{url}} is the link to the ticket in the web console. It is built from the Public console URL under Settings → Overview. While that setting is empty, {{url}} is replaced by nothing and the webhook is sent without a link; the dialog shows a notice in that case.
The dialog pre-populates new webhooks with the following default body. Adjust it to the shape your integration expects.
A Test action sends a single request filled with sample placeholder values; {{url}} behaves as in a real delivery, so it stays empty without a public console URL. Before sending, the dialog validates that the URL is well-formed and that the body and headers parse as JSON, so a misconfigured webhook fails at save time rather than at the next real event.
Email: per department. The Notification Recipients list and the Notify on these events checkboxes decide who is emailed and for which events. Notifications go to staff recipients through the global e-mail settings (Settings > Notifications > E-Mail) and require a department on the ticket.
The auto reply and the follow-up reminder go to the contact through the department's own SMTP settings, and only for tickets raised by mail or from the tray icon of a device, not for tickets created in the console or through the API. A ticket created in the console reaches its contact only through Notify contact by email in the New Ticket dialog and through public replies; the API never mails the contact. Replies to customers also use the department's SMTP and require a department with an SMTP server and a contact email on the ticket.
In-app toasts: a live notification service pushes toasts to the Console on new tickets, replies, and updates. Tickets and replies that arrive from the tray icon of a device are announced the same way as an inbound mail.
Device notice: for a ticket opened from the tray icon, a public reply or a change to Resolved or Closed is announced on the device within seconds while it is online (a small notice for the Windows user who filed it, if the policy allows it); otherwise the tray icon picks it up at its next check. Internal notes are never sent to the device.
Unread counter: the Tickets entry in the navigation carries a badge showing unread ticket activity for the current user.
Webhook delivery is a separate channel, covered in 10.16.
Notification mails carry an Open ticket line with the link to the ticket while a Public console URL is set; without one the line is left out and the rest of the mail stays the same.
A link opened without a session leads to the sign-in page and, once the sign-in is complete including a second factor or a forced password change, to the ticket. An account without access to the ticket system ends on its usual start page. The ticket itself opens only for an account that may see it: its department has to be visible to the account, and a ticket of a tenant has to belong to one of the account's tenants; otherwise the page says the ticket does not exist or is not visible.
Where the e-mail channel logs: Logging → Web Console Logs, files error.log and debug.log, module Tickets.NotificationMailDispatcher; every skipped or failed send writes one line naming the reason. Events raised through the public API log on the server instead, module Public_Api.Ticket_Notification_Mail_Dispatcher. See A.9 — Logging & protocols for the log files.
Note: Ticket changes do not appear in /events. The ticket's History tab records every change field by field; the Audit log records ticket actions under entity type ticket.
For wider context on how each notification channel is configured (SMTP, Teams, Telegram, Ntfy, webhooks), see Appendix A.8.
Chapter 3 — Devices covers how devices are added to tenants. Contacts in this module link to those devices, which is how tickets reach the managed estate.
Appendix A.8 — Notifications deep dive documents each notification channel (SMTP, Teams, Telegram, Ntfy, webhooks) in detail. The department Notifications section chooses which events fire; A.8 covers how each channel is configured.
On the Reports page at /reports you build, schedule and distribute reports about the fleet, from a device inventory to a patch-compliance summary or a custom SQL breakdown of job outcomes. The page also hosts the community report templates and the brand templates that give generated PDFs a consistent look.
The Templates tab lists every report template you have access to. Two categories share the tab:
Built-in templates ship with the product and are flagged with a Built-in chip. A Show Built-in checkbox in the toolbar shows or hides them, so the list can be narrowed to your own templates.
Custom templates are created from the Templates tab's Create action, or by duplicating an existing template. They can be shared with other users via the Share Template dialog. A community template becomes a custom template when you copy it from the Community tab (see 11.9).
Each template has an Author, a creation date, a description, and a list of widgets that define what the generated report contains. Templates are edited in the Report Builder (covered next).
The Report Builder at /reports/builder (and /reports/builder/{id} when editing an existing template) is where a template is authored. A template is a sequence of widgets; the Builder is the editor for that sequence.
Each widget is backed by a data source: a SQL query that produces the rows the widget shows. The Builder offers two modes for authoring that query: the Visual Query Builder and direct SQL. Both need SQL access (see below); the statements of the built-in templates run without it.
The Visual Query Builder is the default mode. It shows the query as a set of form controls:
Table: the table to select from. The list contains exactly the tables the MySQL user for SQL access can read.
Columns: the columns to include in the result, from the columns that user can read.
Fn: aggregate function applied to a column. The supported aggregates are COUNT, SUM, AVG, MIN, MAX, and DISTINCT.
Joins: a list of joins, each with a join type, a right-hand table, and an ON condition.
Where: the filter conditions, composed with AND / OR logic. Supported operators: =, !=, <, >, <=, >=, LIKE, IN, IS NULL, IS NOT NULL.
Logic: per-clause grouping between conditions.
Op, Value: the operator and right-hand side for each condition.
Order-by and limit controls complete the query.
Filter by the report's tenants: on for a new query. The Builder adds the tenant condition for the base table: t0.tenant_id IN (@tenant_id) for a table with a tenant_id column, t0.device_id IN (SELECT id FROM devices WHERE tenant_id IN (@tenant_id)) for a table with a device_id column, and the same through access_key for a table with an access_key column. The condition stands first in its own parentheses; your own conditions follow in theirs. A table without any of these columns cannot be filtered by tenant, and the editor says so. On older widgets the switch is off; turn it on to filter them by tenant.
The resulting SQL is composed by the Builder and stored on the widget.
Own SQL (the SQL typed into the widget's SQL field and the SQL the Visual Query Builder generates, including the SQL of text parameters) runs only over a dedicated MySQL user that the administrator creates and enters under Settings → SQL access (/settings/sql-access). The grants of that user are the boundary of what such SQL can read. Setting it up is described in Set up SQL access for reports, dashboards and custom fields. On cloud instances SQL access is not available.
With SQL access configured, the Widget Editor offers the Visual Query Builder and the SQL field to every user who may create or edit the template (reports_create / reports_edit). In the SQL field you type the query directly, for queries the visual builder cannot express. On save, each own statement is checked with EXPLAIN over the report user: syntax, tables and columns it may read. When MySQL refuses the statement, its message is shown and the template is not saved. Queries run in a read-only transaction with a limit of 10 seconds per statement; user variables such as @rownum := @rownum + 1 are allowed.
The built-in templates and unchanged copies of them, imported ones included, run without SQL access. A changed or new statement needs SQL access, and so does a copy whose built-in statement an update has changed.
Without SQL access:
own widgets show SQL access not configured instead of data (in generated output [SQL access not configured]);
the Widget Editor shows a notice with a link to Settings → SQL access and offers neither the Visual Query Builder, the SQL field nor the AI SQL Assistant;
saving or importing a template that contains own SQL is refused.
The AI SQL Assistant button drafts a query from a natural-language description. The AI only writes into the editor; you still review and run the query yourself.
Placeholders. A query, including the SQL of a text parameter, may use these placeholders:
@date_from and @date_to are bound as parameters to the date range the report runs for.
IN (@tenant_id) is replaced, when the report runs, by the list of tenant ids the report is generated for, for example WHERE d.tenant_id IN (@tenant_id). Only this exact text is replaced: IN(@tenant_id), in (@tenant_id) or = @tenant_id stay as they are. For tables without a tenant column, filter through the devices of the tenants, for example e.device_id IN (SELECT id FROM devices WHERE tenant_id IN (@tenant_id)) or a.access_key IN (SELECT access_key FROM devices WHERE tenant_id IN (@tenant_id)). A widget whose SQL does not carry the placeholder in this form is left out of reports for selected tenants (see 11.10); the Widget Editor and saving point this out and offer the correction.
@scope_unassigned is replaced by 1=1 in a report over all tenants and by 1=0 in a report for selected tenants. It is for rows that belong to no tenant, for example audit entries with an empty tenant: ((@scope_unassigned AND tenant_name = '') OR tenant_name IN (SELECT name FROM tenants WHERE id IN (@tenant_id))). The built-in audit reports use it.
@patch_scope is replaced the same way by the scored predicate of the compliance scope of Patch Management → Settings (see 7.4): sources, update types, severities, approval state, grace period and the exclusion of Defender security intelligence updates, evaluated at the time the report runs. It expects the update catalog devices_available_updates to be joined with the alias dau and stands where a condition stands, for example ... WHERE du.status = 'Available' AND @patch_scope. The built-in patch reports use it, so their compliance figures match the patch management page and GET /v1/patch-compliance. A query that carries @patch_scope without the dau alias fails with an unknown-column error; the placeholder is case-sensitive.
For the EXPLAIN check on save, IN (@tenant_id) stands in as IN (0), @patch_scope and @scope_unassigned as 1=1, and @date_from / @date_to are bound.
Both modes store their output in the same widget field, so a template can mix widgets authored in either mode.
Tip: Start in the Visual Query Builder. Switch to direct SQL only for what the visual builder cannot do, such as window functions, user variables or custom field values. A Visual Query Builder query is easier to read, review and hand over.
A report is a sequence of widgets. Each widget is one of four types:
Metric: a single number with a label. Use for headline figures: total devices, open incidents, unpatched criticals.
Chart: a plotted series. Bar, line, and pie presentations are available depending on the widget configuration.
Table: a tabular display of the rows the data source returns. The usual choice for inventory-style reports.
Text: static markdown content, rendered in place. Use for narrative explanations, section headers within a report, or preamble paragraphs. The text can carry {{tenant_name}}, {{tenant_company}}, {{date_from}} and {{date_to}} (see 11.10) and the {{key}} of its text parameters; a text parameter with one of these keys keeps its own value.
Each widget is authored and edited in the Widget Editor dialog. The dialog is divided between the widget's data source (handled via either the Visual Query Builder or direct SQL, as described in 11.3) and its presentation, with the controls for the chosen widget type (axes, colours, column order, label text). The data source controls are shared across all widget types except Text, which is purely markdown and has no query.
Brand templates at the Brands tab define how a generated report looks, independent of what it contains. A brand wraps the content of any template with a cover page and footer consistent with a specific customer, MSP unit, or product line.
The Brand Template dialog accepts:
Company info: company name, address, contact details.
Colours: primary and secondary colours used on the cover page and in section headers.
Logo: the image shown on the cover page and (scaled) in the footer.
Header text: the text line at the top of each generated page.
Footer text: the text line at the bottom of each page.
Custom fields: a list of key-value pairs rendered as cosmetic footer entries on the PDF cover page.
Show custom fields in footer: a switch that controls whether those custom fields are rendered.
Important: The Report Builder does not offer Custom Fields as a data source, and the Visual Query Builder has no dropdown for them. In Reports, Custom Fields appear in one place only: as cosmetic key-value pairs on brand template footers.
To show Custom Field data in the body of a report, for example a table of devices and their Asset Tag custom field, write direct SQL against the underlying tables. This needs SQL access (see 11.3).
A brand template is attached to a report template via the Report Builder. One brand can back many templates; a template with no brand uses the default styling.
The Schedules tab lists scheduled runs; each row attaches a template to a cadence and a distribution method. Schedules are created from the Schedule dialog.
Scheduled runs deliver through one of two channels:
Email: the schedule carries a Recipients field (comma-separated addresses), a Subject, and a Body. The rendered report is attached to the message. Send to the report contacts of the tenant also sends each report made for one tenant to the report contacts of that tenant (see 11.10), in a mail of its own.
Webhook: the schedule carries a URL, an HTTP Method (GET, POST, PUT, DELETE, PATCH), Request Headers as JSON, Request Body as JSON, and an Attach File toggle. When Attach File is on, the rendered report is sent as a multipart attachment; when off, only the request body is sent. A schedule that produces one report per tenant calls the webhook once per report.
Subject, body and the webhook request body can use {{tenant_name}}, {{tenant_company}}, {{date_from}} and {{date_to}}; in the webhook body the values are escaped for a JSON string.
The distribution is set per schedule, so the same template can back one email schedule and one webhook schedule.
While a run produces its reports, the schedule shows running. The next run is set when a run starts. A server that stops in the middle of a run therefore does not start the same run again and sends no report twice. After the next start, such a run shows failed with a note, and the reports it had not produced yet are missing for that period. When some reports of a run fail and others succeed, the status is failed with n of m tenants failed and their names.
The Generate action on any template opens the Generate Report dialog for a one-off run.
Fields:
Template: pre-filled from the row you clicked.
All tenants / Tenants: the tenants the report covers; all tenants by default (see 11.10).
Reports: with several tenants, One report per tenant (the default) or One combined report.
Format: PDF, HTML, CSV, or JSON.
Date range: the same options as scheduled delivery.
Email: optional; if filled, the generated file is emailed to that address. Leave it blank to only produce the file (it appears on the Generated tab). With Also send to the report contacts of the tenant, a report made for one tenant also goes to that tenant's report contacts. Every recipient gets a mail of its own.
The Community tab of the Reports page lists report templates curated by NetLock. They are read-only. Each row offers two actions:
Generate: make a report from the community template directly.
Copy to my templates: create a custom template from it.
Copied templates are normal custom templates that you can edit, schedule and delete. Report templates cannot be published to the community from the console.
A report can be made for one customer (tenant), for several, or for all tenants, on demand and on a schedule.
Choosing the tenants. The Generate Report dialog, the Schedule dialog and the preview of the Report Builder offer All tenants and the tenants that exist. With several tenants, One report per tenant makes a separate report for each of them; One combined report makes one report over all of them. On demand, one report per tenant is limited to 25 reports per run and the files are downloaded as one ZIP file. A schedule over All tenants (including new ones) with one report per tenant also covers tenants created after the schedule was saved. Tenants being deleted are left out.
What the customer sees. A report for one tenant names it on the cover page and in the PDF header as Customer: Company (Name) (the company only when it is set), and in the HTML, CSV and JSON output. The file name is <template>_<tenant>_<date>_<time>.<extension>. A report over all tenants names no customer.
Widgets that do not filter by tenant. A report for selected tenants (anything other than all tenants) leaves out every widget whose SQL does not carry IN (@tenant_id) exactly (see 11.3), so it never shows data of other customers. The Templates tab marks such templates with Partly tenant-filtered, the Generate and Schedule dialogs name the widgets before the report is made, and after an on-demand run the dialog lists what was left out. In a report over all tenants every widget runs.
Templates that describe the whole instance. A template marked Whole instance (for example Policy Assignment Overview, which lists every policy) is generated over all tenants only, as one combined report. Copies of it are treated the same way.
Built-in templates. The built-in templates filter by tenant. Update Approval Status Report counts the updates pending on the authorized devices of the report's tenants (each update once, however many devices it is pending on), also in reports over all tenants. The audit reports (Admin Activity Audit, Configuration Change Audit, Device Authorization Audit, the change history of Policy Assignment Overview) include entries without a tenant (logins, settings changes) only in reports over all tenants. The failed logins of Remote Access Audit are left out of reports for selected tenants.
Report contacts. Each tenant can carry a list of report contacts in its tenant settings (Chapter 4.3). A schedule with Send to the report contacts of the tenant sends every report made for exactly one tenant to that tenant's report contacts, in a mail of its own, so they do not see the other recipients. Combined reports over several tenants are not sent to report contacts. Addresses in Recipients (for example your own team) receive every report.
Text variables. Text widgets, mail subject and body and the webhook body can use {{tenant_name}} (the tenant's name; All tenants over all tenants; the names when a report covers several tenants), {{tenant_company}}, {{date_from}} and {{date_to}} (yyyy-MM-dd).
Generated tab. The Tenants column shows the tenants each report covers (All tenants, a tenant, or the first tenant and +n); a tenant deleted since appears as Deleted tenant #id. The tenant filter in the toolbar shows the reports of a tenant, including reports over all tenants. Reports made for one tenant only are deleted together with that tenant; a deleted tenant is removed from the selection of a schedule, and the schedule is switched off when no tenant is left.
Accounts with access to some tenants. An account without access to all tenants (Chapter 14.5) chooses among its own tenants; All tenants is not offered, and all of its tenants are selected at the start. Generated reports and schedules that cover other tenants, or all tenants, are shown with a lock; the account cannot download, change or delete them. A schedule reports on no more than the tenants of the account that created it, at the time of each run; a schedule whose creator was deleted, or has none of its tenants, does not run.
Tip: One report per tenant multiplies the work of a run by the number of tenants. Schedule large per-tenant runs outside working hours.
Running the Generate Report dialog, including the choice of tenants.
reports_schedules
Creating or managing schedules, including their tenants.
reports_brand_templates
Managing brand templates.
Own SQL and the Visual Query Builder additionally need SQL access, configured under Settings → SQL access by an account with settings_sql_access (see 11.3).
See Appendix X.2 for the full permission catalogue.
Chapter 8.4 — Custom Fields covers where Custom Fields live in the product and how to read their values via SQL when you need them inside a report body.
NetLock RMM keeps two separate logs, each answering a different question.
Events answers "what happened on the devices?": antivirus detections, job outcomes, sensor breaches, uptime-monitor failures, port-scan findings, device online/offline transitions.
Audit answers "what happened in the console?": who logged in, who changed a policy, who approved a patch, who deleted a user.
Events is the operational log and can be filtered by severity and device. Audit is the administrative log and can be filtered by user and entity type. Events can be marked as read and exported. Audit entries cannot be deleted in the console.
The table shows which log receives each kind of record:
Source of the record
Logged in
Antivirus events from Microsoft Defender on a device
Events
Job execution outcomes on a device (scripts, deployments, policy pushes)
Events
Sensor threshold breaches from a device
Events
Website uptime-monitor checks
Events
Port Scanner findings
Events
Device online / offline transitions
Events
SNMP discovery results reported by a device
Events
Output of a completed classic remote shell command (the command text is not stored)
Events
Application Control / Device Control block attempts on a device
Events (also on dedicated Blocked tabs, see 12.5)
Login success, login failure, logout
Audit
Any create / update / delete through the console
Audit
Permission or role change on a user
Audit
Script executed from the console
Audit (+ Events from the device side when the script runs)
Export of a list to JSON or HTML
Audit
Authorizing or deauthorizing a pending device
Audit
Script execution writes a record to both logs. The Audit entry records that a console user started the run (action execute on entity type script). The device writes the Events entry after the script finishes (event type job), with the outcome and any output. Check both to follow a run from start to result.
Application Control and Device Control blocks appear in Events and on their own Blocked tabs (see 12.5).
Timestamp of the event: the time the server received it. Events from agent 3.3.0.6 or later also carry the time they were created on the device; the details dialog shows it as Occurred (device), and the export has it as its own column.
Tenant
The tenant the event's device belongs to.
Location
The location under the tenant.
Device
The device that produced the event.
Reported By
The source subsystem: antivirus, job, sensor, uptime monitor, port scanner, SNMP discovery, remote shell.
Events are categorised by type. The Type filter lists eleven of them. Device uptime events have no dropdown entry:
UI label
Source
Notes
antivirus
Antivirus detections and signature updates from Microsoft Defender, plus Application Control and Device Control block events. All three share this type.
Distinguish the source by the Reported by field: Application Control [...] / Device Control [...] for block events.
Website uptime monitor state changes: Down, Recovered, Degraded.
Controlled by the Show website uptime events checkbox in addition to the filter dropdown.
Port Scanner
Open ports discovered by the Port Scanner.
Controlled by the Show port scanner events checkbox in addition to the filter dropdown.
SNMP Discovery
Results of an SNMP network discovery run, reported by the agent that ran it.
Also listed on the device's Events tab.
Remote Shell
The output of a completed classic remote shell command: Remote shell command executed. with author, source (web console or public API token), run-as user, shell and the output, cut at 64 K characters. The command text is not stored.
Written for commands from the Remote Shell dialog, the Bulk Remote Shell dialog and the public API run-command / run-script actions; the real-time shell writes no events. Not sent to notification targets. Also listed on the device's Events tab; an event retention rule of this type prunes it.
Patch management
Events the agent raises about its scheduled patch runs and about the package managers behind application updates, for example a scheduled run held back by an outstanding restart, or winget is not usable from the agent's system account.
Also listed on the device's Events tab. Agents up to 3.3.0.11 report the winget event with the type job.
Device authorization
A device's authorization changed: a new device awaiting authorization, a reinstalled agent, the license limit, or a changed hardware ID (the device stays authorized in that case). Written by the server for each matching server sensor of the kind Unauthorized device, with that sensor's severity and channels; Reported by reads Device authorization.
A device connected from a country outside the server list of the country restriction, was refused by it, or changed its country. Written by the server for each matching server sensor of the kind Device country, with that sensor's severity and channels; Reported by reads Device country.
A device or an address was blocked by rate limiting on the server, or would have been blocked in observe mode. Written by the server at every block start, with the device or address, the request class, the reason, the measured rate against the limit, the level and the duration; Reported by reads Rate limiting. Severity high for an enforced block, moderate for one recorded in observe mode.
Never sent to a notification channel or as a push. A device block is listed on the device's Events tab as well; an address block names no device and is shown only to accounts with access to every tenant. Throttling alone writes no event.
(no dropdown entry)
Device uptime: online / offline transitions.
Visible with the default filter; no dedicated checkbox.
The Show website uptime events and Show port scanner events checkboxes are independent of the Type dropdown. If you pick Uptime Monitoring from the Type dropdown, the events are shown regardless of the checkbox state. A type selected in the dropdown takes precedence over the checkboxes.
Jobs marked Hidden in their library entry (see Chapter 8.2) are excluded from the Events view at query time. No filter or checkbox shows them on this page. Use hidden jobs for background work that feeds Custom Fields or other non-operational data flows; use non-hidden jobs when you want the outcome surfaced here.
Clicking a row opens the Event Details dialog and marks the event as read. Below Date, the line Occurred (device) shows when the event was created on the device (agent 3.3.0.6 or later). The line is left out when the agent did not report a time, when the server wrote the event itself, or when the reported time lies more than 30 days before or more than 5 minutes after receipt (a wrong device clock).
The dialog has two tabs:
Monaco: the event content rendered in a Monaco code editor with syntax highlighting. Best for output that is JSON, XML, or otherwise structured.
RAW: the plain-text form of the same content. Use this when Monaco's highlighter guesses wrong or when you want to copy content verbatim.
When AI is enabled in Settings → AI/LLM, the dialog also shows the Analyze with AI button. It opens the AI chat with the event content pre-filled, so you can ask the model to explain the event without copying it.
Tenant scoping is applied through the standard tenant-list permission, so a user with access to tenants A and B will see events from devices in those tenants only.
A new entity is created (tenant, policy, script, job, and so on).
update
An existing entity is edited.
delete
An entity is deleted.
login
A user successfully logs in.
login_failed
A login attempt fails.
logout
A user logs out.
execute
A user triggers an execution, typically a script or deployment.
export
A user exports a list to JSON or HTML.
authorize
A user approves a pending device.
deauthorize
A user deauthorises an authorised device.
Some entries carry other actions, for example view when the Audit page is opened and adopt_reinstall when an unauthorized entry is adopted as reinstall of an existing device.
The Audit page offers no way to delete entries. You cannot remove individual entries, bulk-delete, or clear the log from the UI. Entries leave the log only through the audit log retention under Settings → Retention (see A.3).
Viewing the Audit log is itself audited. Opening the page writes an entry with action view on entity type audit_log, with the user and the source IP, so the log shows who has read it.
Retention is not configurable on the Audit page. The date-range picker filters what you see; it does not delete anything. Retention is a global setting under Settings → Retention (see Appendix A.3).
Clicking a row opens the Audit Details dialog. It shows the full record: date, severity, user, source IP, action, entity type, entity ID, entity name, tenant scope, and the formatted details payload. If the details field contains valid JSON, it is pretty-printed; otherwise it is rendered as plain text. The dialog has a single Close button.
A single console action often produces records in both logs. The table below maps common operations to the records they write. Use it to trace a change across both logs.
Action
Events record
Audit record
Automation causes a device to change policy
— (no event; see the device detail's Assigned policy field)
When the agent blocks an unknown application or USB device, the block appears in two places.
On the Events page. Each block is logged as an event. It shares the antivirus type with Microsoft Defender events, so the Type filter dropdown has no separate Application Control or Device Control entry. Selecting antivirus, or leaving the filter on its default, includes them. Identify them by the Reported by column, which reads Application Control [<mode>] or Device Control [<mode>].
On a dedicated Blocked tab. The same block also appears on a Blocked tab in Collections, where you can approve it:
Application Control blocks appear on the Blocked Applications tab of Manage Application Control Rulesets (see Chapter 8.6).
Device Control blocks appear on the Blocked Devices tab of Manage Device Control (see Chapter 8.7).
The Events entry records what happened, when, and on which device. On the Blocked tab you decide whether to whitelist the blocked item. Use Events to spot a block and the Blocked tab to act on it.
If the policy has tray-icon notifications enabled, the on-device user additionally sees a notification at the moment of the block. This is configured per policy (see Chapter 6).
Chapter 5 — Automations explains why automation-driven policy changes show up as update on policy rather than as events.
Chapter 6 — Policies covers what a policy edit actually changes, producing the update on policy audit entries referenced in 12.4.
Chapter 7 — Patch Management covers the approval workflow whose state changes surface as update on patch entries.
Chapter 8 — Collections documents the Collections features whose executions appear as job, sensor, and antivirus events, and whose block logs live in their own tabs rather than in Events.
Chapter 13 — AI Chat covers the chat that the Analyze with AI button on Event Details opens.
The AI Chat page at /ai-chat is a general-purpose AI assistant embedded in the console. You type a question and get an answer, as in any chat assistant. Typical uses are quick lookups, explaining log output, drafting a customer email, or checking a configuration choice before you make it.
The feature depends on three switches. Two are deployment-wide and live under Settings → AI/LLM, which also holds the model source and provider configuration: the Enable AI Features master toggle, and the AI Chat feature toggle that covers this page, the slide-in chat panel, and the chat button in the top bar. The third is ai_chat_page_enabled, a per-user permission for this page.
With AI switched off deployment-wide, the page shows the message "The AI provider has not been enabled. Ask your administrator to configure it under Settings → AI / LLM." and no conversation can be started. With ai_chat_page_enabled off, the page is not in the user's navigation menu.
The sidebar lists your past conversations. At the top:
New chat: starts a new conversation.
A search field with placeholder text Search conversations... that filters the list by title.
Below, conversations are grouped by recency:
Today
Yesterday
Last 7 days
Last 30 days
Older
Each conversation shows its title, the time of its last update, and an optional context badge when the conversation was started from another part of the console (for example, when you launched the chat from the Analyze with AI button on an event).
A header strip with the AI avatar, the conversation title, the optional context badge, and Rename and Delete controls.
The message area, with date dividers between different days.
Chat bubbles: your messages right-aligned, the AI's responses left-aligned with the AI avatar.
Markdown rendering for AI responses: code blocks, numbered and bulleted lists, tables, links and blockquotes.
A typing indicator while a response is being generated.
Streaming updates as each chunk of the response arrives, so the answer appears incrementally rather than all at once.
For questions about NetLock RMM itself, the answer is based on the product documentation that ships with the console. The model receives the documentation sections that match the question and cites them as [1], [2] and so on. The console turns those citations into a Sources line at the end of the answer, with links to the documentation pages used; the links open in a new tab.
Where a documentation section has a screenshot of the page in question, the answer shows it below the step it illustrates. The screenshot comes from the copy bundled with the console, and a click opens it in full size in a new tab.
If the documentation does not cover a question, the answer says so briefly and points to the online manual. General questions (scripting, operating systems, networking) are answered from the model's own knowledge without citations. The switch and the amount of documentation sent per request are set under Settings → AI/LLM; see A.11.5.
The Delete Conversation dialog asks for confirmation. Deletion is permanent: the conversation and all its messages are removed. The dialog is titled Delete conversation and needs one click to confirm.
File types: text-based only. More than 40 extensions are allowed: plain text, Markdown, source files across the major languages, YAML, JSON, XML, INI, CSV, logs, and configuration formats. Binary formats are not accepted.
File size: 10 MB maximum per file.
Files per message: up to 10 files can be attached to a single message.
When you send, the content of each attached file is prepended to your message with markers so the AI can tell where each file starts and ends:
--- Attached file: {name} ({size}) ---{file contents here}--- End of {name} ---
The full content is sent without truncation, up to the 10 MB per-file limit. Very large prompts can exceed the provider's token limit; the response then shows an error.
Click an attachment chip in an existing message to open the Attachment View dialog, which shows the file name, a size label, and the full content as it was sent. Use it to check what was sent to the AI.
The AI Assistant button in the Scripts editor (see Chapter 8.1 — Scripts) is a separate integration. It sits in the Add Script and Edit Script dialogs, has its own inline panel, and writes directly into the script editor.
AI Chat cannot save its output to the Collections library. To keep a script the AI drafted, copy its code from the conversation, open the Scripts library, and paste it into a new script.
The AI Assistant buttons on the Automations dialogs, and the Widget Editor's AI SQL Assistant are integrations of their own, each tied to its page. The Analyze with AI button on Event Details opens the AI chat with the event as context.
The chat does not show the configured provider, model name or parameters. They are set under Settings → AI/LLM (see Appendix A.11) and are visible only to users with access to that Settings page. Ask your administrator which model answers.
AI Chat does not know your Scripts, Jobs, Sensors, Custom Fields, App Hub entries, Application Control rulesets or Device Control entries. It cannot look up a device, assign a policy or trigger a deployment. Use the relevant console page for these tasks.
Separate from the operator AI Chat page, NetLock RMM can give end users their own AI assistant in the agent's tray icon. It is enabled per policy and lets staff use AI under your control instead of pasting company data into an external chatbot.
How it works:
Opened from the tray. When enabled in the tray-icon policy, users open the chat from the agent's system-tray icon, without a separate app, browser or portal.
Encrypted history. Each user registers with a username (an email address by default) and a password. The conversation history is encrypted on the device with the user's password and stored encrypted; operators cannot read it. To answer, each message is passed through the NetLock server to the configured model. If the user forgets the password, the history cannot be recovered.
Relayed through the deployment's model source. Requests travel tray → agent → server → either the managed NetLock AI (hosted on IONOS AI Hub) or the provider configured for your own model, and are streamed back the same path. Which of the two applies is the deployment-wide Settings → AI/LLM model selection; see A.11.2.
Account control. New accounts are created inactive and must be activated by an operator, unless their tenant is set to auto-activate new accounts. Password rules and a required terms/privacy-acceptance step are configured per policy.
Token limits. Each account has an optional monthly token limit, and each tenant has an optional monthly cap that applies on top: when the tenant cap is reached, all of that tenant's users are blocked until the monthly reset, even if an individual user still has budget. Usage is shown as a percentage and can be reset per account.
Operators manage these accounts from the Customer AI dialog, reached from the Tenants list (all accounts the operator may see) and from a tenant's detail page (that tenant only, where the per-tenant cap and auto-activation are set). The dialog shows email, tenant, active state, token usage/limit, reset date, and per-period statistics. Conversation content is not shown. Access is gated by the enduser_ai_accounts permission and scoped to the operator's tenants.
The tray chat's title, labels, buttons and messages, and the username/email requirement, are configurable per policy. See Chapter 6 — Policies for the tray-icon AI Chat settings.
Per-user access to the AI Chat page. Users without this flag do not see the page in their navigation. The deployment-wide Enable AI Features and AI Chat switches under Settings → AI/LLM apply on top of it; when either is off, the chat page shows the disabled message regardless of per-user flags.
enduser_ai_accounts
The Customer AI dialog for managing end-user AI chat accounts: activation, per-user and per-tenant token limits, auto-activation, and statistics. Tenant-scoped.
See Appendix X.2 for the full permission catalogue.
The Users page at /users is where console user accounts are created, edited, and deleted. User accounts are the identities that sign in to the console, usually one account per technician.
Each account has a permission set and a tenant scope. The permission set is the matrix of flags described in 14.4. An account either follows a role (a named, reusable permission set managed under Users › Roles) or carries custom permissions of its own. The role defines what an account may do. The tenant scope (14.5) defines where, and it is always set on the account.
The role the account follows. An account with its own permission set shows a Custom chip; its tooltip names the role it was detached from, if any.
Tenants
The tenant access of the account: All for an account with access to all tenants, including tenants created later (14.5), otherwise the number of assigned tenants.
Mail Address
The account's email, for notifications and password-reset delivery.
Phone
Optional contact number.
Last Login
Timestamp of the user's most recent successful login.
IP Address
Source IP of the most recent login.
2FA
Activated or Deactivated.
Toolbar actions include Add (14.2), Roles (opens the roles page, 14.4, shown to accounts that hold roles_enabled) and Export data to JSON, CSV or HTML. The actions column of a row opens the user's settings page (14.3).
Double-clicking a row, or using the Manage action, opens the user's settings page. The list can be narrowed to the members of one role or to the custom accounts: the member count on the roles page opens the list with a filter chip. The close icon on the chip removes the filter.
Name: required. This is the username the user will log in with.
Password: auto-generated, 12 characters, read-only in the dialog. The Copy to Clipboard button copies the username and the password together, for example into your password manager.
Role: required, without a preselection. The list holds every role of the instance (14.4) and Custom (set permissions later). With a role the new account starts with that role's permissions and follows it; with Custom it starts without permissions. It can sign in but sees nothing until its permissions are set on the settings page.
Auth Mode: Password, SSO, or Password & SSO. Chooses how the user signs in.
Password: local password only.
SSO: single sign-on only; the local password is not used.
Password & SSO: either method works.
Access to all tenants: a switch. When it is on, the account has access to every tenant, including tenants created later, without a tenant list (14.5). The dialog pre-selects it when the chosen role can manage user accounts (users_enabled, users_manage and users_edit together, which the Administrator role always holds); a hint under the switch says so, and it can be switched off. For every other role and for Custom it is off, and the new account starts without tenants: assign them on its settings page. An account with users_edit can change the permissions and tenants of every account, including its own. Give it to administrators only.
Submitting the dialog creates the account. The password is stored hashed, never in plain text, and the new account is flagged for mandatory password change on first login. When the user first signs in, the console forces them to pick a new password before anything else.
Tip: Keep the dialog open until you have captured the generated password. Once the dialog closes, there is no way to retrieve that initial password from the UI. If you miss it, use the Reset Password flow (14.6) to generate a new one.
User Settings at /user_settings is the full editor for a single user. It is reached from the Users list via double-click or the Manage button.
The page is divided into sections:
Account details: username, email, phone, authentication mode and the enabled switch.
Tenant scope: the Access to all tenants switch and the table described in 14.5, at the top of the permissions tab.
Role: the card described in 14.4 under Roles on the account page.
Permissions: the matrix described in 14.4.
2FA: the switches described in 14.6.
Actions: the Reset Password and Delete buttons described in 14.6 and 14.8.
A Save button at the top or bottom of the page commits every edit on the page in one step; unsaved changes are kept in the browser until you save or navigate away.
A role is a named permission set stored on the instance. The roles page at /users/roles (reached through the Roles button of the Users list) lists every role with its description, its type, the number of accounts that follow it, its author and when it was last changed.
One role is built in: Administrator. It always holds every permission the console knows, including permissions added by a later update, and it cannot be renamed, edited or deleted. It can be duplicated and exported like any other role. After an update from a version before 3.3.0.5, accounts that held every permission follow Administrator, and all other accounts keep their permissions as custom permissions.
Add opens the Add Role dialog: a name (unique on the instance), a description and a Start from template that pre-fills the matrix. A role created from a template is an ordinary role that you can change freely:
Template
Contents
Empty
No permissions.
Administrator
Every permission, for "everything except ..." roles.
Technician
Devices, scripts, patching, remote tools and tickets in full; no user, role or instance settings, no tenant creation, no secrets.
Helpdesk
View devices, remote control and remote shell, restart, wake, sync, App Hub, tickets; no policies, scripts or deletions.
Read-only
Every page in view mode; no changes, no remote tools, no secrets.
Reporting
Dashboards, reports, events and audit in view mode.
Duplicate on a role opens the same dialog with Copy of <role> selected; the new role is then opened for fine-tuning.
The role page at /users/roles/{id} holds the name, the description, the number of accounts that follow the role (with a link to that list) and the permission matrix. A saved change applies to every account that follows the role at that account's next page load. Nobody has to sign out. The built-in role is shown read-only.
Export writes the role as a JSON file (role_<name>_<timestamp>.json) with a format marker, the name, the description and the permission object. Import on the roles page reads such a file back as a new role: the dialog previews the name, the number of granted permissions and any keys it does not know (they are ignored), and proposes <name> (imported) when the name is taken. A permission template file (a plain permission object without a name) is imported the same way; the dialog asks for the name.
A role is deleted from its row or from its page after a confirmation. The built-in role cannot be deleted, and neither can a role that accounts still follow. Reassign those accounts first (the member count links to them).
The permissions tab of User Settings carries a Role card between the tenant table and the matrix:
The Role select holds every role and Custom. While the account follows a role, the matrix shows that role's values read-only; picking another role previews its values the same way. The binding is written when the page is saved.
Customize permissions (shown while the account follows a role) detaches the account in the page: the matrix keeps the role's values and becomes editable, and the save writes them as the account's own permissions. The list then shows the account as Custom, with the previous role in the tooltip.
Save as new role (shown for a custom account, needs roles_add) stores the current matrix as a new role and, by default, binds the account to it right away.
Reset to role (shown for a custom account that was detached from a role) puts that role back into the select.
Custom permissions are never changed by a role. A change to a role reaches only the accounts that follow it.
At least one account must be able to manage users: the last enabled account that holds users_enabled, users_manage and users_edit cannot be disabled, deleted, bound to a role without those three permissions, or saved without them. The page shows the reason next to the affected controls, and the save refuses the change with the same message. Apart from this rule, you can edit your own account like any other.
The permission matrix is a set of sections, each introduced by a parent switch. The parent switch turns the whole section on or off. Inside each section, child checkboxes control the individual functions of the section. When the parent switch is off, its child checkboxes are disabled. Their values are kept and take effect again when the parent switch is turned back on.
The pattern is the same in every section, so you can turn off access to a page without losing the child settings you made for it.
The top-level sections in the matrix, in the order they appear:
Devices: access to the Devices list, and per-tab / per-tool child checkboxes covering General, Software, Task Manager, Antivirus, Events, Updates, Remote Shell, Remote File Browser, Remote Control, Remote EventLog Viewer, Remote Registry Editor, SNMP Tools, Shutdown, Reboot, Wake On LAN, Force Sync, Deauthorize, and Move.
Tenants: create / manage / edit / delete for tenants, plus analogous children for Locations and Groups.
Automations: add / edit / delete for automation rules. See Chapter 5.
Policies: add / manage / edit / delete for policies. See Chapter 6.
Patch Management: access to the /patch-management page. See Chapter 7.
Collections: a section per sub-feature: Antivirus Controlled Folder Access, Application Control, Device Control, Sensors, Scripts, Jobs, Custom Fields, App Hub, Software Deployment, and File Server. Each has its own child checkboxes for add / edit / manage / delete as applicable. See Chapter 8.
Relay Server: access to the Relay Server page and the manage / add / edit / delete children.
Website Uptime Monitoring: page access.
Port Scanner: page access.
Events: page access.
Audit: page access.
Users: the Users list plus add / manage / edit / delete children, and the Roles block with the roles page switch plus add / edit / delete children.
Reports: page access plus Create, Edit, Delete, Generate, Schedules, and Brand Templates children.
Tickets: optional module; add / edit / delete / assign plus the manage-section children (departments, templates, SLAs, and so on).
Settings: sub-sections for every settings page. Notifications have per-channel children (Mail, Microsoft Teams, Telegram, ntfy.sh, Webhook, App) with add / test / edit / delete; Overview, Licensing, Maintenance, Updates, Database, Retention, API tokens, Remote Screen, IP Whitelist (the IP whitelist and country restriction tabs of the Security page), Rate limiting, SSO, Sessions, Whitelabeling, Globalization, Custom Fields, Dashboards, Reports, and AI/LLM all have their own section flags.
Every checkbox in the matrix corresponds to exactly one permission flag in the product. The flag names are the strings used throughout this documentation, for example devices_remote_shell, policies_edit, collections_scripts_add and reports_generate. See Appendix X.2 for the complete list.
A practical pattern: start from the template that comes closest (Read-only for an observer, Technician for a hands-on operator), save it as a role, and adjust the children the role needs. Accounts that share a job then follow that role; an account that needs one exception is detached with Customize permissions, or gets a role of its own saved from its matrix.
At the top of the permissions tab sit the Access to all tenants switch and, below it, the Tenants table. The table lists every tenant of the instance with one checkbox per row. Ticking a tenant grants this user access to the devices, policies, events, and everything else scoped under that tenant.
Columns on the Tenants table: Name, Description, Author, Date, and Company.
Access to all tenants. With the switch on, the account has access to every tenant, including tenants created later, and the table shows every row ticked and not editable. The console and the server evaluate the switch at request time, so a tenant somebody else creates is visible to the account at once.
With the switch off, the ticked tenants are the scope. A user with tenants A and B ticked sees the devices, events, policies, jobs and other items of A and B. Everything in tenant C is hidden from that user, whatever page access (such as devices_authorized_enabled) their permission matrix grants.
The account stores both the switch and the list of tenant identifiers. While the switch is on, the list keeps the tenants of the last save and is ignored. When you switch it off, the list is editable and defines the scope again. Changes to the switch and to the tenant list are written to the audit log together with the permission changes of the save.
Accounts created before version 3.3.0.11 have the switch off. Turn it on, on the settings page, for every account that should have access to all tenants. Setting the switch needs users_add or users_edit, the same as ticking tenants.
A tenant created in the console or through the public API is added to the tenant list of the account that created it. The list of an account with the switch on is not changed.
Permissions and tenant scope apply together. To see devices in tenant A, a user needs the devices_authorized_enabled flag (permission to open the Devices page) and access to tenant A, through the switch or a tick in the scope table (permission to see anything in that tenant).
Two switches under the 2FA section of User Settings:
Two Factor Enabled: turns 2FA on for this user. With this switch on, the user is prompted for a second factor on every login.
Two Factor Remote Actions: a second, narrower switch that requires 2FA specifically for sensitive remote operations (remote shell, remote file browser, remote control, remote registry editor, and similar). Available only while Two Factor Enabled is on.
When Two Factor Enabled is first toggled on, the user is walked through 2FA enrolment on their next login.
A Reset Password button under the Actions section generates a one-time password for the user. The dialog shows the new password in a read-only field, with a Copy to Clipboard button for handoff, and sets the account back into mandatory-password-change state so the user must pick a fresh password on their next login.
Use this when a user has lost their credentials, or after the initial Add User dialog's generated password was not captured. If no account with users_edit can sign in on a self-hosted deployment, see Recover access to the Web Console.
Warning: The one-time password is visible on screen only once. After you close the dialog, it cannot be retrieved. Run Reset Password again if you need a new one.
The Users page has no impersonation and no password policy settings.
No impersonation. To test what another user sees, sign in as that user (with a password you reset for that purpose) or use a dedicated test account with the permissions you want to check.
No password policy configuration. Passwords generated on account creation and on reset always have 12 characters. Minimum length, complexity rules, rotation interval and password history cannot be configured.
The Delete button on User Settings opens the Delete User confirmation dialog. Deletion is:
Hard: the account is removed, not disabled, and cannot be restored.
Cascading to AI Chat: the user's AI Chat conversations and their messages are also deleted.
Audited: an audit entry delete on entity type user is written, including the deleted user's identifier and the admin who performed the deletion. See Chapter 12.3.
After deletion the console redirects back to the Users list.
Events, sessions, logins, and actions previously performed by the deleted user remain in the Audit log.
The public API (see Appendix X.9) uses the same model:
An account's role is an object with id, name and builtIn, or null for custom permissions, next to roleOrigin. From version 3.3.0.5, role is an object or null; before, it was a lower-case string.
GET /v1/roles lists the roles.
POST /v1/users accepts roleId. It needs the users:permissions:write scope because it grants permissions.
PUT /v1/users/{id}/role binds or detaches an account.
PUT /v1/users/{id}/permissions detaches a bound account.
The tenant access of an account is allTenants and tenants on the same endpoints, see X.9.7.
See Appendix X.2 for the full permission catalogue, including the flags referenced in the matrix throughout 14.4.
Chapter 12.3 — Audit documents the audit trail written by every create / edit / delete on user accounts.
Chapter 13 — AI Chat covers the ai_chat_page_enabled flag that appears under the AI section of the matrix, and the effect of deleting a user on their AI Chat conversations.
Community features are built into three areas of the console, each connected to the same Members Portal: a Scripts catalogue, a Reports catalogue and a Themes catalogue. The Console navigation has no separate Community entry.
Community Scripts and Community Themes offer four actions against their catalogue: browse, import into your local library, publish a local item to the community, and report an abusive or broken entry. Community Reports are read-only: you generate a report from a community template or copy it to your templates.
Community actions use the deployment's Members Portal API key, stored in the Console's settings. Users do not sign in to the community individually, and there is no separate community permission. Each action needs the permission of the page it sits on. For Community Scripts, publishing needs collections_scripts_edit (it starts from the script's edit dialog), withdrawing a published script needs collections_scripts_delete, and importing needs collections_scripts_add. Publishing a theme needs settings_whitelabeling_enabled. Without an API key the community actions do not work.
The gamepad icon in the app bar opens the Arcade, a picker with three mini games. Virus Defense is a tower defence in which security tools hold malware back; Kernel Panic is a first-person game in which an administrator clears a data center floor by floor; Overclock Rally is a racing game with a season of its own, driven on twelve circuits named after the parts of a data center. On phones the same entry sits in the overflow menu behind the three dots.
The games are an Easter egg. They need no permission beyond being signed in and have no route of their own; all three open as dialogs on the current page. High scores are kept in the browser that played them, per browser and per device, and are never sent to the server. The same is true of the progress Overclock Rally saves: its career, credits and best lap times are stored only in that browser and are deleted with its site data.
The Mini game checkbox under App bar icons in the whitelabel settings hides the gamepad icon and with it all three games; see Chapter A.6.
After an agent is installed it reports in to the Console but does not appear in the main Devices list. It sits in Unauthorized Devices until an administrator approves it, unless its installer authorizes devices automatically until a set date. This guide covers the approval step and the follow-up of giving the device a readable label. The prerequisite is a successful agent install; if the agent has not yet reported in, see Guide H.1 first.
One or more agents have registered and are visible at /unauthorized_devices.
You know which tenant, location, and group the device should end up in.
Required permissions: devices_enabled, devices_unauthorized_enabled and devices_unauthorized_authorize (also covers Adopt as reinstall). Editing the label needs no further permission.
In the Console, open Devices → Unauthorized Devices.
Find the new entry. Each row shows the device's hostname, operating system, and the tenant, location, and group the agent was configured against.
Confirm the row is correct. If the agent was configured for the wrong group, approve it and move it afterwards with Move devices on the Devices page (permission devices_move). A row with the chip Name already exists is most likely a device you already manage whose operating system was reinstalled: use the row action Adopt as reinstall instead of approving, so the existing device continues under the new agent and no duplicate is created (see Chapter 3.2).
Tick the row and click Authorize device above the table, or use the row action Authorize device. The entry disappears from the pending queue and the device appears in the main Devices list with status beginning to report in real time.
Find the new device in the Devices list. The default label matches the hostname (for example MARKETING-LAPTOP-01).
Double-click the device's label (or right-click the row and choose Edit label) and replace the machine name with something meaningful, such as Anna's laptop, Warehouse POS 3 or Reception desk. Save.
Tip: Labels appear throughout the Console: in the event feed, reports, the world map and the dashboard. A readable label makes reports easier to understand.
The entry does not appear in Unauthorized Devices. The agent may not have reached the server yet. Wait a minute and refresh. If it still does not appear, check the agent's service is running on the device and review Troubleshooting.
The entry reappears after approval. Another agent is registering against the same identity, or the same installer was run twice on the device. Inspect Events for the device to see each contact attempt.
The entry sits next to a device of the same name that is still authorized. The operating system of that device was reinstalled; the entry carries the chip Name already exists. Adopt it as reinstall instead of approving it, otherwise you end up with two devices.
Approved but no policy lands. Policy attachment runs through Automations, not through approval. Create or verify an automation whose condition matches the device's new group; see Guide H.4.
Whitelabeling lets you replace the NetLock RMM branding with your own. This guide walks through uploading a logo, tweaking a small set of palette colours, setting the browser-tab title, and optionally exporting the whole theme as a JSON file so you can reuse or share it.
Note:
Whitelabeling is deployment-wide, not per-tenant. All authenticated users see the same branding.
One logo is used for both light and dark mode.
Colours come in two palettes, 20 fields in light mode and 20 in dark mode (40 fields total), and both are always defined.
Most changes apply immediately after saving; the login-page palette may need a hard refresh.
Scroll to the colour-palette section. It has two identical blocks, one for light mode and one for dark mode, each with twenty fields.
Set at least these three in each palette for a coherent look:
Primary: the dominant brand colour.
AppBar Background: the top bar colour.
Text Primary: default body-text colour; make sure it contrasts well with Background.
Use the colour-picker widget next to each field, or paste a hex value directly (for example #FF0000).
Make the same three choices (or their dark-mode equivalents) in the dark-mode block.
Tip: If you only set light-mode values, users on dark mode see the stock dark palette. Both palettes are always defined; the mode toggle selects which one is shown.
Click the page's save action. An alert on the page states: Changes will be applied immediately after saving. The authenticated UI updates live. For colour changes the alert adds: The Login page may require a refresh to see the new colors. Reload the login page if you need to verify it there.
Click Export Theme. The Console produces a versioned JSON file (for example whitelabeling-theme.json) containing the title, the logo, login-page settings, both palettes, AppBar settings, and footer links.
Save the JSON somewhere safe. It is the only backup of your theme.
The page also has a Community Themes browser, where you can filter themes by category (Light Theme, Dark Theme, Corporate, MSP, Seasonal, Holiday, Other), preview them, and import one. Importing a community theme first downloads the current theme as a backup.
Logo upload rejected. Confirm the format is PNG or JPG and the size is ≤ 2 MB.
Login-page colours are stale. Browsers cache the login page aggressively. Clear the cache or hard-refresh.
Wrong brand in some views. Whitelabeling has no per-tenant scope. If you manage multiple customers as an MSP, the Console always shows your own brand to authenticated users; separate per-customer login portals are not available from this page.
Appendix A.6 — Whitelabeling & themes — full reference, including the import dialog, particle and fun-fact options, footer links, and community publish flow.
Applying configuration to a device in NetLock RMM is a two-stage task. First you build a policy that describes what should be enforced. Then you create an automation, a condition → policy rule, that routes the policy to the devices that should receive it. Policies reach groups, locations, and devices only through automations, and this guide walks through both stages.
At the end you will have one device running one policy, with evidence of the assignment in the device detail view and in Events.
At least one tenant, location, and group exists (see Guide H.3).
At least one authorised device is online in a group you intend to target (see Guide H.1 and Guide H.2).
Required permissions: policies_enabled, policies_add, policies_manage, policies_edit, automation_enabled and automation_add.
Note: A device receives at most one policy at a time. Policies do not layer, merge, or inherit. If two automations match the same device, the rule with the lower priority number wins.
On Manage Policies, click Add. In the Add Policy dialog enter a Name (for example Starter Workstations) and an optional Description. Save.
Click Manage on the new row to open the Policy Settings editor.
Step through the tabs you care about and tune settings. For a first pass the defaults on the Agent tab are usually fine; they set the sync interval and remote-control capabilities. See the full tab reference in Chapter 6 for everything you can configure. What end users get from the tray icon (the App Hub, the AI Chat and the chat request to the administrators) is switched on per policy on the Tray Icon tab (§6.5).
Save.
Warning: Edits to a policy apply in place and cannot be rolled back; policies have no templates or versions. Before making risky changes to an in-use policy, duplicate it first from the Manage Policies page and edit the copy.
Under If …: keep the condition type Group for the simplest case and pick the group this policy should apply to (for example Workstations). Add further conditions only if the policy should reach part of the group, for example Platform = Windows.
Under Then …: pick the policy you created in stage 1.
Priority: leave the proposed value (400 for a group rule). Check matching devices shows which devices the conditions match right now.
Confirm.
The server immediately re-evaluates the affected devices against the updated automation list and pushes matching policies. You do not need to wait for the next scheduled poll.
Tip: When several automations match a device, the one with the lower priority number wins; at the same number the rule with more conditions, then the older one. The dialog proposes a priority from the rule's most specific condition (device 100, internal IP 200, domain 300, group 400, location 500, tenant 600, otherwise 700), so a rule for a single machine beats a group rule by default. To reorder rules, change their priority numbers on the Manage Automations page.
The device shows - as assigned policy. No enabled automation matched the device and no default policy is set. Open the rule and use Check matching devices to see whether its conditions match the device; every condition of the rule has to hold. Alternatively, mark a default policy on the Policies page; it applies to every device that no automation reaches.
Wrong policy is assigned. Another matching automation has a lower priority number, or the same number with more conditions or an older creation date. Raise its number, narrow it, or give the rule you want a smaller number. A Device rule for a single machine gets 100 by default.
Policy saved but no events appear. Confirm the device is online in Devices. A device that is offline picks up the policy on its next sync. For persistent offline devices, see Troubleshooting.
Notifications in NetLock RMM are configured on a single page, Settings → Notifications, for multiple channels. This guide walks through the two most common: email via SMTP and Microsoft Teams via a webhook created in the Workflows app. You will configure the global SMTP server, add one email recipient, create the Teams webhook and add it as a connector, and run the built-in test for each.
You have SMTP server credentials for your environment, and you can receive mail at a test address.
For Teams, you are allowed to add a workflow to the target channel. Since Microsoft retired the classic connectors, the webhook URL comes from such a workflow. The first Teams step below creates it.
Required permissions: settings_enabled, settings_notifications_enabled; for the SMTP settings and their tests also settings_notifications_mail_smtp.
Open Settings → Notifications (route /manage_notifications).
On the tab labelled E mail, click SMTP settings to open the SMTP settings dialog.
Fill in:
Server: SMTP hostname.
Port: SMTP port.
SSL/TLS: tick if the server requires TLS.
TLS certificate validation: how the server certificate is checked. Full validation (recommended) requires a certificate from a trusted authority that is valid and carries the server name. Encrypt, but ignore a host name mismatch drops the name requirement, for servers reached under an internal name. Encrypt, accept any certificate does not check the certificate. In the first two modes the revocation list of the certification authority is downloaded over HTTP (port 80); if it cannot be reached, mail is still sent and a warning is written to the log. A revoked certificate is refused.
Username: SMTP authentication username. If this is not a valid email address, the dialog shows extra fields.
Password: SMTP password.
From address: if shown, the sender address the server will accept.
To address: if shown, a test-recipient address.
Optionally click Test connection to check server, port, encryption and sign-in without sending a mail. Then click Test. The Console sends a message with subject NetLock - Test Alert and body Test successful.. The result of either test is shown in a snackbar and below the buttons; a failure names its cause, for example a failed sign-in, a server that cannot be reached, or an untrusted, expired or revoked certificate.
Save. Saving requires a successful test, so a configuration that has not been tested cannot be stored.
Note: Only one SMTP configuration exists per deployment. Editing it replaces the previous configuration for every email recipient.
Microsoft retired the classic Office 365 connectors in May 2026. A channel's webhook URL comes from a Power Automate flow, and the Workflows app inside Teams creates that flow for you.
In Teams, open the channel that should receive the alerts.
Open the channel's … menu and choose Workflows.
Pick the template built on the When a Teams webhook request is received trigger. Teams lists it as Post to a channel when a webhook request is received.
Confirm the connection Teams offers, click Next, check that the team and the channel are the ones you want, and add the workflow.
Copy the URL the dialog shows. That URL is what NetLock RMM needs; you can read it again later by opening the workflow and expanding its trigger.
Back in the Console on the Notifications page, switch to the Microsoft Teams tab.
Click Add to open the Add Microsoft Teams Notification dialog.
Fill in:
Connector Name: a recognisable name for this channel.
Connector-Webhook-URL: the URL you copied in step 1. The value is masked once saved.
Payload format: Adaptive Card (Workflows webhook) for a workflow created as above. Pick Adaptive Card without envelope if you edited the flow so that it passes the request body straight into its Post card in a chat or channel action, and Plain text (legacy connector) only when the URL points at something other than Teams. See A.8.3.
On the new row in the Microsoft Teams table, click the row's Test action.
The Console POSTs a test message in the connector's payload format. A snackbar reports Successfully sent on pass or Failed sending: <error> on failure.
Open the Teams channel the workflow posts into and confirm the test message arrived. The webhook answers before the flow runs, so a successful send is not on its own proof that the message was posted.
The test reports that the revocation status of the certificate could not be checked. The mail server works; the Console could not download the revocation list of the certification authority. See X.3.6.
SMTP test fails with authentication errors. Re-check username, password, and whether your SMTP provider requires an app password or OAuth. For providers that allow only specific sender addresses, fill in From address to match.
Teams test succeeds but no message arrives. The webhook took the call and the flow failed afterwards. Open the workflow in Teams and read its run history: a failing Post card in a chat or channel step usually means Payload format does not match how the flow is built. Switch between the two Adaptive Card options. A workflow that is turned off, or an archived channel, produces the same result.
Teams test fails outright. The URL is wrong, or the workflow behind it was deleted. Create it again as in step 1 and paste the new URL over Connector-Webhook-URL. A URL on webhook.office.com belongs to a classic connector and does not work.
Events do not trigger emails after setup. Severity filtering is on the recipient record. An event below the recipient's severity threshold is filtered out without a message; lower the threshold temporarily to verify.
No messages for a specific tenant. Tenant scope on the recipient record acts as a filter. Add the missing tenant to Selected tenants or leave the scope empty to receive events from all tenants.
Microsoft Defender Antivirus settings for managed Windows devices live inside a policy, under the Windows tab. This guide shows the shape of a minimal Defender setup: enable the feature, add one exclusion, and schedule a weekly scan. Defender offers many more settings than these three steps; see Chapter 6.6 for the full reference including every scanner toggle, all eight notification categories, and the complete exclusion-type list.
On Manage Policies, click Manage on the policy you want to edit.
Open the Windows tab, then Microsoft Defender Antivirus, then Configuration.
Switch on Manage Defender settings at the top of the panel. Without this, none of the settings below are applied to devices. Notifications are switched on separately on the Notifications sub-tab and do not need this switch. With notifications on and management off, the agent only reads the Defender event log and changes no Defender setting.
Still on the Configuration sub-tab, scroll to the Scan Jobs section.
Click Add to open the Add Scan Job dialog.
Fill in:
Enabled: on.
Name and Description: for example Weekly full scan.
Schedule Type: pick a day-of-week schedule.
Day toggles: tick one day (for example Sunday).
Time: pick an off-hours time.
Scan Mode: pick the mode that fits (quick versus full).
Set the CPU Usage % cap, and the Scan on Battery, Network Drives, Removable Disks, and Update Signatures toggles to your preference.
Save. The scan-job row appears in the table.
Use the Add Scan Job Directory dialog from inside the scan-job editor to add the directory list the scan covers. Most deployments want the full system drive.
Save the policy. Devices that receive this policy through an automation apply the Defender configuration on their next sync. If no automation routes the policy yet, create one as described in Guide H.4 stage 2.
On the policy's detail view, the Windows → Microsoft Defender Antivirus → Configuration sub-tab shows Manage Defender settings switched on, the exclusion in the table, and the scan job in the schedule table.
In Events, filter by a targeted device and look for entries reflecting the Defender configuration push.
Locally on the device, Windows Security shows Defender active, the new exclusion listed under Virus & threat protection settings → Exclusions, and a scheduled task entry corresponding to the scan job.
No Defender changes on the device. Confirm the device is assigned the right policy (Devices → <device> → detail view → Assigned policy). If the field shows -, create or fix an automation.
Scan never runs. Open the scan job in the policy and confirm Enabled is on, the day toggle matches today's plan, and the time has not already passed for this week.
Exclusion is ignored. Check the value in the exclusion row against the actual path on the device.
NetLock RMM organises every device into a three-level hierarchy: tenant → location → group. A device cannot be approved into the console without one of each. This guide walks through creating the hierarchy from scratch on the Tenants page. Once finished you will have an empty tree ready to receive an agent.
Click Add above the tenant table. While no tenant exists, the page shows Create Tenant instead.
Enter the tenant name and, if you like, a description, the company and contact persons. For an in-house IT team the tenant usually maps to the company; for an MSP it maps to one customer.
Click Confirm. The new tenant appears in the list. It does not contain any locations, groups or devices yet.
In the Locations table, open the new location with the row action Manage. The Manage location page opens.
Click Add above the Groups table.
Enter a group name aligned to how the devices inside it will be configured, for example Workstations, Laptops, Servers or POS Terminals. As a rule of thumb, create one group per intended policy.
Click Confirm.
Tip: If a single policy applies to every device at a location regardless of role, one group per location is plenty. Only split groups when different policies will apply. It is easier to add groups later than to consolidate them.
An Add button or the Manage action is missing. Your user account is missing the matching permission from the list above. Ask an administrator to grant it.
A name is rejected with Name already taken. Tenant names are unique across the installation, location names within their tenant, and group names within their location. Pick a different name or a different parent.
This guide turns on debug logging for the NetLock RMM agent services on a device, walks through reproducing a problem while logs are being written, and shows where to collect the log files from. By default the agents write no log files at all, not even errors, so an empty or missing Logs folder on a device is normal, not a fault. Debug logging is the on-device counterpart to the server-side Logging page described in A.9.
Each of the three agent services (Comm, Remote, and Health) checks once at process startup whether a file named debug.txt exists in its data directory. The file's content is ignored; an empty file is enough. Because the check runs only at startup, creating or deleting debug.txt takes effect only after the service restarts.
You have administrator or root access on the target device. The agent data directories are protected on every supported OS, so both creating debug.txt and restarting the services require elevation.
You know which agent you need to debug. Comm Agent handles the server connection, policies, jobs, and sensors; Remote Agent handles remote control sessions; Health Agent supervises the other two. When in doubt, enable debugging on all three.
Plan to turn debugging off again. Debug logs grow without rotation or a size limit, so do not leave debug.txt in place on a production device after you have collected what you need.
The debug.txt file goes into the agent's data directory. The directory names contain spaces on every OS, so always quote the paths in a shell:
where <Agent> is Comm Agent, Remote Agent, or Health Agent.
Note: The Health agent checks the other services every 60 seconds and automatically starts a stopped Comm or Remote service. Always use a single restart command rather than stopping a service, waiting, and starting it again. Otherwise the Health agent may start the service before you do.
Reproduce the problem. Trigger the failing action again (run the job, start the remote session, wait for the sync cycle) so the agents write log lines while the problem happens.
Collect the logs. Each agent writes JSON-lines .txt files into a Logs subfolder next to its debug.txt (for example C:\ProgramData\0x101 Cyber Security\NetLock RMM\Comm Agent\Logs\). The key files are Debug.txt and Error.txt, plus topic files such as Jobs.txt, Sensors.txt, and PowerShell.txt on the Comm agent or Remote_Control.txt on the Remote agent. Copy or zip the entire Logs folder per agent rather than picking individual files.
Folder permissions: the working folders of the agents (Scripts, Jobs, Sensors, Temp, Tools below each agent, and Installer, Updates, Temp below NetLock RMM) are accessible to the system account and administrators only. Open them from an elevated console (dir, icacls) rather than through the Explorer prompt "You don't currently have permission to access this folder — Continue": that prompt adds your account to the folder permissions, and the agent resets them on its next start. The Logs folders and debug.txt stay readable for every user.
The scripts that ship with the agent live under C:\Program Files\0x101 Cyber Security\NetLock RMM\Comm Agent\Scripts (system account and administrators only). The agent refuses a changed script with an Endpoint protection event (type 14, reason script_manifest_mismatch) and a missing one with script_missing. Do not edit these files; run the installer with fix to restore them.
Tip: Independent of debug mode, the services' standard output is available too. On Linux, use journald: journalctl -u netlock-rmm-agent-comm -n 300 --no-pager (likewise for the remote and health units). Errors that stop a service right after its start, before it writes any log file, appear only there. On macOS, the LaunchDaemons log to /var/log/netlock_rmm_agent.comm.log and /var/log/netlock_rmm_agent.comm_error.log (likewise .remote / .health).
Disable debugging again. Delete debug.txt from each data directory and restart the services with the same commands as in step 2. Debug logs grow unbounded, so do not skip this on a production device. You can delete the collected Logs folders afterwards to reclaim disk space.
After step 2, the Logs subfolder appears in each agent's data directory and Debug.txt inside it grows as the agent works. The Comm agent writes lines on every sync cycle, so within a minute or two the file should have content.
After step 5, the services run without writing new lines, and the timestamps on the files in Logs stop advancing.
Screen capture, keyboard and mouse input and the clipboard of a remote control session are not handled by one of the three services but by the User Process, a program of the agent that runs inside the desktop session of the signed-in user. When a remote control session connects but shows no picture or takes no input, its log is the one to read, next to the Remote agent's. This section covers Windows, Linux and macOS.
Debugging is switched on with a debug.txt in the data directory of the User Process:
Nothing has to be restarted: the User Process looks for the file every time it is about to write a log line, so logging starts as soon as the file exists and stops as soon as it is deleted.
Where the log is written depends on the platform:
Windows: the Logs folder next to debug.txt (Debug.txt and Error.txt).
Linux (agent 3.3.0.11 or later): below the home directory of the desktop user, because the User Process runs as that user: ~/.config/netlock/logs/ (Debug.txt and Error.txt), next to the stored screen-sharing permission pipewire_restore_token. From a root shell that is /home/<user>/.config/netlock/logs/. The folder and its files are readable for that user and root only.
macOS (agent 3.3.0.11 or later): below the home directory of the signed-in user, because the User Process runs as that user: ~/Library/Logs/NetLock RMM/User Process/ (Debug.txt and Error.txt). From a root shell that is /Users/<user>/Library/Logs/NetLock RMM/User Process/. The folder and its files are readable for that user and root only. The log records the permission state at every capture start, the start and the end of each ScreenCaptureKit stream with its reason, the fall-back to single pictures and the kind of each input error; never what was typed or clicked.
On macOS the log of a signed-in user is in /Users/<user>/Library/Logs/NetLock RMM/User Process/; remove the marker with sudo rm on the same path when you are done.
Reproduce the problem (on Linux, start a remote control connection from the console) and collect the log. On Linux, replace <user> with the name of the desktop user:
sudo ls -la /home/<user>/.config/netlock/logs/
Switch debugging off again when you are done; the log grows without a limit. On Linux:
On macOS the User Process also has a diagnosis mode that reports the permission state, the signature of the program, the displays and the result of a short capture without a session from the console; it is described under Remote Screen Control on macOS. The signature and notarization of the installed programs can be checked on the Mac with codesign --verify --deep --strict and spctl -a -t exec on the application bundles under /usr/local/bin/0x101_Cyber_Security/NetLock_RMM/, and the LaunchAgents of a signed-in user with launchctl print gui/$(id -u)/com.netlock.rmm.user.process.
The log of a Linux device covers the whole start of the screen capture on Wayland: the availability check with the name of what failed (for example gstreamer_element_missing:jpegenc, python_modules_missing, pipewire_not_running or portal_not_available), each request to the desktop portal with its answer and the time it took, whether a stored screen-sharing permission was used, the GStreamer pipeline with its error output, the first picture, and the reason whenever the capture is stopped. It holds neither what was typed or clicked during a session nor the stored permission token. The Remote agent's Debug.txt records the capture results the User Process reports to it. The checks that go with it are listed under Troubleshooting Remote Screen Control on Linux.
No log output appears even though debug.txt exists. The services were not restarted after the file was created, and the check runs only at process startup. Restart all three services as in step 2. On Windows, also check the file name: with hidden file extensions enabled, Explorer's New → Text Document creates debug.txt.txt without showing the extension, and the agent ignores that file. Create the file from PowerShell as shown above to be safe.
The Comm agent service on Linux restarts every few seconds and the device never comes online. Read the journal first: sudo journalctl -u netlock-rmm-agent-comm -n 300 --no-pager. The agent checks at startup that its SQLite library loads; if it does not, the journal and Error.txt contain one line starting with NetLock RMM Comm Agent: the SQLite library could not be loaded, followed by the loader error, the operating system and the glibc version. Agents before 3.3.0.11 do not run on systems with a glibc older than 2.34 (Ubuntu 20.04, Debian 11, RHEL/Oracle/Rocky/AlmaLinux 8). Those devices do not update themselves; install the agent again with an installer from a server on 3.3.0.11 or later. See X.8 — Platform Support for the supported distributions.
A Linux device with SELinux in enforcing mode (Fedora, RHEL and its rebuilds) stays on an agent before 3.3.0.11 and no longer syncs.sudo systemctl status netlock-rmm-agent-installer shows status=203/EXEC. sudo ausearch -m avc -ts today shows a denied execute on NetLock_RMM_Agent_Installer. Until the reinstall, the device does not sync its policy or report patch results. These devices do not update themselves. Install the agent again with an installer from a server on 3.3.0.11 or later, the same way as a first installation (see Deploy your first agent): the installer with its embedded configuration or the --server parameter mode. This runs a clean installation, which removes the old agent and its local data first, and the device then waits for approval under Unauthorized Devices (see Approve and label a new device). A failed start of the installer is written to the agent's Error.txt.
The agent is offline or cannot reach the server. Debug logging still helps. The logs are written locally on the device, independent of the server connection, so connection problems are exactly what debug logging is for. Collect the Logs folders directly from the device (step 4) instead of expecting anything to show up in the Console.
The device is behind an HTTP proxy: which proxy did the agent pick? With debug logging on, the Comm, Remote and Health agents write the decision to Debug.txt under Helper.Proxy_Resolver.Create_Proxy on every start: the mode (auto, manual, none), the proxy address, the authentication method and, if one is used, the user name. The password is never written. No such line means no proxy applies and the agent connects directly, which in auto mode is also what you see on a device that reaches the backend without one. The reachability check itself logs under Helper.Connectivity_Probe, including a proxy that answered 407. The settings the agent reads come from proxy.json next to server_config.json; see Devices behind an HTTP proxy.
A device turns up under Unauthorized Devices although nobody deauthorized it. The on-device logs cannot show the reason, because that decision is made on the server. Read the device's authentication log in the Console first, as described in the next section. A second entry with the name of a device that is still authorized is a reinstalled operating system; the entry carries the chip "Name already exists" and is continued with "Adopt as reinstall" rather than approved as a duplicate.
A device that suddenly waits under Devices → Unauthorized Devices although nobody deauthorized it is the one agent problem the on-device logs cannot explain, because the decision is made on the server. The server writes every agent check-in that it did not accept as a plain success to a per-device authentication log, and the Console shows it in two places:
Devices → select the device → tab Authentication, for a device that is (again) authorized.
Devices → Unauthorized Devices → row action Authentication log, for a device that just lost its authorization.
Both require the permission "Authentication log" in the device information tabs group of the user settings.
Each row names the endpoint the request hit, the remote address, the agent version, the hardware ID the agent sent next to the one that was stored for the device, and a reason. Repeats of the same state within ten minutes are folded into one row whose counter grows, so a device that polls every 30 seconds while it waits for approval produces one row per ten minutes rather than twenty. The moment authentication succeeds again is recorded as "Authentication succeeded again". Successful check-ins of an authorized device are not listed, so an empty tab means the device has authenticated without trouble.
Reason
What happened
What to do
Hardware ID changed: new ID stored, device stays authorized
The access key matched, but the hardware ID the agent sent differed from the stored one. The server stored the new ID, kept the previous one with the device and left the authorization as it was. The stored ID in the row is the previous value, the received ID the new one. The server sensor trigger "Hardware ID changed" fires for this row.
Nothing, unless you did not expect it. A new ID means the operating system was reinstalled or the device is a copy of an image that was not generalized (see Hardware ID). Two devices sharing one access key (a cloned image) show alternating IDs from two remote addresses; give each clone its own agent installation.
Hardware ID changed again while waiting for approval
The same for a device that was not authorized at that moment: the new ID is stored and the device keeps waiting. The auto-authorization window of its agent package is checked afterwards.
Approve the device; it stays stable.
Hardware ID migrated to the new format
The agent update moved the device to the current hardware ID format. The authorization is unchanged. The stored ID in the row is the previous value, the received ID the new one.
Nothing. A device that was already waiting for approval still needs that approval.
Reinstall detected: new access key, waiting for approval
The agent was reinstalled on a known device whose previous installation no longer reports. The device waits for approval under its new access key; the details name the prefix of the previous key. If the previous installation still reports, a new entry is created instead, with fallback_skipped=online in its details.
Expected after a reinstall with a fresh installer. Approve the device.
New device created, waiting for approval
Nothing matched, so a new device row was created. Details tenant_id=0 mean the tenant or location GUID of the installer did not resolve; the device is then in no tenant view. Details duplicate_of=<id> name an authorized device of the same name (duplicate_same_tenant=1 when it is in the same tenant): the new row is most likely that device after a reinstall of its operating system. Details fallback_skipped=online mean a device of the same name and hardware ID exists but its agent still reports, so it was not re-keyed.
Approve the device. With tenant_id=0, check the installer package. With duplicate_of, the Unauthorized devices page shows the chip "Name already exists" on the entry; use Adopt as reinstall there instead of approving a duplicate.
Adopted as reinstall of an existing device
An administrator used "Adopt as reinstall" on the Unauthorized devices page: the existing device took over the access key and hardware ID of the unauthorized entry, the entry was removed and its rows of this log were moved to the device. The stored ID in the row is the device's previous hardware ID, the received ID the new one; the details name the removed entry and the prefix of the device's previous key.
Nothing. The device fetches its policy at its next check-in.
Auto-authorized by its agent package / New device auto-authorized by its agent package
The agent package has an auto-authorization window that was still open.
Nothing.
Auto-authorization failed
The window was open, but the authorization could not be written.
Check the server error log; approve the device manually.
Not authorized, waiting for approval
The device polls while it waits for approval.
Approve the device.
Identity incomplete: hardware ID or device name missing / Identity rejected
The request lacked a hardware ID or a device name, or the stored authorization state was unreadable.
Usually a hand-made or truncated request. A file browser download with an incomplete identity ends here as well.
Server error while checking the identity
The check failed with an exception; the details carry the message. The agent treats this answer as a no-op and retries.
Check the server error log and the database connection.
Hub connection rejected: …
The Remote agent's connection to the command hub was refused: unknown agent package, device not authorized, identity incomplete (no hardware ID), unknown access key or server error.
An incomplete identity here while the HTTP check-ins pass means the Remote agent carries an older identity file than the Comm agent; restart the Remote agent service.
Deauthorized by the license limit
The number of authorized devices exceeded the license, and the newest devices were deauthorized. The details name the limit and the count at that moment.
Raise the license or reduce the number of authorized devices, then re-authorize.
The log is written by the server, so agents need no update for it. Rows are kept for 90 days by default (Settings → Retention & cleanup). Update the Web Console before the server.
Next to the access key, every device identity carries a hardware ID. The server stores it with the device, shows it in the authentication log and in the Authentication tab, and uses it to recognize a reinstalled agent; it is also the value behind {{device.hwid}} in scripts. The access key remains the identifier to use when you refer to a device from outside. A changed hardware ID does not take the authorization away: the server records the new value and the device stays authorized (see the table above).
The hardware ID identifies the operating system installation, not the hardware:
A reinstalled operating system (same host name, fresh agent) produces a new hardware ID and, with a fresh installer, a new access key. The agent appears as a new entry under Unauthorized Devices. The entry carries the chip Name already exists when an authorized device of the same name exists in your tenants; use the row action Adopt as reinstall to continue that device under the new agent (it keeps tenant, location, group, policy, label and history; the new entry is removed) instead of approving a duplicate. See Chapter 3.2.
An agent that is uninstalled and installed again on the same operating system installation keeps its hardware ID, and the server continues the existing device ("Reinstall detected") once the previous installation no longer reports. A reinstall while it still reports appears as a new entry with the chip, to be adopted.
A replaced mainboard, a VM moved to another host or restored from a backup do not change the ID.
Clones of an image that was not generalized share the hardware ID. Clones that also carry the agent's server_config.json share the access key and merge into one device row; clones with their own agent installation but the same ID can take over each other's row when one of them is reinstalled. Run sysprep /generalize (Windows) or clear /etc/machine-id (Linux) before sealing an image, and install the agent after provisioning.
Winget, Chocolatey, and Flathub cover the common catalogue apps, but plenty of software is not in any of them: an internal line-of-business tool, a vendor MSI behind a download URL, a .deb from a private repository, a macOS .pkg. For those, App Hub has a Script source: you write the install, update, uninstall and detection commands yourself, and Software Deployment runs them on the target devices.
For an installer file that only needs its silent switches (an MSI, EXE, MSU, PowerShell file, .deb, .rpm, .sh or .pkg), the source File from the file server is simpler: see Deploy an installer file from the file server.
This guide covers the whole flow: creating a script-based app in App Hub, writing scripts whose result is judged correctly, adding a detection script that tells NetLock RMM whether the app is installed and which version, deploying the app, and reading the per-device results.
Required permissions: collections_enabled, collections_app_hub_enabled to create the app; plus collections_software_deployment_enabled and collections_software_deployment_add for the deployment.
Target devices are online and assigned a policy.
You know the silent-install command line for your software (for example an MSI's /qn switches, an installer's /S, apt-get install -y, or installer -pkg).
With Requires Elevation on, every script runs as the agent: SYSTEM on Windows, root on Linux and macOS. No user can answer prompts, so every command must be fully non-interactive.
Open Collections → App Hub (route /app_hub_manage_apps).
Click Add to open the Add Manual App dialog.
Fill in the shared metadata:
Name (required): how the app appears in the catalogue and the deployment wizard.
Version: the version this catalogue entry installs, for example 2.4.1. It is compared with the version the detection script reports (see Versions and updates).
An icon upload (.png, .ico, .jpg/.jpeg, up to 256 KB).
Under Source, choose Script. (The sources Winget (Windows), Chocolatey (Windows) and Flatpak (Linux) are package-manager entries and do not take scripts; File from the file server runs an uploaded installer file, see Deploy an installer file from the file server.)
Pick the Script Shell that matches the platform you are targeting: PowerShell for Windows, Bash for Linux, Zsh for macOS. This sets the editor language. The agent always runs scripts in the platform's shell: PowerShell on Windows, Bash on Linux, Zsh on macOS.
Fill in the script editors:
Install Script (required): the commands that install the software.
Update Script: run when a deployment item or the tray icon updates the app. Without it, Update is not offered for this app.
Uninstall Script: run when a deployment item or the tray icon uninstalls the app. Without it, Uninstall is not offered for this app.
Detection Script: reports whether the app is installed and which version; see The detection script.
Detection window (seconds): how long the detection script keeps being asked after an action (0 to 3600, default 300; 0 turns the check after the action off).
Set Target OS to Windows, Linux, or macOS, consistent with the scripts.
Leave Requires Elevation on so the scripts run as SYSTEM/root. Turning it off runs them in the signed-in user's session on Windows; see Apps without elevation.
Optionally set Tags as a JSON array, e.g. ["dev","cli"].
Click Confirm. The app appears in the App Hub list with the script source chip.
The Edit App dialog has the same fields for an existing entry. A deployment reads the scripts from the app when it is saved; a deployment that is already running keeps what it was saved with.
The same rule applies to the install, update and uninstall script, on Windows, Linux and macOS:
The script failed when it exits with a code other than 0, when its output starts withError (case-insensitive), or when it runs longer than 30 minutes (it is then stopped and reported as Timeout).
Anything else is a success.
In practice: let the script end with the installer's exit code. An uncaught PowerShell exception, exit 1, or a failing command under set -e in Bash all mark the step as failed. A line that starts with Error: also marks the step as failed.
A script is done when its process ends. Several installers return to the script before they have finished:
msiexec.exe and most setup.exe files are GUI programs; PowerShell starts them and continues immediately unless you wait.
Bootstrappers hand the actual installation to a second process, a service or a scheduled task and exit right away.
Start installers with Start-Process ... -Wait -PassThru and exit with their exit code. For installers that still return early, the detection window covers the rest: after the script, NetLock RMM keeps asking the detection script until the app shows up.
set -eapt-get install -y ./app.debecho "MyApp installed."
Write idempotent scripts. The same install script can run more than once on a device, for example without a detection script or when a deployment uses Force reinstall. Check before you act, use installer switches that repair or upgrade in place, and avoid steps that fail when a previous run already completed them.
A detection script answers: is this application installed on the device, and which version? It is the same idea as an Intune detection rule, written as a script you control.
Exit code 0 and at least one non-whitespace character on stdout → installed. Any other result → not installed.
Print the installed version on the first line, for example 2.4.1 (a leading v is accepted). Up to four numeric parts are compared. A script that prints only installed still works; the version is then unknown.
It runs in the same context as the app's other scripts, with the platform shell, and has a 5-minute timeout per run.
A script that does not start, crashes or runs into the timeout counts as a detection error.
The detection script runs before and after every install, update and uninstall.
Action
Before the action
After a successful action
install
Installed → skipped (Skipped, detection state Detected)
must report installed
update
Not installed → skipped (Skipped, Not detected)
must report installed
uninstall
Not installed → skipped (Skipped, Not detected)
must report not installed
Before: a detection error lets the action run anyway (fail-open) and adds a [detection] note to the output. Force reinstall on a deployment skips only the check before an install; the check after it still runs.
After: the detection script is asked right away, after 5, 10, 20 and 30 seconds and then every 30 seconds until it reports the expected state or the detection window ends. Confirmed → Success with a [detection] Confirmed after N s line. Not confirmed within the window → Failed, even though the script itself succeeded. If every check fails with a detection error → Detection error.
A detection window of 0 turns the check after the action off. Without a detection script neither check runs.
With Requires Elevation on, the detection script runs as SYSTEM (Windows) or root:
The user's registry hive (HKCU) and profile folders (%APPDATA%, %LOCALAPPDATA%, ~/…) belong to the SYSTEM or root account, not to the signed-in user. An app installed per user is invisible there; detect it in the user's context (Requires Elevation off) or detect an installed file path that does not depend on the profile.
32-bit applications on 64-bit Windows register under HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall. Query both uninstall keys, as in the example below.
Keep the script fast and local; avoid network calls.
A deployment item runs the script of its own action: update runs the Update Script, uninstall the Uninstall Script.
An app without an update script cannot be deployed with the update action, and an app without an uninstall script cannot be deployed with uninstall: the wizard disables the action and saving the deployment is refused.
An update or uninstall is skipped on devices where the detection script reports the app as not installed.
When the detection script prints a version, it is compared part by part with the app's catalogue Version:
Tray icon App Hub: the app shows Update available when the catalogue version is higher.
Auto-update: a policy's auto-update for a script app runs the update script only when the detection script reports a version lower than the catalogue version. An app without a detection script, without an update script, without a version on the detection output or without a catalogue version is not updated automatically.
After you publish a new release, raise the Version of the App Hub app and update its install and update scripts.
With Requires Elevation off, deployment steps on Windows run in the session of the signed-in user through the tray icon:
The tray icon runs the detection script before the step, the script, and the check after it, in the user's context. Per-user installs (HKCU, %LOCALAPPDATA%) are visible there.
The deployment waits for the tray icon's result (up to 35 minutes plus the detection window) and reports it like any other step, so Abort on first failure applies. Without a signed-in user the step fails right away.
On Linux and macOS, steps without elevation run in the agent's context and have to be script apps.
Script apps show their state in the tray icon's App Hub:
The detection script decides Installed (with the detected version), Not installed or Update available. Apps that require elevation are checked by the agent; apps without elevation are checked in the user's session. While the check runs the badge shows Checking….
Without a detection script, or when it fails, the state is Status unknown; hover the badge for the reason.
Update and Uninstall are shown only when the app has the matching script. Update is enabled when an update is available, when the app is installed but no version can be compared, or when the state is unknown. Uninstall is enabled when the app is installed or the state is unknown.
After an install, update or uninstall the tray shows the phase verifying while the detection window runs.
App Hub is the catalogue; the app is installed on devices through Software Deployment.
Open Collections → Software Deployment (route /software_deployment) and start a New Deployment.
Step 1: Packages. Select your script app and choose the action. update and uninstall are disabled when the app has no script for them.
Step 2: Targets. Pick the devices, groups, locations, or tenants that should receive it. Keep the Target step aligned with the app's Target OS; a Windows PowerShell app fails on Linux devices.
Step 3: Options. Set the schedule, retries, and flags. Leave Force reinstall off to skip devices where the app is already detected; turn it on to install everywhere (the check after the install still runs).
Open the deployment's detail page. The History tab and the per-device results dialog show an outcome chip per attempt, and next to it what the detection script saw:
Success: the script succeeded and, with a detection script, the result was confirmed.
Failed: the script failed, or the detection script did not confirm the result within the detection window.
Skipped: the detection before the action decided there was nothing to do. Counts as a success.
Detection error: the script succeeded, but the detection script failed on every check after it.
Timeout: the script ran longer than 30 minutes, or the tray icon did not report a result in time.
Detection state: Detected, Not detected or Detection failed.
The per-device dialog shows the exit code, duration, timestamps, an error summary, and the stdout tail. Lines starting with [detection] explain every decision the detection script made, including how many seconds after the action the result was confirmed.
The step fails with "the detection script did not report the app as installed within N s". The script finished, but the app did not show up. Either the installer returned before it was done (start it with Start-Process -Wait -PassThru, or raise the detection window for bootstrappers that hand over to a service), or the detection script looks in the wrong place (per-user install seen from SYSTEM, 32-bit app under WOW6432Node, a different DisplayName). Run the detection script as SYSTEM on the device (for example with psexec -s) to check what it reports.
The deployment reports Failed with an exit code, but the app is installed. The installer returned a non-zero exit code that is not an error for it (for example 3010, restart required). Map such codes to exit 0 in the script.
The app always installs, even where it is already present. Detection reported "not installed". Check that the detection script exits 0 and prints at least one line when the app is present. Also confirm Force reinstall is off.
The app is always skipped, even on clean devices. Your detection script exits 0 with output on machines that do not have the app. Tighten the check (a specific file path or a specific registry DisplayName).
Detection error. The detection script crashed or ran into its 5-minute timeout on every check after the action. Keep it fast and avoid network calls.
Update or Uninstall is not offered. The app has no update or uninstall script.
The tray shows Status unknown. The app has no detection script, the detection script failed, or the agent did not answer within 3 minutes. Hover the badge for the reason.
A script app is never auto-updated. The detection script prints no version on its first line, the catalogue Version is empty, or the installed version is not lower than the catalogue version.
A step without elevation times out. The tray icon did not report a result: no user was signed in, the tray icon was closed, or the script is still running. The step waits up to 35 minutes plus the detection window.
Many installers are not in Winget, Chocolatey or Flathub and are not worth wrapping in a script: a vendor MSI, a setup EXE, a Windows update package, a .deb or .rpm from a supplier, a macOS .pkg. For those, App Hub has the source File from the file server. You upload the file to the File Server once, pick it in the app, set the arguments for install, update and uninstall, and add a detection script. Software Deployment, the tray icon's App Hub and auto-update then run exactly that file on the devices.
The app stores the SHA-512 of the file when you pick it. A device downloads the file, compares its SHA-512 with the stored value and starts it only when both match. A file that was replaced or changed on the server is never run.
Permissions: collections_app_hub_enabled and collections_app_hub_add to create the app, collections_app_hub_manage to edit it, and file_server_enabled to choose or change its file. Uploading a new file from the dialog needs file_server_add.
The file lies on the File Server (Collections → Files, see 9.1 File Server). Files below netlock/ and files collected from devices (below devices/) cannot be chosen.
You know the silent switches of the installer.
File apps always run as the agent: SYSTEM on Windows, root on Linux and macOS. There is no interactive user, so the installer must run without any question.
The programs are started by their full path and never through a shell. Every other exit code is a failure. One start may take up to 60 minutes; after that it is stopped and reported as Timeout.
Upload the installer under Collections → Files if it is not there yet. You can also upload it from the file dialog in step 5.
Open Collections → App Hub and click Add.
Fill in Name and Version (required for file apps; it is compared with the version the detection script reports).
Under Source, choose File from the file server. The option is available with the permission file_server_enabled.
Click Choose file and select the installer. Only the types the source supports can be selected; the netlock and devices folders are not offered. The dialog shows the file name and its SHA-512, with a copy button. The target system follows the file type: an .msi makes a Windows app, a .deb a Linux app, a .pkg a macOS app.
Enter the arguments per action (see below). Command the agent runs below the fields shows the resulting command.
Choose the uninstall mode under Uninstall.
Write the Detection Script (required).
A file app always runs as SYSTEM or root; the elevation switch is on and locked.
Edit App shows the same block. Without a new choice, the app keeps the file and the SHA-512 it pinned. If the file on the file server is missing or was replaced since it was chosen, the dialog asks you to choose the file again before you can save; choosing a file pins its current SHA-512. Changing the file, the arguments or the uninstall mode needs file_server_enabled. Saving the app also updates the pending deployments that use it and have not started on any device yet; a deployment that has started keeps what it started with.
Update arguments: used for an update. Leave it empty to use the install arguments.
Uninstall arguments: used when the uninstall mode is This file with arguments.
Each field holds up to 2048 characters on one line. Line breaks and other control characters are refused.
On Windows, the arguments are appended to the command line exactly as you type them, without a shell. Quotes work the way the installer expects them. For example, INSTALLDIR="C:\Program Files\Contoso" for msiexec, or /D=C:\Program Files\Contoso for NSIS. Characters such as &, | and > have no special meaning. On Linux and macOS, the arguments are split like a command line, with quotes grouping words, and passed to the program without a shell.
The Template menu next to the install field fills in common silent switches for the type of the chosen file:
Installer
Arguments
MSI
/qn /norestart
Inno Setup
/VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP-
NSIS
/S
InstallShield
/s /v"/qn /norestart"
MSU
/quiet /norestart
For MSI, the agent adds /L*v with a log file of its own when the arguments do not name a log. For a failed run, the result contains the part of that log around the first failed action (Return value 3) and its last lines.
The hash pins only the chosen file. The arguments are part of what you approve: they can make the installer load something else. Examples are TRANSFORMS= or PATCH= with msiexec, a second /i, additional package names with apt-get, dnf or zypper, or a second -pkg with installer. Such additional files are not covered by the SHA-512 of the app. Keep the arguments to the switches the chosen file needs.
Arguments are delivered to the devices with the policy and shown in the device's App Hub data. Do not put passwords or licence keys into them; pass such values with a script and a custom field instead.
None: the app cannot be uninstalled from NetLock RMM. The tray icon shows no uninstall button, and a deployment cannot use the action.
This file with arguments: the same file runs with the uninstall arguments. Available for .msi (as msiexec.exe /x), .exe, .ps1 and .sh.
Script: an uninstall script that you write, run in the platform's shell. Use it for .msu, .deb, .rpm and .pkg, or when the vendor's uninstaller is not the installer file.
Uninstall an MSI by its ProductCode (PowerShell, as SYSTEM):
Other examples: wusa.exe /uninstall /kb:5000000 /quiet /norestart for an MSU, apt-get remove -y contoso-client for a DEB, dnf remove -y contoso-client for an RPM. For a PKG, remove the installed files and then run pkgutil --forget com.contoso.client.
A file app needs a detection script. It works as for script apps (see The detection script): exit code 0 and output means installed, and the first line should carry the installed version. It runs before the action and, until the detection window ends, after it. When the detection before an install already reports the app, the file is not even downloaded.
Examples:
# Windows: version of an installed MSI or EXE from the uninstall keys$keys = 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*', 'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'$app = Get-ItemProperty $keys -ErrorAction SilentlyContinue | Where-Object { $_.DisplayName -eq 'Contoso Client' } | Select-Object -First 1if ($app) { $app.DisplayVersion; exit 0 } else { exit 1 }
# Linux (DEB): version of an installed packagedpkg-query -W -f='${Version}\n' contoso-client 2>/dev/null
# Linux (RPM)rpm -q --qf '%{VERSION}\n' contoso-client 2>/dev/null
The detection script runs. An install of an app that is detected, and an update or uninstall of an app that is not, are skipped.
Unattended runs (deployments, auto-update) wait a random 0 to 120 seconds, so that a large rollout does not start every download at once.
The agent downloads the file from the File Server into its protected working folder. It needs free space for twice the file size plus 512 MB. A broken download resumes where it stopped. If the File Server answers that it is busy, the agent waits as long as the server asks and tries again, for up to 30 minutes.
The agent computes the SHA-512 of the downloaded file and compares it with the app. On a mismatch nothing starts and the result is Error: file hash mismatch.
3010 and 1641 on Windows mean success with a restart required. The output ends with [reboot] restart required. The agent never restarts the device; plan the restart yourself. If the detection script cannot confirm the change before the restart, the result is still a success, with the note that the detection is pending until the restart.
1618 (another installation is in progress) is tried again up to three times, one minute apart, for .msi and .msu. On Linux, apt-get waits up to five minutes for the package database lock (held, for example, by unattended-upgrades), and a lock held by another dpkg, rpm or zypper process is tried again the same way.
The result starts with a summary: the restart line, the exit code and, for a failure, the reason. The installer's output follows.
The downloaded file and its folder are deleted. The detection script confirms the result.
The tray icon shows the phase downloading with a percentage while the file is transferred.
A .ps1 file runs with -ExecutionPolicy Bypass. If a Group Policy enforces AllSigned, sign the script with a certificate the devices trust (see Run only signed PowerShell scripts).
Upload the new installer under a new name, for example contoso-client-4.3.msi. The file the app uses cannot be overwritten (see below).
Edit the app, choose the new file, and raise Version.
Save, and sign it if your devices use endpoint protection.
Devices then see an update when the detection script reports a lower version: the tray icon offers Update, and auto-update runs it when the policy allows auto-update for the app. An update runs the new file with the update arguments, or with the install arguments if the update field is empty. Once no app and no open deployment uses the old file any more, you can delete it.
A file that an App Hub app or an open deployment (draft, pending or running) uses cannot be deleted or overwritten on the File Server. The Console names the apps and deployments. Renaming or moving the file is allowed: the app keeps working.
The App Hub list marks an app with File missing or File changed when its file is gone or was changed on the server outside of NetLock RMM (for example restored from a backup); open the app and choose the file again. Devices refuse such a file: a missing file is reported as not available, a changed file as a hash mismatch.
A deployment keeps the file it was saved with. Saving the app updates pending deployments that have not started on any device yet; a deployment whose file is missing or changed on the server cannot be saved.
On anchored devices a file app runs only when it is signed. The signing request in the NetLock app shows the file name, the SHA-512, the arguments and the uninstall mode. Compare the SHA-512 with the hash of your own copy of the installer:
A software deployment with file items shows its items with file, SHA-512 and arguments in the signing request as well. A file or an argument changed after signing is refused by the device with event type 14 (file_hash_mismatch or payload_hash_mismatch). See Endpoint protection.
Deploy the app with Software Deployment like any other app (see Deploy software with App Hub). Update is always available for file apps, and Uninstall is available when an uninstall mode is set.
the file is not available on the file server (status 401) / (status 404)
The file was deleted or replaced outside of NetLock RMM, or the device is isolated. Choose the file again in the app. The agent does not repeat the download in that run.
file hash mismatch
The file on the server is not the file of the app. Choose the file again (and sign the app on anchored devices).
not enough free disk space
The device needs twice the file size plus 512 MB free.
another installation is in progress
Windows Installer stayed busy during three attempts (exit code 1618). The deployment retries according to its retry settings.
the download did not finish within N min
The transfer took longer than its limit: at least 30 minutes, longer for large files (about 100 kB/s), at most 12 hours. Check the connection between the device and the File Server.
the file server stayed busy
The File Server limited parallel downloads for 30 minutes; see Downloads by devices.
a file app runs only as the system account or root / A file item runs only with elevation
The app or deployment item has elevation switched off.
[reboot] restart required
Success; the change completes after the next restart.
App Hub is a catalogue; it does not install software by itself. To roll an app out to devices you combine two Collections features: App Hub supplies the package definition, and Software Deployment wraps that definition in a deployment job with targets, scheduling, and per-device result tracking. This guide walks through picking a Winget app into App Hub and rolling it out to a small group with the Software Deployment wizard.
For Winget apps, target devices are Windows and have Winget available (Windows 10 1809+ or Windows 11).
Required permissions: collections_enabled, collections_app_hub_enabled and one of the browser flags (collections_app_hub_browse_winget for Winget); plus collections_software_deployment_enabled and collections_software_deployment_add for the deployment.
Open Collections → App Hub (route /app_hub_manage_apps).
Either click Refresh catalogs first to sync the remote catalogues, or use the Winget Catalog Browser directly.
Open the Winget Catalog Browser, search for the app you want (for example 7zip.7zip), select it, and click Add to Catalog. The app appears in the App Hub list with the winget source chip, publisher, and version.
Alternatively, click Add on App Hub to open the manual-entry dialog, pick Winget as the source, and paste the Winget Package ID and Winget Source directly.
Open Collections → Software Deployment (route /software_deployment).
Click New Deployment. Enter a Name and optionally a description at the top of the page; the four-step wizard is below it.
Step 1: Packages. In Search catalog, find the app you added and pick it; it is added to the list below. Choose Install in its Action column.
Step 2: Targets. Pick tenants, locations, groups, or individual devices. Tick Automatically include future group members (or the matching option for tenants and locations) if devices that join the selected scope later should be picked up automatically.
Step 3: Options. Set the start date and expiry if needed, the retry policy (Max attempts per device, Backoff between retries (minutes)), and the force-reinstall and abort-on-first-failure options as needed.
Step 4: Review. Check the summary and click Create Deployment. The deployment appears on the Software Deployment list.
Note: Software Deployment is not policy-driven. A deployment targets devices directly through its own wizard. The App Hub tab inside the Policy Settings editor is a separate setting; it only selects which apps appear in the tray icon.
Some devices fail. Open the deployment detail page and review the per-device result. The stderr tail and exit code usually identify the cause (Winget source unavailable, package ID incorrect, insufficient disk space).
Install fails with an elevation or permissions error. An installer runs in a specific user context, and whether it needs administrative elevation is declared by the package maintainer, not by NetLock RMM. The App Hub entry carries an elevation setting (whether the installer requires elevation) that reflects what the maintainer specified.
Maintainers occasionally specify this incorrectly: an installer that needs elevation is marked as not requiring it, or the reverse. The installer then runs in the wrong context and reports installation failed. When the exit code or stderr points to a permissions or elevation problem, edit the App Hub entry and test the opposite elevation setting before assuming the package itself is broken.
An update in the tray icon's App Hub ends with winget does not see this package as installed for the whole device or winget does not find this package in your user profile. winget keeps packages that are installed for the whole device apart from packages installed for a single user. An app with Requires Elevation is updated by the agent as the system account, which only sees packages installed for the whole device. An app without it is updated by the tray icon in the user's session and only looks at the packages of that user. The tray icon offers Update from what the signed-in user's winget reports, so the action finds nothing when the package was installed the other way. Set Requires Elevation to match how the package is installed: off for a package installed for one user, on for a package installed for the whole device. The Logs dialog shows the sentence in front of winget's own output (agent and tray icon 3.3.0.12 or later). An automatic update that meets this state is skipped without an error and tried again the next day.
Non-Windows devices reported failure. Winget is Windows-only. Narrow the Target step to Windows devices, or add a Flathub app (Linux) or a script-based app for the other platforms.
App not listed in the wizard. Apps created through the public API with availableForDeployment: false do not appear. Set the field to true through the API.
Retry the failed devices. Click Retry on the deployment detail page. Retry respects Max attempts per device and Backoff between retries (minutes) and increments the per-device attempt counter.
Deploy custom applications with scripts — package software not in Winget/Chocolatey/Flathub as a script-based App Hub app, with install and detection scripts.
This guide takes you from a clean device to a running NetLock RMM agent that has reported in for the first time. It covers only getting the installer and the installation itself. The follow-up, approving the pending device and giving it a label, is in Guide H.2. For an end-to-end walk-through with tenant creation and policy assignment, see the First-Run Walkthrough.
A tenant, location, and group already exist to receive the agent. If they don't, do Guide H.3 first.
You have administrator or root access on the target device.
The target device can reach the Console's communication and remote servers over the network.
Required permission: agent_installers_enabled for Agent Installers.
On a self-hosted installation, the backend address the agents connect to is set. The Setup Wizard asks for it; otherwise Agent Installers asks for it before it shows any installer.
Open Agent Installers: Deploy Agent in the navigation, or the agent download icon in the app bar. While no device is enrolled, the Install Agent button on Devices opens the same page, and on a fresh deployment so does Deploy your first agent on the last step of the Setup Wizard.
Select the Tenant and Location the agent is deployed to. The Console keeps one ready-built installer per platform and architecture for every location and builds them in the background; a row shows Generating... until its installer is ready.
Decide under Automatic device authorization whether new devices of this location are authorized automatically. With Authorize new devices automatically turned on, devices installed until the Automatically authorize devices until date appear directly in Devices; afterwards, and while the option is off, they wait for approval. For a first agent, pending approval is the safer choice.
In the installer table, find the row of the target platform and architecture (win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64). Once its status shows Ready, use one of its actions:
Download installer: the .zip with the installer and its embedded configuration.
Download script / Copy script: an installation script (Install-NetLockAgent.ps1 for Windows, Install-NetLockAgent.sh for Linux or macOS) that installs the agent only where it is missing, so it can be assigned repeatedly through Intune, group policies or another deployment tool.
When you downloaded the .zip, copy it to the target device and run the installer with the commands below.
With no arguments the installer uses its embedded configuration; on macOS (3.3.0.11 and later) it uses the server_config.json next to it instead. For manual re-configuration or repair it also accepts positional modes: clean "<path-to-server_config.json>" runs a fresh install with an external config, fix "<path>" repairs an existing install while preserving its server config, and uninstall removes the agent.
Agent Installers also hands out the command that performs the whole installation in one line, so nothing has to be transferred to the device first. Use the Copy command button rather than typing it out: the command carries the package id of the selected tenant and location, and the proxy of that location where one is set.
Every installer row has a Copy command next to its download. On a Windows row it opens a short menu and you pick the shell you are going to paste into, PowerShell or Command Prompt; Linux and macOS rows have the shell form only and copy it straight away. The command downloads the ready-built installer package of that architecture, runs the installer inside it and removes the downloaded files again. That installer carries its configuration, so no parameters are passed.
Windows (Command Prompt, elevated): the second entry of the menu. It uses curl.exe and tar, both of which Windows ships since Windows 10 1803 and Windows Server 2019.
Linux / macOS (root shell), which needs unzip (installed by default on most distributions):
On macOS the package from the Console (from 3.3.0.11 on) holds the installer exactly as it was built and signed, with the configuration as a separate file server_config.json next to it; the installer reads the file from its own folder, so the command above works as it is. Keep the installer and the file together when you copy the package somewhere.
The one-line command is the recommended route on a Mac: a file saved by a browser carries the quarantine attribute, and Gatekeeper then checks the notarization of the installer before it runs, for which the command line installer needs an internet connection at that moment.
Where the agent package configuration has a proxy, the Console writes it into the download step of the command as well, because that download happens before the agent exists on the device. A proxy password is never written into an install command or an installation script, neither the ones shown on the page nor the .ps1 and .sh files offered for download. The placeholder <proxy-password> takes its place everywhere, so replace it before you run the command or the script. Only the downloadable server_config.json carries the real value, so a site with an authenticating proxy is usually deployed with that file and clean.
The commands are as sensitive as the installer they fetch: the link and the ids in them enrol any device they are run on into that tenant and location, and they do not expire. Revoking the installers of a location rotates the package id and invalidates every command handed out before.
The Standard Installer also takes its whole configuration on the command line. This is the route for deployments that do not want to distribute a binary with an embedded configuration. The same executable is then used everywhere and only the parameters differ per tenant. --server switches the installer into this mode; the positional clean / fix modes are not used with it.
--server <host:port>: the backend address, without a protocol. All five server fields of the configuration (communication, remote, update, trust, file) are set to this address, which is what the Console does as well. A comma separated list is accepted.
--tenant-guid <id>: required.
--location-guid <id>: required.
--package-guid <id>: required. This is the agent package configuration the device is enrolled with.
--ssl true|false: optional, true by default.
--language <code>: optional, en-US by default.
The three GUIDs are the ones Agent Installers uses for the same tenant, location, and package. The device is installed unauthorized, exactly like a clean install; it waits in the pending queue unless the Automatically authorize devices until date of that package configuration has not passed yet.
The Console offers this route ready to run. On Agent Installers, the section below the installer table hands out the unmodified installer for the selected architecture together with the commands built from it. All six architectures are served: win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64. On Windows the executable keeps its Authenticode signature and the Console reports whether it carries one. The macOS builds are signed with an Apple Developer ID and notarized.
Devices whose only route to the internet is a forward proxy need to be told about it, because the installer checks that it can reach the update and trust server before it downloads anything, and the agents determine the server they talk to the same way.
By default the installer and the agents work in auto mode: a direct connection is tried first, and only when that fails is a proxy looked for: first the NETLOCK_PROXY environment variable, then HTTPS_PROXY / HTTP_PROXY, and on Windows finally the machine-wide WinHTTP configuration that netsh winhttp set proxy writes. A device that reaches the backend directly therefore never changes behaviour, even if a proxy is configured on it for other software.
The proxy belongs to the network a device sits in, which is what an agent package configuration already describes, so it is normally set once in the Console instead of per device:
On Agent Installers, pick the tenant and location, then fill in the Forward proxy card. It writes the proxy into the configuration of that pair and rebuilds its six ready-to-use installers, because the proxy is built into them. The download links stay valid; the installers show as Generating until the rebuild is through.
The card offers the three modes (Automatic, Manual, No proxy) and the authentication method, and feeds the generated installers, install commands and installation scripts.
There is no list of hosts that stay direct. A configuration points the agents at one backend address, so excluding that address from the proxy would be the same as No proxy. The machine itself and the usual private ranges (10.*, 172.16.*–172.31.*, 192.168.*, 169.254.*, *.local, loopback) are always reached directly, which is what lets a self-hosted backend on the local network be reached without the proxy while a proxy is configured.
The Console builds no installer for a configuration that authenticates against the proxy with a user name and password; the Agent Installers page says so instead of showing a download. Deploy those devices with the parameters below or with the downloadable configuration file.
Where that is not enough, pass the proxy explicitly:
--proxy <http://host:port>: the proxy for all traffic to the NetLock backend.
--proxy-auth none|default|basic: how to authenticate. none is an anonymous proxy, default authenticates as the machine account against an NTLM or Negotiate proxy (Windows only, stores no secret, and is the right choice in most Active Directory environments), basic sends an explicit user name and password. Without this parameter, basic is assumed as soon as --proxy-user is given and none otherwise.
--proxy-user <name> / --proxy-pass <password>: the credentials for --proxy-auth basic.
--no-proxy: no proxy and no automatic detection. Use it on the rare device where a detected proxy is the wrong one.
The settings are written to proxy.json next to server_config.json in the Comm and Health agent data directories, and the agents read them from there on every start. A self-update (fix) leaves the file untouched, so the proxy survives agent updates.
The same values can travel inside the server_config.json you hand to clean, as a proxy object next to the existing fields. Use this for a scripted rollout that reuses one configuration file:
Warning: A proxy password given with --proxy-pass is stored in proxy.json on the device. Treat a stored proxy password as readable by local administrators of the device. A proxy service account is usually a domain credential, so prefer --proxy-auth default on domain-joined Windows devices, or an anonymous proxy rule for the backend address.
On Linux the agents run as systemd system units, which inherit neither /etc/environment nor a login shell. To set the proxy through environment variables there, put them in /etc/default/netlock-rmm (the generated units read that file if it exists) and restart the three services:
sudo tee /etc/default/netlock-rmm >/dev/null <<'EOF'HTTPS_PROXY=http://proxy.corp.local:3128NO_PROXY=localhost,127.0.0.1,.corp.localEOFsudo systemctl restart netlock-rmm-agent-comm netlock-rmm-agent-remote netlock-rmm-agent-health
The NetLock proxy applies to the requests the agents and the installer make themselves: the traffic to the communication, remote, update, trust and file server. It does not apply to the update mechanisms of the operating system, because those are separate components with their own configuration.
Windows. Patch Management drives the Windows Update Agent, and that component takes its proxy from the machine-wide WinHTTP configuration or from a WSUS, never from a NetLock setting. On a device whose only route out is a proxy, patch downloads therefore stay broken until one of the two is in place:
netsh winhttp set proxy proxy.corp.local:3128 "<local>"netsh winhttp show proxy
Point the device at a WSUS instead where you have one; the agent then reports and installs against that server and needs no internet route for updates at all. netsh winhttp set proxy is machine-wide and affects every WinHTTP client on the device, which is normally what you want in a proxy-only network. Note that it is also one of the sources the agent's own auto mode reads, so setting it can be enough to configure both at once.
Linux.apt and dnf read http_proxy / https_proxy from the environment of the process that runs them. The agents run as systemd units that read /etc/default/netlock-rmm (see above), and a patch job started by the agent inherits that environment, so the entries there cover the package managers as well. Where a package manager is also used outside the agent, configure it in its own place (/etc/apt/apt.conf.d/95proxy with Acquire::http::Proxy, or proxy= in /etc/dnf/dnf.conf) so a manual apt update behaves the same way.
macOS. Updates go through the system proxy configured in the network settings; NetLock does not change it.
Three limitations to consider before you plan a rollout:
The ready-built installers cannot be built for a configuration that stores a proxy user name and password. Those sites use the Standard Installer with the parameters above, or the configuration-file route. An anonymous proxy and --proxy-auth default are built into the installers normally.
A device that is already offline because of the proxy cannot receive the proxy setting through an update. Every such device needs one manual re-install with a current installer.
PAC / WPAD auto-configuration is not supported. Point the agents at the proxy directly.
The installer aborts before it downloads anything when it cannot reach the update or trust server, and it exits with code 1 so a deployment tool sees the failure. --skip-connection-check bypasses that gate and takes the first configured address as the update and trust server. Use it for a network the check cannot handle; on a device behind a proxy, configuring the proxy is the better answer, because the agents run into the same check afterwards.
Warning: Treat agent installers like secrets. The server configuration is embedded inside the binary, so anyone with the .zip can register a new device into the configured group. Rotate the installer if it leaves trusted hands.
Android phones and tablets use no installer. Install the NetLock RMM app from Google Play on the device. The Android card on Agent Installers offers the same store link and a Send download link button that mails it to the person setting up the device; the mail goes out through the SMTP server configured in the settings.
Once the app is on the device, enroll it with Mobile enrollment on Agent Installers or Devices: choose the tenant and location, then scan the QR code with the app or enter the enrollment code shown next to it. Both carry everything the app needs to reach this installation, so hand them only to the device that is being enrolled. The device then waits for approval like any other.
A phone that should be protected by endpoint protection gets its enrollment code from the anchor page of the NetLock app instead; the console's code never carries a trust anchor. See A.13.11. Viewing and controlling the screen of an enrolled phone is described in A.7.12.
The installer reports success and exits without an error code.
The agent is registered as a Windows service, a systemd unit on Linux, or a LaunchDaemon on macOS, and is running. On macOS, from agent 3.3.0.11 on, the User Process and the tray icon are registered as LaunchAgents under /Library/LaunchAgents/ for every signed-in user, provided the agent carries a valid Developer ID signature; see X.8.6.
Within a minute or two the device appears in the Console: in Unauthorized Devices (pending approval), or in Devices directly if the configuration's Automatically authorize devices until date (set on Agent Installers) has not passed yet.
Device never appears. Confirm the target device can reach the configured communication server from its network. A curl or Test-NetConnection against the server address from the device is the fastest check. See Troubleshooting for deeper diagnostics.
Installer fails with permission errors. Re-run as Administrator (Windows) or sudo (Linux / macOS). The installer registers a service, which requires elevation on every supported OS.
The device appears in the wrong tenant or location. The installer carries the tenant and location it was downloaded for. Download the server_config.json of the correct tenant and location from Agent Installers (Manual: configuration file) and re-run the installer with clean "<path-to-server_config.json>" to reconfigure in place.
Devices deployed from one image share one device row or take over each other's row. The image was sealed with the agent installed, so every clone carries the same server_config.json and shares one access key; without sysprep /generalize (on Linux, a cleared /etc/machine-id) the clones also share the hardware ID. Uninstall the agent before sealing an image, generalize the image, and install the agent on each clone after provisioning; see Hardware ID.
Installer aborts at the connectivity check on a device behind an HTTP proxy. The installer reports that the update or trust server connection failed and exits with code 1. In a proxy-only network there is no direct route for the check to take. Re-run the installer with --proxy http://host:port (plus --proxy-auth / --proxy-user / --proxy-pass when the proxy authenticates) as described in Devices behind an HTTP proxy. A message about the proxy answering with 407 means the proxy was reached but rejected the credentials.
Installer fails on a Linux NAS or appliance distro. Some Linux distributions, notably those on NAS systems such as Synology, restrict or block execution from the default temporary directory. The installer cannot stage its files there and fails early. Re-run the installer with --temp <path> / -t <path> pointing at a directory the system permits execution from (a path on a regular data volume, for example), then retry.
NetLock RMM supports single sign-on via OpenID Connect. This guide covers the two most common providers, Azure AD (Microsoft Entra ID) and Google, as two short sub-flows on the same configuration page. SSO is the only area in the product where saving a settings change restarts the Console, and user accounts have to exist before their first SSO sign-in; see Before you start.
NetLock RMM signs users in with OpenID Connect (OAuth 2.0) only. SAML 2.0 is not supported, so there is no SAML metadata file to download from the Console and none to upload to it.
This matters most on the Azure side, because Microsoft Entra ID presents SAML as the default path. Register NetLock RMM under Microsoft Entra ID → App registrations. Do not use Enterprise applications → Single sign-on → SAML. The metadata file you may be looking for is created there, and an application configured there cannot be used for OpenID Connect sign-in.
The same applies to the other providers: create an OIDC — Web Application in Okta and a Regular Web Application in Auth0, not their SAML equivalents.
If your identity provider speaks SAML only, you need a federation layer that translates SAML to OIDC between it and NetLock RMM.
One provider at a time. Only one SSO provider can be enabled. Turning one on automatically turns the others off.
Users must be pre-provisioned. SSO login does not create accounts. Every SSO user must already exist in Users with Auth Mode set to SSO or Password & SSO. The NetLock username must match the email claim the provider returns. When the username is matched against the email claim, the address has to be verified at the provider: if the provider reports it as not verified (email_verified is false), the sign-in is refused. Providers that do not send email_verified, such as Microsoft Entra ID by default, are not affected.
Saving restarts the Console. Confirming the save restarts the application and ends all active user sessions.
No paid plan required. SSO is available on every NetLock RMM deployment and is not reserved for a paid tier. Signing in via SSO does require the deployment's licence to be in a valid state, the same condition that applies to the Console as a whole. A banned, expired or deactivated licence blocks SSO sign-in along with everything else.
Required permissions for this guide: settings_enabled, settings_sso_enabled.
For every user who should sign in via SSO, open or add their account.
In the Add / Edit User dialog, set Auth Mode to SSO (SSO only) or Password & SSO (either method). Make sure the username matches the email address the identity provider will return as the email claim. While you test, Password & SSO keeps password sign-in available, so you cannot lock yourself out if the SSO login needs troubleshooting.
Save.
If you skip this step, every SSO sign-in attempt is rejected with User is not authorized for SSO login. Please contact your administrator..
Open the Microsoft Entra admin center and go to Microsoft Entra ID → App registrations → New registration. Do not use Enterprise applications → Single sign-on; see the SAML note above.
Give the registration a name, for example NetLock RMM.
Under Redirect URI, select the platform Web and enter https://<your-console-host>/signin-oidc. Replace <your-console-host> with the exact address your users open the Console at, including the port if you run on a non-standard one. /signin-oidc is the default Callback Path on the Azure AD tab; if you change it there, change it here too. The Azure AD tab shows this URI with a copy button.
Register the application, then open Authentication and add https://<your-console-host>/signout-callback-oidc as the Front-channel logout URL. This matches the default Signed Out Callback Path.
On the Overview page, record the Directory (tenant) ID and the Application (client) ID.
Go to Certificates & secrets → New client secret, create a secret and copy its Value. Copy the Value, not the Secret ID. The Value is shown only once and cannot be retrieved afterwards.
Toggle Enable Azure AD on. The info alert on the page reminds you that enabling one provider disables the others.
Fill in the required fields:
Instance: for example https://login.microsoftonline.com/.
Domain: for example your-domain.onmicrosoft.com.
Tenant ID: from the Azure portal.
Client ID: from the Azure portal.
Client Secret: from the Azure portal.
Callback Path: typically /signin-oidc.
Signed Out Callback Path: typically /signout-callback-oidc.
Response Type: typically code.
Save Tokens: optional, enable if downstream flows need the provider tokens.
Click Save.
A confirmation dialog warns: The web console will automatically restart after saving the SSO configuration. All active user sessions will be terminated. Do you want to continue?. Confirm.
The Console restarts. Wait a moment and sign back in. The SSO option should appear on the login page.
If the Console runs behind a reverse proxy that terminates HTTPS but does not forward the X-Forwarded-Proto header, also enable Force https in redirect URLs at the top of the SSO page before saving. Without it the redirect URL is built from the internal http scheme and Azure rejects it as a redirect URI mismatch.
In Google Cloud Console, create an OAuth 2.0 Client ID of type Web application. Add an authorised redirect URI constructed as https://<your-console-host>/<callback-path>. For Google the default Callback Path is /signin-google, giving https://<your-console-host>/signin-google.
Record:
Client ID.
Client Secret.
If you want to restrict sign-in to a Google Workspace domain, note the domain name too.
You cannot find a SAML metadata file. There is none. NetLock RMM uses OpenID Connect, not SAML. Register the application under Microsoft Entra ID → App registrations, not under Enterprise applications → Single sign-on → SAML.
The provider reports a redirect URI mismatch and the URI it received starts with http://. The Console sits behind a reverse proxy that terminates HTTPS without forwarding X-Forwarded-Proto. Enable Force https in redirect URLs at the top of the SSO page and save. The log line SSO | <Provider> challenge names the URI that was sent.
SSO sign-in is refused with a licence dialog. SSO itself needs no paid plan, but the deployment's licence has to be in a valid state. Check Settings → Licensing for a banned, expired or deactivated licence.
Red alert SSO Configuration Error! on the page. The configuration failed to load on startup and SSO is disabled. Re-check all required fields on the active provider tab and re-save.
User sees User is not authorized for SSO login. The account is missing, or its Auth Mode is Password only, or its username does not match the email claim. Fix in Users and have them try again.
The sign-in page reports that the email address of the account is not verified. The provider sent email_verified with the value false for this user. Mark the email address as verified at the provider (in Keycloak: Email verified on the user) and sign in again. The log line SSO | <Provider> email_not_verified names the login name.
Redirect URI mismatch at the provider. The callback path you entered in NetLock must match the redirect URI you registered at the provider exactly, including the leading /.
SSO works at one Console address but not at the other. A cloud instance reached through a custom domain has two addresses, and the redirect URI is built from the one the user opened. Register the redirect URI of both addresses at the provider; the SSO page lists them per tab.
Optional module: This guide assumes the Ticket System is enabled. See Chapter 10 to enable it.
This guide walks through the full loop for a single ticket: create it, triage and assign it, post an internal note, reply to the customer, log time, and close it out. The same steps apply to tickets that arrived via inbound email; only the starting point differs.
The Ticket System is enabled in Settings → Ticket System.
At least one support department exists, with outbound SMTP configured if you want to reply to the customer by email. A ticket without a department, or with a department without SMTP, cannot mail the contact.
Required permissions: tickets_enabled, tickets_create, tickets_edit, tickets_assign. Time-tracking entries additionally require tickets_view_time_tracking on the entry-creator.
Fill in Title (required), Department (preselected with your own department), Priority (defaults to Medium), Contact Email (the autocomplete searches existing contacts; new addresses are accepted), and an optional Description. If entered, the description is stored as an internal note in the Conversation tab; it is not sent to the contact.
To inform the contact right away, check Notify contact by email and write the Message to the contact. Only this message is mailed, with the ticket title and number as subject; the contact's answer is added to the ticket. The checkbox is disabled, with the reason below it, when the department has no SMTP server or the contact email is missing or invalid.
Save. The ticket appears in the list with a generated ticket number and Status = Open.
In the list, click the new row. The detail dialog opens with six tabs: Conversation, Details, Time Tracking, History, Attachments, and, when AI is configured, AI.
Set Assigned To Operator to yourself or the owning operator. This field is gated by tickets_assign.
Optionally set a Type (for example Incident, Request) and add colour-coded Labels for reporting. Edits save in place and are logged in the History tab.
Toggle the composer direction to outbound (the globe icon). Outbound messages are emailed to the contact using the department's SMTP settings. If a hint above the editor says that no email will be sent, fix the named cause (department, SMTP, contact email) on the Details tab and save before replying.
Optionally click the template-picker button to insert a saved response template.
Optionally attach files with Attach; they are mailed with the reply (up to 20 MB in total, otherwise the reply goes out without them and a warning says so).
Pick Rich Text, HTML, or Plain Text mode and send. The toast and the History tab say whether the reply was mailed.
If the department has automatic time tracking enabled, the banner at the top shows the running timer. No action is needed unless it has paused on idle.
Otherwise, expand Add Entry and fill in Date, Start Time, End Time, and optional Notes. Duration is computed. Save.
The customer never received the reply. Outbound replies use the department's SMTP settings, not the global notification SMTP. Check the History tab: Reply saved, not mailed: no department (or no contact email, invalid contact email, department has no SMTP server) means the reply was never sent. Set the department and contact email on the Details tab, save, and reply again. Reply saved, mail to <address> failed means the SMTP server refused the mail; verify the department's outbound SMTP configuration and check the error log (module Tickets.EmailService); see Chapter 10.
The reply arrived without its attachments. The attachments of one reply exceeded 20 MB together. They are on the Attachments tab; send them in smaller replies or share them another way.
The ticket is stuck in Waiting. Every status can be changed to any other status. Open the Details tab and change Status directly.
The web console can be installed as a progressive web app (PWA). Installed, it opens in its own window without browser tabs or an address bar, has its own icon on the desktop, in the Dock or on the home screen, and appears in the task switcher like any other application. Nothing is installed on the server for this: the console publishes a web app manifest, and the browser does the rest.
The app uses the whitelabeling settings of your installation: the app name is the web console title, the theme colour follows the active design, and the icon is either the bundled NetLock icon or an icon you upload. See Brand the Console for the rest of the whitelabeling options.
The web console must be reached over https with a certificate the device trusts. Browsers do not offer to install an app from a plain-http address or from a site with a certificate warning. The console itself still works over http; only the install option is missing.
Any user can install the console; no permission is involved. The install button in the app bar can be hidden deployment-wide under Settings > Whitelabeling > AppBar & Effects (checkbox Install app); the browser's own install option in its menu remains available.
An installed app is a shortcut to your server, not a copy of it. It needs a network connection to the server like the browser does, and there is no offline mode.
Click the Install app icon in the app bar (next to the agent download icon), or use the install icon at the right end of the address bar, or choose Install <title> from the browser menu.
Confirm the browser's prompt. The console opens in its own window and is added to the Start menu, the Applications folder or the app drawer.
On Android, Chrome may show Add to Home screen instead of an install prompt; both lead to the same result.
Chrome and Edge only offer the install once the manifest has been evaluated, which takes a moment after the page has loaded. If the Install app icon does not appear at all, check the address bar for a certificate warning and make sure you are not already running the installed app.
Tap the Share button, then Add to Home Screen, and confirm with Add.
The Install app icon in the app bar shows these steps as well, because Safari has no install prompt of its own. The console then opens from the home screen in full screen.
By default the installed app uses the bundled NetLock icon. To use your own:
Open Settings > Whitelabeling, tab Web Console Logo, section App icon.
Select a PNG of exactly 512 × 512 pixels (at most 1 MB). The console checks the file header and the pixel size and does not rescale; a file of another size is rejected with a message.
Click Save. The manifest and the icon endpoints switch to the new icon immediately; Revert to default restores the bundled icon.
Keep the important part of the artwork inside the inner 80 % of the square: Android and some desktop launchers mask the icon to a circle or a rounded square. For the home screen on iOS, use an opaque background — iOS renders transparent areas of the icon as black.
Devices that already have the app installed keep the icon they installed with. To pick up a new icon, remove the app and install it again. iOS in particular caches the home-screen icon aggressively.
Sign-in on every cold start. The console keeps the session inside the live connection, not in a cookie. Closing the app window and opening it again shows the sign-in page, exactly as a new browser tab would. Passkeys make this quick.
Reconnecting. If the connection to the server drops, the standard "Attempting to reconnect" overlay appears. When it cannot reconnect, reload the app (the overlay offers a reload); this leads to the sign-in page.
No back button. The standalone window has no browser toolbar. Navigate with the console's own menu; on Android the system back gesture still works.
External links such as the documentation, GitHub or a public file link open in the default browser, not inside the app window.
Updates. The app is the live console; a server upgrade is visible on the next reload. Nothing has to be reinstalled on the device.
Self-hosted only: This guide applies to self-hosted deployments. Cloud customers do not install the server — the hosted platform is run for them.
This guide covers installing the NetLock RMM server and Web Console with Docker. Both can run in the cloud or in an offline environment, depending on your requirements. Two methods are described: a guided installer that generates the setup for a standard server, and a manual Docker Compose setup for full control.
Agents only make outgoing connections, so no port forwarding is required on the managed machines. The Web Console renders content server-side and sends it to the administrator's browser, so a persistent connection between the Web Console and the administrator is required during operation.
The Web Console communicates either directly with the SQL server or, for real-time features such as the remote shell and file browser, with the NetLock Remote Server over SignalR. Make sure the Web Console can reach the NetLock Remote Server.
Warning: The Web Console should only be reachable from trusted networks.
NetLock RMM can be deployed in any environment with Docker support, including setups behind Cloudflare tunnels and similar. The guided script builder targets typical server installations.
For help deploying NetLock RMM in non-standard environments, contact the support team.
MySQL Server 8.4 LTS (the compose file below uses mysql:8.4). MySQL 8.0 still runs, but Oracle support ended on 30 April 2026 — see Upgrade MySQL to 8.4.
2 CPU cores — more may be needed depending on how many agents you monitor.
8 GB RAM.
Note: The 8 GB RAM requirement supports the high-performance, memory-optimised update delivery. With insufficient RAM the setup may fail, or NetLock RMM may run slowly because it falls back to swap space. 8 GB is enough for about 2,000 devices.
The Docker images are published under the latest tag.
Warning: The database name, password, domains, time zone, Let's Encrypt email address (acme.email), and Members Portal API key in the templates below are examples. Use your own email address for Let's Encrypt and replace every other value with values for your own environment before deploying.
Adjust the values to match your environment. On the first start the key from ApiKeyOverride is stored in the database; to replace it later, use Settings → Licensing (see Replace the Members Portal API key). Likewise, the URL from PublicOverrideUrl is stored in the database on the first start; to change it later, use Settings → Overview (see Public backend URL). The address of the web console itself is not part of this file: set it under Settings → Overview after the first sign-in, otherwise ticket webhooks and notification mails contain no link to the ticket (see Public console URL).
Both application containers run as the unprivileged user with id 1654. Give that user ownership of the two data directories, including the appsettings.json files you just created:
Note: Traefik v3 stops reading a request after 60 seconds by default (respondingTimeouts.readTimeout). That cuts off large uploads from agents and through the web interface access before they finish. The two readTimeout=24h lines in the Traefik command: block above raise the limit to 24 hours. Existing installations add both lines to the Traefik command: in their docker-compose.yml and recreate the container with docker compose up -d traefik.
Note: Existing installations that still run image: mysql:8.0: Oracle support for MySQL 8.0 ended on 30 April 2026, and the Web Console shows a notice for it. Upgrade MySQL to 8.4 walks through changing the tag on an existing data directory, including the backup and the options to check.
The server and Web Console images contain no shell and no package manager, and their application files are read-only. Both applications are meant to run as the unprivileged user with id 1654. A small entrypoint decides at every container start which user the application runs as and writes its decision to the container log, each line prefixed with [entrypoint].
An installation created with the guided installer or with the steps above sets user: "1654:1654" on both application services and gives user 1654 ownership of /home/netlock/web_console and /home/netlock/server. The containers run as user 1654 from the first start, and the log shows:
[entrypoint] running as uid 1654 (set by the container configuration), starting the application
What happens at the first start of a 3.3.0.11 or newer image depends on the capabilities the compose file grants to the container.
Compose file from this manual guide (Docker's default capabilities). The container starts as root, takes ownership of the mounted data directories (/app/internal, the log directory and, for the server, the file storage) and of the mounted appsettings.json, then switches to user 1654 on its own. On the host, the mounted directories and the two appsettings.json files under /home/netlock/web_console and /home/netlock/server are owned by user 1654 afterwards. The ownership pass runs at every start and only touches entries that are not owned by 1654 yet. Any entry inside the data directories that cannot be taken over (for example a nested mount from another filesystem) keeps the container on root, and the log names it (see Other reasons the container keeps running as root). The log shows:
[entrypoint] ownership: 1234 entries checked, 1200 changed, 0 errors, 12 ms[entrypoint] switched to uid 1654 gid 1654, starting the application
Compose file from the guided installer (cap_drop: ALL). Nothing changes: the container keeps running as root, and the log shows how to switch:
[entrypoint] the container was started without the chown/dac_override/setuid/setgid capabilities, so the application keeps running as root[entrypoint] to run it unprivileged, run once on the host: sudo chown -R 1654:1654 <host directories behind the mounts; guided installation: /home/netlock/web_console and /home/netlock/server>[entrypoint] then add user: "1654:1654" under both NetLock services in the compose file and recreate the containers
To switch such an installation, give user 1654 ownership of the two data directories once:
sudo docker compose -f /home/netlock/docker-compose.yml up -d
The same two steps apply to an installation from this manual guide that should start as user 1654 directly instead of switching at every start.
Warning: With user: "1654:1654" in the compose file, do not use an image older than 3.3.0.11. Those images expect to start as root, and the Web Console does not start as user 1654. Remove the two user: lines before going back to an older image.
If Https is enabled in an appsettings.json and the certificate file lies in /home/netlock/certificates, the file must be readable for user 1654. Before it switches users, the entrypoint checks every file directly in /app/certificates. When one of them is not readable for 1654, the container keeps running as root and names the file:
[entrypoint] file "/app/certificates/certificate.pfx" is not readable for uid 1654; run on the host, inside the directory mounted at "/app/certificates": chmod 640 "certificate.pfx" && chgrp 1654 "certificate.pfx"; the application keeps running as root
A symbolic link is followed and checked at its target; the hint then names the target. A link whose target cannot be opened, for example because it points outside the mounted directory, keeps the container on root as well:
[entrypoint] file "/app/certificates/certificate.pfx" (symbolic link to "renewed/2026-10.pfx") is not readable for uid 1654; run on the host, inside the directory mounted at "/app/certificates": chmod 640 "renewed/2026-10.pfx" && chgrp 1654 "renewed/2026-10.pfx"; the application keeps running as root[entrypoint] file "/app/certificates/old.pfx" is a symbolic link to "/nonexistent/old.pfx", which cannot be opened: No such file or directory; the application keeps running as root
Make the file readable for the group 1654 and restart the container:
The directory itself must be accessible for user 1654 as well (chmod 755 /home/netlock/certificates). Leave /home/netlock/certificates/traefik as it is: Traefik's certificate store lives in that subdirectory, which the entrypoint neither reads nor changes, and it stays owned by root.
With user: "1654:1654" in the compose file there is no such check: the application cannot load an unreadable certificate file and stops, which the container log reports.
The environment variable NETLOCK_RUN_AS_ROOT=1 on a service keeps the application running as root regardless of the capabilities the compose file grants:
The log then shows [entrypoint] NETLOCK_RUN_AS_ROOT=1 is set, starting the application as root. Use it as a temporary measure while you investigate a start problem, and remove it afterwards. With user: "1654:1654" set, the container never starts as root and the variable has no effect.
In each of the following cases the application runs as root; the log names the cause, and the next start switches once the cause is fixed.
The Docker engine does not allow an unprivileged user to bind the port (engines older than 20.10, or network_mode: host): [entrypoint] the kernel does not allow unprivileged binding of port 80 on this engine (ip_unprivileged_port_start=1024), the application keeps running as root.
An entry inside a data directory could not be taken over, for example a nested mount from another filesystem or a file the kernel refuses to change: [entrypoint] ownership: 3 entries could not be taken over (first: "/app/www/private/files/archive"), the application keeps running as root. The line follows the ownership summary and names the first such entry.
A data directory itself or the appsettings.json is still not owned by user 1654 after the ownership pass, for example on a network file system: [entrypoint] "/app/internal" is still owned by uid 0 gid 0 after the ownership pass, the application keeps running as root.
The engine does not let the container change its group list (some user-namespace setups): [entrypoint] cannot clear the supplementary groups: Operation not permitted, the application keeps running as root.
The certificate directory is not accessible for user 1654: [entrypoint] directory "/app/certificates" is not accessible for uid 1654; run chmod 755 "/app/certificates" on the mounted host directory, the application keeps running as root.
The images contain no shell, so docker exec -it <container> sh into the server or Web Console container is not possible. Use docker logs <container> for the application output and the entrypoint messages, and the mounted log directories (/home/netlock/web_console/logs and /home/netlock/server/logs) for the log files.
The server and Web Console images contain no shell, so a container cannot be entered with docker exec; the log files are in the mounted log directories on the host (see Troubleshooting without a shell).
The NetLock RMM server runs in seven roles. Each is toggled in the server's appsettings.json under the Roles block; a single instance can run all of them, or they can be split across multiple instances.
Role
Purpose
Comm
Handles communication with the comm agent — device information, policy, and event synchronisation.
Update
Provides update packages for the agents — comm agent, health agent, remote agent, installer, and uninstaller.
Trust
Provides the hashes of all update packages. Agents contact the trust role to verify the hash of a downloaded package.
Remote
Handles real-time connections between agents and the Web Console, such as the remote shell and file browser.
Notification
Sends third-party notifications — email, Microsoft Teams, Telegram, and ntfy.sh.
File
Provides the file storage service for downloading and uploading files.
LLM
Provides the AI language-model integration for the intelligent features.
The Docker Compose setup above runs every component — the reverse proxy, MySQL, the Web Console, and the NetLock RMM server — on a single host. This is the recommended starting point and is sufficient for most deployments.
Note: If you replace Traefik with another reverse proxy, it must forward request headers unmodified. nginx drops header names containing underscores unless underscores_in_headers on; is set in the server block.
For larger fleets or specific infrastructure requirements, the three main components can instead run on separate servers: the MySQL database, the NetLock RMM server (the backend), and the Web Console.
The components communicate over the network, so nothing forces them onto the same machine. Each one is pointed at the others through its appsettings.json:
The Web Console's MySQL block addresses the database server, and its NetLock_Remote_Server and NetLock_File_Server blocks address the backend.
The server's MySQL block addresses the database server.
In the single-host Compose setup these settings use Docker container names (mysql-container, netlock-rmm-server) because every component shares one Docker network. In a distributed setup, you replace those with the hostnames or IP addresses of the separate servers.
Splitting the deployment this way lets you size and scale each component independently — for example, running MySQL on dedicated database infrastructure, or keeping the Web Console and the backend on separate hosts.
NetLock RMM can monitor an SNMP-capable device (a switch, firewall, NAS, UPS, printer, or access point) without installing an agent on it. Instead, an installed NetLock RMM agent on the same network polls the SNMP target on your behalf.
The chain has four parts: an SNMP device (the target definition with address and credentials), an SNMP sensor (what to poll and, optionally, when to alert), a policy the sensor is attached to, and an automation that routes that policy to the agent doing the polling.
Note: The SNMP target itself never runs NetLock RMM software. The polling is done by an ordinary managed device, a Windows, Linux, or macOS machine with the agent installed, that can reach the target on UDP port 161.
The sensor decides what to poll on the target. Open Collections → Sensors, choose Add, and set Category to SNMP. Then pick the SNMP Type. This is the most important choice:
SNMP Type
Purpose
SNMP GET (Alert)
Polls one OID and alerts when its value crosses a threshold.
SNMP Walk (Alert)
Walks an OID subtree and alerts if any returned value crosses a threshold.
SNMP Monitor (Data Collection)
Polls a list of OIDs and collects the readings for display. It does not alert.
For every type, select the SNMP Device you registered in Step 1. The sensor takes the target's address and credentials from it.
For SNMP GET and SNMP Walk:
OID: the object identifier to query. The MIB Browser (the tree icon) helps you locate one.
OID name: an optional friendly label.
Condition and Threshold value: when the sensor should trigger (equals, greater than, less than, contains, regex match, and so on).
Max Walk Results: for Walk only, a cap on how many returned values are evaluated.
Notification and action thresholds, and an optional action script. These behave the same as for any other sensor (see Chapter 8.3).
Numeric conditions (greater than, less than) compare the value as a number with a dot as decimal separator. Some devices, many BMCs among them, send floating-point and 64-bit readings as Net-SNMP opaque values. The agent decodes these to plain numbers automatically (shown with a type such as Opaque/Double), so thresholds work on them as on any integer value; the sensor event also lists the raw hex value. Opaque values in any other format are shown as hex and only match text conditions.
For SNMP Monitor:
Add the OIDs to collect, each with a method (get or walk), the OID, and a display name. The preset buttons (System Info, Interfaces, Storage) add common OID sets in one click.
Monitor sensors only gather data and have no thresholds or actions.
Set the sensor's Platform to match the agent that will do the polling, then save.
Note: A sensor copies the SNMP device's address and credentials when it is created. If you later change those details on the SNMP device, re-open and save each sensor that targets it so the change is picked up.
A sensor only runs when a policy carries it. Open the policy assigned to your polling agent, go to the Sensors tab, and enable the SNMP sensor. See Chapter 6 for the policy editor.
A policy only reaches a device through an automation. Make sure an automation routes the policy from Step 3 to the managed device that will poll the SNMP target. See Chapter 5 for the automation model.
Once the policy is assigned, the agent polls the SNMP target on the sensor's schedule.
For a GET or Walk sensor: when the condition is met, an event is raised and any configured notification or action runs. Check Events (see Chapter 12).
For a Monitor sensor: the collected readings appear on the SNMP device's detail panel in the SNMP view of the Devices page, and the device's status and last-seen time update automatically.
Separate from sensors, SNMP Tools runs a one-off SNMP query through an agent. Use it to test an OID or confirm reachability before building a sensor. Open a managed device's detail view, choose SNMP Tools, and run a GET or Walk against any target IP.
SNMP Tools requires the devices_snmp_tools permission and the SNMP Tools toggle on the policy's Agent tab (which depends on remote service being enabled; see Chapter 6). It supports SNMP v1 and v2c only.
No data and no events. Confirm the polling agent can reach the target on UDP port 161. A firewall between them is the most common cause. The SNMP Tools check above is the quickest way to test reachability.
Authentication failures. Re-check the community string (v1 / v2c) or the v3 username and auth / privacy settings. The target must also permit SNMP read access from the agent's IP.
The sensor never runs. Confirm the sensor is enabled on a policy and that an automation routes that policy to the polling agent. Both are required.
Wrong OID. Use the MIB Browser when building the sensor, or SNMP Tools to walk the target, to confirm the OID returns the value you expect.
NetMesh makes a TCP service on (or behind) one device reachable through a local port on another device. File shares use SMB on TCP port 445. This guide explains which local port to use, how to connect from Windows, Linux and macOS, and what the console tells you when the local port cannot be opened.
The device that opens the local port and connects is the client device (in a service network: a consumer). The device the share runs on, or that reaches the file server, is the service device (in a service network: the publisher).
Required permissions: netmesh_enabled and netmesh_add (create a link or service), netmesh_edit (change one).
The file share itself works on the service device or on the file server behind it. NetMesh passes the SMB traffic through unchanged, including SMB signing and encryption.
On Windows, the built-in file sharing (the "Server" service, which runs in the kernel) always listens on TCP 445, and on 139 for NetBIOS. No other program can open these ports, also not on 127.0.0.1 or on a service network's 127.x.y.z address. A link with local port 445 on a Windows client device therefore stays in the status Port not available. A jump host does not change this: it only changes where the service device connects to, the client device still tries to open 445 locally.
On Linux and macOS, 445 works as long as no local Samba server or macOS "File Sharing" uses it.
Use a different local port, for example 1445. The SMB preset of a service network proposes 1445 for this reason.
Choose the client device and the service device, and pick the SMB service (service port 445). If the share is on another server in the service device's network, enter that server as the target host.
Set Local port to 1445 and Listen on to Only this device (127.0.0.1).
Save and wait until the link shows as established.
On the client device, open an elevated command prompt or PowerShell and connect:
Connecting to an SMB server on another port is only possible from Windows 11 24H2 and Windows Server 2025 on. Administrators can control it with the group policy Computer Configuration > Administrative Templates > Network > Lanman Workstation > Enable alternative ports. Explorer and a plain \\host\share path always use port 445; the alternative port is only available through net use /TCPPORT and New-SmbMapping -TcpPort.
Note: If the mapping fails, check the GPO above and that the link shows as established.
A service network gives each service a hostname that points to a 127.x.y.z address on the consumer. On Windows, connect to a file share through a manual link on 127.0.0.1 as described above.
Warning: When the local port of a service network cannot be opened on a Windows consumer, its hostname still points to the 127.x.y.z address, and Windows' own file sharing answers there. Opening \\hostname then lands on the consumer itself: you see its own shares or get a sign-in error. Fix the local port first.
Windows 10 and Windows 11 before 24H2, as well as Windows Server 2022 and older, cannot connect to SMB on another port. Alternatives:
Copy the files with the file transfer of the remote session, or use RDP over NetMesh and work on the service device.
Use a Linux or macOS device as the client device.
Stopping the Windows "Server" service (LanmanServer) frees port 445, but it also disables the administrative shares (C$, ADMIN$), printer sharing and parts of remote management on that device. This is your own decision and not recommended.
Through 127.0.0.1 or a service network hostname, Windows cannot use Kerberos for the file server and falls back to NTLM. When NTLM is blocked on the client device (an option from Windows 11 24H2 on, off by default), the connection fails. Kerberos works when the client device reaches the share under the file server's real name, for example through a hosts-file entry in a domain.
When a link cannot open its local port, the link shows Port not available on the NetMesh page. The link details show the operating system's message and, with a current agent, a hint with the reason:
Hint
Meaning
What to do
Another program uses the port
A program or service on the client device already listens on the local port.
Choose a different local port.
Windows reserves the port
The port lies in an excluded port range on Windows, typically reserved by Hyper-V, WinNAT or Docker.
Choose a different local port. List the ranges with netsh int ipv4 show excludedportrange protocol=tcp.
Port used by the NetLock agent
Ports 7337 and 7338 are reserved for the NetLock agent.
Choose a different local port.
Windows file sharing holds the port
Local port 445 or 139 on a Windows client device.
See the sections above.
With the netmesh_edit permission, the hint offers Change local port. For a manual link it opens the link; for a service network it opens the service. A service's local port applies to all consumers of the service, so a conflict on one consumer means changing the port for all of them.
After the change, the application on the client device must connect to the new port: for example net use ... /TCPPORT:<port>, mount -o port=<port>, or the port in the application's connection settings.
Note: The reason hints need a current server and a current agent on the client device. Without them, the console shows the operating system's message, and for port 445/139 on Windows the file-sharing hint.
Self-hosted only: This guide applies to self-hosted deployments. On cloud, you have no host or database access — contact NetLock RMM support to regain access to your Console.
Use this guide when you forgot your Console password and no other account can reset it for you. You set the account's password to a known temporary value directly in the database and mark it for a forced password change. At the next sign-in, the Console asks you for a new password.
Tip: If another account with users_edit can still sign in, it can reset your password in the Console instead: Users → User Settings → Reset Password (see Reset Password). You do not need this guide then.
You need:
Shell access with sudo on the host that runs the NetLock RMM containers.
The username of the account. The Console signs you in by username, not by email address.
The database credentials. The Console's appsettings.json is stored encrypted, so read them from the Docker setup instead. Option A reads them from the container automatically. For Option B, print them with:
MYSQL_ROOT_PASSWORD is the password of the database user root, and MYSQL_DATABASE is the NetLock RMM database.
Note: The root password from the compose file only applies when the database is first created. If someone changed the root password later, use the current one. Installs from the guided installer also have a dedicated database user; its name and password are in /home/netlock/mysql/init/01_create_app_user.sql.
The temporary password hash used below is the BCrypt hash of the password admin:
If your container has a different name, list the names with sudo docker ps --format '{{.Names}}'.
List the accounts and note the username and state of yours:
SELECT id, username, mail, auth_mode, enabled, two_factor_enabled FROM accounts;
Set the temporary password and the forced reset. Replace your-username with the username from step 2:
UPDATE accounts SET password = '$2a$11$KIDo.90Gv0jaEOi8ZH.JYuQzrD3YXlptkL0hIKABtxB5UqcNZbNWy', reset_password = 1 WHERE username = 'your-username';EXIT;
Note: Type the statement at the MySQL prompt. Do not pass it on the command line with mysql -e "...": inside double quotes the shell replaces $2a and $11, and the stored hash no longer matches admin.
Use this option if you prefer a graphical database tool such as HeidiSQL. The steps use HeidiSQL; DBeaver or MySQL Workbench work the same way. The database port is published on the host's loopback address only, and you reach it through SSH.
Open the compose file:
sudo nano /home/netlock/docker-compose.yml
Under the mysql: service, add the following block, indented like volumes::
ports: - '127.0.0.1:3306:3306'
Warning: Bind the port to 127.0.0.1 only. A plain '3306:3306' publishes the database on every network interface, and Docker's published ports bypass host firewalls such as ufw. Your database would then be reachable from the internet.
Note: Installs set up with the installer's external MySQL access option already publish port 3306 under mysql:. In that case, skip this step, step 2 and step 5.
Restart the stack:
sudo docker compose -f /home/netlock/docker-compose.yml down && sudo docker compose -f /home/netlock/docker-compose.yml up -d
On hosts with the standalone binary, use docker-compose instead of docker compose.
Connect through SSH. In HeidiSQL, create a session with the network type MariaDB or MySQL (SSH tunnel):
On the SSH tunnel tab: the server address, your SSH user and your SSH key or password.
On the Settings tab: host 127.0.0.1, port 3306, user root and the MYSQL_ROOT_PASSWORD value.
For any other tool, open the tunnel yourself with ssh -L 3307:127.0.0.1:3306 your-ssh-user@your-server and connect the tool to 127.0.0.1, port 3307.
Open the NetLock RMM database (the MYSQL_DATABASE value), then the accounts table, and find the row with your username:
Warning: Until you finish this step, the account accepts the publicly known password admin. Sign in right after the database change and choose a strong new password.
Open the Console and sign in with your username and the password admin.
The Console shows Choose your new password. Enter a strong new password twice and confirm.
You are then signed in. All other sessions of the account end, and the Audit log records Password reset (forced).
The password reset does not change any other sign-in requirement. Check the SELECT output from Option A, or the account row in Option B, and run the matching statement the same way as the UPDATE above. Replace your-username with your username.
State
Effect
Fix
auth_mode is SSO
Password sign-in is refused with Incorrect user name or password.
UPDATE accounts SET auth_mode = 'Password & SSO' WHERE username = 'your-username';
enabled is 0
The account is suspended; sign-in is refused with the same message.
UPDATE accounts SET enabled = 1 WHERE username = 'your-username';
2FA is on and the authenticator is lost
The Console asks for the 2FA code before the password change.
UPDATE accounts SET two_factor_account_secret_key = '', two_factor_secret_encrypted = 0, two_factor_last_step = 0 WHERE username = 'your-username'; — 2FA stays on, and you enrol a new authenticator at the next sign-in.
The account has a passkey that is lost
The Console asks for the passkey after the password.
DELETE FROM account_passkeys WHERE account_id = 42; — replace 42 with the id of your account.
Too many failed attempts
Sign-in is blocked temporarily.
Wait 60 minutes, or restart the Web Console with sudo docker restart netlock-rmm-web-console. The Option B restart clears it as well.
Note: If MySQL reports Unknown column, skip that fix.
Self-hosted only: This guide applies to self-hosted deployments. On cloud, the hosted operations team manages licensing.
If a licence ran out before the renewal was paid, the deployment can still show the old, expired licence after the payment went through, or keep reminding you that the licence expires. The server and the Web Console each keep the licence they last loaded in a local file and keep using it while it is still within its grace period. The Refresh License Information button on Settings → Licensing only updates the Web Console; the server loads its licence when it starts.
To make both services load the renewed licence, delete their licence files and restart the containers. The API key stays the same.
If the status is still Expired, check in the Members Portal that the renewal is active for this API key, and that the host can reach the Members Portal.
The Relay App is a desktop program for the operator's machine. Besides the relay tunnels of Chapter 9.2, it controls the screens of managed devices from its Screen Control tab, without a browser. NetLock RMM does not use VNC or RDP for this: the agent streams the device's screen as JPEG frames over the NetLock server, exactly as for the remote control window of the web console. This guide installs the app, opens a session and walks through the controls of the remote control window.
A relay API key. Create it on the Relay Server page under Manage API Keys (permission relay_server_manage) and switch Screen control on for that key. The key belongs to your account; every screen session opened with it runs under that account.
Permissions of the account that owns the key:devices_remote_control and access to the device's tenant. Pasting files additionally needs devices_remote_file_browser.
The device is online. A macOS device needs agent 3.3.0.11 or later; a Linux device needs the packages of X.8.5.
The policy of the device allows remote screen control (Policy > Tray Icon > Remote Screen Control); whether the user has to accept the session is decided there as well.
The Relay App runs on the operator's machine — the technician who opens the session — not on the target device. Download it from https://netlockrmm.com/downloads, pick your OS and architecture, and unzip it.
The Relay App brings its own runtime, so nothing else has to be installed. On a Mac it needs macOS 12 or newer.
The Relay App ships with nine interface languages: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese and Chinese (Simplified). On first start it follows the operating system's display language and falls back to English when that language is not among the nine. Change it in the dropdown on the login screen or in the header of the sessions window, next to the theme buttons; the choice applies immediately, without restarting the app, and is remembered on that machine. Date, time and number formats keep following the operating system's regional settings and are not affected by this setting.
Start the Relay App. On the first start enter the Backend Server URL, the API key and a password that encrypts the stored credentials on this machine, then Save & Connect. Later starts ask for that password only.
Open the tab Screen Control in the sessions window. It lists the devices the key may control; search by name and filter the list as needed.
Select the device and click Connect. The remote control window opens.
Pick the user session. With exactly one active session the window starts it by itself; with several it offers them with the console session preselected; with none it offers Connect anyway.
If the policy requires it, the user on the device accepts the request. The prompt on the device shows your name and, if you released your profile picture for end users, your picture — taken from the account that owns the key.
On a Linux Wayland device, the first connection shows the desktop's screen-sharing dialog on the device. The window says "Waiting for the user to accept screen sharing on the device." until someone at the device accepts it, then "Starting the screen capture on the device." until the picture arrives. Later connections are silent. See X.8.5 when this does not get past one of these states.
On a device with endpoint protection, screen control needs an approval on a registered phone first (A.13.10). The request goes to the phone of the account that owns the key, and the window shows "Confirm the approval in the NetLock app on your phone." while it waits. When that account has no registered phone, the request goes to the approvers of the device instead and the window shows "Waiting for an approver of this device to confirm the request in the NetLock app."Cancel ends the attempt. After the approval the session starts as usual; a rejection, a request that nobody approved in time, or a device no phone may approve for is named in the window. An active work session of the account covers screen control without a request.
Stream mode.Mode with Quality, Balanced (default), Performance, Auto and Custom, Advanced for frame rate, quality and chroma, Stats for the statistics panel. The choice is kept for the next sessions. See A.7.5.
Zoom.Fit fits the picture into the window; + and − step through 25 % to 300 %, and so does Ctrl+wheel (Command+wheel on a Mac). Zoomed in, scroll bars and the middle mouse button move the picture. The zoom wheel never reaches the device.
Full screen.F11 or the Full screen button. The toolbar stays visible. Esc goes to the device, so leave full screen with F11 or Exit full screen.
Mouse and keyboard. The pointer reaches the device while it moves over the picture, also without a pressed button. Ctrl and Shift go with clicks and the wheel; a horizontal wheel scrolls sideways on the device. See A.7.8.
Recording. The red REC chip shows a running recording, REC (forced) one that the setting Force session recording enforces. The recording button starts and stops a recording of your own; a forced recording cannot be stopped. See Recording in the viewers.
Clipboard. With the Clipboard checkbox on, Ctrl+V pastes your clipboard's text and Ctrl+C takes the device's. View remote clipboard shows the device's clipboard without changing it. See A.7.6.
Paste files. Drop files onto the picture, press Ctrl+V with files copied in your file manager, or use Send files. The window confirms once, shows the progress of every file and reports what the device did with them. Up to 100 files and 10 GB per transfer, no folders; it needs the agent 3.3.0.11 or later on the device and devices_remote_file_browser. See A.7.10 for what Windows, macOS and Linux devices do with the files.
Screenshot.Screenshot copies the current picture to the clipboard, Save as… writes it as a PNG file.
Session and screen. The user and screen pickers switch between user sessions and monitors; Send Text types a text as keystrokes, Elevate starts an elevated user process on a Windows device.
"Another technician is already connected to this device." Another viewer already holds a screen session on the device. The session still starts; agree with the other technician who works.
The session does not start. The window names the reason: device offline, device not found, other tenant, or Remote control is not allowed for this relay key or account when the key's Screen control switch is off or the account lacks devices_remote_control. The server cannot process the request right now means the server could not read the device's data; try again in a moment.
"Waiting for the first picture from the session." The device answers but sends no picture. When "The agent on the device may need an update." follows, update the agent.
"The remote screen is showing a black picture." The display of the device is off or the selected session draws nothing. Wake the display, or use Switch session to pick the session that owns the screen.
No signal. The last picture stays dimmed with the reason. Press Retry, or Switch session. On Linux and macOS devices the reason often names a missing permission or package; see X.8.5 and X.8.6.
Connection lost. After a short loss the window reconnects by itself and returns to the same user session and screen. It gives up after about two and a half minutes.
Self-hosted only: This guide applies to self-hosted deployments. On cloud, the hosted operations team manages licensing, so there is no API key to change and the Licensing page is not shown.
The Members Portal API key is the credential the server and the Web Console use to fetch your licence and the agent packages. You replace it on the Licensing page in the Console (see A.1). The Console checks the new key against the Members Portal and stores it encrypted in the database; the web console and the server start using it after they have been restarted.
A Console account with settings_enabled, settings_licensing_enabled and settings_licensing_manage (see X.2). Accounts that can manage user permissions receive settings_licensing_manage automatically.
Shell access to the host running the NetLock RMM containers, for the restart.
A short maintenance window: both services restart, and the server downloads the agent packages for the new key during its start.
In API Configuration, paste the key into New API key.
Click Replace API key and confirm.
The Console checks the key against the Members Portal before saving it. A key the Members Portal does not accept (unknown, or belonging to a banned, expired or inactive membership) is not saved, and the page shows the reason. If the Members Portal cannot be reached, the Console asks whether to save the key anyway. Only do so if you are sure the key is correct: with a wrong key the server cannot load its licence after the restart.
After saving, the page shows Restart required together with the last four characters of the new key. Until the restart, the web console and the server keep working with the current key.
You can also set the key in the configuration files. Both files are stored encrypted, so you replace their entire content:
Stop the services: cd /home/netlock and sudo docker compose down.
Replace the entire content of /home/netlock/web_console/appsettings.json and /home/netlock/server/appsettings.json with your plain JSON configuration, with the new key in Members_Portal_Api → ApiKeyOverride.
Start the services: sudo docker compose up -d.
On start the files are encrypted again. A key entered into appsettings.json this way takes precedence over the key in the database: it is written to the database, and the licence and packages of the previous key are discarded in the same way as above.
If appsettings.json is mounted read-only, the services cannot write to it, and the key in the file wins on every start. In that setup, change the key in the file rather than on the Licensing page.
A service logs that the stored API key could not be decrypted. The key in the database is protected with Security:Local_Encryption_Key. When this value is set in only one of the two appsettings.json files, that service cannot read the stored key and runs with the key from its own file instead, without changing the database. Set the same value in both files.
If the new licence changes the code-signing entitlement, from a licence without code signing to one with it or the reverse, the agents reinstall themselves automatically to match. The server rebuilds its agent packages under the new entitlement during the restart, and managed devices pick up the rebuilt agent on their next sync. No manual reinstall is needed.
USB access in NetLock RMM is an allowlist: anything not on the whitelist is blocked. A device gets its whitelist in two ways:
Learning. When a device is assigned to a policy with learning switched on, it learns the devices connected to it during its learning period, typically its keyboard, mouse, dock and headset. The entries apply to that device only. Other devices on the policy keep blocking unknown devices in the meantime.
Approval. A USB device that is blocked appears on the Blocked Devices tab, where an administrator approves it for the device, its group, location, tenant or globally.
This guide sets up a policy for a group of Windows devices, lets the devices learn what is attached to them, and then approves a further USB device for the whole group.
The policy reaches the target group through an automation (see Guide H.4).
The devices run agent 3.3.0.11 or later.
Required permissions: policies_edit to change the policy; collections_enabled, collections_device_control_enabled and collections_device_control_manage to approve devices; devices_usb_learning to re-learn or end learning on a device.
Open the policy and go to Windows → USB Device Control. Switch on Enabled.
Switch on Learn connected devices on devices newly assigned to this policy and choose the Learning period:
4 hours (the default) or longer when users plug in their docks and headsets over the day.
Devices connected when learning starts when only what is attached at that moment should be learned; everything connected later is blocked and can be approved afterwards.
Choose the device type filters and the actions on unknown devices (Eject / disable device, Log device event), then save the policy.
Each device of the group starts its own learning period when it receives the policy. Devices that are already on the policy are not affected.
Follow a device on its USB Devices tab: the status line shows Learning connected devices until …, and the learned devices appear in its whitelist with the author Auto-Whitelist (Agent: <device name>).
Let the period run out, or end it early with End learning now once the device has learned what it needs. From then on, unknown devices are blocked on it.
Tip: For a device that gets a new dock or keyboard later, use Re-learn connected devices on its USB Devices tab. Several devices can re-learn at once from Collections → Device Control (Re-learn connected devices on the Whitelist tab, at most 500 devices).
On one of the devices, plug in the USB device. The agent detects it, disables it and reports it to the Console.
In the Console, open Collections → Device Control and switch to the Blocked Devices tab (route /device-control/blocked).
Find the row for the USB device. The Blocked Devices table shows Count, Date, Reporting Device, the USB metadata (name and manufacturer), the device Type (Mouse / Keyboard / HID / USB / DiskDrive / and so on), the Device ID, the Actions Taken, and a Pending status chip.
Confirm this is the intended device. If more than one pending row looks similar, compare the vendor-id, product-id, and serial encoded in the Device ID.
Open the row's menu and pick Approve for group. The group is the group of the reporting device. The other choices are Approve for this device, Approve for location, Approve for tenant, Approve globally (accounts with access to all tenants) and Dismiss.
The server adds the device to the whitelist scoped to that group, sets the row's status chip to Approved, and requests a sync so the devices in the group pick up the updated whitelist.
Note: Scope is chosen once, at approval time. To widen or narrow a whitelist entry later, delete it from the Whitelist tab and re-approve the blocked-device entry with a different scope.
On the USB Devices tab of a device, the status line reads Connected devices learned on … under policy … once its period is over, and its keyboard and mouse work.
On the Whitelist tab (route /device-control/whitelist) a new row appears with the approved USB device's metadata, the group scope chip, and the reporting device's group as Scope Target. Status is on.
On any device in the group, the approved USB device connects. On devices outside the group, it continues to be blocked.
A device does not learn. Check its USB Devices tab. Connected devices have not been learned on this device means it has not received a policy with learning switched on since it was assigned; use Re-learn connected devices. A device that returns to a policy it has already learned under does not learn again by itself.
USB device does not appear as blocked. The policy assigned to the device must have USB Device Control turned on. In block mode, at least one whitelist entry must apply to the device or the device must be in its learning period: with an empty rule set nothing is enforced, because every device would otherwise be blocked, including keyboard and mouse.
Approved but still blocked. Allow a sync cycle to pass. Once the device has the updated whitelist, the agent enables the device again by itself; re-plugging is not required. If the device was disabled while it was unplugged, it is enabled at the next periodic check after it is plugged in again (5 minutes by default).
Multiple similar rows appear. Each failed enumeration is logged as a separate attempt; approve one and delete or dismiss the others.
The Reports module turns data already in your NetLock RMM deployment into shareable documents. This guide walks through two common tasks against the same template: produce a report now for immediate use, then set up a recurring weekly PDF email to your stakeholders.
A report template already exists that matches your compliance scope. The built-in templates are on the Templates tab with a Built-in chip; tick Show Built-in if they are hidden. If no suitable template exists, build one with the Report Builder (see Chapter 11.3).
SMTP is configured if you want email delivery (see Guide H.10).
Required permissions: reports_enabled, reports_generate for on-demand generation, reports_schedules for the scheduled run.
On the Templates tab, find the compliance template you want to run.
Click the Generate action on the row to open the Generate Report dialog.
Fill in:
Format: pick PDF for a human-readable document, or HTML, CSV, or JSON for other use cases.
Date range: pick Last 24 Hours, Last 7 Days, Last 30 Days, Last Quarter or Last Year.
Email: optional. Fill in to email the result now; leave blank to only produce the file.
Submit. The generated file lands on the Generated tab (and arrives by email if you filled in an address).
Tip: PDF output honours the brand template attached to the source template; the other formats ignore it. If your compliance PDF needs a customer-specific cover page, attach a brand template first in Chapter 11.5.
Still on the Reports page, switch to the Schedules tab.
Open the Schedule dialog to create a new scheduled run.
Pick the same template you generated in step 1.
Fill in:
Frequency: Weekly, with a day-of-week picker. Choose the day and time that suit your stakeholders.
Hour (0–23) and Minute (0–59): evaluated in the server's time zone.
Date range: for a weekly email, Last 7 Days matches.
Export format: PDF.
Distribution: Email.
Recipients: one or more addresses, comma-separated.
Subject and Body: the message that accompanies the attached report.
Save.
Each week at the configured time the Console generates the report with the selected date range, renders it to PDF using the attached brand template, and emails it to every recipient as an attachment.
The Generated tab lists the on-demand run with the correct format and timestamp; you can re-download it from there.
The Schedules tab lists the new schedule with frequency, next-run time, recipients, and format.
After the first scheduled run fires, each recipient receives the PDF in an email with the subject and body you configured. Subsequent runs arrive on the weekly cadence.
No suitable template. Build one with the Report Builder, using the Visual Query Builder (Table, Fn, Columns, Joins, Where, Logic, Op, Value fields) or direct SQL. Both need SQL access (Set up SQL access); the built-in templates run without it. See Chapter 11.3.
Scheduled email never arrives. Confirm SMTP is configured and tested (Guide H.10). Check the Generated tab. If the file is produced but not emailed, the failure is in delivery, not in generation.
PDF missing the brand cover. The source template has no brand template attached. Edit it in the Report Builder and attach one; PDF honours it, other formats do not.
Time zone mismatch. Scheduled times use the server's time zone, not the viewer's. Cross-check with the administrator who configured the server.
Windows PowerShell can be told to run only scripts that carry a valid Authenticode signature (AllSigned). Organisations that enforce this through Group Policy can keep it with NetLock RMM: the scripts the agent brings along are signed, and your own scripts run when you sign them with a certificate the devices trust. There is no switch for this in the web console; the policy is yours, set and enforced by Windows.
Built-in scripts (Windows Update, WSUS, Storage Spaces, DHCP, Terminal Server, Hyper-V and Exchange sensors) ship as fixed files under C:\Program Files\0x101 Cyber Security\NetLock RMM\Comm Agent\Scripts, signed with the NetLock RMM code-signing certificate. The agent starts them with the execution policy RemoteSigned; a Group Policy that sets AllSigned takes precedence and is honoured.
Your scripts (jobs, sensors, sensor actions, remote shell, App Hub script apps) are written to the protected working folder of the agent exactly as you saved them in the console. The agent does not add or change a line, so a signature block you saved with the script stays valid. The script is started through the signed wrapper Run-Customer-Script.ps1 from the folder above, with -ExecutionPolicy Bypass; under a Group Policy AllSigned that parameter has no effect and Windows checks the signature of your script.
Python, Bash and Zsh scripts are not affected by the PowerShell execution policy.
A code-signing certificate for your own scripts: from your internal PKI (AD CS) or a public CA. A self-signed certificate works as well when you distribute it to the devices as described below.
The NetLock RMM code-signing certificate (public part). Export it from any signed agent file on a managed device, for example in an elevated PowerShell:
AllSigned runs a script only when the signing certificate chains to a trusted root and the publisher is listed under Trusted Publishers. The agent runs PowerShell non-interactively, so the "Do you want to run software from this untrusted publisher?" prompt cannot be answered; a publisher that is not trusted is simply blocked.
Deploy both certificates through Group Policy (Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies):
Trusted Publishers: the NetLock RMM code-signing certificate and your own code-signing certificate.
Trusted Root Certification Authorities: the root of your own certificate if it is not a public one (for a self-signed certificate, the certificate itself).
Computer Configuration → Policies → Administrative Templates → Windows Components → Windows PowerShell → Turn on Script Execution → Allow only signed scripts. This sets the MachinePolicy scope, which wins over every other scope and over the -ExecutionPolicy parameter.
Paste the clipboard into the script editor and save. The block at the end (# SIG # Begin signature block … # SIG # End signature block) is part of the script and must stay complete. Any later edit in the console, even a changed comment, invalidates the signature; sign the file again and paste it again.
Script variables are passed to the script through environment variables, not by editing the script text, so a signed script can use them without losing its signature. Signed scripts with variables need agent 3.3.0.11 or later.
Run a signed job once from the console. The job output appears as usual.
Run an unsigned test script. The job fails with the PowerShell message that the file is not digitally signed — the expected outcome under AllSigned.
Check a built-in: with debug logging on, Comm Agent\Logs\PowerShell.txt shows Execute_Builtin … script: Wua-List.ps1 lines without execution-policy errors.
RemoteSigned as a Group Policy also works: built-in and local scripts run without a signature, and scripts you paste into the console are local files for Windows.
Timestamp your signatures (-TimestampServer) so they stay valid after the certificate expires.
The PowerShell 7 installer package the agent downloads for winget and the Sysinternals tools are checked by the agent itself against Microsoft's signature before they are installed or started; they are not affected by this policy.
With Endpoint Protection anchored devices add a second, independent check: the agent runs only definitions that were signed in the NetLock RMM app (see Appendix A.13 — Endpoint protection). The two mechanisms complement each other; neither replaces the other.
Patch management in NetLock RMM is configured in two places, and patching works only when both are set up. The /patch-management page is the global approval queue: which patches are allowed on any device at all. The Policy Settings editor's Patch Management tab is the per-policy rollout: when and how these particular devices install the approved patches. This guide covers both, using a Windows group as the worked example.
A policy already exists and is routed to the target Windows group via an automation (see Guide H.4).
At least one Windows device is online in that group.
Patches have been detected and sit in the Pending state on the Patch Management page. If the list is empty, agents have not yet reported their update inventory; wait a sync cycle.
Required permissions: patch_management_enabled for the approval page, plus policies_enabled and the policy edit flag for the rollout configuration.
Open Patch Management from the navigation. The Update Approval tab is the default.
Filter by Windows and browse the Pending patches.
Select a manageable first set. Critical security updates from the previous month are a safe start. Avoid bulk-approving every pending patch on day one.
Click Approve. The selected patches move into the Approved state. The server flags every device for a resync so agents pick up the updated approval list on their next poll.
Use the other actions as needed:
Reject: explicitly block a patch; devices never install it.
Defer: postpone a patch for a number of days (default 7).
Reset to Pending: revert any state decision back to pending for later review.
Approvals are global and apply to all devices. Scoping to devices and groups happens in stage 2.
Open Policies from the navigation and click Manage on the policy that routes to your Windows group.
Open the Patch Management tab in the Policy Settings editor. The tab is split into Global and per-platform sub-tabs; pick Windows.
Under the Windows sub-tab, fill in at least these three sub-tabs for a minimal rollout:
General: enable patching for Windows and select which sources participate (at minimum OS-Mandatory, optionally Winget and Chocolatey).
Schedule: pick the allowed patch days (default Monday to Friday) and a maintenance window. Outside the window the agent will not start an install; the one exception is the catch-up run described in Chapter 6.12, which runs the first check after the policy arrives, or after a missed window, right away.
Reboot: decide whether the agent may reboot, whether it prompts the user, how long the prompt is visible, and what happens on a device where nobody is signed in. This is the only place in the product where reboot behaviour is configured.
Optionally fill in Approval & Filtering (narrow approved patches by severity or source), Deployment Rings (stage the rollout across Pilot → Early → Broad), Notifications, and Retry.
On the Patch Management page's Update Approval tab, the patches you approved show the Approved state and the Installed and Pending columns begin moving as devices pick up the change.
On a target device's detail view in Devices, the line Last patch run: <time> – <outcome> appears after the first scheduled run that reached the install stage, and the device's Updates tab shows per update whether it was installed or why the last scheduled run held it back. Scheduled runs do not create entries in Events; the only event a scheduled run writes is the Patch management event recorded once when an outstanding restart blocks the run.
The Patch history tab on the Patch Management page and on the device lists each scheduled run of an agent 3.3.0.5 or later next to the Patch Now jobs. Its details show per update whether it was installed, failed with the error Windows Update or the package manager reported, or was held back and why.
The Update History tab on the Patch Management page shows the install outcomes per patch per device.
Patches stay at 0 installed. Check that a policy with Patch Management → Windows → General enabled is actually assigned to the device. If the device's detail view shows - as assigned policy, the automation is missing. On Linux, open the job or the scheduled run in Patch Management → Patch history: the item details and the note carry apt's E: lines or dnf's error lines (No match for argument, Error:, Problem:), as does the agent's Error.txt. A package that apt keeps back because the upgrade would remove another package is listed as Skipped with the packages a full upgrade would remove; enable Allow package removal (full upgrade) in the policy's Linux tab to install it. On Fedora and RHEL-based systems a package excluded by excludepkgs in dnf.conf, or a version the repository no longer offers, fails with dnf's message while the other approved packages are installed.
Patches approved but devices ignore them. Check the policy's Approval & Filtering sub-tab. A filter there can block a globally approved patch.
My scheduled run never happens. First check where you are looking. With agent 3.3.0.5 or later, every scheduled run that reached the installation is an entry in the device's Patch history tab and on the Patch history tab of the Patch Management page, with the result of each update and the reason an update was held back or failed (see Chapter 7.5). Runs skipped for disk space, informational mode, a disabled policy, missing patch settings or an incomplete maintenance window are listed there as Skipped.
Waiting for an allowed day or for the maintenance window creates no entry; the Scheduled patching line in the device's detail view on /devices shows it with the next possible run. Further traces are the Last patch run line, the chips on the device's Updates tab, and the Last scheduled run column on the Devices Not Up To Date tab; with an older agent they are the only ones.
The agent decides every five minutes whether a scheduled run may start and checks the following stages in this order. Go through them from the top; the first stage that fails is the reason. Agents 3.3.0.5 and later report the waiting stages in the Scheduled patching line.
Patch settings on the device. The device has received the policy's patch settings. The detail view names the assigned policy (not -) and the Scheduled patching line does not say The device has not received its patch management settings yet. Until the agent has reported anything, the detail view shows the schedule facts of the device's policy (mode, allowed days, window, catch-up), so you can compare them with what you expect. If the policy is missing, fix the automation and wait for the next sync.
Platform mode is Managed.Informational only reports: Last patch run: … – informational mode, nothing installed. Disabled skips without a run; the Scheduled patching line shows Patch management is disabled in the policy of this device. Check Patch Management → Windows → General in the policy.
Allowed patch day. The default is Monday to Friday. On an unticked day no scheduled run happens, not even as a catch-up run. The line shows Waiting for an allowed patch day with the next possible run. Check Schedule → Allowed patch days. A typical example is a policy saved on Friday evening and checked on Saturday morning.
Maintenance window or catch-up. Inside the window the run starts at the agent's next check. Outside the window a run starts only as a catch-up: the first check after the policy arrives on the device, or the first check after a missed window, runs right away even outside the window (Catch up a missed maintenance window on the platform's Schedule sub-tab, on by default). From equal to To means no time restriction. The line shows Waiting for the maintenance window with the next possible run, or The maintenance window of the policy is incomplete, no run is scheduled when it cannot read the From/To pair. Nothing runs until the window is corrected.
One run per window occurrence. After a run the agent installs nothing more until the next window opens (once per day for a 24/7 window), whatever the outcome of that run was. The line shows Already ran in the current maintenance window with the next possible run. If that run installed nothing, the reason is in one of the following stages.
Free disk space. With Check minimum free disk space before patching on, a device below the threshold is skipped: Last patch run: … – skipped, insufficient disk space. This skip does not use up the window; the agent tries again at its next check.
Windows: no outstanding restart. While a restart from an earlier update run is outstanding, a scheduled run installs no Windows updates: Last patch run: … – restart pending, Windows updates held back. Winget and Chocolatey updates are still installed in such a run (agent 3.3.0.11 or later), and the tooltip of the line names how many of them were installed, failed or held back.
The device shows the Restart pending since … banner with the note that scheduled runs install no Windows updates until the device has restarted, together with the restart behaviour of its policy, and the blocked run is recorded once as an event of type Patch management on the device.
With Ask user a device where nobody is signed in asks nobody; the If nobody is signed in option on the Reboot sub-tab decides whether such a device restarts in the maintenance window, immediately, or not at all (the default). With the default the restart has to happen another way (a user or the Console restarts the device, or you change the option), and scheduled runs keep installing no Windows updates until then. Patch Now still installs Windows updates too.
Windows Update query. The agent asks Windows Update for the available updates. When the query times out, fails or returns no result, the run is recorded as completed and its note (the tooltip of the Last patch run line) says that the query for available updates failed and no update was installed. Windows Update itself, not the policy, is the place to look then.
Per-update filters. The run happened (completed or nothing pending) but a specific update is still missing: open the device's Updates tab, where the chip on each update names the reason from the last scheduled run: Blocked by severity filter, Blocked by update type filter, Not approved, Deployment ring until …, Retry after …, Waiting for restart, Not offered in last run. nothing pending means Windows Update offered nothing that the policy's sources cover. A deployment ring set to Immediate only removes the waiting time after an update's release; the allowed days, the maintenance window and the one-run-per-window rule still apply. Only Patch Now bypasses the schedule, the rings and the retry budget.
On the device itself, a 3.3.0.5 agent writes every change of its schedule decision and every run outcome to Logs\Patch_Management.txt in the Comm Agent folder (C:\ProgramData\0x101 Cyber Security\NetLock RMM\Comm Agent\) without debug mode; state changes and outcomes only, so the file stays small. The full detail of every five-minute check needs debug mode: create an empty debug.txt in the Comm Agent folder and restart the service, as described in Guide — Debug an agent. The agent's run bookkeeping lives in patch_cycle_state.json under C:\ProgramData\NetLock RMM\Agent\ (Linux: /var/lib/netlock-rmm/); a missing or empty file means that no scheduled run has reached the install stage yet.
Winget or Chocolatey updates are not installed by the scheduled run, although Patch Now installs them.Patch Now only proves that the installer works on the device. The scheduled run has further places where it holds an application update back, and each one leaves a trace. Open the device's Patch history tab, open the last scheduled runs with a double-click and check in this order:
The notice Winget and Chocolatey updates were not checked in this run because Windows updates are waiting for a restart. The agent on the device is older than 3.3.0.11. Update the agent; until then, make sure the device restarts on the same day (Reboot sub-tab) or use Patch Now.
Items with source Winget or Chocolatey and the reason Retry after …. The update failed in earlier runs and the retry budget is used up: after the policy's Retry count (default 3) failed attempts the agent waits seven days before it tries again; the attempts are kept in patch_retry.json under C:\ProgramData\NetLock RMM\Agent\. The Failed items of the earlier runs carry the installer's result in Details. Patch Now ignores the budget, and a successful installation resets it.
The note The winget upgrade query failed, so application updates from winget were not attempted (or the same wording for Chocolatey). The package manager could not be queried when the run started, for example because winget is not usable from the agent's system account; the device then also carries the event winget is not usable from the agent's system account (see the entry below). The Updates tab keeps the rows of the last successful inventory, so the list looks current although the query fails. The rows of that source show Package manager query failed in the last run (agent 3.3.0.11 or later). Patch Now with Patch All runs the same query and shows the failure in the job's note.
Items with the reason Deferred to a later run.Install all pending patches before rebooting is off on the Reboot sub-tab, so the run installs one update and the others follow in later runs.
No Winget or Chocolatey items and no notice. The package manager reported nothing to upgrade when the run queried it, even if the Updates tab lists updates from an earlier inventory. Such rows show Not offered in last run (agent 3.3.0.11 or later).
The Last run chip on the device's Updates tab shows these decisions for Winget and Chocolatey updates as well (agent 3.3.0.11 or later), in the same way as for Windows updates; a Retry after … chip names the time of the next allowed attempt. The device's patch status is no indication either way: software updates only count toward it when the compliance scope on the Patch Management Settings tab includes the Winget and Chocolatey sources (see Chapter 7.4).
The device shows the event winget is not usable from the agent's system account. The agent runs as the system account. There it uses winget through PowerShell 7 and Microsoft's module Microsoft.WinGet.Client, and winget.exe when the module is not available. With agent 3.3.0.12 or later the event has the type Patch management and is raised when neither of the two works. As long as that is the case, application updates from winget are not detected or installed on the device, and App Hub actions for winget apps with Requires Elevation fail. The event is raised once per cause, not repeatedly, however often the causes alternate. The same cause is reported again only after winget worked in between and at least a day has passed since its last event. Each event opens one alert, which ends when the event is read or hidden.
The Cause: line of the event names the step that failed, and the winget.exe: line what the fallback did:
Cause: begins with
Meaning
What to do
PowerShell 7 install: … the download … failed
The device could not download the PowerShell 7 installer package from GitHub.
Allow HTTPS from the device to raw.githubusercontent.com, github.com and release-assets.githubusercontent.com, or install PowerShell 7 on the device yourself (x64, ARM64 or x86 MSI from Microsoft, default location).
PowerShell 7 install: … no Windows Installer package … could be downloaded
None of the PowerShell 7 releases the agent looked at offers an MSI for the device's architecture.
Install PowerShell 7 on the device yourself.
PowerShell 7 install: … does not carry a valid signature
The downloaded package was not signed by Microsoft and was not installed.
Check whether a proxy or a security product changes downloads on the way to the device; install PowerShell 7 yourself.
PowerShell 7 install: … msiexec exit …
Windows Installer did not install the package.
Install the PowerShell 7 MSI by hand on the device to see the installer's own message.
PowerShell 7: PowerShell 7 at … is not used
Standard users can write to the PowerShell 7 folder or to pwsh.exe, so the agent does not start it.
Restore the default permissions of C:\Program Files\PowerShell\7, for example by reinstalling PowerShell 7.
Microsoft.WinGet.Client module check
PowerShell 7 did not answer when the agent asked for the installed module.
Start C:\Program Files\PowerShell\7\pwsh.exe on the device and check that it opens; repair or reinstall PowerShell 7 if it does not.
Microsoft.WinGet.Client install from PSGallery
The module could not be installed from the PowerShell Gallery. The cause names what each of the two installation commands reported (Install-PSResource, then Install-Module).
Allow HTTPS to www.powershellgallery.com and cdn.powershellgallery.com, or run Install-PSResource -Name Microsoft.WinGet.Client -Repository PSGallery -Scope AllUsers -TrustRepository in an elevated PowerShell 7 on the device (Install-Module Microsoft.WinGet.Client -Scope AllUsers on a PowerShell older than 7.4).
…: PowerShell 7.x ended with a fatal error (exit …) after any of the steps
pwsh.exe itself ended while the agent looked for, installed or loaded the module, for example with exit 0xC0000005. This is not an error of the module or of the PowerShell Gallery. The cause carries the PowerShell version and the beginning of PowerShell's own error report; the complete output is in Error.txt of the Comm Agent on the device.
Repair or reinstall PowerShell 7 with Microsoft's MSI package and restart the device. Check whether a security product on the device interferes with pwsh.exe. Then run the Install-PSResource command of the row above in an elevated PowerShell 7 on the device. If PowerShell ends there as well, the Windows Application event log has the entries Application Error and .NET Runtime for pwsh.exe, which name the failing component.
…: the check ended before winget ran, exit … or …: the check ended while the module was loaded, exit …
The module is installed, but the check ended with exit 0xC0000409 or 0xC0000135. With the first text winget itself could not be started from the system account, which is a state of App Installer on the device, not of PowerShell. With the second text the process already ended while it loaded the module.
Install the pending Windows updates and bring App Installer up to date (Microsoft Store, or Repair-WinGetPackageManager -AllUsers in an elevated PowerShell 7 window of an administrator). If the event stays, send its text to support.
Microsoft.WinGet.Client module import or winget source query (Get-WinGetSource)
The module is installed but does not answer from the system account. The cause carries the error, the module version and the Windows build.
Install the pending Windows updates and the current module version (Install-Module Microsoft.WinGet.Client -Scope AllUsers -Force). If the event stays, send its text to support.
The line winget.exe: no usable answer for more than 24 hours means that winget.exe starts on the device but, for longer than a day, has only run into its time limit or answered in a form the agent cannot read with certainty. Run winget upgrade --source winget in an administrator session on the device to see what it prints, and check the device's network path to the winget source.
Windows Server and LTSC editions without App Installer. These editions come without App Installer, the package that contains winget.exe; the event then shows winget.exe: not found on this device (App Installer is not installed). The agent does not install App Installer and does not repair its registration. Without it the updates inventory lists no winget updates for the device, and the agent has no fallback when the module cannot be used. To install or repair it, sign in as an administrator and run in an elevated PowerShell 7 window: Install-Module Microsoft.WinGet.Client -Scope AllUsers, then Repair-WinGetPackageManager -AllUsers. Do not run this through a NetLock RMM job or the remote shell: both run as the system account, where Microsoft's cmdlet refuses -AllUsers.
The agent tries again by itself 60 minutes after a failed attempt (6 hours after an attempt in which PowerShell 7 ended with a fatal error, because every such attempt leaves a crash entry in the Windows Application event log), and right away once PowerShell 7 exists at its default location; a service restart is not needed. It only uses PowerShell 7 from C:\Program Files\PowerShell\7. An installation elsewhere (Microsoft Store, zip archive, dotnet tool) is neither used nor changed; the agent installs its own copy next to it. It installs the newest PowerShell 7 release Microsoft publishes as a Windows Installer package, at present the 7.6 LTS line. A Microsoft.WinGet.Client older than 1.12.440 stays in place, and the agent installs the current version next to it.
PowerShell 7 and the module are only installed on devices that use winget through the agent (agent 3.3.0.12 or later): the policy has Install application patches (Winget) ticked in Informational or Managed mode, Patch Now runs with winget updates, a winget app with Requires Elevation is installed, updated or removed through App Hub or a software deployment, or such an app has automatic updates switched on. On every other device the updates inventory uses PowerShell 7 and the module if they are already there and winget.exe otherwise. Where winget.exe does not answer from the system account either, or answers in a form the agent cannot read with certainty, the winget rows on the Updates tab stay as they are (none on a new device) until one of the conditions applies. When winget.exe reports nothing to upgrade, the rows are removed with the second sync in a row that says so.
Agents up to 3.3.0.11 report the event with the type job and repeat it every six hours.
A Windows update is Failed with a time limit, or Skipped because Windows is still installing. An update has 6 hours for its download and installation, and a run starts no installation while Windows has another one in progress (agent 3.3.0.12 or later). Both, and the 60-minute limit of older agents, are described in Chapter 7.7.
Reboots happen at unexpected times. Review Patch Management → Windows → Reboot and Schedule in the policy. Reboot prompts follow the schedule's maintenance window.
SLA chips show Overdue. Adjust the SLA thresholds on the Patch Management Settings tab if the defaults (7 / 15 / 30 / 60 days by severity) do not fit your environment.
Self-hosted only: This guide applies to self-hosted deployments. On cloud instances SQL access is not available; the menu entry is hidden and only the statements of the built-in report templates run.
SQL that you write yourself and SQL that the query builders generate runs only over a dedicated MySQL user. This covers:
report widgets and report text parameters,
SQL panels on dashboards, including the preview in the Panel Builder,
SQL custom fields on the device page, including the preview in the Custom Field Builder.
You create that user in MySQL and enter it in the Web Console under Settings → SQL access (/settings/sql-access). Its MySQL grants decide which tables and columns such SQL can read. The query builders list exactly the tables and columns the user can read.
The built-in report templates do not need SQL access. Their unchanged statements run without it, also in duplicates, imports and catalog templates. A changed or new statement needs SQL access, and so does a duplicate whose statement a later release has changed.
A MySQL account with the right to create users, usually root. The database user that the guided installer creates for NetLock has no CREATE USER right.
A Web Console account with the permission settings_sql_access (the Administrator role has it).
The name of the NetLock database. The examples below use netlock; replace it with yours.
Open a MySQL prompt as root:
Docker install. The NetLock images have no shell; open the prompt in the database container:
If your container has a different name, list the names with sudo docker ps --format '{{.Names}}'. The database name is MYSQL_DATABASE in /home/netlock/docker-compose.yml.
Own MySQL server. Use any administration client and sign in as root.
Note:Install the NetLock RMM server with Docker configures NetLock itself with "User": "root". The user for SQL access must still be a separate user: the console refuses the MySQL user that NetLock itself uses.
The simplest way is to copy the statements shown on Settings → SQL access under Create the MySQL user. They are generated for the tables of this instance: one CREATE USER statement and one GRANT SELECT statement per table. Replace the password placeholder <strong password> and run them as root.
The equivalent manual way:
Create the user:
CREATE USER 'netlock_reports'@'%' IDENTIFIED BY '<strong password>';
Run this generator. Replace netlock in the WHERE clause with your database name. It prints one GRANT line per table:
SET SESSION group_concat_max_len = 1000000;SELECT CONCAT('GRANT SELECT ', IF(SUM(c.COLUMN_NAME REGEXP 'password|secret|token|access_key|private_key|api_key|_encrypted$|community|credential|auth_|headers|http_body') > 0, CONCAT('(', GROUP_CONCAT(IF(c.COLUMN_NAME REGEXP 'password|secret|token|access_key|private_key|api_key|_encrypted$|community|credential|auth_|headers|http_body', NULL, CONCAT('`', c.COLUMN_NAME, '`')) ORDER BY c.ORDINAL_POSITION SEPARATOR ', '), ') '), ''), 'ON `', c.TABLE_SCHEMA, '`.`', c.TABLE_NAME, '` TO ''netlock_reports''@''%'';') AS grant_statementFROM information_schema.COLUMNS cJOIN information_schema.TABLES t ON t.TABLE_SCHEMA = c.TABLE_SCHEMA AND t.TABLE_NAME = c.TABLE_NAME AND t.TABLE_TYPE = 'BASE TABLE'WHERE c.TABLE_SCHEMA = 'netlock' AND c.TABLE_NAME NOT IN ('account_app_devices', 'account_app_push_settings', 'account_passkeys', 'account_sessions', 'accounts', 'agent_package_configurations', 'agent_package_guid_history', 'agent_package_installers', 'agent_protection_blocks', 'agent_protection_exemptions', 'agent_protection_offenders', 'agent_protection_statistics', 'agent_protection_volume', 'api_command_requests', 'api_idempotency_keys', 'api_request_log', 'api_tokens', 'api_webhooks', 'dashboard_shares', 'device_bitlocker_recovery_keys', 'device_upload_tokens', 'enduser_accounts', 'enduser_sessions', 'external_refs', 'integration_billing_maps', 'integration_connections', 'integration_jobs', 'integration_leases', 'integration_log', 'integration_mappings', 'integration_object_links', 'integration_state', 'integration_status_items', 'ip_whitelist_dynamic', 'microsoft_teams_notifications', 'ntfy_sh_notifications', 'policy_defaults', 'relay_admins', 'relay_session_admins', 'relay_sessions', 'settings', 'telegram_notifications', 'ticket_webhooks', 'webhook_notifications')GROUP BY c.TABLE_SCHEMA, c.TABLE_NAMEHAVING SUM(NOT c.COLUMN_NAME REGEXP 'password|secret|token|access_key|private_key|api_key|_encrypted$|community|credential|auth_|headers|http_body') > 0ORDER BY c.TABLE_NAME;
Copy the printed GRANT lines and run them.
What the generator leaves out:
The tables in the NOT IN list hold sign-in data, keys and tokens, the credentials of notification channels, the request and command logs of the public API, relay sessions and the state of the agent protection.
In every other table, columns whose name contains password, secret, token, access_key, private_key, api_key, community, credential, auth_, headers or http_body, or ends in _encrypted, are left out through a column grant — for example devices.access_key, devices.fcm_token, the mail passwords of ticket_departments, the SNMP community and v3 passwords of snmp_devices and the request headers, body and credentials of uptime_monitors. A query that selects such a column fails with a MySQL access error. A table in which every column is left out gets no grant.
A table grant (a line without a column list) also covers columns that a later update adds to that table.
Tables added by a later update are not readable automatically, and neither are columns added to a table that carries a column grant, such as devices.update_inventory_at (3.3.0.11). Run the generator again, or copy the statements from Settings → SQL access again, after an update. Existing grants are not affected by running them a second time.
CREATE USER 'netlock_reports'@'%' IDENTIFIED BY '<strong password>';GRANT SELECT ON `netlock`.* TO 'netlock_reports'@'%';
This user can also read the credential tables and columns that the recommended variant leaves out, and every table added by later updates. Choose the variant that matches who edits reports, dashboards and custom fields on your instance.
If the database name contains an underscore, escape it in a database-level grant, for example `net\_lock`.*. An unescaped _ is a wildcard in MySQL; the console accepts it only if no other existing database matches the pattern.
'%' is needed with Docker, because the Web Console and the server connect from other containers. With your own MySQL server, restrict the host to the machines that run the Web Console and the server, for example 'netlock_reports'@'10.0.0.5' (create one user per host or use a subnet pattern if they differ).
The user may hold nothing but SELECT on the NetLock database — on the whole database, on single tables, or as column grants — plus USAGE. Do not grant anything else: no other privilege, no WITH GRANT OPTION, no roles, no privileges on *.* and no grants on other databases. A user without any grant on the NetLock database fails at connect with MySQL's Access denied … to database message.
Enter the MySQL user name (for example netlock_reports) and the Password.
Click Save.
The console connects with the user and checks its grants. The status line at the top shows the result:
Active: SQL runs over the MySQL user netlock_reports. — your own SQL and the query builders are available.
Off: the MySQL user netlock_reports was refused. followed by the reason — see Refusal reasons below.
Not configured: your own SQL and the query builders are off. Scheduled reports with your own SQL show [SQL access not configured] in those widgets until a user is configured.
The connection uses the same server, port, database, TLS settings and extra connection parameters as NetLock's own connection; only user and password differ. It appears in MySQL with the application name netlock-report-sql. Each piece of SQL must be exactly one SELECT query (or WITH … SELECT). Queries run read-only and stop after 10 seconds. User variables such as @rownum := @rownum + 1 are allowed.
The password is stored encrypted with the local encryption key and is never shown again. When you save with the same user name and an empty password field, the stored password is kept; a different user name always needs its password.
The Web Console and the server check the grants again every 15 minutes. If the grants were widened in the meantime, SQL access switches off: a log entry is written and the page shows the refusal. While the user is refused, the check runs every minute, so SQL access returns shortly after you fix the grants.
The connection with this user failed: followed by the MySQL error
Check user name, password and host part of the user. Access denied … to database means the user has no grant on the NetLock database; run the GRANT statements of step 1.
This is the MySQL user of NetLock itself. Create a separate user.
Create a separate user as described in step 1.
The user holds privileges other than SELECT.
Revoke every other privilege (for example INSERT, UPDATE, EXECUTE, SHOW VIEW or dynamic *_ADMIN privileges). Proxy grants and partial revokes are refused with this message as well. Check with SHOW GRANTS FOR 'netlock_reports'@'%';.
The user holds WITH GRANT OPTION.
Revoke the grant option, for example REVOKE GRANT OPTION ON `netlock`.* FROM 'netlock_reports'@'%'; (use the level it was granted on).
The user has a role granted or active, or the MySQL server sets mandatory roles.
Revoke the role from the user and remove it from the default roles. When the server sets mandatory_roles, every session could activate those roles; SQL access needs a server without mandatory roles.
The user can read databases other than the NetLock database.
Revoke grants on other databases and on database name patterns with %. Escape _ in the NetLock database name if another database matches the pattern.
The user holds privileges on all databases (*.*).
Revoke the global privileges; grant SELECT on the NetLock database or its tables instead.
The user cannot read any table of the NetLock database.
Run the GRANT statements of step 1.
After fixing the grants, click Save again, or wait for the next check (every minute while the user is refused).
Own report widgets show SQL access not configured instead of data; in generated output the widget shows [SQL access not configured]. Widgets of the built-in templates keep working.
Dashboard SQL panels are locked with a notice, also in the TV view. Catalog widget panels are not affected, and neither are SQL panels that were added from the shipped panel templates and still carry the template statement unchanged.
SQL custom fields show (SQL access not configured).
The Widget Editor, the Panel Builder and the Custom Field Builder show a notice with a link to Settings → SQL access and do not offer the query builder, the SQL field or the AI SQL assistant.
Saving or importing a report template that contains own SQL is refused.
In the public API, creating or changing such a template, generating a report from it and scheduling it answer 403 sql_access_not_configured; see X.9.16.
This guide removes the NetLock RMM agent from a device and leaves it in a clean state: services deleted, processes stopped, install and data directories gone. It is the counterpart to Guide H.1. Uninstalling only affects the local device; the device record stays in the Console until you delete it there (see Verify it worked).
You have administrator or root access on the target device. The uninstaller deletes services and protected directories, so it requires elevation on every supported OS.
You have the matching agent installer binary for the device's platform and architecture. Any build removes the agent (the embedded server configuration is ignored in this mode), but it must match the OS and architecture (for example a win-x64 build to uninstall on 64-bit Windows). On Windows, use an installer from a server on 3.3.0.11 or later, so the uninstall also releases the Windows Update settings (see What gets removed). If you no longer have the original .zip, download one from Agent Installers as described in Guide H.1.
The uninstaller is part of the command-line installer that Agent Installers hands out. A graphical installer built with an earlier version does not uninstall; download the installer from Agent Installers instead.
The uninstall mode performs a full cleanup, in order:
Stops the services:NetLock_RMM_Agent_Comm, NetLock_RMM_Agent_Remote, and NetLock_RMM_Agent_Health.
Terminates the processes: the three agent services, the user process, the UAC helper, and the tray icon.
Deletes the services: removes the Windows services, the Linux systemd units under /etc/systemd/system/, or the macOS LaunchDaemons under /Library/LaunchDaemons/ together with the LaunchAgents of the User Process and the tray icon under /Library/LaunchAgents/ (unloaded from every signed-in user session first), and unregisters the user-process and tray-icon Run entries on Windows.
Releases Windows Update (Windows): removes the Windows Update settings the agent applied for Disable Windows built-in automatic updates (see Chapter 6 — Policies): NoAutoUpdate and SetDisableUXWUAccess under HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate, and TrayIconVisibility under HKLM\SOFTWARE\Microsoft\WindowsUpdate\UX\Settings. Only values the agent recorded as its own are removed; a WSUS configuration and values from your own group policies stay. Automatic updates resume, the Windows Update page shows its controls again without the "Some settings are managed by your organization" notice, and the Windows Update icon in the notification area is visible again.
The step also removes the Microsoft Update registration the agent made for Include updates for other Microsoft products (Microsoft Update), through the Windows Update Agent's service manager (powershell.exe). Only a registration the agent recorded as its own (marker mu_opt_in_applied) is removed; one made by a user, by a group policy or before the agent was installed stays.
Finally it removes the agent's registry key HKLM\SOFTWARE\WOW6432Node\NetLock RMM, and HKLM\SOFTWARE\0x101 Cyber Security once it is empty. No service is restarted.
Deletes the directories and logs: the install tree under Program Files and the data tree under ProgramData, plus the agent service logs on Linux and macOS. When the uninstall was started by the agent itself (remote uninstall or an update), the installer runs from NetLock RMM\Temp\netlock rmm\installer below the data tree and leaves that folder with its executable and log behind; a manual uninstall removes the data tree completely.
After it finishes, no NetLock RMM service, process, or directory remains on the device, and Windows Update is back under Windows' control. The installer prints the outcome of the Windows Update step, including whether a Microsoft Update registration was removed.
Note: A fresh installation over an existing agent (clean mode, the --server parameter mode, or the installer with its embedded configuration) runs the same cleanup first. On a device whose policy disables Windows' automatic updates, the agent applies the Windows Update settings again within a few minutes of its first policy sync. A repair (fix, also used by agent updates) keeps the settings.
Wait for the installer to print Uninstall complete. and exit with code 0.
Note:uninstall is one of the installer's positional modes, alongside clean "<path-to-server_config.json>" (fresh install with an external config) and fix "<path>" (repair while preserving the server config). See Guide H.1 for the install and repair modes.
Linux:systemctl status netlock-rmm-agent-comm reports "not found".
macOS:launchctl list | grep netlock is empty, both as root and as every signed-in user (the LaunchAgents of the User Process and the tray icon), and /Library/LaunchAgents/ holds no com.netlock.rmm.*.plist.
The install and data directories no longer exist:
Windows:C:\Program Files\0x101 Cyber Security and C:\ProgramData\0x101 Cyber Security. After a remote uninstall only C:\ProgramData\0x101 Cyber Security\NetLock RMM\Temp\netlock rmm\installer (the installer executable and its log) remains.
Linux:/usr/0x101_Cyber_Security and /var/0x101 Cyber Security, and the logs under /var/log/netlock-rmm-agent-*.log.
macOS:/usr/local/bin/0x101_Cyber_Security and /Library/Application Support/0x101 Cyber Security.
Windows: the Windows Update settings are released. In an elevated command prompt:
The first command lists neither NoAutoUpdate nor SetDisableUXWUAccess (it may report that the key does not exist, or show WSUS and group policy values, which stay). The second reports that the value was not found, the third that the key does not exist. The fourth lists no service with the ID 7971f918-a847-4430-9279-4a52d1efe18d (Microsoft Update) unless it was registered by someone other than the agent, in which case it stays. Reopen Settings › Windows Update: Check for updates is available again.
The device still shows in the Console, because uninstalling does not delete the record. Remove it from Devices (or Unauthorized Devices) by hand once the agent stops reporting in. See Chapter 3 — Managing Devices.
"Failed to elevate" and the installer exits. The uninstaller needs administrative or root privileges to delete services and protected directories. Re-run from an elevated PowerShell prompt (Windows) or with sudo (Linux / macOS).
A service is "marked for deletion" or a directory is locked. A process still holds a handle. The uninstaller already waits for the service manager to release handles, but if it raced an open management console or a running agent process, reboot the device and run uninstall again. The second pass clears any leftovers.
The device keeps reappearing in the Console. That is the cached device record, not a live agent. Confirm the services are gone (above), then delete the record in Devices. If the device genuinely re-registers, an installer or deployment task is reinstalling it. Check your GPO, Intune, or Ansible jobs.
Windows Update stays locked after an uninstall with an installer before 3.3.0.6 ("Some settings are managed by your organization", no Check for updates). Remove the values in an elevated command prompt:
These commands delete single values, never a whole key; a value that does not exist only produces an error message. Skip the first two if your own group policy sets NoAutoUpdate or SetDisableUXWUAccess. If the values come back after a while, a group policy writes them; check with gpresult /h report.html.
Microsoft Update stays registered after an uninstall with an installer before 3.3.0.11 (Receive updates for other Microsoft products is on, or Microsoft Update is listed by the fourth command under Verify it worked). Remove the registration in an elevated command prompt:
The first command is the same as turning off Receive updates for other Microsoft products in the Windows settings; skip it if Microsoft Update should stay registered. The second removes the agent's marker and only produces an error message when the value is already gone.
Uninstaller fails on a Linux NAS or appliance distro. Some distributions, notably Synology and similar NAS systems, block execution from the default temporary directory. Re-run with --temp <path> / -t <path> pointing at a directory the system permits execution from, then retry.
Self-hosted only: This guide applies to self-hosted deployments. Cloud customers do not run a database server — the hosted platform is run for them.
This guide moves the MySQL container of a self-hosted NetLock RMM installation from MySQL 8.0 (or 5.7) to MySQL 8.4, the current long-term support release. It follows the Docker Compose layout of Install the NetLock RMM server with Docker: the compose file at /home/netlock/docker-compose.yml, the mysql service with the container name mysql-container, and the data directory /home/netlock/mysql/data. Plan for downtime: the server and the Web Console are stopped while the database upgrades its files. On a small installation that is a matter of minutes; on a large database the first start of the new version can take considerably longer (see step 4).
Oracle publishes security fixes only for MySQL releases that are still in support:
Release
Oracle support ended / ends
Status
MySQL 5.7
31 October 2023
Out of support
MySQL 8.0
30 April 2026 (last release 8.0.46)
Out of support
MySQL 8.4 LTS
30 April 2032
Recommended
The dates follow Oracle's lifetime support policy; a compact overview is kept at endoflife.date/mysql. NetLock RMM is developed and tested against MySQL 8.4, and every current installation path — the guided installer and the compose file in the installation guide — deploys mysql:8.4. Installations created earlier usually still pin mysql:8.0.
The Web Console tells you when the database server is older than 8.4:
A warning icon next to the update notice in the top bar (on phones, an entry in the account menu). It opens a short dialog with the running version, the date its support ended, the recommended version, the upgrade steps and a link to this guide.
A warning above the status card on Settings → Database, with the same link.
Both are visible to accounts that may open Settings → Database (settings_enabled and settings_database_enabled), only on self-hosted installations, and they stay until the database reports version 8.4 or newer. There is no dismiss button.
On an installation that follows the Docker layout above, the upgrade takes six steps:
SSH into the NetLock RMM server.
Navigate to /home/netlock
Run sudo docker compose down
Run sudo nano docker-compose.yml
Locate the mysql image entry, change from mysql:8.0 to mysql:8.4, save and exit.
Run sudo docker compose up -d
Keep these points in mind:
Take the backup before step 3 of this list: mysqldump needs a running database.
down waits only 10 seconds by default. With a large buffer pool use sudo docker compose down -t 120 so MySQL can shut down cleanly.
up -d starts everything at once. The Web Console and the server restart until MySQL is ready; do not interrupt the first start.
The sections below are the same upgrade in smaller stages, with the check of the MySQL options that 8.4 no longer accepts. On MySQL 5.7, the note under "Before you start" applies.
Shell access to the host that runs the containers, with permission to run docker (the commands below use sudo).
The compose file. The installation guide places it at /home/netlock/docker-compose.yml; adjust the paths below if yours differs.
The running MySQL version. Settings → Database shows it on the status card. From the host, the container's own client reports it as well; the root password comes from the container's environment, so nothing is typed into the shell:
A current backup of the database. Step 1 explains why there is no way back without one.
Note: MySQL 5.7 cannot be upgraded to 8.4 directly — a release series cannot be skipped (upgrade paths). Run this guide twice: first with the image mysql:8.0, wait until that upgrade has finished and the server is up, then again with mysql:8.4.
Note: Pin the image tag. mysql:8.4 stays on the 8.4 series and receives its patch releases through normal image pulls. A container-update watcher such as Watchtower follows the tag you pinned and never moves mysql:8.0 to 8.4 on its own. The tags mysql:8 and mysql:latest already resolve to 8.4 and would jump versions on the next pull without the preparation below, so replace them with mysql:8.4.
Make sure you have a current backup of the database before you change the image. There is no way back in place: once 8.4 has started on the data directory, 8.0 will not open it again, and the only route back is a backup loaded into a fresh 8.0 database (downgrading MySQL). If your regular backup has not run since the last changes, take a logical dump now. The root password and the database name are read from the container's environment (MYSQL_ROOT_PASSWORD and MYSQL_DATABASE in the compose file), so neither ends up in the shell history:
Then stop the database container. The stop command waits up to two minutes; the default of ten seconds can end a server with a large buffer pool before it has written everything out.
sudo docker compose -f /home/netlock/docker-compose.yml stop -t 120 mysql
Note: Upgrade only a server that was shut down cleanly; docker compose stop does that. A server that crashed and was not restarted since must be started once and stopped again before you continue (upgrade prerequisites).
MySQL 8.4 refuses to start on options it has removed and writes unknown variable to the log. The compose file from the installation guide passes its options in the command: block of the mysql service; a mounted my.cnf, if you added one, needs the same check. Compare what you have against this table:
Docker pulls mysql:8.4 and starts a new container on the existing data directory, which is how a MySQL container is upgraded (upgrading a MySQL container). On this first start the server upgrades its data dictionary and system tables on its own; no option is needed, this is the default --upgrade=AUTO (what is upgraded). The log shows a line like Server upgrade from '800xx' to '804xx' started, later a matching completed line, and finally ready for connections. Leave the log with Ctrl + C; that does not stop the container.
Note: The upgrade can take a while. On this first start MySQL rewrites its data dictionary and system tables and checks every table of the database. On a small installation that is done in seconds; on a database that has collected events, inventory and patch data for years it can take many minutes, and the time grows with the size of the data directory and the speed of the disk. The container is not stuck while the log stays quiet between started and completed. Do not stop, restart or recreate it during that time: an interrupted upgrade leaves a data directory that only the backup from step 1 brings back.
sudo docker compose -f /home/netlock/docker-compose.yml up -d
Open Settings → Database. The status card shows Version: 8.4.x, the warning above it is gone, and the warning icon in the top bar disappears as soon as the page has read the new version.
Keep the backup from step 1 until the installation has run on 8.4 for a few days.
The container stops right after the start and the log says unknown variable. An option that 8.4 removed is still in the command: block or in a mounted my.cnf. Go back to step 2, fix the option, and run the up -d mysql command again.
The log says Plugin 'mysql_native_password' is not loaded, or an application cannot sign in after the upgrade. The mysql_native_password plugin is disabled by default since 8.4.0. The root account the image creates uses caching_sha2_password and is not affected, and the Web Console's connection parameters keep AllowPublicKeyRetrieval=True, which that method needs. Only accounts created by hand with mysql_native_password are affected. Enable the plugin once by adding --mysql-native-password=ON to the command: block, start the container, and switch the account:
ALTER USER 'name'@'%' IDENTIFIED WITH caching_sha2_password BY '<password>';
The log has shown Server upgrade … started for a long time and nothing else. The upgrade is still running; see the note in step 4. Wait for the completed line, do not restart the container.
A 5.7 data directory with mysql:8.4. The server refuses to start; a release series cannot be skipped. Set the tag to mysql:8.0, let that upgrade finish, then continue with 8.4.
Going back to 8.0. The upgraded data directory cannot be opened by 8.0 again. Stop the database container, move the directory aside, set the tag back to mysql:8.0 and start the container on an empty directory; the image then creates the database and the accounts from the compose environment again. Wait for ready for connections in the log, then load the backup from step 1:
sudo docker compose -f /home/netlock/docker-compose.yml stop mysqlsudo mv /home/netlock/mysql/data /home/netlock/mysql/data-8.4sudo mkdir /home/netlock/mysql/data# change image: to mysql:8.0 in the compose file, thensudo docker compose -f /home/netlock/docker-compose.yml up -d mysqlsudo docker logs -f mysql-containersudo docker exec -i mysql-container sh -c 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" "$MYSQL_DATABASE"' < /home/netlock/mysql-backup-<date>.sql
Then run the up -d command from step 5. Delete /home/netlock/mysql/data-8.4 once the installation runs again.
This guide upgrades a NetLock RMM deployment to the latest release: first the server and Web Console, then the agents. The server side applies only to self-hosted deployments. On cloud, the hosted operations team upgrades the platform for you, and you only need the agent steps.
For the server upgrade (self-hosted): shell access to the host running the NetLock RMM containers, and the path to the docker-compose.yml that defines your deployment.
For the agent upgrade: a Console account that can reach Settings → Updates and edit the policy your devices use; see A.2 and Chapter 6.
No database migration is required; see the note below.
Self-hosted only: This section does not apply to cloud deployments.
The server and Web Console ship as container images. Upgrading means pulling the latest images and recreating the containers. NetLock RMM deployments use a fixed compose-file path, so from the host this single command is all you need:
Note: The database structure updates automatically when the new server image starts. There are no manual migration steps. The agent installer packages the server distributes are refreshed at the same time.
From version 3.3.0.11 the server and Web Console images run as the unprivileged user 1654 where the compose file allows it. With the compose file from the guided installer nothing changes: the containers keep running as root and the log shows how to switch. With the compose file from the manual installation guide the containers take ownership of their data directories and switch to user 1654 on their own. With user: "1654:1654" set on both services they start as that user directly.
With the compose file from the manual installation guide, a custom TLS certificate file in /home/netlock/certificates must be readable for user 1654 (chmod 640 and chgrp 1654), otherwise the container keeps running as root and names the file in its log. Once user: "1654:1654" is in the compose file, do not go back to an image older than 3.3.0.11. The details, the log lines and the two steps to switch an existing installation are in Running the containers as an unprivileged user.
To avoid pulling manually, you can run a container-update watcher such as Watchtower alongside the stack. The command below starts Watchtower with a 15-minute check interval:
Agents update themselves. Once the server offers a new agent version, every agent whose policy has Auto-update agent on installs it on its next sync.
The policy option. In the Policy Settings editor, on the Agent tab, Auto-update agent is on by default. Leave it on; turn it off only for a golden image. See Chapter 6.
The concurrency limit.Max concurrent installations & updates in Settings → Updates caps how many agents update at the same time. See A.2 for what the value controls and how to size it.
Agent not updating. Check that Auto-update agent is on in the device's policy. If it is off, the agent stays on its current version.
Slow rollout. Raise Max concurrent installations & updates in Settings → Updates, within what your network bandwidth supports; see A.2.
An agent upgrade failed. The Health agent repairs a failed agent update on its own, usually within about 15 minutes. If the device stays offline, see Debug an agent.
An update appears stuck on the server. Inspect the container logs with docker logs <container-id> to see what the service reported.
A NetLock RMM cloud instance is reachable at an address we generate for it, something like 8f3c…-…-….n2.cloud.netlockrmm.com. You can put a subdomain of your own in front of it, for instance rmm.example.com, so your technicians open the Web Console at an address that belongs to you.
You set the domain in the Members Portal, create one DNS record, and the certificate is obtained and renewed for you. The original address keeps working the whole time; both addresses lead to the same Web Console.
This applies to cloud instances only. A self-hosted installation already runs on whatever address you gave it.
Use a subdomain, not the domain itself.rmm.example.com works; example.com does not. The record type needed here is a CNAME, and DNS does not allow a CNAME on the domain itself. Some providers offer "ALIAS" or "CNAME flattening" at the apex. Those resolve to address records and are not accepted.
Switch the proxy off for this record. If your DNS provider puts traffic through its own network (Cloudflare calls this the orange cloud), the record cannot be verified and no certificate can be issued. Use "DNS only" (grey cloud) for this record.
Check your CAA records. If your domain has CAA records, they have to allow letsencrypt.org to issue certificates. A domain without any CAA records needs nothing, which is the common case.
International domains go in as Punycode. Enter xn--bcher-kva.example.com, not bücher.example.com.
One domain per instance, and a domain can only be used on one instance.
The record is not visible yet, or points somewhere else. The message below the status says what was actually seen, which is usually enough to spot a typo.
DNS record found
The record is correct. The routing is set up in the next few minutes.
Being set up
The routing is being written.
Issuing the certificate
Your domain is routed and the certificate is being obtained. Until it arrives, opening the domain shows a certificate warning. This is expected and goes away once the certificate is issued.
Active
Done. The domain serves the Web Console with its own certificate.
Needs attention
The domain worked and something changed, usually the DNS record was removed or repointed. The Web Console keeps answering until the certificate expires; fix the record and the status returns to Active on its own.
Failed
Verification or certificate issuance did not succeed. The message says why. Try again starts over.
A new DNS record is usually visible within minutes; some providers take a few hours. Verification is given three days, after which the entry is marked as failed and you can start over.
Your users can open the Web Console at either address. A few things are tied to the address they were set up with:
Passkeys. A passkey belongs to the address it was registered at. If your users sign in with passkeys, have them register one again at the new address.
Single sign-on. Add the redirect URI of the new address at your identity provider, in addition to the existing one. The Console shows both URIs under Settings → SSO. See Enable SSO with Azure AD / Google.
Bookmarks, the mobile app and QR codes. These keep pointing at the address they were created with. Both addresses work, so nothing breaks, but a QR code scanned before the change still enrols against the generated address.
Screen control. The new address registers itself the first time somebody signs in through it; no action needed.
Both are done from the same block on the cloud card.
Change: press Change domain and enter the new one. Create the CNAME record for the new domain as before. A domain can be changed once per hour and five times per week.
Remove: press Remove. The routing is taken off within a few minutes and the domain is free to be used again, on this instance or another one. The Web Console stays reachable at its generated address.
"No CNAME record was found for this domain." The record does not exist yet, has not propagated, or you created an A record instead of a CNAME. If the message mentions an address record, that is what happened, or you used the domain itself instead of a subdomain.
"The CNAME record points somewhere else." The message names the target that was seen. Compare it with the target in the dialog; a missing label or a copied trailing dot is the usual cause.
"The DNS record is not visible everywhere yet." Two independent resolvers are asked and they do not agree yet. Wait a few minutes and check again.
"A CAA record of your domain does not allow Let's Encrypt." Add a CAA record for letsencrypt.org, or remove the restricting one.
The browser shows a certificate warning. If the status is Issuing the certificate, wait until the certificate has been issued. If the status is Active and the warning persists, the browser is probably showing a cached page; reload without cache.
The status stays Needs attention. The DNS record was changed or removed after the domain went live. Put it back and the next check restores the status.
The block does not appear on the card at all. The block appears on running cloud instances. If your instance is running and the block is missing, contact support.
NetLock RMM separates the Script (the code) from the Job (the schedule). A script lives in the Scripts library and can be reused; a job picks a script and defines when and how often it runs. This guide walks through authoring a trivial PowerShell script, saving it, and wrapping it in a job that runs once on a target device. See Chapter 8.1 and Chapter 8.2 for the full reference on both.
At least one Windows device is online and assigned a policy, so the agent is ready to execute a job.
Required permissions: collections_enabled, collections_scripts_enabled, collections_scripts_add for the script; collections_jobs_enabled, collections_jobs_add for the job.
In the navigation, open Collections → Scripts (route /manage_scripts).
Click Add to open the Add Script dialog.
Fill in the fields:
Name: for example Return current date.
Description: a one-liner so others know what it does.
Default timeout: accept the default for a small script.
Platform: Windows.
Shell: PowerShell.
Paste a trivial command into the editor:
Get-Date
Save. The script now appears in the Scripts list.
Tip: The shell dropdown offers supported Platform / Shell pairs: Windows → PowerShell or Python3; Linux → Bash or Python3; macOS → Zsh or Python3; and System → MySQL for SQL-only scripts that run against the Console's own database.
Exit code: the job reports the exit code of the script: exit n, or the exit code of the native command the script ends with. A terminating error reports 1. A script that ends with a non-zero native command (for example robocopy, which returns 1 when files were copied) therefore shows that code; end the script with exit 0 when that is the intended result.
Tip: The one-shot job below exercises the full job-execution path, but it is slow to iterate on. Every change means editing the script, waiting for the scheduled time, and waiting for the next agent sync. While you are still getting the script's logic right, test it faster through the Remote Shell: open the target device, start a Remote Shell session, and run the commands directly for immediate output with no sync delay. Remote Shell must be enabled in the device's policy (Agent tab → Remote Control); see Chapter 6.4. Once the logic is correct, run it once as a job as well to confirm it behaves the same under the agent's job runner, because the two are different execution contexts.
In the navigation, open Collections → Jobs (route /manage_jobs).
Click Add to open the Add Job dialog.
Fill in:
Name: for example Return current date (one shot).
Description: optional.
Timeout: accept the default.
Schedule: pick Date/Time (a one-shot schedule) and set the time a few minutes in the future.
Platform: Windows.
Type: PowerShell.
Script: pick the script you just created.
Hidden: leave off, so you can find the result in Events afterwards.
Save.
Attach the job to a policy that routes to your test device: open Policies → Manage, pick the policy, open the Jobs tab, and enable the new job. Save the policy.
At the configured time the device's agent picks up the job, runs the script, and reports the result back.
To convert this into a recurring job, edit the job and change the Schedule field from Date/Time to a recurring option, for example On specific days at time with a day-of-week toggle, or Every X hours. Save. Devices already assigned the job start using the new schedule on their next sync.
Job never fires. Confirm the policy that carries the job is assigned to the device (Devices → detail → Assigned policy). If not, fix the automation.
Job runs but no result appears in Events. The job may be flagged Hidden. Hidden jobs do not write to the Events view. Clear the flag for general-purpose scripts and reserve it for Custom-Field data collectors.
Script times out. Raise the Default timeout on the script, the Timeout on the job, or both. Script timeouts are enforced and the script is terminated when the limit is hit.
A script in the Scripts library can refer to data of the device it runs on and to custom field values. The values are filled in per device when the script is handed out, so one script serves hundreds of tenants without a copy per customer. A typical case is an antivirus installer that needs the customer's OU id: the id lives in a custom field on the tenant, the script reads it through a variable.
Required permissions: collections_scripts_enabled plus collections_scripts_add or collections_scripts_edit for the script; collections_custom_fields_enabled to see custom fields in the editor's variable menu and in the preview.
A custom field definition with at least one Manual field. A field that should be set once per tenant, location or group must be marked Inheritable in the builder.
A variable is written as a token with a namespace and a key:
{{namespace.key}}
Spaces inside the braces are allowed. The key may contain letters, digits, underscores and hyphens. The six namespaces:
Namespace
Reads
Example
device
A built-in property of the device (see the table below).
{{device.name}}
field
A custom field of the device, with inheritance from group, location, tenant and global level for inheritable fields.
{{field.av_ou_id}}
tenant
The value stored on the device's tenant, without inheritance.
{{tenant.av_ou_id}}
location
The value stored on the device's location, without inheritance.
{{location.av_ou_id}}
group
The value stored on the device's group, without inheritance.
{{group.av_ou_id}}
global
The global value, without inheritance.
{{global.av_ou_id}}
Fallback. A token may carry a default after a pipe: {{field.av_ou_id|ou-default}}. The fallback is used when the variable cannot be resolved and also when the resolved value is empty. When the same variable appears several times with different fallbacks, the first non-empty fallback is used. Without a fallback an unresolved or empty variable is an empty string.
Native names. Every variable also has an environment variable name of the form NL_<NAMESPACE>_<KEY>, for example NL_FIELD_AV_OU_ID or NL_DEVICE_NAME. A script may use that name directly in the shell's own syntax ($env:NL_FIELD_AV_OU_ID, ${NL_FIELD_AV_OU_ID}, os.environ['NL_FIELD_AV_OU_ID']) instead of a token. Both forms are resolved the same way and can be mixed. The name is derived from the key: the key is written in upper case and every character that is not a letter or a digit becomes an underscore, so the keys av_ou_id and AV-OU ID both map to NL_FIELD_AV_OU_ID.
What is not a variable. Only the six namespaces are recognised. Other double braces such as {{0}} in a PowerShell format string or a Python format escape are left untouched.
{{field.key}} names a custom field by its key. The key is the Key of the field in the custom field definition; the definition name is not part of the token.
Inheritance. The value is looked up in this order, and the first level that holds a value wins:
the device's own value,
the device's group,
the device's location,
the device's tenant,
the global value.
Levels 2 to 5 are only consulted for fields marked Inheritable in the definition. A field without the flag has device values only. A level the device does not have (a device without a group) is skipped.
Explicit levels.{{tenant.key}}, {{location.key}}, {{group.key}} and {{global.key}} read exactly that level and nothing else, whether the field is inheritable or not. Use them when a script needs the tenant's value even though the device carries its own.
Which fields work. Fields with the data source Manual of type Text, Multiline or Secret. Only inheritable manual fields can hold level values; Job Result and SQL Select fields have no level values and are read from the device only.
Key rules and legacy keys. A key is a lowercase identifier: it starts with a letter and continues with lowercase letters, digits and underscores, at most 64 characters. Keys that do not follow this rule, for example AV-OU ID, work through their native name (AV-OU ID is reachable as NL_FIELD_AV_OU_ID); a key with a space cannot be written as a token. The Insert variable menu handles this for you and inserts the native reference for such a key. When two definitions share a key, scripts receive the value of the definition that was created first; the menu marks such keys.
Unknown keys. A token whose key no definition knows resolves to an empty string on every device. Saving a script with such a token shows a warning with the token names; the script is saved anyway. The server also writes a warning to its log each time the script is rendered.
Values are never pasted into the script text. The server defines every referenced variable as an environment variable in one prelude line and replaces each token by the shell's reference to that variable. A value therefore stays data whatever it contains; a script has to execute it explicitly (Invoke-Expression, eval) before it can act as code.
import os as _nl_os; _nl_os.environ['NL_FIELD_AV_OU_ID'] = 'ab\'c'
_nl_os.environ.get('NL_FIELD_AV_OU_ID', '')
Rules that follow from this:
Single quotes do not expand. In PowerShell, Bash and Zsh a token works bare ($ou = {{field.av_ou_id}}) and inside double quotes ("OU: {{field.av_ou_id}}"). Inside single quotes the shell keeps the reference literally, so '{{field.av_ou_id}}' does not give you the value.
In Python a token is an expression. Write ou = {{field.av_ou_id}} or print("Device: " + {{device.name}}). Inside a string literal the token is not evaluated.
The value is always a string.{{device.id}} in PowerShell is the string "42", not a number. Cast it when you need a number.
Values with line breaks and special characters are escaped so that the prelude stays a single line and the value arrives unchanged, including quotes, $, backticks and typographic quotation marks.
Where the prelude line goes. The line is not always placed on line 1:
PowerShell: after leading comments, #Requires lines, <# ... #> blocks, using statements, attribute lines such as [CmdletBinding()] and the param(...) block, so param stays the first statement.
Bash and Zsh: after a shebang on line 1.
Python3: after a shebang, leading comments including an encoding comment, a module docstring and from __future__ imports.
Because the prelude is exactly one line, line numbers in error messages are shifted by one. The script's line ending style (CRLF or LF) is kept.
A script without variables is delivered unchanged. A script that names no token and no native name is not touched.
Warning: A PowerShell script that uses param(...) followed by named blocks (begin, process, end or dynamicparam) cannot take a statement between param and the first block. The prelude line would be placed there and the script fails to parse. Do not combine variables with that script layout.
Variables are resolved at the moment a script is handed to a device, always for exactly that device:
Path
Shell used for rendering
Jobs of a policy
Python3 when the job type is Python3, otherwise the platform default: PowerShell on Windows, Bash on Linux, Zsh on macOS
Script sensors of a policy (script)
PowerShell, Bash, Zsh or Python3 according to the sensor category
Action scripts of a sensor
The action script language when one is set; otherwise Python3 for Python sensors, otherwise the platform default
Remote shell, classic mode
The shell chosen in the dialog (platform default or Python3)
Remote shell, real-time terminal, template run as a script
The terminal's shell: PowerShell, Bash, Zsh or Python3. CMD is not rendered
Bulk remote shell
Per device, by the device's platform
Sensor live test (console and API)
As for the sensor
Public API run-command and run-script
The language of the request or the platform default; cmd is not rendered
Jobs and sensors are rendered when the server builds the device's policy; the script stored in the library, in the job and in the sensor keeps its tokens. Remote shell and API calls render at send time.
Not rendered: System scripts (MySQL), the CMD shell of the real-time terminal, Software Deployment and App Hub install scripts, patch management, and text fields that are not scripts (a sensor's expected result, job names, MOTD messages, webhooks).
When resolution fails. A database error while resolving is handled per path: a policy keeps the tokens in the script and the server logs an error with the job or sensor name; the remote shell and the live test refuse to send and show an error; the public API answers 500 (a bulk entry is marked dispatch_failed). An empty value because of an unknown key is not a failure; see above.
A field of type Secret is used in a script like any other field: {{field.av_token}}. The script does not see where the value comes from and receives the plain text. Keep these points in mind:
Whoever can run a script on a device can read every value that device receives. That includes secrets. The audit entry of a remote shell, bulk shell or live test dispatch lists the names of the referenced variables and, separately, the names of the referenced secret variables, never the values; the stored command text is the unrendered script. The public API likewise keeps the unrendered text in the action record.
Do not print a secret. Script output lands in events (including the Remote Shell event of a classic remote shell command) and in API results.
The preview masks secrets for everyone, including accounts that hold the reveal permission.
A device fetches its policy again only when it is marked for a re-sync. Every write path marks the affected devices:
a device value marks that device,
a group, location or tenant value marks the devices of that level,
a global value marks every device.
The next check-in of the device brings the policy with the new values; jobs and sensors use them from then on. A value written back by a script marks the device only when the value actually changed. The remote shell and the public API render at send time and always use the current values.
Each entry has a copy button for its native name. A key that does not follow the naming rule is marked and inserts the native reference in the syntax of the selected shell instead of a token. A key that also exists in an earlier definition is marked, with the name of the definition whose value scripts receive. For the System platform the menu is disabled, because MySQL scripts are not rendered.
Preview for device in the dialog's button row renders the current editor text for a device of the script's platform, online or not, and shows:
a table of the referenced variables with token, native name, value and source (Built-in, Device, Group, Location, Tenant, Global, or None when no level holds a value), with an Unknown key chip where no definition knows the key;
the prelude line;
the rendered script, with a copy button for both.
Secret values are masked. An account without collections_custom_fields_enabled sees the built-ins resolved and every field reference with an empty value and the source Hidden. For a script without any reference the preview says so and shows the text unchanged; for a MySQL script it says that scripts of this shell are delivered unchanged.
Saving. When the script names a key no definition knows, saving shows a warning listing the tokens. The script is saved.
The customer's OU id differs per tenant, the installer URL is the same for everyone.
In Collections → Custom Fields, add a definition with a section holding two fields, both of type Text with data source Manual and Inheritable enabled: key av_ou_id (label AV OU id) and key av_installer_url (label AV installer URL).
Open Settings → Custom Fields, section Global values, and set av_installer_url to the download URL.
For each customer open the tenant's Manage tenant page, section Custom Fields, and set av_ou_id to the customer's OU id.
Create a Windows / PowerShell script:
# Installs ExampleAV with the tenant's OU id when it is not installed yet.$ou = {{field.av_ou_id}}if ([string]::IsNullOrWhiteSpace($ou)) { Write-Output "No OU id configured for tenant {{device.tenant}}; nothing to do." exit 0}$installed = Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*', 'HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*' -ErrorAction SilentlyContinue | Where-Object { $_.DisplayName -like 'ExampleAV*' }if ($installed) { Write-Output "ExampleAV is already installed on {{device.name}}." exit 0}$installer = Join-Path $env:TEMP 'exampleav.msi'Invoke-WebRequest -Uri {{global.av_installer_url}} -OutFile $installerStart-Process msiexec.exe -ArgumentList "/i `"$installer`" /qn OU_ID=`"$ou`"" -WaitWrite-Output "ExampleAV installed with OU $ou."
Click Preview for device, pick a device of the customer and check that av_ou_id shows the tenant's value with the source Tenant.
Delivered to a device of the tenant Contoso, the script starts like this:
# Installs ExampleAV with the tenant's OU id when it is not installed yet.$env:NL_FIELD_AV_OU_ID = 'ou-4711'; $env:NL_DEVICE_TENANT = 'Contoso'; $env:NL_DEVICE_NAME = 'PC-01'; $env:NL_GLOBAL_AV_INSTALLER_URL = 'https://downloads.example.com/exampleav.msi'$ou = ${env:NL_FIELD_AV_OU_ID}if ([string]::IsNullOrWhiteSpace($ou)) { Write-Output "No OU id configured for tenant ${env:NL_DEVICE_TENANT}; nothing to do." exit 0}
A device with its own av_ou_id value uses that value instead of the tenant's; a device in a tenant without a value skips the installation and says so in its job result.
The token appears literally in the output. The token is inside single quotes, or the script runs through a path that is not rendered (a CMD terminal, a System script, a deployment script).
The value is empty on every device. The key is unknown or misspelt. Open the script and save it: the warning names the tokens no definition knows. For a legacy key with spaces or upper-case letters, use the native name from the Insert variable menu.
The value is empty on some devices. Those devices, their groups, locations and tenants hold no value and there is no global value, or the field is not marked Inheritable. Check the effective value on the device page or with Preview for device.
A job still uses the old value. The device has not checked in since the value changed. Wait for the next check-in or force a sync from the device page.
A PowerShell script fails to parse after adding a variable. See the warning about param with begin/process/end blocks above.
A script can store values in custom fields of the device it runs on. This keeps inventory data that no built-in sensor covers, such as the LAPS status, the Entra ID join state or the BitLocker protector types, up to date from a recurring job. Reading values in a script is described in Script variables and custom fields in scripts.
Note: Deploy the web console first, then the server, then the agents.
A custom field definition with a Manual field of type Text, Multiline or Secret whose key the script will write, for example laps_status. The field does not need to be inheritable.
Call the helper with the field key and the value. The helper is defined in the prelude line of the script whenever the script mentions it; see What happens on the device.
The Insert variable menu of the script editor lists the three calls under Write back to custom fields and inserts them at the cursor. The Preview for device dialog marks a script that writes back and shows the helper in the prelude line.
A script that calls the helper and refers to no variable gets a prelude line with the helper only. A script that does neither is delivered unchanged.
The marker line. The helper prints one line per call to standard output:
NETLOCK_FIELD_SET:<key>:<base64 of the UTF-8 value>
You can print that line yourself, from any language, as long as it starts at the beginning of a line. The line is taken out of the output before the output is logged, matched or shown, so it never appears in an event or in an API result.
Warning: Every output line that starts with the marker sets the field, including a line that comes from a file or a web response your script prints. Do not print untrusted text unfiltered.
The server checks every value before it is stored:
Key. Letters, digits, underscores and hyphens, 1 to 255 characters. The key is matched to the field the same way a variable is resolved: written in upper case with every other character turned into an underscore, so a script may write AV_OU_ID for a legacy key AV-OU ID. The value is stored under the key as spelt in the definition. When two definitions share a key, the value goes to the definition that was created first, the one a script also reads from.
Field. A Manual field of type Text, Multiline or Secret. A Job Result field, a SQL Select field and a manual Table field are rejected.
Size. At most 64 KB per value and at most 50 values per run. Values beyond the limit are rejected.
Duplicates. When a run writes the same key several times, the last value wins.
A rejected value is reported back to the agent and logged with the key and the reason (unknown_key, not_manual, too_large, invalid_key, or invalid_base64 for a hand-written marker line); the value itself is never logged. Rejections are not shown in the console. Check the agent log (jobs and sensors) or the server log (remote shell) when a value does not arrive.
What is stored. The value is stored on the device with the source script; the device page shows an icon next to the value whose tooltip reads Set by script on <date>, and the public API returns "source": "script". A Secret field is stored encrypted like a value entered in the console. A write-back sets the device's own value; it never writes to a group, location, tenant or global level.
Policy re-sync. The device is marked to fetch its policy again only when the stored value actually changed. A recurring job that writes the same value every hour updates the timestamp and the source, but does not trigger a re-sync.
Marker lines are removed before the job result is logged and put into the event. Hidden jobs write as well.
Script sensors and their action scripts
Comm agent
Marker lines are removed before the expected result is matched and before the action history and the event are written.
Sensor live test (console and POST /v1/sensors/{id}/test)
Comm agent
Nothing is written. The result lists Would set: <keys> under further information.
Remote shell, classic mode
Server
Includes Run as user. The cleaned output goes to the dialog and the Remote Shell event.
Bulk remote shell
Server
Per device.
Public API run-command and run-script
Server
The action record and the Remote Shell event hold the cleaned output.
Real-time terminal
Server and Remote Agent
See the limits below. CMD has no helper.
Timeout. A job or sensor script that runs into its timeout returns only the timeout message. Its output, and with it every value it wrote, is lost for that run. Keep write-back scripts well inside their timeout.
Expected result. The expected-result pattern of a script sensor is matched against the cleaned output. A pattern that looks for NETLOCK_FIELD_SET: never matches.
PowerShell scope.Set-NetLockField is a function in the script's scope. It is not visible inside ForEach-Object -Parallel, Start-Job or Invoke-Command (a different runspace). Collect the value in the main scope and call the helper there.
Captured output. The PowerShell helper writes through [Console]::Out, not through the pipeline, so $x = Set-NetLockField ... or Set-NetLockField ... | Out-Null do not swallow the marker line. The Bash and Python helpers print to standard output; do not redirect it away.
The real-time terminal streams the shell's output. The server watches the stream for marker lines, removes them and stores the values; the Remote Agent already removes them on the device. Two limits follow from the terminal:
Long values on Windows. The Windows terminal can break a line that is longer than the terminal width into several lines. A marker line with a long value can then be torn: the value is rejected as invalid base64 and the remainder appears in the terminal. Keep values written from the terminal short (a status word, an id), or use the classic mode or a job for long values.
CMD has no helper. Write-back works in the PowerShell, Bash, Zsh and Python terminals only.
A marker line without a line break is held back until more output follows or the session ends. A prompt that ends in the first letters of the marker appears together with the next output.
While a template runs as a script in the terminal, the rendered script, prelude line included, is staged as a file in the Remote Agent's program data under Scripts\RealTime on the device and removed when the session ends; leftovers of an interrupted session are removed when the agent starts. The terminal always runs as SYSTEM or root, so a value written from it is the device's value.
Note: Do not write recovery passwords into custom fields. Recovery keys are escrowed by the BitLocker management of NetLock RMM and are readable only through its own, audited paths.
Each example runs as a recurring job (for example Every X hours) attached to the policy of the devices; see Write, test, and schedule a PowerShell script. Flag the job Hidden when its only purpose is to feed the field.
The value does not arrive and the agent log says unknown_key. No definition has a manual field with that key, or the key is misspelt. not_manual means the field is a Job Result, SQL Select or Table field.
The value does not arrive after a run through the real-time terminal on Windows. The value was longer than the terminal line. Use the classic mode.
The device does not pick up a changed job. The value was the same as before; only a changed value marks the device for a re-sync.
Self-hosted only: This chapter is written for self-hosted deployments. On cloud, the hosted operations team runs the deployment and manages licensing: Settings → Overview shows only the Public console URL panel, and the Licensing entry is hidden, so opening /settings/licensing directly returns to the dashboard.
This chapter covers two administrative pages that show the deployment operator how the system is performing and what the current licence allows. Both are mostly read-only: the System Overview page is read-only apart from three settings, the System Storage Limit, the public backend URL and the public console URL, and the Licensing page is read-only apart from replacing the Members Portal API key. Connection strings are never editable in the Console; they are changed outside it, in appsettings.json.
Settings → Overview at /settings/overview is the place to check first when you want to know at a glance whether everything is healthy. It is almost entirely a monitoring page and shows the live state of the four subsystems a self-hosted NetLock RMM deployment depends on, using the same data the agents and backend services use to do their work. The exceptions are the System Storage Limit, Public backend URL and Public console URL panels, each of which carries a single editable setting; everything else on the page is read-only.
The database section answers two questions: is the database reachable, and is it under load. A status icon at the top of the section turns green when the Console has an active connection to MySQL and red when it does not. The panel reports:
Version: the MySQL server version string.
Uptime: elapsed seconds since the MySQL instance started.
Active connections: the number of sessions currently open against the server.
Database size: total size of the NetLock RMM database, in bytes.
Max connections: the configured upper limit for concurrent sessions.
Failed logins: a running count of authentication failures since the database started.
Below those counters, a searchable table lists every active query the database is currently executing. Columns are Id, User, Host, Database, Command, Time, State, and Info. Open this view first when the Console feels slow. A long-running query or a connection pile-up often shows up here before it shows up anywhere else.
Three cards summarise how much resource the machine hosting the Web Console is using right now:
CPU usage: a percentage with a progress bar.
RAM usage: a percentage with a progress bar, plus a Used / Free / Total breakdown in GB.
Disk usage: a percentage with a progress bar, plus a Used / Free / Total breakdown in GB.
The values are sampled from the Web Console host, not from any individual managed device. Use the section as an early warning when the Console itself is about to run out of headroom. A sustained high CPU number on this panel means the host needs more resources; the managed devices are not involved.
The System Storage Limit panel caps how much data NetLock RMM may store on disk. The on-screen description states this covers the devices/ and internal/ folders together with the MySQL database size.
A usage card shows current consumption as <current> GB / <limit> GB with a progress bar that shifts from green to amber at 90% and to red at 100%, plus a line reporting how many GB remain.
A second card carries the editable control: a Storage limit (GB) numeric field (1 to 999999) and a Save button. Set the value and save it to change the cap.
When consumption crosses a threshold, the Console opens a dialog automatically: a warning at 90%, and at 100% a limit-reached dialog that cannot be dismissed by clicking away until you free space or raise the limit.
Two smaller panels report the Console's ability to reach the other two backend services in a NetLock RMM deployment.
NetLock RMM File Server: shows Connected when the Console can talk to the File Server, Not connected otherwise. The File Server is responsible for agent downloads, script artefacts, and attachment storage.
NetLock RMM Remote Server: shows Connected when the Console can talk to the Remote Server, which handles remote control sessions and relay. A failed check here is accompanied by a PTR-mismatch warning when the probable cause is a reverse-DNS misconfiguration; the warning includes a link to the relevant documentation.
If either panel shows Not connected, use the Check again action at the top of the page to re-run the connectivity probe without reloading the entire page. Check again only retests the two service endpoints and updates their status chips, so during an incident you keep any search you have already typed into the MySQL active-queries table.
A persistent Not connected state on either service is a signal to check the service's own host. For the File Server, confirm the service is running and that the Console host can reach it on its configured port; for the Remote Server, confirm the service is running and the public DNS record resolves, including a matching PTR record.
The Public backend URL panel holds the address under which agents and browsers reach the installation from outside, for example https://rmm.example.com. The Console uses it for agent installer and download links, remote screen control and web access sessions; the server uses its host part over HTTPS for the same purposes. When no URL is set, the configured File Server and Remote Server addresses are used instead. The value is the same one that Webinterface:PublicOverrideUrl in the Console's appsettings.json carries; because that file is encrypted after the first start, this panel is the place to change it.
The first card shows the URL the running Console uses (Active URL, or Not configured). The second card, shown only to accounts with settings_overview_manage, takes a new URL. The field accepts a scheme, a host and an optional port (https://rmm.example.com or https://rmm.example.com:8443), with no path, query or fragment. Trailing slashes are removed; otherwise the value is stored as typed, so a port such as :443 is kept. Save asks for confirmation and stores the URL; Clear URL (offered while a URL is stored) removes it after confirmation. Both actions write an audit entry with the previous and the new value.
A saved change does not take effect immediately. The running Console keeps its URL and the panel shows a Restart required notice with the change until the web console and the server have been restarted:
docker compose downdocker compose up -d
Without Docker, restart the NetLock RMM Web Console service and every NetLock RMM Server service.
On start, the Console compares the stored URL with the one in its appsettings.json:
A file value the Console wrote itself yields to the stored value, so a URL saved or cleared on this page becomes the active one and is written back into the file.
A URL entered into appsettings.json by hand takes precedence and is written to the database.
An empty file value never removes a stored URL. Use Clear URL for that.
The server reads the stored URL when it starts. A value saved on this page is already in the database when the stack restarts, so the start order does not matter. After you edit the URL in appsettings.json by hand, restart the Console first and then the server.
The Console writes appsettings.json in place, so the file keeps its owner and permissions. It has to be writable for the user the Console runs as. In a Docker installation that is user 1654: the guided installer sets the ownership when it creates the file, and on a host with the compose file from the manual installation guide the container takes ownership at start (see Running the containers as an unprivileged user).
If the file could not be written at the last start, the panel shows a notice, and the URL in the file takes precedence on every start until the file is writable again. The same applies to the other settings the Console writes into the file (the logging switch, the Members Portal API key, the membership reminder), which report a failed write instead of appearing saved.
The Public console URL panel holds the address under which people reach the web console, for example https://console.example.com. Links into the console are built from this value and from nothing else: the {{url}} placeholder of ticket webhooks and the Open ticket line of ticket notification mails, for tickets created in the console as well as through the public API, from the tray icon or from a device.
While no URL is set, {{url}} is empty and notification mails contain no link. Webhooks and mails are sent as usual. The panel, the Webhooks dialog, the Notifications section of a department and Settings → Ticket System show a notice until a URL is set.
The panel is visible with settings_overview_enabled; changing the value needs settings_overview_manage. Use this browser's address copies the address the page is open under into the field, Save asks for confirmation and stores it, and Clear URL removes it after confirmation. The field accepts a scheme, a host and an optional port, as for the public backend URL. Both actions write an audit entry with the previous and the new value. No restart is needed: the Console uses a saved value at once, and a running server picks it up within a minute. The value is stored in the database only; a self-hosted installation has no appsettings.json key for it.
On cloud, the address of your instance is filled in for you and follows a custom domain when it goes live or is removed. A URL you save yourself stays in place until you clear it. After Clear URL NetLock Cloud fills in the address of your instance again, at the latest at the next start of the web console, so on cloud the panel cannot stay empty for good.
Apart from the System Storage Limit, the Public backend URL and the Public console URL, the Overview page is read-only. Its interactive controls are the Save buttons for these settings, Clear URL, Use this browser's address, and the Check again button for the service connectivity probes. To change any of the monitored values (MySQL connection string, File Server URL, Remote Server URL), edit appsettings.json on the Console host and restart the Console. Connection strings belong to the deployment, not to the runtime configuration, so the Console has no editor for them.
Settings → Licensing at /settings/licensing reports the status of your NetLock RMM licence against the Members Portal. Like Overview, this page is mostly read-only. Besides refreshing the licence information, the only thing you can change here is the Members Portal API key.
The API Configuration section at the top of the page shows the key the Console currently runs with as Active API key, masked down to its last four characters, or No API key configured. The full key is never shown.
Accounts with settings_licensing_manage also see a New API key field and a Replace API key button:
The Console checks the new key against the Members Portal. A key the Members Portal does not accept (unknown, or belonging to a banned, expired or inactive membership) is not saved. If the Members Portal cannot be reached, the Console asks whether to save the key anyway.
The key is stored encrypted in the database. The audit log records the change with the last four characters of the previous and the new key.
The page shows Restart required with the masked new key, the Docker commands to restart the services, and a copy button. The web console and the server keep running with the current key until they are restarted; on start they adopt the new key and fetch the licence and the agent packages for it.
A status badge: Active (green) when the licence is in good standing, Expired (red) when it has lapsed.
The licence name, which reflects the tier you are subscribed to.
A code-signing row. When code signing is included in your tier, the line reads Code signing enabled. When it is not, the line reads Code Signing not available with the sub-text Available from Tier 1 for professional deployments. Code signing determines how managed devices trust agent installers.
A licence-count row shown as X / Y with a progress bar, where X is the number of seats you are currently consuming and Y is the total you are licensed for. Only approved devices consume seats. Unauthorised devices (see Chapter 3.2) do not count until they are approved.
Replace API key: in the API Configuration section, shown only with settings_licensing_manage. See Members Portal API key above.
Refresh License Information: re-fetches the licence record from the Members Portal. The button is disabled when no API key is configured. Use this after adding seats or upgrading a tier. The Console caches the licence state and does not re-query it automatically. The button updates only the Web Console; the server loads its licence when it starts. After a renewal of a licence that had already run out, follow Reload licence information after a renewal.
Upgrade: shown only when code signing is not available for your current tier. The button opens https://www.netlockrmm.com/pricing in a new tab so you can compare plans. Upgrades are handled on the pricing page and through your account manager, not inside the product.
Billing is not shown in the product. To change the plan, use the pricing page or the Members Portal, then come back to the Licensing page and click Refresh License Information to pull the updated status. A replaced API key does not take effect before the web console and the server have been restarted.
Licensing settings are not accessible on cloud deployments, because the cloud team handles billing and licensing centrally. The navigation entry is hidden, and opening the page directly returns to the dashboard.
The listed flags must be set on a user's permission matrix (see Chapter 14) for the corresponding page to appear in the navigation, or for the action to be offered.
This chapter covers two small admin pages that are often needed together during maintenance work: the Updates page, which controls how aggressively the server rolls updates out to agents, and the Maintenance page, which lets you silence outbound notifications while you do planned work. A third section covers the notice self-hosted deployments see when the MySQL server behind the Console has fallen out of support.
The Updates page has one setting, the concurrency cap. NetLock RMM itself is updated outside the Console; see Upgrade NetLock RMM.
Max concurrent installations & updates is a numeric value that caps how many devices the server will process at the same time when installing new software packages or applying update approvals. Ranges differ by deployment:
Two information panels on the page explain why the cap exists, which helps you pick a sensible value:
In-memory package delivery. The server loads each installation package into memory once and serves every download from that single cached copy. Holding more downloads open at the same time does not multiply that memory. The cached packages are a fixed cost, independent of the concurrency number. Because delivery is from RAM, neither disk I/O nor CPU limits the rollout; network bandwidth does.
Bandwidth-limited rollout. Even on a fast network, the agents in any given location share egress. A concurrency ceiling keeps a mass rollout from saturating a branch uplink or degrading the Console for other users. Each in-progress update also writes to the MySQL database in the background, so the database host's capacity is a secondary consideration when setting a high value.
The cloud cap of 50 reflects the capacity of the hosted platform. On self-hosted deployments you can raise the number up to 9999, but the practical ceiling is almost always lower. It is set by your available network bandwidth and, to a lesser degree, by the MySQL database load that concurrent updates generate. Start with a low value and measure before raising it.
After editing the number, click Save. The new value takes effect on the next rollout cycle; no restart is required. The throttle affects the queues used for software deployment (Chapter 8.8) and patch approvals (Chapter 7), but does not affect one-off remote actions such as reboot, shutdown, or scripted jobs.
Settings → Maintenance at /settings/maintenance switches notifications off while you work. It only stops outbound notifications from leaving the server: agents keep running, scripts keep executing, and events are still recorded. When a planned maintenance window lifts, events that accumulated during the window are automatically marked as read rather than surfacing as a backlog of alerts.
A live status banner at the top of the page reflects the current state. When any trigger is active, it reads:
Maintenance mode is currently ACTIVE. Notifications are being suppressed (manual toggle | window '<name>' | …).
When nothing is active, it reads:
Maintenance mode is currently inactive. Notifications are being processed normally.
The banner lists which trigger is causing suppression, so if both a manual toggle and a scheduled window are active you will see both called out.
The page has two tabs: Manual and Scheduled Windows.
The Manual tab has a single toggle, Enable manual maintenance mode, and a Save button.
When the toggle is on, the server suppresses outbound notifications on every channel the deployment has configured:
Mail
Microsoft Teams
Telegram
ntfy.sh
Webhook
Events still accumulate in the Events log as they normally would, and during suppression they are automatically marked as read, so switching the toggle off does not bring up a backlog of overnight alerts.
Use the manual toggle for unscheduled work, such as immediate reboots, network changes in progress, or a firewall reconfiguration where the fleet will temporarily look offline. Turn it off when you are done; it does not time out.
The Scheduled Windows tab covers recurring windows, for example a weekly Sunday patching slot that you want to suppress every week without remembering to toggle anything. The tab's master toggle, Enable scheduled maintenance windows, switches evaluation on and off as a group; when it is off, none of the configured windows apply.
Underneath the master toggle is a table of windows with one row per window and the following columns: Name, Weekdays, From, To, Timezone, Enabled, and Actions. Each row's Actions cell exposes Edit and Delete.
Click Add window to open the window editor. The editor fields are:
Name (optional): a friendly label. The helper text suggests something like Weekly Sunday Patch Window. The field is optional; when blank the table shows a record number instead.
Weekday checkboxes for Monday through Sunday. At least one weekday must be selected.
From: the window start time in 24-hour HH:mm format.
To: the window end time in 24-hour HH:mm format. When To is earlier than From, the window wraps past midnight. For example, From 22:00 and To 02:00 suppresses notifications from ten in the evening to two the next morning. The table row for such a window displays a +1d chip.
Timezone: the wall clock From and To are meant in. A new window starts with the instance display timezone (see Chapter A.5.2); Server time (legacy) keeps the window on whatever clock the server runs on.
Window enabled: per-window toggle. Disable a single window without deleting it when you want to keep its definition but skip it this month.
The server evaluates each window in the timezone stored with it, not in the user's browser time or personal display timezone. If your team is distributed across time zones, pick one zone for your maintenance rota and use it on every window.
Edit in the table actions reopens the editor with the existing values. Delete opens a small confirmation dialog titled Delete maintenance window with a body message of Delete window '<name or #id>'?. Confirm to remove the window permanently; there is no undo.
Viewing the page requires settings_maintenance_enabled. Making changes (toggling the manual switch, adding, editing, or deleting windows) requires settings_maintenance_manage. Without the manage flag, the page renders read-only: you can see the current state but none of the controls respond.
Self-hosted only: Cloud deployments never see this notice; the hosted platform runs the database for them.
The Console compares the MySQL server it is connected to with the recommended release, currently MySQL 8.4. When the server is older, two things appear:
A warning icon next to the update notice in the top bar (on phones, an entry in the account menu). It opens a dialog that names the running version, the date Oracle support ended where that is known, the recommended version and the steps of the Docker upgrade, with a link to the guide.
A warning above the status card on Settings → Database, with the same link.
Both are visible to accounts that hold settings_enabled and settings_database_enabled, the permissions of the Settings → Database page. The notice cannot be dismissed or snoozed; it disappears once the database reports version 8.4 or newer. The Console reads the version at start, once an hour, and every time Settings → Database loads, so after an upgrade a visit to that page clears the notice at once.
Release
Oracle support ended / ends
MySQL 5.7
31 October 2023
MySQL 8.0
30 April 2026
MySQL 8.4 LTS
30 April 2032
The innovation releases 8.1 to 8.3 are flagged as well; the notice shows them without a date. The upgrade itself happens at the host level. Upgrade MySQL to 8.4 walks through it for the Docker container.
Self-hosted only: The Database Management page is hidden on cloud deployments; the hosted team manages optimisation and backup centrally, and the page renders the same "Some settings that are available in the On-Premises version are not visible here" notice as Overview and Licensing. The Retention page described in A.3.1 is available on cloud instances as well, with the retention ceilings the cloud platform enforces and without the device telemetry switches.
Two pages share this chapter. Settings → Retention at /settings/retention controls how much history the database keeps and shows what the cleanup is doing. Settings → Database at /settings/database shows the MySQL status, rebuilds tables on demand and, for power users, runs ad-hoc SQL against the schema. The SQL Console tab is gated behind its own permission flag, so not every administrator with settings_database_enabled will see it.
Connection settings, backups and schema changes are handled outside these pages. The connection string is loaded from appsettings.json at startup and cannot be edited from the UI, and schema upgrades run on their own when the web console starts. A.3.4 lists where each of these tasks is handled.
Settings → Retention is the page of this chapter that admins use most. It lets you set, per table, how long NetLock RMM keeps historical rows before the cleanup removes them, and it shows the state of the cleanup itself.
Each card stands for one table of history data and has two controls:
Enable cleanup: a per-table toggle. When off, the cleanup never touches this table, regardless of the day count. When on, the cleanup removes rows older than the configured threshold.
Delete entries older than (days): a numeric input in days. The value is interpreted relative to the row's own timestamp column; rows younger than the threshold are retained.
The cards are grouped: device telemetry (CPU, RAM and disk history, self-hosted only), compliance and audit (events history, audit logs, API request log, device action queue, device authentication log), database maintenance (the daily optimisation window, see below), website uptime monitoring (check results, resolved incidents, SSL snapshots), remote screen recordings and the event retention rules, which give single kinds of events a retention of their own. Two retention settings live elsewhere: the update history and the scheduled patch run history are configured on the Settings tab of /patch-management, but the same cleanup deletes them, so they appear in the status card like every other table.
The section Integrations holds the history of integration connections (finished jobs only, 30 days by default), their log (14 days by default, counted from the last occurrence of an entry), the records of removed devices that integrations and the device.deleted webhook read (30 days), and the daily device usage behind usage figures and contract quantities (400 days). Keep the usage rows at least as long as your longest billing period. The Open alerts card does not delete anything. It sets how many days an open alert of any kind stays open without a new event before it ends (30 by default). One-shot alerts such as an antivirus finding also end when the event is read or hidden.
The events history keeps some events regardless of their age: the event that opened an alert stays while the alert is open, and while an integration still follows it through a ticket. Later events of an alert age normally, and an event ages normally once its alert is resolved and no ticket link is open. The section Integrations shows how many events are kept this way. The event rules and the size limit of a cloud instance respect the same condition.
Three quick buttons at the top set every toggle at once (Enable all, Disable all) or load the recommended values (Apply recommended defaults). Nothing is applied until you click the one Save retention settings button at the bottom of the page. The confirmation names the time of the next cleanup run, which is when the new values take effect.
The right values depend on your compliance requirements and your disk budget. A few rules of thumb:
Operational tables (telemetry samples, uptime check results) usually work well with 30 to 90 days.
Audit-adjacent tables (who did what, when) typically need longer. The page recommends at least 365 days, and regulated environments often go beyond that.
Session recordings grow fastest on disk, so with tight storage a shorter retention here saves the most space. The Remote Screen Control page (Chapter A.7) also exposes a separate Auto purge specifically for session recordings.
Start with Apply recommended defaults, watch the database size on the Overview page (Chapter A.1.1) and the Table sizes on Settings → Database, and narrow down from there.
The cleanup is a background job of the web console. It runs once right after the web console starts and then every hour, measured from the end of the previous run. On every run it reads the current retention settings and deletes, table by table, the rows that are older than the retention of that table. A table with millions of expired rows is finished in one run. If a delete fails, the run logs it and continues with the next table.
The run only deletes. The space of deleted rows stays inside the table files, where InnoDB reuses it for new rows, so with a rolling retention the files settle at a stable size on their own. Handing that space back to the file system means rebuilding the table, and that is what the daily optimisation window below does.
The card under the page title shows what the cleanup of this web console process is doing. The left half is the cleanup:
a chip that says Idle or Running; while a run is in progress the card names the table being deleted from, the batch number and the rows deleted so far, and the page redraws every two seconds until the run has ended;
the last run with its time, trigger (scheduled or manual) and duration, followed by one chip per table with the rows it lost; a table whose delete failed is marked in red with a hint to the log;
the time of the next scheduled run.
The right half is the database optimisation: the last optimisation (time, trigger, duration, number of tables, bytes handed back), the next window with its time zone (or the note that the window is switched off), and the tables the next window would rebuild right now.
The card keeps no history across restarts: after a restart it says that no run has happened yet until the first run, which starts within seconds.
Four buttons close the card:
Run cleanup now starts a cleanup run right away and hands it to the background job; the page does not wait for it. The same run cleans up the session recordings on the NetLock server. A run that is already in progress is reported instead of being queued.
Optimize now runs the daily optimisation window right away, with the same tables the scheduled window would pick. Read the note on the search index below before using it during working hours.
Estimate pending rows counts, for every table configured on this page, the rows the next run would delete with the values currently in the form, including unsaved changes, so you can see what lowering a retention would remove before saving. Event retention rules are not applied to the estimate. A count stops at one million rows and says "more than".
Refresh reads the state and the candidate tables again.
Every action needs the same permissions as the page; Run cleanup now and Optimize now are written to the audit log.
Deleting rows frees space inside the table files; rebuilding a table (OPTIMIZE TABLE) rewrites the whole table and its indexes and is the only way to hand that space back to the disk. A rebuild is expensive because it writes the entire table once, so the web console does it once a day, in a window you set in the Database maintenance section of the page:
Optimize tables daily switches the window on or off.
Start time is the start of the window on the wall clock of the instance display time zone (Settings → Globalization); the caption under the picker names that zone. The window stays open for one hour after the start time, so a run that is delayed by a long cleanup still fits.
Within the window, the web console rebuilds every retention table whose reclaimable free space is at least 64 MB and at least a quarter of the file; a table below that threshold is left alone, because the rewrite would cost more than the space it returns. The inventory search index is rebuilt in every window regardless of the threshold: its full-text index keeps the entries of deleted rows until the table is rebuilt, and that space is invisible to the statistics the threshold is read from. The status card names the tables the next window would pick.
Two things to know about the window:
A window the web console was not running for is skipped, not caught up. A restart after the window does not rebuild every table in the middle of the day.
The rebuild of the inventory search index holds a write lock on that table for its duration (seconds on a small installation, a few minutes on a large one). Inventory syncs that arrive in that time wait for the lock; nothing is lost. The default start time is therefore 03:00, and Optimize now asks for confirmation before it runs.
If innodb_file_per_table is switched off on your MySQL server (it is on by default and in the compose files of the installation guide), every table lives in the shared system tablespace: the free space the threshold reads describes that shared file and a rebuild never hands space back to the operating system. The window still compacts the tables, but the disk usage you see will not drop.
The Status tab of Settings → Database has an Optimize database action. Clicking it opens a confirmation dialog:
Optimize database tables?
This runs OPTIMIZE TABLE on all major tables. Tables may be briefly locked; running against a multi-GB database can take several minutes. Continue?
Choosing Optimize rebuilds the core tables of the schema, every table the retention cleanup deletes from (events, audit logs, telemetry history, API request log, update history, patch history, uptime monitoring, device authentication log) and the inventory search index, one table after the other. There is no time limit per table. Each rebuild runs to completion, and a table that fails is logged while the run continues with the rest. The action reclaims the space freed by deleted rows and rebuilds the indexes.
Caution:OPTIMIZE TABLE rebuilds each table it processes, and the inventory search index is write-locked while it is rebuilt. On a large NetLock RMM database the whole run can take several minutes, during which parts of the Console will feel sluggish. Run the action off-peak, ideally from within a maintenance window (see Chapter A.2.2) to prevent noisy notifications for the duration.
With the daily window in place there is rarely a reason to run the action by hand. Reasonable triggers include:
You lowered a retention substantially, the next cleanup has run, and you want the space back before the night. Optimize now on the Retention page does the same for the retention tables and asks first.
You restored a database from a dump or moved it between servers and want the files compacted once.
You switched the daily window off and compact the tables on your own schedule.
The SQL Console tab of Settings → Database gives administrators a free-form SQL editor against the NetLock RMM database. It is a power-user tool and is gated separately:
Requires permission:settings_system_mysql_console. Without this flag the tab does not appear at all.
The tab has a multi-line Query textarea with placeholder text Enter SQL query..., and two buttons.
Execute runs the query against the current NetLock RMM database. The default query timeout is 30 seconds; long-running statements are cut off to prevent a runaway query from holding the connection pool.
Clear empties the editor.
Query results render as a standard table beneath the editor. Column headers come from the query's column list, and rows are paginated when results are large.
Clicking a cell opens the Cell Value dialog, which shows the full value without table-row truncation. The dialog includes:
The originating column name as its title.
The cell's length in characters.
A Copy button that places the value on the clipboard.
A Close button.
When the cell contains JSON, which is common for NetLock RMM fields that store structured configuration, the dialog pretty-prints it with indentation. This is the fastest way to inspect a single policy's JSON blob or a theme palette entry without leaving the Console.
The SQL Console runs against the live production database under the Console's connection credentials. Statements run without a preview and without read-only enforcement: an UPDATE, INSERT, or DELETE issued here is committed immediately. Two principles keep this safe:
Only grant settings_system_mysql_console to deployment operators who need it. Treat it as a high-risk permission.
Use the console for read queries by default. When you do need to mutate data, assume you will need to re-run the same statement against a backup; take a logical dump of the affected tables first.
The SQL Console is not a substitute for the regular admin pages. Prefer the dedicated UI for anything it can do (Retention, Users, Tenants, Policies), and reserve the SQL Console for diagnostics and the rare fix that no UI covers.
The following tasks are handled elsewhere, or outside the Console:
Connection string editing.MySQL.Connection_String is read once from appsettings.json at startup. To change it, edit the file on the Console host and restart the Console.
Backup and restore. The Console has no backup or restore function. Backups are your responsibility at the host level; the recommended approach is mysqldump on a schedule outside NetLock RMM, with backups shipped to offsite storage.
Schema upgrades. The web console applies the schema changes of a release on its own when it starts; no manual step is needed. Deploy the web console before the server, because the web console is what applies the schema changes.
MySQL server upgrades. The status card shows the running MySQL version and a warning when that version is older than the recommended release (currently 8.4). The upgrade itself happens at the host level; Upgrade MySQL to 8.4 covers it for the Docker container.
Per-tenant retention. Retention is global: it applies to the table, not to the rows of a specific tenant. If a tenant requires a different retention, filter the reports you deliver to that tenant; the database configuration cannot do this.
Automatic backup on the optimise action. Neither Optimize database nor the daily window takes a backup before running; both assume you have your own backup strategy in place. Take a backup out-of-band if you need a guaranteed rollback point.
Query history in the SQL Console. The SQL Console does not record a history of past queries. If you rely on a particular diagnostic statement repeatedly, keep it in your own notes or a script file rather than expecting the Console to remember it.
On a fresh deployment, open Settings → Retention, click Apply recommended defaults, and Save retention settings. Leave the daily optimisation window on and move its start time into your quietest hour if 03:00 is not it.
A few days later, review the database size in Settings → Overview (Chapter A.1.1) and the table sizes on Settings → Database. If growth is faster than expected, narrow down the retention on the noisiest tables (typically telemetry, events and the API request log), use Estimate pending rows to see what the change removes, and save again.
After lowering a retention by a lot, wait for the next cleanup run (the status card names the time) and either leave the space to the nightly window or click Optimize now.
Delegate the SQL Console permission (settings_system_mysql_console) only to the operators who regularly need it; revoke it for people who occasionally need one-off lookups but can have you run the query for them.
This chapter covers the security controls that most deployments configure early in their lifecycle: restricting which source IPs can reach the product, and replacing local passwords with single sign-on. The two features work independently of each other, but both control who can reach the Console, and the same administrators usually configure them.
The page Settings → Security at /settings/security holds four tabs, each behind its own permission:
IP whitelist (?tab=ip-whitelist): which source addresses may reach the Web Console, see A.4.1.
Country restriction (?tab=countries): admits connections to the Web Console and to the NetLock server only from selected countries, see A.4.1a.
Sessions (?tab=sessions): how long a sign-in to the Web Console stays valid, see A.4.1c.
Rate limiting (?tab=rate-limiting): request limits and temporary blocks for the agent traffic of the NetLock server, see A.4.1b.
The first two tabs are shown to accounts with settings_ip_whitelist_enabled, Sessions to accounts with settings_sessions_enabled and Rate limiting to accounts with settings_rate_limiting_enabled; the menu entry Security appears for any of them. Single sign-on has a page of its own, Settings → SSO, see A.4.2.
All of these apply to cloud and self-hosted deployments. Changing the SSO configuration restarts the Web Console and disconnects every signed-in user, so plan that change for a maintenance window (see Chapter A.2.2). Changes to the IP whitelist and to the country restriction apply within a few seconds, changes to rate limiting within thirty, and none of them restarts anything.
The tab IP whitelist of Settings → Security (/settings/security?tab=ip-whitelist) controls which source IP addresses may reach the Web Console. Two mechanisms feed one whitelist:
a static list of addresses an administrator types on the page, and
dynamic entries that Relay App users add for their own current address for a limited time.
The Web Console re-reads the whitelist from the database every ten seconds and applies it in memory. Saving the static list, turning dynamic whitelisting on or off, revoking an entry, an entry expiring: each takes effect within that window, with no restart and without ending anyone's session.
The whitelist restricts the Web Console only. The agent, file server and relay endpoints of the NetLock server are not filtered by IP address: agents and Relay Apps connect from wherever the fleet and the administrators happen to be, and they authenticate with their own credentials. That is also what makes dynamic whitelisting possible: the Relay App can always reach the server, and the server can therefore whitelist the address it sees the Relay App connect from. To limit the server by the country of the source address, use the country restriction, which has a list of its own for the server.
The page opens with an informational alert and a five-line text area labelled Allowed IP Addresses (comma-separated) with the helper text Example: 192.168.1.100, 10.0.0.5, 172.16.0.1.
Enter one IP address per comma-separated item. Each entry is validated with standard IP-address parsing; an invalid value raises an inline error like Invalid IP address: <ip> and prevents the save. An empty field is a legitimate value that means allow all source IPs while dynamic whitelisting is off; this is the default state on a fresh deployment. Addresses are compared as addresses, not as text, so an IPv4 address written by a proxy in its IPv6-mapped form (::ffff:203.0.113.5) still matches its IPv4 entry. IPv6 addresses match exactly.
Save writes the list and applies it at once. If the list you are about to save is not empty and does not contain the address your own browser session comes from, the page asks for confirmation first, because your next request would be rejected. An address that is covered by an active dynamic entry counts as contained.
Caution: If you lock yourself out anyway, recovery is direct database access on the Console host. Run the statement below in MySQL; the Console picks it up within ten seconds:
UPDATE settings SET ip_whitelist_dynamic_enabled = 0, ip_whitelist_web_console = NULL;
On a cloud instance, use the Reset IP whitelist action in the members portal instead; it does the same and also removes all dynamic entries.
Administrators who work from a connection without a fixed address (home office, hotspot, a provider that rotates addresses) cannot be on a static list. The section Dynamic whitelisting via Relay App lets them keep the whitelist anyway: the Relay App, which they already run and which authenticates against the NetLock server with its relay identity, asks the server to whitelist the public address it connects from. The server records that address as a temporary entry; the Web Console admits it while the entry has not expired.
Three things have to be true for a Relay App to use this:
The switch Allow Relay App users to whitelist their address on this page is on (off by default; nothing changes for an existing installation until an administrator turns it on).
The account behind the relay identity holds the permission Whitelist own address for the web console (Relay App) in the Relay Server group of Users → <account> → Settings (relay_server_ip_whitelist), and Relay Server access itself is enabled for that account. Existing accounts start without the permission.
The account is enabled. A relay identity whose account is disabled or deleted is refused on every relay route, not only on this one.
Lifetime of an entry (hours) sets how long an entry lasts after it was added or last refreshed: 1 to 168 hours, default 24. The same lifetime applies to entries added with the button and to entries the Relay App refreshes automatically.
Enabling with an empty static list. When you turn the switch on while the static list is empty, the whitelist changes from "everyone" to "only dynamic entries". So that you keep access, the page asks for confirmation and then writes a seed entry for your own current address with the configured lifetime. The seed entry shows in the table with the source Seed and the relay identity Web console. Whitelist your own address from a Relay App, or add it to the static list, before the seed entry expires.
Active dynamic entries. The table lists every entry that has not expired: address, owning account, relay identity, source (Manual for the button, Auto for the timer, Seed for the row the console wrote), the machine name the Relay App reported, when the entry was created and last refreshed, and when it expires. Refresh reloads the list; the Revoke icon in the actions column deletes an entry after a confirmation, and the address is rejected with its next request. Revoking does not stop the identity from adding the address again a minute later. To stop an identity, remove the permission from its account, delete the identity, or turn the switch off.
Automatic removal. Entries are deleted, and their addresses rejected at once, when the owning account is saved as disabled or without the permission, when the account is deleted, and when the relay identity that added them is deleted or has its hardware id reset. A password change does not affect entries.
Limits. An account may hold ten active entries and an instance five hundred; the Relay App reports limit reached beyond that, and an existing entry is always refreshed regardless of the limits. A refresh less than thirty seconds after the previous one is answered without a write. Repeated failed authentications from one address are answered with 429.
Audit. Creating an entry, removing it from the Relay App, revoking it here, and changing the switch or lifetime are recorded in the audit log under the entity ip_whitelist_dynamic; a refresh is not, so auto mode does not fill the log.
Once the server confirms the feature, the header button row of the Relay App shows Whitelist my IP, Remove my IP and the checkbox Auto-whitelist every minute. On a server that does not know the feature the controls stay hidden; while the switch on this page is off or the account lacks the permission they are shown disabled, with the reason as tooltip.
Whitelist my IP adds or refreshes the entry for the address the server sees. The status line at the bottom reports the address and the local time the entry lasts until, for example Address 203.0.113.5 whitelisted for the web console until 03.09.2026 14:22.
Auto-whitelist every minute refreshes the entry every sixty seconds while the app runs, including while it is locked. The setting is remembered across restarts. When the public address changes, the new address is whitelisted on the next tick; the previous address stays until its entry expires. A temporary failure (server unreachable, too many requests, console not yet updated) keeps the timer running and reports once in the status line. A hard failure (feature disabled in the console, permission removed, account disabled, limit reached, server without the feature) turns the checkbox off and explains why.
Remove my IP deletes the entry for the current address and turns auto mode off, because auto mode would add the address again within a minute.
The Relay App and the NetLock server are released in lockstep: this feature needs a Relay App build that knows it and a server that expects that build.
The Relay App whitelists the address the server sees it connect from; the browser has to reach the Web Console from that same address. Normally both leave through the same NAT and this holds. It does not hold when the browser and the Relay App take different routes:
a VPN with split tunnelling,
a browser proxy or PAC file,
privacy tools that route the browser only,
a dual-stack mismatch where the Web Console host has an AAAA record and the server host does not (the browser then arrives over IPv6 while the Relay App whitelisted the IPv4 egress, or the reverse).
The 403 page prints the rejected address and the Relay App shows the whitelisted one, so the mismatch is visible. The fix is on the client side.
For deployments behind a reverse proxy or load balancer, both the NetLock server and the Web Console have to trust the forwarded client address (X-Forwarded-For with the proxy configured as trusted). If the server sees only the proxy's address, that is what gets whitelisted; if the Web Console sees only the proxy's address, every request appears to come from the same source.
Allowlist, empty means all. An empty static list with dynamic whitelisting off means "allow all"; anything else means "allow only these".
Instance-wide. The list applies to all administrators equally; dynamic entries are bound to the account and relay identity that added them only for the purpose of listing, revoking and automatic removal.
No description per static entry. If you need to remember why a specific IP is in the list, keep a separate note.
IP addresses only. Individual IPv4 and IPv6 addresses; no CIDR blocks, DNS names or wildcards.
Add your new address before removing the old one; the list is live at the moment of save.
After changing the static list, confirm you can still sign in as an unprivileged account as well as your admin account.
Review the static list annually and the active dynamic entries whenever an administrator leaves. Rotate the whitelist on the same day you disable the account; disabling the account already removes its dynamic entries.
If you rely on dynamic whitelisting alone, keep at least one administrator with the permission and a working Relay App, or a static entry for a fixed site, so the switch can always be reached.
IP whitelisting and SSO are complementary, not alternatives. When both are in effect, a request must pass the IP filter and satisfy an SSO-compatible identity before it gets in. In practice this means:
A user on a whitelisted IP with the wrong identity is still refused.
A user with a valid SSO identity but an unwhitelisted source IP never sees the SSO sign-in page, because the IP filter applies first.
If you operate a strict IP-restricted environment and also use SSO, verify that both gates are configured independently before rolling out. Missing one does not compromise the other, but users can easily mistake an IP filter rejection for a problem with the identity provider.
The country restriction limits who can reach the Web Console and the NetLock server by the country of the source address. It lives on the same page as the IP whitelist, Settings → Security, on the tab Country restriction (/settings/security?tab=countries), behind the same permissions (settings_enabled and settings_ip_whitelist_enabled). Unlike the whitelist it covers both applications: one list for the Web Console and one for the server.
The country of an address comes from the GeoIP database that already drives the device world map. The Web Console and the server both ship that database as geodb/geoip.mmdb next to their binaries, and read it locally without asking an external service. The database needs no configuration, key or volume. The same database fills the country of every device, see Country of a device.
Country restriction for the web console and Country restriction for the server each consist of a switch, a country picker and a Save button of their own:
Restrict web console access to the selected countries and Restrict server access to the selected countries turn the respective list on.
Allowed countries is a picker over the ISO 3166-1 countries (plus Kosovo): type a two-letter code or a name in the language of your console, pick the country, and it appears as a chip with its flag. The codes are stored; the names follow the console language.
Copy from web console list fills the server picker with the web console selection; it does not save.
A list is in effect only while its switch is on and it holds at least one country. Saving a list with the switch on and no country is refused (Select at least one country or turn the switch off.). By default both switches are off and both lists are empty, so nothing changes until you turn a list on.
A third block, Addresses without a country, holds one switch that applies to both lists: Allow addresses the GeoIP database has no country for, on by default. Turned off, an address the database has no record for is refused wherever a list is active.
Every request to the Web Console and every request to the server is checked before anything else handles it: page loads, the Blazor connection, static files and sign-in callbacks on the Web Console; agent check-ins, downloads, file operations, the SignalR hubs, relay routes and the public API on the server.
While no list is active, everything passes.
Addresses from private networks, the local machine and link-local ranges always pass: the RFC 1918 ranges, carrier-grade NAT (100.64.0.0/10), 169.254.0.0/16, fe80::/10, fc00::/7 and loopback. They are never looked up and never counted. On a single-host Docker installation the Web Console reaches the server through such an address, and so do the agents on the LAN of an on-premises server.
Calls the Web Console makes to the server for a signed-in user are not filtered, so a Web Console hosted in another country keeps working. Browsers and apps that connect to the server directly are filtered (see the next section).
The country of the address is looked up in the database and cached in memory. A listed country passes; any other country is refused with 403.
An address the database has no country for follows the Addresses without a country switch.
If the GeoIP database is missing or cannot be opened, the failure is written to the log and the settings page shows a warning banner with its path.
The Web Console re-reads the settings every ten seconds and the server every sixty, so a saved change is live within that window without a restart. A Blazor session that is already open is not cut; it ends at its next reconnect or page load.
A refused request receives status 403. The Web Console answers with a small page that shows Access denied, Connections from your region are not permitted by this installation. and Your address: 203.0.113.5 (US). The server answers with the same sentence as plain text: Access denied. Connections from your region are not permitted by this installation. Your address: 203.0.113.5 (US). The address and the two-letter country are named so that a legitimate administrator can tell the operator what to add; an address without a country shows (unknown). Agents in a country that is not listed receive that answer on every endpoint: they stop syncing, are reported as disconnected and trigger the disconnection notifications.
A server sensor of the kind Device country turns the server list into events, with the severity and notification channels of the sensor:
Monitor before you enable. Maintain the server list but leave its switch off. The trigger outside_countries reports every device that checks in from a country outside the list, while the device keeps working. Together with the Connections by country tile below, this shows which devices a restriction would cut off before it is turned on.
Refused devices. With the switch on, the trigger refused reports an authorized device the server has refused because of its country. The device is identified by its access key and hardware ID in the refused request. Unknown devices, new installations in a refused country and browsers or apps produce no event; they appear in the log and the statistics only.
Country changes. The trigger country_changed reports a device whose country differs from its last known one, independent of the list.
Each device is reported once per country and trigger until it checks in from a listed country again, and the same country no earlier than 24 hours after the last event for it. A new or changed sensor takes effect within a minute. Below the server list, the page links to /manage_sensors for accounts with the sensor permission.
The exception for the Web Console only covers calls it makes on the server side. Several functions connect the browser of an administrator, or one of the apps, to the server directly, and the server list filters them like any other client:
remote screen control and audio calls (the browser connects to the screen hub of the server),
agent installer downloads, file downloads from the file browser and the installer links the console offers,
the Relay App, which connects to the tunnel hub for relay sessions and dynamic whitelisting,
the Console App, which checks its version against the server,
clients of the public API and the Swagger page.
So the server list must contain every country administrators and Relay App users work from, in addition to the countries of the fleet. The alert above the server list says so. The licence check against the Members Portal is an outgoing connection of the server and is not affected.
Each save checks the list you are about to save against your own current address, resolved with the same rules the check uses:
Web Console list. A list that does not contain your own country is not saved: Not saved: your current address 203.0.113.5 resolves to United States (US), which is not in the list. You would lose access to the web console with your next request. The same applies when your address has no country in the database and addresses without a country would be refused.
Server list. The same condition asks for confirmation instead of refusing, because the server list blocks remote screen control, downloads and the Relay App from your address, not the console itself: Your current address 203.0.113.5 resolves to United States (US), which is not in the server list. Remote screen control, downloads and the Relay App from your address will be refused by the server. Do you want to continue?
Addresses without a country switch. Turning it off is checked against both saved lists in the same way: refused for the Web Console list, confirmed for the server list.
Your own address is a private or local one (the console is reached over the LAN or through a VPN into its network): the list is saved and an info message reminds you that the rule never applies to your address and that the list should contain the countries administrators connect from.
Your address cannot be determined, or the database is not available: the page asks whether to save anyway.
The Status and lookup block shows what the page sees: Your current address 203.0.113.5 resolves to Germany (DE). (or that it is private, unknown to the database or not determinable), the counter Connections refused by the web console since start, and Look up an address, which resolves any address to its country, city and region against the bundled database. Use it to check how a customer site or a colleague's address will be treated before a list is turned on.
Caution: If you lock yourself out anyway, typically as an administrator behind a VPN exit or on a roaming connection, recovery works as for the IP whitelist. On a cloud instance, the Reset IP whitelist action in the members portal also turns both country switches off. On a self-hosted instance, run the statement below in MySQL; the Web Console picks it up within ten seconds and the server within a minute, without a restart. The lists themselves are kept, so the restriction can be turned on again once the missing country has been added.
UPDATE settings SET geo_allowlist_web_console_enabled = 0, geo_allowlist_server_enabled = 0;
Two tiles below the lists show where connections come from, whether or not a list is active, so that the countries a fleet connects from are known before a restriction is turned on:
Connections by country counts, per day and country, the connections the Web Console and the server admitted and refused. One address counts at most once per ten minutes and country, so page assets and agent polling do not inflate the numbers. Only the country and the counters are stored, never an address, and the rows are kept for 90 days. While the database file is not available, nothing is counted. The table has:
a period selector (Today, Last 7 days, Last 30 days, All),
the columns Web console allowed, Web console blocked, Server allowed, Server blocked and Last seen, and a row Unknown for addresses without a country,
per row the actions Add to web console list and Add to server list, which put the country into the picker above (the list still has to be saved).
Reset statistics deletes all counted rows of both applications after a confirmation and writes an audit entry.
Devices by country counts the authorized devices of the tenants you are assigned to by the country of their external address: the ten largest countries, a row … more countries for the rest and a row No country (private address or not synced yet).
A refused request is written to the log with severity WARNING, module Middleware, event Geo allowlist: Address 203.0.113.5 (US) refused for /downloads/…: Blocked. At most one line per address is written every ten minutes, so a scanner cannot flood the log. In the Web Console the line lands in warning.log and combined.log (Settings → Logging → Web Console Logs), on the server in the files of the same name (Server Logs tab); see A.9. Both applications echo the database path, its build date and the state of the restriction at start-up.
Saving a list, changing the switch for addresses without a country and resetting the statistics are recorded in the audit log under the entities geo_allowlist_web_console, geo_allowlist_server, geo_allowlist_unknown_allowed and geo_allowlist_statistics, with the previous and the new value.
Until the Web Console has restarted after the update, the tab shows a notice and its controls are disabled.
A server that is older than the Web Console treats the server list as off, writes no device country and logs that once.
On a split-host installation (Web Console and server on different hosts with public addresses), update the Web Console before you turn the server list on. Otherwise its relay pages, remote control tokens and hub connections are refused as soon as the country of the Web Console host is not listed.
Rate limiting restricts how many requests each agent may send to the NetLock server and blocks, for a limited time, devices and addresses that keep exceeding their limits. It lives on the tab Rate limiting of Settings → Security (/settings/security?tab=rate-limiting), behind settings_enabled and settings_rate_limiting_enabled. It covers the agent-facing side of the server only: check-ins, events, reports, the tray ticket and end-user chat endpoints, hub connections of the agents, device file transfers and installer downloads. The Web Console, the Relay App, the public API and the Members Portal are not subject to it.
The purpose is to keep one misbehaving device (a compromised agent, a reinstall loop, a script that floods the event queue) from taking the server down for the rest of the fleet, and to keep floods of requests without a valid identity away from the database. Legitimate traffic, including the backlog a device delivers after a week offline and a large SNMP collector, stays far below the limits. The limits catch abnormal traffic and are not usage quotas.
Mode has three values; the server applies a change within thirty seconds.
Off: nothing is counted or limited.
Observe: everything is counted, requests that would have been refused and blocks that would have been imposed are recorded, but no request is refused. Observe is the default on self-hosted installations; cloud instances run in Enforce, see NetLock cloud.
Enforce: requests above a limit are answered with 429, and a device or address that keeps exceeding its limit is blocked for a while.
Run in Observe first. The tab shows an info banner while it is on, the KPI tiles Would be refused (24 h) and Would be blocked (24 h) fill up, and a block that would have been imposed appears in the Blocks table with the chip Observed and writes an event whose title reads … would be blocked by rate limiting (observe mode; …). After seven days in observe mode without such a block the banner changes to No block has been recorded for 7 days; rate limiting can be enforced. Switching to Enforce asks for confirmation and names how many devices and addresses would have been blocked in the last 24 hours.
Blocks recorded in observe mode never refuse anything, not even after the switch to Enforce. The levels of the two modes are counted separately, so the first enforced block of a device starts at level 1.
The limits are derived from two settings, so no individual values need tuning:
Device count.Counted devices is the number of devices the instance knows, pending ones included, refreshed every minute. Expected devices is optional and only ever raises that number, for a planned rollout; a value that is too low never tightens the limits.
Sensitivity.Relaxed doubles the limits and blocks later, Normal (the default) keeps the limits, Strict halves the limits and blocks sooner.
A third setting, Daily data volume per device (MB), is a budget of its own: how many bytes of request bodies a device may send per day, counted after decompression, across check-ins and inventory uploads, events, reports and the interactive endpoints. Default 1024 MB, allowed 64 to 102,400. The budget starts full and refills continuously over the day (a 1 GB budget refills at about 12 KB per second); it does not reset at midnight.
File transfers between the device and the file server, the screen, tunnel and command hubs, and downloads are not counted. A typical device uses well under 100 MB per day. An SNMP collector needs roughly hosts × runs per day × 2 KB; 2,048 hosts polled every 15 minutes come to about 0.4 GB per day. Raise the budget or add an exemption for a collector beyond that.
Derived limits (an expandable table under the settings) shows the rate and burst of every class for devices, addresses and the instance that follow from your device count and sensitivity, before you save them.
Every request that reaches an agent endpoint is assigned to a class and to a subject:
A request from a known device (its access key is in the device table, pending devices included) is charged to that device. Known devices are never limited or blocked by their address, so a site with hundreds of devices behind one NAT address needs no special treatment.
A request without a known identity (no identity, an invalid one, or an access key the instance does not know) is charged to the source address (IPv4 addresses individually, IPv6 addresses as their /64 network). Installer and update downloads are charged to the address as well. Two instance-wide limits sit above the per-address ones.
Per-device limits do not depend on the device count; an agent sends the same amount whether the fleet is small or large. The requests of a device fall into these classes:
Class
What it covers
Can block
Sync
Check-in, version check, policy download, inventory upload, deployment and uninstall pulls; check-in and sync of mobile devices
yes
Events
Delivery of events from the agent queue
yes
Telemetry and reports
SNMP results and discovery, application and device control reports, patch, BitLocker and custom field reports, deployment and uninstall acknowledgements
yes
Interactive
Tray tickets and the end-user AI chat
yes
Hub connections
Connection set-up of the command hub and the screen hub
yes
Tunnel connections
Connection set-up of the tunnel hub — one per NetMesh link or relay session
yes
Device files
Uploads to and downloads from the device through the file server, counted as requests only, never by size
only on a clear flood
Data volume
The daily budget above
yes
Hub messages
Calls on an open command hub connection
no; observed only
Each class has a rate a device may send continuously and a burst it may send at once on top of that; Derived limits shows both. An offline credit of the events class keeps a backlog from looking like a flood: a device that was out of contact with the server for up to seven days delivers its queued events without a violation. After a server restart the credit is derived from each device's last check-in.
The limits per address and per instance grow with the device count, because a larger fleet has larger sites and larger rollouts; Derived limits shows their current values. The sensitivity applies to the per-device and per-address limits and to the instance-wide limit for requests without a known identity. The two capacity limits of the instance, hub handshakes and all agent requests, are not scaled, answer with 503 instead of 429 and never count against a device or an address.
The answer is sent before the request reaches the database, in plain text, with Cache-Control: no-store:
Above a limit:429 with body rate_limited and a Retry-After header that says after how many seconds the next request fits.
Daily volume spent:429 with body volume_exceeded; Retry-After is the time until one percent of the budget has refilled, about 14 minutes at 1 GB.
Blocked:429 with body blocked; Retry-After is the remaining time of the block.
Instance overloaded (hub handshakes or all agent requests): 503 with body overloaded and a Retry-After of 5 to 30 seconds. This spreads a herd of reconnecting agents after a server restart; it is never a violation.
Request body too large:413 with body payload_too_large. The limits are 64 MB for the inventory upload, 4 MB for events and 16 MB for every other agent request, measured after decompression; the tray ticket endpoints keep their own 512 KB (8 MB for attachments). In observe mode only the ticket limits are applied and an oversized body is counted; in enforce mode an oversized body is refused and counts as a violation. Device file transfers have no size limit.
Nothing is discarded. An event that was refused stays in the queue of the agent and is delivered later; a refused check-in is repeated at the next interval.
A violation minute of a class is a minute in which many requests of a subject were refused, or in observe mode would have been refused. A subject that collects several violation minutes within ten minutes is blocked; the sensitivity sets how many. Too many parallel event requests or hub connections of one device and an oversized request body count as a violation minute at once.
Device blocks last 5 minutes at level 1, 15 at level 2 and 60 from level 3 on; the level falls back to 1 after 24 hours without a block. While a device is blocked, every request from it is answered with blocked, its open command hub and screen hub connections are ended (on other server instances within thirty seconds), and it shows the chip Blocked until <time> next to its name in the devices list. A block does not extend itself: the polling of a blocked agent is not a violation, and after the block ends the device needs a fresh set of violation minutes for the next one. Because of the 60-minute cap, a false positive is released automatically within the hour.
Address blocks follow floods of requests with an unknown identity or repeated failed authentication from one address; they last 15, 60 and 240 minutes. A blocked address is refused for requests without a known identity and for downloads; known devices behind the same address keep working.
Every block start writes an event of the type Rate limiting (in enforce mode with severity High, in observe mode with Moderate) that names the device or address, the class, the reason, the measured rate against the limit, the violation minutes, the level, the duration and the instance that decided it. Reported by reads Rate limiting. These events are not sent to notification channels or as push messages; they are visible on /events, on the device's Events tab and in the event widgets. Address blocks have no device and are shown only to accounts with access to every tenant. Throttling alone writes no event; the statistics on the tab cover it. See Chapter 12.2.
Unblocking.Unblock on a row and Unblock all above the table release blocks after a confirmation; the server picks the release up within thirty seconds and then grants the subject fifteen minutes of grace in which it can be throttled but not blocked again. Both are written to the audit log. Expired blocks and manual releases stay in the History filter of the table for 90 days, with Released by naming the account or Expired. Export data writes the current filter as JSON, CSV or HTML.
Exemptions. A device, or an address or CIDR range, on the Exemptions table is still counted but never throttled, blocked or shed. An exempt address also covers the known devices behind it. Use it for a collector that outgrows the volume budget or a site whose NAT address keeps producing unknown-identity floods you have accounted for. Address exemptions can be added by accounts with access to every tenant; device exemptions by anyone who may see the device. Adding and deleting an exemption is audited.
Above the settings a KPI row shows the blocked devices (with a caption for blocks recorded in observe mode), the blocked addresses (accounts with access to every tenant only), and the refused, would-be refused and would-be blocked counts of the last 24 hours.
Below the Blocks table, Top subjects (24 h) lists the fifty devices and addresses with the most refused and would-be refused requests per class, with the peak per minute and the last contact, and Top data volume lists per device the largest daily volume of the last seven days, summed over all server instances, as a share of the budget. Both refresh with their Refresh button; the statistics behind them are written by the server once a minute.
The mode, the device count, the sensitivity and the daily volume are instance-wide. The tables follow the tenant scope of the account: device rows of the tenants you are assigned to; address rows, the Blocked addresses tile and address exemptions only with access to every tenant.
Saving the settings, releasing a block, adding or deleting an exemption and exporting the blocks are recorded in the audit log under system_setting (entity name agent_protection, with the previous and the new values), agent_protection_block and agent_protection_exemption.
On NetLock cloud instances rate limiting always runs in Enforce with sensitivity Normal and the default daily volume of 1,024 MB per device, and Expected devices is the device limit of your license, so the limits follow the licensed device count rather than only the devices enrolled so far. These values cannot be changed, so the tab does not show the settings. The KPIs, the blocks, the top lists and the statistics work as described above, and Unblock, Unblock all and the Exemptions table stay available.
Blocks, releases, exemptions and the settings reach every server instance within thirty seconds; the other instances also end the hub connections of a blocked device. A server restart never causes a block, and a backlog that piled up during the downtime is delivered without a violation.
The server logs its state at start ([Rate limiting] observe, preset normal, 512 devices counted, N = 512, volume 1024 MB per device and day, 0 active block(s), 0 exemption(s)), every block as a warning with the class, the reason and the measured rate, and the hub connections it ended. Statistics and top subjects are kept for 30 and 7 days, daily volumes for 30 days, released blocks for 90 days; the server deletes older rows once a day.
The tab Sessions of Settings → Security (/settings/security?tab=sessions) sets how long a sign-in to the Web Console stays valid. It needs settings_enabled and settings_sessions_enabled.
Idle timeout (minutes): a session without an open Console tab ends after this time (5 to 43200, default 720). A lowered value also applies to existing sessions from their next activity.
Maximum lifetime (hours): a session ends after this time even while it is in use (1 to 8760, default 168). It applies to new sessions; existing sessions keep the lifetime they got at sign-in.
Offer "Stay signed in" on the sign-in page: when on (default), users can stay signed in across browser restarts. Turning it off removes the option; existing sessions keep their lifetime.
"Stay signed in" lifetime (days): a session created with Stay signed in ends after this many days, regardless of activity (1 to 365, default 30).
Saving writes an entry to the audit log. Nothing restarts.
Settings → SSO at /settings/sso configures OpenID Connect for the Web Console. Once SSO is enabled and a user account's authentication mode allows SSO, that user signs in through their identity provider instead of (or in addition to) a local password.
Five providers are supported, each on its own tab:
Azure AD
Keycloak
Google (Workspace / Identity)
Okta
Auth0
All five are OpenID Connect. SAML 2.0 is not supported. There is no SAML metadata file to export from the Console or import into it. If your identity provider is reached through SAML only, you will need a bridge (such as a federation layer that translates SAML to OIDC) between it and NetLock RMM.
Several identity providers offer SAML as their default path. Register NetLock RMM as an OpenID Connect client instead: App registrations in Microsoft Entra ID (not Enterprise applications → Single sign-on → SAML), an OIDC — Web Application in Okta, and a Regular Web Application in Auth0.
Only one SSO provider can be active at any given time. Each provider tab has its own Enable <Provider> switch; turning one on automatically turns the others off. An informational alert on the page points this out.
A licence in a valid state. SSO is available on every deployment, and configuring and saving it does not depend on the licence plan. SSO sign-in is refused while the deployment's licence is banned, expired or deactivated, which is the same condition that blocks the Console as a whole.
Pre-provisioned user accounts. NetLock RMM does not create accounts automatically on the first SSO sign-in. Every user who will sign in via SSO must already exist in Users with their Auth Mode set to SSO or Password & SSO, and the username on the NetLock account must match the email claim the provider returns. When the username is matched against the email claim, the address has to be verified at the provider: a sign-in whose ID token carries email_verified with the value false is refused, with a message on the sign-in page and the line SSO | <Provider> email_not_verified in the web console log. A username matched against preferred_username or upn, or an ID token without the claim (as with Microsoft Entra ID by default), signs in as before. See Chapter 14.2 for how to create users with the correct auth mode.
A registered application on the identity provider. The identity provider needs a client registration pointing back at your Console. The redirect URI is https://<public-host>/<callback-path>; see the section on callback paths below.
Each provider tab asks for a Callback Path (and its signed-out counterpart) as a path, not a full URI. The Console constructs the full redirect URI at runtime by combining the public host of the Console with the path. When you register the application at the identity provider, you assemble the full URI manually:
https://<public-host>/<callback-path>
For example, with a Console at https://console.example.com and the default Azure AD callback path of /signin-oidc, the redirect URI you register at Azure AD is https://console.example.com/signin-oidc.
If you leave the callback path field blank, the Console falls back to the per-provider default listed in the helper text on each field (/signin-oidc for Azure AD, /signin-keycloak for Keycloak, and so on). The defaults work and are the recommended choice.
Each provider tab shows the resulting sign-in and post-logout redirect URI below the path fields, with a copy button. The values follow the address the page is opened with and the Force https in redirect URLs switch as it will apply after saving.
SSO login does not create NetLock accounts on demand. When a user signs in via SSO, the Console extracts the email address from the identity provider's token and looks for an account with a matching username that has an SSO-compatible authentication mode. The account must therefore already exist, and its Auth Mode must be either SSO or Password & SSO.
If the account does not exist, or if it exists but its Auth Mode is Password only, the Console rejects the sign-in with:
User is not authorized for SSO login. Please contact your administrator.
When a new technician joins your team, provision their NetLock account first (see Chapter 14.2), set their Auth Mode to SSO or Password & SSO, and make sure the username exactly matches the email address they will authenticate with at the identity provider. Only then point them at the Console's login page.
When you create a user, you pick one of three auth modes (also covered in Chapter 14.2):
Password: local password only. Cannot sign in via SSO.
SSO: SSO only. The local password slot is disabled.
Password & SSO: either mechanism. Useful during migrations, where you want to keep password fallback available until every user has successfully used SSO at least once.
The SSO Settings page has a single Save button. The page has no Test button. To validate the configuration, sign out and attempt an SSO sign-in yourself.
Before the configuration is written, a confirmation dialog appears:
The web console will automatically restart after saving the SSO configuration. All active user sessions will be terminated. Do you want to continue?
Confirming writes the configuration and restarts the Console. Every signed-in user, including you, is returned to the login page.
If the stored SSO configuration fails to load at application startup, for example because a provider secret was rotated without the Console being updated, the page shows a red banner the next time it is opened:
SSO Configuration Error! The SSO configuration could not be loaded during application startup and SSO is currently DISABLED.
When you see that banner, fix the misconfiguration, save again, and restart.
Pilot with a single power user first. Set one user's Auth Mode to Password & SSO, confirm they can sign in either way, then roll out across the team.
Keep at least one break-glass local account with Auth Mode set to Password. If the identity provider is unavailable, that account is your only route back into the Console.
Rotate provider secrets in the identity provider and the NetLock SSO page on the same day, and warn the team before you save, because saving always restarts the Console.
Document the provider's redirect URI and the NetLock account's Auth Mode setting in your onboarding runbook.
"User is not authorized for SSO login." The account either does not exist with the expected username, or its Auth Mode is Password. Confirm the username on the NetLock account exactly matches the email claim the provider issues, and confirm Auth Mode is SSO or Password & SSO.
Callback URI mismatch reported by the provider. The redirect URI registered on the provider side does not match what the Console constructs. Re-derive the URI from https://<public-host>/<callback-path> and register exactly that value at the identity provider, with no trailing slash differences.
Post-restart red banner on the SSO page. The saved configuration could not be loaded at startup. A typical cause is a secret that was rotated at the provider but not updated in the NetLock SSO page, or an Authority / Instance URL that contains a typo. Fix the stored value and save again to retry the startup load.
Everything works except sign-out. The Signed Out Callback Path is either missing or not registered at the identity provider. Add it in both places.
The provider reports a redirect URI mismatch and the URI it received begins with http://. The Console is behind a reverse proxy that terminates HTTPS without forwarding X-Forwarded-Proto, so the redirect URL is built from the internal scheme. Enable Force https in redirect URLs at the top of the SSO page and save. The log line SSO | <Provider> challenge names the URI that was sent.
The log shows Message contains error: 'invalid_request', error_description: 'Invalid parameter: redirect_uri'. Keycloak rejected the redirect URI at its pushed authorization endpoint, before the browser was redirected; the sign-in returns to the login page with the SSO error message. The Console writes the URI it sent to its log (SSO | Keycloak challenge), and the Keycloak tab on the SSO page shows the URI to register. The entries under Valid redirect URIs must match it character for character. If the log line contains forwarded_headers_applied=False, the reverse proxy is not listed in Kestrel:KnownProxies of the Console's appsettings.json (the install template lists 172.18.0.2).
If the failure does not fit one of these, confirm the licence is still in a valid state (Settings → Licensing, Chapter A.1.2). SSO sign-in is refused while the licence is banned, expired or deactivated, even though the stored configuration itself remains intact.
Chapter 8.3 — Server sensors — the Device country sensor, which reports devices outside the server list, refused by it or with a changed country.
Chapter 12.2 — Events — the event type Rate limiting and the Occurred (device) time of an event.
Chapter A.2.2 — Maintenance. Use a window to silence notifications during an IP or SSO change.
Chapter X.3 — Troubleshooting — covers common SSO callback and IP filter failure modes, a device blocked by rate limiting and a failed download from a device.
Settings → Globalisation at /settings/globalization configures how NetLock RMM formats and renders dates and times across the Console, which clock timestamps are stored on, and which language the Console uses by default. Users can override the timezone and the language for their own account on Account → Home (/account/home).
Date/Time Format is a dropdown with seven presets. A live preview renders directly beneath the dropdown, updating as you change the selection, so you can see the chosen format applied to the current date and time before saving.
Preset label
Example
ISO
2026-03-18 14:30:00
EU
18.03.2026 14:30:00
UK
18/03/2026 14:30:00
US
03/18/2026 02:30:00 PM
Textual month
18 Mar 2026 14:30:00
Slash ISO
2026/03/18 14:30:00
Dashed day-first
18-03-2026 14:30:00
Pick the preset that matches your team's convention and click Save. The change is applied Console-wide immediately; a browser refresh is not required.
The selection is deployment-wide. Users and tenants cannot override it, so choose a format your entire admin team is comfortable reading.
Every timestamp in the database is stored on one clock, the instance's time mode:
local: timestamps are stored in the server's local time. Installations that have never been switched to UTC use this mode. Timestamps are shown exactly as stored, in server time. No timezone setting has any effect in this mode, neither the instance display timezone nor a user's own timezone. Both can be set ahead of the switch; the page and Account → Home say so next to the field.
utc: timestamps are stored in UTC, and the Console converts them to the display timezone of the signed-in user. New installations start in this mode.
The alert at the top of the card shows which mode the instance is in. While the instance is still in local mode, the card offers Switch to UTC:
Choose the Display timezone. The switch refuses to start without one, because every screen would otherwise jump by the server's offset.
Click Switch to UTC. The confirmation dialog lists the consequences and requires the literal text UTC to be typed.
On confirm the time mode and the zone shown in the field are saved together and written to the audit log. The Console follows immediately, including sessions that are already open; the backend picks the change up within a minute.
The switch is one-way. Run it inside a maintenance window. Directly after the switch, alerts and scheduled work can trigger once at an unexpected time. Rows written before the switch are not converted and appear shifted by the server's previous UTC offset; in tables with a retention period they disappear over time.
The zone a timestamp is rendered in is resolved per user, in this order:
The user's own timezone, chosen on Account → Home with the Timezone field and saved with Update. The browser's zone is offered there as a one-click suggestion but never applied on its own. Leave the field empty to follow the instance.
The instance Display timezone on this page.
UTC, when neither is set.
Only zones from the list can be saved; an unknown zone is rejected. A changed zone applies on the next render of the Console: the instance zone in every open session, a user's own zone in the session it was saved from. Other open tabs of the same user pick it up after a reload. Lists and charts that are already loaded show the new zone once they are refreshed.
Messages that leave the instance (e-mail, Microsoft Teams, Telegram, ntfy, the ticket webhook) are produced without a signed-in user and always use the instance display timezone, naming the zone next to the time.
Default Language is the language used for users who have not chosen their own; it also sets the number and date formatting culture. Users pick their own language on Account → Home.
Language Files lists the shipped and custom language files. Shipped languages are embedded; to customise strings or add a language, place a JSON file in internal/lang/ and click Reload language files. Download en-US template provides the English baseline, Import language runs a guided import with a completeness check against it, and Upload language file saves a file (including a partial override with only the changed keys) without that check.
A language file also carries the presets for the end-user texts of a policy (section Classes.Policies.Policy_Text_Presets, see §6.5.1). All shipped languages include them.
A custom language is offered in the policy editor's Text language menus once its own file translates every text of that section; an incomplete section is not filled up from English or from a base language, so the language is not offered until the file is complete. The import's completeness check counts missing preset texts like any other key.
A partial override of a shipped language can change single preset texts; the change appears in the menus after Reload language files. Applying a preset copies the texts into the policy, so a later change of the language file does not alter policies that were already saved.
Settings → Whitelabeling at /settings/whitelabeling is where you replace the NetLock RMM default look with your own brand. The page controls the Console's logo, the login-page background, a forty-field colour palette split across light and dark modes, the browser-tab title, a welcome string on the login page, custom footer links, and the import / export of the whole theme as JSON. A separate Community Themes browser lets you pull in a pre-built theme or publish yours back to the community.
Whitelabeling applies to the whole deployment. All administrators and all tenants see the same logo, the same colours, the same login page, and the same footer links. If you run NetLock RMM as an MSP and your customers sign into the Console directly, they all sign into the same branded Console.
Per-tenant branding (a customer seeing their own logo when they sign in) is not supported. PDF report branding is managed separately in the Reports module (Chapter 11), and email notification branding is managed in the Notifications configuration (Chapter A.8).
The Web Console Logo slot replaces the default NetLock RMM wordmark in the Console's top-left corner once you are signed in.
Accepted formats: PNG or JPG.
Maximum size: 2 MB.
Recommended dimensions: 200 × 50 pixels.
Upload: drag and drop onto the slot, or click to open a file picker.
A single logo is used across light and dark modes; the page has no separate dark-mode logo upload. If your full-colour logo does not render well on a dark background, supply a version that works on both, for example a white-on-transparent PNG with enough contrast in both modes. The favicon is part of the build and cannot be uploaded here.
The Login Page Background slot replaces the background imagery on the Console's unauthenticated sign-in page.
Accepted formats: WEBP, PNG, JPEG, GIF, or MP4.
Maximum size: 20 MB.
Behaviour for video: an uploaded MP4 auto-plays, is muted by default, and loops continuously.
The background runs full-bleed behind the sign-in form, so pick imagery with enough contrast margin around the centre that the sign-in form remains legible. The size limit is higher than for the logo because a good-quality image or short loop can be several megabytes.
The central portion of the page is the colour palette. NetLock RMM has 40 colour fields: twenty for light mode and twenty for dark mode, as mirrored pairs. Each field is a text input for a hex value (such as #1976D2) paired with a spectrum colour-picker widget, so you can pick visually or paste a hex value from your brand guide.
A short instruction sits above the fields:
Customize the color palette for both light and dark modes. Use hex color codes (e.g., #FF0000 for red).
The twenty fields per mode fall into these groups:
Brand accent colours:Primary, Secondary, Tertiary and their Contrast Text counterparts. Use these for calls to action, selected states, and interactive accents.
Surfaces:Background, Background Gray, Surface. Base page, panel, and card surfaces.
Semantic colours:Info, Success, Warning, Error with their Contrast Text pairs. These drive alert banners, confirmation snackbars, validation errors, and similar feedback surfaces.
Text colours:Text Primary, Text Secondary, Text Disabled.
Action colours:Action Default, Action Disabled. Default icon and control tint in the neutral state.
Chrome colours:Drawer Background, Drawer Text, AppBar Background, AppBar Text. The navigation rail and top bar.
The same categories appear in the dark-mode section with different values. One palette cannot apply to both modes; every mode carries its own set of twenty. A brand colour that looks good on a white surface rarely looks good on a near-black surface, so the two sets usually differ anyway.
Do not leave Contrast Text fields at defaults unless the default genuinely reads cleanly on your chosen brand colour. Low-contrast text is a frequent problem in a new whitelabel.
Keep Background and Surface subtly different rather than identical, so cards read as cards.
Semantic colours (Success, Warning, Error) should remain recognisable as their semantics. A green brand colour re-used as Warning confuses users.
Web Console Title is a plain text field. Its value appears in the browser tab and in the authenticated header. The default is NetLock RMM; replace it with your service name (for example, Acme MSP Console) to brand the browser tab and screenshots.
Welcome Text is the greeting string on the login page. Use it for a short welcome or a compliance notice, for example Welcome to the Acme MSP Console. Authorised use only. Keep it short.
The login-page footer is a configurable list of name-and-URL pairs. Each entry has:
Label: the text the user sees.
URL (optional): where the link points. If you leave this empty, the label renders as plain text rather than as a link, which is useful for small disclaimer strings in the footer area.
Two built-in toggles control whether NetLock RMM's own footer links appear:
Show built-in 'Support' link
Show built-in 'Documentation' link
Turn these off if your whitelabel replaces them with your own support and documentation URLs, on if you want users to reach the default NetLock RMM destinations.
The AppBar & Effects tab holds one checkbox per icon in the top bar: logo, AI chat, global search, agent download, GitHub, documentation, support, Discord, Mini game, version number and install app. Clear a box and the icon disappears for every user of the deployment; the same entry disappears from the overflow menu of the phone layout. Clearing Global search hides the search box and the phone icon that opens it; the results page at /search remains reachable by its address. The settings are deployment-wide and take effect on the next page load.
Mini game controls the gamepad icon that opens the Arcade. Clearing it hides the Arcade and all three games it lists, Virus Defense, Kernel Panic and Overclock Rally. Clear it if a games icon does not belong in your branded console; see Chapter 15.4.
Clicking Import Theme opens the Import Whitelabeling Theme dialog. Pick a previously exported .json file. The dialog shows a preview of what is about to be applied:
The console title from the file.
A checklist of included components (logo, background, palette, appbar, particles, fun facts, footer links).
Palette swatches so you can see the colours before you commit.
The dialog automatically downloads a backup of your current theme before applying the imported one:
Your current theme will automatically be downloaded as a backup before the import.
If the imported file is missing a component your current theme has, the missing component is skipped gracefully rather than overwriting your current value with blank. This means you can safely import a palette-only theme without losing your logo.
The Community Themes button opens a browser for pre-built themes shared by other NetLock RMM administrators, and is also the entry point for publishing yours back to the community.
The browse dialog supports a free-text search across name, description, and category, and a category filter with seven values:
Light Theme
Dark Theme
Corporate
MSP
Seasonal
Holiday
Other
Theme cards show a preview screenshot, the theme name, its category, its maintainer, and an Official badge when the theme has been curated by NetLock RMM. If a video preview is provided, the card exposes a link to it.
Clicking a card opens the theme detail view. The detail view includes the full description, the creator's contact and homepage URLs, the video preview, the screenshot gallery, palette swatches, and a checklist of which components are included. The detail view's Import button runs the same auto-backup flow as a local JSON import: your current theme is downloaded first, then the community theme is applied on top.
The Publish to Community button opens a dialog for submitting your current theme to the community catalogue. The submission fields are:
Field
Limit / note
Theme Name
Required, up to 255 characters.
Description
Up to 8000 characters.
Category
Required; dropdown of the seven categories listed above.
Contact
Optional, up to 255 characters.
Homepage URL
Optional, up to 512 characters.
Video Preview URL
Optional, up to 512 characters.
Screenshots
Up to three, 2 MB each.
Beneath the metadata you pick which components are included in the publication:
Logo: on by default if you have one set.
Login Background: on by default if you have one set.
Particles configuration: off by default.
Fun Facts: off by default for privacy.
Footer Links: off by default for privacy.
A note inside the dialog states:
Color palette and AppBar settings are always included. Iframe-embedding is never shared.
The palette is the core of any theme, so it is always included. Iframe-embedding settings are deployment-specific security configuration and are therefore never shared.
Published themes can be reported by other community members for moderation, and the Community Themes section follows the same moderation model as Community Scripts (Chapter 8.1) and Community Reports (Chapter 11).
Two mode selectors sit separately from the palette fields, because the palette defines the colours for both modes regardless of which mode is currently rendered.
Login Page Theme: system, light, or dark. Controls the login page's colour mode.
Global Theme Mode: system, light, or dark. Controls the authenticated Console's colour mode.
When either is set to system, NetLock RMM follows the operating system's light / dark preference on the viewer's device. Setting one or both to an explicit light or dark overrides the system preference.
Community themes always contain both the light and the dark palette, so importing one never leaves you with a half-configured theme.
For colour palette changes specifically, a slightly different message appears:
Changes will be applied immediately after saving. The Login page may require a refresh to see the new colors.
The signed-in Console updates for every administrator right after you save. The login page is cached more aggressively and may need a hard refresh (Ctrl + Shift + R, or Cmd + Shift + R on macOS) to pick up palette changes.
No whitelabeling change needs a Console restart, so you can adjust the page during working hours without disrupting anyone.
The following order keeps a first whitelabel short:
Gather your brand inputs first. Have the logo file, the background image or video, the six or so brand hex values, and the footer-link URLs to hand before you open the page. Switching between this page and your brand assets folder otherwise costs the most time.
Upload the logo and background first. Get the top-of-page sections done and saved, so you have a visual frame to judge colours against.
Start with the light-mode palette. Set Primary and Secondary from your brand guide, then work through the remaining light-mode fields. Set the contrast-text fields explicitly instead of leaving them on their defaults.
Mirror the dark-mode palette. Do not simply copy the light values across; dark backgrounds typically need slightly lighter, more desaturated brand colours to read cleanly. Use the mode toggle (see A.6.7) to flip the Console into dark mode while you tune.
Set the text fields. Console title, welcome text, footer links. Decide whether the built-in Support and Documentation links stay on.
Export the theme as JSON. Keep the file as your brand backup. When you later want to propagate the theme to a second deployment (staging to production, or one tenant-of-yours to another of your deployments), you import the file rather than re-entering every value by hand.
Save. Confirm that every signed-in admin sees the new look within a few seconds. Hard-refresh the login page in a private-browsing window to confirm the login colours also landed.
A first whitelabel pass done this way typically takes an hour; subsequent adjustments are a few minutes at a time.
The Remote Screen Control page at /settings/remote-screen is where a deployment operator decides whether remote control sessions are recorded, how long those recordings stay on disk, and where they are watched, downloaded, or deleted when something needs reviewing. It is an audit-and-compliance page, not a connection page. Several sections of this chapter describe the viewers instead of server settings:
A.7.5 and A.7.6 cover the stream mode and the clipboard an operator sets inside a running session.
A.7.8 to A.7.11 describe input, the three viewers (web console, Relay App, NetLock app), pasting files into a session and the touch input of the NetLock app.
A.7.12 covers viewing and controlling Android devices.
How a session reaches the device (the agent streams JPEG frames through the NetLock server to the viewer) is outlined in Chapter 3.5. Nothing on this admin page changes how sessions connect; it only controls what the server does with a recording once a session has ended.
Two controls drive the recording behaviour for the whole deployment.
Force session recording: a single toggle at the top of the page. When on, the Remote Server records every remote control session that any operator starts against any device. Recording cannot be declined by the operator and is not surfaced as a per-session option; the policy is deployment-wide. When off, no server-side recording is performed. The field description on the page reads "When enabled, all remote screen control sessions will be recorded by the server."
Save: the toolbar action that persists the toggle. Changes do not apply to sessions already in progress; a recording started under the old setting continues to behave as it did when it began.
Without the toggle, an operator can still record a single session from the viewer. Every viewer shows a running recording, a forced one included, for as long as it runs; see Recording in the viewers.
Note: The recording is produced by the Remote Server, not by the operator's browser. You do not need any client-side capture software, and the session being recorded does not reveal itself to the remote user any differently from an unrecorded session. Treat the toggle as a compliance decision: once it is on, every session is evidence, and every operator should be told so.
Compliance requirements rarely call for keeping recordings indefinitely. Two fields manage their lifetime:
Auto purge: a checkbox that enables automatic cleanup on a rolling window. When off, recordings are kept until an operator deletes them from the session browser.
Older than X days: the retention window, in days. Recordings older than the chosen value are removed on the next purge cycle. Valid range on self-hosted deployments is 1 to 9999 days.
Cloud only: On cloud deployments, the retention window is fixed at seven days and the numeric field is hidden. The page shows the text "Your recordings will be kept for seven days." instead. To keep recordings longer on cloud, download the ZIP before the seven-day window elapses (see A.7.3).
Self-hosted operators can use the whole range. With Auto purge set to 1 day, recordings are kept just long enough to review them on the day they happen. A value of 9999 keeps them practically forever; plan disk space for that as for any long-lived evidence store, and review the capacity periodically. Auto purge deletes recordings older than the threshold and nothing else.
The lower half of the page is a table of recorded sessions. The table fills when you click Load Sessions in the toolbar.
Each row represents one recorded session, with three row actions:
View: opens the Recording Session Viewer, an in-Console playback dialog. Use this for quick review without copying the recording off the server.
Download ZIP: packages the session's files into a zip archive and triggers a browser download. Use this when evidence has to leave the server, for example for an external auditor, a ticket attachment, or a long-term archive outside the retention window.
Delete: opens a confirmation dialog and, on confirm, deletes the session directory. Deletion is immediate and not undoable. The auto-purge setting does not replace the button; operators still need manual delete for sessions they want gone sooner than the window allows.
If a session row is missing from the table after Load Sessions, check whether the session actually fell into the current retention window. Auto-purge may already have removed it.
Viewers. The Force session recording toggle applies to every session, whether it was opened from the web console, the Relay App or the NetLock app (A.7.9).
Maintenance mode. Maintenance mode suppresses notifications but does not suspend recording. A session started during maintenance is still recorded if the toggle is on. See A.2 for maintenance-mode semantics.
Per-operator opt-out. Operators cannot opt out. Session recording is enforced at the server, not at the operator's workstation, so no client-side setting can bypass it.
Every remote control session streams the device's screen as JPEG frames. The operator sets how sharp, how smooth and how large that stream is, per session, with the Stream mode selector in the viewer; no server-side setting is involved. This section lists the modes, where the selector sits, what the statistics overlay shows, what an older agent does, and how the screen is captured on the device.
Quality keeps the full colour resolution (4:4:4), so small text and colour edges show no fringes, and streams the screen at its native size. Pick it for reading, detail work and screenshots; the frames are large.
Balanced is the default of the web console and the Relay App; the NetLock app starts with Auto, which suits a mobile connection better. The device adjusts the JPEG quality within a middle range to the amount of change on the screen.
Performance favours motion: up to 60 frames per second, a lower quality range and a resolution ceiling of 1600 px. Pick it for video, animations and fast interaction.
Auto starts with the Balanced settings and then steps the frame rate, the resolution ceiling and the quality up or down while the session runs. It reacts to four signals, measured once per second in the viewer: the frame rate actually received against the requested one, the round-trip time to the agent, the time the viewer needs to decode a frame, and frames that were superseded by a newer one before they could be shown. Under congestion it steps down at most once every two seconds; after several seconds of headroom it steps back up, one step at a time. Colour stays 4:2:0 in Auto; 4:4:4 is only available in Quality and Custom.
Custom uses exactly the values of the advanced panel: frame rate (5, 10, 15, 20, 30, 45 or 60 fps), quality (Auto for adaptive quality, or the fixed levels High, Medium and Low), chroma (4:2:0 or 4:4:4) and resolution (Auto fits the viewer window, Full is the native size, Saver caps the longest edge at 1600 px). Touching any of these values while a preset is selected switches the mode to Custom automatically. Custom applies no mode ceiling, so Full reaches the native resolution.
The resolution is a ceiling, not a target: a frame is never larger than the screen, and in Auto resolution never larger than what the viewer window can show. The mode is per session and stays selected across monitor switches.
Web Console. The Stream mode select sits in the viewer toolbar directly after Zoom. The advanced panel is the Streaming settings popover (tune icon) further right in the same row; the statistics overlay is toggled with the Statistics button next to it.
Relay App. The Mode picker is in the second toolbar row of the viewer window, next to the resolution picker. Advanced reveals a third row with FPS, Quality and Chroma; it opens on its own when Custom is selected. Stats toggles the statistics panel.
NetLock app.More → Streaming settings opens a sheet with the five modes and their descriptions, and under Advanced the frame rate, quality, chroma and resolution. The statistics button in the viewer toolbar shows the statistics panel.
Changes apply to the running stream at once. Nothing reconnects, the session is not interrupted and a recording in progress continues. On a screen where nothing moves, the new settings show with the next periodic refresh, within four seconds.
The overlay is the place to judge a mode and to see what the connection is doing. Its values:
Mode: the selected mode.
FPS: two numbers: frames shown in the viewer per second, and frames received from the agent per second (shown / received in the Web Console, shown / sent in the Relay App). A gap between the two means the viewer cannot keep up.
Bandwidth: the received stream in kbit/s, smoothed over the last seconds. A static screen sits near zero.
Frame size (Relay App: Avg Frame): the average size of a frame in KB.
Decode: the time the viewer needs to decode one frame, in milliseconds.
Encode: the time the device needs to compress one frame, in milliseconds, as reported by the agent.
Round-trip time (Relay App: RTT): the round trip between the viewer and the agent, measured with a probe every two seconds.
Resolution: the size of the streamed frame and, after the @, the frame rate the device actually achieves.
Capture method (Relay App: Capture): dxgi when the screen is captured with the Desktop Duplication API, gdi when the classic capture is in use (see Capture on the device).
Quality and Chroma: the JPEG quality and colour subsampling of the last frames.
Dropped frames (Relay App: Dropped): frames that arrived but were superseded by a newer one before they were shown. A steadily rising count means the connection or the viewer is behind; Auto reacts to it.
Adaptive step (Relay App: Adaptive): in Auto, the current step of the adaptive controller: 0 is the Balanced baseline, positive steps reduce the load, negative steps raise the frame rate.
The Relay App and the NetLock app additionally list the codec, the total data received and the number of frames.
Web Console: in the browser's local storage (mode, chroma, frame rate, quality, resolution mode and whether the overlay is visible). The choice is per browser and per Console address; another browser or a private window starts with Balanced again. Nothing is stored on the server or per account.
Relay App: in the app's own settings store (session_settings.dat in its application data directory), so the choice applies to every session opened from that installation of the app. The resolution mode, the clipboard switch and whether the statistics panel is visible are kept there as well.
NetLock app: in the app's settings on the phone (mode, advanced values, statistics panel and the touch settings of A.7.11), for every device opened from that phone.
Stream modes need an agent of version 3.3.0.1 or newer on the device. With an older agent the session still works: the stream runs with the settings that agent supports, the viewer shows a hint next to the mode selector, and a mode change is translated into the closest frame rate and quality the old agent understands (at most 30 fps and always 4:2:0). Update the agent to get 60 fps, 4:4:4 and the adaptive quality ranges.
A macOS device is offered for screen control and the end user chat only from agent 3.3.0.11 on: the device page, the tool window, the Relay App and the NetLock app leave the entries out for a Mac on an older agent instead of opening a session that cannot deliver a picture.
On Windows the screen is captured with the Desktop Duplication API and falls back to the classic GDI capture automatically wherever duplication is not available: headless devices, RDP sessions, the lock screen and UAC prompts, devices running on the Microsoft Basic Display Adapter. The fallback is decided per screen and per frame; the device retries Desktop Duplication on its own, and the overlay's Capture method shows which one is active. Every mode works on both paths; only the CPU cost differs.
A screen where nothing changes costs almost nothing: the device sends a small "unchanged" reply instead of a frame, and re-sends the full picture every four seconds so that a viewer joining late, or a monitor switch, always gets an image.
Performance mode on a weak endpoint does not run the device dry: when capture and compression together take more than 80 % of the frame interval, the device halves the effective frame rate on its own and raises it again when there is headroom. The overlay's Resolution row shows the frame rate the device actually achieves.
Note: On Linux (Wayland, see X.8.5) the frame-rate cap and the resolution ceiling of a mode apply; quality and chroma are decided by the capture tools on the device and are not changed by the mode.
On macOS (agent 3.3.0.11 or later, see X.8.6) the screen is captured with ScreenCaptureKit, one stream per display. Every mode applies as on Windows: frame rate, resolution ceiling, quality range and chroma, the "unchanged" reply for a still screen with the full picture every four seconds, the frame-rate reduction on a busy device, and the statistics overlay, whose Capture method shows sck.
When a stream does not start or stops delivering, the device takes single pictures instead until a stream works again. The picture needs the screen recording permission on the Mac and the input the accessibility permission; the remote control window names the one that is missing. The pointer is not part of the picture; the viewer shows its own, as on Windows.
Recording works in every mode. The Remote Server samples the frames as they are streamed, so a recording carries the resolution and quality of the mode that was active; the Force session recording toggle in A.7.1 applies regardless of the mode.
Text travels in both directions of a remote control session. Which directions are active is decided in the viewer with the Clipboard switch, per operator and per session, like the stream mode in A.7.5. No policy or server setting controls it: a second operator in the same session has their own switch, and the device is told about it for as long as that viewer's session lasts.
Ctrl+V in the viewer reads the operator's own clipboard in the browser and sends the text with the keystroke, so the paste lands in the application that has the focus on the device.
In the NetLock app the same is done with More → Paste from phone, which sends the text of the phone's clipboard.
Files are handled separately. Files copied in the operator's file manager and pressed in with Ctrl+V, dropped onto the picture or chosen with Send files are sent to the device as files and pasted there; see A.7.10.
Ctrl+C in the viewer is forwarded to the device, which injects the copy into the focused application and then waits for the clipboard to actually change before it answers. The device waits up to about half a second for the copy to land and then sends the text.
A clipboard that did not change within that budget is answered as empty. The operator's clipboard then keeps what it holds instead of receiving the value the copy was meant to replace, and the viewer says so.
While the switch is on, the device reports every change of its own clipboard, however the end user produced it, for example with the context menu's Copy, an application's own copy button, or a shortcut pressed at the device itself. Nothing has to be pressed in the viewer, and the text lands on the operator's clipboard as it arrives.
What the device applies before it reports a change:
An empty clipboard is never reported; it would clear the operator's clipboard.
Content that is not text is skipped.
Text the operator has just pasted into the session is not handed straight back to them.
Changes that fall close together are coalesced: at most one report every 250 ms, carrying the value the clipboard holds by then.
The clipboard as it stands when the first viewer subscribes is a baseline, not a change. Reporting starts with the first copy after that.
Reporting runs only while at least one viewer of the session asked for it and stops with the last one. It is not session activity, so a session in which nothing else happens still reaches its inactivity timeout.
The View remote clipboard button next to the switch opens a dialog showing what the remote session's clipboard holds at that moment. It only reads the clipboard:
No copy is injected on the device. The end user's selection and the end user's clipboard stay exactly as they were. That is what separates the dialog from Ctrl+C, which necessarily copies whatever is selected in the focused application.
The operator's own clipboard is not touched either. The text reaches it only when the operator presses Copy to my clipboard in the dialog.
Refresh asks again; the character count of the answer is shown below the text. Where there is nothing to show, the dialog says why, inline instead of as a toast: the clipboard is empty, it holds something that is not text, the content is too large, it could not be read, or the device did not answer within eight seconds. The last two offer a retry.
The dialog is useful alongside the automatic sync in three situations:
with the switch off, when you want to see what the end user has without taking it;
at the start of a session, because the automatic sync only reports changes from the moment it begins and does not see what was already on the clipboard;
where the sync is not available on the device at all.
The switch governs both directions at once: a paste into the session, and the device reporting its own clipboard changes. It is on by default.
Web Console.Clipboard in the viewer toolbar. The choice is remembered per browser, next to the stream settings; another browser or a private window starts with it on again. Nothing is stored on the server or per account.
Relay App. The Clipboard checkbox of the viewer window, on by default.
NetLock app.Clipboard sync in the More menu of the viewer.
In the web console and the Relay App the switch also decides whether Ctrl+V with copied files sends those files (A.7.10); dropping files and Send files work with the switch off.
The device is told the state of the switch once the session is streaming and again on every change. Turning it off stops the reporting at the device, not just in the viewer.
Reporting also follows the session's access state. While the session is not granted (the end user has not accepted, or the grant has lapsed), the device does not report clipboard changes and does not answer a request for its clipboard, even if the switch is on. That is re-evaluated for the running stream, not only when the switch is touched.
None. On macOS 15.4 and later the content is read only while the clipboard access of NetLock RMM User Process is set to Always Allow on the Mac; otherwise automatic sync stays off and Ctrl+C and the view dialog read on request, which macOS may confirm with the user at the Mac (see X.8.6).
Linux — Wayland
wl-clipboard
Linux — X11
xclip or xsel
Linux — none of these tools installed
No automatic sync, and no clipboard at all.
A Linux session with none of wl-clipboard, xclip or xsel cannot reach its clipboard in either direction. Ctrl+C and the view dialog are answered with "The clipboard of the remote device cannot be accessed in this session", and no copy is injected for a request that cannot be answered. Install one of the tools (wl-clipboard on Wayland, xclip or xsel on X11) to enable it; see X.8.5.
Text only. Files, pictures and rich text are never transferred in either direction:
On the automatic sync, a copied file or picture is skipped without a message. Copying a file is normal use, and the viewer would otherwise show a message every time the end user copies one.
In the view dialog, where the operator asked for the result, the device distinguishes the two cases on Windows and reports "The clipboard of the remote device holds content that is not text" instead of claiming an empty clipboard. On macOS and Linux the clipboard is read through tools that hand out text only, so both cases arrive as an empty clipboard.
To move files to the device, paste them into the session as described in A.7.10.
At most 1 MiB. Content larger than 1 MiB of UTF-8 text is not transferred, and it is not shortened either. The operator is told ("The clipboard content of the remote device is too large to transfer"), once per copy rather than on every poll.
Writing to the operator's clipboard is done by the browser, under the browser's own rules.
A secure context. Serve the Console over HTTPS (localhost also counts). Otherwise the browser can refuse clipboard writes.
A focused tab. Text arriving from the device is a server push, not a click, and that is the state in which browsers refuse a clipboard write. This shows most visibly when the viewer sits on a second monitor, the developer tools have the focus, or the tab is in the background. The Console therefore retries the write once on the operator's next click or keypress and says so meanwhile: "Clipboard received. Click into the session to apply it." Click into the session and the text is on the clipboard. Only the newest text is held, and the retry expires after 30 seconds.
The view dialog is not affected by this: its Copy to my clipboard happens inside the operator's own click.
The automatic sync and the view dialog need an agent of version 3.3.0.1 or newer on the device; they are advertised separately, because reading the clipboard on request works wherever the clipboard can be read at all, while reporting changes depends on the platform. With an older agent the session still works and pasting into it is unaffected:
The viewer shows a hint next to the Clipboard switch ("This agent version does not sync the clipboard automatically") and Ctrl+C in the viewer still works.
The View remote clipboard button is present but disabled, with a tooltip that says why. A request the device cannot answer is never sent, and a request that does go unanswered leaves the dialog after eight seconds with a retry rather than spinning.
The Relay App and the NetLock app carry the switch, the device's messages and the view as well: View remote clipboard in the toolbar of the Relay App, More → View remote clipboard in the NetLock app while the picture runs. Both show the text read-only with its character count and Copy to my clipboard, wait eight seconds for the answer and name an empty clipboard or content that is not text. A text longer than 64 KB is shown cut off with a note; Copy to my clipboard still takes the whole text. With an older agent the Relay App disables the button with the reason as tooltip, and the NetLock app shows the reason instead of the text.
Clipboard transfers are not recorded in the audit trail. Neither direction is logged: a paste into the session, the answer to Ctrl+C, an automatic report and a look with the view dialog leave no audit entry. None of the transferred content is written to the audit trail, the server logs or the device's logs. The device's own log records the outcome and the length of a transfer, never the text.
The start and the end of the remote control session itself are recorded (see A.9 and, for sessions from the Relay App and the NetLock app, Audit of app sessions), and session recording under A.7.1 captures the screen, so a paste that becomes visible on the device appears in the recording like anything else on screen.
The end user chat can be turned into a voice call. An operator calls the signed-in user of a Windows device from two places: the phone icon in the title row of the end user chat popup (which rings the session the chat talks to) and the phone icon in the title row of the remote screen control dialog, which opens the chat popup and places the call as soon as the session picker has settled. The audio travels as Opus packets through the NetLock server over the same hub that carries remote control sessions; no additional port and no direct connection between the browser and the device are needed.
The tray icon of the device shows an incoming call window with the operator's name and picture, plays a ring tone and waits 45 seconds for Accept or Decline; without an answer the call times out and the operator is told so.
After accepting, the user's default microphone and playback device are in use; the call window on the device lets the user change both devices, mute the microphone, switch echo suppression and hang up, and it shows the level of both sides and the duration.
The operator has the same controls in the console: a call bar under the title row of the chat popup with the state (calling, ringing, connected with the user's name), the duration, mute, the microphone and playback device pickers, level meters and Hang up. Either side can end the call; closing the chat popup or switching the user during a call asks the operator for confirmation first.
Permission. The account needs devices_remote_audio_call ("Audio call" in the permission editor, directly under Remote Control). Members of the built-in Administrator role hold it automatically; every other account or role has to be granted it. Without the permission the phone icons are not rendered and the server refuses the call.
Policy. On the Agent tab of the policy, Allow audio calls sits in the Remote Control block below Remote Screen Control (see §6.4). It is on by default and only takes effect while remote screen control is enabled in the same policy; a policy with remote screen control off cannot carry calls. The texts of the incoming call window (title, message with {operator} replaced by the operator's name, and the Accept, Decline and Hang up buttons) are edited in the Audio Call block of the Tray Icon tab (§6.5); empty fields use the English defaults. A change of the policy reaches the server's check within about 30 seconds.
Device. Windows only. Requires agent 3.3.0.5 or later with the tray icon running in the user's session. A device with an older agent answers "agent update required"; a device without a signed-in user, without a running tray icon, or a Linux or macOS device shows no phone icon or reports the call as not supported. Mobile devices cannot be called.
Browser. The operator's browser needs WebCodecs with the Opus codec, an AudioWorklet and microphone access: Chrome and Edge, Firefox 130 or later, Safari 26 or later. A browser without this support shows a toast and nothing else. The console asks for the microphone permission of the site on the first call; a refused permission is reported as a toast, and the call is not placed. The playback device picker is hidden in browsers that cannot route audio to a chosen output (no setSinkId).
The operator's browser applies its own echo cancellation, noise suppression and automatic gain control to the microphone. On the user's side there is no acoustic echo canceller: a user on speakers is heard back by the operator with a delay unless echo suppression is on, which lowers the playback while the user speaks. A headset on the user's side avoids the effect altogether, and the call bar in the console says so.
Calls are not recorded. Session recording (A.7.1), including forced recording, applies to screen sessions only; an audio call never produces a recording. Each call is kept as an entry of the remote control session history with the time of the call, the accepted time as its start, the duration and how it ended (declined, not answered, hung up by the operator or the user, connection lost, or not supported with the reason). The console audit log records "Audio call started" and "Audio call ended" with the reason for the operator's account. The audio itself is never stored.
One call per device session at a time: a second operator who calls the same user while a call is on is told that the user is already in a call, and a repeated call to the same device within a few seconds is asked to wait.
Keyboard input goes to the device once the remote screen has been clicked; it keeps going there in fullscreen and after leaving fullscreen. In fullscreen in Firefox and Safari, Esc ends the fullscreen view (a browser rule) and does not reach the device; for Chrome and Edge see Full screen in Chrome and Edge. With agent 3.3.0.11 or later, Ctrl and Shift held during a mouse click or a wheel turn reach the device as well, so Shift+right-click (for example Run as different user on Windows), Ctrl+click and Shift+click selections work. Firefox always shows its own context menu on Shift+right-click in addition to the device's menu; this is browser behaviour that a web page cannot switch off, so close the browser menu with Esc or use Chrome or Edge for this shortcut.
On a macOS device the modifiers of a Windows or Linux keyboard are translated: Ctrl is applied as Command, the Windows or Meta key as Control and Alt as Option, for keyboard shortcuts as well as for clicks and the wheel. When the viewer runs on a Mac too, the keys are sent as they were pressed, so Command stays Command and Control stays Control; this applies to the Web Console and the Relay App. The Ctrl+Alt+Del button sends Command+Option+Esc to a Mac. See X.8.6 for the permissions the input needs there.
In the Relay App the pointer reaches the device while it moves over the picture, also without a pressed button, so hover effects and tooltips on the device appear. Ctrl and Shift go with clicks and the wheel, as in the web console. A horizontal wheel or a sideways swipe on a touchpad is sent as Shift+wheel, which applications on the device read as horizontal scrolling. Two keys stay with the Relay App:
Ctrl+wheel (Command+wheel when the Relay App runs on a Mac) zooms the picture and never reaches the device. On a Mac, Control+wheel is sent to the device as a wheel turn with Ctrl.
F11 switches full screen on and off and is not sent. Unlike in the browser, Esc in full screen goes to the device; leave full screen with F11 or the Exit full screen button.
In the NetLock app input works by touch, in one of two modes; see A.7.11.
Some shortcuts never reach the browser, because the operator's own computer keeps them: the Windows or Super key on its own and its combinations (Win+D, Win+R, Super+D), Alt+Tab, Ctrl+Shift+Esc and, depending on the system, Alt+F4, F11 and Print. The shortcut button (⌘ icon) next to Ctrl+Alt+Del in the toolbar opens a menu that sends them to the device. It lists the shortcuts of the device's operating system:
Device
Shortcuts in the menu
Windows
Start menu (Win), Show desktop (Win+D), File Explorer (Win+E), Run dialog (Win+R), Quick link menu (Win+X), Task view (Win+Tab), Lock screen (Win+L), Switch window (Alt+Tab), Close window (Alt+F4), Task Manager (Ctrl+Shift+Esc), Escape (Esc), Toggle full screen (F11), Screenshot (Print)
macOS
Switch app (Command+Tab), Spotlight search (Command+Space), Quit app (Command+Q), Close window (Command+W), Hide app (Command+H), Mission Control (Control+↑), Toggle full screen (Control+Command+F), Lock screen (Control+Command+Q), Escape (Esc)
Linux (GNOME, KDE Plasma)
Activities overview (Super), Show desktop (Super+D), Show applications (Super+A), Switch window (Alt+Tab), Close window (Alt+F4), Run a command (Alt+F2), Open terminal (Ctrl+Alt+T), Toggle full screen (F11), Escape (Esc), Screenshot (Print)
The macOS shortcuts are sent as listed, with Command, Control and Option of the Mac; the modifier translation described above does not apply to them.
The last entry, Win + next key (Super + next key on Linux, Cmd + next key on macOS), covers combinations that are not in the list, such as Win+Shift+S or Win+V: the next key you press goes to the device together with that key, then the menu returns to normal. While it waits, the shortcut button is highlighted and a note is shown on the remote screen; Esc or choosing the entry again cancels it. On a phone or tablet the next character typed on the soft keyboard is used.
Each shortcut is pressed and released at once. Alt+Tab and Command+Tab therefore switch to the previous window only; to choose any open window, use Task view (Win+Tab) or Mission Control.
What a shortcut does depends on the settings of the device. Super+D shows the desktop on Ubuntu and KDE Plasma but is not assigned on a standard GNOME desktop (Fedora, for example); use Super or Alt+Tab there. Alt+F2 and Ctrl+Alt+T are GNOME and Ubuntu shortcuts.
Ctrl+Alt+Del stays a button of its own. Its tooltip names what the device does with it: Windows shows its security screen, a Mac opens Force Quit Applications (Command+Option+Esc), Linux opens the log out dialog of the desktop.
On a phone or tablet the menu is also the way to send Esc, which the soft keyboard does not have.
The Relay App offers the same menu, including the + next key entry, under the Shortcuts button next to Ctrl+Alt+Del. In the NetLock app, More → Keyboard shortcuts lists the same shortcuts; for other combinations use the latched Win key of the key bar (A.7.11).
In full screen, Chrome and Edge hand the keyboard to the remote screen. Esc, the Windows key on its own and combinations such as Win+D or Alt+Tab then go to the device, as far as the operator's operating system releases them to the browser; Ctrl+Alt+Del and Win+L always stay with the operator's computer (use the button and the menu for them). To leave full screen, hold Esc for two seconds; the browser shows a note about it when full screen starts. The browser may ask once whether the console may use the keyboard; if this is refused, full screen works as in Firefox.
Firefox and Safari do not offer this: there Esc leaves full screen, and the keyboard shortcut menu in the toolbar is the way to send these keys.
A remote screen session is opened from one of three viewers. All three talk to the same screen hub of the server and to the same agent, so what the device does is the same; they differ in how they are operated and how they sign in.
Web console
Relay App
NetLock app
Opened from
Remote Control on the device
Tab Screen Control of the sessions window, Connect on a device
For the Relay App and the NetLock app, the server lets a relay API key open a screen session only when the key's Screen control switch is on (Relay Server → Manage API Keys) and the account that owns the key holds devices_remote_control and the device's tenant. The account that owns the key is the account the session runs under: it is shown on the device, it is written to the audit log, and its permissions decide what the session may do.
While the server records a session, every viewer shows a red REC chip, from the first picture to the end of the recording. The chip follows the recording state the server reports, not a local setting, so a recording started by another viewer of the same session, or forced by Force session recording, is shown as well. The Relay App and the NetLock app write REC (forced) for a forced recording; the web console shows REC with the tooltip "This session is recorded by policy and cannot be stopped." In the NetLock app the chip stays visible while the toolbar is hidden.
Start and stop
Web console
Start recording and Stop recording in the toolbar; a click on the chip stops as well.
Relay App
The recording button in the toolbar, enabled while the picture runs.
NetLock app
More → Start recording or Stop recording while the picture runs.
A forced recording cannot be stopped: the web console offers neither button, the Relay App disables its button, and the NetLock app answers with the policy hint. A stopped recording is reported as "Recording saved (n frames)." or, without any frame, "Recording stopped, no frames were captured."; a start is refused with a message when the storage limit of the instance is reached. When the server ends a recording on its own (storage limit reached, the frame limit of a session reached, a write error), the viewer says so.
When the Relay App or the NetLock app opens a new hub session for the same window (after a connection loss, after switching the session, and in the NetLock app after returning from the background), a recording the operator started is started again. A recording that the server ended does not start again.
Before a session starts, the viewer asks the server how many screen sessions other viewers hold on the device. Web console, Relay App and NetLock app sessions are all counted; backstage sessions are not. When there is at least one, the viewer shows "Another technician is already connected to this device. Proceed with caution to avoid conflicts." for ten seconds. It is a hint, not a block: the session starts as usual. The web console shows it once per remote control dialog, the apps once per window when the session first starts, not again after a reconnect.
The viewers name the states in which no usable picture arrives, as non-blocking notices at the upper edge of the picture; input keeps working while they show.
"Waiting for the first picture from the session." means that the device answers, but no picture arrived since the stream started. When the state lasts, the line "The agent on the device may need an update." is added.
"The remote screen is showing a black picture." means that the viewer samples the shown picture at regular intervals and found it black several times in a row, for example a switched-off display or a session that draws nothing. A pointer, a line of text or a spinner on a black background does not count as black.
No signal: when the picture stops, the last picture stays visible, dimmed, with the reason above it. Retry asks again; Switch session moves to another user session of the device, or Connect anyway connects to the selected session regardless.
Linux devices can be controlled from all three viewers. On a Wayland device the desktop asks the user for the screen-sharing permission on the first connection. Instead of No signal, the viewers show what the device is doing:
Message
Meaning
Waiting for the user to accept screen sharing on the device.
The screen-sharing dialog is open on the device.
Starting the screen capture on the device.
The capture is starting and the first picture is not there yet.
Screen sharing was not accepted on the device.
The dialog was declined or not answered.
Screen capture components are missing on the device. See the Linux prerequisites in the documentation.
A package of the capture path is missing on the device.
The prerequisites and the troubleshooting are in X.8.5.
The server answers a refused session start with a reason, and every viewer shows it as a sentence in the operator's language:
Reason
Text in the viewer
Device offline
The device is offline. It is not connected to the NetLock RMM server.
Device not found
The device was not found.
Other tenant
Access denied for this device's tenant.
No permission, or the relay key's Screen control switch is off
The web console shows its permission message; the apps show Remote control is not allowed for this relay key or account.
Request not queued
The request could not be queued for this device. Please try again.
Approval required (anchored device)
The apps show This device needs an approval in the NetLock app before screen control can start., see A.13.10.
Server could not check the device
The web console shows The server could not check the device right now. Please try again in a moment., the apps The server cannot process the request right now. Please try again in a moment.
Anything else
The screen control session could not be started.
Relay App and NetLock app versions before 3.3.0.11 show a short code such as device_offline instead; update the app.
The consent prompt and the support badge on the device show the name of the technician and, if the account has released its profile picture for end users, the picture. The server sets both from the account the viewer signed in with: the console account for the web console, the account that owns the relay key for the Relay App and the NetLock app. When the account cannot be read, the prompt shows the name of the relay key.
The web console writes the start of a session into the audit log. For a session from the Relay App or the NetLock app the server writes the line Remote control session started (Relay key: <key name>) under the login of the account that owns the key. Recordings started or stopped from the apps, and forced recordings of app sessions, are written in the same way, with the key name.
After a short connection loss the Relay App and the NetLock app reconnect on their own, start the session again on the new connection and return to the same user session and screen. They retry for about two and a half minutes before they show Connection lost. The web console retries its connection to the server on the same schedule. The NetLock app ends the stream when it goes to the background or the phone is locked, and resumes it with the same user session and screen when it comes back.
Files from the operator's computer can be sent into a running session and pasted on the device where the user is working, for example into the open Explorer or Finder folder, onto the desktop, or as a mail attachment. Several files go in one transfer.
Drop the files onto the picture (every browser); the Send files button next to the file browser button (multiple selection); Ctrl+V with files copied in the file manager, in Chromium-based browsers such as Chrome and Edge.
Relay App
Drop the files onto the picture; the Send files button (multiple selection); Ctrl+V with files copied in the file manager.
NetLock app
Not available.
Ctrl+V sends files only while the Clipboard switch of the viewer is on (A.7.6); with text on the clipboard it pastes the text. In the web console:
Firefox does not hand copied files to a web page, so Ctrl+V there always pastes text. Drop the files or use Send files instead.
A picture alone on the clipboard, for example a screenshot, is sent as a file image.png, after the confirmation.
A copy from Office that carries text and formatting next to a picture, for example Excel cells, stays text.
While files are dragged over the picture, a frame with "Drop to send to the device" appears. A drop onto the picture never navigates the browser away from the console, even while no file can be sent; the frame then names the reason.
The viewer asks once for confirmation, with the number of files, their total size and their names.
It uploads the files to the server one after another. A list shows the state of each file (waiting, uploading with percent, uploaded, failed) and offers Cancel; after Cancel nothing is pasted.
It sends the files that arrived to the device as one transfer. A file that failed to upload is left out.
The device downloads the files, puts them on its clipboard as files and pastes them into the application in front. The list shows On the device for each file, and the viewer reports the result, for example "3 files pasted on the device." or "2 of 3 files were pasted."
Only one transfer runs per session at a time; a second one is refused with a message until the first has finished.
Up to 100 files and 10 GB together per transfer; a single file can be up to 10 GB.
Folders are skipped, with a notice; only files are sent.
Names are cleaned the same way in the viewer and on the device: characters that Windows does not allow in file names (< > : " | ? *) become _, reserved Windows names such as CON or NUL get a leading _, and very long names are shortened with the extension kept. Two files with the same name in one transfer become name.ext and name (2).ext.
The files are put on the clipboard as a file list to be copied, then Ctrl+V is pressed in the user's session. Where they land is decided by the application in front: the open Explorer folder, the desktop, an attachment in Outlook.
macOS
The files are put on the general pasteboard as file URLs, then Command+V is pressed. It goes to the application in front: a Finder window pastes into its folder, the Finder without a window pastes onto the desktop, Mail adds an attachment. The Finder is not brought to the front. Command+V needs the Accessibility permission of NetLock RMM User Process (X.8.6); without it the files stay on the clipboard and the viewer says that the user can paste them.
Linux (GNOME and KDE on Wayland)
The files are put on the clipboard with wl-copy from the package wl-clipboard, in the format the desktop's file manager reads, then Ctrl+V is pressed. The open file manager window pastes them. Without wl-clipboard, outside a Wayland session, or when the clipboard cannot be set within five seconds, the files are copied into the user's Downloads folder instead and the viewer shows the path.
When the paste keystroke cannot be sent, the files are on the device's clipboard and the viewer says "The files are on the clipboard of the device, but the paste could not be triggered. The user can paste them there." (web console). When a step fails on the device, the viewer names it (not enough free space, no user session, download failed, the user session did not answer), together with the folder the files were stored in on the device, where one is known.
On the server the files are stored in the File Server folder uploaded of the device, the same folder the file browser shows. They stay there until someone deletes them; a file with the same name is replaced.
On the device the agent downloads them into a folder of its own per transfer, below Clipboard Files in the Remote agent's data directory, from which they are pasted. The folder belongs to the user the files are pasted for: only that account, the system account and administrators (root on Linux and macOS) can read it, and the user cannot place anything in it. In the device session of a Windows device that is the user signed in at the console.
The clipboard of the device points to these copies, so the user can paste them again later; the agent removes them one day after the transfer. A transfer that was saved to the Downloads folder, in which no file arrived, or whose session ended during the download is removed right away.
Permission. Pasting files requires devices_remote_file_browser in every viewer, checked by the server, next to devices_remote_control. For the Relay App it is the account that owns the relay key. Without it the web console shows no Send files button and answers a drop with a message, and the Relay App reports "You are not permitted to send files to this device."
Agent. The device needs an agent that reports file paste, 3.3.0.11 or later. With an older agent Send files is disabled with the tooltip "The agent on this device cannot receive files this way. Update the agent to use it."; a drop is answered with the same notice, and nothing is uploaded.
Server. The Relay App sends files through the server; an older server is reported as "The server does not accept files from the Relay App. Update the server to use it."
Anchored devices. On a device with endpoint protection, the grant of the running screen session (A.13.9) covers the paste; no separate approval is needed.
The web console writes one line per transfer it sent, for example Remote control: 3 file(s) sent to paste into the session ('a.pdf', 'b.pdf', 'c.pdf'), 1048576 bytes. The Relay App's uploads are written by the server, one line per file under the account that owns the relay key, with the key name. A transfer that was cancelled before anything was sent writes no line.
The NetLock app offers two ways to operate the remote screen with the fingers. The Touchpad button in the viewer toolbar switches between them, with a short notice. The choice is kept on the phone and applies to every device. Direct touch is the default; the first time a device with input opens, the app points once to the touchpad mode.
The touch modes need mouse and keyboard input on the device. On a macOS device without the Accessibility permission the button is greyed out; a tap on it explains why.
The app draws a pointer over the picture and the fingers move it like on a laptop touchpad. Clicks always land at the pointer, not under the finger, which makes small targets reachable on a phone screen. The pointer is a white arrow with a black outline whose tip is the click point; it turns cyan while the left button is held. The device's own pointer follows with the delay of the connection. The pointer starts in the middle of the screen, and again after switching the screen or the user session.
Gesture
Effect
One finger moving
Moves the pointer; slow movement is precise, fast movement covers distance
Tap
Left click at the pointer
Tap twice
Double click
Double tap and hold, then move
Drag: the button stays down until the finger lifts
Two-finger tap
Right click
Two fingers moving
Scroll at the pointer, up, down, left and right; the direction is fixed when the movement starts
Pinch
Zoom; while zoomed in, the picture follows the pointer when it reaches the edge
Two-finger double tap
Back to the whole screen
A long press does nothing in this mode, so a resting finger does not right-click, and three or more fingers are ignored. In touchpad mode the Drag mode button is hidden; double tap and hold drags instead.
Touchpad settings (More → Touchpad settings):
Pointer speed: five steps from Slow to Fast.
Mouse button bar: shows a bar with Left and Right above the key bar, in touchpad mode only. A tap on Left clicks; holding Left keeps the button down, so a second finger on the picture moves the pointer and drags. Right right-clicks. There is no middle button.
Show gestures: opens the gesture card, which also appears once the first time the touchpad mode is switched on.
The key bar below the picture holds Esc, Tab, Ctrl, Alt, Win, Shift, the arrow keys, Del, Home, End, PgUp, PgDn, Ins and F1 to F12; the keyboard button opens the phone's keyboard for typing. A modifier is latched:
A tap latches it for one use: it applies to the next key, click, drag or scroll and is released afterwards.
A long press locks it until it is tapped again.
Ctrl and Shift apply to taps, clicks, drags and every scroll step in both touch modes, for example Ctrl+click to select several files or Shift+click to select a range. Alt and Win apply to keys only. On a macOS device the modifiers are translated as described in A.7.8.
When the app goes to the background, the phone is locked, a call comes in or the mode is switched while a button is held down (dragging, or holding Left of the mouse button bar), the app releases the button on the device first, so no button stays pressed.
An Android phone or tablet enrolled with the NetLock RMM app can be viewed and, when its policy allows it, controlled from the web console. Open the device on Devices and choose View screen in the action bar; the button reads Control screen when the device's policy allows control. The Relay App and the NetLock app do not offer screen sessions to Android devices.
A person at the phone is always involved: Android asks its user for permission at the start of every session, and nothing can be shown or operated while nobody is at the device.
The account holds devices_remote_control. The same permission covers viewing and controlling; Android needs no separate permission.
Opening a session passes the step-up authentication of the remote actions, as for every remote action on a desktop device, viewing included.
For control, the device's policy has Remote Screen Control switched on (Enable on the Remote Control sub-tab of the Agent tab, see Chapter 6.4), the same setting as for desktop devices. Its Access mode does not apply to Android: the phone always asks. Viewing does not depend on this setting.
The phone runs an app version with remote control, and its remote control service is switched on (see below). Typing text needs Android 13 or later; taps, swipes, scrolling and the system buttons work on every Android version the app supports.
On a phone protected by endpoint protection, every screen session, viewing included, needs an approval on a registered phone (A.13.11).
Control works through an Android accessibility service of the app, NetLock remote control. It does not read what is on the screen and collects no data; it only carries out what the technician does in the viewer, and only during a session the user allowed.
While the device's policy allows control and the device is approved, the app shows the card Remote control with the state of the service (Not set up yet. Until then, technicians can only see the screen. or Ready.). Set up remote control first shows Allow remote control?, which explains what the service does and does not do; after Agree, Android's accessibility settings open.
Android opens the list of accessibility services, not the page of this one. The service appears in that list only after Agree: the app ships it switched off and makes it available only while the policy allows control, and removes it again when the policy stops allowing it or the enrollment is removed. Find NetLock remote control in the list (depending on the manufacturer under Installed apps or Downloaded apps) and switch it on.
If the app was installed from an APK file rather than from Google Play, Android shows the switch as Controlled by Restricted Setting at first. Open Settings → Apps → NetLock RMM Agent App, tap ⋮, choose Allow restricted settings, confirm, and switch the service on again. The card shows this step on such installations.
On newer Android versions accessibility services cannot be switched on during a phone call. Set the service up before or after the call; the card says so as well.
Android may remind the user after some time that the service has access to the device. That is Android's own notice for services of this kind and can be confirmed.
The technician opens the viewer. The request reaches the phone as a notification, A technician wants to see and control this screen (or An operator wants to view this screen for a view session); the user taps it.
When the session may take input, the app asks first: Allow remote control? with the text "{name} wants to see your screen and operate this phone: tap, swipe and type." and the buttons Allow control, View only and Decline. The name is the technician's account name, set by the server. When the remote control service is not switched on yet, the question says that the technician will only see the screen. Without control the app asks only whether the screen may be shared.
Android then asks to start screen sharing. A control session always shares the entire screen. For a view session (also when the user chose View only), the user chooses what to share, and from Android 15 the prompt preselects A single app: the viewer then shows only that app, and the rest of the phone stays hidden.
If the user declines, nobody answers in time or the phone cannot ask its user, the viewer says so at once.
While the picture is shown, the toolbar above it offers:
View / Control: the switch turns on by itself once control is available and can be turned off for viewing only. When control is not available it is greyed out and its tooltip names the reason: the policy, the account, the user chose view only, the service is not enabled on the phone, or the app is out of date.
Back, Home, Recent apps, Notifications, Quick settings and Power menu (with a confirmation; choosing an entry there can end the session).
Long press: the next tap on the picture is held.
Keyboard and Paste clipboard: on Android 13 and later.
A chip with the input state, and the recording chip when the session is recorded.
With control on, the picture works like a finger: click or tap to tap, hold to long-press, drag to swipe or move, the mouse wheel scrolls, a right click is a long press. Typed text goes into the field that is selected on the phone; Enter, Backspace, Delete, Tab, the arrow keys, Home and End work as editing keys, and Ctrl+V pastes the operator's clipboard as text. When the phone is rotated, the next picture arrives in the new orientation; an input made on the old picture is dropped with a notice.
While control is active, the phone shows a red frame around the screen with the pill Remote control active and Stop, and the screen stays on. The notification of the session reads {name} can see and control this screen and has Stop sharing. Both Stop buttons end the whole session, the picture as well as the control; control cannot be stopped on its own. A finger on the screen interrupts what the technician is doing at that moment. Every end of the session (Stop on the phone, the viewer closing, the connection ending, the phone locking) ends the input at once.
Somebody has to be at the device for every session; Android allows no unattended start and cannot be unlocked remotely.
On recent Android versions locking the screen ends the session. The Power menu is offered, but no lock button.
Apps that protect their content (banking apps, password fields) appear black in the picture but still receive taps. The viewer shows a hint when the picture is black during control.
Some system dialogs (permission prompts, the package installer, parts of the settings) accept no input from accessibility services and cannot be operated remotely.
When Android reports during a control session that the phone no longer shares its entire screen (Android 14 and later), control pauses and the viewer says so until the whole screen is shared again.
One finger only: no pinch or multi-finger gestures. Nothing is copied from the phone to the operator.
An app version without remote control shows the screen for viewing only; the viewer says so.
A forced recording (A.7.1) covers Android sessions like any other; the viewer shows the recording chip. The audit log records Mobile screen view started or Mobile screen control started and each time the operator switches input on or off in the viewer. Single taps and typed text are not recorded in the audit log, and neither the server nor the app logs typed text or positions.
settings_enabled: access to the Settings group at all.
settings_remote_screen_enabled: access to this page's toggles and session browser.
devices_remote_audio_call: starting an audio call with the signed-in user of a Windows device (A.7.7); granted to the built-in Administrator role automatically.
devices_remote_control: opening a remote screen session in any viewer, starting and stopping a recording and viewing the remote clipboard. For the Relay App and the NetLock app it is checked on the account that owns the relay key, together with the key's Screen control switch. It also covers viewing and controlling Android devices from the web console (A.7.12); the server checks it again at least every minute while input flows.
devices_remote_file_browser: pasting files into a session (A.7.10), in every viewer, checked by the server.
The Notifications page at /manage_notifications is where every outbound alert leaves NetLock RMM. Five channels share the page as tabs (E mail, Microsoft Teams, Telegram, Ntfy.sh, and Webhook), and they all draw from the same event stream on the backend. This chapter documents each channel in depth, including the fields that differ between them, the test action, and the permissions that gate add, edit, delete, and test per channel.
Each channel manages its own list of recipients. A channel does not subscribe to a global recipient list: an email address you add on the Email tab does nothing on the Telegram tab, and vice versa. Add the same inbox to every channel you want it to receive alerts on.
Every recipient record on every channel carries a Severity dropdown with five options: Any, Critical, High, Moderate, and Low. The match is exact, not a threshold, and does not escalate. A recipient set to High receives High events only, not Critical ones. Only Any crosses severities and delivers events of every severity. To send two specific severities to the same destination without sending all of them, add that recipient once per severity, or use Any. Filtering happens on send, so a setting change affects future events only. Events already dispatched are not re-evaluated.
Every recipient record has two side-by-side lists, Tenants on the left and Selected tenants on the right, with a drag-drop control between them. Drag a tenant into Selected tenants to scope the recipient to that tenant. Leave Selected tenants empty to receive events from every tenant.
An operator only ever works with tenants they can see. If your role is restricted to one tenant, the Tenants list shows that one tenant and that is the only scope you can assign; administrators with wider access see every tenant and can drag any combination across.
Every channel has a toggle labelled Uptime Monitoring on every recipient record. The tooltip reads "If 'Disconnection Alert' is enabled in the device overview, the event is forwarded." If the per-device Disconnection Alert flag (see Chapter 3.3) is on, device-uptime events will reach this recipient when the toggle here is also on. With the toggle off, uptime events bypass this recipient even if disconnection alerts are enabled on the device.
The E mail tab is the first tab on the page. Two things live here: a single global SMTP configuration for the entire deployment, and a list of per-recipient email records.
Click SMTP settings on the Email tab toolbar to open the SMTP settings dialog. Exactly one SMTP configuration exists per deployment; editing it replaces the previous configuration for every email recipient.
Fields in the dialog:
Server: SMTP hostname.
Port: SMTP port.
SSL/TLS: checkbox. Tick if the server requires TLS.
Username: SMTP authentication username. Some providers accept an email address here; others accept a distinct mailbox name.
Password: SMTP password, with a visibility toggle next to the input.
From address: sender address. This field is shown only when Username is not itself a valid email address, because some providers require an explicit From when the login name is not a mailbox.
To address: test-recipient address. Shown alongside From address under the same condition, and used only by the Test action.
Test: runs a live send. The Console sends a message with subject NetLock - Test Alert and body Test successful. to the To address (or to the first email recipient if the conditional fields are not shown). A snackbar reports Test successful. on pass or Test failed: <error> on failure.
The dialog's Confirm action is gated behind a successful test: you can save the configuration only after Test has passed in this dialog.
Tip: For providers that require app-specific passwords (Microsoft 365 with security defaults, Google Workspace with 2-Step Verification, some business ISPs), generate the app password first, paste it into Password, and leave Username as the full email address. The From address and To address extra fields should stay hidden for these providers.
The recipient table on the Email tab is where individuals and mailing lists get added. Add, Edit, and Delete row actions manage entries; the dialogs behind them all share the same fields:
E mail: recipient address.
Description: free text. Useful for listing a role ("On-call NOC engineer") rather than a person, so the row survives personnel changes.
Severity: one of Any, Critical, High, Moderate, Low.
Multiple recipients are supported. The UI sets no cap; the practical limit is how many addresses your SMTP provider is willing to accept before rate-limiting you.
The per-recipient Test action is on the row itself. It reuses the global SMTP configuration to send the same NetLock - Test Alert message but to the recipient's address rather than to the To address field. Use this after adding a new recipient to confirm delivery reaches them specifically.
The Microsoft Teams tab hosts a list of webhook connectors. Unlike Email, the tab has no global configuration dialog. Each Teams channel you want to post to is its own connector row.
Microsoft retired the classic Office 365 connectors in May 2026. Teams channels do not offer a connector configuration any more, and webhook.office.com URLs do not work. A channel takes webhook posts through the Workflows app instead: a Power Automate flow that starts with a webhook trigger and posts what it receives into the channel. H.10 walks through creating one.
Fields per connector:
Connector Name: identifying name. Shown in test payloads and on notifications so recipients can tell which connector fired. Pick a name that describes the audience (NOC channel, Finance alerts) rather than the technology.
Connector-Webhook-URL: the URL the webhook trigger issued. Once saved, the value is masked in the table view and can be revealed only in the Edit dialog. The URL carries the binding to the flow along with its own signature, so regenerating it in Teams breaks the connector until the new URL is pasted over the old one.
Payload format: the shape of the body that is POSTed to that URL. Three options, described below.
A Workflows webhook and a classic connector do not read the same body, and two flows built on the same trigger can disagree about what they expect. Payload format decides which body NetLock RMM sends:
Plain text (legacy connector): {"text": "…"}, the body the classic connector read. Teams does not accept it, but many other services do: Mattermost, Rocket.Chat, Google Chat and receivers of your own take a webhook URL and read a single text field.
Adaptive Card (Workflows webhook): the message envelope a webhook trigger expects, an object of type message whose attachments array holds one Adaptive Card. This is what a webhook created from the Workflows template needs, and the normal choice for a Teams channel.
Adaptive Card without envelope: the card on its own, starting at "type": "AdaptiveCard". A flow that hands the request body straight to its Post card in a chat or channel action needs this one, because that action accepts a bare card only.
The enveloped body has this shape; the body array carries the lines of the alert, and Adaptive Card without envelope sends the content object alone:
Connectors created before Payload format existed use Plain text (legacy connector). Switch such a Teams connector to the Adaptive Card format its flow needs (see the table below). A new connector opens with Adaptive Card (Workflows webhook) preselected.
Which option a Teams connector needs follows from how the flow behind the URL is built:
The flow behind the URL
Payload format
The Workflows template unchanged: it posts the card it finds in the request's attachments.
Adaptive Card (Workflows webhook)
A flow that passes the request body itself into Post card in a chat or channel.
Adaptive Card without envelope
No flow at all — the URL belongs to a service that reads a text field.
Plain text (legacy connector)
Over the Public API the field is payloadFormat, with the values legacyText, adaptiveCard, and adaptiveCardBare.
Note: A Workflows webhook posts as Flow bot. The display name and icon a classic connector could carry have no counterpart in Workflows, so every connector pointed at the same channel arrives under the same sender. Where it matters, let the Connector Name inside the message carry the distinction, or give each connector its own channel.
The row Test action sends a test message in the connector's Payload format and names the connector in it. A snackbar reports Successfully sent on pass or Failed sending: <error> on failure.
A pass means the webhook accepted the call, which is not the same as the message reaching the channel. The webhook answers before the flow runs, so a flow that is turned off, or one whose post action cannot read the body it was handed, still produces a successful test. Open the Teams channel and confirm the message is there; if it is not, the flow's run history in Teams names the step that failed.
The Telegram tab configures one or more bot-to-chat pairings. Each row represents a single Telegram bot posting into a single chat or group.
Fields per bot:
Bot Name: display name for this bot configuration. Used in test messages and snackbar feedback; does not have to match the name you gave the bot in BotFather.
Bot-Token: the Telegram Bot API token issued by BotFather. Password-masked in the table view; the dialog exposes a visibility toggle.
Chat-ID: target chat or group ID. Private chats have a numeric positive ID; groups have a negative ID; channels have a -100… ID. Password-masked.
Description: free text.
Severity: Any, Critical, High, Moderate, Low.
Uptime Monitoring: toggle.
Tenants / Selected tenants: drag-drop scope.
Multiple bots are supported. A common setup is one bot per region or per severity tier, each wired to a different chat.
The row Test action sends the text NetLock RMM Alert: Test.\nBot Name: <bot_name> to the configured Chat-ID using the configured Bot-Token. A snackbar reports Successfully sent on pass or Failed sending: <error> on failure.
Tip: A failed Telegram test often means that the bot has not been invited to the target group. Telegram bots cannot post into a group they are not a member of, even with a valid token and chat ID. Invite the bot first, then test.
The Ntfy.sh tab targets topics on ntfy.sh (or a self-hosted ntfy instance). Each row is one topic.
Fields per topic:
Topic Name: identifier and display name. Used in test messages and snackbar feedback.
Topic URL: the full ntfy URL for the topic. The public default looks like https://ntfy.sh/<topic>, but any ntfy-compatible URL works, including self-hosted instances. Password-masked in the table view.
Access Token: optional. When the topic requires authentication, paste a Bearer token here. The Console sends it as Authorization: Bearer <token> on every outgoing request. Leave blank for public topics. Password-masked.
Description: free text.
Severity: Any, Critical, High, Moderate, Low.
Uptime Monitoring: toggle.
Tenants / Selected tenants: drag-drop scope.
Multiple topics are supported. The usual pattern is one topic per on-call team or one topic per severity tier.
The row Test action POSTs the plain-text body NetLock RMM Alert: Test.\nTopic Name: <topic_name> to the Topic URL. A snackbar reports success or failure. Subscribers who have the ntfy app open with a subscription to the topic see the test notification arrive live.
Note: ntfy.sh delivers push messages and does not keep them as a record. A notification sent before a subscriber opens the app on a fresh device is normally not replayed. For audit, rely on Events in the Console (see Chapter 12) rather than on ntfy history.
The Webhook tab is the most flexible channel. Each row configures one outgoing HTTP call, with a freely edited request body and header set.
Fields per webhook:
Name: identifier. Shown in the recipients table and in snackbar feedback.
Description: free text.
Severity: Any, Critical, High, Moderate, Low.
Url: the target URL. Unlike the other password-style fields on this page, the URL is shown in the dialog in clear text so it can be reviewed and corrected without toggling visibility.
Method: HTTP verb. Dropdown with GET, POST, PUT, DELETE, PATCH.
Request Body: JSON template. Edited in a Monaco editor with syntax highlighting. Runtime substitution replaces placeholder tokens with event data just before the call is sent.
Request Headers: JSON object. Defaults to {"Content-Type": "application/json"}. Edited in a Monaco editor. Keys and values are sent as HTTP headers on every call.
Sign requests: off by default. When on, every request carries the header X-NetLock-Signature, computed over exactly the body it sends. Switching it on generates a secret and shows it once; Rotate secret in the Edit dialog replaces it at once. The header name is reserved and cannot be set under Request Headers. Slack, Microsoft Teams, Discord and ntfy ignore signatures. X.10 shows how a receiver verifies them.
Seven tokens are substituted into Request Body at send time:
Token
Replaced with
$netlock_tenant_name
Name of the tenant the event belongs to.
$netlock_location_name
Name of the location the event belongs to.
$netlock_device_name
Name of the device that produced the event.
$netlock_date
Timestamp of the event, formatted per the deployment's date/time format (see A.5).
$netlock_reported_by
Identifier of the subsystem or user that raised the event.
$netlock_event
Short event type label.
$netlock_description
Human-readable description of what happened.
Tokens are substituted literally. If your downstream system expects one of them to be wrapped in quotes for JSON validity, write the quotes into the template: "tenant": "$netlock_tenant_name" rather than "tenant": $netlock_tenant_name.
The Add / Edit dialog has a Test Webhook button; the row in the table also has a Test action. Both actions parse the stored JSON and validate the URL. If both are well-formed, they send the call with the configured method, headers, and body. Validation failures surface as Invalid webhook URL. or Invalid JSON in Request Body.. A successful HTTP call produces a snackbar Webhook test successful! Status: <code>; a failed call produces Webhook test failed. Status: <code>. The test passes when the receiver answers with a 2xx status. Any other status, a 4xx answer for example, fails it.
When maintenance mode is active (see A.2), none of the five channels fire. Maintenance mode applies to the whole installation, not to single tenants. The events are still written to the event stream and marked as read, so nothing is lost from the Console's history and they do not fire as a backlog when maintenance mode ends. What is suppressed is the outbound delivery. This applies equally to Email, Teams, Telegram, ntfy.sh, and Webhook. No channel can bypass maintenance mode.
A scheduled patch window with maintenance mode turned on keeps alerts for expected reboots away from operators and on-call channels. A genuine incident during the window is suppressed as well, so keep maintenance windows short.
Pick the one that matches the event source. "Send every ticket update to Slack" calls for a ticket webhook. "Alert us when a device has been offline for ten minutes" calls for a notification webhook on this page.
Every channel carries its own block of flags. A user without settings_enabled sees nothing in Settings; a user without settings_notifications_enabled sees no Notifications page at all; beyond that, each channel has independent add / test / edit / delete flags.
Flag
Gates
settings_enabled
Access to the Settings group.
settings_notifications_enabled
Access to /manage_notifications and its tabs.
settings_notifications_mail_enabled
Visibility of the E mail tab.
settings_notifications_mail_smtp
Access to the SMTP settings dialog (Email-only sub-flag).
settings_notifications_mail_add
Add a mail recipient.
settings_notifications_mail_test
Test a mail recipient.
settings_notifications_mail_edit
Edit a mail recipient.
settings_notifications_mail_delete
Delete a mail recipient.
settings_notifications_microsoft_teams_enabled
Visibility of the Microsoft Teams tab.
settings_notifications_microsoft_teams_add
Add a Teams connector.
settings_notifications_microsoft_teams_test
Test a Teams connector.
settings_notifications_microsoft_teams_edit
Edit a Teams connector.
settings_notifications_microsoft_teams_delete
Delete a Teams connector.
settings_notifications_telegram_enabled
Visibility of the Telegram tab.
settings_notifications_telegram_add
Add a Telegram bot.
settings_notifications_telegram_test
Test a Telegram bot.
settings_notifications_telegram_edit
Edit a Telegram bot.
settings_notifications_telegram_delete
Delete a Telegram bot.
settings_notifications_ntfysh_enabled
Visibility of the Ntfy.sh tab.
settings_notifications_ntfysh_add
Add a ntfy.sh topic.
settings_notifications_ntfysh_test
Test a ntfy.sh topic.
settings_notifications_ntfysh_edit
Edit a ntfy.sh topic.
settings_notifications_ntfysh_delete
Delete a ntfy.sh topic.
settings_notifications_webhook_enabled
Visibility of the Webhook tab.
settings_notifications_webhook_add
Add a webhook.
settings_notifications_webhook_test
Test a webhook.
settings_notifications_webhook_edit
Edit a webhook.
settings_notifications_webhook_delete
Delete a webhook.
The _smtp sub-flag on Email has no counterpart on the other channels. It exists because Email is the only channel with a single shared global configuration separate from the per-recipient records.
Payload format has no flag of its own either. It is a field on the connector record and follows the channel's add and edit flags like every other field in the dialog.
Self-hosted only: On cloud deployments the Logging page shows a standard "cloud team manages these" notice instead of the logging switches, the downloads and the file list, and the page is not listed in the navigation. Your hosted operations team owns log retention, rotation and review. The rest of this chapter describes the self-hosted experience.
The Logging page gives a self-hosted operator three things: a runtime switch to turn logging on or off for the Web Console and for the NetLock RMM server without a restart, a download of the log files of both as a ZIP package, and a diagnostics view of the Console process. Use it to find out why something went wrong a few minutes ago, and to hand log files to support without opening a shell on the host.
Where to find the page and who can open it:
The page is at /logging, not under /settings. You open it from Navigation → Logging in the main navigation, not from inside Settings.
The page needs the permission settings_protocols_enabled. In the role editor the switch is labelled System logs. See the Permission reference (X.2).
The Web Console Logging card carries an Enabled / Disabled switch and a status chip that reads Active or Inactive. The switch takes effect immediately for the Console process, without a restart. The value is also written to Logging:Custom:Enabled in the Console's appsettings.json, so it survives a restart. If the file cannot be written (for example a read-only mount), the switch still applies until the next restart and the page shows a warning that the setting could not be saved.
Turning logging off stops all Console logging from that moment on, including warnings and errors; files written so far stay as they are.
The Server Logging card switches the logging of the NetLock RMM server the same way. It lists every server the Console connects to: the address configured as remote server and the address configured as file server. When both addresses lead to the same server, which is the case for a standard installation and for the Docker setup, the card shows a single row labelled Remote and file server; when they lead to two separate server instances, each gets its own row.
Each row shows:
the label (Remote server, File server or Remote and file server) and the address;
the roles the server runs with (for example comm, update, trust, remote, notification, file, llm, relay);
an Enabled / Disabled switch with the Active / Inactive chip, showing the state the server itself reports;
The switch takes effect on the server immediately and is stored as Logging:Custom:Enabled in the server's own appsettings.json, so it is kept across a server restart. If the server cannot write its configuration file, the switch applies until the server restarts and the page shows a warning. Every switch is recorded in the audit log with the server address.
When a server cannot be asked, the row shows the reason instead of the switch:
could not be reached: the server is down, the address is wrong, or a firewall blocks the connection. The card waits at most a few seconds per server, the rest of the page stays usable.
rejected the request: the server did not accept the Console's credentials.
does not offer this function yet: the server runs an older version than the Console. Update the server to the version of the Console.
answered with an error: the server was reached but could not answer the request (the HTTP status is shown). Check the server's console output (docker logs on Docker) and try again with Refresh.
Split installations. If you run the server roles on several separate instances, the card only reaches the instances behind the remote server and the file server address. Switch any further instance (for example a dedicated communication instance) with Logging:Custom:Enabled in that instance's appsettings.json and restart it, as described in Changing a value in appsettings.json.
The appsettings.json files of the server and of the Web Console are stored encrypted. To change a value by hand, stop the service, replace the entire content of the file with your plain JSON configuration including the changed value, and start the service again; the file is encrypted again on start. On Docker, stop and start with sudo docker compose down and sudo docker compose up -d in /home/netlock.
Turning server logging off stops logging at all levels, including warnings and errors. The server still prints one line about the switch to its console output, so docker logs shows when logging was turned off and on.
Download logs in the toolbar downloads the Console's log files; Download server logs on a server row downloads the log files of that server. Both produce a ZIP archive with the same layout:
one entry per log file that exists (combined.log, debug.log, info.log, warning.log, error.log);
a manifest.txt with the creation time, the version, the machine name, whether logging is enabled, the log directory and the size of each file. The server package also names the server's roles.
The log files are never rotated by NetLock RMM, so combined.log in particular can grow large. A file above 25 MB is cut to its newest 25 MB, starting at a full line, and begins with a line that says so; the manifest marks it as truncated. A server prepares one package at a time. If a second request arrives while one is being built, the page asks you to try again in a moment.
Both downloads are recorded in the audit log.
A log package contains diagnostic data of the server or the Console, such as device identifiers and connection details. Treat it as confidential and share it only with a support contact you trust; the manifest.txt in the package says the same.
The Diagnostics section shows memory and runtime figures of the Web Console process: process memory, garbage collector, thread pool, timers, Blazor circuits by page and by account, active sign-in sessions and the heavy pages and dialogs that are still held in memory. The values are read when the page opens and when you press its Refresh; there is no automatic update. Full GC runs a full garbage collection after a confirmation and shows the heap before and after. All sessions of the Console pause for a few seconds while it runs, and the run is recorded in the audit log.
The diagnostics section is shown on cloud deployments as well.
Trace a failing agent operation. Switch server logging on in the Server Logging card, reproduce the failure, then use Download server logs and search combined.log (or error.log) for the device name or hostname. Switch logging back off when done to keep disk use down.
Triage a user-reported Console error. Use Download logs, open error.log and search for whatever identifier the user gave you (username, page, time). If nothing matches, search combined.log, because some errors appear as a warning first.
Collect logs for a support ticket. Download both packages, the Console's and the server's, and attach them. The manifests carry the versions and the time the packages were made; add the time window of the problem to the ticket.
No live viewer. The page lists and downloads log files; it does not display their content. Open the files from the downloaded package in a text editor.
No log rotation or retention. NetLock RMM does not rotate or delete its log files. Switch logging off when you do not need it, and remove or archive old log files on the host if disk space matters.
No log export to external SIEM. For SIEM forwarding, wire a collector to the log directories directly on each host.
No verbosity setting. The level of detail of the server log is set with Logging:Custom:VerbosityLevel in the server's appsettings.json (see Changing a value in appsettings.json) and takes effect after a restart of the server.
No remote-device logs. This page covers the Web Console and the NetLock RMM server only. Agent-side logs are collected on the device (see Debug an agent).
settings_enabled: access to the Settings permission group (the page is under Settings in the permission tree even though its URL is /logging).
settings_protocols_enabled: access to the Logging page itself: both logging switches, both downloads and the diagnostics. In the role editor the switch is labelled System logs.
Restrict Console access by IP address or country, set how long Console sign-ins stay valid, limit the request rate of the agents and block misbehaving devices
/settings/security (tabs IP whitelist, Country restriction, Sessions, Rate limiting)
If the setting you want does not appear in this table or under Settings in the navigation, it is not configurable in the Console. Two cases to be aware of:
Connection strings (MySQL, File Server, Remote Server URLs). Configured in appsettings.json on the Console host. See A.1 for the read-only view.
Password expiry and MFA enforcement. There is no deployment-wide setting. Two-factor authentication is switched on per account, see Chapter 14 — Users & Roles. How long sign-ins stay valid is set on the Sessions tab of /settings/security.
The AI / LLM Settings page at /settings/ai is where a deployment operator turns AI on, decides where inference happens, and controls where AI appears in the product.
Two model sources are available, and the choice between them is made on this page: the managed NetLock AI (hosted on IONOS AI Hub), or an OpenAI-compatible provider you run or subscribe to yourself. The second option uses the OpenAI chat-completions API, so any provider that offers it (OpenAI itself, Anthropic via its OpenAI-compatible endpoint, Ollama, LM Studio, LocalAI and others) works with the same fields.
Enable AI Features sits at the top of the page. It decides whether any AI feature in the product is active.
When off, all AI features in NetLock RMM are disabled. The AI Chat page is unavailable, AI buttons inside Scripts and Remote Shell are hidden, the Analyze with AI button on Event Details is gone, the AI Assistants inside the Add / Edit Sensor and Add / Edit Job dialogs are hidden, and the end-user chat in the agent tray is refused by the server. Everything else in the product keeps working.
When on, the per-feature toggles below decide which AI features are active (see A.11.4).
Save stores the change. Switching the master toggle does not change the model selection or the provider configuration below; when you turn AI off and back on later, the settings you saved last apply again.
Tip: If you are not sure whether AI is the right fit for your deployment, turn the master toggle on, decide on a model source, and leave every per-feature toggle at its default. Individual operators can then explore AI Chat (Chapter 13) before you roll out the AI buttons on the other pages.
The Model Selection block is a two-option radio group directly below the master toggle. It decides where every AI request from this deployment is processed, which makes it the most important setting for a compliance review.
The default for a new deployment. Requests do not go to a provider of yours: the Web Console (and, for the end-user tray chat, the server) sends them to NetLock, which forwards them to its AI provider, the IONOS AI Hub, and streams the answer back along the same path. Authentication is the deployment's Members Portal API key (the same key the Licensing page holds); no provider credentials of your own are involved, and the provider fields described in A.11.3 are hidden because they do not apply.
In this mode the managed service sets the request parameters. The model is the one the managed service runs and cannot be chosen here; the sampling temperature is always 0; and the completion length is capped at 4 096 tokens, or at the remaining token budget of the deployment if that is lower.
Consumption counts against the token budget included with your membership. The page shows it under NetLock AI Usage as a progress bar with <used> / <max> tokens (<remaining> remaining). The same figure appears on the NetLock AI card under Settings → Licensing (A.1). If the membership does not include managed AI, the block reads "NetLock AI is not enabled for your membership." and no request can be sent in this mode.
Every request goes directly from the Web Console (and, for the end-user tray chat, from the server) to the provider you configure in A.11.3. Nothing is sent to NetLock, and NetLock cannot see the content. Model, token limit and temperature are taken from your fields and sent unchanged.
This is the only mode that keeps AI content inside your own infrastructure. If your compliance rules require that prompts, script bodies, event data, shell output, or ticket content never leave your network, select Use my own model and point it at a model you host yourself.
Note: Switching between the two modes does not clear anything. The provider fields keep their saved values while the managed mode is selected, and the managed mode is available again after you switch away from your own model.
These fields appear when Use my own model is selected, and every AI call the deployment makes in that mode uses them.
Provider Name: a free-text label for your own overview. It is not rendered on any other page and is not sent to the provider. To confirm which endpoint is actually in use, read the active-endpoint line on this page rather than this field.
API Base URL: the root URL the request path is appended to. NetLock RMM appends /chat/completions and sends the result exactly as it stands; it never adds, removes, or corrects a path segment. Enter the OpenAI-compatible root including the /v1 segment where the provider uses one; for Ollama that is http://<host>:11434/v1, not http://<host>:11434/. The provider templates below fill this in correctly; if you type the URL by hand, check it yourself. The helper text on the field reads e.g., https://api.openai.com/v1.
API Key: the secret sent in the Authorization: Bearer header. Password-masked input. Leave it empty for a local provider that does not require authentication: with an empty field no Authorization header is sent at all, which is what Ollama, LM Studio, and comparable runtimes expect.
Model: the model identifier the provider expects in the chat-completions call. The helper text reads e.g., gpt-4o, claude-sonnet-4-20250514, llama3. If you configure an identifier the provider does not recognise, Test Connection shows the provider's error message.
Max Tokens: the maximum response length. Numeric input, range 256 to 128000. The value should match what your chosen model and provider accept. A local model with a 4 000-token context window will not honour a 128000 setting. The default produced by the provider templates is 4096.
Send temperature: toggle. When on, a Temperature slider appears with range 0.0 to 2.0 in steps of 0.1 and the value is sent with every request. Lower values produce more predictable output (at 0.0 the model always picks the most likely next word); higher values produce more varied output. 0.7 is a reasonable default for script analysis and event commentary, which is what the provider templates set. Turn the toggle off for models that reject requests that carry a temperature; the parameter is then not sent at all.
Four one-click templates populate the fields with sensible defaults. Clicking a template overwrites Provider Name, API Base URL, and Model, resets Max Tokens to 4096 and Temperature to 0.7 with Send temperature on, and leaves API Key as it is. A local runtime does not need a key.
Template
API Base URL
Model
OpenAI
https://api.openai.com/v1
gpt-4o
Anthropic
https://api.anthropic.com/v1
claude-sonnet-4-20250514
Ollama
http://localhost:11434/v1
llama3
LM Studio
http://localhost:1234/v1
local-model
For a provider that is not listed above, for example LocalAI or a self-hosted vLLM, enter its API Base URL and Model manually. There is no "Custom" template; the four templates only prefill the fields.
Note: For Ollama and LM Studio, the template URL uses localhost. That address points to the host running the Console, not to your workstation and not to the device running the agent. If you run a local model on a different machine, replace localhost with the reachable hostname or IP. If you run the Console in a container, make sure the container can reach the host's loopback if that is where the model lives.
The Test Connection button sends a minimal probe with the current field values. While the call runs, a spinner labelled Testing... is shown. The result appears below the button, either as a success alert or as an error alert that quotes the provider's error text.
Use Test Connection every time you change API Base URL, API Key, or Model. Save only after the test succeeds. An untested configuration can make every AI action fail.
Ten toggles decide which AI features are active in the rest of the product. All of them are on by default. They can only restrict what the master toggle allows: a feature toggle that is on has no effect while Enable AI Features is off.
Toggle
Where the surface appears
Script Analysis
The AI Assistant in the Add / Edit Script dialogs. See Chapter 8.1.
Remote Shell
The AI actions inside the Remote Shell dialog and inside Bulk Remote Shell. See Chapter 3.5.
Event Analysis
The Analyze with AI button on the Event Details dialog, both on the device Events tab and on the Events page. See Chapter 12.2.
Sensor & Job Creation
The AI Assistants inside the Add / Edit Sensor dialog and the Add Job dialog. See Chapter 8.2 and Chapter 8.3.
Event Log Analysis
The AI buttons in the Remote Event Log viewer and on an event-log entry's details. See Chapter 3.3.
Ticket Analysis
The AI actions in the ticket detail dialog. See Chapter 10.
Audit Analysis
The AI analyze action on the Audit page. See Chapter 12.3.
Automations Assistant
The AI Assistant on the Automations page and in the Add / Edit Automation dialogs. See Chapter 5.
AI Chat
The operator AI Chat page, the slide-in chat panel, and the chat button in the top bar. See Chapter 13.
End-user Chat
The end-user AI chat in the agent's tray icon. This one is enforced on the server: with the toggle off the tray's requests are refused and the menu entry disappears on the tray's next sign-in. The tray entry additionally depends on the AI chat switch in the tray-icon policy, which stays an independent second switch. See Chapter 13.6.
Turning a toggle off hides the AI element wherever it appears; the feature it belongs to keeps working. With Script Analysis off, the Scripts editor works normally, only without the AI Assistant.
The toggles are deployment-wide, not per user. Use them to decide which of your data may reach the model at all. Per-user permissions cannot do that, because they describe what a person may do, not what the model sees.
A common rollout is to leave AI Chat on for all operators (it is the cheapest feature to evaluate), enable Script Analysis and Event Analysis once the team is comfortable, and keep Ticket Analysis and End-user Chat off until the content these features send has been reviewed.
The Web Console contains the product documentation of its own release (the chapters of this manual as of the build) and uses it to answer questions about NetLock RMM. When an operator asks the AI Chat how a page, a setting, a policy or an agent behaves, the console picks the documentation sections that match the question and sends them to the model together with the question. The model is instructed to answer from those sections, to quote page and setting names as written there, and to say when the documentation does not cover a question instead of guessing. The answer ends with a Sources line that links the documentation pages the model cited.
Two fields under Product documentation control this:
Use the product documentation to answer questions about NetLock RMM: toggle, default on. When off, the chat sends the question without documentation sections and the model answers from its own knowledge.
Documentation excerpt budget (characters): numeric, range 2000 to 32000, default 8000. The maximum number of documentation characters the console adds to one request. A section that does not fit the remaining budget is left out.
A read-only line below the fields names the documentation snapshot the console carries: the product version, the number of articles and sections, and the revision and date of the documentation it was built from. When the line reports that no snapshot was found, the installation was built without the documentation and answers come from the model alone.
Which chats use it:
The AI Chat page and the slide-in chat panel opened without a context always run the lookup and send up to the configured budget.
The context chats (the assistants in the Script, Remote Shell, Event, Event Log, Audit, Sensor, Job, Automation and Report Builder dialogs) run the lookup as well, but only add documentation when the question clearly matches a documented topic, and with at most 3,000 characters, because those chats already carry the script, log or schema they were opened for.
The ticket AI actions and the end-user chat in the agent tray never add documentation.
The screenshots of this manual ship with the console as well. When a documentation section handed to the model carries a screenshot of the page or dialog in question, the answer can show it below the step it illustrates. The image is served by the Web Console itself from the bundled copy and opens in full size in a new tab; nothing is loaded from the documentation site or any other external source. Images from anywhere else are never rendered in an answer, only their description text appears.
The lookup runs inside the Web Console. Nothing is sent anywhere except the request to the configured model, which carries the matching documentation sections alongside the question. On the managed NetLock AI a grounded question adds roughly 2,000 tokens, which count against the membership budget like any other prompt text; on your own model it adds the same amount to the prompt the provider sees.
Note: Small local models with a short context window cannot hold the default budget together with the conversation. Ollama, for example, truncates a prompt that exceeds the model's context length from the start, which drops the instructions and the documentation sections before the question. The answer is then not based on the documentation, although everything is configured. Either lower the budget to 2000 or 3000, or raise the model's context window (for Ollama OLLAMA_CONTEXT_LENGTH=16384 or num_ctx in a Modelfile) and keep Max Tokens well below it. A temperature of 0.2 to 0.4 gives the most faithful answers on your own model.
AI conversations started from the AI Chat page (see Chapter 13) are stored in the database. Two fields control how long they are retained.
Auto-cleanup chat history: toggle. When on, conversations older than the retention window are deleted on a rolling schedule. When off, conversations are kept until manually deleted from the AI Chat page.
Keep chat history for X days: numeric, range 1 to 9999. Disabled when the auto-cleanup toggle is off.
Turning the toggle off stops the cleanup at once. Turning it on resumes it with the next scheduled run. Clearing the retention window does not restore conversations that were already deleted; deleted conversations cannot be recovered.
Warning: Chat history can contain sensitive information operators pasted into the chat (credentials, internal hostnames, PII). If your compliance rules require it, set a short retention window (7 or 14 days) from day one. Longer windows make sense if you use older conversations for training or coaching.
After changing settings on this page, check the following:
Read the active-endpoint line on the page. It names the resolved mode and the target URL as saved, and is the reliable answer to where the deployment sends its prompts.
On Use my own model, run Test Connection. Only a success alert confirms that the provider is reachable and that URL, key and model work together. On Use NetLock AI (managed), check that NetLock AI Usage shows a budget rather than the "not enabled for your membership" notice.
Open AI Chat (Chapter 13) and ask a one-line question. Confirm a reply arrives within a sensible time for the model source you chose.
Open a page with an AI feature whose toggle you enabled (the Scripts editor for Script Analysis, Event Details for Event Analysis) and confirm the AI button appears and produces output.
With Product documentation on, ask AI Chat a question about the product ("Which permission is needed to delete a policy?"). The answer should carry citations such as [1] and end with a Sources line; if it does not, see A.11.5 and the troubleshooting entry AI answers are not grounded.
If step 2 passes but step 3 fails, the endpoint is reachable but the Chat-specific prompt is not being answered; on your own model, check Max Tokens against the model's context window. If step 2 passes but step 4 fails, the per-feature toggle is off or the operator's role lacks the relevant feature-area permission.
Three content builders of the Console work with SQL: the Report Builder, the dashboard Panel Builder and the Custom Field Builder. Which parts of the MySQL schema they can read is decided by one setting, Settings → SQL access. The separate Ticket System Settings page is sometimes grouped with these, but works differently; it is covered at the end.
Route:/settings/sql-access. Self-hosted only; on cloud instances the menu entry is hidden and the page states that SQL access is not available.
SQL that users write themselves and SQL that the query builders generate runs only as a dedicated MySQL user. The administrator creates that user in MySQL and enters user name and password on this page. The user's MySQL grants are the boundary of what such SQL can read; the query builders list exactly the tables and columns it can read.
The page shows:
the status: Active, Not configured, or Off with the reason the user was refused;
the MySQL user name and the Password field. The password is stored encrypted with the local encryption key and never shown again; leaving the field empty keeps the stored password while the user name is unchanged;
ready-to-copy CREATE USER and per-table GRANT SELECT statements generated for the tables of this instance, without the tables and columns that hold credentials, and a link to the how-to.
Saving with an empty user name removes the configuration after a confirmation; the user stays in MySQL.
The console accepts a user only if it holds nothing but SELECT on the NetLock database (whole database, single tables or column grants) plus USAGE. The check runs on save and again every 15 minutes in the Web Console and the server; if the grants are widened later, SQL access switches off until they are fixed. The step-by-step setup, the statements and the refusal reasons are in Set up SQL access for reports, dashboards and custom fields.
Permission:settings_sql_access.
Note: After the update to 3.3.0.11, accounts and custom roles that held settings_reports_enabled or settings_dashboards_enabled hold settings_sql_access.
SQL panels on dashboards run as the SQL access user. This covers statements typed directly and statements generated by the Panel Builder's query builder, including the preview. Without SQL access they are locked with a notice, also in the TV view; catalog widget panels are not affected. Creating and changing SQL panels needs dashboard_sql_panels and assignment to every tenant. See Chapter 2.
Custom SQL in report widgets and text parameters runs as the SQL access user. The built-in report templates work without it as long as their statements stay unchanged, also in duplicates, imports and catalog templates. Without SQL access, widgets with custom SQL show SQL access not configured, and saving or importing a template with custom SQL is refused. See Chapter 11.3.
The page holds the section Global values: the custom field values every device inherits unless a group, location, tenant or the device itself sets one (see Chapter 8.4). Custom fields with the SQL Select data source run as the SQL access user; without it they show (SQL access not configured) on the device page.
The Ticket System has its own settings page at /settings/ticket-system with a different layout: module toggle, ticket number prefix, blocked file extensions, and Labels / Types / SLA tabs. It is documented with the rest of the ticket module in Chapter 10.2 and the sub-sections that follow.
To only enable the module, switch on Ticket System Enabled on the General tab at /settings/ticket-system.
Saved SQL is checked when it runs. Every custom statement runs as the SQL access user, so narrowing that user's grants takes effect at once for existing reports, panels and custom fields. A statement that reads a table or column the user can no longer read fails with MySQL's access error.
New tables after an update. With per-table grants, tables added by a later update are not readable until you run the GRANT statements again. Copy them from Settings → SQL access after an update.
Built-in report statements after an update. When a release changes a built-in statement, a duplicate made from the older version needs SQL access.
With endpoint protection, an anchored device runs a definition (the policy, its jobs and sensors, App Hub apps, software deployments) only after a phone you registered has signed it. The server and the Console store and transport the definitions, but they cannot sign them. A change made in the Console reaches anchored devices once somebody with a registered phone has reviewed and confirmed it.
The same applies to remote actions. A remote shell, a file transfer, a screen control session, a tunnel or an agent uninstall on an anchored device needs a grant the phone signs for exactly that action on exactly those devices, or a work session that covers a class of actions on a device list for a few hours. A.13.4 describes the definitions, A.13.9 the grants and work sessions, A.13.10 screen control from the Relay App and the NetLock app, A.13.11 Android phones and tablets.
Note: Endpoint protection is opt-in per device. A device installed without an anchor is not affected by signatures. Without a trust line, the Console shows only the settings page of endpoint protection.
A trust line lists the signer phones and the recovery key. Every change to it is a new keychain version, signed by an existing signer with the keychain role or by the recovery key. Normally an installation has exactly one trust line.
The anchor is a 64-character value that identifies the trust line. It is the only value a device needs, and the device receives it at installation time. With it the device knows which keys may sign what.
A signer is a phone running the NetLock app with a key in its hardware keystore. The key signs only after the fingerprint or face check. The keychain lists each key with its roles: definitions (sign policies, jobs, sensors and the other definitions), grants (approve remote actions and work sessions) and keychain (add, remove or re-role signers). The recovery key is created once during setup, shown as QR code and text, and signs keychain documents only; it restores access when every phone is lost.
A definition is one version of a policy, job, sensor, automation, App Hub app, software deployment or NetMesh link. The phone signs it, and an anchored device runs it only with a valid signature.
The Console never shows an anchor as something to copy. The anchor comes out of the app that created it. The Console only displays which anchors devices report back, so you can compare the first characters after a rollout.
Setup happens entirely on the phone, with the NetLock app for Android. The account needs the permission ztep_signer_own to register a phone and settings_endpoint_protection_manage to upload the trust line.
Open Endpoint protection in the app and choose Set up. Give the trust line a label (the installation or company name is a good choice).
The app creates the signer key in the phone's keystore and registers it with the Console. Keep the phone's screen lock on; the key does not sign without it.
The app shows the recovery key once, as QR code and as text. Print it or store it in a password safe that is not reachable from the server. It is not shown again.
Choose the protection level: Productive (default) requires a grant for everything that can take over a device (scripts and remote shells, writing files, system changes, screen control, backstage and elevation, tunnels and NetMesh links, application and agent uninstalls, sensor live tests) and allows work sessions of up to eight hours on up to 500 devices; Strict requires a grant for every class, including power actions, patch runs, reading files, the BitLocker key resync and audio calls, and allows no work sessions. The protection level is part of the keychain and can be changed later with a new keychain version.
The app creates the trust line and shows the anchor in groups of four characters and offers Copy and Share. The copied value is the plain 64-character string the installer expects.
The app uploads the trust line to the Console. The Console then lists the trust line under Settings → Endpoint protection.
To add a second phone, start on that phone: it registers its key, shows the key as QR code, and an existing keychain signer scans it and signs the next keychain version. The Console transports the new version to the devices with their next policy sync.
GPO, Intune and scripted rollouts pass the parameter. The installer writes ztep/anchor.json next to the agent, readable only by SYSTEM and administrators (root on Linux and macOS). The agent update path never touches the file: an anchored device stays anchored through agent updates, an unanchored device never becomes anchored by itself.
Devices that were installed earlier are anchored by reinstalling them with the parameter or by running the installer in fix mode with it. Devices cannot be anchored remotely.
From the app. The anchor page of the NetLock app shows the installation commands per platform with the anchor already in them (PowerShell and command prompt for Windows, a shell one-liner for Linux and macOS), the repair commands for devices that are already installed, the files the anchor is stored in, and the bare parameter for your own script, GPO or Intune. The commands are the ones of the Agent installers page with --ztep-anchor appended. The app builds the commands on the phone.
The page needs the permission agent_installers_enabled next to the endpoint protection permission, and the location must have been opened once on the Agent installers page so its installers exist. The page also carries a fixed warning: never hand out the anchor through the Console, in a policy, a job, a script or a remote shell.
The installer writes the anchor into two files, one for the Comm agent and one for the Remote agent, readable only by administrators or root:
The repair command for an installed device is the installer in fix mode with the path of the Comm agent's server_config.json of the platform (…\Comm Agent\server_config.json below the same base directory) and the parameter; the app shows it ready to paste for every platform. The device keeps its registration, the installer refreshes the agent files and writes the anchor. Run it from your own deployment tool, a GPO, Intune or a local session, not through the remote shell or a job of the Console.
After the first sync the device reports its anchor, the keychain version it runs and its state. The device details show one line Endpoint protection in the General tab; the settings page counts devices per line and state. When the app uploads a new keychain version, devices anchored to that line receive it with their next contact (online devices right away).
Once a trust line exists, the Console shows a Signature column in the lists of jobs, sensors, policies, automations, App Hub apps, software deployments and NetMesh links, with three states:
State
Meaning
Signed
The stored content matches the last signature. Anchored devices run it.
Changed since signature
The definition was saved after it was last signed. Anchored devices keep running the signed version until it is signed again; unanchored devices already run the new one.
Unsigned
Never signed. Anchored devices do not run it.
Three ways lead to a signature:
Save and sign in the dialogs of jobs, sensors, automations and App Hub apps and on the policy settings page. The definition is saved as usual, then the waiting dialog opens.
Sign in the actions column of a list entry.
Sign all pending above a list (every unsigned or changed entry of that list) and Sign all on the settings page (every kind at once).
The waiting dialog says Confirm in the NetLock app. The phone receives a push notification. Without push, the app lists open requests while it is in the foreground, and the QR code in the dialog opens the request directly. If the app knows the Console under another address, it asks before it loads the request. The app shows every document of the request with name, kind, version and the script text, one fingerprint signs them all, and the Console dialog closes as soon as the signatures have arrived. The devices receive the new versions with their next sync; the Console triggers that sync for online devices right away.
Who may ask for a signature follows the existing permissions: whoever may edit a job may ask for its signature. Who may sign is decided by the keychain alone. If the account that asks has a registered phone listed in the keychain with the definitions role, the request goes to that phone. Otherwise it goes to every account whose phone is such a signer, and the first signature wins. The dialog names the people it is waiting for.
Signing follows these rules:
Jobs and sensors are signed in their template form: variables such as {{field.api_key}} stay references. Changing the script needs a new signature; changing a custom field value does not.
A policy document lists the signed versions of its jobs, sensors and apps. Signing a job or sensor therefore re-signs the policies and automations that reference it in the same request: the item comes first, the lists follow, one confirmation on the phone covers them all. A list that was never signed is not pulled in.
A definition signed by a key the keychain no longer accepts (removed, revoked or without the definitions role after a keychain change) shows Signer key removed and counts as pending; Sign all pending re-signs it with a current key.
Deleting a job, sensor, app, automation, deployment or link marks its signatures as superseded and the policies and automations that listed it as Changed since signature. The delete dialogs of jobs, sensors and automations additionally offer Also revoke the signed versions on the phone: a registered phone signs a revocation, and anchored devices refuse the deleted definition with their next sync instead of waiting for the next policy signature.
Editing a script that jobs or sensors embed marks those jobs and sensors as changed.
An App Hub app of the source File from the file server is signed with its file name, the SHA-512 of the file, every argument field and the uninstall mode; the app shows them in the request, so the signer can compare the SHA-512 with the hash of a known copy of the installer (Get-FileHash -Algorithm SHA512, sha512sum, shasum -a 512). The device starts the file only when the downloaded bytes have exactly this SHA-512; a different file is refused with file_hash_mismatch.
A software deployment hands the app its items as one text, so packages, files, SHA-512 values, parameters and every install, uninstall and detection script are visible before signing; an item changed after signing is refused with payload_hash_mismatch.
A request for a definition that is saved again before the phone answered is marked superseded; sign again after the last save.
Anchored devices do not run SNMP sensors that discovery creates automatically.
The device enforces with an empty keychain: no signed definition can verify, so the policy is empty (no jobs, sensors or apps). Inventory and sync keep running. An event of type 14 is written once an hour.
Anchored, active
the keychain of the trust line verified
Signed definitions run, unsigned ones are removed from the policy and reported with event type 14.
Chain break
the delivered keychain does not continue the trusted chain
The last valid chain stays in force, event type 14 names the reason.
Event type 14, Endpoint protection, carries the reason the agent decided on (missing_authorization, payload_hash_mismatch, not_in_policy, version_rollback, keychain_missing, …). The policy's agent settings have a block Endpoint protection that switches these notifications on and chooses the channels, like the antivirus notifications.
Two reasons are written on every Windows device, anchored or not: script_manifest_mismatch and script_missing. They concern the PowerShell scripts included with NetLock RMM (Windows Update, WSUS, Storage Spaces, DHCP, Terminal Server, Hyper-V and Exchange sensors), which ship as code-signed files under Program Files\0x101 Cyber Security\NetLock RMM\Comm Agent\Scripts. A script that was changed or removed is not started, and the event names the script. Reinstalling the agent (fix) restores the files.
the trust lines: label of the trust line, the anchor prefix as reported by devices (nothing while no device reports it), keychain version, the signers with their roles, devices per state and the number of unsigned definitions with Sign all;
the number of devices that are not anchored;
my signer devices: the phones registered for the signed-in account, whether the keychain lists them, when they were last used, and Disable. Disabling stops the phone from answering requests for this account; removing it from the keychain is a separate keychain step in the app;
the setup hints: the app version that carries the signer, the installer parameter, and the reminder that the anchor is taken from the app only;
the active work sessions: the signed-in account's own, every account's with settings_endpoint_protection_manage, each with account, trust line, device count, classes and expiry, and End with signature or End on the console only (see A.13.9).
Endpoint protection is only as strong as the handling of the keys. Follow these rules:
Sign every definition before you anchor devices. Use Sign all on the settings page, then roll the anchor out in steps, starting with a handful of pilot devices. Watch event type 14 on them before you widen the rollout.
Keep the recovery key offline. It is the only way to add a new phone when every registered phone is gone. It must not be stored on the server, in the Console or in a share the server can reach.
Compare the anchor. After the rollout, compare the first characters shown by the devices with the value the app displays. They must match; a difference means the installer received a different value.
Read before you sign. The app shows the script text and the document. A request you did not trigger, or one that lists a device or a change you do not recognise, is rejected on the phone.
Phones are personal. One account, one or more of its own phones. Shared accounts defeat the audit trail; the signed document records which key signed.
Lost or replaced phone: disable the device on the settings page and remove its key from the keychain with another signer or the recovery key. Until the keychain version without the key has reached the devices, the key is still trusted by them.
Several trust lines are possible (a second anchor with its own signers and protection level, for example for a high-security group or a customer who keeps their own phone). The Console lists them side by side; definitions are signed per line.
Leaving endpoint protection means reinstalling the device without the anchor (a clean installation without the parameter) or deleting both anchor files locally as administrator or root. Running the installer in fix mode without the parameter keeps the anchor. Nothing on the server can switch it off remotely.
Use the current version of the NetLock app. Requests of the kinds grant and session show the action class, the devices with their names, the tenant and location, the requester, the validity and the details (the script, the user a shell runs as, the target of a tunnel); a session request additionally lists the classes it covers, the device count and the duration.
On an anchored device the actions of a class the keychain signs need an approval as well. The Console asks a registered phone for a grant: a signed approval of one action class for the listed devices, the requesting account and a limited time. Before you approve, the phone shows the action, the devices, the requester, the validity and the details (script, shell user, tunnel target). Anchored devices refuse anything that differs and write event type 14.
Which classes need a grant follows the protection level of the trust line. Productive protects everything that can take over a device: scripts and remote shells, writing files, system changes (services, tasks, registry writes, clearing event logs), screen control, backstage and elevation, tunnels and NetMesh links, application and agent uninstalls, sensor live tests. Viewing a screen is part of screen control and needs the grant like controlling it. Strict also asks for power actions (restart, shutdown, lock, log off), patch runs, reading files (including the disk usage analyzer), the BitLocker key resync and audio calls, and allows no work sessions.
The Console asks at the point where the action is dispatched. A device without an anchor keeps the usual step-up authentication. So does an anchored device for an action whose class the protection level does not sign. A mixed selection (anchored and unanchored devices in one bulk action) runs the step-up once for the action and asks the phone for the anchored devices. For an interactive tool (remote shell, file browser, task manager, registry editor, disk usage, screen control, backstage) one grant covers the whole dialog. A classic shell command, a patch run, an uninstall or a sensor test is one grant per action.
Before the request goes to the phone, the Console offers three choices: only this action, a work session on this device, or a work session on the group (or on the selection, for a bulk action). The choice is remembered per account.
With a work session the phone signs one reusable document for the chosen devices, the classes the protection level allows a session for and a duration (default 4 hours, at most the keychain limit); until it expires, the Console attaches it to every matching action of the account and asks nothing more. An action on another device or of another class asks again.
The device details show Session active until HH:MM with Extend (a new session for the chosen hours; the Console stops using the old one) and End.
Start work session on the device details and Work session next to the bulk remote shell open the session dialog directly; the Work session button in the top bar of the Console opens the same dialog from any page with a tenant, location and group picker (each entry shows how many anchored devices it covers, and a badge on the button counts your active sessions). In the dialog a signer of the line can also start a session for another user: that account's actions use it, nobody else's.
There are two ways to end a session. End with signature asks the phone for a revocation; the listed devices receive it with their next contact (online devices right away) and stop accepting the session. End on the console only needs no phone: the Console stops attaching the session immediately, but the devices accept it until it expires. The dialog says so.
Whoever may run an action may ask for its grant; who may sign is decided by the keychain (role grants). An account without a registered phone has its requests routed to the signers of the line whose accounts may see the devices' tenants; the waiting dialog names them, the first signature wins. Grant requests expire after five minutes.
A work session lets the Console run matching actions of the account on its devices without a new approval until it expires. Keep work sessions short and scoped, or choose only this action or the protection level Strict. The Relay App cannot sign: a tunnel or a screen control session to an anchored device is approved on a registered phone (the app shows Confirm the approval in the NetLock app while it waits). Screen control from the apps is described in A.13.10.
Public API. Device actions of the public API (run-command, run-script, reboot, shutdown, uninstall-agent, patch-now, patch-uninstall, the file, registry, event log and process actions, sensor tests and discoveries) answer 409 ztep_grant_required for an anchored device whose keychain signs the class of the action. The API has no phone to ask; run such actions from the Console. Actions of classes the protection level leaves unsigned, sync and Wake on LAN keep working through the API.
Screen control is a signed class at both protection levels, so a session from the Relay App or the NetLock app to an anchored device needs a grant as well. Before the session starts, the app asks the server whether the device needs one. The grant is requested for the account that owns the relay key and covers the whole session, pasting files included. An active work session of that account that names the device and screen control covers it without a request, as in the console.
In the NetLock app.
When this phone signs grants for the device's trust line, the signing page opens right away in the app, without a push notification: "Screen control on this device needs an approval. Approve the request on this phone." After the fingerprint or face check the session starts.
Otherwise the app waits until another phone approves: "Approve the request on another phone." when the account has another registered phone, "Waiting for another person to approve it." when the request went to the approvers of the line.
A rejection, a request that nobody approved in time and a device that no phone may approve for are named in the viewer; start again to send a new request.
In the Relay App. The Relay App never signs. The request goes to the phone of the account that owns the key ("Confirm the approval in the NetLock app on your phone."), or to the approvers of the device when that account has no registered phone ("Waiting for an approver of this device to confirm the request in the NetLock app."). Cancel ends the attempt and closes the window. A device for which no phone may approve is reported as "No registered phone can approve screen control on this device."
Relay App versions older than 3.3.0.11 cannot request a screen grant; their sessions to an anchored device are refused.
When the server cannot check a device, for example while the database is not reachable, the action is refused and nothing is sent to the device. A device is never treated as unanchored because its data could not be read. The refusal says to try again: "The server could not check the device right now. Please try again in a moment." in the console, "The server cannot process the request right now. Please try again in a moment." in the Relay App and the NetLock app, 503 with temporarily_unavailable on the public API and the relay routes.
This applies to screen control, backstage, audio calls and tunnels, to the approval requests of the Relay App and the NetLock app, to the remote actions of the console, to tenant and location deletion, to work sessions and to device actions of the public API. During such an outage:
An approval request that is already open stays open and is not sent to the phone a second time.
The Relay App and the NetLock app keep asking while they wait for an approval instead of reporting that no phone can approve. They show the message above only when the waiting time runs out during the outage.
Ending a work session is stored only after the server has read the sessions it ends; otherwise the app gets an error and can try again.
An Android phone or tablet with the NetLock RMM app supports endpoint protection like a desktop agent: the app holds an anchor, receives the keychain of its trust line with every sync and checks grants itself.
The Endpoint Protection card. The app shows a card Endpoint Protection with the state of the phone:
State on the card
Meaning
Off. Screen sessions need no approval from the NetLock App.
No anchor; screen sessions need no approval.
Protected · waiting for the trust line …
Anchored, no valid keychain yet: every screen session is refused.
Active · trust line …
The keychain of the trust line verified; screen sessions need an approval.
Chain break · trust line …
The delivered keychain does not continue the trusted chain; the last valid one stays in force.
The protection data cannot be read. …
The anchor exists but cannot be read: screen sessions are refused until the enrollment is removed. Protection is never switched off this way.
The trust line is shown by the first 12 characters of its anchor.
Anchoring at enrollment. The anchor of a phone comes only from a code built in the NetLock app, never from the web console. On the anchor page of the NetLock app, the card Android phones builds the enrollment code for the tenant and location chosen above with the anchor of the line, as QR code and as text. The phone scans it in the NetLock RMM app instead of the code of the console's Mobile enrollment dialog; that dialog creates codes without an anchor and says so.
The card carries the same warning as the installation commands: do not pass the codes on through the web console or by e-mail. Anchored enrollment requires NetLock RMM app 3.3.0.11 or later. Update the app on the phone before it scans the code.
If the server refuses such an enrollment, nothing of the code is kept: the anchor it wrote is taken back with it (The protection in this code could not be stored, so the phone was not enrolled. when the anchor itself could not be stored).
Anchoring a phone that is already enrolled. The same card in the NetLock app shows a second code with the anchor alone. On the phone, Scan trust anchor code or Enter trust anchor code (paste the text form) on the Endpoint Protection card takes it; the card then says This phone is now protected by the trust line …. The phone accepts it only while it holds no anchor (This phone is already protected. The protection ends only when the enrollment is removed.) and only once it is enrolled. A trust anchor code is not an enrollment code; the enrollment field refuses it.
Re-enrolling an anchored phone. An enrollment code with the same anchor, or one without an anchor, re-enrolls the phone and keeps its anchor. A code with another anchor is refused as a whole, and nothing changes (This phone is protected by another trust line. Remove the enrollment first.).
Leaving. An anchor cannot be replaced or removed. Removing the enrollment in the app or clearing the app's data ends the anchor together with the enrollment; the phone is then enrolled again like a new device.
New phone. The app's data, the enrollment and the anchor included, is excluded from Android backups and from device-to-device transfer. A phone set up from a backup of another phone, or moved to new hardware, starts without enrollment and must be enrolled again (with an anchored code if it should be protected). It appears as a new device.
What needs a grant. Starting a screen session, for viewing as well as for control (A.7.12). The grant is of the class screen control, as for a desktop: a single approval from the viewer, or a work session whose classes include screen control and whose device list includes the phone. The phone checks the grant before it shows anything to its user, before the consent question; a refusal reaches the viewer at once with the reason and is written as an event of type 14. Locating the phone, letting it ring and sending it a message need no grant.
During a session. Input needs no grant of its own; it belongs to the session. The phone ends the session once the grant has expired or a revocation names it.
Keychain and revocations reach the phone right away where push is available, otherwise with its next sync. A phone in a screen session receives them within a few seconds, even without push; when a revocation names the grant of that session, the session ends at once.
States in the console. The phone reports its anchor, keychain version and state like a desktop agent, and the device lists show the same lock on its icon (see A.13.5).
Limits. The anchor is stored in the app's private storage. The compliance check of the device reports a phone that looks rooted.
An API client of the partner or customer tenant, created in the management portal under Settings, API clients. Client ID and secret are shown once. A partner client reaches its customers through a token for each customer.
The address of your data center, for example https://eu2-cloud.acronis.com. Only addresses below acronis.com are accepted, so a stored secret cannot go anywhere else. A tenant with its own domain cannot be connected.
In Settings → Integrations, open the Acronis tile and choose Connect.
Enter the Instance address, the Client ID and the Client secret.
Choose whether a report for an unmatched device goes to the tenant.
Map each tenant to an Acronis customer, or import the customers. Only tenants of the type customer are offered. Customers without a mapping are not read.
Activate the connection.
The token of the connection needs the scopes devices:read, alerts:ingest and external-refs:read.
Every five minutes NetLock queries Acronis for each mapped customer and reports through POST /v1/alerts/ingest with the token of the connection. Synchronize now starts a pull immediately. Nothing is written in Acronis.
The first pull only records the current state: existing problems open no alert and no ticket until they change. The Overview tab shows how many there are. Everything after that is reported.
Status of the machines: a machine in warning, error, critical or waiting for an answer opens an alert (critical is critical, error is high, the others moderate) with its plans and the last successful backup. It ends with idle, scheduled or no_policies_applied. The status running or a missing status says nothing about the last backup, so an open alert stays open.
Active alerts: alerts of Acronis with the severity warning, error or critical (moderate, high, critical). An alert that is dismissed in Acronis ends here too. Information alerts and false positives do not open an alert.
The Overview tab shows the time and the counts of the last pull, including skipped items. A pull that changes nothing leaves no line in the History tab. If no pull succeeds for a day, the connection stays active and shows a note.
When a mapping changes, open alerts end at the old tenant and open at the new one; if the mapping is removed, they end.
NetLock tries these in order, always within the tenant of the customer:
An external reference of the device for the system acronis-cyber-protect-cloud, set through the public API with the resource id of Acronis in lower case.
The match of an earlier pull.
The host name, if exactly one device of the tenant has it. Case and domain are ignored.
Without a match the report goes to the tenant. If Report unmatched devices for the tenant is off, it is skipped and counted. If two devices share a host name, they need a reference. The External systems tab of the device shows its status at Acronis, the plans, the last successful backup and open reports.
A condition that stays the same is reported again once a day, so its alert does not run into the time limit for open alerts.
A customer the client cannot reach, including one whose token Acronis refuses, is counted in the overview. The other customers are still read, the state of the connection does not change, and no alert of that customer is treated as ended. The test of the connection tries the token of one customer.
If a customer has more than 20000 machines or alerts, the list is read only in part. No alert from it is then treated as ended, and the overview shows a note.
In Settings → Integrations, open the Autotask PSA tile and choose Connect.
Enter the API user name, the Secret and the API tracking identifier. NetLock finds the zone of your database through the user name.
Under options, choose the Status of new tickets, the Default priority, the Closing status (usually Complete), the Note type and the Visibility of the note. Choose the value for internal notes there. The lists come from your Autotask database.
If the ticket category of the API user requires a queue, choose a Queue. Autotask also requires a due date unless the category sets one, so every ticket gets a due date based on Due after (hours).
Map each tenant to a company, or import companies and locations. Tenants without a mapping are not included.
Optionally map locations and severities.
Activate the connection.
Autotask allows 10,000 requests per hour per database across all integrations and limits parallel calls per endpoint. A job that hits a limit waits and then continues.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
With contract items mapped, also: the device count of the mapped tenant per period.
An alert becomes a ticket of the mapped company. The reference NetLock-Alert-<id> is stored in the External ID of the ticket and at the end of its title. Autotask limits the title to 255 and the description to 8,000 characters.
When the alert ends, the ticket gets a note with the type and visibility of the options, and it is set to the closing status if nobody is working on it.
A ticket with a primary resource counts as assigned.
If Autotask refuses the status, for example because of a required field, the ticket stays open with its note, and the history says close_refused.
The behaviour is set in the Settings tab, see A.14.4. NetLock never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets, and choose a Product of configuration items, which Autotask requires, and a default type or a mapping of the device classes.
A device is a configuration item with NetLock-Device-<id> as reference number. NetLock reuses an existing item only on an exact match within the company.
The company of an item cannot change in Autotask, so a device that moved gets a new item at its new company. The old one stays.
An alert of a synced device names its configuration item in the ticket.
The Billing tab of the connection writes device counts to the services of recurring contracts, see A.14.10.
The list holds the services of the recurring contracts of the company that run in the period.
Contracts with ContractServiceBundles do not appear in the list, only single services.
Autotask stores units in rows per period and accepts only changes. NetLock reads the units at the effective date and writes the difference as an adjustment, so a second transfer of a period adds nothing.
A period with 0 units has no row in Autotask. A date inside the contract without a row therefore counts as 0.
If the units cannot be determined, nothing is written and the history says so: for a date before all rows of the service, at the very end of a row, or after the end of the contract.
A change applies from the day after the period, which has not been billed yet. With Quantities apply from the start of the period it applies from the first day of the period; Autotask can refuse that for a period already posted.
An adjustment holds for all later periods. Only the latest closed month can be transferred; the preview offers no other month, and Send again on an older job ends without a write.
If a write gets no answer, NetLock does not repeat the difference by itself. If Autotask shows the old quantity, the row waits for your check.
The NEXOWARE / c-entron web service, which comes with the subscription Ultimate, reachable from the NetLock server.
Either a NEXOWARE / c-entron user for the login, or an access token. An access token needs the license Access Token and release 2.0.2605 or newer. It has an expiry date, one year ahead by default.
For contract quantities, the RMM interface of NEXOWARE / c-entron.
In Settings → Integrations, open the NEXOWARE / c-entron tile and choose Connect.
Enter the Instance address: the address of the web service without /REST, for example https://server/CentronService. Allow unencrypted http is for an instance on an internal network only.
For a login, enter User name and its password in Password or access token. For an access token, leave User name empty and enter the token.
Under options, choose the Status of new tickets and the Ticket type. If NEXOWARE / c-entron asks for a category, enter the number (I3D) of a main category.
Map each tenant to an account, or import the accounts as tenants. Tenants without a mapping are not included.
Optionally map the severities to helpdesk priorities.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
With contract items mapped, also: the device count of the mapped tenant per period.
An alert becomes a helpdesk ticket of the customer of the mapped account. The reference NetLock-Alert-<id> is added at the end of the short description.
A synced device of the alert is linked to the ticket.
When the alert ends, the ticket gets a comment, and it is closed if nobody is working on it. Depending on your NEXOWARE / c-entron settings, customers may see this comment.
Nobody is working on it means that neither the status nor the editors have changed since the ticket was created. Editors that NEXOWARE / c-entron assigns automatically at creation do not count as assigned.
NetLock first asks NEXOWARE / c-entron whether the ticket can be closed. If the answer is no or the close is refused, the ticket stays open with its comment, and the history says close_refused.
The behaviour is set in the Settings tab, see A.14.4. NetLock never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets. Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run.
A device is a customer device of the mapped account, with NetLock-Device-<id> as device id. An existing customer device is reused only if that id matches exactly.
Values NetLock does not know stay as they are in NEXOWARE / c-entron.
A device that moved to another customer gets a new customer device there. The old one stays.
A customer device deleted in NEXOWARE / c-entron comes back as a new one.
The Billing tab of the connection writes device counts to the contract items of the RMM interface, see A.14.10.
The list holds the items of the billing intervals of the customer's active contracts.
An item has its own billing interval in NEXOWARE / c-entron. NetLock takes the earliest interval that overlaps the chosen month, counts that interval, not the calendar month, and writes the quantity for it. The preview shows the dates.
An interval that has not ended is not written. A quarterly contract therefore gets its quantity with the run after the quarter has ended.
An item without an interval in the chosen month does not appear for that month.
The reason stored on the item is NetLock RMM: <name of the count>.
An item NEXOWARE / c-entron blocks is not written, and the history says so.
An access token, created in DocBee under the user icon in the top bar, Settings, Access Token. The token has the rights of its user, so NetLock cannot see records that the user cannot see. Use a dedicated user.
The user needs to read customers, locations, statuses and priorities and to write tickets and ticket messages, and for the device sync to read catalog objects and write customer objects.
In Settings → Integrations, open the DocBee tile and choose Connect.
Enter the Instance address and the Access token. Allow unencrypted http is for an instance on an internal network only.
Under options, choose the Status of new tickets, the Status when closing and the Default priority, which DocBee requires on every ticket. Ticket category and Queue are optional.
Map each tenant to a customer and its locations, or import them. Tenants without a mapping are not included.
Optionally map the severities to priorities.
Activate the connection.
Choose statuses that fit an automatic ticket. NetLock sets no contact on a ticket, so status e-mails to the customer contact are not sent, but a status can have other effects configured in DocBee, for example under Automation. If a category restricts its status changes, the closing status has to be reachable from the status of new tickets; otherwise the ticket stays open and the history says close_refused.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes a ticket of the mapped customer and location, with the customer object of the device if the asset sync linked one. A DocBee ticket has no title of its own, so the title is the first line of the description. The reference NetLock-Alert-<id> is stored in the external reference number.
When the alert ends, the ticket gets an internal message and the closing status, if nobody has taken it. A ticket that has no owner or stays with the queue of the connection counts as unassigned. Any other owner, including another queue, counts as assigned.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets, and map device classes to catalog objects or choose a Default object: a customer object in DocBee always points to one.
Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
A device becomes a customer object with the device name as extended name and NetLock-Device-<id> as number. Operating system, IP address and MAC address go into their fields, manufacturer, model and serial number into a marked block of the details. Text outside that block is kept.
A device with the name of an existing object of the customer is linked to that object, provided that exactly one such object exists, it has no number yet and no other device holds it.
An update sends only the values NetLock knows. Anything else you entered in DocBee is kept.
A device that moved to another tenant or location moves its object. If DocBee refuses that, the device is named in the history and tried again; the change is not marked as done.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed.
When a job is repeated, NetLock looks for the ticket among the 200 newest tickets of the customer. An older ticket is not found, and a second ticket can open.
Docusnap runs its own network inventory, and its objects have no key an outside system could use. NetLock therefore does not add a second inventory. It links a device to the object Docusnap scanned, and the External systems tab of the device shows the link.
Nothing is written to a matched object: NetLock does not change values that Docusnap365 scanned.
An API key, created in Docusnap365 under the gear icon, API Keys. The right Read is enough. Write is only needed for creating objects. A key has an expiry date; an expired key or a key without Read puts the connection into the error state with the reason.
The address api.docusnap365.com is fixed, so a stored key cannot be sent anywhere else.
In Settings → Integrations, open the Docusnap365 tile and choose Connect.
Enter the API key. The test of the connection shows the number of organizations, tries a search and checks that the objects of the first organization carry an id.
Under options, switch on Sync devices as assets. It is off by default: without it the connection does nothing.
Map each tenant to an organization, or import the organizations. Tenants without a mapping are not included.
Only by its exact serial number, within the mapped organization. The match is case-sensitive. Names are not used, because scanned names and host names often differ.
A device is skipped, without counting as a failure, when:
Reason in the history
Meaning
no_serial
The device has no serial number, or a placeholder such as To Be Filled By O.E.M.
not_in_source
The organization has no object with this serial number
ambiguous
Several objects have this serial number. NetLock does not guess. Remove the surplus objects in Docusnap
taken
The one object that fits belongs to another device of this connection. Deleting that device in NetLock frees the object
create_incomplete
Creating is on, but a hardware type for the device class or the scope is missing
create_refused
Docusnap365 refused to create the object, see below
create_unconfirmed
A create request was sent, but the object cannot be found, see below
A skipped device is checked again a week later, because requests are counted; a device with no_serial costs no request and is checked again a day later. Saving the settings, changing a mapping or Synchronize now ends the wait.
A linked device is checked again only when its serial number or its organization changes. If the object is no longer in the organization or carries another serial number, NetLock searches again; if nothing is found, the link is removed, so a device that moved to another tenant does not show the object of the old customer. An object deleted in Docusnap is not noticed until such a change.
Docusnap365 counts API requests per month: 50,000 in Pro, 100,000 in Business, unlimited in Enterprise. The requests of other tools with API keys count as well.
A linked device only costs a request when its serial number or organization changes. A new IP address or another operating system costs nothing, because this data is not sent to Docusnap365.
NetLock reads one list per organization and run step instead of one request per device, and processes the devices of an organization together.
A device without a serial number costs no request.
The test of the connection costs three requests, the dropdowns one each.
If Docusnap365 reports that the limit is reached, the run stops and tries again an hour later, unless the response gives a different time. While that job waits, no new one is added. The connection stays active, nothing pauses, and the Log tab says that the requests of the month may be used up.
If the list of one organization fails with a server error or a timeout, its devices are retried within the hour, and the other organizations are still processed.
Create objects for devices without a hit is off by default.
Warning: Docusnap365 does not recognise objects that NetLock created. If a gateway later scans a machine for which NetLock created an object, a second object can appear next to it. The serial number is then ambiguous, and you have to clean up in Docusnap. Leave this off where a gateway scans. It is meant for devices no scan reaches.
With it on, a device with a serial number and without a hit becomes a new hardware object in the mapped organization. Right before creating it, NetLock searches for the serial number once more, so an incomplete list does not lead to a second object. A device without a serial number is never created, because it could not be found again. Creating requires:
a key with Write,
a hardware type for the device class, under Mappings,
Scope of new objects, by default HwComputer. It applies to all new objects of the connection, so map only hardware types of this scope. A server type, for example, has its own scope in Docusnap365,
optionally a site from the mapping of the location, and Platform of new objects.
The serial number, the label and the note Created by NetLock RMM are the only data sent. Nothing is deleted, even when a device is removed. A serial number that exists with different case counts as ambiguous: no link, and no second object.
Refused: If Docusnap365 refuses to create an object, for example because the key lacks Write or the scope does not fit, creating stops for the whole run. The device waits a week, the others a day, and the Log tab shows the refusal.
Unconfirmed: A create request can be sent without NetLock finding the object afterwards: the response names no object and the search finds none, or no response arrives. The object may exist, so NetLock does not create this device again. The device stays on create_unconfirmed, and the Log tab names it. To end this:
If the object exists, make sure it is in the organization and carries the serial number of the device. The next check links it.
If it does not exist, switch Create objects for devices without a hit off, choose Synchronize now, and switch it on again.
NetLock treats any unexpected answer as a failure, so a failure is never mistaken for an empty inventory. Status 429 counts as the monthly limit, 401 as an expired key.
A location in NetLock is only used when creating.
The External systems tab shows the link without a button to open the object.
Data flows in one direction only: Docusnap data does not flow into NetLock.
A Freshdesk account, reached at https://<account>.freshdesk.com. Other addresses are refused.
The API key of an agent who may create tickets, add notes, change the status, and read companies and contacts. The key is shown in the profile settings of the agent.
In Settings → Integrations, open the Freshdesk tile and choose Connect.
Enter the Instance address and the API key.
Under options, enter the requester of tickets, the e-mail address under which tickets are created. Freshdesk creates the contact if it does not exist. Optionally choose a Group, and choose the Status when closing.
Map each tenant to a company, or import companies as tenants. Tenants without a mapping are not included. Without a severity mapping the four severities follow the four priorities.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes a ticket with the reference as tag. The subject ends in [NetLock-Alert-<id>].
When the alert ends, the ticket gets a private note and moves to the chosen status if nobody is assigned.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
A Freshdesk ticket belongs to the company of its requester. By default the configured address is the requester, so the ticket does not belong to the company; the tenant is named in the ticket text.
First contact of the company as requester assigns the ticket to the company. Freshdesk may then send its new-ticket notification to that contact, who is a customer. Check the requester notifications of your account before you switch it on.
Send the company with the ticket is for accounts with the Freshdesk feature Multiple Companies. Without that feature Freshdesk refuses the ticket.
A Freshservice account, reached at https://<account>.freshservice.com. Other addresses are refused.
The API key of an agent who may create tickets, add notes and change the status. The key is shown in the profile settings of the agent, and the integration has the rights of the agent.
For the asset sync, the right to manage assets, and an account on the classic asset model, see Known limits.
In Settings → Integrations, open the Freshservice tile and choose Connect.
Enter the Instance address and the API key.
Under options, set Freshservice for MSPs if you use that product: tenants then map to clients instead of departments. Enter the requester of tickets, the e-mail address under which tickets are created. Freshservice creates the contact if it does not exist. Optionally choose a Group, and choose the Status when closing.
Map each tenant to a department or client, or import them as tenants. Tenants without a mapping are not included. Without a severity mapping the four severities follow the four priorities.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes a ticket with the reference as tag. The subject ends in [NetLock-Alert-<id>].
When the alert ends, the ticket gets a private note and moves to the chosen status if nobody is assigned.
If your account requires fields on closing, Freshservice refuses the status. The ticket stays open with its note and the history shows close_refused. Skip mandatory fields when closing avoids that; it works only with the API key of an administrator.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The sync is off by default, because assets can count against your Freshservice license. To use it:
Switch on Sync devices as assets.
Map device classes to asset types, or choose a Default asset type. A device without a type is skipped and named in the history.
Optionally map locations.
Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately. NetLock recognises a device by its asset tag NetLock-Device-<id>. The device details are written to the description of the asset, because the other fields differ per asset type. A ticket for a device links to its asset.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed, and the connection is not affected. Nothing is deleted in Freshservice: a device removed from NetLock stays there.
The asset sync supports accounts created up to 31 March 2026. Newer accounts use Freshservice IT Asset Management; leave the asset sync off there. Tickets are not affected.
In Freshservice for MSPs an asset cannot be moved to another client. A device that moved to another tenant reports that in the history.
An API key, created in the GravityZone console under My Account, with the APIs Companies, Network, Incidents and Quarantine. The test of the connection lists the APIs the key is missing.
The Access URL from the same page, for example https://cloudgz.gravityzone.bitdefender.com/api. Only addresses below gravityzone.bitdefender.com are accepted, so a stored key cannot go anywhere else. An on-premises console cannot be connected.
For incidents, a license that includes them. Without one, switch Read incidents off.
In Settings → Integrations, open the GravityZone tile and choose Connect.
Enter the Instance address and the API key.
Under options, choose what to read: Read incidents, Read the quarantine, and whether a report for an unmatched device goes to the tenant.
Map each tenant to a company, or import the companies. A partner key lists its companies, including those in folders. Companies without a mapping are not included.
Activate the connection.
The token of the connection needs the scopes devices:read, alerts:ingest and external-refs:read.
Every five minutes NetLock queries GravityZone and reports through POST /v1/alerts/ingest with the token of the connection. Synchronize now starts a pull immediately. Nothing is written in GravityZone.
The first pull only records the current state: existing problems open no alert and no ticket until they change. The Overview tab shows how many there are. Everything after that is reported.
Incidents: every pull reads the open incidents and those closed since the last pull. The priority of an incident sets the severity: critical is critical, high is high, medium is moderate, low is low. An unknown priority falls back to the severity score (from 80 critical, from 60 high, from 30 moderate). A closed incident, a false positive or an incident closed after review ends the alert. An organization incident does not name a single endpoint and is reported for the tenant.
Quarantine: the findings of the last 14 days of an endpoint become one alert with moderate severity. It ends when the endpoint has no finding left in that time.
The Overview tab shows the time and the counts of the last pull, including skipped items. A pull that changes nothing leaves no line in the History tab. If no pull succeeds for a day, the connection stays active and shows a note.
When a mapping changes, open alerts end at the old tenant and open at the new one; if the mapping is removed, they end. Switching off Read incidents or Read the quarantine ends the alerts that part left open.
NetLock tries these in order, always within the tenant of the company:
An external reference of the device for the system bitdefender-gravityzone, set through the public API with the endpoint id of GravityZone.
The match of an earlier pull.
The host name, if exactly one device of the tenant has it. Case and domain are ignored.
Without a match the report goes to the tenant. If Report unmatched devices for the tenant is off, it is skipped and counted. GravityZone does not include serial numbers in these lists, so if two devices share a host name, they need a reference. The External systems tab of the device shows its endpoint, open reports and links to incidents.
A condition that stays the same is reported again once a day, so its alert does not run into the time limit for open alerts.
The malware status of single endpoints is not read; threats arrive through incidents and the quarantine.
If the quarantine holds more than 10000 findings in 14 days, it is read only in part. No quarantine alert is then treated as ended until a full read succeeds, and the overview shows a note.
If the test of the connection reports that no customer company is visible, connect each company with its own key.
GravityZone allows 10 requests a second per key and 5 a second for the company list. NetLock waits when GravityZone reports the limit.
An API application in HaloPSA under Config > Integrations > Halo API, with the authentication method Client ID and Secret, the permission scope all, and an agent it runs as.
For a hosted instance, its tenant name, which is shown on the same page.
In Settings → Integrations, open the HaloPSA tile and choose Connect.
Enter the Instance address, for example https://company.halopsa.com, the Client ID and the Client secret, and for a hosted instance the Tenant. An Authorisation server is only needed if it is not located at /auth on the instance.
Under options, choose the Ticket type and the Closing status, and optionally a Team. Outcome of the note is the action outcome that writes a private note.
Map each tenant to a client, or import clients and sites. Tenants without a mapping are not included.
Optionally map locations to sites and severities to priorities.
Activate the connection.
The API allows 700 requests in five minutes per tenant; a job that hits this limit waits and then continues.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes a ticket of the mapped client, at the mapped site if there is one. The reference NetLock-Alert-<id> is added at the end of the summary.
When the alert ends, the ticket gets a note hidden from the user, without an e-mail, and it is set to the closing status if nobody is working on it.
A ticket with an agent counts as assigned.
If Halo refuses the status, for example because of a field required on closing, the ticket stays open with its note, and the history says close_refused.
The behaviour is set in the Settings tab, see A.14.4. NetLock never deletes anything at the vendor.
The sync is off by default. Assets can count towards a license in Halo. Switch on Sync devices as assets, and map device classes to asset types or choose a Default asset type. A device of a class without a type is named in the history and waits; the other devices are still processed.
An asset carries NetLock-Device-<id> as inventory number. NetLock reuses an existing asset only on an exact match.
A device without a location mapping goes to the main site of its client.
The fields of an asset type differ per instance, so the device details are written to the notes of the asset.
A device that moved to another client gets a new asset there. The old one stays.
An alert of a synced device links the asset to the ticket.
The HaloPSA connector does not write contract quantities. The asset sync keeps the assets of each client current, which a recurring item in HaloPSA can count.
An API key, created in the admin area of Hudu under API Keys. Use a dedicated key for NetLock, without password access and without delete rights. If NetLock should create the layout, the key needs the right to write asset layouts.
In Settings → Integrations, open the Hudu tile and choose Connect.
Enter the Instance address and the API key. Allow unencrypted http is for an instance on an internal network only.
The test of the connection shows the version of Hudu and what will happen with the layout.
Under options, switch on Sync devices as assets: without it the connection does nothing, and nothing is created in Hudu. Choose the Asset layout: NetLock Device, or a layout that already exists in Hudu.
Map each tenant to a company, or import the companies. Tenants without a mapping are not included.
Every hour NetLock sends the devices that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
NetLock Device is created on the first run if it does not exist, with the text fields NetLock Device Id, Operating System, IP Address and MAC Address. Manufacturer, model and serial number go into the primary fields of the asset.
A custom layout receives only the fields with these labels. Without a field NetLock Device Id, NetLock finds a device by its serial number or, if there is none, by its name.
A device is linked to an existing asset of the same company and layout by its serial number, or by its name if neither has a serial number, provided that exactly one such asset exists, it is not archived and neither another device nor another NetLock Device Id holds it.
An update sends the existing fields of the asset with the values NetLock knows filled in, so what you entered is kept. An asset of a custom layout whose fields NetLock cannot read counts as failed and is not changed.
A device that moved to another tenant gets a new asset in the new company. The old one stays.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed.
Nothing is deleted in Hudu. The External systems tab of the device links to its asset.
Settings → Integrations at /settings/integrations connects NetLock RMM to other products. Every entry is a tile with its category and its state on this instance. Tiles fall into three groups:
Connectors connect to a product of another vendor, for example a ticket system. They have a setup assistant and, once connected, a page of their own.
Custom integration is for tools that fetch data themselves. It creates an ordinary API token with suggested read scopes, see A.14.8.
The store offers a search, a filter per category and the switch Connected only. A product can appear in more than one category.
E-mail, Microsoft Teams, Telegram, ntfy and the NetLock app are notification channels and are not part of the store. They are configured under Settings → Notifications.
Connectors read NetLock data through the public API, on a local port of the server, with a token that belongs to the connection. The public API therefore has to be on. While it is off, the store and every connection page show a banner, and connections do not run. An account with settings_api_tokens_manage sees the button Switch on public API in that banner.
The web console and the server need the same Security:Local_Encryption_Key, because the console stores the credentials and the server reads them. If the keys differ, a connection stops with the note that the stored credentials cannot be read.
The server listens for this traffic on 127.0.0.1:7480. Integrations:Loopback_Port in the appsettings.json of the server changes the port; 0 switches the listener off, and connectors then do not work. The port accepts only /v1 and is not meant to be published. In a container it stays inside the container, so nothing has to be added to a compose file. If the port is taken, the server starts anyway and the connection shows that the local listener cannot be reached.
Connect in the detail of a tile opens the assistant.
Credentials. The name of the connection and the fields of the product. A secret field is write-only: it is stored encrypted and never shown again.
Test. NetLock makes a read-only call to the vendor. The step cannot be skipped, and nothing is stored until the test has passed. The connection is created with exactly the values that were tested, and it gets its token, bound to your account.
Options. The settings of the product, the alert filter, what an all-clear does to a ticket, and the language of the ticket frame, see A.14.4.
Mappings. Which tenant belongs to which company, and which severity to which priority, see A.14.5.
Activate. The connection starts to work. Alerts that were already open are not sent: a connection only handles alerts from the moment it is activated.
If you leave the assistant after step 2, the connection stays in the state Setup open. Continue setup on the page of the connection resumes at the options.
Note: Alert texts, device names and tenant names go to the vendor. Check that this matches your data processing agreements before you activate a connection.
Target addresses follow the rules of the instance. On a cloud instance only public addresses can be reached. A self-hosted instance can also reach private addresses, but never loopback, link-local or cloud metadata addresses. The test reports a refused address.
State and its reason, the account the connection runs under, mapped tenants, last success and last error. Pause, Resume, Synchronize now and Switch to my account.
Tables per kind of mapping, Auto mapping, Import companies, see A.14.5.
Billing
Only for connectors that can write quantities: contract items per tenant, plan, preview and transfer, see A.14.10. For accounting connectors: positions, tax case per tenant, preview and documents, see A.14.11.
History
Every job with its result, filter, export, the redacted request and response, Send again, see A.14.6.
There is no service account. The token of a connection is bound to the account that connected it, and it always has the current rights of that account. The overview shows that account, the tenants it does not cover and the scopes it can no longer grant. A disabled or removed account stops the connection.
Switch to my account moves the connection to your account with a new token. That only works if your account covers every mapped tenant and every scope of the connection; otherwise nothing changes and the page names what is missing, so a connection never loses tenants without notice.
The token appears under Settings → API tokens with the chip Integration: <name> and cannot be changed there. NetLock replaces it every 30 days. It is valid only on the local port and from the server itself; the public port rejects it with 401.
If you leave a secret empty in Replace credentials, the stored secret is kept, but only for the address it was stored for. If the address changes, or Allow unencrypted http is switched, every secret has to be entered again; otherwise the test and saving are refused. The audit log names the old and the new address.
Alert filter. The minimum severity and the sources that create tickets. Empty sources mean every source.
After an all-clear.Add a note only, Close if nobody is assigned (default) or Always close. If the ticket was changed at the vendor in the meantime, only the note is added.
When a one-shot alert is acknowledged. The same choice for alerts that have no all-clear, such as an antivirus finding. They end when the event is read or hidden. Like every open alert, they also end when no new event arrives for the number of days set on the retention page (30 by default).
Language of the ticket frame. Title, field names and notes of a ticket; the text of the alert stays as it is. Defaults to the language of the instance.
Tickets link back to the web console through the public console URL. Without that setting a ticket has no link.
Only mapped tenants are included. An alert of a tenant without a mapping is not lost: it appears in the history as skipped, with the reason.
A mapping connects a local object with its counterpart at the vendor: tenants and locations with companies and sites, severities with priorities, device classes with types. A product decides which of them it offers and which are required. A mapping can be switched off without removing it.
Auto mapping compares the tenants without a mapping with the companies of the vendor by name. A company whose name matches the tenant's, ignoring case and spaces, is selected. Less certain matches stay open as candidates: names that differ in an accent or in punctuation, a tenant with several candidates, and a company that matches two tenants. Müller and Muller can be two different customers, so a person has to choose. Existing mappings stay as they are, and one company cannot be chosen for two tenants.
Import companies lists the companies without a mapping. Each one can become a new tenant, which needs the permission to add tenants, or be mapped to an existing tenant without a mapping. A new tenant is added to the tenants of your account. The import never replaces a mapping; a line it cannot apply stays in the dialog with the reason.
The history lists what a connection did, newest first. A job is Waiting, Running, Done, Failed or Skipped. Failed attempts are repeated after 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours and 24 hours; a limit of the vendor (429) does not count as a failure, and a refused request (4xx) is not repeated.
The full text of a vendor error is shown only on the job of its tenant. The overview of a connection and jobs without a tenant, which every reader sees, show only the kind of error.
The detail of a job shows the request and the response. Credentials and tokens are redacted before they are stored. Send again queues a failed or skipped job once more. NetLock does not create a second ticket for an alert it already reported, and it never deletes anything at the vendor. The connector pages name the cases where a repeated job cannot rule out a second ticket.
Finished jobs are removed after the time set on the retention page.
The tab Log on the page of a connection shows what happened and why something failed. It exists for every connector. The history lists jobs; the log also shows events that no job records: failed connection tests, status changes, a pause and its end, the replacement of the token, a local listener that cannot be reached, and what the scheduler decided, such as a report left out or the first status pull. A line that belongs to a job links to it. Notification channels and signed webhooks keep their own delivery logs and do not appear here.
Each line has a time, a level (Error, Warning, Info, Debug), an area and a message in your language. You can filter by level, area and time, and the search also covers the messages of the vendor. Export data writes the lines you see. The detail of an error or a warning says what to do, and shows the request it came from: method, host, path without the query, status and duration. The same explanation appears in the setup assistant when a test fails.
Repeats of the same error within an hour are combined into one line with a counter and the time of the last occurrence, so a failing connection does not fill the log. Runs that find nothing new leave no line.
Message
What to do
The vendor rejected the credentials (401)
Check them at the vendor and replace them under Danger zone. The connection stays stopped until then.
The address is not allowed on this instance
Use the public https address of the vendor. Private addresses and plain http are refused, and the name has to resolve on the server.
Mapping missing
Add it under Mappings, then use Send again on the job in the history.
The key or token has expired
Create a new one at the vendor and replace it under Danger zone.
The token of the connection is refused
The token belongs to NetLock. Reconnect, or switch the account on the overview.
The vendor limits the requests (429)
Nothing for now: the work waits as long as the vendor asks. If it stays, reduce other use of its API.
Debug for 60 minutes is for a support case. For that time the log also keeps every request with a summary of the request and the answer, and the runs that found nothing. It ends automatically; Stop debug ends it early. The button needs settings_integrations_manage, and switching it on or off is recorded in the audit log.
Credentials are removed before anything is stored, at this level too, and vendor lists such as all companies or all tickets never reach the log. Requests for work that covers all tenants, such as the asset sync, show the response only when they fail. A very busy connection records up to 120 requests per minute and server process; a line says how many were left out.
Entries are removed after 14 days, counted from their last occurrence. The period can be changed on the retention page. Deleting a connection removes its log.
settings_integrations_enabled opens the store and shows connections, mappings, history and log. settings_integrations_manage allows everything else. Both are described in X.2.17.
An account limited to some tenants can still connect, configure, pause and disconnect, because a connection belongs to the instance. Anything that touches the data of a tenant is limited to the account's own tenants:
None. The confirmation of Disconnect and Delete names how many tenants the connection serves.
Lists of the vendor, such as companies or queues
None. They are not NetLock data, but they need settings_integrations_manage: reading them uses the stored credentials. An account that only reads sees stored values as text.
Mappings of tenants and their locations
Outside the account's tenants a row stays visible, locked and without names.
Auto mapping, Import companies
Only tenants of the account. A new tenant additionally needs the permission to add tenants.
Contract items, preview, transfer
Only tenants of the account. Other rows stay visible, locked and without names or numbers. Preview and transfer need settings_integrations_manage. A planned transfer covers every mapped item.
History
Jobs of other tenants are hidden. Jobs without a tenant are visible. Send again only for visible jobs.
Log
Lines of other tenants are hidden. Lines without a tenant are visible with their message and error class, without the text of the vendor, the path and the summary of the request. Switching debug logging on needs settings_integrations_manage.
Token of the connection
Only mapped tenants, and only those the bound account covers.
A connection set up by an account with few tenants can therefore serve only those tenants. The overview shows when mapped tenants are out of reach.
The tile Custom integration suggests read scopes for tools that fetch data themselves. Create token opens the usual token dialog with these scopes ticked; account, tenants and expiry are chosen there. It needs settings_api_tokens_manage. The token is shown once and then behaves like any other token, see X.9. For push instead of pull, see X.10 — Webhook signatures.
NetBox and Snipe-IT are usually a customer's source of truth. NetLock therefore only adds its own fields to objects that already exist there and skips a device without a match, with the reason in the History tab.
Docusnap365 runs its own scans, so NetLock only links a device to its scanned object by serial number and writes nothing.
Status connectors such as GravityZone, Acronis and Wazuh query the vendor every five minutes and report through POST /v1/alerts/ingest, so the same rules apply to their alerts as to any external report. Their first pull only records the current state, so connecting an account does not open hundreds of old problems.
A ticket that cannot be closed keeps its note and stays open, and the History tab gives the reason: assigned, changed, no_transition or close_refused.
As soon as a connection exists, the device details show the tab External systems. It lists the objects of the device in the connected systems: the asset of the device sync, the endpoint a status connector matched, what such a connector reports as open, the tickets of the alerts of the device, and references set through the public API. Each row names the system, the connection, the state and the last change, and links to the object where the vendor provides an address.
Like the rest of the device details, the tab requires the device tab permission General and access to the tenant of the device. Nothing can be changed in it.
Connectors that support it write the device count of a tenant for a period to a contract item at the vendor. The Billing tab holds one row per tenant and item. A tenant needs its company mapping first.
Each row has its own counting rule. The rules apply together; all three are on by default.
Rule
Effect
Only authorized devices
A device counts on a day it was authorized.
Leave out blocked devices
A device does not count on a day it was blocked.
Online at least once in the period
A device counts only if it checked in on at least one day of the period.
Platforms, Device classes
Only the chosen ones. Empty means all.
Value of the period decides what goes to the vendor: the Maximum of the daily counts (default), their Average, rounded, or the Last day. The counts come from a snapshot NetLock takes every night, starting with the first snapshot. Days without a snapshot are not included. They match the usage endpoints of the public API.
Required coverage sets the share of days in a period for which the tenant needs counts. The default is 100 percent, every day. A month that is not fully covered, such as a month with a long server outage, is then not written until you lower the value for that item. A contract item holds one count, so two tenants or two counts cannot write to the same item.
Preview shows what a transfer would do for a month: the quantity at the vendor against the new one, how each rule changes the count, for example All devices 52 → Only authorized 50 → Without blocked 49 → Online in the period 47, the three period values, how many days have numbers, and which devices a rule removes. A device that passes a rule on some days stays in the list and only lowers the count of those days.
Transfer now sends the rows that would change. Planned transfer sends the previous month on a day of your choice, once the snapshot of its last day exists. If a plan or a row is switched on after that day, it starts with the next month, because nobody has seen a preview for the month that is due.
When in doubt, NetLock writes nothing and says why, in the preview, in the Billing tab and in the history.
A transfer asks the vendor what is booked and writes only the difference. A second transfer of a period books nothing twice.
A period that has not ended is not written, not even by hand. If the vendor bills a quarter, the quantity is sent once the quarter is over.
A period below the required coverage is not written.
A tenant without any numbers for the period writes nothing; in particular, it does not write zero.
A planned transfer never sets an item to zero. A manual transfer can, and the preview warns about it.
An item the vendor blocks or no longer lists is skipped.
A refused quantity fails its job but does not count as a failure of the connection.
A write that ends without an answer, such as after a timeout, is resolved on the next attempt based on what the vendor holds. If that is not possible, the row shows Check at the vendor and nothing else goes out for this item. Look at the quantity at the vendor and use Send again on the job in the History tab.
Send again runs a transfer under your account.
A plan that skipped a month, for example while the connection was paused, does not catch up. The row shows A period was missed.
Every transfer is recorded in the audit log with the old and the new quantity and the coverage. A planned one has the user system.
Check the rules in the preview before you plan a transfer: these numbers end up on invoices.
This is meant for MSPs without a PSA. Accounting connectors create one invoice draft per tenant and month, with one line per position. A person checks the draft and finishes it in the accounting product. NetLock never finishes or sends a document: a finished invoice can only be undone by a cancellation.
The connectors are Lexware Office and sevdesk. Their pages describe the differences, most of which concern Lexware Office.
Positions. A tenant needs its contact mapped first. A position in the Billing tab names an article of the accounting product, what it counts, and the rule of A.14.10: the three rules, the filters, the value of the period and the required coverage. Price per unit is optional and overrides the price of the article, because prices often differ per customer. A tenant can have several positions, for example Servers and Workstations through the platform and class filters. They all end up on one document.
Preview and creating.Create drafts shows, for a month and per tenant, each position with the effect of the rules, the article, the price and the amount, the total, the tax case, and whether a document of that month exists. Create drafts in the dialog then creates drafts for the tenants that can get one. The dialog applies the same checks as the planned job.
Plan.Planned drafts is off by default. When switched on, it creates the drafts for the previous month on a day of your choice, once the snapshot of its last day exists. A tenant with a position switched on after that day starts with the next month, because nobody has seen a preview for this one.
All or nothing. If one position cannot be written, the whole document is stopped and the history names the reason: a period that has not ended, too little coverage, no numbers for the tenant, an article that is gone, a position without a price. A planned run never reduces a position from a quantity to zero. A position that counts 0 is left out; if all of them count 0, no document is created.
Tax. NetLock does not decide tax questions or calculate tax. The rate comes from the article, and the tax case is set per tenant. For a contact in Germany, no choice is needed. For a contact in another country or with an unknown country, no document is created until a tax case is chosen, even on a small-business account. If the vendor refuses the tax, no document is created either. The mapping of the tax cases to the vendor's terms follows the vendor's names. It is not tax advice; have it checked by your tax adviser.
Documents. The list of documents shows one row per tenant and month. The rows are kept permanently, even after the jobs have been removed and the connection is deleted, because they prevent a period from being invoiced twice. A document belongs to the account at the vendor, not to a connection: a second connection to the same account, or one set up again, sees the same rows and creates no second document. Before a document is created, NetLock also searches the vendor for its reference. If the vendor does not identify the account, no document is created.
NetLock reads the current state of the documents when an account with the manage permission opens the tab, when you click Check at the vendor, and once a day.
State
Meaning
What happens next
Draft
The vendor holds the draft.
No second document. If the count differs from it, the row shows old and new, and you correct the draft at the vendor.
Finished
A person finished the document.
The same. A correction is a cancellation or credit note in the accounting product.
Deleted at the vendor
The draft is gone.
Nothing by itself. Create again makes a new one.
Check at the vendor
A call ended without an answer, and the vendor does not show the document. A run left in progress ends here as well.
Nothing by itself. Check at the vendor, then use Checked, try again in the list of documents. NetLock looks once more and creates a document only if there is none. Your confirmation allows one attempt.
Send again in the history repeats a job, but does not allow a new attempt for a document in Check at the vendor or Deleted at the vendor. For those, use Checked, try again or Create again in the list of documents.
The vendor key has access to the entire accounting. Use it only for this connection. Every draft is recorded in the audit log as invoice_draft_created, with tenant, month, lines and amount. A planned one has the user system. A failure of one tenant never pauses the connection.
An API key, created by an administrator in IT Glue under Account, Settings, API Keys. Use a dedicated key for NetLock. IT Glue shows a key only once and revokes it after 90 days without use, so a connection that was paused for a long time may need a new one.
The address of your data center: https://api.itglue.com, https://api.eu.itglue.com or https://api.au.itglue.com. No other address is accepted, so a stored key cannot go anywhere else.
In Settings → Integrations, open the IT Glue tile and choose Connect.
Enter the Instance address and the API key.
Under options, switch on Sync devices as assets: without it the connection does nothing. Check whether new configurations affect your IT Glue plan before you switch it on. Choose the Default configuration type, which IT Glue requires on every configuration, and optionally a Configuration status.
Map each tenant to an organization and its locations, or import the organizations. Tenants without a mapping are not included.
Optionally map device classes to configuration types.
Every hour NetLock sends the devices that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
A device becomes a configuration of the mapped organization, with NetLock-Device-<id> as asset tag.
A device is linked to an existing configuration by its serial number, provided that exactly one configuration of the organization has it, it is not archived, its asset tag is empty and no other device holds it. A configuration that already has a different asset tag is left alone, and the device gets a new configuration. A linked configuration keeps its name and type.
Manufacturer, model and operating system are lists in IT Glue. If IT Glue knows the exact name, it is selected. NetLock creates no entries in these lists: an unknown manufacturer or model goes into the notes of a new configuration, and the operating system is always written to Operating system notes.
Name, type and status are set when NetLock creates a configuration. An update sends only the values NetLock knows, among them the host name, and never changes name, type, status or notes.
A configuration that another system such as a PSA syncs accepts only a few attributes through the API. If IT Glue refuses the update and the configuration shows such a link, NetLock sends only the serial number and, if the field is empty, the asset tag. Any other refusal counts as a failed device.
A device that moved to another tenant gets a new configuration in the new organization. The old one stays.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed.
Nothing is deleted in IT Glue. The External systems tab of the device links to its configuration.
IT Glue answers a wrong or revoked key with status 403, which NetLock treats as a problem of the whole connection: it goes to Error until the key is replaced.
IT Glue allows 3000 requests in five minutes. NetLock waits when IT Glue reports the limit.
A self-hosted ITFlow instance, version 26.08 or newer. Older versions have no API for replies; the test of the connection shows that.
An API key, created in ITFlow under Admin, API keys. A key runs as its ITFlow user, with that user's role and client access, and has no separate limits. Use a dedicated user with access to the mapped clients only, and with the support module for tickets.
In Settings → Integrations, open the ITFlow tile and choose Connect.
Enter the Instance address and the API key. Allow unencrypted http is for an instance on an internal network only.
Under options, decide whether tickets are closed or only resolved at an all-clear, see below.
Map each tenant to a client and its locations, or import them. Tenants without a mapping are not included. Without a severity mapping the four severities follow the four priorities.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes a ticket of the mapped client, with the asset of the device if the asset sync linked one. The subject ends in [NetLock-Alert-<id>], and the reference is also stored in the vendor ticket number.
When the alert ends, the ticket gets an internal reply and is resolved if nobody is assigned. With Close tickets instead of resolving them it is closed as well.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets, and optionally map device classes to asset types or enter a Default asset type, which is free text in ITFlow.
Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
A device with the name of an existing asset of its client is linked to that asset, provided that exactly one such asset exists, it is not archived and no other device holds it. Otherwise a new asset is created.
An update sends only the values NetLock knows. Anything else you entered in ITFlow is kept.
A device that moved to another tenant gets a new asset at the new client. The old asset stays.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed.
For read requests, ITFlow accepts the key only in the request URL, so it appears in the access log of your ITFlow web server. NetLock keeps it out of its own history and logs. Use a dedicated key.
API keys of ITFlow expire. The connection then shows that the credentials are invalid or expired; create a new key and use Replace credentials.
ITFlow has no search for tickets. When a job has to be repeated, NetLock reads the tickets of the client to find out whether the ticket already exists. If it cannot read all of them, the job ends as failed without a new ticket, and you decide whether to use Send again.
In Settings → Integrations, open the Jira Service Management tile and choose Connect.
Enter the Instance address, the Account e-mail address and the API token.
Under options, choose the Status when closing: the done status a request moves to. If the workflow requires a resolution for that step, also choose a Resolution.
Map each tenant to a request type. The list shows every service desk with its request types, so tenants can be assigned to different service desks. Tenants without a mapping are not included. Severities can be mapped to Jira priorities; that only works if the field Priority is on the request type.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes a request of the mapped request type. The summary ends in [NetLock-Alert-<id>], which NetLock uses to find the request again.
When the alert ends, the request gets an internal comment. If nobody is assigned, it moves to the chosen status through the workflow transition that leads there.
NetLock does not guess a transition. If the workflow has no transition from the current status into the chosen one, the request stays open with its comment and the history shows no_transition.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
NetLock does not fill other required fields of a request type, so a request type with such fields refuses the ticket. Use a request type that needs only summary and description.
If a transition requires a resolution and none is chosen, or Jira refuses the transition for another reason, the request stays open and the history shows close_refused.
Organizations are not set on a request, and there is no company import. The tenant is named in the text of the request.
NetLock counts the devices of a tenant and creates one invoice draft per tenant and month in Lexware Office. A person checks the draft and finishes it there. NetLock never finishes an invoice and never sends one.
Tax: NetLock does not decide tax questions or calculate tax. This page is not tax advice. Have the tax cases you choose checked by your tax adviser, and check every draft.
A Lexware Office tariff with API access, for example the tariff XL.
An API key, created at https://app.lexware.de/addons/public-api. NetLock reads the id of your organization with it; documents belong to that organization and not to a connection. The key cannot be restricted; it has access to the whole account. Lexware may limit how long a key is valid; an expired key appears as rejected credentials.
Your company data in the general settings of Lexware Office. Lexware checks it at the latest when a document is finished.
A public API token with the scope usage:read, which the connection creates for you.
In Settings → Integrations, open the Lexware Office tile and choose Connect.
Enter the API key. The address of Lexware is fixed and cannot be changed.
Under options, enter a Closing text if you want one, see Reference.
Map each tenant to a customer contact. Tenants without a mapping are not included. There is no import: an accounting product also holds customers that are not tenants.
Activate the connection.
In the Billing tab, add a position for each thing you bill, see A.14.11.
Per draft: the contact of the tenant, the article and the quantity of each position, its price and tax rate, the service period, and the reference. No device names and no alert data go to Lexware.
A line refers to an article of Lexware Office. Name, unit, price and tax rate are read from the article when the draft is created. A price set on the position takes precedence over the price of the article; the tax rate stays that of the article.
If Lexware refuses the reference to the article, NetLock sends the same document once more with manual lines.
The invoice date is the day the draft is created, the service period is the counted month.
A draft has the status draft. The status cannot be changed through the API.
The texts of a document are German. According to the invoice guide of Lexware, the API creates German documents only.
The API of Lexware Office has no way to change or delete an invoice, and according to the guide of Lexware every invoice created through the API uses a number from the number range, even as a draft. A draft you delete in Lexware Office leaves a gap in the numbers.
NetLock therefore handles drafts as follows:
The plan is off by default. Without it, drafts are created only through Create drafts after a preview.
One document per tenant and period, all or nothing. A position that fails stops the whole document, because a partial invoice could not be completed later.
A call that ends without an answer is never repeated blindly. If Lexware does not show the document, the run shows Check at the vendor and waits for you, see A.14.11.
NetLock stays within the API limit of 2 requests per second, so a large preview can take a while.
Lexware has no internal field on an invoice. NetLock writes Referenz: NL-<tenant>-<yyyy-MM> as the last line of the closing text (Nachbemerkung). Your customer can read this line. NetLock uses it to find a document again after a failure, so it cannot be switched off.
A closing text sent through the API replaces the default of your account. If you want to keep yours, enter it under Closing text; it is placed before the reference.
If somebody removes the line from a draft, NetLock still knows the document. If creation failed at that moment, the run asks you to check.
The tax case is set per tenant in the Billing tab. For a contact in Germany, no choice is needed. For a contact in another country or without a billing address, you have to choose: without a chosen case no document is created, even on a small-business account.
Tax case
Tax type at Lexware
Tax rate of the lines
Domestic
net or gross, as in your account
From the article
Small business (from your account, no choice)
vatfree
0
EU, reverse charge
externalService13b
0
Third country
thirdPartyCountryService
0
The table follows the names Lexware gives its tax types.
vatfree only works for an account that is set up as tax free or as a small business, so the case Tax free is not available for Lexware. On such an account, no choice is needed for a contact in Germany; for a contact abroad a case still has to be chosen, and the document then stays vatfree.
externalService13b needs a contact of type company with a valid VAT id.
thirdPartyCountryService needs a contact with Allow tax free invoices. If Lexware refuses it, no document is created and the history says so.
A refused tax ends the job with The tax of this document is unclear, and nothing is created.
NetBox describes how your network should look, so NetLock does not change that description. It only adds its own fields to objects that already exist. Name, serial number, site, role, status and every other field stay as they are, and nothing is ever deleted.
NetBox 4 or later. The test of the connection reads the version from /api/status/.
An API token of a user who may read tenants, custom fields, sites, device roles and device types, and read and change devices and virtual machines. Use a v2 token and enter it in full, starting with nbt_. A v1 token still works, but NetBox deprecated it in 4.6 and removes it in 5.0, and the test says so.
The address of the instance, without /api.
The custom fields below, or the right to add custom fields if NetLock should create them.
Where the device opens in the console, if a public console address is set
Assign them to the object types dcim | device and virtualization | virtual machine. A field that exists only on one of them is written only there. Without netlock_device_id on a type, that type is not included.
With Create missing NetLock fields on, the next run creates the fields that do not exist at all, with the group NetLock. A field that already exists is never changed, even if its type is wrong or it is assigned to only one object type; the test of the connection reports both cases. netlock_device_id stays editable, the other fields can only be changed through the API.
The five fields above, and only those, one object at a time. A value NetLock does not know is left out. An object that already holds the same values is not written, so it does not appear in the change log of NetBox.
Every hour NetLock checks the devices that changed since the last run. The last contact is stored by day, so it changes an object at most once a day. Synchronize now starts a run immediately.
By exact match, within the mapped tenant, among devices and virtual machines. The first step that finds an object wins:
The object of the stored link.
The object whose netlock_device_id is the id of the device.
The object with the same serial number. Placeholders such as To Be Filled By O.E.M. are ignored.
The object with the same name.
Steps 3 and 4 ignore case. A prefix does not match, and a name with a domain does not match one without. If the name matches but both sides have a real serial number and the numbers differ, they are two machines and the device is skipped as ambiguous.
A device is skipped, without counting as a failure, when:
Reason in the history
Meaning
not_in_source
NetBox has no such object
ambiguous
Several objects fit, or the name fits and the serial numbers differ. Make the serial number or name unique, or set netlock_device_id on the right one
taken
The one object that fits belongs to another device, by a link or by its netlock_device_id. After a reinstallation a machine gets a new device id: clear netlock_device_id on the object, and the next run links it
fields_missing
netlock_device_id does not exist
create_incomplete
Creating is on, but a mapping or option for it is missing
Such a device does not count as a failure and is checked again a day later, or within the hour for fields_missing and create_incomplete. Saving the settings, changing a mapping or Synchronize now ends the wait. An object that moved to another tenant in NetBox, or whose netlock_device_id names another device, is no longer written. If no new match is found, the link is removed, so the device no longer shows the object.
The External systems tab of the device links to its object.
Create devices that are missing is off by default and should stay off where NetBox is maintained by hand. With it on, a device without a match becomes a new device in NetBox with the status Inventory, in the mapped tenant. Creating requires:
a device type for the device class, under Mappings,
Role of new devices,
a site, from the mapping of the location or from Site of new devices.
NetLock always creates devices, never virtual machines.
Odoo 17 or newer with the Helpdesk app, on a plan with access to the external API.
The API key of a dedicated user who may read and write helpdesk tickets and read companies, created under My Preferences, Account Security. Odoo keys can have an expiry date.
In Settings → Integrations, open the Odoo Helpdesk tile and choose Connect.
Enter the Instance address and the API key.
Odoo 19 and newer: leave Odoo 17 or 18 (JSON-RPC) off. Database is only needed when a server hosts several databases.
Odoo 17 and 18: switch it on and enter Database and Login.
Allow unencrypted http is for an instance on an internal network only.
The test reads the helpdesk teams and the fields of the ticket model, so a database without the Helpdesk app, or with different fields, is detected here and not at the first alert.
Under options, choose the Helpdesk team and the Stage when closing. Choose a stage of that team: the list shows the stages of all teams.
Map each tenant to a company, or import companies as tenants. Tenants without a mapping are not included. Without a severity mapping the four severities follow the four priorities.
Activate the connection.
Note: A ticket carries the mapped company as its customer. Odoo can e-mail the customer when a ticket reaches a stage with an e-mail template. Check the stages of the team before you connect, otherwise a customer gets an e-mail for every alert.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes a ticket in the chosen team. The name ends in [NetLock-Alert-<id>], which NetLock uses to find the ticket again.
When the alert ends, the ticket gets an internal note and moves to the chosen stage if nobody is assigned.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
A self client in the Zoho API console with its client id and client secret.
A refresh token of that client for the scopes SDPOnDemand.requests.ALL,SDPOnDemand.setup.READ,SDPOnDemand.general.READ. Generate an authorization code in the console and exchange it once, as described in the self client guide.
ServiceDesk Plus On-Premises
The API key of a technician, generated under Admin → Technicians/Users.
A version with the v3 API.
Both need a technician who may add, edit and close requests and read sites. API access depends on your ServiceDesk Plus edition.
In Settings → Integrations, open the ServiceDesk Plus tile and choose Connect.
Enter the Instance address.
Cloud: the address of your data center with your portal, for example https://sdpondemand.manageengine.eu/app/itdesk. Only the addresses of the data centers are accepted, so a custom domain does not work here.
On-Premises: switch on On-Premises installation and enter your server, for example https://sdp.example.com:8080. Allow unencrypted http is for an internal network only: the key is then sent unencrypted.
Enter the Client ID, Client secret and Refresh token for the cloud, or the API key (authtoken) for an installation.
Under options, set the Status when closing and, if a closure rule of your instance requires one, a Closure code. Status when closing applies to the cloud only and is the exact name of a status that closes a request; if the request then does not count as closed, the history shows close_refused. Requester of tickets is optional, see below.
Map each tenant to a site, or import sites as tenants. Tenants without a mapping are not included. Severities can be mapped to priorities.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes a request of the mapped site. The subject ends in [NetLock-Alert-<id>], which NetLock uses to find the request again.
Without a Requester of tickets, the account of the API is the requester, so no customer receives an e-mail about a request. With an address, your notification rules apply.
When the alert ends, the request gets a note hidden from the requester and is closed if no technician is assigned. The text of the note is also the closure comment.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
NetLock sends at most ten requests per minute and client to the cloud. Further alerts wait in the queue and arrive with a delay; other connections are not held up. If the cloud reports that the limit is reached, the jobs wait a minute and then continue.
Tenants map to sites. The test of the connection reads the list of sites and fails with a clear message if it gets no answer or the list is empty.
A closure rule of the instance can refuse the close. The note is added and the request stays open. The history shows close_refused.
If ServiceDesk Plus refuses the note, the request is left unchanged, because nobody could otherwise see why it ended. The history shows note_refused.
ServiceDesk Plus MSP is not covered by this connector.
An integration user with the role itil and read access to core_company, sys_user_group and sys_choice.
As an alternative, an OAuth client with client id and secret. The client credentials grant is off by default: an administrator of the instance has to switch it on and specify the user the client acts as. See Client credentials grant workflow.
In Settings → Integrations, open the ServiceNow tile and choose Connect.
Enter the Instance address, for example https://yourcompany.service-now.com. Only addresses under service-now.com are accepted.
Enter the Login name and Password of the integration user, or the OAuth client ID and OAuth client secret. With a client id, the user fields are ignored.
Under options, choose the Close code an incident is resolved with. The values come from your instance. Group sets the assignment group. Caller expects the sys_id of a user, for an instance that requires a caller.
Map each tenant to a company, or import companies as tenants. Tenants without a mapping are not included. Severities follow the impact and urgency of the default priority lookup unless they are mapped.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes an incident of the mapped company. The reference NetLock-Alert-<id> is stored in the correlation_id, which NetLock uses to find the incident again.
When the alert ends, the incident gets work notes and is set to Resolved with the chosen close code and the note as close notes, if nobody is assigned.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
Incidents only. NetLock writes nothing to the CMDB.
Domain separation is not supported.
If a data policy or business rule stops the resolve, or the instance answers without the new state, the note is kept and the incident stays open. The history shows close_refused.
If the instance refuses the work notes, the incident is left unchanged. The history shows note_refused.
NetLock does not change closed or canceled incidents.
If NetLock cannot confirm whether an incident exists, the job ends as failed and no second incident is created. Use an account without row filters on incidents.
Rate limits are configured on your instance. When a limit is reached, the instance answers with 429, and the jobs wait for the time it specifies.
NetLock counts the devices of a tenant and creates one invoice draft per tenant and month in sevdesk. A person checks the draft and finishes it there. NetLock never finishes, books or sends an invoice.
Tax: NetLock does not decide tax questions or calculate tax. This page is not tax advice. Have the tax cases you choose checked by your tax adviser, and check every draft.
A sevdesk tariff with API access, for example Buchhaltung Pro.
The API token of an administrator, 32 characters, from the user settings. The token cannot be restricted; it has access to the whole account, and it stays valid as long as the user exists. Use a dedicated sevdesk user for NetLock.
At least one contact and one invoice in sevdesk. The account and its price setting are read from them. Without them no draft is created.
A public API token with the scope usage:read, which the connection creates for you.
In Settings → Integrations, open the sevdesk tile and choose Connect.
Enter the API token. The address of sevdesk is fixed and cannot be changed.
Under options, choose the Contact person of the invoices. sevdesk requires a user on every invoice. The list comes from the invoices of your account; an account without any invoice shows a plain field for the number of the user.
Switch on Small business (§19 UStG) if that applies to you.
Map each tenant to a customer contact. Tenants without a mapping are not included. There is no import: an accounting product also holds customers that are not tenants.
Activate the connection.
In the Billing tab, add a position for each thing you bill, see A.14.11.
Per draft: the contact of the tenant, the part and the quantity of each position, its price and tax rate, the service period, the contact person and the reference. No device names and no alert data go to sevdesk.
A line refers to a part of sevdesk. Name, unit, price and tax rate are read from the part when the draft is created. A price set on the position takes precedence over the price of the part; the tax rate stays that of the part.
Prices follow your account: sevdesk works with net or gross prices depending on a setting that the API cannot read. NetLock takes it from the invoices of the account. With no invoice, or with both kinds among the latest ones, a document with tax is refused, because a wrong guess would change the amount by the tax. The test of the connection reports this.
The invoice date is the day the draft is created, the delivery period is the counted month.
The invoice is created as a draft. NetLock never prepares a document for sending, sends, books or finalises it.
The address comes from the first address of the contact.
The texts of the lines follow the language of the connection.
The reference NL-<tenant>-<yyyy-MM> is stored in the field Referenz/Bestellnummer of the invoice, which NetLock uses to find a document again after a failure. If you clear this field on a draft, NetLock still knows the document. If creation failed at that moment, the run asks you to check.
The tax case is set per tenant in the Billing tab. For a contact in Germany, no choice is needed. For a contact in another country or without an address, you have to choose: without a chosen case no document is created, even on a small-business account.
Tax case
Tax rule of sevdesk
Tax rate of the lines
Domestic
1, Umsatzsteuerpflichtige Umsätze
From the part
Small business (from the option, no choice)
11, Steuer nicht erhoben nach §19 UStG
0
EU, reverse charge
21, Reverse Charge gem. §18b UStG
0
Third country
17, Nicht im Inland steuerbare Leistung
0
Tax free
4, Steuerfreie Umsätze §4 UStG
0
The table follows the names sevdesk gives its rules. If sevdesk does not allow the rate for a rule, the job ends with The tax of this document is unclear, and nothing is created.
An account on the old bookkeeping system 1.0 has a tax type instead of a rule. There NetLock offers Domestic, Third country and the small business, the cases that have an exact counterpart. The other two cases end the job the same way.
Any country other than the one with the number 1 in sevdesk counts as abroad, even if the contact is in Germany under another entry. The preview shows the number.
The contact person comes from your invoices.
NetLock shows the number of a document, no link.
A draft you correct in sevdesk is not read back. NetLock keeps what it sent.
If sevdesk reports a limit, the job waits and tries again.
Snipe-IT records what you own, so NetLock does not change that record. It only fills the columns you choose on assets that already exist. Asset tag, name, serial number, model, status, location, assignment and notes stay as they are, and nothing is ever deleted.
Snipe-IT 8 or later. The test of the connection reads the version and refuses an older one.
A personal access token of an account that may read and edit assets and read companies, models, status labels and custom fields. It is created in your profile under Manage API Keys.
The address of the instance, without /api.
Custom fields for the values of NetLock, added to the fieldsets of your models. Their name must contain NetLock. NetLock does not offer or write any other field, so a field you maintain cannot be overwritten by mistake.
Suggested name
Content
NetLock device id
The id of the device in NetLock. Required
NetLock last seen
The day of the last contact
NetLock OS
Operating system
NetLock agent version
Version of the agent
NetLock URL
Where the device opens in the console, if a public console address is set
Use plain text fields without encryption. An asset whose model has no field for the device id is skipped with fields_missing.
Tenants map to companies, which requires Full Multiple Companies Support. For an instance without companies, see below.
In Settings → Integrations, open the Snipe-IT tile and choose Connect.
Enter the Instance address and the API token. Allow unencrypted http is for an instance on an internal network only.
Under options, choose the field for each value. The lists are read live from Snipe-IT. Only Field for the device id is required; a field left empty is not written.
Switch on Sync devices as assets. It is off by default: without it the connection does nothing.
Map each tenant to a company, or import the companies. Tenants without a mapping are not included.
Activate the connection.
The test of the connection shows the version of Snipe-IT and reports when a field is missing or no company exists. It writes nothing.
With This instance uses no companies on, the mappings offer one company for all assets, which several tenants can share. Names are then not unique across tenants, so only the serial number and the device id field are used to match a device.
The chosen columns, and only those. A value NetLock does not know is left out. An asset that already holds the same values is not written, so it does not appear in the history of Snipe-IT.
Every hour NetLock checks the devices that changed since the last run. The last contact is stored by day. Synchronize now starts a run immediately.
By exact match, within the mapped company. The first step that finds an asset wins:
The asset of the stored link. A deleted asset is treated as missing.
The asset whose device id field holds the id of the device.
The asset with the same serial number. Placeholders such as To Be Filled By O.E.M. are ignored.
The asset with the same name.
Steps 3 and 4 ignore case. If the name matches but both sides have a real serial number and the numbers differ, they are two machines and the device is skipped as ambiguous.
A device is skipped, without counting as a failure, when:
Reason in the history
Meaning
not_in_source
Snipe-IT has no such asset
ambiguous
Several assets fit, or the name fits and the serial numbers differ. Make the serial number or name unique, or fill the device id field of the right one
taken
The one asset that fits belongs to another device. After a reinstallation a machine gets a new device id: clear the device id field of the asset, and the next run links it
fields_missing
No field for the device id is chosen, or the model of the asset does not have it
create_incomplete
Creating is on, but a mapping or option for it is missing
Such a device does not count as a failure and is checked again a day later, or within the hour for fields_missing and create_incomplete. Saving the settings, changing a mapping or Synchronize now ends the wait. An asset that moved to another company, or whose device id field names another device, is no longer written. If no new match is found, the link is removed, so the device no longer shows the asset.
The External systems tab of the device links to its asset.
Create assets that are missing is off by default. With it on, a device without a match becomes a new asset in the mapped company. Creating requires a model for the device class under Mappings and a Status label of new assets. The asset tag is NL-<device id>; with Snipe-IT numbers new assets on, Snipe-IT sets it, which requires automatic asset tags in its settings. The model has to carry the chosen fields, otherwise Snipe-IT refuses the asset.
NetLock treats a refusal by Snipe-IT as a failure of the device and names the fields concerned.
Snipe-IT allows 120 requests a minute per user by default. NetLock stays below that with one request every 0.55 seconds, so a large first run takes several hourly jobs. A lower limit of your instance is respected when Snipe-IT reports it.
Data flows in one direction only: Snipe-IT data does not flow into NetLock.
The connection uses two credentials, because the TANSS API requires different credentials for different functions:
A login of a technician, for tickets, comments and devices. Use a dedicated technician for this connection, with access to the mapped companies and without two-factor authentication: a connection cannot enter a code. A login of a customer is refused by the test.
An API token of the external role ERP, created in TANSS, for the list of all companies. The test checks it as well.
For the device sync, the technician also needs the rights for PCs and peripherals.
In Settings → Integrations, open the TANSS tile and choose Connect.
Enter the Instance address, the Login name, the Password and the API token (role ERP). Allow unencrypted http is for an instance on an internal network only.
Under options, choose the Status when closing. TANSS does not mark a status as closing, so choose the status your tickets end in. Status of new tickets, Ticket type and Department are optional.
Map each tenant to a company, or import the companies as tenants. Tenants without a mapping are not included. Inactive companies are not offered.
Optionally map the severities to ticket types: a TANSS ticket has no priority field.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name, operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes a ticket of the mapped company, without a remitter, assigned to the PC of the device if the asset sync linked one. The reference NetLock-Alert-<id> is stored in the external ticket id.
When the alert ends, the ticket gets an internal comment and the closing status, if no technician is assigned. A department alone does not count as assigned.
If TANSS refuses the status, the ticket keeps its comment and stays open, and the history says close_refused. A missing permission still fails the job.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets. Devices are created as PCs; a device with Server in the name of its operating system is marked as a server. To send a device class to the peripherals instead, map it to a periphery type.
Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
A device carries NetLock-Device-<id> as inventory number, which NetLock uses to find it again.
A device with the name of an existing device of the company is linked to that device, provided that exactly one such active device exists, it has no inventory number yet and no other device holds it.
Operating system and manufacturer are set when TANSS knows a value of exactly that name. NetLock creates no entries in these lists. All values are also written to a marked block of the remark. Text outside that block is kept.
An update sends only name, company, inventory number, model or type, serial number, operating system, manufacturer and remark.
An object that carries another inventory number is left alone and the device is named in the history.
If the class of a device maps to the other kind of object later, the existing object stays and the device is named in the history. Set the mapping back, or delete the old object in TANSS to create the new one.
A device that moved to another tenant moves to the new company.
A device that fails is named in the history and waits for the next hourly run; the other devices are still processed.
Components such as CPU, memory and disks are not sent, only the device itself.
IP and MAC address go into the address list of a device only when it is created. Later changes are written only to the remark.
A periphery is not assigned to tickets. Its model goes into type, and it has no operating system.
TANSS has no search for the external ticket id. When a job has to be repeated, NetLock reads the tickets of the company to find out whether the ticket already exists. If it cannot read all of them, the job ends as failed without a new ticket, and you decide whether to use Send again.
A TOPdesk operator or API account with the permission REST API and the write permission Use application tokens, and the rights to create, read and edit first or second line incidents. Branch filters of the account apply, so it has to see the mapped branches. For the device sync, use an account without branch filters: an assignment it cannot see counts as no assignment.
An application token, created in TOPdesk under My settings or on the card of the API account. A token expires on the date set there, by default after one year. The connection then shows that the credentials are invalid or expired; create a new token and use Replace credentials.
For the device sync, permissions for Asset Management.
In Settings → Integrations, open the TOPdesk tile and choose Connect.
Enter the Instance address, the Login name and the Application token. Allow unencrypted http is for an instance on an internal network only.
Under options, choose the caller, the Incident line, and optionally the operator group, category, subcategory, call type and entry type of new incidents.
Set how incidents close, see below.
Map each tenant to a branch, or import the branches as tenants. Tenants without a mapping are not included.
Map the severities. Each one maps to a priority or to a pair of impact and urgency, from which TOPdesk derives the priority through its matrix. Without a mapping TOPdesk applies its own default.
By default, the caller of an incident is an unregistered caller named after Caller name, in the mapped branch. With Registered caller (e-mail address) the person with that address is the caller of the incidents of their own branch; the person needs the caller role on their card, and the account has to be allowed to read persons. A registered caller always carries the branch from their card, so incidents of all other branches keep the unregistered caller, and branch filters and reports per customer keep working.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
With the asset sync on, also: device name and its NetLock device id, and with Field for device details set the operating system, manufacturer, model, serial number, IP address and MAC address.
An alert becomes an incident of the mapped branch. TOPdesk limits the brief description to 80 characters, so a long title is cut. The reference NetLock-Alert-<id> is stored in the External number of the incident.
When the alert ends, the incident gets an action that is invisible to the caller and is closed if nobody is working on it. An operator group alone does not count as assigned; an operator does.
With a status in Status when closing NetLock sets that processing status. Whether it closes the incident depends on the settings of the status in TOPdesk; if it does not, the incident stays open and the history says no_transition. Without a status NetLock sets the incident to closed directly. Closure code is sent as well.
If TOPdesk refuses to close, for example because of a setting of the status, the incident stays open with its note, and the history says close_refused.
An archived incident cannot be changed, not even with a note.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes an incident whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The sync is off by default. Switch on Sync devices as assets, and map device classes to asset templates or choose a Default asset type.
The fields of an asset belong to its template and differ per installation. NetLock only sets the name, and fills the text field you choose in Field for device details with the remaining values. If the template requires fields that NetLock does not know, creating the asset fails, and the device is named in the history.
Every hour NetLock sends the authorized devices of the mapped tenants that changed since the last run, at most 200 per run; if more devices changed, the next run starts right after. Synchronize now starts a run immediately.
TOPdesk requires a name that is unique among all assets, while host names repeat across customers. A new asset is therefore named <host> (NetLock-<id>), and the name is updated when the device is renamed.
A new asset is assigned to the branch of its tenant.
A device with the plain host name of an existing asset of the template is linked to that asset, which keeps its name, provided that exactly one such asset exists, it is not archived, no other device holds it, and it is not assigned to another branch.
A device that moved to another tenant keeps its asset and is named in the history, because TOPdesk would show the asset at both branches. Move the assignment by hand.
A device that fails is named in the history and waits for the next run; the other devices are still processed.
An alert of a synced device links the asset to the incident.
NetLock reads Wazuh and writes nothing there. By default it reads only agents that stay disconnected and alerts from level 12 on, because Wazuh and the NetLock agent can see the same event.
NetLock calls Wazuh, so the server has to reach it.
Self-hosted NetLock in the same network: works. Private addresses are allowed.
NetLock Cloud: an instance in the cloud reaches public addresses only. A Wazuh in a private network cannot be connected from there. Publishing the API of Wazuh on the internet just for this is not recommended.
Wazuh 4. The connector reads the version from the server API and refuses any other major version, because the API changes with it. The test of the connection reports this.
A user of the server API, port 55000. A dedicated user with the role readonly is enough.
For alerts and vulnerabilities, the indexer, port 9200, with a user who may read wazuh-alerts-* and wazuh-states-vulnerabilities-*. Alerts are stored only in the indexer. Without it NetLock reads only the agent status, and the history shows a note.
NetLock accepts valid certificates only and has no switch to turn that off. The certificates of a default Wazuh installation are self-signed and are refused; the test of the connection then fails with a network error.
Issue certificates for the names you enter in NetLock, from a public CA or your own CA.
Server API: set key and cert in the https section of /var/ossec/api/configuration/api.yaml, then restart wazuh-manager.
Indexer: replace the certificates as the documentation of Wazuh describes for your installation.
With your own CA, add it to the trust store of the hosts or containers that run the NetLock web console and server. Both call Wazuh: the console for the test, the server for the pulls.
In Settings → Integrations, open the Wazuh tile and choose Connect.
Enter the address of the server API with its port, such as https://wazuh.example.com:55000, its user and password.
Enter the address of the indexer with its port, its user and password. Leave them empty to read only the agent status.
The test of the connection shows the version and the number of agents, and checks that the indexer can be searched.
Under options, choose what to read.
Map each tenant to an agent group, or import the groups. Wazuh has no tenants, so a group represents a customer. Groups without a mapping are not included.
Activate the connection.
The token of the connection needs the scopes devices:read, alerts:ingest and external-refs:read.
An agent has to be in exactly one mapped group. An agent in two mapped groups could belong to either tenant: it reports nothing new, its open alerts stay open, and the Log tab shows a note. Every agent starts in the group default, so that group should usually stay unmapped.
Every five minutes NetLock queries Wazuh and reports through POST /v1/alerts/ingest with the token of the connection. Synchronize now starts a pull immediately.
The first pull only records the current state: existing problems open no alert and no ticket until they change. The Overview tab shows how many there are. A hit in a later hour than the newest one recorded counts as a change.
Part
Source
Default
Becomes
Disconnected agents
Server API
On
One alert per agent, moderate, after the agent is away for Disconnected for at least minutes (default 60). It ends when the agent is back
Alerts
Indexer
On, from level 12
One alert per agent and rule. It ends 24 hours after its last hit
Critical vulnerabilities
Indexer
Off
One alert per agent with their number, high. It ends when the agent has none left
Levels become severities: 7 to 11 moderate, 12 to 14 high, 15 critical. Alerts from level accepts values from 7 to 15. SCA and file integrity results are not read.
Alerts are events, so NetLock reads the last 24 hours on every pull, as one total per agent and rule. There is no limit on the number of hits. An open alert is written again at most once an hour, however often its rule fires.
After a pause NetLock reads back to its last good pull, at most seven days, and continues to read that far back for a day. A hit from the pause therefore opens an alert that stays open for 24 hours, like any other. Switching Report alerts off discards the last pull: when you switch it back on, NetLock reads the usual 24 hours.
When a mapping changes, open alerts end at the old tenant and open at the new one; if the mapping is removed, they end. Switching off a part ends the alerts it left open.
NetLock tries these in order, always within the tenant of the group:
An external reference of the device for the system wazuh, set through the public API with the agent id.
The match of an earlier pull.
The name of the agent, if exactly one device of the tenant has it. Case and domain are ignored.
Two tenants can hold a device of the same name: an agent only ever matches within the tenant of its group. A reference contains only the agent id, so with two managers in one tenant it applies to the agent with that id on both. Without a match the report goes to the tenant. If Report unmatched devices for the tenant is off, it is skipped and counted. The External systems tab of the device shows its agent and open reports.
If the indexer does not answer, or a part of it fails, disconnected agents still arrive. No alert is treated as ended; the pull reports the failure and the next one tries again. The Log tab shows the failure. If Report disconnected agents is off, the whole pull fails.
@timestamp is the time of the alert, not of its arrival in the indexer. Alerts that reach the indexer more than 24 hours late, for example after a long stop of Filebeat, fall outside the window and are not read.
The index of vulnerabilities appears with the first scan of Wazuh 4.8 or later. Without it the option reads nothing and ends no alerts, and the test and the Log tab show a note.
If no pull succeeds for a day, the connection stays active and shows a note.
If the vulnerability list cannot be read in full, no vulnerability alert is ended.
A condition that stays the same is reported again once a day, so its alert does not run into the time limit for open alerts.
The manager allows 300 requests a minute by default. NetLock waits when Wazuh reports the limit. A login that is refused is not repeated for five minutes, because Wazuh blocks a client after too many of them.
A Zammad instance with API Token Access switched on.
An access token of an agent, created in the Zammad profile under Token Access. It needs the permissions ticket.agent and admin.group, and its account needs access to the target group.
In Settings → Integrations, open the Zammad tile and choose Connect.
Enter the Instance address, for example https://helpdesk.example.com, and the Access token. Allow unencrypted http is for an instance on an internal network only: the token is then sent unencrypted with every request.
Under options, choose the Group that receives the tickets, the Status when closing, and the customer for tickets without an organization member. This is an e-mail address; Zammad creates the user if it does not exist.
Map each tenant to an organization, or import organizations as tenants. Tenants without a mapping are not included. Severities can be mapped to Zammad priorities; without a mapping Zammad uses its default priority.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
An alert becomes a ticket in the chosen group, with the alert as an internal note. The title ends in [NetLock-Alert-<id>], which NetLock uses to find the ticket again.
A Zammad ticket belongs to an organization through its customer, so NetLock uses the first member of the mapped organization as customer. Without members the configured customer is used, and the ticket does not belong to the organization.
When the alert ends, the ticket gets an internal note and goes to the chosen status if nobody is assigned. A ticket counts as unassigned while it has the empty default owner of Zammad.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
The article is internal, but the title of the ticket is visible to the customer and to members of a shared organization in the customer interface.
If Zammad refuses to close the ticket, for example because of a Core Workflow, the note is added and the ticket stays open. The history shows close_refused.
A Zendesk Support account. The request limits depend on the plan.
An OAuth client of the kind Confidential, created by an admin in the Admin Center under Apps and integrations → APIs → OAuth clients. NetLock uses the client credentials grant with the scopes tickets:read tickets:write users:read users:write organizations:read groups:read. If the client restricts its allowed scopes, they have to include these.
Tokens of this grant act for the admin who created the client. They stop working when that admin is deleted or loses the permission, so use a dedicated admin account.
As a fallback, an API token with the e-mail address of the same kind of account. Zendesk has marked API tokens as deprecated, without a date.
The account behind the client or the token has to be an admin, or an agent in a custom role that may manage end users. The test of the connection checks this.
A ticket can only be solved with an assignee, so this account has to be a member of the group the tickets are in.
The OAuth client belongs to your Zendesk account and stays there.
In Settings → Integrations, open the Zendesk tile and choose Connect.
Enter the Instance address, for example https://yourcompany.zendesk.com. Only addresses under zendesk.com are accepted, so host-mapped domains do not work here.
Enter the OAuth client identifier and the OAuth client secret. Without a client, enter the Account e-mail address and the API token instead.
Under options, choose a Group if tickets should go to one. If left empty, the rules of the account decide.
Map each tenant to an organization, or import organizations as tenants. Tenants without a mapping are not included. Severities follow the priorities Low, Normal, High and Urgent unless they are mapped.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
For each organization that receives tickets, NetLock also creates one end user named NetLock RMM, with the external id netlock-company-<organization id> and no e-mail address.
An alert becomes a ticket of the mapped organization. The reference NetLock-Alert-<id> is stored in the external_id of the ticket, which NetLock uses to find it again.
A ticket belongs to an organization through its requester. The requester is the end user of that organization. Because that user has no e-mail address, triggers cannot send any e-mail, and end users need no license. No e-mail goes to the customer, but where an organization shares tickets in the help center, its users may see the subject.
The API user remains the submitter, and the first comment is an internal note.
When the alert ends, the ticket gets an internal note and is set to Solved if nobody is assigned. Zendesk cannot solve a ticket without an assignee, so the account of the connection becomes the assignee, which also appears in reports per agent.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
If required fields prevent the ticket from being solved, or the account is not in the group of the ticket, the note is added and the ticket stays open. The history shows close_refused.
A ticket in the status Closed cannot be changed, so an all-clear leaves it as it is.
A Zoho Desk organization. Its edition sets the daily API credits; the Free edition has 5 000.
A self client in the Zoho API console with its client id and client secret.
A refresh token of that client for the scopes Desk.tickets.ALL,Desk.accounts.READ,Desk.contacts.READ,Desk.contacts.CREATE,Desk.basic.READ. Generate an authorization code in the console and exchange it once, as described in the self client guide. The refresh token does not expire.
The user of the token needs a profile that may create contacts and comment on tickets.
The organization id, shown in Zoho Desk under Setup → Developer Space → API.
In Settings → Integrations, open the Zoho Desk tile and choose Connect.
Enter the Instance address of your data center: https://desk.zoho.com, .eu, .in, .com.au, .jp, .sa, .uk, .sg, .ae or https://desk.zohocloud.ca. It also determines the accounts server. Other addresses are refused.
Enter the Organization ID, Client ID, Client secret and Refresh token.
Under options, choose the Department that receives the tickets and the Status when closing.
Map each tenant to an account, or import accounts as tenants. Tenants without a mapping are not included. Severities can be mapped to the priorities of Zoho Desk; without a mapping the default of the department applies.
For every alert that passes the filter of the connection: a title, the severity, tenant, location and device name, the source, first and last time seen, the alert text, and a link to the web console if the public console URL is set. Check that this matches your data processing agreements before you activate the connection.
For each account that receives tickets, NetLock also creates one contact named NetLock RMM without an e-mail address, unless it already exists.
An alert becomes a ticket of the mapped account in the chosen department. The subject ends in [NetLock-Alert-<id>], which NetLock uses to find the ticket again.
The contact of the ticket is the NetLock RMM contact of the account. It has no address, so department notifications cannot be sent to it. No e-mail goes to the customer, but what a help center shows depends on your settings.
When the alert ends, the ticket gets a private comment and goes to the chosen status if nobody is assigned.
The behaviour is set in the Settings tab, see A.14.4. NetLock never closes a ticket whose status somebody changed in the meantime, and it never deletes anything at the vendor.
Every read and write uses the daily API credits. Lists are read during setup and when a ticket is created, never on a schedule. When the credits run out, Zoho answers with a time to wait, and the jobs wait for it.
New tickets take minutes to reach the search of Zoho Desk, so a repeated job reads the ticket list of the department instead. If that department has too many new tickets to look through, the job ends as failed and no second ticket is created. Check the department, then use Send again.
Zoho allows ten access tokens per ten minutes.
If Zoho Desk refuses to close the ticket, for example because of a required field, the note is added and the ticket stays open. The history shows close_refused.
If Zoho Desk refuses the comment, the ticket is left unchanged, because nobody could otherwise see why it ended. The history shows note_refused.
A repeated job only looks in the chosen department. If a rule moves new tickets elsewhere right away, a repeat can create a second ticket.
Alphabetical reference for terms that carry a specific NetLock RMM meaning. When a term is ambiguous in general IT usage, this glossary reflects what the product does, not what the word means elsewhere. Every entry points to the chapter that owns the subject in full.
Agent. The software installed on every managed device. It reports status, runs scheduled Jobs and Sensors, enforces the assigned Policy, and terminates remote-access sessions on the device side. Supported on Windows, Linux, and macOS. See Chapter 2 — Core Concepts and Chapter 3 — Devices.
AI Chat. The chat page at /ai-chat that operators use to ask an LLM about devices, events, or scripts, and optionally save generated scripts back into Collections. Off by default; configured under Settings → AI / LLM. See Chapter 13 and A.11.
App Hub. The software catalogue under Collections. Entries come from Winget (Windows), Flathub (Linux), Chocolatey, or manual scripted packages. The App Hub itself is a catalogue; installation runs through Software Deployment. See Chapter 8.5.
Application Control. The allowlisting feature under Collections. Rulesets define which applications may execute on Windows devices, matched by path, metadata, hash, or code-signing certificate. Rulesets attach to devices through Policy Settings → Windows → Application Control. See Chapter 8.6.
Audit. The administrative trail at /audit. Every configuration change (user created, policy saved, automation edited) is recorded with the acting user, source IP, and timestamp. Distinct from Events. See Chapter 12.
Authorized device. A device that has been approved from the Unauthorized queue and now appears in the main inventory. Contrast with Unauthorized device. See Chapter 3.2.
Automation. A rule with a list of conditions that all have to hold (organisation, device attributes, inventory or custom fields, each one negatable), an explicit priority (lower wins) and an action: assign one named Policy and/or add Sensors and Jobs from the library. Among the matching rules the lowest priority that assigns a policy decides the policy; the items of every matching rule are added. Automations have no event triggers or schedules and perform no other actions. See Chapter 5.
Brand template. A reusable cover-page, colour, logo, and PDF-footer bundle applied to generated Reports. Managed on the Brands tab of the Reports page. See Chapter 11.
Collection. The umbrella for eight reusable libraries: Scripts, Jobs, Sensors, Custom Fields, App Hub, Application Control rulesets, Device Control entries, and Software Deployments. You build library items once and reference them from Policies, Automations, or standalone actions. See Chapter 8.
Community. The integration layer that connects a deployment to the shared NetLock RMM catalogues of Scripts, Reports, and Whitelabeling themes. It has no page of its own; each community feature sits inside its parent feature. Authentication is deployment-level through a Members Portal API key. See Chapter 15.
Custom field. A device attribute defined in Collections. Field types are Text, Multiline, Table, and Secret. Data sources can be Manual entry, a parsed Job result, or a SQL query. A manual field marked inheritable can also hold values on group, location, tenant and global level, which a device without a value of its own inherits. Custom fields render as tabs and sections on the device detail page; scripts read them through variables and can write them back. See Chapter 8.4.
Dashboard panel. A widget on a Dashboard, backed by a SQL query. Panels are composed in the Panel Builder; a panel with its own SQL statement runs as the report user configured under Settings → SQL access. See Chapter 2 and A.12.
Department. In the Ticket System, a team-level container holding its own mailbox, operators, SLA defaults, templates, and webhooks. Every ticket lives in exactly one department. See Chapter 10.9.
Device. A managed computer (workstation, laptop, or server) that runs the Agent. Devices carry a hostname, a human-readable label, one Policy at a time, and any Custom Fields defined for the deployment. See Chapter 3.
Device Control. The USB-peripheral allowlisting feature under Collections. Entries match by vendor id, product id, serial, or device class, and scope to a device, tenant, location, group, or globally. Entries are added by approving a blocked device on the Blocked Devices tab or by a device learning its connected devices during its learning period; there is no create dialog. See Chapter 8.7.
Events. The operational activity stream at /events. Events record things that happened on or to devices, such as script results, sensor breaches, policy deployments, and antivirus detections. Contrast with Audit, which records configuration changes. See Chapter 12.
Group. The innermost level of the tenant hierarchy. A group belongs to exactly one location, which belongs to exactly one tenant. Groups are typically used to reflect device role or configuration rather than physical location. See Chapter 4.
Hardware ID. The identifier of a device's operating system installation as the Agent reports it. A new operating system installation gives a new hardware ID; replacing hardware does not. The Server shows it in the authentication log; a changed hardware ID does not take the authorization away. See Debug an agent.
Job. A Scripts-plus-schedule binding under Collections. A Job says "run this Script on the device on this trigger": System Boot, a fixed Date/Time, a recurring interval, or recurring on named weekdays. A Job may be marked hidden, in which case it is excluded from Events and typically drives a Custom Field. Not to be confused with an operating-system scheduled task. See Chapter 8.2.
Label. A free-text display name for a device, editable per-device. The label replaces the hostname in Console lists, event feeds, reports, and audit entries. See Chapter 3.1.
Location. The middle level of the tenant hierarchy. A location belongs to exactly one tenant and contains one or more groups. Typically maps to a physical site. See Chapter 4.
Members Portal. The external identity and catalogue service that NetLock RMM uses for community features (Scripts, Reports, Themes). Authentication is deployment-level via a single API key stored in the Console settings. Individual operators do not sign in to the Members Portal. See Chapter 15.
Policy. A named bundle of desired device configuration: agent behaviour, tray icon, Windows Defender, Application Control, Device Control, Linux UFW, Sensors, Jobs, per-platform patch rollout, and App Hub exposure. A device is assigned at most one Policy at a time. Policies are not layered or merged, and they have no version history or rollback. See Chapter 6.
Public API. The REST API under /v1 of the server, used by external systems with a Bearer token created under Settings → API tokens. A token is bound to a console account and carries scopes, a tenant scope and a rate limit; the server serves its own Swagger reference at /docs. See X.9.
Relay. A server-side tunnelling service that lets the Console reach a device's TCP port through a relay connection when a direct connection is not possible. Used for Remote Control and for ad-hoc TCP forwarding. See Chapter 9.2.
Remote Control. The live screen-and-input session to a device, opened from the Console, the Relay App or the NetLock app. The agent streams the screen as JPEG frames through the NetLock server. The product does not use VNC or RDP. See Chapter 3.5 and A.7.
Report user. The dedicated MySQL user that custom SQL in reports, dashboard SQL panels and SQL custom fields runs as. It holds only SELECT grants on the NetLock database, and those grants decide what such SQL can read. See SQL access.
Requester. The Windows account (DOMAIN\user) that opened a ticket from the tray icon of a device. The agent sets it from the signed-in Windows user who opened the ticket; the user cannot type it in. Together with the device it decides which tickets the tray icon shows: only the requester's own tickets from that device, and never internal notes. Shown on the Details tab of such a ticket as Windows user. See Chapter 10.6 and §6.5.
Ruleset. In Application Control, a named list of rules that together form an allowlist for a set of devices. A ruleset is attached to devices through Policy Settings → Windows → Application Control. See Chapter 8.6.
Script. A snippet of PowerShell, Bash, Zsh, Python3, or MySQL stored in the Scripts library under Collections. Scripts run ad-hoc from the device detail page, on a schedule via Jobs, as the action of a Sensor breach, or from a remote shell. See Chapter 8.1.
Script variable. A token of the form {{namespace.key}} in a script, resolved per device when the script is handed out: device for built-ins such as the device name, field for a custom field with inheritance, and tenant, location, group and global for one level. Each variable also has a native environment name such as NL_FIELD_AV_OU_ID. See Script variables and custom fields in scripts.
Secret field. A custom field of type Secret. Its values are stored encrypted, shown masked in the console and never returned by the public API; revealing one needs collections_custom_fields_reveal_secrets and is audited. See Chapter 8.4.
Sensor. A per-policy metric collected by the Agent on an interval, such as CPU, memory, disk, an event log matcher, a ping, an SNMP probe, or the output of a script. Sensors carry severity-based thresholds for notification and for triggering an action Script. See Chapter 8.3.
Server. The central service the Console reads from and Agents report to. In a cloud deployment the vendor runs it; in a self-hosted deployment the customer runs it. See Chapter 1.2 — Core Concepts.
SLA. In the Ticket System, a response-and-resolution clock attached to a ticket through its priority and department. SLA states are Compliant, At Risk, and Overdue; thresholds are configured per priority. The Patch Management page uses the same three states against default thresholds (7 / 15 / 30 / 60 days by severity) for patch compliance. See Chapter 10.15 for tickets and Chapter 7.4 for patches.
Software Deployment. The packaged-deployment feature under Collections. A four-step wizard composes a target set and a sequence of App Hub entries to install, and the deployment tracks per-device attempt outcomes. It is the only direct path from the App Hub catalogue to installation on devices. See Chapter 8.8.
SQL access. The setting under Settings → SQL access (/settings/sql-access, self-hosted only) that holds the report user. Without it, only the statements of the built-in report templates run; custom SQL and the query builders are disabled. See Set up SQL access and A.12.
SSO. Single sign-on via OpenID Connect. Five providers are supported (Azure AD, Keycloak, Google, Okta, Auth0), and exactly one can be active at a time. SAML 2.0 is not supported. See A.4.
Tenant. The top-level organisational container. For an in-house IT team it typically maps to the company itself; for an MSP it maps to one customer organisation. Tenants contain Locations, which contain Groups. See Chapter 4.
Ticket. The optional helpdesk unit of work. A ticket has a status, a priority, a department, a contact, an SLA clock, a conversation, a time-tracking log, and an audit trail. See Chapter 10.
Tray Icon. The small application the Agent exposes on Windows, Linux, and macOS devices to end users. Branding and visibility are controlled per-policy; the apps exposed in the tray menu are drawn from the App Hub selections on the policy. See Chapter 6.5.
Unauthorized device. A device whose Agent has contacted the Server but not yet been approved. Unauthorized devices sit at /unauthorized_devices until an operator authorises or rejects them. They do not appear in the main inventory. See Chapter 3.2.
Whitelist(Device Control). In Device Control, the allowlist of USB and peripheral devices permitted to attach to in-scope devices. Entries are added by approving a blocked device on the Blocked Devices tab or by a device learning its connected devices during its learning period. See Chapter 8.7.
Whitelabeling. The branding feature at Settings → Whitelabeling that replaces logos, colours, and accent text across the Console. Whitelabeling also hosts the Community Themes browser, which imports or publishes full themes. See A.6.
Write-back. Setting a custom field value from a script with Set-NetLockField, nl_field_set or a hand-written NETLOCK_FIELD_SET: marker line. The value is stored on the device the script runs on with the source script. See Write custom field values from a script.
A receiver of a webhook has to answer two questions: did this request really come from NetLock RMM, and was its body changed on the way? A signature answers both. NetLock RMM computes it with a secret that only the instance and the receiver know, and sends it in the header X-NetLock-Signature.
The signature covers the timestamp and the body. It does not cover the URL, the query string, the method or any other header, so do not base a decision on those alone.
With the switch off, requests of the notification channel and of ticket webhooks are sent unchanged.
Slack, Microsoft Teams, Discord and ntfy ignore signatures. The switch only helps with a receiver that checks them, such as your own endpoint or an automation platform.
v1 is the lowercase hex HMAC-SHA256 of the exact string t + "." + body, keyed with the secret as UTF-8 text.
body is exactly what the request carries, as UTF-8. A request that carries no body, which is every GET and a test from a dialog with an empty template, is signed over the empty string. A real event with an empty template carries the default JSON document, and that is what is signed.
If the receiver has to tell requests without a body apart, use a method with a body.
Use this vector to test your code: the secret whsec_test, t = 1700000000 and the body {"type":"webhook.test"} give the v1 shown above.
Read the raw bytes of the body before any parser touches them. Parsing and serializing JSON again changes the bytes, and the signature no longer matches.
Split the header into t and v1.
Reject the request if t is more than a few minutes away from your own clock. Five minutes is a good value. That is what makes a captured request useless later: the timestamp is part of what is signed, so it cannot be moved forward.
Compute HMAC-SHA256 over t, a dot and the raw body, and compare it to v1 in constant time.
Answer with a 2xx status. A redirect is not followed and counts as failed.
The delivery id in X-NetLock-Delivery repeats when a signed webhook is delivered again, with a new t and a new signature. Use it to detect duplicates.
import hashlibimport hmacimport timedef verify(secret: str, header: str | None, raw_body: bytes, tolerance_seconds: int = 300) -> bool: if not header: return False parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part) t, v1 = parts.get("t"), parts.get("v1") if not t or not v1 or not (t.isascii() and t.isdigit()) or len(t) > 12: return False if abs(time.time() - int(t)) > tolerance_seconds: return False expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected.encode(), v1.encode())
In Flask the raw body is request.get_data(), in FastAPI await request.body().
rawBody is a Buffer. In Express, use express.raw({ type: "*/*" }) on the route instead of express.json(). For a request without a body express.raw does not hand over a Buffer, which the routine treats as the empty body.
NetLock RMM generates the secret, in the form whsec_…. It cannot be chosen.
It is stored encrypted and shown once: when the subscription is created, when Sign requests is switched on, and after a rotation. Copy it at that moment. It cannot be read again later, not even by an administrator.
Rotating replaces it at once. Everything sent after the rotation is signed with the new secret, and the old one no longer verifies, so update the receiver right away.
With Sign requests switched off and saved, the secret is deleted. Switching on again generates a new one.
A webhook that signs never goes out unsigned. If the instance cannot read its secret, for example because the web console and the server use different encryption keys, nothing is sent and the failure is logged.
X-NetLock-Signature is reserved. The dialogs and the Public API refuse custom headers with that name.
A test from a dialog uses what is in the form. It signs with the stored secret only if the address equals the saved one; for another address it uses a one-time secret, which the receiver cannot verify, and says so. Every such test is recorded in the audit log, with the host of the target only.
Settings → Integrations → Signed webhooks needs the permission settings_integrations_enabled to read and settings_integrations_manage to change. A subscription appears only for accounts that cover every tenant it delivers, and only tenants of the account can be selected. Subscriptions created through the Public API appear here as well. Accounts that can only read see the scheme, host and port of an address, because path and query often carry a token.
Address. The address has to be absolute, http or https, without a user name or password. A cloud instance delivers to public addresses only, a self-hosted instance also to private ones. Neither delivers to loopback, link-local or metadata addresses. The address is checked when you save and again at every delivery.
Events. All seven event types of X.9.23, or all events, which also includes types added later.
Location limit. Without a selection, every location of the selected tenants is delivered. With a limit, whatever has no location is not delivered: website monitors, alerts of a whole tenant and removed devices. A subscription with a limit stays limited: if no location of the limit remains, because locations were deleted or their tenant was removed from the subscription, saving is refused until you choose another one. To deliver every location, delete the subscription and create it again.
Smaller reach. When a tenant leaves a subscription or its location limit shrinks, deliveries that are waiting or failed are dropped, because they can contain data the subscription no longer covers. They stay in the delivery log as failed.
Minimum severity. Applies to event.created only.
Active. A subscription starts at the present and does not replay older events. After 20 failed attempts in a row NetLock RMM switches it off and marks it. Switching it on again continues from the present.
Test. Sends a signed webhook.test delivery at once and reports the answer of the receiver. A test appears in the delivery log, but does not count as a failed attempt. An account can send six tests per minute. While the Public API is off, no test goes out.
Delivery log. Shows status, HTTP code, attempts and the reason of a failure. Send again puts a failed delivery back on the queue; the server sends the stored body within a few seconds with a new signature and the same delivery id. It needs an account that covers every tenant of the subscription, including any tenant deleted since then. A failed test is repeated with Test. The log follows the retention set under Settings → Retention, 14 days by default.
The Public API has to be switched on for deliveries to go out; the page says so when it is off.
This appendix is the canonical catalogue of every permission flag NetLock RMM exposes to role configuration. Use it as a lookup when the User Settings matrix is too dense to navigate, when you are auditing an existing user's rights, or when you are designing a new role and need to see everything the product can gate.
Permissions are granted per account, directly or through a role. Three things matter before you start assigning flags.
Roles. An account either follows a role, whose changes apply to every account that follows it, or holds custom permissions. See Chapter 14.4.
Permissions are boolean flags. Each flag is either granted or not granted. Access control is exercised through the matrix on User Settings, where section-level switches enable a block and child checkboxes gate finer-grained actions within the block. Turning a parent switch off disables every child regardless of the child's stored value.
Tenant scoping is layered on top. Independent of flags, every user record holds a list of tenants they may act on. A user with every flag enabled but only tenant Acme selected sees and acts on devices, tickets, and events scoped to Acme alone. Global pages (Settings, Events, Audit, Users, Reports library) are not tenant-scoped; feature pages that operate on devices are.
Four specific facts shape how the flags below behave:
tickets_view_all_departments is a scope flag, not a feature flag. Users without it still see the Tickets page, create tickets, reply, and close tickets, but only in the department(s) they are assigned to. The flag widens their view to every department; it does not gate access to the Tickets page itself.
settings_system_mysql_console is a sub-permission. The System settings group is unlocked by settings_system_enabled, but the MySQL console that lives inside it takes a separate, narrower flag. Keep it off unless the user truly needs raw query access.
ai_enabled has no effect. The flag is present in the matrix and stored on the user, but nothing reads it. What decides whether AI is available is deployment-wide: the Enable AI Features master switch and the ten per-feature toggles under Settings → AI / LLM. The one AI flag that is enforced per user is ai_chat_page_enabled. See A.11.
Custom SQL depends on SQL access, not on a separate SQL permission. Custom SQL and the query builders in reports, dashboard panels and custom fields run only as the MySQL user configured under Settings → SQL access (settings_sql_access). With it configured, everyone who may edit the item may use them: reports_create / reports_edit, dashboard_sql_panels plus assignment to every tenant, collections_custom_fields_add / collections_custom_fields_edit. See A.12.
Access to the Dashboard page and the Panel Builder.
dashboard_sql_panels
Create and change panels with their own SQL statement. Takes effect only for accounts assigned to every tenant, and only while SQL access is configured.
The File Browser action, and pasting files into a remote screen session from the web console or the Relay App. The server checks it for every paste of every viewer; for the Relay App it is checked on the account that owns the relay key (A.7.10).
devices_remote_control
Remote screen control in the web console, and in the Relay App and the NetLock app for the account that owns the relay key (together with the key's Screen control switch under Relay Server → Manage API Keys). Covers starting and stopping a recording and viewing the remote clipboard (A.7.9). Also viewing and, when the device's policy allows it, controlling the screen of Android devices from the web console (A.7.12).
devices_mobile_locate
Locate and Ring for Android devices: request the position of the device and let it ring.
devices_mobile_message
Send message for Android devices: a message that is shown on the device.
devices_remote_chat
End user chat: the chat with the signed-in user of a device from the device page and the remote control dialog, and the chat requests end users start from the tray icon (badge and list in the header of the console). Accounts and roles that held devices_remote_control received it once with the update to 3.3.0.5.
devices_remote_audio_call
Audio call: the voice call with the signed-in user of a Windows device from the end user chat and the remote control dialog (A.7.7). Members of the built-in Administrator role hold it automatically; other accounts and roles start without it.
devices_remote_eventlog_viewer
The Remote Event Log viewer (Windows only).
devices_remote_registry_editor
The Registry Editor (Windows only).
devices_snmp_tools
The SNMP Tools dialog.
devices_shutdown
The Shutdown command.
devices_reboot
The Reboot command.
devices_wake_on_lan
Wake on LAN.
devices_force_sync
The Force Sync action.
devices_usb_learning
Re-learn connected devices and End learning now on the USB Devices tab (Chapter 3.3), and the bulk re-learn on the Whitelist tab of Device Control (Chapter 8.7). Part of the built-in Administrator role and the Technician template; not in the Helpdesk, Read-only and Reporting templates. Custom roles get it when an administrator adds it.
devices_deauthorize
The Deauthorize action: removes the device and returns its Agent to the Unauthorized queue.
devices_move
Move a device between tenants, locations, or groups.
devices_unauthorized_enabled
The Unauthorized Devices list at /unauthorized_devices.
devices_unauthorized_authorize
The actions that authorise a pending device or adopt it as the reinstall of an existing device of the same name.
devices_security_incidents_view
The security incident dialog of a device on /devices and /unauthorized_devices, with the JSON export (see 3.8). The red row and the chip are shown without it. Accounts and roles that held devices_general or devices_unauthorized_enabled received it once with the update.
devices_security_incidents_manage
Acknowledge security incidents, whitelist a device, release an isolated unauthorized device for analysis, release an isolation and block new registrations of the installer package; revoking the package additionally needs agent_installers_enabled. Accounts and roles that held devices_unauthorized_authorize received it once with the update. The Read only template does not include it.
devices_world_map_enabled
The Device World Map.
devices_topology_enabled
The Device Topology map at /device-topology: tenants, locations, inferred subnets and the devices attached to them. Each user keeps their own node arrangement.
The whitelist and blocked-devices pages under /device-control.
collections_device_control_manage
Approve a blocked device (globally only with access to all tenants) and switch a whitelist entry on or off.
collections_device_control_delete
Delete whitelist entries and dismiss blocked devices.
There is no _add flag. An administrator adds an entry through the approval flow on Blocked Devices, which is gated by the _manage flag plus the ability to act on the specific scope. Devices also add device-scoped entries themselves while they learn; re-learning is gated by devices_usb_learning in the Devices group. See Chapter 8.7.
Reveal the stored value of a Secret custom field on a device or on tenant, location, group or global level. Every reveal is written to the audit log. Not granted by default; administrator accounts hold it.
collections_custom_fields_edit also gates changing values on devices and on tenant, location and group level; the global level needs settings_custom_fields_enabled in addition. See Chapter 8.4.
Create a relay session, and change the target of an existing one.
relay_server_edit
Edit a relay session and turn it on or off. Changing its target device, remote host, port or protocol also needs relay_server_add.
relay_server_delete
Close or delete a session.
relay_web_access
The Web interface action on the Devices page: open the web interface of a device, or of a host the device can reach, in a browser tab through a temporary relay session. Accounts that held relay_server_add received it once with the update.
The two flags are independent. Most operators need events_enabled; audit_enabled is usually reserved for security and compliance roles. See Chapter 12 — Events & Audit.
The roles page (Users › Roles) and the Roles button of the Users list.
roles_add
Create, duplicate and import roles; Save as new role on an account.
roles_edit
Save a role; the change applies to every account that follows it.
roles_delete
Delete a role that no account follows.
A user who holds users_edit can edit every other user's permission flags and role, including their own. Grant this flag only to accounts that should have full administrative rights. The console enforces one limit: the last enabled account holding users_enabled, users_manage and users_edit keeps them and stays enabled. Binding an account to a role is a users_edit action; changing the role itself, which reaches every account that follows it, is roles_edit. See Chapter 14 — Users & Roles.
Custom SQL and the Visual Query Builder in report widgets additionally need SQL access (Settings → SQL access, see settings_sql_access in X.2.17). See Chapter 11 — Reports.
Every flag below gates a specific Settings sub-page. The top-level Settings nav group requires settings_enabled; each sub-page requires its own flag in addition.
Change the storage limit and the public backend URL on the Overview page. A new URL becomes active after the web console and the server have been restarted.
settings_licensing_enabled
The Licensing page.
settings_licensing_manage
Replace the Members Portal API key on the Licensing page. The new key becomes active after the web console and the server have been restarted.
The MySQL console embedded in System settings. Narrower than settings_system_enabled; grant only to operators who truly need raw query access.
settings_sql_access
View and change Settings → SQL access, the MySQL user that custom SQL in reports, dashboards and custom fields runs as. The Administrator role has it; accounts and custom roles that held settings_reports_enabled or settings_dashboards_enabled received it once with the update to 3.3.0.11. The Technician and read-only templates do not include it. See A.12.1.
The tabs IP whitelist and Country restriction of the Security page, i.e. the IP whitelist of the web console and the country restriction of the web console and the server (see A.4.1a).
settings_sessions_enabled
The tab Sessions of the Security page: idle timeout, maximum lifetime and Stay signed in of Web Console sign-ins (see A.4.1c).
settings_rate_limiting_enabled
The tabs Rate limiting and Security incidents of the Security page: mode, limits, blocks, exemptions (see A.4.1b), and the two switches of the security incident detection (see 3.8). Accounts and roles that held settings_ip_whitelist_enabled received it once with the update; the Technician template does not include it.
settings_sso_enabled
The SSO configuration page.
settings_integrations_enabled
The Integrations store, connections, their mappings, history and log. Read only, and the role template Read only includes it. No lists are read from a vendor with this flag alone.
settings_integrations_manage
Connecting, testing, replacing credentials, settings, pausing, disconnecting and deleting connections, mappings, auto mapping, the company import and debug logging of a connection.
The tenant scope of an account limits these two flags only where tenant data is touched:
Connecting, credentials, settings, pausing and disconnecting need settings_integrations_manage alone.
Mappings of tenants and locations outside the scope are locked and show no names.
Auto mapping and the company import offer only tenants in scope.
History and log lines of other tenants are hidden.
Creating tenants in the import additionally needs tenants_add, and switching on the public API from the store needs settings_api_tokens_manage. The full table is in A.14.7.
The Notifications page has one master flag and five per-channel flag groups. Every channel follows the same pattern, with Email adding one extra flag for SMTP.
The deployment-wide SMTP configuration dialog. Separate from mail_edit: a user can manage recipients without being granted the ability to change the global SMTP server.
No effect; the flag is only stored on the user. AI availability is decided deployment-wide under Settings → AI / LLM; see A.11.1.
ai_chat_page_enabled
The AI Chat page at /ai-chat.
enduser_ai_accounts
The Customer AI dialog for managing end-user AI chat accounts: activation, per-user and per-tenant token limits, auto-activation, and statistics. Opened from the Tenants list and from tenant detail; scoped to the operator's tenants. See Chapter 13.6.
The individual AI features (script analysis, remote shell, event analysis, sensor and job creation, event-log analysis, ticket analysis, audit analysis, the Automations assistant, the operator AI Chat, and the end-user tray chat) are switched on at the deployment level under Settings → AI / LLM, not per user. The AI Chat page is gated on both levels: the deployment toggle decides whether it exists at all, ai_chat_page_enabled decides who may open it. See Chapter 13 and A.11.4.
Roles are stored objects; see Chapter 14.4 for the roles page and the Start from templates (Technician, Helpdesk, Read-only, Reporting). The templates cover the common cases; the profiles below describe what such a role typically holds and where a deployment usually adds to or takes from a template:
Level-2 engineer: L1 plus the policies_* flags, automation_*, most of the collections_*_add / _edit flags, patch_management_enabled, and audit_enabled for incident review.
Deployment operator: L2 plus settings_*_enabled for the settings sub-pages they own, users_enabled / _add / _manage / _edit if they onboard staff, but not settings_system_mysql_console or users_delete unless strictly required.
These profiles are starting points, not fixed rules.
This appendix lists common failure modes with a short cause and fix for each. It is organised by area rather than by error code; start with the area your symptom belongs to.
Most entries below assume a working baseline: you can sign in to the Console, the server process is running, and the database is reachable. When any of those is in doubt, check the Logging page first (see A.9); most deeper problems show up there before they show up in the UI.
Symptom. You installed the agent on a device, the installer reported success, but the device is not in the Devices list.
Likely cause. The agent is waiting in the Unauthorized queue. Unapproved devices do not appear in the main inventory.
Fix. Open Devices → Unauthorized Devices at /unauthorized_devices. Confirm the hostname, operating system, and the target tenant / location / group. Approve the entry. If the device is not in the Unauthorized queue either, see the next entry.
Symptom. Installation completed but the device never reaches the Console: there is no entry in Devices and none in Unauthorized Devices.
Likely cause. The agent cannot reach the server. The three common reasons are a wrong server URL in the installer configuration, a network or firewall block between the device and the server, and TLS validation failure against the server certificate.
Fix. On the device, confirm the agent service is running (NetLock_RMM_Agent_Comm on Windows; the netlock-rmm-agent-comm systemd unit on Linux). From the device, verify TCP reachability to the server URL and port. A device whose only route to the internet is a forward proxy has no direct TCP route, so a failing test there does not mean the device is misconfigured; see the next entry.
Switch server logging on at /logging, then download the server logs there and look for rejected connection attempts. The source IP on the rejection is the device's apparent source IP, which helps when a NAT or reverse proxy is in the path. For a detailed on-device view, enable debug logging on the agent and collect its log files, as described in Debug an agent.
Symptom. The device has no direct route to the internet and reaches everything through a forward proxy. The installer aborts at the connectivity check, or the installation succeeded but the device stays offline: the Comm agent works in offline mode, the Remote agent never connects to the command hub, and remote control, remote shell and tunnels are unavailable.
Likely cause. The agents determine the server address they talk to from a reachability check. Without a proxy configuration that check has no route to take, so the address stays empty and nothing downstream can connect. Proxy settings from the environment do not help by themselves: the three services run as LocalSystem on Windows and therefore see no per-user internet settings, and on Linux a systemd system unit inherits neither /etc/environment nor a login shell.
Fix. Install the agent with the proxy parameters of the Standard Installer, or with a proxy object inside the server_config.json you hand to clean; both are described in Devices behind an HTTP proxy. On Windows the machine-wide WinHTTP proxy written by netsh winhttp set proxy is picked up automatically as a fallback when no direct connection works, and on Linux the same is true for HTTPS_PROXY / HTTP_PROXY / NETLOCK_PROXY placed in /etc/default/netlock-rmm.
An authenticating proxy that answers with 407 is called out separately by the installer. It means the network path is fine and only the credentials were refused. Check --proxy-user / --proxy-pass, or use --proxy-auth default on a domain-joined machine.
A device behind a proxy that runs an agent before 3.3.0.3 cannot update itself; install the agent once again with a current installer.
Once the device is online, patch downloads are a separate matter: Patch Management drives the Windows Update Agent, which takes its proxy from the machine-wide WinHTTP configuration or from a WSUS and not from the NetLock proxy setting. A device that reports patches but never downloads them needs netsh winhttp set proxy or a WSUS as well; see What the proxy setting does not cover.
Symptom. A device that was authorized and working appears in Devices → Unauthorized Devices again, sometimes repeatedly, and the audit log holds no matching deauthorize entry.
Likely cause. The server deauthorizes a device on its own in two cases: a reinstall of the agent was detected (the device then waits for approval again, reason "Reinstall detected"), or the license limit was exceeded and the newest devices were deauthorized.
A changed hardware ID does not take the authorization away: the server stores the new ID and the device stays authorized; the authentication log shows "Hardware ID changed: new ID stored, device stays authorized", and a server sensor of the kind "Unauthorized device" with that trigger selected writes an event.
A device that appears as a second, unauthorized entry next to an authorized one of the same name was reinstalled (new operating system, new access key, new hardware ID); the entry carries the chip "Name already exists" and is continued with the row action "Adopt as reinstall" rather than approved as a duplicate.
Fix. Use the Authentication log row action on the device's row in Unauthorized Devices (permission "Authentication log"). The rows name the reason, the endpoint, the remote address and both hardware IDs, so the case is visible at a glance; the reasons and what to do about each are listed in Debug an agent, and what the hardware ID is and when it changes is described in Hardware ID. Re-authorize the device, or adopt the new entry as a reinstall of the existing device.
Symptom. The device shows Offline in the Console, but the agent service is running on-device.
Likely cause. The sync interval on the device's policy is longer than you expected, the agent is running but unable to reach the server (intermittent network), or the agent service stopped. A device that shows a red Blocked until … chip next to its name is refused by rate limiting on the server; see the next entry.
Fix. Check the Agent tab on the device's assigned policy for the configured sync interval (valid values are 5 to 1440 minutes). A shorter interval shows an offline device sooner and causes more check-ins. Restart the agent service on the device; when the agent comes back up it emits a fresh check-in that moves the Console to Online. If the problem recurs, look at the agent logs on the device and at the server logs (download them from the /logging page) for the device's identifier around the transition window.
Symptom. A device goes Offline although the agent is running and the network is fine. The devices list shows a red chip Blocked until <time> next to its name, the agent log on the device shows answers with status 429 and the body blocked or rate_limited, and /events has an event of the type Rate limiting for the device.
Likely cause. The device exceeded one of the request limits of rate limiting for several minutes in a row and rate limiting is in Enforce mode. Typical triggers are a reinstall or restart loop of the agent, a script or sensor that produces events at a high rate, a collector that outgrew the daily data volume, or a second agent that shares the device's identity. In Observe mode nothing is refused; a Blocked until chip only appears for enforced blocks.
Fix. Open Settings → Security → Rate limiting. The Blocks table names the class, the reason and the measured rate of the block, and the event of the type Rate limiting on /events carries the same details; Top subjects (24 h) shows whether the device is still over a limit. Unblock releases the block; the server applies it within thirty seconds and does not block the device again for fifteen minutes. A device block ends by itself after at most 60 minutes.
Then remove the cause on the device; the agent logs show which endpoint was refused. When the traffic is legitimate (a large SNMP collector, for example), raise the daily volume, choose the sensitivity Relaxed or add the device to the Exemptions.
If many devices behind one site are affected and the Rate limiting tab warns that most devices share one private address, the reverse proxy in front of the server does not pass the client addresses on; fix Kestrel:ForwardedHeaders before you keep the protection in Enforce mode.
Symptom.Download in the file browser of a device, or the public API action POST /v1/devices/{id}/files/actions/collect, fails. The file browser shows The agent on this device needs to be updated before files can be downloaded from it.; uploads to the device work.
Likely cause. The agent on the device is older than 3.3.0.6. Its upload is refused with 403 and nothing is stored. Devices whose policy has the automatic agent update turned off keep the old agent until they are updated by hand.
Fix. Update the agent on the device (through the automatic agent update or by installing the current agent package) and repeat the download.
Symptom. The device detail view shows - in the policy field.
Likely cause. No automation's condition matches the device and no default policy is set, so no policy has been selected for it. Policies do not attach to devices, locations, or groups directly; they are routed through Automations, with the default policy as the only fallback.
Fix. Open Automations and review the list for an enabled rule whose conditions all hold for this device (device, tenant, location, group, internal IP, domain, platform or a device attribute); Check matching devices in the rule's dialog shows whether it matches. Create a new automation if none exists.
Among the matching rules, the one with the lower priority number wins. If the wrong automation is winning, raise its number, narrow it, or give the rule you want a smaller number (a Device rule for the single machine gets 100 by default). Automation changes force an immediate re-evaluation on the affected devices. See Chapter 5 — Automations.
Alternatively, mark a default policy on the Policies page (Set as default policy in the actions column); it applies to every device that no automation reaches (see Chapter 6.2).
Symptom. You edited a policy, saved, and the device has not picked up the change.
Likely cause. The device has not synced since you saved. Policy changes apply on the agent's next sync cycle.
Fix. If the delay is unacceptable, use the Force Sync action on the device detail page (requires devices_force_sync). Check the Events page for the policy deployment record of the device.
Symptom. Events that should trigger an email produce none; nothing arrives in the recipient's inbox.
Likely cause. The global SMTP configuration has not been saved with a passing test, a maintenance window is suppressing sends, or the recipient's severity threshold is filtering the events out.
Fix. Open Notifications → E mail → SMTP settings and re-run Test. The dialog's Confirm action is gated behind a passing test. Until the test passes, no email notification is sent. Check the recipient's Severity dropdown: Any delivers every event, every other value delivers only events of exactly that severity (see A.8). Confirm no maintenance window is currently suppressing notifications. See A.8.2.
Symptom. The Teams channel receives nothing, or the ntfy.sh topic shows no messages.
Likely cause. The webhook URL or topic URL is wrong, the workflow behind a Teams webhook is turned off or fails on the body it receives, or the recipient's tenant scope does not include the tenant the event belongs to.
Fix. Open the channel tab and run Test on the suspect recipient. For Teams, check that the URL still belongs to a live workflow. A URL on webhook.office.com is a classic Office 365 connector, which Microsoft retired in May 2026; create the workflow as described in H.10 and paste the new URL over the old one.
A Teams test that passes while the channel stays empty points at the workflow rather than at the connector: its run history names the failing step, and a post step that cannot read the body it was handed means Payload format does not match how the flow is built.
For ntfy.sh, verify the topic URL is still current on the receiving side. Check that the recipient's Tenants / Selected tenants scope includes the relevant tenant: an empty Selected tenants list means "all tenants", but a single selected tenant excludes events from others. See A.8.
Symptom. Sign-in fails with Incorrect user name or password., and no other account that can manage users is able to reset your password.
Likely cause. The password is wrong or forgotten. The same message also appears when the account is set to SSO-only or is suspended, so the login screen does not show which of these applies.
Fix. If another account with users_edit can sign in, reset the password from Users (see Chapter 14). Otherwise, on a self-hosted deployment, set a temporary password in the database and change it at the next sign-in. See Recover access to the Web Console. On cloud, contact NetLock RMM support.
Symptom. A user completes the identity provider's sign-in flow but the Console rejects them with an authorization error.
Likely cause. The user has not been pre-provisioned in Users, their Auth Mode does not include SSO, or the email the identity provider returns does not match the username on the NetLock account.
Fix. NetLock RMM does not auto-provision accounts on first SSO sign-in. Open Users, create the account, set Auth Mode to SSO or Password & SSO, and make sure the Name field matches the email claim your provider returns exactly. Save. Ask the user to try again. See A.4.2.
Symptom. You toggled SSO settings and saved, and the Console restarted and signed out every user.
Likely cause. SSO configuration changes restart the Web Console so that the new identity configuration is loaded.
Fix. No fix needed. Plan SSO changes during a maintenance window if signing out all users is a problem, and confirm you can still sign in via the old method from a separate browser before you make the change, so you are not locked out if the configuration is wrong. See A.4.2.
Symptom. The SSO tile does not appear on the sign-in page even though you configured a provider.
Likely cause. No provider is currently enabled, or the saved configuration failed to load at startup. The SSO tile does not depend on the licence plan; SSO is available on every deployment.
Fix. Re-open Settings → SSO, confirm exactly one provider tab has its Enable switch on, and save. Only one provider can be active at a time; switching one on turns the others off. If the page shows the red SSO Configuration Error! banner, the stored configuration could not be loaded at startup; correct the provider fields and save again.
Symptom. Clicking the SSO button returns to the login page with the SSO error message, and the Web Console log contains Message contains error: 'invalid_request', error_description: 'Invalid parameter: redirect_uri'.
Likely cause. Keycloak rejected the redirect URI the Console sent. It checks the URI when the Console pushes the authorization request to it, before the browser is redirected, and uses the same message for any mismatch in scheme, host, port or path. Either the client's Valid redirect URIs do not match the Console's public address and callback path, or the Console builds the URI from the internal scheme or host because the reverse proxy is not trusted.
Fix. Open Settings → SSO; the Keycloak tab shows the sign-in and post-logout redirect URI to register. Compare them with the log line SSO | Keycloak challenge, which names the URI that was actually sent, and with the client's Valid redirect URIs, then register the exact value. If the log line shows forwarded_headers_applied=False, add the reverse proxy address to Kestrel:KnownProxies in the Console's appsettings.json, or enable Force https in redirect URLs and save. See A.4.2.
Symptom. A relay session you initiated stays in an offline state indefinitely.
Likely cause. The device is offline, or the Remote agent on the device is not running.
Fix. Confirm the device status on the Devices page first. If the device is online, the Remote agent may be stopped or stuck; trigger a Force Sync on the device to reset its side of the relay connection. Check the Relay Server page for the session's state and for errors. See Chapter 9.2.
Symptom. The remote control session connects, runs for a minute, and drops, again and again.
Likely cause. A middlebox (firewall, proxy, or deep-packet-inspection appliance) is terminating long-lived WebSocket connections or the relay stream.
Fix. Verify the device and the viewer can maintain persistent outbound connections to the server. Review the middlebox's session-timeout policy for WebSocket traffic. After a short loss the viewers reconnect on their own (A.7.9); a session that keeps dropping points to the middlebox.
Symptom. Remote control, screen sessions and tunnels are unavailable on a device, but the device shows as online in the Console and syncs normally. The Remote agent's Logs\Error.txt (see Debug an agent) contains entries from Service.Setup_SignalR with Failed to start SignalR and a message containing HTTP/2 error code 'INADEQUATE_SECURITY'.
Likely cause. The device runs Windows 8.1, Windows Server 2012 R2 or older, and the server is reached through a reverse proxy that enforces the HTTP/2 cipher-suite rules, such as Traefik in the setup from the Docker install guide, Caddy, or Apache with mod_http2. These Windows releases have no cipher suite that such a proxy accepts for HTTP/2, so the proxy refuses the HTTP/2 connection the Remote agent opened for its SignalR connection setup. The Comm agent uses plain HTTP/1.1 requests and is not affected, so the device still reports online.
Fix. Update the agent. Current agents use HTTP/1.1 for the SignalR connection setup and are not affected.
Symptom. A link or a service of a service network stays in the status Port not available on the NetMesh page. The link details show the operating system's message and, from agent 3.3.0.11, a hint with the reason.
Likely cause. The agent on the client device cannot open the local port of the link. Usually another program or service on the client device already listens on that port. On Windows the port can also be in an excluded port range (reserved by Hyper-V, WinNAT or Docker), and Windows' own file sharing always holds 445 and 139. A jump host does not help here: it only changes where the service device connects to.
Fix. Choose a different local port. With the netmesh_edit permission, the hint offers Change local port; for a service network the port applies to all consumers of the service. Afterwards the application on the client device must connect to the new port. On Windows, list the reserved ranges with netsh int ipv4 show excludedportrange protocol=tcp. For file shares (SMB, port 445) see Reach a file share (SMB) over NetMesh.
Symptom. A custom field renders but its value is blank or stale.
Likely cause. The Job that feeds the field failed on the device, or the Job has not run since the field was created.
Fix. Identify the Job feeding the field on Manage Custom Fields. Review its last execution on the device. If the Job is marked Hidden, its outcomes do not appear on the Events page. Run it manually from the device detail page's Job list or from the Jobs management page to see the failure. Fix the Job's Script or parse regex, then let it run again. See Chapter 8.4.
Symptom. A user launched an application that is not whitelisted in any attached ruleset, and Application Control did not stop the launch.
Likely cause. The ruleset is not attached to the device's policy, the policy has not synced since the ruleset was attached, or Application Control itself is disabled on the policy.
Fix. Open Policy Settings → Windows → Application Control on the device's policy. Confirm the ruleset is attached and the master switch is on. Force-sync the device. If Application Control is attached and synced, check the Blocked Applications tab on the ruleset for the launch attempt. If the attempt is not recorded there either, the agent is not enforcing yet. Enforcement starts once the ruleset holds rules and the auto-whitelist period of the policy has ended.
Symptom. The Winget, Flathub, or Chocolatey browser is empty.
Likely cause. The catalogue has not been refreshed yet on this deployment, or the server cannot reach the upstream service.
Fix. Click Refresh catalogs on the App Hub page. The refresh runs server-side and pulls the catalogue to the local database. Check the server logs (download them from /logging) for network failures against the upstream catalogue. See Chapter 8.5.
Symptom. Customers reply to a department mailbox but no new tickets or replies appear.
Likely cause. The department's IMAP credentials are wrong, the mailbox is unreachable, or the Ticket System is disabled globally.
Fix. Open Tickets → Departments: the Last poll column shows whether the latest poll of each department failed, and hovering over it names the cause. Open the department, review its mailbox configuration and click Test connection. Check that Settings → Ticket System → General → Ticket System Enabled is on. Confirm the mailbox is reachable from the server. Note that Blocked File Extensions strips attachments during ingestion; it does not prevent the ticket from being created. If attachments are being stripped but the ticket still does not appear, the issue is not the blocklist. NetLock RMM's own notification mails in that mailbox are skipped and stay unread; they do not indicate a broken intake.
Symptom.Test connection of a department, or a test in the global e-mail settings, succeeds with a warning that names the mail server and a second host from which the revocation list could not be retrieved. The web console log (for notification mails sent by the server: the server log) contains a warning The revocation status of the certificate of <server> could not be checked.
Likely cause. With Full validation (recommended) or Encrypt, but ignore a host name mismatch, NetLock RMM checks whether the certification authority has revoked the mail server's certificate. The revocation list is downloaded over plain HTTP (port 80) from the host named in the certificate. The machine or container running NetLock RMM cannot reach that host: outbound port 80 is blocked, the host name cannot be resolved, or the network only allows outbound traffic through a proxy.
Fix. Mail is still fetched and sent; only the revocation check is skipped, and the warning is repeated at most once per server and hour. To have the revocation checked, allow outbound HTTP (port 80) from NetLock RMM to the host named in the message. On a Docker installation, test from the network of the containers, for example sudo docker run --rm --network <network> curlimages/curl -sI http://<host>/. Switching to Encrypt, accept any certificate is not needed for this warning and turns off every certificate check. A certificate the authority has revoked is always refused, whatever the network allows.
Symptom. The recipients listed under the department's Notifications get nothing although the event is ticked.
Likely cause. The ticket has no department (the console's New Ticket dialog defaults to None; the API's departmentId was left out), the global e-mail settings under Settings → Notifications → E-Mail were never saved with a passing test (the department's own SMTP is not used for these mails), the event is not ticked, or the recipient list is empty or invalid.
Fix. Check the ticket's Department on the Details tab. Run the global SMTP test. Re-tick the events and save. Download the Console logs from /logging and search error.log / debug.log for Tickets.NotificationMailDispatcher (for events raised through the public API: the server logs, Public_Api.Ticket_Notification_Mail_Dispatcher); every skipped or failed send writes one line naming the reason. A notification that lands in the polled mailbox stays unread and is not imported. See Chapter 10.10.
Symptom. New replies arrive by email but the list lags behind.
Likely cause. The background refresh runs every 60 seconds. The real-time toasts are an additional notice and do not replace the refresh.
Fix. Click Refresh on the page, or reload the page. If toasts are not arriving either, the Console's persistent connection has dropped; reload to re-establish it. See Chapter 10.3.
Symptom. The panel renders but the value area is empty or shows zero.
Likely cause. The panel's SQL query returns no rows, or the MySQL user for SQL access cannot read a table or column the query uses.
Fix. Open the panel in the Panel Builder and check the underlying query; the query builder lists only the tables and columns the SQL access user can read. Widen that user's SELECT grants in MySQL if the panel needs another table. See Chapter 2.
Symptom. Report widgets with custom SQL show SQL access not configured (in generated output [SQL access not configured]), dashboard SQL panels are locked with a notice, SQL custom fields show (SQL access not configured), and the Widget Editor, Panel Builder and Custom Field Builder show a notice instead of the query builder and the SQL field. Saving a report template with custom SQL is refused; the public API answers 403 sql_access_not_configured.
Likely cause. No MySQL user is configured under Settings → SQL access, or the configured user was refused. Built-in report templates and SQL panels added from the shipped panel templates keep working, because their unchanged statements run without SQL access. On cloud instances SQL access is not available.
Fix. Open Settings → SQL access and read the status line. If it says Not configured, create the user and enter it as described in Set up SQL access. If it says Off with a reason, fix the grants as listed under Refusal reasons and save again. SQL access also switches off by itself when the periodic check (every 15 minutes) finds wider grants; it returns within a minute after the grants are fixed.
Symptom. A copy of a built-in template showed data before the update; afterwards some widgets show SQL access not configured.
Likely cause. The release changed the built-in statement. The copy still carries the old statement, which no longer matches the shipped one and is therefore treated as custom SQL.
Fix. Configure SQL access, or duplicate the current built-in template again.
Symptom. Generating a report returns an error mentioning an unknown table or column, or an access-denied error.
Likely cause. The SQL access user cannot read the table or column (for example a table added by an update after the per-table grants were created, or a credential column left out by the generated grants), or the schema changed between releases.
Fix. Run the GRANT statements from Settings → SQL access again after an update. If the schema changed, edit the template and rewrite the query against the current columns. On save, the console checks the statement with EXPLAIN and shows MySQL's message.
Symptom. AI Chat answers questions about NetLock RMM from general knowledge (menu paths or setting names that do not exist in the product), and no Sources line appears under the answer. Or the answer says the documentation does not cover a question that the manual clearly does.
Likely cause. There are three possible causes. The Use the product documentation to answer questions about NetLock RMM toggle on Settings → AI/LLM is off. The installation was built without the documentation snapshot; the status line under Product documentation on the same page then reports that no snapshot was found. Or a model with a short context window (a local Ollama or LM Studio model at its default context length) received more prompt than it can hold and truncated it from the start, which drops the instructions and the documentation sections before the question arrives.
Fix. Turn the toggle on and save. If the status line reports a missing snapshot, pull the current web console image; the published images carry the documentation. For a small local model, lower Documentation excerpt budget (characters) to 2000 or 3000, or raise the model's context window (for Ollama OLLAMA_CONTEXT_LENGTH or num_ctx in a Modelfile) and keep Max Tokens well below it. See A.11.5.
Logging at /logging: switch logging on or off for the Console and the server without a restart, and download the log files of both as ZIP packages. Self-hosted only. See A.9.
Audit at /audit: the record of configuration changes, including who changed what, from which IP, and when. When something used to work and now does not, the Audit log usually names the change that broke it. See Chapter 12.
Together they answer most "what changed and when" questions.
The Console has two global shortcuts: Ctrl+K (Cmd+K on macOS) and / open the global search box in the header on every Console page, or the box on the results page when that page is open.
/ is ignored while the cursor is in a text field, a script editor, a terminal or the ticket editor, and while a dialog is open, so a slash typed there arrives as usual.
While a remote control session has the keyboard, both shortcuts go to the remote device.
Inside the search box, ↑ and ↓ move through the suggestions, Enter opens the highlighted suggestion (or the results page when nothing is highlighted) and Esc closes the list.
Login page. Enter submits the sign-in form and the two-factor code.
Search fields. On pages with a search bar, such as Devices, Events, Tickets and Manage Files, typing filters the list as you type.
Script editor. The script editor on the Scripts page is an embedded Monaco editor with its own keys for code navigation, find (Ctrl+F), replace (Ctrl+H) and multi-cursor editing.
Remote control window. Function keys, modifier keys and shortcuts pressed in the window are sent to the remote device instead of being handled by the browser.
Remote shell window. The embedded terminal works like a standard terminal, including Ctrl+C to interrupt and Tab for completion.
This appendix lists every external system the product talks to, what the integration is for, and where in the Console it is configured. Use it as a firewall-review checklist and as a quick index when you need to find "where do I plug in the X credentials?".
Every row points to the chapter where the integration is documented in depth. The configuration column names the Console page that owns the credentials.
App Hub catalogues are refreshed on the server, not in the operator's browser. The server therefore needs outbound access to the relevant catalogue; the operator's workstation does not.
Five channels on the Notifications page reach outbound destinations. Every channel is independently configurable and every recipient carries a severity filter and a tenant scope.
Endpoint / Service
Purpose
Configuration home
SMTP (any provider)
Email notifications. Global SMTP configuration plus per-recipient addresses.
Ticket webhooks follow the same URL + secret + events shape as the notifications webhook but draw from a different event stream. They also require the tickets_manage_webhooks flag.
Where AI requests go depends on the model source selected on the AI / LLM Settings page. The two paths below are mutually exclusive: a deployment uses one or the other. See A.11.2 — Model selection.
Selected with Use NetLock AI (managed), and the default for a new deployment.
Endpoint / Service
Purpose
Configuration home
Members Portal API (https://api.members.netlockrmm.com)
The only host the deployment itself contacts in this mode. The Web Console posts chat completions to it; the server does the same for the end-user tray chat. Authentication is the deployment's Members Portal API key.
NetLock's upstream inference provider. The Members Portal API forwards the request to it and streams the answer back. The deployment never connects to it directly, so it is not a firewall entry. It is, however, where prompt content is processed, which is relevant for a data-protection review.
Selected with Use my own model. The configuration speaks the OpenAI chat-completions shape, so any provider that exposes that shape works. Requests go directly from the Web Console (and, for the end-user tray chat, from the server) to the host you enter; nothing passes through the Members Portal.
LocalAI, vLLM, self-hosted OpenAI-compatible gateways. Enter the provider's API Base URL and Model manually; API Key stays empty when the provider needs no authentication.
localhost in the local-model templates resolves to the host running the Console, not to the operator's workstation and not to a device running the agent. Adjust the base URL when the model runs on a different machine. The base URL is used exactly as entered with /chat/completions appended, so it has to carry the /v1 segment where the provider uses one.
The infrastructure endpoint behind community features and licence information.
Endpoint / Service
Purpose
Configuration home
Members Portal API (https://api.members.netlockrmm.com)
Deployment-level authentication and distribution for community features (Community Scripts, Community Reports, Community Themes) and for licence information. The same host carries the managed AI path described in X.5.5. A single API key is stored on the deployment; every operator inherits it.
Connections of the integrations store talk to the product they connect, in two ways:
Direction
From
To
Purpose
Outbound
Web console
The address of the vendor
The test of the assistant and the lists of its dropdowns, such as companies and queues.
Outbound
Server
The address of the vendor
Tickets, notes, device sync, contract quantities, status pulls of security and backup products.
Local
Server
127.0.0.1:7480 on the server itself
Connectors read NetLock data through the public API. Integrations:Loopback_Port changes the port, 0 switches it off. Do not publish this port or open it in a firewall.
Both the web console and the server therefore need the outbound path to a connected product. The addresses depend on the product:
IT Glue, GravityZone and Acronis accept only vendor addresses: the three API hosts of IT Glue, hosts below gravityzone.bitdefender.com and hosts below acronis.com.
Lexware Office, sevdesk and Docusnap365 have a fixed address: api.lexware.io, my.sevdesk.de and api.docusnap365.com.
Autotask has no address field in the setup: NetLock asks webservices.autotask.net for the zone of the API user and then talks to the webservices<n>.autotask.net host of that zone.
NetBox, Snipe-IT and Wazuh run at the customer: any address can be entered, and a cloud instance reaches them only on a public address. Wazuh needs two addresses, the server API (port 55000) and the indexer (port 9200), both with a valid certificate.
Vendors cannot reach anything inside NetLock through a connection: all of its traffic starts on the NetLock side.
A self-hosted instance can reach public and private addresses, but never loopback, link-local or cloud metadata addresses. A cloud instance reaches only public addresses. The same rules apply to public API webhooks. When a system proxy is set for a self-hosted instance, connections use it, and the name of the target has to be resolvable from the instance as well, because the address rules are checked before the request.
For a self-hosted deployment, the server needs outbound HTTPS to every endpoint above that the deployment actually uses. A starter checklist:
api.members.netlockrmm.com: for any community feature, for licence information, and for the managed NetLock AI.
The catalogue hosts for Winget, Flathub, and Chocolatey: only for App Hub refreshes.
The identity provider's OIDC discovery and token endpoints: only for SSO.
Each notification destination: SMTP gateway, the host in the Teams webhook URL, Telegram API, ntfy.sh (or your self-hosted ntfy), and whatever your generic webhooks target.
The address of each connected product in the integrations store, from the server and from the web console.
The LLM provider's base URL: only when AI features are enabled and the deployment uses its own model. With the managed NetLock AI there is no separate AI destination; that traffic goes to api.members.netlockrmm.com.
Cloud deployments delegate this connectivity to the hosted operations team; only the notifications and LLM endpoints remain the customer's firewall concern.
The list above covers the server. Every managed device additionally needs outbound access to the deployment's own backend address: the host and port the installer was built with (443 in a standard deployment). That single address carries all five agent roles (communication, remote, update, trust, file server) plus the SignalR command, screen and tunnel hubs, so one rule is enough. The agents open no UDP side channel and use no STUN / TURN.
Where the devices have no direct egress, that traffic can go through a forward proxy. Point the agents at it with the installer's proxy parameters, described in Devices behind an HTTP proxy. Two things matter when the firewall rules are written:
Only the backend traffic uses the proxy. LAN sensor probes, network and SNMP discovery, Wake-on-LAN and the jump-host end of a tunnel keep connecting directly and must keep their direct path to the local network.
The proxy has to allow the CONNECT method to the backend host on 443 for the WebSocket transport of the hubs. If the proxy refuses it, the connection falls back to server-sent events and then to long polling, and remote control and screen sharing are noticeably slower.
After an update, the Console opens the changelog on the NetLock RMM website in a new browser tab the first time each account opens the Dashboard. It answers "what changed in the version I am running?".
When a newer version is available, the app bar shows an Update available icon and the account menu shows Update available (v…). Both open a short summary of the new version. On self-hosted deployments you run the update yourself; on cloud deployments NetLock applies updates centrally.
The authoritative, searchable changelog for published releases lives on the NetLock RMM website. It lists the release notes of every published version, so you can trace the history of a feature across several releases.
This manual describes the current release of NetLock RMM. Where a feature needs a minimum version, the chapter names it. When a feature referenced in this manual is missing from your Console, check the changelog; most likely you are on an older release in which the feature had not yet shipped.
This appendix is a single-page index of what NetLock RMM does. It groups every feature into Console, server, and agent areas, records platform support where it varies, and links to the chapter that documents the feature in full. Use it to answer "does the product do X, and where do I read about it?", not as a configuration reference. For mechanics, follow the cross-links.
Three conventions apply throughout:
Yes / No in a platform column means the feature is or is not available on that operating system.
A dash (—) means the feature does not apply to that platform.
Where a column names a tool or shell instead of Yes (for example PowerShell), that is the platform-specific implementation.
Note: This matrix summarises shipped behaviour. When a feature area carries deployment-specific or licensing-specific limits, the linked chapter is authoritative.
The web Console is the interface operators work in. The features below are available regardless of agent platform; they are properties of the Console itself.
Feature
Summary
Documented in
Multi-tenancy
Tenant, location, and group hierarchy for organising devices.
Per-user dashboards with chart and table panels from catalog widgets or custom SQL (visual query builder or direct SQL; custom SQL needs SQL access, self-hosted only).
Operator-defined device-detail tabs, sections, and fields; values per device or inherited from group, location, tenant and global level; secret fields with an audited reveal.
Draws tenants, locations, subnets and devices as a network map inferred from the adapters the agents report; nodes can be dragged and the arrangement is kept per user.
Optional module: The Ticket System applies only when it is enabled in Settings → Ticket System. See Chapter 10.
The AI features are optional. They run either on the managed NetLock AI reached through the Members Portal, or on an OpenAI-compatible provider the deployment configures and hosts itself; the choice is made under Settings → AI / LLM (see A.11.2).
Two kinds exist: the general-purpose AI Chat page, and targeted per-feature assistants. The targeted integrations are the AI Assistant in the Scripts editor (which writes directly into a script), the AI Assistant on the Automations dialogs, the AI SQL Assistant in the Widget Editor, and the Analyze with AI action on event and audit details (which opens AI Chat with the entry pre-filled). See Chapter 13.
A separate, optional Customer AI feature extends AI to end users: when enabled in the tray-icon policy, staff open an AI chat directly from the agent's tray icon. The conversation history is encrypted on the device with the user's password and stored encrypted; operators cannot read it. To answer, each message is passed through the NetLock server to the configured model. Accounts self-register and are activated by an operator (or auto-activated per tenant), and usage is bounded by per-user and per-tenant monthly token limits. Operators manage these accounts from the Customer AI dialog on the Tenants pages, gated by the enduser_ai_accounts permission. See Chapter 13.6.
Self-hosted only: Server architecture and role splitting apply to self-hosted deployments. Cloud deployments delegate server operation to the hosted operations team.
GNOME and KDE on Wayland; without wl-clipboard saved to Downloads (agent 3.3.0.11 and later)
Yes (agent 3.3.0.11 and later)
SNMP Tools
Yes
Yes
Yes
Uninstall application
Yes
Yes
Yes
Wake on LAN
Yes
Yes
Yes
Relay Server
Yes
Yes
Yes
Remote Screen Control streams the device's screen as JPEG frames from the agent through the NetLock server to the viewer (the web Console, the Relay App or the NetLock app). The product does not use VNC or RDP.
The picture is tuned per session with a stream mode: Quality (4:4:4 colour, native resolution, up to 20 fps), Balanced (the default, up to 30 fps), Performance (up to 60 fps), Auto (adapts to the connection) and Custom; a statistics overlay shows frame rate, bandwidth, latency and the capture method in use. Full detail, including session switching, recording, and unattended access, is in Chapter 3 and A.7; the modes are described in A.7.5.
On Linux a mode sets the frame-rate cap and the resolution ceiling only. Remote Screen Control runs in the device's Wayland session; its prerequisites, the desktop support matrix, and how unattended access works on Wayland are covered in X.8.5.
Files can be pasted into a running session from the web Console and the Relay App: dropped onto the picture, pressed in with Ctrl+V or chosen with Send files, up to 100 files and 10 GB per transfer. The device puts them on its clipboard and pastes them where the user works; it needs devices_remote_file_browser and the 3.3.0.11 agent. See A.7.10.
Android phones and tablets are viewed and, when their policy allows it, controlled from the web console: taps, swipes, scrolling, the system buttons and, from Android 13, text; the user agrees on the phone for every session. See A.7.12 and X.8.7.
Sessions from the Relay App and the NetLock app run under the account that owns the relay key: that account's name is shown in the consent prompt on the device and written to the audit log. See A.7.9.
The Relay Server provides TCP tunnels and jump-host access for network devices without an agent. The Relay App and NetMesh links use end-to-end encrypted TCP tunnels. Relay Web Access is encrypted between the browser and the server. See Chapter 9.
Allowlist rulesets matched by path, metadata, hash, or signing certificate.
USB Device Control
Yes
No
No
Allowlist with device, tenant, location, group, and global scope.
Antivirus management covers Microsoft Defender only; third-party antivirus products are not managed. Application Control and Device Control are library features under Collections (see Chapter 8.6 and Chapter 8.7). A ruleset or whitelist reaches devices only through a policy; see Chapter 6.
The App Hub is a catalogue you pick from; installation runs through Software Deployment. See Chapter 8.5 and Chapter 8.8.
Patch Management is split across two places. The /patch-management page is a global approval queue with compliance and SLA tracking; per-policy rollout rules (schedule, deployment rings, reboot, retry, notifications) live inside the policy editor. See Chapter 7 for the page and Chapter 6 for per-policy rollout.
One policy per device; agent behaviour, security, patching, App Hub.
Automations
Yes
Yes
Yes
Routes one policy to devices by a device-attribute condition.
Jobs
Yes
Yes
Yes
Scheduled script execution with twelve schedule types.
Sensors
Yes
Yes
Yes
Utilization, event log, script, service, ping, and SNMP sensors.
Device uptime monitoring
Yes
Yes
Yes
Connection and disconnection alerts per device.
Website uptime monitoring
Yes
Yes
Yes
HTTP status, SSL expiry, response time, content checks.
Port Scanner
Yes
Yes
Yes
TCP scans of operator-defined targets with banner grabbing.
An automation is a conditions → policy and/or items rule. It has no event triggers or schedules, and its only actions are assigning one policy and adding sensors and jobs from the library. Every rule has a priority; among the rules whose conditions all hold for a device, the one with the lowest number that assigns a policy decides the policy, and the sensors and jobs of every matching rule are added on top. Automations cannot run scripts themselves or send notifications. See Chapter 5 for the resolution model and Chapter 6 for what a policy contains.
Note: A device is assigned at most one policy at a time. Policies do not attach to tenants, locations, groups, or devices directly; they are routed through Automations.
Besides alerting, sensors can run an action script on a threshold breach. Sensor and Job mechanics live in Chapter 8.2 and Chapter 8.3. Website uptime monitoring and the Port Scanner are documented in Chapter 9.
The agent exposes an optional tray application to end users on all three platforms. Its branding, button set, App Hub window labels, AI Chat and the chat request to the administrators are configured per policy.
Feature
Win
Linux
macOS
User tray icon
Yes
Yes
Yes
Custom tray branding
Yes
Yes
Yes
App Hub window
Yes
Yes
Yes
AI Chat (end user)
Yes
Yes
Yes
Chat request to the administrators (end user)
Yes
Yes
Yes
Incoming audio call window (end user)
Yes
—
—
On macOS the tray icon, and with it the consent prompt and the support badge of Remote Screen Control, the end user chat and the chat request, need agent 3.3.0.11 or later. The macOS prerequisites are in X.8.6.
The tray AI Chat is optional. The conversation history is encrypted on the device with the user's password and stored encrypted; operators cannot read it. To answer, each message is passed through the NetLock server to the configured model. It is enabled and fully labelled per policy and managed from the Console's Customer AI dialog; see Chapter 13.6.
When the policy allows it, an end user can ask the administrators for a chat from the tray menu. The request is offered to the administrators who are signed in to the web console, hold the End user chat permission and have access to the device's tenant. The first who accepts gets the end user chat of the device with the user's session pre-selected. If no such administrator is signed in, the user is told right away that nobody is available. See §6.5.
An operator can also call the signed-in user of a Windows device from the end user chat: the tray icon shows an incoming call window with the operator's name and picture, and after accepting the user talks through the default microphone and playback device, with device pickers, mute, echo suppression and hang up in the same window. The call needs the Audio call permission (devices_remote_audio_call), the Allow audio calls switch of the policy and a browser with WebCodecs (Chrome, Edge, Firefox 130+, Safari 26+); calls are not recorded. See A.7.7.
The supported operating systems and architectures, further platforms the agent runs on, and the Linux prerequisites for Remote Screen Control on Wayland are documented on their own page: Platform Support.
The agent runs on x64 and arm64 architectures and needs no third-party runtime dependencies. The server is distributed as a container image and is installed with Docker.
The operating systems below are officially supported. Where the notes state that troubleshooting support has ended, the agent still runs on that version but issues specific to it are not investigated.
For where each feature is available per platform, see the Feature Matrix.
All updates must be installed. No troubleshooting support.
Windows 8.1
All updates must be installed. No troubleshooting support.
Windows 7
All updates must be installed. No troubleshooting support.
The audio call from the end user chat (A.7.7) is available for Windows devices only and needs agent 3.3.0.5 or later. Linux and macOS devices show no call button in the console and answer a call as not supported.
The Linux agent needs glibc 2.28 or later; Alpine uses its own musl build. Ubuntu 20.04, Debian 11, RHEL 8 and its rebuilds (Oracle Linux, Rocky Linux, AlmaLinux 8) need agent 3.3.0.11 or later. Devices there on an older agent do not update themselves and need a one-time reinstall, see Debug an agent.
SELinux in enforcing mode needs agent 3.3.0.11 or later; no policy module or relabeling is needed. Devices with SELinux enforcing on an older agent need a one-time reinstall, see Debug an agent.
The macOS programs of the agent (3.3.0.11 or later) are signed with an Apple Developer ID and notarized by Apple. Remote Screen Control and the tray icon on macOS need agent 3.3.0.11 or later (X.8.6). Remote Screen Control uses ScreenCaptureKit, which every macOS version in the table has. Intel Macs get the same signed build (osx-x64).
Remote Screen Control on Linux is supported on Wayland sessions: GNOME and KDE Plasma, and wlroots desktops with grim and ydotool (see the table below). Unlike on Windows, where capture and input are built in, the Linux agent relies on the Wayland desktop portal and a few host tools. Install the packages below on the controlled device (the one running the agent's user process), not on the operator's machine. Linux devices can be controlled from the web console, the Relay App (3.3.0.11 and later) and the NetLock app; all three show the consent and start states described below. Full feature detail is in A.7.
To confirm the device is running a Wayland session, run:
This prints Type=wayland for the active graphical seat session.
Remote Screen Control on Linux has two independent layers, screen capture and input injection. Each tries a preferred path first and uses a fallback only when the preferred path is unavailable. The agent decides this automatically at runtime; you do not configure which path is used. The installed packages determine which paths are possible.
Capture falls back on desktops other than GNOME and KDE if the portal/PipeWire prerequisites are missing or the portal capture ends without a picture. It does not fall back when the user declined the screen-sharing dialog or left it unanswered. On GNOME and KDE the agent never switches to the command-line tools, because they cannot capture there; a missing prerequisite or a capture that delivers no picture is reported in the remote control window instead (see Troubleshooting).
Input falls back if no portal input session is active (portal not running, permission not granted, or a session that only provides capture).
Whether Remote Screen Control works is decided by the display server and the desktop's portal backend, not by the distribution itself.
Wayland desktop
Capture
Input
Result
GNOME
ScreenCast portal
RemoteDesktop portal
Full
KDE Plasma
ScreenCast portal
RemoteDesktop portal
Full
wlroots (Sway, Hyprland)
grim
ydotool (wlroots has no RemoteDesktop portal)
Works (mixed path)
No portal backend
—
ydotool
Not supported (no capture)
On GNOME and KDE Wayland only the portal path works; the command-line capture fallbacks do not apply there (grim needs wlroots; scrot only sees XWayland windows). On those desktops the portal bridge packages below are required.
Applies to graphical desktops only. Remote Screen Control needs a screen to control. Headless server and cloud installs, common for RHEL/CentOS Server, SUSE Linux Enterprise Server, Alpine, Azure Linux, and Ubuntu Server, have no display server, so the feature does not apply there even though the agent itself runs.
The package names below are for Debian and Ubuntu (apt). Other distribution families ship the same tools under their own package managers (dnf, zypper, apk).
The preferred path is the desktop portal: org.freedesktop.portal.ScreenCast provides the screen and org.freedesktop.portal.RemoteDesktop injects input, without ydotool and without uinput access. The agent drives the portal through a small Python helper and bridges the PipeWire video stream with GStreamer.
Install the full portal path on the controlled device. On Debian and Ubuntu:
On KDE, install xdg-desktop-portal-kde instead of xdg-desktop-portal-gnome. A standard GNOME or KDE desktop already ships pipewire, xdg-desktop-portal, and its portal backend; the packages that are usually still missing are the GStreamer plugins (gstreamer1.0-plugins-base and gstreamer1.0-plugins-good, which provide the videoconvert / videoscale / videorate and jpegenc / multifilesink elements the capture pipeline uses) and the GStreamer↔PipeWire bridge with the Python bindings the helper uses.
Clipboard sync needs one of the clipboard tools of the session. On Wayland wl-clipboard is preferred and is the only tool that reports a clipboard change on its own, without polling; xclip (which works through XWayland) and xsel are the alternatives and the X11 path. Without any of them the device cannot reach its clipboard at all, and the viewer reports that; see A.7.6.
Files pasted into a session (A.7.10) need agent 3.3.0.11 or later. On a GNOME or KDE Wayland session the device puts them on the clipboard with wl-copy from wl-clipboard (in the format Nautilus reads on GNOME, as a URI list on KDE and other desktops) and presses Ctrl+V through the desktop portal, so the open file manager window pastes them. wl-clipboard is not installed on a standard Ubuntu desktop; install it to get the paste:
sudo apt install -y wl-clipboard
The device copies the files into the user's Downloads folder instead when:
wl-clipboard is not installed,
the session is not a Wayland session, or
wl-copy fails or does not finish within five seconds.
The Downloads folder is the one from ~/.config/user-dirs.dirs, otherwise ~/Downloads. The files are readable for that user only, a name that already exists gets the form name (2).ext, and the viewer shows the path. On GNOME, wl-copy waits while the Activities overview is open, so a transfer during the overview ends up in Downloads. When the clipboard was set but the keystroke could not be sent, the files are on the clipboard and the user can paste them.
The transfer folders below /var/0x101 Cyber Security/NetLock RMM/Remote Agent/Clipboard Files/ belong to the user the files are pasted for (0700, files 0600); other accounts of the device cannot read them.
The Wayland portal is built around user consent, which shapes how unattended access behaves:
First connection to a device shows a one-time screen-sharing dialog that must be accepted on the controlled device. The agent requests a persistent grant. While the dialog is open, the remote control window in the console shows that it is waiting for the user on the device; the dialog stays until it is answered.
Every connection after that runs without a prompt. Once the first picture has arrived, the agent stores the restore token the portal returned (per user, under ~/.config/netlock/pipewire_restore_token) and replays it on later connections, so the grant is restored without a prompt. This survives reboots: the grant persists until it is explicitly revoked.
Re-approval is only needed if the user revokes the grant (GNOME Settings → Sharing / Privacy → Screen Sharing, or the equivalent on KDE), a different user or application identity is used, or, rarely, a desktop update invalidates the token. If a stored token fails to restore, or restores without a picture arriving, the agent asks again with a fresh prompt on the same connection, and the new grant takes the place of the stored one once it has delivered a picture.
Limitation: the login screen is not covered. Because the portal lives inside the user's session, unattended capture covers a logged-in user (including after a reboot, once that user's session is back). It does not cover the login screen (GDM) or a state with no logged-in user. To guarantee a session always exists for unattended access, enable autologin on the device.
If the portal cannot be used, for example in a session with no portal backend or in a locked-down or headless-style setup, the agent falls back to ydotool for input and CLI tools (grim, scrot) for capture. The capture tools are of use on wlroots desktops only; on GNOME and KDE they capture nothing and the agent does not use them. Install these only if you need that fallback to work:
sudo apt install -y ydotool grim scrot
ydotool injects at the kernel level through /dev/uinput, which needs two extra steps:
Step
Command
Enable and start the daemon
sudo systemctl enable --now ydotool
Grant access to uinput
sudo usermod -aG input "$USER", then sign out and back in
On the first connection to a device, the desktop shows its screen-sharing dialog on the device. Someone at the device has to accept it. The dialog stays open until it is answered; the desktop portal ends an unanswered request by itself after about a minute.
While the dialog is open, the remote control window (in the console, the Relay App or the NetLock app) shows "Waiting for the user to accept screen sharing on the device." Nothing needs to be done in the viewer during that time. Before the dialog opens, the window can briefly show "Starting the screen capture on the device." while the device prepares the request.
After the dialog was accepted, the window shows "Starting the screen capture on the device." until the first picture arrives. On most devices that takes a moment; a slow or busy device is given up to 30 seconds.
The permission is stored only once the first picture has arrived. Later connections restore it without a dialog; the window then shows only "Starting the screen capture on the device." until the picture is there. A stored permission that the desktop no longer accepts, or that brings no picture within 30 seconds, is followed by a fresh dialog on the same connection, and the new permission takes the place of the stored one once it has delivered a picture. You do not need to delete a file or restart the device for that.
Message in the remote control window
Meaning
What to do
Waiting for the user to accept screen sharing on the device.
The screen-sharing dialog is open on the device and has not been answered.
Ask the person at the device to accept it.
Starting the screen capture on the device.
The device is starting the capture and the first picture is not there yet. It appears briefly before the screen-sharing dialog opens on a first connection, after the dialog was accepted, and on its own when a stored permission is restored without a dialog.
Wait. After the dialog was accepted, a slow device is given up to 30 seconds.
Screen sharing was not accepted on the device.
The dialog was declined or closed, or nobody answered it within about a minute.
Press Retry and accept the dialog on the device.
Screen capture components are missing on the device. See the Linux prerequisites in the documentation.
A program, Python module or GStreamer element of the portal path is not installed, or PipeWire or the desktop portal is not available in the user's session. The same text appears in the session selection when no session of the device can be captured for that reason.
Install the required packages and run the checks below. The device checks again half a minute after a failed check; nothing has to be restarted. Then press Retry.
No signal from the selected session.
No picture arrived within 30 seconds after sharing was granted, the capture stopped delivering, or the device stopped answering.
Press Retry. If it repeats, run the checks below and collect a debug log.
The commands work in a terminal of the desktop user and in a root shell alike, for example in the NetLock remote shell, which runs as root. Where a command reads data of the desktop user, it names that user explicitly: replace <user> with the user's name and <uid> with the numeric id that id -u <user> prints. In a root shell, ~ is root's home and journalctl --user is root's journal, so neither shows the desktop user's data.
Session type: must print Type=wayland (see the command at the top of this section).
GStreamer elements the capture pipeline needs. gst-inspect-1.0 evaluates only its last argument, so each element is checked on its own:
for e in pipewiresrc jpegenc videoconvert videoscale videorate multifilesink; do gst-inspect-1.0 --exists "$e" && echo "OK $e" || echo "MISSING $e"; done
Every line must start with OK. A MISSING line names the element; pipewiresrc comes with gstreamer1.0-pipewire, videoconvert, videoscale and videorate with gstreamer1.0-plugins-base, jpegenc and multifilesink with gstreamer1.0-plugins-good.
PipeWire and the desktop portal in the user's session: pipewire, wireplumber, xdg-desktop-portal and the portal backend of the desktop (xdg-desktop-portal-gnome or -kde) must be listed:
Journal of the desktop user. Start a connection from the console first, then run this right afterwards and read the lines of xdg-desktop-portal, the portal backend, pipewire and gnome-shell:
The line Failed to associate portal window with parent window is expected on every connection: the agent has no window of its own to attach the dialog to. It is not an error.
Stored permission of the user:
ls -la /home/<user>/.config/netlock/
pipewire_restore_token is the stored screen-sharing permission. It exists only after a connection that delivered a picture. A logs folder next to it holds the debug log of the User Process once debugging was switched on (see below).
The agent asks again by itself when a stored permission no longer works. To force a fresh dialog on the next connection anyway, revoke the permission in the desktop settings (GNOME Settings → Sharing / Privacy → Screen Sharing, or the equivalent on KDE), or delete the token file:
Screen capture and input run in the User Process, inside the desktop session of the signed-in user. With debugging switched on it writes every step of a capture start to its log: the check of the prerequisites with the name of what failed, the portal requests and their answers, the time each stage took, the GStreamer pipeline with its error output, whether a stored permission was used, and the reason whenever the capture is stopped.
Switch debugging on as root with a marker file. Nothing has to be restarted:
Start a connection from the console. The User Process runs as the desktop user and writes its log below that user's home, next to the stored permission: Debug.txt and Error.txt, readable for that user and root only, in:
ls -la /home/<user>/.config/netlock/logs/
The log holds neither what was typed or clicked during a session (only the kind of an input command and the kind of an error) nor the stored permission token, so it can be sent to support as it is.
Remove the marker file afterwards to switch debugging off; the log grows without a limit:
The Remote agent's log records the capture results the User Process reports to it; Debug an agent describes how to switch on debugging for the agent services and, under Debug the User Process, the same steps as above.
Remote Screen Control on macOS needs agent 3.3.0.11 or later on the device. The console, the Relay App and the NetLock app offer screen control and the end user chat for a macOS device only once the device reports that agent version; a Mac on an older agent shows neither entry. Full feature detail is in A.7.
Screen control runs in the User Process of the agent, which starts in the session of every signed-in user. The tray icon shows the consent prompt, the support badge and the end user chat. Nothing has to be installed in addition on the device.
The programs of the agent are signed with the Apple Developer ID of the publisher and notarized by Apple. The permissions below are granted to the signed program, so an agent update keeps them.
macOS hands out the screen and the input only to programs that are allowed in System Settings. The User Process asks the system once after it starts, which shows the system's own notice; nothing waits for an answer, and the agent never opens System Settings by itself. An administrator at the Mac allows both entries once:
Permission
Where
What it is needed for
Screen & System Audio Recording
System Settings > Privacy & Security > Screen & System Audio Recording, entry NetLock RMM User Process
The picture. Without it the session shows no signal.
Accessibility
System Settings > Privacy & Security > Accessibility, entry NetLock RMM User Process
Mouse and keyboard input. Without it the picture runs and the input is dropped.
Both switches ask for an administrator password on the Mac. When the screen recording permission is given while the User Process runs, the User Process restarts itself once so that the permission takes effect; a session that is open at that moment shows the picture after Retry. Until a permission is given, the remote control window names it:
Message in the remote control window
Meaning
What to do
Screen recording is not allowed for NetLock RMM on this Mac, or has to be confirmed there again. …
The screen recording permission is missing, or macOS asks for it to be confirmed again (see the next section). The same text appears in the session selection when no session of the device can be captured for that reason.
Allow the entry in System Settings on the Mac, then press Retry.
Mouse and keyboard input is not allowed for NetLock RMM on this Mac. … (line at the lower edge of the picture)
The Accessibility permission is missing. The picture runs; clicks and keys do not reach the Mac.
Allow the entry in System Settings on the Mac. The line disappears on its own once the Mac accepts input again.
No active session — the display may be off or the device is at the login screen.
No user is signed in on the Mac, or the signed-in user's User Process is not running.
Sign a user in on the Mac. The login screen is not covered (see Limits).
No signal from the selected session.
The capture stopped delivering or the device stopped answering. This is also what the window shows when someone at the Mac stops the recording with the screen recording indicator in the menu bar: macOS ends the capture for that session, and the device does not start it again on its own.
Press Retry; a new session starts the capture again. If it repeats, run the checks below and collect a diagnosis.
macOS 15 (Sequoia) and later show the notice "NetLock RMM User Process is requesting to bypass the system private window picker and directly access your screen and audio" about once a month for programs that capture the screen without the system picker, more rarely while the capture is used regularly, and sometimes after a system update. Someone at the Mac has to choose Allow for one month; until then the remote control window shows the screen recording message above. Unattended access to a Mac with nobody in front of it can therefore be interrupted about once a month. On managed Macs the MDM key forceBypassScreenCaptureAlert suppresses the notice (see the next section).
On Macs under device management a configuration profile can set what an administrator would otherwise click. The profile names the program by its bundle identifier and its code requirement. Both are read from an installed agent on any Mac, so the values in the profile are exactly those of the signed program:
The first command prints the identifier com.netlock.rmm.user.process, the Team ID and the certificate chain (Developer ID Application: …, Developer ID Certification Authority, Apple Root CA); the second prints the designated requirement, which goes into the profile as the code requirement. For the tray icon use the bundle Tray_Icon/NetLock RMM Tray Icon.app in the same folder (identifier com.netlock.rmm.tray.icon).
Accessibility can be granted in advance with a Privacy Preferences Policy Control (PPPC) payload (com.apple.TCC.configuration-profile-policy) for the identifier com.netlock.rmm.user.process, identifier type bundle ID, the code requirement from above, service Accessibility, allowed.
Screen recording cannot be granted by a profile; Apple requires the click on the Mac. The PPPC payload can set Allowed Standard User To Set System Service for the service ScreenCapture, so that a standard user may allow it without an administrator password.
Background items: a Service Management payload (com.apple.servicemanagement) with a rule of type TeamIdentifier and the Team ID from above keeps the LaunchAgents and LaunchDaemons of the agent enabled and hides them from Allow in the Background in System Settings > General > Login Items.
The monthly notice is suppressed with forceBypassScreenCaptureAlert (payload com.apple.applicationaccess), available from macOS 15 on.
The device applies the modifier keys of a Windows or Linux keyboard as follows: Ctrl becomes Command, the Windows or Meta key becomes Control, Alt becomes Option. Ctrl+C, Ctrl+V and the other shortcuts of the viewer therefore reach the Mac as Command shortcuts, and Control+C in a Terminal is sent with the Windows key. When the viewer itself runs on a Mac and the device is a Mac, nothing is translated: Command stays Command and Control stays Control. The Ctrl+Alt+Del button of the viewer opens Force Quit Applications (Command+Option+Esc) on the Mac. The keyboard shortcut menu of the viewers lists Mac shortcuts such as Command+Tab, Spotlight and Mission Control in Mac terms and sends them as listed (A.7.8). Text is typed as the characters that were typed, independent of the keyboard layout of the Mac.
The clipboard works as described in A.7.6, with one difference on macOS 15.4 and later: macOS asks the user before a program reads the clipboard. The automatic sync of what the user copies therefore stays off on such a Mac until someone at the Mac sets the clipboard access of NetLock RMM User Process to Always Allow (System Settings > Privacy & Security > Paste from Other Apps); the entry appears there after the first time macOS asked. Taking the remote clipboard with Ctrl+C and the view dialog still read it on request, and macOS may ask the user at the Mac each time. On macOS before 15.4 the clipboard works without a question.
Files pasted into a session (A.7.10) are put on the general pasteboard as file URLs and pasted with Command+V into the application in front: a Finder window pastes into its folder, the Finder without a window onto the desktop, Mail adds an attachment. The Finder is not brought to the front. Writing to the pasteboard needs no permission; the keystroke needs the Accessibility permission. Without it the files stay on the clipboard and the viewer says that the user can paste them. This needs agent 3.3.0.11 or later.
Once both permissions are given, every connection to a signed-in user runs without a prompt and needs nobody at the Mac, apart from the monthly notice above on macOS 15 and later. The consent prompt and the support badge follow the policy of the device as on the other platforms (Policy > Tray Icon > Remote Screen Control); the tray icon shows both.
The login screen is not covered. The User Process runs inside a user's session, so a Mac with nobody signed in, and a Mac at the FileVault pre-boot screen, shows No active session. A Mac that is locked with a user signed in can be captured.
With fast user switching, every signed-in user has a session of their own in the session selection; the one that owns the screen is the one to pick.
Audio calls and Backstage are not available on macOS.
Run as the signed-in user in a Terminal on the Mac:
# Is the User Process registered and running in this user's session?launchctl print "gui/$(id -u)/com.netlock.rmm.user.process" | grep -E "state|pid|path"# Signature and notarization of the programB="/usr/local/bin/0x101_Cyber_Security/NetLock_RMM/User_Process/NetLock RMM User Process.app"codesign --verify --deep --strict --verbose=2 "$B"spctl -a -t exec -vv "$B"
codesign --verify answers valid on disk and satisfies its Designated Requirement; spctl answers accepted with source=Notarized Developer ID.
To make macOS ask for a permission again, remove the entry in System Settings or reset it on the Mac:
The User Process has a diagnosis mode that checks, step by step and without a session from the console, what a screen control session needs: the process and how it was started, the code signature, the GUI session, the permissions, the displays, ScreenCaptureKit and the content it can share, a short stream with the number of pictures and the time to the first one, the encoding of a picture, the stop of the stream, the capture backend and single pictures. Every step ends with OK, WARN, FAIL or SKIP and the reason; the exit code is 0 when no step failed (WARN counts as passed).
--seconds N: how long the stream runs and is counted, 1 to 120, default 5.
--screen I: the display to capture, counted from 0, default 0.
--out FILE: writes the report to this file as well, line by line, so the file holds everything up to a step that does not return.
--input: sends a small mouse movement there and back.
--clipboard: writes a marker to the clipboard, reads it back and restores the previous content; skipped when the clipboard holds anything but plain text.
--request: lets the system show its notices for the missing permissions.
The diagnosis does not connect to the agent and leaves a running User Process alone. Started from SSH it has no GUI session and stops after the session check. Started from a Terminal on the Mac, the permissions it reports are those of the Terminal, not those of the User Process; the report says so in its Process step (not started by launchd). For the real picture, start it once through launchd in the session of the signed-in user. As that user, in a Terminal on the Mac:
Add --input and --clipboard to the arguments to test input and the clipboard as well. The report holds no picture content, nothing that was typed and no clipboard content, so it can be sent to support as it is.
The User Process also writes a debug log when debugging is switched on; see Debug the User Process.
Android phones and tablets run the NetLock RMM app instead of an agent. They are enrolled with a code from the console (Deploy your first agent) and sync on their own interval, at least every 15 minutes.
Function
Android
Inventory, battery, storage, network, compliance
Every Android version the app supports
Locate, ring, message
Every supported version
View the screen
Every supported version; the user agrees for every session
Control the screen: taps, swipes, scrolling, system buttons
Every supported version, with the app's remote control service switched on and the policy switch on
Control the screen: typing text and editing keys
Android 13 and later
Endpoint protection (anchor, grants for screen sessions)
Every supported version, with the current NetLock RMM app; the app's data is not part of backups or device transfers, so a new phone is enrolled again (A.13.11)
An app installed from an APK file shows the remote control service as Controlled by Restricted Setting until Allow restricted settings is chosen in Settings → Apps → NetLock RMM Agent App → ⋮.
The app opens Android's list of accessibility services; the service is switched on there.
A control session always shares the entire screen. A view session shares what the user chooses; from Android 15 the prompt preselects a single app.
On Android 16 and later the service cannot be switched on during a phone call.
On recent Android versions locking the screen ends a screen session; the phone cannot be unlocked remotely.
Apps that protect their content appear black, and some system dialogs accept no remote input.
Android may show its own reminder that an accessibility service has access to the device.
Devices with Android's advanced protection mode may block accessibility services that are not accessibility tools; the viewer then reports that the service is not enabled.
The server exposes a REST API under /v1 for external systems: a PSA, a CMDB, a documentation tool, an automation pipeline. This appendix explains how access works and documents the custom field endpoints and the automation rules in detail, because they carry rules the generated reference does not spell out. Every other endpoint is documented in the Swagger reference served by the server itself.
Switches.Settings → API tokens (route /settings/api-tokens) holds two deployment-wide switches: Public API enabled and Public API documentation enabled. The server re-reads the API switch about once a minute; no restart is needed. The documentation switch covers only /docs and the OpenAPI document.
Reference. With the documentation enabled, the server serves a Swagger UI at https://<server>/docs and the OpenAPI document at https://<server>/openapi/v1.json. Every route carries a summary and a description with its body shape, its scope and the permissions it needs. That page is the authoritative reference for request and response shapes.
Tokens. A token is created on the same page and shown once. It has the form nlk_<key id>_<secret> and is sent as a Bearer token:
Authorization: Bearer nlk_0123456789ab_...
A token is bound to a console account and carries:
Scopes such as customfields:read or devices:actions:script. Only scopes whose underlying permissions the bound account holds are offered, and the account's permissions are checked again on every request. A token never has more rights than its account.
Tenants: the tenants selected for the token plus the tenants the token created itself through the API, limited to what its account holds. With the option All tenants of the account they are the tenants of the account, evaluated on every request. A token can additionally be narrowed to a list of locations. A device, tenant, location or group outside that scope answers 404. See X.9.11.
A rate limit in requests per minute (default 600). Requests above it answer 429 with a Retry-After header. Independent of the token, one IP address is capped at 1200 requests per minute and at 20 failed authentications per minute.
An expiry date, or none. Tokens can be rotated and revoked from the same page.
Errors. Errors are JSON problem documents with a code, for example insufficient_scope (the token lacks the scope), insufficient_permission (the bound account lacks a permission), location_restricted (the token is limited to locations), invalid_parameter, not_found and rate_limited. The report codes sql_access_not_configured and sql_invalid are described in X.9.16.
Audit. Writes through the API are written to the audit log with the token name.
Idempotency. Actions that change something accept an Idempotency-Key header. Sending the same key again for the same request returns the first response for 24 hours instead of running the action a second time. A key belongs to one request path: the same key sent to another path, for example the same action for another device, answers 409 idempotency_key_reuse. Use one key per device and action. A request that is still running answers 409 idempotency_key_in_flight.
Updates. Update the Web Console first, then the server. The Web Console updates the database that the server's API relies on.
The API covers the organization (tenants, locations, groups); devices with their inventory, enrolment, antivirus state, processes, event logs, files and registry; device actions (power, sync, commands and scripts, agent uninstall); mobile devices; events, alerts and notification results; external references; device usage per tenant; custom fields; patch management and vulnerabilities; sensors, SNMP, uptime monitoring and the port scanner; software deployments and App Hub; scripts and jobs; policies, automations and maintenance windows; notification targets; the file server; tickets and time tracking; users and permissions; the audit log; reports and dashboards; relay sessions; outbound webhooks; application control, device control and controlled folder access; BitLocker; agent packages and installer links; and the platform's own health and licence state. See the Swagger reference for each of them.
Scope customfields:read for the reads and customfields:write for the writes. Every write in addition needs the permission collections_custom_fields_edit on the bound account; the global level needs settings_custom_fields_enabled for reads and writes. For the concepts (levels, inheritance, secrets) see Chapter 8.4.
GET /v1/custom-fields returns the definition catalogue, paginated: id, name, description, author, createdAt and the definition document with its tabs, sections and fields. Definitions are global and not tenant scoped. Definitions cannot be created or changed over the API.
source names who wrote the device value last: manual (console), script (write-back from a script) or api.
isSecret is true for a Secret field; its value is always null.
A field the device has no row for is not listed. A value cleared in the console has no row either.
GET /v1/devices/{id}/custom-fields?effective=true returns one item per manual field of every definition with the value the device effectively reads, resolved the way a script variable is resolved: the device's own value first, then, for an inheritable field, the group, location, tenant and global value in that order.
The key of each entry is <definitionId>:<fieldKey>. null clears the value; the row is deleted, so the device inherits again. A value for a Secret field is stored encrypted. Stored values get source: api, the device is marked for a policy re-sync, and when an automation rule compares one of the fields, the rules are evaluated for the device and it is pushed at once if its assignment changed. The definition must exist. The answer is the device read back in the shape of the GET. The same values can be sent as customFields in PATCH /v1/devices/{id}.
stale is true when the field is no longer an inheritable manual field of its definition, or the definition is gone. The row is listed anyway so it can be cleared.
PUT takes the same body as the device endpoint, { "values": { "<definitionId>:<fieldKey>": value | null } }, and answers with the level read back:
Only inheritable Manual fields of type Text, Multiline or Secret are accepted, and a value may not exceed 64 KB. Any other entry answers 400 invalid_parameter with the reason, and nothing of the request is written.
null clears the row, also a stale one.
A token limited to locations cannot write tenant or global values (403 location_restricted). A token without any tenant cannot write global values.
updatedBy is the token name. One audit entry per request names the level and the counts, never the values.
Every write marks the devices of the level for a policy re-sync; a global write marks every device. When an automation rule compares one of the fields, the online devices of the level are pushed at once.
POST /v1/devices/{id}/actions/run-script (body { "scriptId" } or { "scriptName" }, optional runAsUser; scope devices:actions:script) and POST /v1/devices/{id}/actions/run-command (body { "command", "language", "runAsUser", "timeoutMinutes" }; scope devices:actions:shell) render script variables for the target device before the command is sent, in the shell named by language or the device's platform default. cmd is not rendered.
The action record and GET /v1/device-actions/{id} keep the unrendered text, so a resolved secret never appears in an API answer. The result is the output with write-back marker lines removed; their values are stored on the device.
Every completed command also writes an event Remote shell command executed. (type Remote Shell) on the device that names the token, the action, the run-as user and the shell and carries the output; the command text is not part of it. GET /v1/device-actions/{id} reads the shell output from the action record; result and output hold the same text for shell actions. Both actions exist as /v1/devices/bulk/actions/run-script and /v1/devices/bulk/actions/run-command as well.
POST /v1/sensors/{id}/test renders the sensor's scripts for the target device in the same way. Values the scripts would write back are listed as Would set: <keys> in the additional details and are not stored.
POST /v1/devices/{id}/files/actions/collect (scope devices:remote-files:read) needs agent 3.3.0.6 or later on the device; with an older agent the action ends with a failed result.
Scope automations:read for the reads and automations:write for the writes. For the model (conditions, negation, priority, the enabled switch, how the server picks a device's policy and how sensors and jobs are added), see Chapter 5.
GET /v1/automations lists the rules, ordered by priority then id unless sorted otherwise (sort=priority, sort=-priority, sort=name, …), with the filters tenantId, deviceId, enabled (true/false), sensorId, jobId (rules that add that sensor or job) and search. GET /v1/automations/{id} returns one rule. Both return:
conditions is the rule's condition list as stored. Every entry has type and negate; an entity condition carries its id (deviceId, tenantId, locationId or groupId) and the entity's name; internal_ip and domain carry value; platform carries values; device_attribute carries field, op and value.
A location or group condition additionally carries locationIds / groupIds and names in the same order (null for an entity that is gone or outside the token's tenants). It may name several entities ("is one of"); then locationId / groupId and name are null and only the lists carry the entries: { "type": "group", "negate": false, "groupId": null, "name": null, "groupIds": [12, 17, 23], "names": ["No print", "No print", "No print"] }. For a single entity both forms are filled.
policyName is null for a rule that assigns no policy. sensorIds and jobIds are the sensors and jobs the rule adds to every matching device on top of its policy.
deviceId, tenantId, locationId and groupId on the rule itself mirror the non-negated entity conditions that name one entity; a rule whose location or group condition names several carries the tenant of those entities in tenantId; effectiveTenantId is the tenant the rule belongs to, or null for a rule without an entity condition. Such a rule is instance wide and is returned to every token holding the scope.
A rule is returned only when the tenant it resolves to is inside the token's tenant scope.
From 3.3.0.4, policyName replaces trigger; condition, expectedResult, actions, category and subCategory are not returned.
POST /v1/automations creates a rule, POST /v1/policies/{id}/assign creates a rule for the policy named by the route, PATCH /v1/automations/{id} changes one, DELETE /v1/automations/{id} removes one. The create body:
conditions needs at least one entry; all have to hold. Each entry may carry negate: true. At most one non-negated condition per entity type is allowed. Types and fields:
platform { values[] } with Windows, Linux, MacOS, Android, iOS.
device_attribute { field, op, value } with field one of device_name, operating_system, label, serial_number, device_class, architecture, manufacturer, model, mainboard, cpu, gpu, agent_version, last_active_user, timezone, antivirus_solution and op one of eq, contains, starts_with, wildcard, regex.
service { field, op, value, status } with fieldname or display_name, opeq, contains or wildcard and statusany, running or stopped (a Linux unit matches with or without .service).
application { op, value, versionOp?, version? } with versionOpeq, gte, lt or starts_with.
custom_field { key, op, value? } with key the field key of a custom field definition and opeq, contains, regex or is_empty.
A location or group condition may send locationIds[] / groupIds[] (up to 500) instead of locationId / groupId. The condition holds when the device is in any of them; negated, it holds when the device is in none of them. Send either the single id or the list; sending both answers 400, and so do deviceIds and tenantIds. A list with one id is stored as the single id. Every id has to be inside the token's tenant scope (otherwise 404); all ids of one condition have to belong to the same tenant and lie inside the tenant or location the rule names elsewhere (otherwise 400).
A pattern that does not compile, an unknown platform, field, operator or status, a missing value or version, a key no definition carries or a secret field answers 400 invalid_parameter with the entry named. Service, application and custom field conditions are evaluated on the server against the device's last inventory upload (see Chapter 5.2.2).
A rule needs at least one action: policyName (an existing policy; on /v1/policies/{id}/assign the route names it), sensorIds or jobIds; a body with none of them answers 400. sensorIds and jobIds are lists of existing ids; an unknown id, or a sensor the SNMP discovery manages, answers 400 invalid_parameter naming the field. The items are added to every matching device on top of its policy and are handed out only to devices that have a policy. enabled defaults to true. priority defaults to the most specific organisation condition (device 100, internal IP 200, domain 300, group 400, location 500, tenant 600, otherwise 700) and may be any number from 0.
Every entity a condition names has to be inside the token's tenant scope; one outside answers 404, as reading it would. A rule with no non-negated entity condition matches in every tenant and is accepted only when the token's scope covers every tenant of the instance.
PATCH has merge-patch semantics on name, description, policyName, enabled, priority, conditions, sensorIds and jobIds: a field left out stays as it is; conditions, sensorIds and jobIds each replace their whole list ([] empties it). policyName: null removes the policy; it is refused when the rule would be left without any action.
The answer of a create or change is { id, created | updated, policyName, sensorIds[], jobIds[], enabled, priority, conditions[] } with the conditions in the read shape (entity names resolved). A create answers 201; send an Idempotency-Key header to make a retry safe.
Every write marks the affected devices out of sync and queues an acceleration request, so online devices re-sync right away.
A single-condition body is accepted as well.{ "condition": "tenant" | "location" | "group" | "device" | "internal-ip" | "domain", "tenantId" | "locationId" | "groupId" | "deviceId" | "value": … } is translated into one condition and stored in the list form; the answer is the list form. A request that sends both conditions and the single-condition fields answers 400. On PATCH, the single-condition fields replace the whole condition list with that one condition: a PATCH { "tenantId": 7 } on a rule with three conditions leaves it with the one tenant condition; send conditions to change one entry of a list.
Policies.POST /v1/policies creates a policy with the same default settings the console's policy editor starts with; the answer is { id, created, defaultsApplied }. defaultsApplied is false when the Web Console has not started yet on this instance; the policy is then created without settings. On PUT /v1/policies/{id}/settings, a section that is left out or null takes the default setting instead of being cleared; the answer lists those sections in sectionsDefaulted (field names, like sectionsSet). Only if the Web Console has not started yet on this instance does such a section stay unset; sectionsCleared counts those.
DELETE /v1/policies/{id} deletes the rules that only assign the policy and keeps the rules that also add sensors or jobs, without the policy; it answers { id, deleted, assignmentsDeleted, assignmentsKept }. DELETE /v1/sensors/{id} and DELETE /v1/jobs/{id} remove the item from every rule that adds it; a rule left without any action is switched off.
Deleting a device (DELETE /v1/devices/{id}, bulk delete), a location or a group adjusts the automation rules that name it as in the Console (§5.7): a rule that still names another tenant, location, group or device is switched off, a rule left without one is deleted, and each such rule gets an audit entry under the token's account.
PATCH /v1/automations/{id} without new conditions and DELETE /v1/automations/{id} skip the ids of tenants, locations, groups or devices that no longer exist: such a condition binds the rule to no tenant, so the rule then needs a token whose scope covers every tenant, unless another condition still names an entity in the token's scope. An id that belongs to a tenant outside the token's scope still answers 404.
GET /v1/devices/{id}/sensors lists the sensors the device receives: those of its policy and those the matching automation rules add, the latter only when the device has a policy and only for the device's platform. Every entry carries source, policy or automation.
GET /v1/devices/{id} carries automationState: the decision of the device's last evaluation as { policyName, policySource, automationId, sensorIds, jobIds, matchedAutomationIds, evaluatedAt, handedOutAt }, or null before the first evaluation. policySource is automation, default or none; evaluatedAt is updated by every evaluation, handedOutAt only when the device fetched its policy. The field is left out of list rows and honours ?fields=.
Example: give every Windows device of tenant 5 the policy Windows base, ahead of the tenant's other rules.
curl -X POST "https://server.example.com/v1/automations" \ -H "Authorization: Bearer nlk_..." \ -H "Content-Type: application/json" \ -d '{"name":"Windows in ACME","policyName":"Windows base","priority":550,"conditions":[{"type":"tenant","tenantId":5},{"type":"platform","values":["Windows"]}]}'
Scripts, jobs and sensors carry a free-text label (up to 64 characters, null when none is set), which the console groups its lists by.
GET /v1/scripts, /v1/jobs and /v1/sensors, the single reads and GET /v1/devices/{id}/sensors return label; it honours ?fields=.
The lists filter with ?label= (exact, case-insensitive), and ?search= also matches the label. Scripts and jobs sort with sort=label.
POST /v1/scripts, /v1/jobs and /v1/sensors accept label. On PATCH, a body without label leaves it unchanged; "" or null removes it. A longer value or a value that is not a string answers 400 invalid_parameter.
The label is not part of the document the agents receive: a PATCH that changes only the label does not mark any device out of sync.
Console accounts either follow a role (a named permission set, see Chapter 14.4) or carry custom permissions.
GET /v1/users and GET /v1/users/{id} (users:read) return role as { "id": 3, "name": "Technician", "builtIn": false }, or null for custom permissions, and roleOrigin with the name of the role a custom account was detached from (null when it never followed one). The list filters with ?role=<name>, ?role=custom and ?roleId=<int>, and sort=role sorts by the role name. Both fields honour ?fields=.
GET /v1/roles and GET /v1/roles/{id} (users:read) list the roles with id, name, description, builtIn, memberCount, createdAt and updatedAt; the single read also carries permissions, the same object shape as GET /v1/users/{id}/permissions. The list filters with ?builtIn= and ?search=.
POST /v1/users takes roleId. With roleId the account starts with that role's permissions and follows it; because that grants permissions, the token needs users:permissions:write in addition to users:write, and a role that holds a permission the bound account does not answers 409 permission_escalation_forbidden. Without roleId the account has custom permissions and none of them. The response carries role and roleOrigin.
PUT /v1/users/{id}/role (users:permissions:write) with { "roleId": 3 } binds the account: its permissions become the role's permission object at once and every later change of the role applies to it. { "roleId": null } detaches the account; it keeps its permissions as custom permissions and roleOrigin names the role. An unknown roleId answers 404; the self-edit and escalation refusals of the permissions write apply.
PUT /v1/users/{id}/permissions detaches an account that follows a role: the permissions written become its own, role is null afterwards and roleOrigin names the role.
PATCH /v1/users/{id} does not accept role. Disabling, deleting or demoting the last enabled account that holds users_enabled, users_manage and users_edit (through PATCH with enabled: false, DELETE, the permissions write or a role without those three keys) answers 409 last_user_manager.
From 3.3.0.5, role is an object or null; POST and PATCH reject a role field as unknown.
An account's tenant access is the switch Access to all tenants and a list of tenants (see Chapter 14.5):
GET /v1/users and GET /v1/users/{id} return allTenants (the account has access to all tenants, including tenants created later) and tenants as the effective list of tenant ids: every existing tenant when allTenants is true, otherwise the assigned tenants that exist. Both honour ?fields=; the list filters with ?allTenants=true|false.
GET /v1/users/{id}/permissions returns tenants and allTenants next to permissions, so a read-then-write round trip carries the whole tenant state.
POST /v1/users accepts allTenants (default false, whatever roleId is). It needs users:permissions:write like roleId, and only a token that itself reaches every tenant may set it: a token that uses All tenants of the account while that account has access to all tenants. Any other token answers 409 permission_escalation_forbidden. The response carries allTenants.
PUT /v1/users/{id}/permissions takes { permissions, tenants, allTenants? }. allTenants left out leaves the switch as it is, so a client that replays an earlier response does not switch an administrator off; true carries the same refusal as on POST; false is always allowed. While the switch is on, tenants is stored but not evaluated. The response carries allTenantsBefore and allTenants, and the audit entry names the switch when it changed.
GET /v1/me returns accountAllTenants: the bound account has access to all tenants, so tenantIds of a token with All tenants of the account is complete.
Update the Web Console before the server. Until then the server evaluates every account from its tenant list alone, and allTenants: true on POST or PUT answers 409 console_update_required.
The server resolves the country of a device's external address (ipAddressExternal) at every check-in against its bundled GeoIP database and stores it with the device (see Chapter 3.1 — Country of a device). No lookup leaves the installation.
GET /v1/devices, GET /v1/devices/{id}, GET /v1/mobile-devices, GET /v1/mobile-devices/{id} and GET /v1/enrollment/pending return geoCountryCode (ISO 3166-1 alpha-2, upper case) and geoCountryName (the English name from the database). Both are null for a device that connects through a private address, for an address the database has no country for, and for a device that has not checked in yet. On the device and mobile device reads they honour ?fields=.
GET /v1/devices filters with ?geoCountryCode=DE (exact, one code) and sorts with sort=geoCountryCode or sort=-geoCountryCode.
The fields are read-only; the country cannot be set through the API.
When the country restriction of the server is active, API clients are admitted by the country of their address like every other client; the token does not exempt them.
GET /v1/sensors and GET /v1/sensors/{id} return them with serverSensor { allTenants, triggers }; for every other sensor serverSensor is null. The triggers depend on the sub-category:
0Unauthorized device: new_device, reinstall, hwid_changed, license_limit. hwid_changed is the one trigger whose device stays authorized; the server only records the new hardware ID.
The tenants a server sensor covers are not returned; allTenants tells whether it covers every tenant, including tenants created later.
Server sensors are read-only through the API: POST, PUT and PATCH do not create or change them, DELETE /v1/sensors/{id} removes one. Create and change them in the Web Console.
GET /v1/events filters with ?type= on the numeric event type: 0 antivirus, 1 job, 2 sensor, 4 device uptime, 5 website uptime, 6 port scanner, 7 SNMP discovery, 8 remote shell, 10 patch management, 11 device authorization (written by server sensors of the kind Unauthorized device), 12 device country (written by server sensors of the kind Device country), 13 rate limiting (written by the server when it blocks a device, or records in observe mode that it would; see A.4.1b), 16 external (reported by another system, see X.9.20; a report for a tenant has no device and is not listed by GET /v1/events). Events of server sensors carry the id of the sensor that wrote them in sensorId. Address blocks of rate limiting name no device and are not returned by the API, and the event.created webhook does not deliver them.
Every event carries date, the time the server received it, and occurredAt (agent 3.3.0.6 or later), the time it was created on the device as reported by the agent, as UTC ISO 8601. occurredAt is null for events of older agents, for events the server wrote itself and when the reported time lies more than 30 days before or more than 5 minutes after the receipt. date keeps its meaning in /v1/events, /v1/events/{id}, /v1/devices/{id}/events, in ?fields= and in the webhooks; sorting, retention and notifications follow date.
The API reads both kinds of entries of the Patch history tab (see Chapter 7.5). All routes need the scope patch:read. An entry whose device is outside the tenants or locations of the token answers 404.
Patch jobs.GET /v1/patch-jobs, GET /v1/patch-jobs/{id} and GET /v1/patch-jobs/{id}/items return the jobs an operator started by hand (Patch Now and uninstall) with their items. The list filters with ?deviceId=, ?status= and ?action=. Scheduled runs are not part of it. The status of an item is pending, installing, uninstalling, success (installed, or removed on an uninstall job), restartpending (installed by Windows Update, takes effect after the next restart; from agent 3.3.0.11), failed, skipped or notuninstallable. Once a job with items has finished, its counts follow the items: installedCount counts success and restartpending (on an uninstall job only success), failedCount the failed items and totalItems all items.
Scheduled patch runs. The runs an agent started on its own from the patch schedule of its policy. Agents 3.3.0.5 and newer report them.
GET /v1/patch-runs lists them newest first, paginated with ?page= and ?pageSize= (default 50, at most 500). The answer carries items, page, pageSize, total, totalPages and hasMore.
Filters: ?deviceId=, ?kind=, ?outcome=, and ?from= and ?to= as RFC 3339 timestamps with an offset, compared against runAt. A timestamp without an offset answers 400.
GET /v1/patch-runs/{id} returns one run. id is the numeric run id used by all /patch-runs routes.
GET /v1/patch-runs/{id}/items returns { "runId": <id>, "items": [...] } with every update the run looked at. A skipped run has no items.
A run carries:
Field
Meaning
id
The numeric run id.
agentRunId
The GUID the agent generated for the run.
deviceId, deviceName
The device.
kind
run when the run reached the installation, skip when no run started.
outcome
For run: ran, nothing_pending or reboot_pending. For skip: disk_space, informational, disabled, no_settings or window_invalid.
note
The agent's note on the run, in English.
runAt, finishedAt
Start and end of the run in UTC.
runAtLocal
The start on the device's own clock, as text.
inWindow, catchUp
Whether the run started inside the maintenance window, or as a catch-up of a missed one.
windowStart, windowEnd
The maintenance window of the policy in device time (HH:mm).
Winget and Chocolatey were not checked because Windows updates wait for a restart.
itemsTruncated
The agent reported only part of the updates; failed updates come first.
durationSeconds, agentVersion, receivedAt
Duration, agent version and the time the server received the run.
An item carries id, updateId, updateSource (OS-Mandatory, Winget, Chocolatey, Apt, Dnf, Yum or MacOS), name, status, reason and detail. status is installed, failed, restart_pending, held_back or skipped. reason is the code behind the reason column of the console, for example not_approved, severity_filter, type_filter, ring_until, retry_wait, user_input, deferred, framework_package, no_upgrade, not_outdated, replaced, kept_back, held or unresolvable. detail holds the error text, including the Windows Update error code, or for ring_until and retry_wait the UTC time the update becomes due.
Runs are deleted by the retention of the Patch history (90 days by default).
Which tenants a token has.Settings → API tokens offers two ways to set the tenants of a token. The switch All tenants of the account sits in the dialog of the token (Add in the toolbar, or the edit icon of an existing token), directly above the tenant selection; it is available from version 3.3.0.10 on.
With the switch All tenants of the account off, the token uses the tenants selected in its dialog and, in addition, every tenant it created itself through POST /v1/tenants. Tenants the account gets later are not included.
With the switch on, the token uses every tenant its account is assigned to, including tenants assigned or created later. The selection in the dialog is then not an input. An account with Access to all tenants (Chapter 14.5) has every tenant, including tenants created later, so such a token reaches them as well; GET /v1/me reports accountAllTenants: true for it, and the token list shows Currently: All tenants for the token.
In both cases the account is the upper limit: a tenant that is taken from the account is gone for its tokens as well, and a tenant that no longer exists is not part of any token. Changes made in the console reach the API within five seconds.
GET /v1/me shows the result: tenantIds are the tenants the token can use right now, tenantScope is account with the switch on and selected otherwise, and createdTenantIds lists the tenants among tenantIds that the token created itself.
Tenants a token created.POST /v1/tenants assigns the new tenant to the account the token is bound to and records the token with the tenant. The same token can use the tenant from its next request on. Tenants created before version 3.3.0.10 are used by a token only when it is selected for it or when the token uses all tenants of its account.
The edit dialog of the token marks these tenants as created by this token and preselects them. Deselecting one and saving withdraws the access; selecting it again grants it like any other tenant of the account.
Rotating a token keeps the access, because the token stays the same entry. A newly issued token does not inherit it; select the tenants for the new token.
Other tokens of the same account do not get the tenant automatically. They see it when it is selected for them or when they use all tenants of the account.
Webhook subscriptions, notification targets and reports that copy the token's tenants when they are created keep that list; they do not grow with the token.
A token that is narrowed to locations stays narrowed: it does not see a location it creates in a new tenant.
Provisioning with one token. A tenant, its locations and groups can be created and existing devices moved into them by the same token, one request after the other:
POST /v1/tenants with { "name": "..." } returns the id of the tenant.
POST /v1/locations with { "tenantId": <id>, "name": "..." }.
POST /v1/groups with { "tenantId": <id>, "locationId": <id>, "name": "..." }.
POST /v1/devices/bulk/move with { "ids": [...], "locationId": <id>, "groupId": <id> }; "tenantId": <id> may be sent as well as a cross-check that the location belongs to the new tenant, see X.9.12.
The token needs the scopes organization:write and devices:write, and organization:read and devices:read to read back what it wrote. The bound account needs tenants_enabled, tenants_manage, tenants_add, tenants_locations_add, tenants_groups_add, devices_general and devices_move. The tenant the devices come from has to be one of the token's tenants as well: the device and the target of a move both have to be inside the token's scope. For an automation, bind the token to an account of its own that holds only these permissions and tenants.
Text filters.GET /v1/devices filters by deviceName, label, operatingSystem, domain, lastActiveUser, ipAddressInternal, serialNumber and agentVersion:
A value without a wildcard has to match the whole field. Case and accents are ignored.
* stands for any number of characters and ? for exactly one: deviceName=web-* (starts with), deviceName=*-prod (ends with), deviceName=*web* (contains), deviceName=web-???? (four characters after the prefix).
\*, \? and \\ stand for the character itself. % and _ have no special meaning.
A value may be at most 255 characters long and contain at most four *; anything else answers 400 invalid_parameter and names the parameter.
All filters combine with AND, also with the existing ones. platform, deviceClass and geoCountryCode are compared exactly and take no wildcards. search looks for its text anywhere in deviceName, label, serialNumber or ipAddressInternal and takes no wildcards either.
Changed devices.updatedSince (RFC 3339) lists the devices whose name, label, tenant, location, group, platform, device class, authorization, block, operating system, domain, architecture, internal IP address, hardware fields, serial number, manufacturer or model changed at or after that time. The server compares these fields every two minutes. A check-in, the load figures, the external IP address and the agent version do not count as a change. A new device is reported as changed once.
GET /v1/mobile-devices has the text filters deviceName and label. GET /v1/tenants, GET /v1/locations and GET /v1/groups have the text filter name, for example to look a tenant up before creating it.
Sorting.GET /v1/devices sorts by id, deviceName, label, lastAccess, platform, tenantName, locationName, groupName, operatingSystem, serialNumber, agentVersion, cpuUsage, ramUsage and geoCountryCode; a leading - sorts descending, several fields are separated by commas. id follows the order in which the devices were first registered (there is no first-seen timestamp), so sort=-id returns the most recently registered device first. Devices with equal sort values keep a fixed order, so consecutive pages neither repeat nor skip a device.
The highest name with a prefix, without reading the list:
GET /v1/devices?deviceName=web-*&sort=-deviceName&pageSize=1&fields=id,deviceName
total in the answer is the number of devices that match.
Moving devices.PATCH /v1/devices/{id} and POST /v1/devices/bulk/move move a device with locationId, groupId or both. A move needs the permission devices_move on the bound account.
locationId moves the device to that location and to the tenant the location belongs to. A location of another tenant therefore moves the device into that tenant. The group of the device is cleared, unless the device is already in that location.
groupId moves the device into that group and with it into the group's location and tenant. Sent together with locationId, the group has to belong to that location; otherwise the answer is 400 invalid_parameter.
PATCH with "groupId": null takes the device out of its group and leaves the rest as it is.
The bulk form accepts tenantId as well. It is optional and has to be the tenant of the target location. tenantId alone answers 400 invalid_parameter, because a device always belongs to a location: send locationId (a location of that tenant) and optionally groupId.
The device and the target both have to be inside the token's scope. A target outside it answers 400 invalid_parameter, a device outside it 404 (in the bulk form: not_found for that item).
A target in a tenant that is being deleted answers 409 conflict. An id that is not an integer answers 400 invalid_parameter.
GET /v1/patch-compliance (scope patch:read) returns the compliance figures of the patch management overview (see Chapter 7.4) for the devices inside the tenants and locations of the token:
Field
Meaning
asOf
The instant the figures were computed (RFC 3339, UTC).
scope
The compliance scope of Patch Management → Settings the figures were counted with: sources, types, severities (the bucket keys critical, high, medium, low, unspecified), approval (approved or approved_and_pending) and graceDays.
devicesTotal
Authorized devices that reported an update inventory in which every operating system source answered, with or without entries in the update catalog. A Linux or macOS device without pending updates is counted (as compliant); a device that has never reported, or a Linux device with a package manager NetLock does not patch (zypper, pacman), is not counted.
devicesCompliant
Devices with no scored update outstanding. A device whose open updates all lie outside the scope is compliant.
devicesSecurityCompliant
Devices with no security-relevant scored update outstanding (Security classification, Critical, High or Important severity, or a CVE).
compliancePct, securityCompliancePct
The two groups as a percentage of devicesTotal, one decimal; 0 when no device is counted. securityCompliancePct is the headline figure of the overview.
devicesMissingCritical, devicesMissingSecurity
Devices with a scored update of severity Critical, or a security-relevant scored update, still outstanding.
overdueSecurity, overdueCritical
Outstanding device-update pairs past their SLA deadline that are security-relevant, or rated Critical.
The figures are counted by the same statements the overview runs, so they match the page for an account with the same tenants. The scope is instance-wide and is changed on the Settings tab (7.6); the API does not change it.
GET /v1/devices/{id}/updates and GET /v1/updates carry inComplianceScope per row: true when the update counts toward compliance under the saved scope, false for an update the console marks as Not scored (for example a driver update, an update of a source outside the scope, a pending update while only approved updates are scored, or an update still inside the grace period).
GET /v1/devices and GET /v1/devices/{id} (scope devices:read) return three fields from the device's last inventory upload:
Field
Meaning
macAddress
The MAC of the network adapter that carries ipAddressInternal (the same adapter Wake on LAN uses), upper case and colon separated, e.g. AA:BB:CC:DD:EE:FF. null when no adapter carries that address, when the device has not uploaded an inventory, or when the adapter reports no valid MAC. A device with several active adapters exposes only this one here; every adapter is listed by GET /v1/devices/{id}/inventory/network-adapters (devices:inventory:read).
cpuCores
Physical cores, the total of all processor packages.
cpuLogicalProcessors
Logical processors (threads), the total of all processor packages.
The fields honour ?fields=; ?fields=id,macAddress reads only what it needs. They cannot be sorted or filtered.
On multi-socket Windows and Linux machines, the counts cover all processor packages with agent 3.3.0.11 or later.
manufacturer and model are reported by Windows, Linux and macOS agents 3.3.0.11 and later (Windows: Win32_ComputerSystem; Linux: the DMI vendor and product name; macOS: Apple and Model Name (Model Identifier), e.g. MacBook Pro (MacBookPro18,3)). An older desktop agent leaves them null.
Text values the device did not report are null: operatingSystem, domain, architecture, ipAddressInternal, ipAddressExternal, antivirusSolution, firewallStatus, cpu, ram, gpu, mainboard, tpm, serialNumber, manufacturer, model, lastActiveUser, lastBoot and timezone. label and notes are entered by people and keep an empty string.
An agent package configuration is what an agent installer enrols with: tenant, location, server addresses, language, installer texts and forward proxy. Its package guid is part of the installer's download address; treat it like a password.
Scope
Calls
agents:read
GET /v1/agent-packages, GET /v1/agent-packages/{id}
agents:write
POST /v1/agent-packages, PATCH /v1/agent-packages/{id}, DELETE /v1/agent-packages/{id}
agents:installer-url:read
GET /v1/agent-packages/{id}/installer-url. Sensitive: the link enrols any machine it runs on. Every retrieval is audited and the call has its own rate limit.
The writing calls need the account permission agent_installers_enabled. A package outside the token's tenants (or, for a token restricted to locations, outside its locations) answers 404.
tenantId is required and has to be inside the token's scope. locationId has to name a location of that tenant, otherwise 400 invalid_parameter. A token restricted to locations has to name one of its own locations; without locationId or with another location it answers 403 location_restricted.
Defaults: the instance's own server addresses, languageen-US, ssltrue, the standard installer texts, proxyModeauto.
Answers 201 { id, created, installerUrlNote }. The guid is never returned. A name that already exists answers 409 duplicate_name.
A package created through the API is always unmanaged. Managed packages (one per tenant and location) are created by the console.
Change.PATCH /v1/agent-packages/{id} uses merge-patch: a field left out stays as it is. tenantId cannot be changed. locationId is checked as for create. Naming any proxy field rewrites the whole proxy block. A managed package answers 409 managed_package.
Delete.DELETE /v1/agent-packages/{id} removes the configuration, its package guid history and its installer build state. On an instance with the file server role it also removes the stored installer files; elsewhere the files stay on disk, but their download address answers 410 because the guid is gone. Answers 204.
409 package_in_use while devices still authenticate with the current guid or a guid that has not been revoked. Their agents would no longer be able to connect. The detail names the number of devices. Move or uninstall those devices first. A device with a queued uninstall counts until it has been removed.
409 managed_package for a managed package while its location exists, because the console would create it again. Once the location has been deleted, the managed package can be deleted here.
Installer link.GET /v1/agent-packages/{id}/installer-url?architecture=<win-x64|win-arm64|linux-x64|linux-arm64|osx-x64|osx-arm64> returns the download URL of a built installer with its sha512. An installer that is not built yet answers 409 with its build status. Installers are prebuilt only for the managed packages the console keeps per tenant and location. An unmanaged package, which includes every package created through the API, has no prebuilt installer and answers 409 installer_not_available; download its installer from the console's agent download dialog instead.
Custom SQL in report templates runs only as the MySQL user configured under Settings → SQL access (see Set up SQL access). Statements that match the ones shipped with the release (built-in templates and unchanged copies of them) run without it.
Code
Status
Calls
Meaning
sql_access_not_configured
403
POST /v1/report-templates, PATCH /v1/report-templates/{id}, POST /v1/reports/generate, POST /v1/report-schedules, PATCH /v1/report-schedules/{id}
The template (sent, or referenced by the generation or the schedule) contains custom SQL and SQL access is not configured or the configured user is refused. Always the case on cloud instances.
sql_invalid
422
POST /v1/report-templates, PATCH /v1/report-templates/{id}
MySQL refused a statement when it was checked with EXPLAIN as the SQL access user. The detail carries MySQL's message and the name of the widget.
An edit share applies to that one template.
POST /v1/report-templates and PATCH /v1/report-templates/{id} answer with warnings: widgets whose SQL does not filter by tenant, or names @tenant_id in a form that is not replaced, and templates that describe the whole instance. They are notes only; nothing is refused because of them.
Without tenantIds, a token that reaches every tenant reports over all tenants (allTenants: true in the answer); any other token reports for its own tenants. perTenant: true makes one report per tenant (at most 25) and answers 202 with reports: [{ id, tenantId }]; the request counts once against the report rate limit. templateId names a stored template; the built-in templates have no id, generate a copy of one.
GET /v1/reports, GET /v1/reports/{id}
tenantIds, filter tenantId
tenantIds is the list of tenants a report covers, null for all tenants. tenantId matches reports whose list contains the tenant and reports over all tenants. The download is named <template>_<tenant>_<date>_<time>.<extension> for a report made for one tenant.
A new schedule without tenantIds covers all tenants, including tenants created later, for a token that reaches every tenant (tenantIds: null in the answer), otherwise the token's tenants; tenantIds: null asks for all tenants explicitly, an empty list is refused. PATCH keeps the stored tenants and the webhook delivery when they are not sent. exportFormat accepts JSON. sendToTenantContacts sends each report made for one tenant to the report contacts of that tenant.
A report for selected tenants leaves out widgets whose SQL does not filter by tenant (Chapter 11.10); a template that describes the whole instance answers 422 for anything but all tenants combined.
Tokens with some tenants. A token that does not reach every tenant lists only generated reports and schedules whose tenants are all its own; reading, downloading, changing or deleting any other one answers 404. A token restricted to locations answers 403 location_restricted for POST /v1/reports/generate and for creating or changing a schedule, because a report covers whole tenants.
The learning period of a device (see Chapter 6.8) can be read and controlled per device, the same way as on the device's USB Devices tab.
Call
Scope
Permission
GET /v1/devices/{id}/device-control/learning
devices:read
—
POST /v1/devices/{id}/device-control/learning/relearn
devices:usb-learning:write
devices_usb_learning
POST /v1/devices/{id}/device-control/learning/end
devices:usb-learning:write
devices_usb_learning
The answer of all three calls is { deviceId, status, policyId, policyName, source, startedAt, learningUntil, initialScanOnly, requestedBy, requestedAt }, with times in UTC. status is none, pending (a re-learn was requested and starts at the device's next policy sync), learning, done or migrated (learned under the policy-wide auto-whitelist of a release before 3.3.0.11).
relearn stores the request and asks a connected device to sync right away. It answers 422 unsupported_platform for a device that is not a Windows computer and 422 device_control_off when the device's policy has Device Control off or the device has no policy.
end ends a running or requested period at once and answers 409 not_learning when none runs.
devices:usb-learning:write is a dangerous scope: while a learning period runs, every device connected to the device is whitelisted for it. Existing tokens do not get the scope; it has to be added to a token explicitly.
A device outside the token's tenants answers 404. Every re-learn and end is written to the audit log.
The learning period is set with auto_whitelist and auto_whitelist_duration_minutes (0 = devices connected when learning starts, up to 20160) in a policy's Device Control settings; auto_whitelist_until is ignored.
GET /v1/device-control/whitelist (scope devicecontrol:read) marks the entries a device learned with autoLearned: true. Their author is Auto-Whitelist (Agent: <device name>) with the device's current name; for an entry whose device was deleted it keeps the name the device had when the entry was learned. Entries created in the web console or over the API have autoLearned: false and the account as author.
POST /v1/tickets/{id}/comments, POST /v1/tickets/{id}/close and POST /v1/tickets/{id}/reopen take an optional format next to comment. A comment made through the API is always an internal note.
format is text or html; any other value answers 400 invalid_parameter. On close and reopen it is ignored when no comment is sent. The 201 of /comments reports the resolved format.
Without format (or with null) the format is detected from the content. It is html when the comment starts with <!DOCTYPE html, contains a <br>, <hr> or <img …> tag, or contains a known HTML element with its closing tag: html, head, body, style, div, p, span, table, tbody, thead, tr, td, th, ul, ol, li, h1–h6, b, strong, i, em, u, a, pre, code, blockquote, font, center. Everything else stays text, for example List<string>, a < b, <hostname>, <# … #> or <Configuration>…</Configuration>.
For text that contains such tags, or HTML built from other elements, send format.
text is shown as written, with its line breaks. In GET /v1/tickets/{id}/comments, body holds the comment and bodyHtml is empty.
html is stored as delivered and returned in bodyHtml. body holds the text derived from it, without <style>, <script> and <head> content. It is empty when the HTML holds no text, for example only an embedded image; the note is still accepted.
The console cleans HTML when it shows it: style blocks and scripts are removed, external images do not load, links to web addresses are not clickable, and only a safe set of inline styles remains. An e-mail template therefore shows its content, but not the design of its stylesheet.
POST /v1/tickets is not affected: description stays plain text.
Events report what happened; an alert says what is wrong right now. GET /v1/alerts folds the events of one problem into one entry with a state. It needs the scope alerts:read.
An alert is the event that opened it: its id is the id of that event. Repetitions raise occurrences and lastSeenAt; severity is the highest severity the alert reached.
Source
Opens with
Closes with
resolvedBy
sensor
a sensor event or an execution error of a sensor, severity above low
the notice Sensor Resolved of that sensor, when the sensor has Notify when resolved switched on; otherwise reading or hiding the event
every event above severity low; each event is an alert of its own
reading or hiding the event
read, hidden
Other website events (performance, certificates, content), jobs, SNMP discovery, remote shell results and rate limiting open no alert.
Sensors. The agent sends a resolved notice only for a sensor with that setting, and only after a trigger. A sensor without the setting, an event of an older agent without a sensor id and an execution error alone have nothing to wait for, so their alert ends like a one-shot alert. Repetitions still fold into that one alert.
Difference from the dashboard. The sensor status on the dashboard counts a sensor as acknowledged once its event is read or hidden. The alert of a sensor that sends a resolved notice stays open until that notice arrives, because reading an event does not fix the cause.
Upper limit. Every open alert, of any source, is resolved with resolvedByexpired when no new event arrived for 30 days (Settings → Retention). A problem that keeps producing events stays open; a device that stays offline writes no further events and its alert ends after that time. An open alert is resolved with resolvedByauto when its device or tenant is removed, and a sensor, uptime or external alert also when its device loses the authorization.
Moved devices. An alert follows its device. When a device moves to another tenant, the open alert with all its events belongs to the new tenant, usually within a minute and at once with the next event. The old tenant can no longer read it.
Feed. The list runs oldest change first. Page with limit and cursor, then keep the last nextCursor and ask again later: it is also returned on the last page, and every change to an alert moves the alert behind it. updatedSince (RFC 3339) sets the start of a feed and is ignored when a cursor is given.
GET /v1/alerts?updatedSince=2026-11-01T00:00:00Z&minSeverity=high&limit=100GET /v1/alerts?cursor=<nextCursor>
Filters: state (open, resolved), tenantId, deviceId, source (comma separated), minSeverity (low, moderate, high, critical). GET /v1/alerts/{id} returns one alert, GET /v1/alerts/{id}/events the opening event, the repetitions and the all-clear.
A change shows up within about 15 seconds. An alert belongs to the tenant of its device, or to the tenant named on the event when it has no device. A token limited to locations sees only alerts of devices in those locations.
Retention. The cleanup keeps the opening event of an open alert, and of a resolved alert an integration still follows. Later events of an alert age normally; GET /v1/alerts/{id}/events then lists what is left.
POST /v1/alerts/ingest with the scope alerts:ingest writes an event of type 16. The console lists it, and the notification targets receive it like any other event.
{ "source": "backup", "dedupKey": "plan-7", "deviceId": 12, "severity": "high", "title": "Backup failed", "description": "Plan 7 ended with an error."}
source: 1 to 32 lower case letters, digits, - and _. It becomes reportedBy of the event.
dedupKey: identifies the alert of a device, or of a tenant when no device is named, inside the source, up to 140 characters. Surrounding spaces are removed; upper and lower case are different keys.
deviceId or tenantId. A token limited to locations has to name a device.
severity and title are required for state open.
state: open (default) or resolved.
Reports for the same device, or for the same tenant without a device, with the same source and dedupKey fold into one alert until a report with state resolved closes it. A later report opens a new alert. A report that repeats an open alert does not notify again. An alert nobody closes ends with the upper limit in X.9.19. The answer is 202 with eventId, key and state; the alert exists a few seconds later. Idempotency-Key is honoured.
system is a lower case name of up to 64 letters, digits, dots, - and _. The body of PUT holds externalId (up to 191 characters) and optionally externalName. A token limited to locations can read the references of its tenants but not change them (403 location_restricted), because such a reference applies to all locations. External ids compare exactly, including case. The search returns at most 200 objects, only inside the token's scope. Removing a device or a tenant removes its references. external-refs:read requires tenants_enabled, external-refs:write additionally settings_integrations_manage.
GET /v1/tenants/{id}/usage and GET /v1/usage/tenants (all tenants of the token) with the scope usage:read count the devices of a tenant over a period. The server records every device once a day, shortly after midnight on the clock of the instance; history starts on the day the instance was updated to 3.3.0.11. usage:read requires tenants_enabled and devices_general.
Parameter
Meaning
Default
from, to
Period, yyyy-MM-dd, inclusive, at most 400 days
Current month up to yesterday
aggregate
max, avg or last: which number value returns
max
authorizedOnly
Only devices that were authorized on that day
true
excludeBlocked
Leave out devices that were blocked on that day
true
onlineInPeriod
Only devices that were seen on at least one day of the period
A day counts the devices of that day that match. max, avg (rounded, .5 upwards) and last are computed over the days of the period for which a record exists; a day with a record and no matching device counts as zero. The answer holds value, max, avg, last, the number of days, and current, the same rules applied to the devices as they are now. GET /v1/tenants/{id}/usage also lists daily.
A device that checks in shortly after midnight, before the record is written, counts as seen on the day before. A day on which no server ran has no record. days says how many days of the period have a snapshot, tenantDays on how many of them the tenant had any device, whatever the rules and filters. tenantDays 0 means that the period says nothing about the tenant, which is not the same as a count of 0.
Subscriptions (/v1/webhooks) know these event types. A subscription without a list of events receives all of them, also types added later.
Every delivery is signed; X.10 shows how a receiver verifies it, with examples in C#, Python and Node.js. Subscriptions can also be managed in the web console under Settings → Integrations → Signed webhooks.
Type
Sent when
data
event.created
A row was added to the events
The event with sensorId, alertId and consoleUrl
device.registered
A device appeared
The device
device.updated
A field listed in X.9.12 under updatedSince changed
The device with updatedAt and consoleUrl
device.deleted
A device was removed
id, tenantId, deviceName, deletedAt
alert.opened
An alert was opened
The alert as in GET /v1/alerts/{id}
alert.updated
An open alert fired again
The alert
alert.resolved
An alert was resolved
The alert
A subscription made with a token limited to locations keeps that limit (locationIds) and receives only what happened in those locations, by the location the device has at delivery time. Events and alerts without a device and device.deleted have no location and are not delivered to it. A token limited to locations sees and changes only subscriptions inside its locations.
A new subscription starts at the present. Several changes between two runs of the feed arrive as one alert.updated; alert.opened always comes before the other events of an alert. A subscription also gets alert.opened for an open alert whose device moved into its tenants. event.created waits up to two minutes for the alert state so that alertId is set. consoleUrl is the link to the device in the console and is null without a public console URL. A new device can additionally produce one device.updated.
A connection of the integrations store reads NetLock through this API with a token of its own. Such a managed token is an ordinary row in the token list with the chip Integration: <name>, and these differences:
It is valid only on the local listener of the server (Integrations:Loopback_Port, by default 127.0.0.1:7480). The public port answers it like an unknown token, with 401.
It cannot be edited, rotated or revoked in the token list. It belongs to its connection: NetLock replaces it every 30 days and when the account of the connection changes, and revokes it when the connection is disconnected or deleted.
Its secret is stored encrypted for the server and is shown to nobody.
Its tenants are the mapped tenants of the connection, within the tenants of the account it is bound to. Its rights are its scopes and the live permissions of that account, as for any token.
It does not count against the token limit of the instance, and it has its own limit of 3000 requests per minute.
All its calls appear in the API request log like those of any other token.
Create and change (POST / PATCH /v1/app-hub/apps, scope apphub:write):
Field
Meaning
sourceType
file
fileId
Id of a file on the file server (GET /v1/files). Required on create. Needs the scope files:read and the permission file_server_enabled in addition (otherwise 403 insufficient_scope / 403 insufficient_permission); a file outside the token's reach answers 404.
Arguments of the actions, up to 2048 characters each, without control characters, passed to the program without a shell. An empty fileUpdateArgs means the install arguments.
fileUninstallMode
none (default), file (the same file with fileUninstallArgs; .msi, .exe, .ps1, .sh) or script (uninstallScript).
Guid, name and SHA-512 are read from the files row when the application is saved. Devices run the file only while it is unchanged; otherwise fileState shows changed.
targetOs follows the file type and scriptShell the target system; leave both out (another targetOs or a scriptShell answers 400). The application always runs elevated (requiresElevation: false answers 400) and has no install or update script.
version and detectionScript are required.
400 invalid_parameter also for: a file collected from a device or below devices/, a file in the netlock folder (404 without file_server_netlock), an unsupported type, a file without a valid SHA-512, an uninstall mode the type does not offer, script without uninstallScript, file fields on an application of another source.
PATCH: fileId picks a (new) file and pins its current SHA-512; without fileId the stored file and hash are kept. Changing the arguments or the uninstall mode needs file_server_enabled as well. Changing the application to another source clears its file fields. Pending deployments that have not started on any device take the new definition with the call (refreshedDeployments).
fileSha512 does not cover files the arguments load in addition (TRANSFORMS=, PATCH=, more package operands); keep them on a trusted share.
Read (GET /v1/app-hub/apps, GET /v1/app-hub/apps/{id}): a file application carries fileId (the files row its guid names, null when that row is gone), fileName (the name when the file was chosen), fileSha512 (the pinned hash), fileInstallArgs, fileUpdateArgs, fileUninstallArgs, fileUninstallMode and fileState: ok, missing (no files row has the guid) or changed (the row holds other bytes than the application pins; devices refuse to run it). fileState is null for other sources.
Software deployments (POST / PATCH /v1/software-deployments): an item with the appHubAppId of a file application copies the file's guid, its pinned SHA-512 and the arguments of the item's action from the application. An uninstall item needs an uninstall mode other than none; a file whose fileState is missing or changed is refused with 400. An item with sourceType: file always needs appHubAppId. GET /v1/software-deployments/{id}/items returns fileId, fileSha512 and fileArgs for file items.
Lock conflicts. A write of an App Hub application or a software deployment that collides with another write at the same moment saves nothing and answers 503 temporarily_unavailable with Retry-After: 5. Send the request again after that time.
Files in use.POST /v1/files over the name of a file and DELETE /v1/files/{id} answer 409 file_in_use when an App Hub file application or an open software deployment (draft, pending or running) uses the file. The problem document lists appIds and deploymentIds. Renaming and moving (PATCH /v1/files/{id}) stay allowed and keep the guid.