Troubleshooting
Work down this page in order. Each step rules out a whole class of cause, so stopping to read logs before checking that the services are even running usually costs time.
Is it linked?
An installed Scanner that was never linked is inert by design: it runs, logs nothing interesting, and never appears in the platform.
sudo test -f /etc/optix/scanner-config.json && echo linked || echo "NOT linked"
If that file is missing, the link step did not complete. Re-run the link command from your Scanner group - see Scanners.
If it exists, check it points where you expect:
sudo python3 -c "import json;d=json.load(open('/etc/optix/scanner-config.json'));print(d['base_url'], d['organization_id'], d['scanner_group_id'], d['mode'])"
Two things to look at in that output:
base_urlmust be your own platform's API hostname. Each brand has its own, so a config copied from another deployment links to nothing.modemust berunning. A Scanner left inmaintenanceconnects fine and deliberately takes no work, which looks identical to a broken Scanner from the platform side.
sudo scanner mode running
Is the service up?
systemctl status --no-pager scanner-daemon optix-sync-tests.timer
Both should be active (running). One daemon runs every Scanner role, so if it is
down nothing happens at all: no work is fetched, no scans run, no results are reported.
If it is up, the roles that matter most for "nothing is happening" are visible in its
log by their component field: new-tasks fetches work and completed-tasks reports
results.
sudo systemctl restart scanner-daemon.service
Are the containers up?
docker ps
You should see two: redis and owaspZap.
redis carries every queue between the services, so if it is down nothing works,
including scan types that have no obvious connection to it. Check it first.
owaspZap only affects DAST. If it is missing, network vulnerability scanning continues
and only web application scans fail.
kali-linux and nmap are expected to be absent from docker ps. They sit behind the
disable compose profile and are invoked on demand rather than run as services.
Restart everything:
docker compose -f /etc/optix/docker-compose-scanner.yml restart
Or rebuild the containers from scratch:
docker compose -f /etc/optix/docker-compose-scanner.yml down && docker compose -f /etc/optix/docker-compose-scanner.yml up -d
Can it reach the platform?
The Scanner needs outbound HTTPS to your API hostname and nothing inbound.
curl -sS -o /dev/null -w "%{http_code}\n" https://<your-api-hostname>/
Anything other than a response code means a network path problem rather than a Scanner problem: check egress filtering, proxy configuration, and DNS resolution from the host itself.
Read the logs
Only once the above are clean. Every edge system logs the same way: one
structured JSON line per event, to its own systemd journal. Each line carries a
component field naming the subsystem that logged it, so you can narrow a busy
log to the part that matches the symptom instead of reading all of it.
Follow the whole daemon:
sudo journalctl -u scanner-daemon.service -f
See which components are active, and how much each is logging:
sudo journalctl -u scanner-daemon.service -o cat | grep -oE '"component":"[^"]+"' | sort | uniq -c
Narrow to one component:
sudo journalctl -u scanner-daemon.service -f | grep '"component":"vm"'
Components by edge system
The same component grep works against every edge system; only the service unit
changes.
| Edge system | Service unit | Components |
|---|---|---|
| Scanner | scanner-daemon.service | new-tasks, task-manager, active-discovery, vm, vm-status, dast, completed-tasks, engine |
| Apex | apex-daemon.service | daemon |
| Endpoint agent | cyberoptix-agent.service | agent, policy |
| Integrator | integrator-daemon.service | integrator |
| Log collector | syslog-collector.service | syslog-collector |
| Log shipper | syslog-shipper.service | syslog-shipper |
For the network vulnerability scanner specifically, vm port-scans each task's
hosts and submits the scan, vm-status reports progress and results back, and
engine runs the individual vulnerability tests.
Raising the log level
Every edge system logs at info by default. When you need more - for the
Scanner, a line per vulnerability test as the engine component runs it, which
is what to reach for when a scan completes but finds less than you expect - raise
the level through the optional env file each edge system already reads. You do
not edit the service unit.
Set the level in /etc/optix/.env (create the file if it is absent):
echo 'LOG_LEVEL=debug' | sudo tee -a /etc/optix/.env
Restart the service to pick it up. The step is the same on every edge system - only the unit name changes:
sudo systemctl restart scanner-daemon.service
Now each test the engine starts and completes is logged with its name and id:
sudo journalctl -u scanner-daemon.service -f | grep '"component":"engine"'
debug is verbose and meant for diagnosis, not day-to-day running. Revert by
removing the LOG_LEVEL line from /etc/optix/.env and restarting. That file is
shared by every edge service on the host, so the level you set applies to all of
them.
For a container:
docker compose -f /etc/optix/docker-compose-scanner.yml logs -f --tail 100 owaspZap
Common causes
| Symptom | Usual cause |
|---|---|
| Scanner never appears in the platform | Not linked, or base_url points at another deployment |
| Appears but takes no work | mode is maintenance, or its group is assigned to no zone |
| Tasks start and never complete | The platform is unreachable from the Scanner, so results sit on the retry queue |
| Everything fails at once | redis container is down |
| Only web application scans fail | owaspZap container is down or out of memory |
| Vulnerability results look stale | optix-sync-tests.timer disabled, or the license key is missing or invalid |
For the last one:
sudo systemctl status --no-pager optix-sync-tests.timer && sudo ls -la /etc/optix/license.key
sudo /usr/local/bin/sync-vulnerability-tests.sh
Still stuck
Collect the service states, the container list, and the last few hundred log lines from the failing service before opening a ticket - it is almost always the first thing asked for:
systemctl status --no-pager scanner-daemon > /tmp/scanner-state.txt; docker ps -a >> /tmp/scanner-state.txt; journalctl -u scanner-daemon.service -n 300 --no-pager >> /tmp/scanner-state.txt
Then contact [email protected] with /tmp/scanner-state.txt attached.