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 .NET Core Pull Relay Server for Windows or Linux installer.
- 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 you 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.