How to Enrol an Ubuntu/Debian Endpoint

This guide walks you through enrolling an Ubuntu or Debian-based Linux endpoint into ZEM Cloud.

Prerequisites

Before enrolling, ensure you have:

Supported OS: Ubuntu 20.04+, Debian 11+, or compatible derivative
Root Access: sudo privileges on the target machine
Network Access: Connectivity to your ZEM Cloud server (HTTPS port 443)
Curl: Installed on the system (usually pre-installed)

Enrolment Steps

Step 1: Open the Enrol Endpoint Wizard

Log in to your ZEM Cloud dashboard
Click the Enrol Endpoint button (green + icon) in the sidebar
Select Desktop as the device type
Select Ubuntu / Debian from the platform options

Step 2: Configure Enrolment Options

Configure the following settings:

Auto Reboot - Automatically schedules a reboot when an update requires it
Reboot Time - Time of day for scheduled reboots (24-hour format)

Toggle the Auto Reboot switch and set your preferred reboot time if needed.

Step 3: Copy the One-Liner Command

A customised installation command will be displayed. It looks like this:

curl -fsSL https://your-zem-server.com/install.sh | sudo bash -s -- --master-url https://your-zem-server.com --api-key YOUR_API_KEY --auto-reboot true --reboot-time 03:00

Click the Copy button to copy the command to your clipboard.

Step 4: Run the Command on the Target Machine

SSH into your Ubuntu/Debian server or open a terminal
Paste and execute the copied command
Enter your sudo password when prompted

Step 5: Wait for Installation

The script will automatically:

Detect your Linux distribution and version
Install required dependencies (`jq`, `bc`, `curl`)
Download the ZEM Cloud agent scripts
Create the configuration file
Set up systemd services and timers
Start the agent

Installation typically takes 30-60 seconds.

What Gets Installed

Agent Scripts

Configuration

File | Location
Agent Config | /etc/zen-update/agent.conf
Machine ID | /etc/zen-update/.machine_id

Systemd Services

Verifying Enrolment

You can confirm the agent is running successfully on your endpoint by running the following commands on the local endpoint.

Check Agent Status

# Check if the agent timer is active

systemctl status zen-update-agent.timer

# Check if the agent service ran successfully

systemctl status zen-update-agent.service

# View recent agent logs

journalctl -u zen-update-agent.service -n 50

View in Dashboard

Navigate to **Endpoint Overview** in ZEM Cloud
The new endpoint should appear within 60 seconds
Click on the endpoint to view details

Expected Output

When the agent runs successfully, you'll see:

Hostname and IP address in the dashboard
OS information (Ubuntu/Debian version)
Update count and system status
Real-time telemetry data

Configuration Options

The agent configuration is stored in `/etc/zen-update/agent.conf`:

MASTER_URL="https://your-zem-server.com"
TOKEN="your-api-key"
AUTO_REBOOT="true"
REBOOT_TIME="03:00"

Modifying Configuration

You can modify settings directly in the config file, but it's recommended to use the ZEM Cloud dashboard to push configuration changes.

Troubleshooting

Agent Not Running

# Restart the agent

sudo systemctl restart zen-update-agent.timer

# Enable the agent to start on boot

sudo systemctl enable zen-update-agent.timer

Network Issues

# Test connectivity to ZEM Cloud

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

# Check DNS resolution

nslookup your-zem-server.com

View Detailed Logs

# View full agent log

sudo cat /var/log/zen-update-agent.log

# Follow logs in real-time

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

Common Errors

Uninstalling the Agent

To remove the ZEM Cloud agent from an Ubuntu/Debian system:

# Stop and disable services

sudo systemctl stop zen-update-agent.timer zen-update-report.timer
sudo systemctl stop zen-update-telemetry.timer zen-update-hwinfo.timer
sudo systemctl disable zen-update-agent.timer zen-update-report.timer
sudo systemctl disable zen-update-telemetry.timer zen-update-hwinfo.timer

# Remove service files

sudo rm /etc/systemd/system/zen-update-*
sudo systemctl daemon-reload

# Remove agent scripts

sudo rm /usr/local/bin/zen-update-*.sh

# Remove configuration

sudo rm -rf /etc/zen-update

# Remove logs

sudo rm /var/log/zen-update-*.log