Troubleshooting endpoint agents
Most endpoint agent problems come down to one of three things: the enrollment token, the network path to your console, or something on the computer stopping the agent. Start with the agent's own status and log on the computer, then work through the section below that matches what you see. For installing and general behaviour, see Endpoint agents. Check the agent on the computer Quick status (all systems) Run as root or in an elevated prompt: The output shows the computer's endpoint name and ID, the server it reports to, when it last sent its inventory, and whether the service is running. If it prints not enrolled, enrollment never completed. See The computer doesn't appear. To see which agent version is installed, run orbital-endpoint version (on Windows, use the full path shown above). Service and logs Service Check it Log Windows OrbitalEndpoint ("Orbital Cyber endpoint agent") Get-Service OrbitalEndpoint, or Services C:\ProgramData\OrbitalCyber\endpoint\agent.log macOS launchd com.orbitalcyber.endpoint sudo launchctl print system/com.orbitalcyber.endpoint /Library/Logs/orbital-endpoint.log Linux systemd orbital-endpoint systemctl status orbital-endpoint journalctl -u orbital-endpoint Things to know about the logs: Windows: the agent doesn't write to Event Viewer. Its log is the file above. When the file grows past 10 MB, it's renamed to agent.log.1 the next time the service starts. Only Administrators and SYSTEM can open this folder. Format: each log line is a JSON record. Look for "level":"WARN" and "level":"ERROR" lines. Restarts: the service restarts by itself if it stops: after 10 seconds on Linux and macOS, and after 10 seconds, 30 seconds and then 1 minute on Windows. To follow the Linux log live: The computer doesn't appear in the console 1. Check the error from the install. The install command, or the MSI log, shows why enrollment failed: Message What it means Fix enrollment token invalid, expired, revoked or used up The token can't be used anymore. Create a new token under Endpoints → Deploy agents and install again. The Enrollment tokens list shows whether each token is active, used up or expired. token and identity_key required The token is missing or was copied wrongly. Endpoint tokens start with oet_. Copy the token again. If you no longer have it, create a new one, because tokens are shown only once. --server must be an https:// URL The server address is missing or isn't https://. With the MSI, this means the SERVER property wasn't passed. Use your console's address, for example SERVER=https://orbital.saas.sageisg.com. The plan includes … endpoint agents and … are enrolled or The plan doesn't include endpoint agents Your plan's endpoint limit has been reached. Revoke computers you no longer need, or add endpoint agents on the Subscription page, then install again. The refused install still counts as one use of the token. Couldn't check the plan just now The plan couldn't be checked at that moment. Try again in a few minutes. run as administrator / root The install wasn't elevated. Run it as Administrator (Windows) or with sudo (macOS and Linux). 2. Check the network. The computer needs outbound HTTPS to your console's address. If a proxy is required, the agent uses the standard HTTPS_PROXY and NO_PROXY environment variables. It doesn't read the Windows proxy settings. The install scripts also check the download's SHA-256 checksum. If you see download corrupted (checksum mismatch), something on the network changed the file. Try again, or download the agent directly from the console. 3. On a Mac installed with the PKG, check that the config file existed before the package ran. Without the file, the package only places the agent and prints a reminder to enroll it with sudo orbital-endpoint install --server … --token …. The computer shows offline A computer shows offline when it hasn't checked in for 45 minutes. A computer that's switched off, asleep or disconnected is offline, and it comes back by itself. If the…
OrbitalCyber documentation