Skip to main content
Version: scarthgap_2-x

Debugging and Logs

Overview​

This guide explains how to monitor, debug, and analyze system behavior on devices running Clea OS.
Clea OS uses systemd as its default init system, providing advanced tools for managing services, processes, and logs.
The main utilities for debugging include systemctl, journalctl, and standard Linux diagnostic commands.

Managing System Services​

The systemctl command allows you to control and inspect system services.

Check Service Status​

List all active services:

# systemctl status

Check the status of a specific service:

# systemctl status docker

Restart or Enable a Service​

To restart a service:

# systemctl restart docker

To enable a service at boot:

# systemctl enable <service>

Replace <service> with the actual name of the service (for example, clea-agent, ssh, or docker).

tip

If a service does not start correctly, check its detailed logs using journalctl -u <service>.

Viewing System Logs with journalctl​

The journalctl tool provides access to the systemd journal, which collects logs from all services, kernel messages, and user-space processes.

Display Recent Logs​

# journalctl -n 50

This command shows the last 50 log entries. You can adjust the number as needed.

View Logs for a Specific Service​

# journalctl -u docker

This filters the log entries for the specified service, making it easier to isolate issues.

Live Log Stream​

To view logs in real time:

# journalctl -f

Press Ctrl + C to stop the live view.

note

The system journal is stored in binary format.
Avoid editing or deleting files manually under /var/log/journal; always use journalctl for viewing or filtering logs.

Network Diagnostics​

Network issues can often be traced to interface misconfigurations or missing routes.
The following commands help diagnose network connectivity problems.

Check Network Interfaces​

# ip a

Test Network Reachability​

# ping -c 4 8.8.8.8

Trace Network Routes​

# traceroute google.com

View Open Ports​

# netstat -tuln
tip

If netstat is not available, you can use ss -tuln for similar functionality.

Storage and System Status​

Monitor system resource usage and kernel messages with standard Linux utilities.

Check Disk Usage​

# df -h

View Running Processes​

# top

Check Memory Status​

# free -m

View Kernel Messages​

# dmesg

These commands help identify memory shortages, storage limits, or hardware initialization problems.

Troubleshooting Common Issues​

This section outlines some typical problems and how to approach them.

Service Fails to Start​

If a service fails to start or remains inactive:

# systemctl status <service>
# journalctl -xe

Use the second command to show extended logs, including errors or dependency failures.

No IP Address on Wi-Fi​

If a Wi-Fi interface does not obtain an IP address:

  • Verify that the wpa_supplicant.conf file is correctly configured.

  • Ensure the wireless interface is up:

    # ip link show wlan0

  • Reconnect manually using wpa_supplicant and udhcpc.

Tips for Effective Debugging​

tip

When diagnosing intermittent issues:

  • Always check both system logs (journalctl) and kernel logs (dmesg).
  • Capture logs before rebooting to avoid losing volatile information.
  • Use systemctl list-units --failed to quickly identify failed services.
  • Keep a USB or serial connection available for emergency debugging.

Summary​

Clea OS provides a full set of standard Linux tools for debugging and diagnostics.
By using systemctl, journalctl, and other core utilities, you can efficiently monitor system behavior, identify service failures, and resolve connectivity or performance problems.
These tools form the foundation for maintaining stability and reliability in Clea OS deployments.