Enabling and Installing Workspace ONE UEM Relay Server / Pull Service on Linux


This guide documents the process of installing and troubleshooting a Linux-based Workspace ONE UEM Relay Server (Pull Service) using the Relay Server Cloud Connector package.

If you are reading this guide, you are likely already familiar with what a Relay Server is and the role it plays within a Workspace ONE UEM environment.

For a detailed overview of Relay Servers, their architecture, and supported deployment models, refer to the official Omnissa documentation:

Relay Servers Documentation
https://docs.omnissa.com/bundle/WorkspaceONE-UEM-Product-ProvisioningVSaaS/page/RelayServers.html

 In this tutorial, I will walk through the initial steps required to deploy a Workspace ONE Relay Server Cloud Connector (RSCC) along with a single Push Relay Server on Linux.

In this design:

  • The Relay Server Cloud Connector (RSCC) is the only server that communicates directly with Workspace ONE UEM.
  • A second Linux server is configured as a Push Relay Server and communicates exclusively within the internal network.
  • The Push Relay Server receives content from the Cloud Connector and makes it available to locally managed devices.
  • Both servers should provide a file distribution service such as SFTP or HTTPS for secure content delivery.

This approach minimizes external exposure, reduces firewall requirements, and allows content to be distributed efficiently to devices operating on internal or remote networks.

To begin, open the Workspace ONE UEM Console and navigate to the Product Provisioning configuration area. The first step is to enable the Relay Server Cloud Connector (RSCC) feature, which will be responsible for synchronizing content from Workspace ONE UEM to your relay infrastructure.

The second thing that you’ll need to do, is to generate a certificate (if you haven’t done so yet). Since i’ve already generated a certificate in my environment, I only have the option to regenerarte.

After that, you can download the relevant installer for your environment, as well as the configuration file.

Now, copy and extrat both files in the same directory on your Cloud Relay Server and run the installer. When the installer is asking for the “Discovery Text”, you can use the IP address of your server.

Considering that the installation was sucesfful, you can go ahead and configure a Cloud Relay Server in the Workspaace ONE UEM Console. 

Relay Server Installation on Linux

Environment

Relay Server installer:

WS1_Relay_Server_Cloud_Connector_<replace>_for_Linux.bin

Installation path:

/opt/airwatch/pull-service

Pull Service executable:

/opt/airwatch/pull-service/bin/AirWatch.PullService.Host

Log file:

/opt/airwatch/Logs/PullServiceLog.log

Step 1 - Install the Relay Server

Make the installer executable:

chmod +x WS1_Relay_Server_Cloud_Connector_4.1.0_for_Linux.bin

Run the installer:

sudo ./WS1_Relay_Server_Cloud_Connector_4.1.0_for_Linux.bin

Verify installation:

ls -l /opt/airwatch/pull-service

 

Step 2 - Verify Pull Service Installation

Confirm the executable exists:

ls -l /opt/airwatch/pull-service/bin/AirWatch.PullService.Host

Step 3 - Check Runtime Requirements

Determine which .NET runtime is required:

cat /opt/airwatch/pull-service/bin/*.runtimeconfig.json

Look for:

"framework": {

  "name": "Microsoft.NETCore.App",

  "version": "8.0.x"

}

or

"framework": {

  "name": "Microsoft.AspNetCore.App",

  "version": "8.0.x"

}

Step 4 - Download .NET 8 Runtime

Create a directory for .NET:

sudo mkdir -p /opt/dotnet

Download the required runtime version.

Example:

wget https://builds.dotnet.microsoft.com/dotnet/Runtime/8.0.20/dotnet-runtime-8.0.20-linux-x64.tar.gz

Step 5 - Extract the Runtime

Extract the archive:

sudo tar -xzf dotnet-runtime-8.0.20-linux-x64.tar.gz -C /opt/dotnet

Verify:

ls /opt/dotnet

You should see:

dotnet

host

shared

Step 6 - Verify Runtime Installation

Run:

/opt/dotnet/dotnet --info

Expected output should display:

.NET SDK / Runtime Information

Step 7 - Test Pull Service Manually

Set environment variables:

export DOTNET_ROOT=/opt/dotnet

export PATH=$PATH:/opt/dotnet

Launch the Pull Service manually:

cd /opt/airwatch/pull-service/bin

./AirWatch.PullService.Host

If the application starts successfully, proceed to service configuration.

Step 8 - Create Startup Script

Create:

sudo nano /opt/airwatch/pull-service/run-pullservice.sh

Contents:

#!/bin/bash

export DOTNET_ROOT=/opt/dotnet

export PATH=$PATH:/opt/dotnet

cd /opt/airwatch/pull-service/bin

exec ./AirWatch.PullService.Host

Make executable:

sudo chmod +x /opt/airwatch/pull-service/run-pullservice.sh

Step 9 - Create a systemd Service

Create:

sudo nano /etc/systemd/system/airwatch-pullservice.service

Contents:

[Unit]

Description=Workspace ONE Pull Service

After=network-online.target

Wants=network-online.target

[Service]

Type=simple

User=root

WorkingDirectory=/opt/airwatch/pull-service/bin

Environment=DOTNET_ROOT=/opt/dotnet

Environment=PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/dotnet

ExecStart=/opt/airwatch/pull-service/bin/AirWatch.PullService.Host

Restart=always

RestartSec=10

StandardOutput=journal

StandardError=journal

[Install]

WantedBy=multi-user.target

Step 10 - Reload systemd

sudo systemctl daemon-reload

Step 11 - Start the Service

sudo systemctl start airwatch-pullservice

Verify:

sudo systemctl status airwatch-pullservice

Expected:

Active: active (running)

Step 12 - Configure Automatic Startup

Enable startup after reboot:

sudo systemctl enable airwatch-pullservice

Verify:

systemctl is-enabled airwatch-pullservice

Expected:

enabled

 

Step 13 - Monitor Pull Service Logs

Pull Service logs are located at:

/opt/airwatch/Logs/PullServiceLog.log

View the last 100 entries:

tail -100 /opt/airwatch/Logs/PullServiceLog.log

Monitor in real-time:

tail -f /opt/airwatch/Logs/PullServiceLog.log

Search for errors:

grep -i error /opt/airwatch/Logs/PullServiceLog.log

Step 14 - Monitor systemd Logs

View recent service events:

journalctl -u airwatch-pullservice -n 100

Follow live:

journalctl -u airwatch-pullservice -f

Show detailed startup errors:

journalctl -xeu airwatch-pullservice

Configure Workspace ONE UEM Console

Considering that the installation was sucesfful, you can now go ahead and configure a Cloud Relay Server in the Workspace ONE UEM Console.

In the Pull Connection tab, you should add information from the installation json file, by default it should be located at “/opt/airwatch/Logs/PullServiceLog.log”. Look for ”DiscoveryText”, copy everything including the IP addresss and paste it without the quotation marks.

 

 

Now, make sure that you see something like this in Workspace ONE UEM Console:

 

After you add your first Push server, you should see something like this:

 

If you want to utilize the Relay Server for Windows Apps, you will need to toggle on the “Relay Server Content Transfer” button in the app “Deployment Options” tab. 

Final Thoughts

I hope you found this guide useful and that it saves you some of the time I spent troubleshooting the Linux Relay Server and Pull Service installation. Troubleshooting startup and runtime issuesIf you're deploying multiple relay servers, I highly recommend documenting your runtime version, installation paths, and service configuration so that future upgrades and troubleshooting efforts are consistent across environments.

Disclaimer

This document is provided as-is and is based on a specific lab and troubleshooting experience. Every environment is different, and configuration requirements may vary depending on your Workspace ONE UEM version, Linux distribution, security policies, and organizational standards.

Use the information in this guide at your own risk. I make no warranties, expressed or implied, regarding the accuracy, completeness, suitability, or reliability of the procedures described. I accept no responsibility or liability for any direct, indirect, incidental, or consequential damage, service interruption, data loss, security impact, or system issues resulting from the use of this guide.

As with any production change, always validate the procedure in a non-production environment, maintain appropriate backups, and follow your organization's change management processes before implementation.

Comments

Post a Comment

Popular posts from this blog

How to Enable DEX (Experience Management) for Omnissa Horizon - Step by Step

Image
In the era of modern distributed work, understanding user experience within virtual desktop infrastructure (VDI) is no longer a luxury - it’s an operational necessity. Omnissa Horizon, coupled with Workspace ONE Experience Management (DEX), gives IT administrators full visibility into VDI performance, from login latencies to application behavior. If you are looking to tap into these rich analytics, here is your definitive, step-by-step guide to enabling and validating DEX for your Omnissa Horizon environment. Step 1: Verify Prerequisites & Licensing Before writing a single line of code or deploying appliances, you must ensure your environment is properly licensed. DEX for Horizon requires a cloud-connected control plane and specific licensing tiers. Supported Core License: You must hold an active Horizon Universal Subscription or Horizon Apps Universal Subscription. The DEX Add-on: Experience Management features require the Workspace ONE Experience Management for Horizon add-on SKU...
Read more
How to access Omnissa's KCD Client tool on Unified Access Gateway To access the Omnissa-KCD-Client tool, you first need to enter the system’s shell either directly on the Linux machine or remotely via SSH using a tool such as PuTTY.  Next, follow the short video below, i've also included the commands below. docker ps docker exec -it {ContainerID} /bin/bash export KRB5CCNAME="MEMORY:" export KRB5_CONFIG="/opt/omnissa/seg/config/kerberos/krb5.conf" cp /opt/omnissa/seg/config/kerberos/kcd-client.conf /opt/omnissa/seg/kerberos-client/kcdclient.conf sed -i 's/log_level 2/log_level 4/' /opt/omnissa/seg/kerberos-client/kcdclient.conf cd /opt/omnissa/seg/kerberos-client/ You can use this syntax for testing KCD: ./Omnissa-KCD-Client -m kerberostest -n HTTP/{Your-SPN} -w {Your-KCD-User}@{your.domain}@YOUR.DOMAIN -u "{your-user}@YOUR.DOMAIN" -p {password} This was demonstrad on UAG version 2503. Good luck! :)
Read more

Deploying Microsoft Defender for Endpoint on macOS with Workspace ONE UEM

Image
Complete deployment blog based on Microsoft guidance and field experience. Executive Summary This document describes a complete deployment of Microsoft Defender for Endpoint on macOS using Workspace ONE UEM. It covers software deployment, required configuration profiles, onboarding, Defender settings, validation, and troubleshooting. The approach is based on Microsoft's macOS deployment model for third-party MDM solutions and practical implementation experience in Workspace ONE.   Microsoft References Deployment guide: https://learn.microsoft.com/en-us/defender-endpoint/mac-install-with-other-mdm GitHub repository: https://github.com/microsoft/mdatp-xplat Combined profile: https://github.com/microsoft/mdatp-xplat/blob/master/macos/mobileconfig/combined/mdatp.mobileconfig Step 1 – Download Defender for macOS Navigate to Microsoft Defender Portal → Settings → Endpoints → Device Management → Onboarding.     Select:   • Operating System: macOS   • Connectivity: Str...
Read more