Using the Workspot Linux Agent
Last updated April 3, 2024 by Robert Plamondon
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 Desktops for more general information about Linux desktop support.
Installation and configuration are divided into four major steps:
- Creating VMs on Azure or GCP.
- Configuring the template VM.
- Registering the VM with Control.
- Special operations at desktop creation time (setup complete script).
Contents
1.0 Creating Linux VMs on Azure and GCP
We will cover Linux VM creation first for Azure, then for GCP. These VMs will be used to create templates visible in Workspot Control.
In general, choose the same VM parameters (RAM, vCPUs, etc.) as you expect to use for the desktops built from the template.
Please follow the steps in the below article before moving on to the next steps.
2.0 Configuring 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.
Please follow the steps in the below article before moving on to the next steps.
3.0 Registering the Template with 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
We have to do extra steps compared to Azure before our GCP VM can be registered with Control.
3.3 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.
3.3.1 Register the GCP Template with Control
Almost there!
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.4 Next Steps
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.
4.0 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
5.0 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.
5.1 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.bsh - Make 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.
5.2 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
6.0 Misc. Tasks
6.1 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
6.2 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
6.3 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
6.4 Install the Agent in Silent Mode
To install in silent mode, run:
sudo bash workspot_installer.sh --silent
6.5 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.
6.6 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
6.7 Check the Agent Version
Debian and Ubuntu
sudo apt-cache policy workspotagent
CentOS /RHEL
sudo yum info workspotagent
6.8 Check Workspot xRDP Version
Debian and Ubuntu
sudo apt policy xrdp-workspot
CentOS /RHEL
sudo yum info xrdp-workspot
7.0 Troubleshooting
7.1 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.bsh- Try to connect to the Linux VM via Remote Desktops.