Agent Logs & Troubleshooting (Day 2)

While the RasnuOS Agent is designed to be entirely invisible and self-healing, there may be times when you need to audit its behavior or troubleshoot connectivity issues.

Finding the Agent Logs

The agent runs as a native system service and logs its output cleanly to the host operating system.

On Linux (systemd)

You can view the real-time logs of the agent using standard journalctl commands. This is highly useful if the agent is failing to connect to the control plane.

# View the last 100 lines of agent logs
sudo journalctl -u rasnuos-agent -n 100

# Follow the logs in real-time
sudo journalctl -u rasnuos-agent -f

On macOS (launchd)

For local development machines or macOS build servers:

# View the live logs via stream
log stream --predicate 'process == "rasnuos-agent"'

On Windows Server (Event Viewer)

The RasnuOS agent writes natively to the Windows Event Log when running as a Background Service.

# View the last 20 agent events
Get-EventLog -LogName Application -Source "RasnuOSAgent" -Newest 20

Raw Log Files

If systemd journal forwarding is disabled, the agent also writes fallback logs to the disk:

• /var/log/rasnuos/agent.log
• /var/log/rasnuos/error.log

Common Troubleshooting Scenarios

1. Clock Drift (mTLS Failures)

Symptom: The agent logs show x509: certificate has expired or is not yet valid. Cause: Mutual TLS relies heavily on accurate timestamps. If your server's system clock is skewed by more than a few minutes, the cryptographic handshake will fail. Fix: Ensure NTP (Network Time Protocol) is enabled on your server:

Linux:

sudo timedatectl set-ntp on

macOS:

sudo systemsetup -setusingnetworktime on

Windows (PowerShell):

w32tm /resync

2. Strict Outbound Firewalls

Symptom: The agent logs show context deadline exceeded or connection refused. Cause: The server's outbound firewall is blocking outbound HTTPS traffic to the RasnuOS API. Fix: Ensure outbound TCP Port 443 is open to os.rasnu.com.

Restarting the Agent

If you need to manually restart the agent (e.g., after a major OS upgrade):

Linux

sudo systemctl restart rasnuos-agent

macOS

sudo launchctl stop com.rasnuos.agent
sudo launchctl start com.rasnuos.agent

Windows

Restart-Service -Name "RasnuOSAgent"