Pull Service Based Relay Server Configuration

Pull service-based relay servers periodically contact the Workspace ONE UEM to monitor for new products, profiles, files, actions, and applications provisioned to devices under the pull relay servers purview. Configure a pull server to provision content to devices without excessive bandwidth use.

The server creates an outbound HTTPS connection on port 443 to the Workspace ONE UEM console and periodically polls for changes or additions. If the server finds changes or additions, then it downloads the new content onto the server before pushing it to its devices.

Pull service is preferred when using a NAT firewall or SaaS environments over on-premises hybrid environments. The reason is that SaaS customers typically do not want the service to tie up bandwidth when content is delivered from Workspace ONE UEM to the store server.

Note: The IP configured in the pull connection / pull discovery must be an internal IP address for the server. The service does not configure correctly if an external IP or NAT IP address is used.

Configure .NET Core Pull Relay Server, PS v2.0

You can configure a pull service v2.0 relay server based on Microsoft's .NET Core, the open source, cross-platform successor to their .NET Framework.

The .NET Core based pull service is built using .Net core 2.1. For more information, see https://dotnet.microsoft.com/.

Hardware Requirements


Component	Requirement
Server	1
CPUs	2 (2.0 GHz Intel Processor, x86 64bit)
Memory	4 GB
Storage*	25 GB

* Required storage size for a relay server must scale with the collective size of the files and applications that are distributed through it. A file is not deleted from the relay server until the associated File Action component is deleted from the Workspace ONE UEM console. Likewise, memory and CPU requirements must increase as the count of devices using the server grows.

On the client side, the pull service can use any dynamically assigned port, with no limitations, to connect to content pull on the server side.

Currently, .NET Core does not support HTTPS proxies.

Network Requirements


Component	Requirement
Outbound Traffic to Workspace ONE UEM console	Port 443
Protocol for Outbound Traffic to Workspace ONE UEM console	HTTPS

Software Requirements


Component	Requirement
Operating System	Windows 64 bit or RHEL7 64 bit or CentOS7 64 bit or Ubuntu 18.04 64 bit
Workspace ONE UEM	Version 1903 or later. Customers using versions 1903 through 1907 must enable the `PullServiceInstallerFeatureFlag`. Contact VMware Support for assistance in updating the database with this feature flag. The feature is enabled by default in versions 1908 and later.

Install Pull Relay Service v2.0

Visit https://my.workspaceone.com/products/Pull-Service and download the pull service installer for Windows or Linux platform.
- The Linux pull service installer has a hard-coded installation path of "/OPT/". You must configure this directory with sufficient write permissions and the top-most privileges. You must also have sufficient write permissions for the directory where the pull service is configured to download the contents.
- Linux Silent Installation Option: You have the option of running the Linux installation without being prompted. The following is an example of the code you might use to install silently the pull relay server for Linux with an NTLM proxy, basic authentication, and custom discovery text.
```
sudo ./VmwarePullserviceinstaller.bin -i silent -DPULL_SERVICE_CERT_PASSWORD=Test@1234 -DOUTBOUND_PROXY=1 -DOUTBOUND_PROXY_HOST=192.168.1.100 -DOUTBOUND_PROXY_PORT=808 -DOUTBOUND_PROXY_CREDENTIALS=1 -DOUTBOUND_PROXY_NTLM_AUTH=0 -DOUTBOUND_PROXY_DOMAIN= -DOUTBOUND_PROXY_USERNAME=john -DOUTBOUND_PROXY_PASSWORD=hello@1234 -DIS_DISCOVERY_TEXT=1 -DDISCOVERY_TEXT=og1
```
- Windows Silent Install Option (without custom discovery text):
```
VMware_WS1_PullService_2.0_for_Windows.exe /s /v" /qn /l*v pullservice.log AWUSERPROVIDEDPASS=<password>"
```
- Windows Silent Install Option (with custom discovery text):
```
VMware_WS1_PullService_2.0_for_Windows.exe /s /v" /qn /l*v pullservice.log AWUSERPROVIDEDPASS=<password> AW_IS_CUSTOM_DISCOVERY=1 AWDISCOVERY_TEXT=<Disc_Text>"
```
On-premises customers using older versions of the console can enable the PullServiceInstallerFeatureFlag. Contact VMware Support for assistance in updating the database with this feature flag.
While logged into Workspace ONE UEM, you must select an organization group (OG) to install the relay service onto. It is a best practice that the devices you intend to pull content from the relay service are managed under the same OG (or earlier) as that which the pull service is installed.
Once you have selected an OG that is equal to or above the OG that manages the devices that you want to use the pull service, navigate to Groups & Settings > All Settings > System > Enterprise Integration > Pull Service Installers and select the Download Configuration button. The Download pull service configuration screen displays.
Enter and confirm the Certificate password you want to use for the pull service certificate and select Download to save the ZIP file. Save the ZIP file to the same directory as the pull service installer you downloaded in step 1.
Extract the contents of the ZIP file to the directory in which you saved it.
Result: The ZIP file contains the pull service installer CONFIG file which is a file you require to run the installer. You must have the Windows EXE (or Linux BIN) Pull Service Installer file plus the CONFIG file extracted from the ZIP file together in the same directory. If you are installing the Linux variant, you might also have one of the NTLM enablers from step 2.
Run the Pull Service Installer, supplying the password you entered in step 5 when prompted. Continue with the remainder of the installation.
1. Select whether you wish to use an outbound proxy and, if applicable, enter the proxy configuration.
2. Select whether you wish to use Custom Discovery Text. The Pull Service uses Discovery Text to identify itself when communicating with Workspace ONE UEM servers. By default, Pull Service v1.0 and v2.0 use the local IP Address and MAC Address of the server but a custom value can be used instead. This is necessary to identify each Pull Server separately in rare cases where multiple Pull Servers do not have unique and distinct local IP Address and MAC Address values.
  When adding Custom Discovery Text, please note that the value entered in the installer is not the full Discovery Text value. The installer will append it to a unique GUID and store it in the appsettings.json file. This file can be found in the install directory of the Pull Service under the /bin folder.
  The Relay Server configuration in the Workspace ONE UEM console must use this Discovery Text value. For more information, see Configure a Relay Server.
** If you are installing the Linux version and you want to configure an NTLM proxy authentication, the "gss-ntlmssp" package must be installed. Select the download link that corresponds to your Linux flavor and install it now.
- For CentOS, download the following RPM file, https://centos.pkgs.org/7/epel-x86_64/gssntlmssp-0.7.0-1.el7.x86_64.rpm.html

Using the .NET Core Pull Service, Best Practices

Do not run multiple instances of pull service (old or new versions) on the same machine.
To ensure that devices can access the pull service without issue, install the pull service and its CONFIG file to an OG equal to or above the OG that manages those devices.
Once the pull service is installed, avoid selecting the Regenerate button on the Pull Service Installers settings page. Regenerating the certificate after the pull service is running breaks communication between the Workspace ONE UEM console and the pull service client. If you must regenerate the certificate, then you must rerun the pull service installer.
On-premises customers must generate and download the PSinstaller.CONFIG file directly from Global OG and not from Customer OG. This configuration enables an easy relay server move from OG 1 to OG 2 without having to reinstall the pull service every time. For more information, see Move an Existing Pull Relay Server from One Organization Group to Another.

Using the .NET Core Pull Service, Starting and Stopping the Pull Service

Start/stop service on CentOS and RHEL.

/etc/init.d/awpullservice {start|stop|status|restart)

Start the pull service.
```
service awpullservice start
```
Stop the pull service.
```
service awpullservice stop
```
Displays status of the pull service.
```
service awpullservice status
```
Restarts the pull service.
```
service awpullservice restart
```

Start/stop service on Ubuntu. Run this SH file, which is located in the pull-service/bin folder.
- Start the pull service.
```
sh start.sh
```
- Stop the pull service.
```
sh stop.sh
```
Start/stop service on Windows.
- Navigate to Run > services.msc, locate the Airwatch Pull Service, and select start, stop, or restart.

Using the .NET Core Pull Service, Appsettings.json Tweaks

The appsettings.json file settings presented here are the default values which you can change to modify the server's default behavior. The appsettings.json file is located in the pull service\Bin folder.

If the "discoveryText" value is set as null in the appsettings.json, then the pull service assembles and posts a default discovery text. This discovery text is composed of the merging of the pull server's IP address and Mac address in place of the null value.

The pull service must be manually restarted each time you change values in appsettings.json to apply the new settings.

"performSystemTaskIntervalMin": "720" (in minutes), the interval when the pull service logs are sent to the content pull endpoint. For more information, see Enable Pull Service Logging.
"clientPostTimeOut": "240" (in minutes), the amount of time the connection remains active before timing out. This time frame can increase as the size of your files increase to avoid connection timeouts.
"waitTimeOnFailure": "300" (in seconds), the amount of time you allow the pull service to rediscover the relay server if there is a connection error.
"logMaxEntries": "10000", the maximum number of log entries in a single log file.
"maxLogFiles": "5", the maximum number of logs generated.
"maxLogFileSize": "2000000" (in bytes), the maximum size a log file is allowed to get.
"enableConsoleLog": "false", for developmental purposes. Enable to activate the console log.
"proxyBypassOnLocal": "false", enable/deactivate the bypass proxy server for local addresses.

Migrating to the .NET Core Pull Service

The .NET Core pull service installer does not support an automatic migration with custom discovery text. When you reinstall the same version of the PS or upgrade the PS to a new version, the custom discovery text value is different each time. For this reason, make a note of the complete discovery text value under appsettings.json ("discoveryText") or from the Undiscovered Pull Relay servers page on the console after a fresh installation for the first time (for example: a6af8505-3d0c-4490-ab02-14db2fa3a80c_PSmachine1).

Saving the discovery text value is useful for when you accidentally uninstall the pull service or when you must move the relay server from one OG to another or from one server to another.

Follow this task when you do not want to use custom discovery text after migration and you want to continue using the same default discovery text. The default discovery text is the pull server's IP address plus Mac address.

Install the pull service v2.0 as described in the above section, Install Pull Relay Service v2.0, setting Custom Discovery Text, per your preference.
Note: If you want to apply Custom Discovery Text during the pull service v2.0 installation, the Relay Server configuration in the Workspace ONE UEM console must be updated after the installation.
From the pull server, navigate to the /bin folder of the installation directory, locate the appsettings.json file, and copy the full Discovery text (GUID_CustomText) with the Ctrl-C shortcut.
From the Workspace ONE UEM console, navigate to Devices > Provisioning > Relay Servers > List View and select the new pull relay server.
Select the Console Connection tab and paste (Ctrl-V) the Discovery Text from the old server onto the Discovery Text text box of this new server.
Save and Reactivate the server.
Restart the AirWatch Pull Service.

Recovering a Pull Relay Server v2.0 with Custom Discovery Text

Failure to recover the uninstalled or corrupted pull relay server may cause Workspace ONE UEM console to consider it a brand new server, causing the Pull Service to re-download all files that are already on the server. These steps apply for both Linux and Windows.

Take note of the current Custom Discovery Text of the corrupted/uninstalled Pull Relay Server. There are two ways to find the current Custom Discovery Text. You must select ...
- ...from the UEM console, navigate to Devices > Provisioning > Relay Servers > List View, select the corrupted/uninstalled pull relay server, then open the Console Connection tab where the Custom Discovery Text is displayed. Go directly to Step 2.
- ...from the pull server, navigate to the install directory of the Pull Service v2.0 and open the appsettings.json file located in the /bin folder. The Custom Discovery Text can be found listed in the JSON file under "discoveryText".
Navigate to Groups & Settings > All Settings > Enterprise Integration > Pull Service and download the latest Pull Service installer.
Uninstall the existing Pull Service from the Linux machine.
Run the Pull Service installer you downloaded in step 2. During the installation process, you are presented with the option to enter your own discovery text. Enter the custom discovery text your found in step 1.
- If using a Linux silent install, make sure you use the -DDISCOVERY_TEXT switch.
Restart the pull service.

The server resumes functioning as it did before, using the exact same discovery text. The already queued items and new items are served to the same directory path as before.

Pull Relay Server Security

Relay Servers may hold sensitive data. Pull servers use HTTPS, which encrypts data in transit. Consider encrypting it in storage as well by using tools like Bitlocker (Windows) and GnuPG (Linux) to enable OS-level encryption on the servers.

To create a pull relay server, you must first have an FTP, Explicit FTPS, Implicit FTPS in Pull configuration (Android only), SFTP, or HTTPS (Pull only) server to function as the relay server. FTP and FTPS servers must be compliant with RFC 959 and RFC 2228 set by the Internet Engineering Task Force.

Important: The ports you configure when you create your FTP, Explicit FTPS, Implicit FTPS in Pull configuration (Android only), SFTP, or HTTPS (Pull only) server must be the same ports you enter when creating a relay server in the Workspace ONE UEM console.

The process covers the installation of one server at a time. For a bulk installation, you must use a third-party application. Workspace ONE UEM supports importing servers in bulk through the Batch Import option. See Batch Import Relay Servers for more information.

Move an Existing Pull Relay Server from One Organization Group to Another

You can move an existing pull relay server installed with the Windows or new Linux installer by taking the following steps.

If you have a .NET Core pull service in an on-premises environment, you must generate and download the PullServiceInstaller.CONFIG file directly from Global OG (not from a Customer OG). This configuration allows you to move the relay server from OG 1 to OG 2 easily without reinstalling the pull service.

To ensure that devices can access the pull service without issue, select the "target" OG2 equal to or above the OG that manages those devices.

If you have a regular .NET Framework pull service or Java pull service installed, then use the following steps to move your relay server from on OG to another.

Delete the existing pull relay server from the original OG on the console. Once it is deleted, the pull discovery text that belongs to the pull service starts appearing on the undiscovered pull discovery page at Global OG.
Navigate to Devices > Provisioning > Relay Servers > Undiscovered Pull Relay Servers and locate the server by searching for your IP address (only available for on-premises).
Copy the pull discovery text that includes the IP address of your selected server.
Create a relay server in the new OG and activate it. After activating the relay server in the new OG, the pull service discovery text listed in the Undiscovered Pull Relay Servers page disappears.

Move an Existing Pull Service from One Relay Server to Another Relay Server

You can move the pull service from one relay server to another relay server by taking the following steps.

Such an action is advisable for when you must install the pull service onto a server with upgraded hardware and your pull service runs with custom discovery text. The old relay server was configured with this custom discovery text and as a consequence, the new relay server must also be configured with the same custom discovery text.

On the old relay server, locate the appsettings.json file and find the custom "discoveryText" value including the GUID. Select and copy this string to the clipboard with Ctrl-C.
Uninstall the pull service from the old relay server manually.
Using the latest version of the PS installer, install the pull service onto the new relay server.
From the Workspace ONE UEM console, update the FTP server details of the new relay server, located in the Device Connection tab.
In the Pull Connection tab, paste the custom discovery text you copied in step 1 in the Pull Discovery Text text box with Ctrl-V. The custom discovery text is now copied from the old machine to the new machine.
Save and activate the relay server from the Workspace ONE UEM console.
Restart the pull service.

Results: The new pull service, using the original custom discovery text, is configured on the new relay server. The new machine serves any existing pending or new content and the device selects content from the new relay server through FTP.

Configuring Session Persistence of a Load Balancer for Multiple Pull Relay Servers

You can configure a load balancer for multiple pull relay servers (both legacy and DotNetCore) by setting session persistence.

Relay servers process requests for content. When the number of requests exceed what a single server can handle, the solution is multiple relay servers. A load balancer can be used to distribute the load across multiple pull relay servers, for both legacy and DotNetCore pull services.

You must configure the load balancer with session persistence, ensuring that the same relay server receives each endpoint call per content request. If session persistence is not configured on the load balancer, subsequent requests that are routed to another relay server can result in a File-Not-Found error.

The following endpoints are called from the pull service to retrieve content.

GetNextManifest, retrieves the file metadata which the client must download.
GetFileInfoEx, retrieves the file-hash which is used to determine whether the file is already downloaded.
GetFileData, downloads the actual content.

Resolution: Since the file is downloaded locally to the server where Content-pull is running, you must configure the Load Balancer to have session persistence (IP based) to route all three endpoints to the same relay server.

Enable Pull Service Logging

You can enable the collection of pull service logs by taking the following steps.

Adjust how often the pull service logs are sent to the content pull endpoint by editing the number of minutes configured for the "performSystemTaskIntervalMin" setting in the appsettings.json file. This file is located in the pull service machine's \Bin folder.

Navigate to Devices > Provisioning > Relay Servers > List View.
Select the radio button above the Edit icon on the relevant Pull Server.
Select the More Actions button and select Pull Logging.
Enable the Collect Log File check box, enter the Start Date and End Date, then select Save.

Results: Pull service logging is enabled for the time period entered.

Completed logs can be found on the Workspace ONE UEM console server under x:\Airwatch\Logs\ContentPull\RSid\ replacing 'x' for the actual drive letter of your environment. SaaS environments must contact Support for further assistance.