This document describes how to create a Workspot Linux desktop template that not only includes the Workspot Linux Agent but the packages that turn Linux into an RDP-enabled Workspot desktop.
See Workspot Linux Desktop for more general information about Linux desktop support.
Installation is divided into four major steps:
Creating VMs on AWS EC2, Azure, or GCP.
Configuring the template VM.
Registering the VM with Control.
Testing.
Additional sections cover special configuration, management tasks, and troubleshooting.
1.0 Create Linux VMs
You must first create the VMs that will form the base of the templates visible in Workspot Control.
In general, choose the same VM parameters (RAM, vCPUs, etc.) for these VMs that you expect to use for the desktops built from the template.
For Azure or GCP, follow the steps in Creating Linux VMs on Azure and GCP.
For AWS EC2, follow the steps in Creating an Ubuntu Linux Template on Amazon AWS.
2.0 Configure the Template VM
Now that we have a base image, we need to log into it and install not only the Workspot Linux Agent but also the software packages that turn our generic image into an RDP-enabled graphical Linux desktop. These are done at the same time with a script provided by Workspot.
Follow the steps in the following article to configure the Template VM: Configuring the Template VM With the Workspot Linux Agent
3.0 Register the Template with Workspot Control
3.1 Azure Registration
Step 1. Stop the VM from the Azure portal.
Step 2. In Control, go to “Setup > Cloud > azure_cloud_name” and click on “Register Template.” Choose respective resource group and give respective VM name, click on the Search button. Your new template should be listed.
Step 3. Select your template VM and Click on “Save.”
Step 4. You successfully added Azure Linux Template to Control. It will be in Published mode.
3.2 GCP Registration
Unlike Azure, GCP requires additional steps before registering with Control.
GCP Console Pre-Registration
Step 1. Create a new intermediate image under the images tab in the GCP portal using the VM instance disk you created earlier.
Step 1a. Select a name for this intermediate instance. It can be anything acceptable to GCP (lowercase letters, numerals, and hyphens).
Step 1b. Select as the “source disk” the VM instance on which we just installed the Linux agent.
Step 1c. Leave “Location” as “Multi-Region.”
Step 2. Now we (finally) create an installable template. Go to “Instance template” and click “Create Instance Template.”
Step 2a. Give it a name you can live with: This name will be imported into Control as the template name and will be listed with your other templates.
Step 2b. Choose the same machine configuration as you used for the original VM instance.
Step 2c. Under Boot disk, choose the “custom image” that matches the name of our original Linux VM (not the instance we created a minute ago).
Step 2d. Select/keep the same network configuration as we chose in the beginning.
Step 2e. Create the Instance Template.
Register the GCP Template with Control
Step 3. Go to “Control > Setup > Cloud > gcp_cloud_name” and click “Register Template.” Type the template VM name (“tdevjubuntudemo” in the screen shots above) into Search box and click “Search.”
Step 4. Select your Template VM and Click “Save.”
Step 5. The template is now published in Workspot Control.
3.3. Ubuntu Registration
Follow the registration steps in Creating an Ubuntu Linux Template on Amazon AWS.
4.0 Testing
Step 1. Using your new template, create a desktop pool with at least one desktop, assign yourself to the pool, and launch your new Linux desktop via any Workspot Client.
Step 2. You should see your Linux GNOME desktop, which uses X Windows as its graphical interface and xRDP for network transport. By using RDP, your Linux desktop interacts with Workspot gateways and Clients like a Workspot Windows desktop.
File Locations
Agent files are in /var/opt/workspotagent.
Scripts are in /var/opt/workspotagent/config/workspotscripts.
Log files are in /var/log/workspotagent.
Scripts have their own log directory: /var/log/workspotagent/scriptlogs.
Access the files by signing in as root:
$ Su
$ enter root user password :
$ cd /var/log/workspotagent
$ ls -al
Setup Scripts
Workspot Agent uses XML files and Bash scripts to control initialization and operation. See the Workspot Agent Scripts section of Workspot Desktop Agent Installation and Configuration for more information.
Setup Complete Script
The Workspot Agent runs the wssetupcomplete.bsh script immediately after the VM is cloned and registered with Workspot Control, but before the domain is joined. It is not run on subsequent restarts.
This script will be run whether or not domain joining is enabled. It is used to install or configure software on the VM’s first boot. It is especially useful if the domain will not be joined, or is joined by other means than that provided by Workspot, since the other script, wsrunonce.bsh, is only run on domain-joined VMs.
The script does not exist by default.
For information about Agent’s scripts and the associated XML files, see the WsSetupComplete.cmd Script section of Workspot Desktop Agent Installation and Configuration.
Usage:
Create the file here: /var/opt/workspotagent/config/wssetupcomplete.bsh.
Wssetupcomplete.bsh must be a Linux-formatted text file (that is, newlines are LF, where in Windows they are CR/LF and on Mac they are CR).
It must start with #!/bin/bash and contain valid shell commands.
For example, the following script restarts the Apache service after waiting two seconds:
#! /bin/bash
echo "wsSetupComplete script is triggered"
sleep 2
sudo systemctl restart apache2
Copy wssetupcomplete.bsh to /var/opt/workspotagent/config/workspotscripts
Make it executable with
sudo chmod +x /var/opt/workspotagent/config/wssetupcomplete.bshMake sure that any packages you refer to in your script are available when the VM is created (that is, when the script is run) or are downloaded by the script.
Run Once Script
The wsrunonce.bsh script is run after domain join but before wssetupcomplete.bsh. As its name implies, it runs just once, when the Agent is run for the first time, and never again. If domain-joining is not enabled, the script is not run.
For information about Agent’s scripts and the associated XML files, see the WsRunOnce.cmd Script section of Workspot Desktop Agent Installation and Configuration.
Usage:
Create the file here: /var/opt/workspotagent/config/wsrunonce.bsh.
It must be a Linux text file with #!/bin/bash as its first line, followed by commands.
Sample code: This code will echo text to the log, wait for two seconds, then restart the ssh service.
#! /bin/bash
echo "wsRunonce script is triggered"
sleep 2
sudo systemctl restart ssh
Copy wsrunonce.bsh to /var/opt/workspotagent/config.
Give execute permission to the wsrunonce.bsh script:
$ sudo chmod +x /var/opt/workspotagent/config/wsrunonce.bsh
Miscellaneous Tasks
Re-Register the Agent with a Pool Token
This operation requires a Pool Token from Workspot Control. See Reregistering VMs and Templates Using an Agent Token.
When logged into the desktop VM as a domain administrator or as root, go to /var/opt/workspotagent/config/workspotscripts and run the wsactl commands:
sudo bash wsactl -–unregister sudo bash wsactl -–re-register tokenid
Reconfigure the Agent with New Domain Details, etc.
To reconfigure domain join details (like domain name, OU, domain username, password), run the following command:
sudo bash workspot_installer.sh –reconfigure
Uninstall the Agent
This uninstalls the Agent and all its configuration.
Debian and Ubuntu
sudo apt purge workspotagent
CentOS and RHEL
sudo rpm erase workspotagent
Install the Agent in Silent Mode
To install in silent mode, run:
sudo bash workspot_installer.sh --silent
Upgrade Agent Manually
If Workspot provides a link to an update file in .tar.gz format, install it as follows:
On a Linux VM on which you will install the update, go to /var/opt/workspotagent/config/workspotscripts/
Download the update with:
curl -O URL
where “URL” is provided by Workspot and starts with https:// and ends with a filename with a .tar.gz extension.
Install the update with:
./autoupgrade filename.tar.gz ./upgrade.log
Verify the upgraded agent version as described in “Check the Agent Version” below.
Start, Stop, etc. The Agent Service
sudo systemctl status workspotagent.service
sudo systemctl restart workspotagent.service
sudo systemctl start workspotagent.service
sudo systemctl stop workspotagent.service
sudo systemctl disable workspotagent.service
sudo systemctl enable workspotagent.service
Check the Agent Version
Debian and Ubuntu
sudo apt-cache policy workspotagent
CentOS /RHEL
sudo yum info workspotagent
Check Workspot xRDP Version
Debian and Ubuntu
sudo apt policy xrdp-workspot
CentOS /RHEL
sudo yum info xrdp-workspot
Troubleshooting
Can’t Log in via RDP/Remote Desktop on GPU-equipped VMs
Use ssh as described in Using a Jump Server to log into the template VM.
Run this command:
sudo bash /var/opt/workspotagent/config/workspotscripts/setup_gpu.bshTry to connect to the Linux VM via Remote Desktops.