Commands to Manage a NodeZero^® Runner¶

This page provides essential commands and best practices for controlling your Runner, from checking its status and viewing logs to configuring auto-restarts and handling advanced features like credential injection. Whether you're scheduling recurring tests or troubleshooting, these tools help you maintain consistent security testing across your network.

UI queue management options

To monitor and manage Runner pentest queues via the NetZero Portal UI, see Managing Runners and Tests.

Runner service commands using systemd¶

These commands use systemd to manage the NodeZero Runner as a service on your NodeZero Host:

Check status:¶

systemctl status nodezero-runner-my-nodezero-runner

Stop the service:¶

sudo systemctl stop nodezero-runner-my-nodezero-runner

The queues abide

If you stop a Runner using this command, any Runner queue will resume in the same order when the Runner is available again.

Disable auto-start:¶

sudo systemctl disable nodezero-runner-my-nodezero-runner

Re-enable and start:¶

sudo systemctl enable nodezero-runner-my-nodezero-runner
sudo systemctl start nodezero-runner-my-nodezero-runner

Runner management commands using h3-cli¶

These commands leverage the h3-cli tool to manage your NodeZero Runner directly:

View logs:¶

Check the Runner log for activity or errors:

h3 tail-runner my-nodezero-runner

Stop the Runner:¶

Terminate the Runner process:

h3 stop-runner my-nodezero-runner

The queues abide

You manage a Runner's queue ordering and preemption not via CLI commands, but in the NetZero Portal. If you stop a Runner using this command, the queue will resume in the same order when the Runner is available again.

Delete the Runner:¶

Remove the Runner registration from Horizon3.ai. If the Runner is still running, it will re-register on its next heartbeat.

h3 delete-runner my-nodezero-runner

Auto-start Runner at system startup¶

To ensure your Runner restarts automatically after a system reboot:

Register with systemd: If your NodeZero host uses systemd, use the following command:
```
h3 start-runner-service my-nodezero-runner /tmp/my-nodezero-runner.log
```
This requires sudo for systemd operations.
The Runner will be registered as nodezero-runner-my-nodezero-runner.
Benefits:
- Starts automatically at boot.
- Restarts if the process fails.

Other tasks:¶

Renaming a Runner¶

Stop (and optionally delete) the Runner.
Start a new Runner with the desired name.
Update any templates with the new name.

Auto-Inject credentials¶

Use the Runner to auto-inject credentials into pentests for enhanced testing.

NodeZero Runner

Portal home

Commands to Manage a NodeZero® Runner¶