Docs / Enrollment / Desktop / Enrol Macos

How to Enrol a macOS Endpoint

This guide walks you through enrolling a macOS endpoint into ZEM Cloud.

Prerequisites

Before enrolling, ensure you have:

  • Supported OS: macOS Ventura (13.0) or later (Sequoia/Tahoe recommended)
  • Administrator Access: Admin privileges on the target Mac
  • Network Access: Connectivity to your ZEM Cloud server (HTTPS port 443)
  • curl: Pre-installed on macOS

Enrolment Steps

Step 1: Open the Enrol Endpoint Wizard

  1. Log in to your ZEM Cloud dashboard
  2. Click the Enrol Endpoint button (green + icon) in the sidebar
  3. Select Desktop as the device type
  4. Select macOS 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-macos.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 Mac

  1. Open Terminal on your Mac (Applications > Utilities > Terminal)
  2. Paste and execute the copied command
  3. Enter your administrator password when prompted

Step 5: Wait for Installation

The script will automatically:

  1. Detect your macOS version
  2. Download the macOS-specific ZEM Cloud agent scripts
  3. Create the configuration directory and files
  4. Set up launchd LaunchDaemons
  5. Start the agent services

Installation typically takes 30-60 seconds.

What Gets Installed

Agent Scripts

Script | Location | Purpose
zen-update-agent-macos.sh | /usr/local/bin/ | Main agent for updates and actions
zen-update-report-macos.sh | /usr/local/bin/ | Status reporting

Configuration

File | Location
Agent Config | /Library/Application Support/ZenUpdate/agent.conf
Machine ID | /Library/Application Support/ZenUpdate/.machine_id

LaunchDaemons

LaunchDaemon | Interval
com.zeniar.zen-update-agent.plist | 60 seconds
com.zeniar.zen-update-report.plist | 60 seconds
com.zeniar.zen-update-telemetry.plist | 5 seconds
com.zeniar.zen-update-hwinfo.plist | 30 minutes

Location: /Library/LaunchDaemons/

macOS-Specific Features

Update Detection

The macOS agent uses softwareupdate for system updates:

  • Update Detection - Uses softwareupdate --list to detect available updates
  • Update Installation - Uses softwareupdate --install --all for system updates
  • Reboot Detection - Identifies updates that require restart

User Management

macOS user management uses sysadminctl and dscl:

  • Add User - sysadminctl -addUser
  • Remove User - sysadminctl -deleteUser
  • Lock User - dscl . -create /Users/$user AuthenticationAuthority ";DisabledUser;"
  • Unlock User - dscl . -delete /Users/$user AuthenticationAuthority

Verifying Enrolment

Check Agent Status

List ZEM Cloud LaunchDaemons:

launchctl list | grep zeniar

Check if the agent is running:

sudo launchctl list com.zeniar.zen-update-agent

View agent logs:

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

View in Dashboard

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

Expected Output

When the agent runs successfully, you'll see:

  • Hostname and IP address in the dashboard
  • macOS version information
  • Available system updates count
  • Real-time telemetry data
  • Hardware information (Mac model, processor, memory)

Configuration Options

The agent configuration is stored in /Library/Application Support/ZenUpdate/agent.conf:

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

Troubleshooting

Agent Not Running

Load and start the agent:

sudo launchctl load /Library/LaunchDaemons/com.zeniar.zen-update-agent.plist
sudo launchctl start com.zeniar.zen-update-agent

Unload and reload (restart):

sudo launchctl unload /Library/LaunchDaemons/com.zeniar.zen-update-agent.plist
sudo launchctl load /Library/LaunchDaemons/com.zeniar.zen-update-agent.plist

Permission Issues

macOS may require Full Disk Access for some operations:

  1. Open System Preferences > Security & Privacy > Privacy
  2. Select Full Disk Access in the left sidebar
  3. Add Terminal or the shell if needed

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

View system log for LaunchDaemon issues:

log show --predicate 'subsystem == "com.apple.launchd"' --last 1h | grep zeniar

Common Errors

Error | Cause | Solution
curl: (6) Could not resolve host | DNS resolution failed | Check network settings and DNS
curl: (7) Failed to connect | Server unreachable | Verify server URL and firewall rules
Operation not permitted | SIP or permission issue | Check System Integrity Protection settings
Launchd job not running | Plist error | Verify plist syntax with plutil

Validate LaunchDaemon Plist

Check plist syntax:

plutil -lint /Library/LaunchDaemons/com.zeniar.zen-update-agent.plist

Uninstalling the Agent

To remove the ZEM Cloud agent from macOS:

Stop and unload LaunchDaemons:

sudo launchctl unload /Library/LaunchDaemons/com.zeniar.zen-update-agent.plist
sudo launchctl unload /Library/LaunchDaemons/com.zeniar.zen-update-report.plist
sudo launchctl unload /Library/LaunchDaemons/com.zeniar.zen-update-telemetry.plist
sudo launchctl unload /Library/LaunchDaemons/com.zeniar.zen-update-hwinfo.plist

Remove LaunchDaemon plist files:

sudo rm /Library/LaunchDaemons/com.zeniar.zen-update-*.plist

Remove agent scripts:

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

Remove configuration:

sudo rm -rf "/Library/Application Support/ZenUpdate"

Remove logs:

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