Troubleshooting sensors
Most sensor problems come down to the host, Docker or the network. Start with the sensor's page in the console, then look at the host. Where to look first In the console: open Sensors and select the sensor. Its page shows the status, warnings about the host's resources, failed updates, results waiting to upload, and its recent scans. On the host (as root): The agent's log is rotated automatically, so it doesn't fill the disk. Installation fails Message from the installer What to do run as root (pipe into: sudo sh -s -- --token …) Run the command exactly as the console shows it, with sudo. missing --token or that doesn't look like an enrollment token The command was cut off when you copied it. Copy it again from the console. Docker is required. Install it (or re-run with --yes) and try again. You answered no, or there was no terminal to ask on. Install Docker or add --yes. don't know how to install Docker on …; install it and re-run Your distribution isn't one the installer can install Docker on. Install Docker yourself, then run the command again. Docker is installed but not running (try: systemctl start docker) Start Docker with systemctl start docker (and systemctl enable docker so it starts at boot). an Orbital agent is already installed on this host This host already has an agent. If you're replacing it, revoke the old sensor in the console, then run docker rm -f orbital-agent && docker volume rm orbital-agent-state and get a new install command. unsupported architecture … Use an x86_64 host (arm64 is for testing only). Enrollment fails If the agent reports enrollment token invalid, expired or already used, the token can't be used again. Each install command: works once, and expires one hour after you create it. Go to Sensors, choose Add sensor again, and run the new command. The sensor shows offline A sensor shows offline when the console hasn't heard from it for a few minutes. Check, in order: Is the host up? If you just used Reboot host, wait a few minutes. Is the agent running? Run docker ps --filter name=orbital-agent. If it isn't listed, check Docker is running (systemctl status docker). What does the log say? Run docker logs --tail 100 orbital-agent. Can the host reach the console? The sensor needs outbound HTTPS to the console address in its install command, including a long-lived WebSocket connection. If your network has a web proxy or TLS inspection, make sure it allows this. Is the clock right? If the log says this host's clock is … ahead of / behind the server's, the clock is more than 15 minutes out. Turn on time sync (NTP) on the host. Was it revoked? If the log says server rejected this sensor (revoked?), the sensor was revoked in the console. Revoked sensors can't come back; install a new sensor. [!TIP] If the sensor goes offline in the middle of a scan, its results aren't lost: they're stored on the sensor and uploaded when it's back. A scan type isn't offered, or says the sensor can't run it Each sensor offers the engines its host is big enough for and its agent supports. The Overview tab lists the sensor's Capability and Engines, and the Scanners tab says why something isn't available: What you see What to do Needs a Standard-tier host (4 vCPU, 8 GB) or it runs on a Lite host; this needs a Standard-tier host Add CPU, memory or disk (the message says what's short), then choose Re-check resources. This host is below the minimum for a sensor The host is too small for any scanning. See Skills and requirements. its agent is … and this needs … or later The agent updates itself when idle. Check the sensor isn't showing Update failed. Not offered by the server yet This engine isn't available to sensors yet. Nothing to fix on your side. Not synced yet (Nuclei templates) or Scanner loading feed (OpenVAS) The sensor is still downloading or loading its vulnerability content. This is normal on a new sensor. Wait and check again. — not in your plan (in the scan form) The scan type depends on your plan. See…
OrbitalCyber documentation