Skip to main content

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_url must be your own platform's API hostname. Each brand has its own, so a config copied from another deployment links to nothing.
  • mode must be running. A Scanner left in maintenance connects 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.

note

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 systemService unitComponents
Scannerscanner-daemon.servicenew-tasks, task-manager, active-discovery, vm, vm-status, dast, completed-tasks, engine
Apexapex-daemon.servicedaemon
Endpoint agentcyberoptix-agent.serviceagent, policy
Integratorintegrator-daemon.serviceintegrator
Log collectorsyslog-collector.servicesyslog-collector
Log shippersyslog-shipper.servicesyslog-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​

SymptomUsual cause
Scanner never appears in the platformNot linked, or base_url points at another deployment
Appears but takes no workmode is maintenance, or its group is assigned to no zone
Tasks start and never completeThe platform is unreachable from the Scanner, so results sit on the retry queue
Everything fails at onceredis container is down
Only web application scans failowaspZap container is down or out of memory
Vulnerability results look staleoptix-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.