Debug an agent

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.

Before you start

• 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 — 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:

• Windows — C:\ProgramData\0x101 Cyber Security\NetLock RMM\<Agent>\debug.txt
• Linux — /var/0x101 Cyber Security/NetLock RMM/<Agent>/debug.txt
• macOS — /Library/Application Support/0x101 Cyber Security/NetLock RMM/<Agent>/debug.txt

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 watchdog may race you.

Steps

1. Create an empty debug.txt in the data directory of each agent you want to debug.

Windows (PowerShell, elevated):

New-Item -ItemType File -Path "C:\ProgramData\0x101 Cyber Security\NetLock RMM\Comm Agent\debug.txt"
New-Item -ItemType File -Path "C:\ProgramData\0x101 Cyber Security\NetLock RMM\Remote Agent\debug.txt"
New-Item -ItemType File -Path "C:\ProgramData\0x101 Cyber Security\NetLock RMM\Health Agent\debug.txt"

Linux (Bash, with sudo):

sudo touch "/var/0x101 Cyber Security/NetLock RMM/Comm Agent/debug.txt"
sudo touch "/var/0x101 Cyber Security/NetLock RMM/Remote Agent/debug.txt"
sudo touch "/var/0x101 Cyber Security/NetLock RMM/Health Agent/debug.txt"

macOS (Terminal, with sudo):

sudo touch "/Library/Application Support/0x101 Cyber Security/NetLock RMM/Comm Agent/debug.txt"
sudo touch "/Library/Application Support/0x101 Cyber Security/NetLock RMM/Remote Agent/debug.txt"
sudo touch "/Library/Application Support/0x101 Cyber Security/NetLock RMM/Health Agent/debug.txt"

2. Restart the agent services so they pick up the file. When you enabled debugging on more than one agent, simply restart all three.

Windows (PowerShell, elevated):

Restart-Service NetLock_RMM_Agent_Comm
Restart-Service NetLock_RMM_Agent_Remote
Restart-Service NetLock_RMM_Agent_Health

Linux (Bash, with sudo):

sudo systemctl restart netlock-rmm-agent-comm
sudo systemctl restart netlock-rmm-agent-remote
sudo systemctl restart netlock-rmm-agent-health

macOS (Terminal, with sudo):

sudo launchctl kickstart -k system/com.netlock.rmm.agent.comm
sudo launchctl kickstart -k system/com.netlock.rmm.agent.remote
sudo launchctl kickstart -k system/com.netlock.rmm.agent.health

3. 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.

4. 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.

Tip: Independent of debug mode, the services' standard output is available too. On Linux, use journald: journalctl -u netlock-rmm-agent-comm (likewise for the remote and health units). 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).

5. 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.

Verify it worked

• 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 — the timestamps on the files in Logs stop advancing.

Troubleshooting

• No log output appears even though debug.txt exists. The services were not restarted after the file was created — 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 silently creates debug.txt.txt, which the agent ignores. Create the file from PowerShell as shown above to be safe.
• The agent is offline or cannot reach the server — is debugging pointless? No. 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.

Related

• Guide H.1 — Deploy your first agent — install the agent and its three services.
• Uninstall an agent — remove the agent, including its data directories and logs.
• X.3 — Troubleshooting — symptom-cause-fix entries for the most common agent problems.
• A.9 — Logging & protocols — the server-side Logging page, the counterpart to on-device debug logs.