Endpoint Troubleshooting

This guide covers common issues with desktop endpoints and how to resolve them.

Endpoint Shows as Offline

If an endpoint appears offline in the dashboard, work through these checks:

Check Network Connectivity

Verify the endpoint can reach your ZEM Cloud server. The agent needs HTTPS access (port 443) to communicate.

Linux/macOS:

curl -I https://your-zem-server.com/api/agent_version

Windows (PowerShell):

Invoke-WebRequest -Uri "https://your-zem-server.com/api/agent_version" -UseBasicParsing

A successful response indicates network connectivity is working.

Verify Agent is Running

Check if the agent service is active on the endpoint.

Linux (Ubuntu, Debian, Arch, Fedora):

systemctl status zen-update-agent.timer

macOS:

launchctl list | grep zeniar

Windows (PowerShell as Administrator):

Get-Service ZenUpdateAgent

Check Firewall Settings

Ensure HTTPS (port 443) is allowed for outbound connections. Common firewall commands:

Linux (UFW):

sudo ufw allow out 443/tcp

Windows (PowerShell as Administrator):

Get-NetFirewallRule | Where-Object {$_.Direction -eq "Outbound" -and $_.Enabled -eq "True"}

Review Agent Logs

Check the agent logs for error messages that indicate what's failing.

Linux/macOS:

sudo tail -50 /var/log/zen-update-agent.log

Windows (PowerShell):

Get-Content "C:\ProgramData\ZenUpdate\logs\agent.log" -Tail 50

Endpoint Not Appearing After Enrolment

If an endpoint doesn't appear in the dashboard after running the enrolment command:

• Wait for Initial Report - Allow at least 60 seconds for the first report to be sent
• Check Enrolment Output - Review the terminal output for any errors during installation
• Verify Network Access - Confirm the endpoint can reach your ZEM Cloud server
• Validate API Key - Ensure the enrolment key hasn't expired
• Check Agent Logs - Look for connection errors in the log files

If the enrolment command completed without errors but the endpoint still doesn't appear, try forcing a report:

Linux:

sudo /usr/local/bin/zen-update-report.sh

macOS:

sudo /usr/local/bin/zen-update-report-macos.sh

Windows (PowerShell as Administrator):

& "C:\Program Files\ZenUpdate\zen-update-report-windows.ps1"

Updates Not Detected

If an endpoint shows no pending updates when you expect there to be some:

Linux Systems

Ensure the package manager cache is current:

Ubuntu/Debian:

sudo apt update

Arch Linux:

sudo pacman -Sy

Fedora:

sudo dnf check-update

macOS

Check that the softwareupdate service is running:

softwareupdate --list

Windows

Verify the Windows Update service is running:

Get-Service wuauserv

If stopped, start it with:

Start-Service wuauserv

Force an Update Check

You can trigger an immediate update check from the ZEM Cloud dashboard:

1. Navigate to Endpoint Overview
2. Click on the endpoint name to open details
3. Click the Actions menu
4. Select "Update Now"

Remote Actions Not Executing

If a remote action (like reboot or shutdown) isn't being executed:

Check Action Queue

In the endpoint details, click "View Action Queue" to see the status of pending actions. Actions can be:

• Pending - Waiting to be delivered to the endpoint
• Delivered - Sent to endpoint, awaiting execution
• Completed - Successfully executed
• Failed - Execution failed (check error message)
• Expired - Action timed out before delivery

Verify Endpoint is Online

Actions can only be delivered when the endpoint is online. Check the "Last Seen" time to ensure the endpoint is actively reporting.

Check Action Expiry

Actions have a limited validity period. If an endpoint is offline for too long, the action may expire before delivery.

Review Agent Logs

Check the agent logs for errors processing the action. Common issues include:

• Permission errors (agent not running as root/administrator)
• Invalid action parameters
• Network interruption during delivery