1. No category

Dell™ Desktop Workspace 4.2
Advanced Setup Guide
Copyright © 2014 Moka5, Inc. All rights reserved.
Moka5™, MokaFive™, LivePC™, and the Moka5 logo are trademarks of Moka5, Inc. All other product or company
names may be trademarks of their respective owners.
This documentation (and the software described herein) was provided based on your prior agreement to a
license agreement governing its use. A copy of the licensee agreement can be found on the web at
http://www.moka5.com/legal/ (for individuals) or in the signed written agreement between you, or your
company, and moka5, Inc. (and/or its resellers and distributors).
Open Source Components
Moka5/Desktop Workspace includes software components developed by open source organizations. A listing of,
and links to the sources for, these components can be found at http://opensource.mokafive.com/v2.
Company Information
Moka5 Headquarters
475 Broadway Street, 2nd Floor
Redwood City, CA 94063
http://www.moka5.com
Desktop Workspace 4.2
Advanced Setup Guide
2
Contents
Welcome to the Advanced Setup Guide!
9
Maintaining Your LivePC
10
Installing Applications and Patches
10
Introduction
10
Publishing a LivePC Update
10
Releasing a new Version or Reverting to a Previous Version
11
Releasing to all Users
11
Releasing to a Targeted Group of Users
11
Controlling Disk Space
11
Introduction
12
Adjusting App And User Disk Sizes
13
Resizing Disks
13
Adjusting System Disk Size
14
Controlling RAM
15
Introduction
15
Default Memory Settings
16
Memory Reserved for Host (Player policy)
16
Memory Reserved for Fearless Browser (Fixed, not Configurable)
17
Memory Reserved for LivePC (Fixed, not Configurable)
17
Percentage of Available Host Memory Assigned to LivePC (LivePC Policy)
17
Maximum RAM Limits Based on Guest and Host OS Instruction Set
17
Letting Users Adjust LivePC Memory
18
Hosts With Low RAM Capacity
18
Controlling CPU
19
How to Set Administrator Default Values Via LivePC Policy
19
How to Assign Exactly 1 vCPU to a LivePC
20
How to Assign One Fewer vCPUs as Host Cores
20
User Control
20
Working With User-Installed Applications
22
Introduction to User-installed Applications
22
Prerequisites
22
Step 1: Setting the Policy
22
Step 2: Installing a User Application
23
Step 3: Rejuvenating an Image
23
Installing a Standalone Image Store
25
Installing a Standalone Image Store
25
What if I Recieved a Warning?
30
Desktop Workspace 4.2
Advanced Setup Guide
3
What if my Registration Failed?
30
Manually Registering a Primary Image Store
30
Adding a Replica Image Store
32
Migrating a Derby Database to an SQL Server Database
34
Setting up a New SQL Server Database
34
Migrating to an SQL Server Database
35
Adding a Forward Proxy
37
Adding a Proxy Server
38
Changing Existing Proxies
38
Adding a Custom List of HTTP Headers
39
Adding a Reverse Proxy Server
40
Deploying a Reverse Proxy Server with Apache
41
Building an SSL Terminating Reverse Proxy Server Using Apache Web Server
41
Prerequisites
41
Overall Steps
42
Install Apache
42
Verify Connectivity and Firewall Settings (port 80)
42
Configure Apache
43
Enable Port 443
43
Enable Reverse Proxy in Apache (port 443)
43
​Copy and Convert the Desktop Workspace HTTPS Keys and Certificates
43
Configure Reverse Proxy (port 443)
44
Restart Apache
45
Test Reverse Proxy (Port 443)
45
Last Steps
46
Trusted Certificates
46
Installing an Active Directory Extender
47
Installation Guidance
47
Enabling Active Directory Extender
47
Installing Active Directory Extender
48
Using Active Directory Extender in the Management Server
51
Field Descriptions
51
Adding a Desktop Application Gateway
52
Using the Desktop Workspace 4.1.3 Desktop Application Gateway
52
Hardware Requirements
52
Adding a Gateway
53
Installing the Desktop Application Gateway
54
Test Your Desktop Application Gateway Configuration
55
Desktop Workspace 4.2
Advanced Setup Guide
4
Configuring SSL
56
SSL Background
56
Self-Signed or CA-Signed Certificates?
57
A Note on Load Balancers and Layer 7 Firewalls
57
Finishing SSL Setup in a Multi-server Self-signed Configuration
58
Adding a Certificate to the Management Server’s Trusted CA Certificates
58
Using Self-signed Certificates
58
Generating a new Self-signed Certificate
58
Copying Self-signed Certificate to Management Server’s Trusted CA Certificates
59
Enabling the new SSL Certificate
59
(Optional) Deleting old Certificates
59
Using CA-Signed Certificates
60
Generating a Certificate Signing Request (CSR)
60
Verifying the Certificate
60
Replacing a Certificate
61
Importing Private Key and SSL Certificates
61
Adding Intermediate Certificates
61
Adding an Enterprise Root CA
62
Replacing Expiring Certificates
62
CA-signed Certificates
62
Self-signed Certificates
62
Blocking and Filtering IPs Attempting to Access the Management Console
63
What is an IP Filter?
63
Using IP Filters in Desktop Workspace
63
Creating a New IP Filter
64
Modifying an IP Filter
64
Deleting an IP Filter
65
Configuring an HTTP Proxy for Outbound Traffic
66
Scaling the Management Server
68
Enabling Multi-Tenancy (Service Provider Edition)
69
Prerequisites
69
Wildcard Certificate
69
DNS Entry
69
Creating a New Tenant
70
Uninstalling Desktop Workspace
71
Uninstalling Desktop Workspace Enterprise Server Components
71
Uninstalling Desktop Workspace Clients: Windows PC
71
Uninstalling Desktop Workspace Clients: Mac
72
Alternate Method to Uninstall Mac Player
72
Desktop Workspace 4.2
Advanced Setup Guide
5
Run Host Scripts on Mac or Windows Host Computers
73
Display a Custom EULA When Starting Desktop Workspace Player
74
Creating Domain Join Packets Using an API
75
Using REST APIs in Desktop Workspace
76
API Formatting
76
Authentication and Authorization
76
Exporting User Information
78
Managing Active Resource Packets
78
Uploading an AD packet
78
Uploading a Reserved AD packet
80
Listing AD packets
80
Deleting an AD packet
81
Authentication
82
Rejecting a Login Attempt Based on Incorrect Credentials
82
Rejecting a Login Attempt Based on Insufficient User Permissions
82
Managing Devices
83
Looking Up Device Properties
83
Method 1
83
Method 2
83
Inventory
84
Looking Up LivePCs
84
Method 1 (Looking up a specific LivePC)
84
Method 2 (Looking up all existing LivePCs)
85
Looking Up Users in a Domain
86
Looking Up Subscriptions
87
Looking Up Devices
88
Looking Up Devices with Properties
89
Looking Up Client Packs
89
Managing Tenants
90
Create a Tenant
90
Update a Tenant
91
Retrieve Information About a Tenant
91
List All Existing Tenants
92
Delete a Tenant
93
Disable and Re-enable a Tenant
93
For more REST APIs, refer to Desktop Workspace REST APIs, Part 2.
94
Desktop Workspace REST APIs, Part 2
95
Integrating Desktop Workspace with a Self-Service Portal
95
Logging In as a User
95
Looking Up User Info
96
Desktop Workspace 4.2
Advanced Setup Guide
6
Downloading the Windows Player
96
Downloading the Mac Player
96
Downloading the BareMetal ISO
97
Managing Desktop Workspace with a Service Desk
97
Looking up Subscriptions
97
Revoking/Unrevoking an Active Subscription
98
Revoking an Active Subscription
99
First, Check the Subscription Status
99
Then, Unrevoke the Active Subscription
99
Then, Confirm the Subscription Status
99
Killing an Active Subscription
100
Then, Check the Subscription Status
100
Revoking/Unrevoking a Device
100
First, Check the Device Status
101
Then, Revoke the Device
101
Then, Confirm the Device Status
101
Or, Unrevoke the Device
101
Then, Check the Device Status
102
Killing an Active Device
102
Killing the Device
102
Then, Check the Device Status
102
Checking Server Status
103
Looking Up Version Information
103
Troubleshooting Common Errors
103
Looking Up Subscriptions for a User that Does Not Exist
103
Looking Up Devices for a User that Does Not Exist
104
Revoking or Unrevoking A Subscription that Does Not Exist
104
Revoking a Subscription that Does Not Exist
104
Unrevoking a Subscription that Does Not Exist
104
Revoking or Unrevoking a Subscription that has Been Killed
105
Revoking a Killed Subscription
105
Unrevoking a Killed Subscription
105
Killing a Device Subscription that Does Not Exist
105
Revoking or Unrevoking a Device that Does Not Exist
105
Revoking a Device that Does Not Exist
106
Unrevoking a Device that Does Not Exist
106
Revoking or Unrevoking a Device That Has Been Killed
106
Revoking a Killed Device
106
Unrevoking a Killed Device
106
Killing a Device That Does Not Exist
106
Identifying the MAC Addresses of Host Computers From the Management Server
Desktop Workspace 4.2
Advanced Setup Guide
108
7
About Dell Software
109
Contacting Dell Software
109
Technical Support Resources
109
Desktop Workspace 4.2
Advanced Setup Guide
8
Welcome to the Advanced Setup Guide!
This Advanced Setup Guide will first cover some advanced administration topics that apply to
Desktop Workspace.
l
Maintaining Your LivePCs
l
Working With User-Installed Applications
Then, this guide will show you how to expand a standard installation to one which can manage thousands of
users in remote offices, on the corporate network or on the Internet.
l
Desktop Application Gateway - Authenticate and manage endpoints over the Internet
l
Replica Image Store - Cache images for remote offices
l
SQL Server database - Improve performance, scalability, and manageability
l
CA certificates for SSL - Improve infrastructure security
l
Clustered Management Servers - Improve scalability
l
Multi-tenant infrastructure (Service Provider Edition) - Provide delegated accounts on a leveraged
infrastructure
Desktop Workspace 4.2
Advanced Setup Guide
9
Maintaining Your LivePC
Installing Applications and Patches
- Introduction
- Publishing a LivePC Update
- Releasing a new Version or Reverting to a Previous Version
Introduction
Images within Desktop Workspace can be modified and updated. Use Desktop Workspace Creator to create and
update LivePC images. Updates are then downloaded by users in the background and applied upon restart of
the image.
Updates are typically unnoticed by users. User data and domain ID (domain join) are always kept, and custom
installed applications can also be kept if the related policy is enabled.
There are two types of updates: Deep Copy and Shallow Copy. Deep Copy updates contain an entire copy of the
image. These updates are recommended after you remove files from your image. Shallow Copy updates
contain only image differences, not the full image. Shallow Copy updates are recommended if you add
incremental patches or applications to your image.
When making changes to a LivePC's data block, the Desktop Workspace Player/Creator creates a temporary
copy of the block before changing it. This improves reliability of data written to disk, but it also temporarily
increases the size of the local LivePC files, sometimes as much as doubling in size. When Player/Creator is idle,
it will compact the local LivePC files by removing the temporary copies, so eventually the LivePC files will
shrink. Also, when packaging a new LivePC version for upload to the server, Creator will first remove the
temporary blocks, so the uploaded version will not include the unnecessary blocks.
NOTE: We strongly recommend that you add applications incrementally. That is, do them one at a time
and test each one on the platforms you plan to support (i.e., MAC and/or PC) before moving on to the
next installation. We also advise you to test the image on multiple platforms if you are running special
GPO scripts. Be aware that some GPOs can delay the image boot time as the objects are being
downloaded. This is typically a one-time event for new images.
Publishing a LivePC Update
1. Launch Desktop Workspace Creator.
2. Click the Play button to start the LivePC image you want to update.
3. Make changes to your image, such as installing software or patches. The process is the same as we have
done in other sections.
Desktop Workspace 4.2
Advanced Setup Guide
10
4. Optionally, at this point, you can optimize the image using the Desktop Workspace tools (e.g., by
deleting temporary files, etc.) to keep the update as small as possible. 5. Shut down the LivePC image.
6. You can run Creator in ‘Test Mode’ if you want to test the new image before rolling it out to end users.
You can do this by choosing this option from the drop down menu in Creator.
7. Click the image drop down menu and select Package and upload.
8. Select Shallow Copy. The update is packaged and uploaded to the Management Server. The
Management Server will automatically assign the update a version number. Creator will automatically
subscribe to this latest version of the LivePC image.
Releasing a new Version or Reverting to a
Previous Version
Releasing to all Users
1. Go to the LivePC Images tab.
2. In the left navigation pane, click the image whose new version you’d like to release. The list of versions
appears. The currently released version is identified as current in the main panel with a green
checkmark icon.
3. In the main panel, identify the version you want to release. This can be either a new version, or a
previous version (if you’d like to revert to an older version).
4. Click the Make Current action.
5. Click Create.
All subscribed users will automatically be upgraded (or reverted) to the chosen release the next time their
Players check in with the Management Server.
Releasing to a Targeted Group of Users
1. Go to the LivePC Images tab.
2. In the left navigation pane, click the new image you want to release. 3. Click the Targeted Groups tab.
4. Identify the target and click Modify Targeting.
5. Select the correct version and click Finish.
All users in that target group will be upgraded (or reverted) to the chosen release the next time their Players
check in with the Management Server.
Controlling Disk Space
Desktop Workspace provides administrators and users flexibility in controlling disk space used in a LivePC.
Desktop Workspace 4.2
Advanced Setup Guide
11
- Introduction
- Adjusting App And User Disk Sizes
- Adjusting System Disk Size
Introduction
The layering technology in Desktop Workspace separates data into layers that can be managed independently.
A typical LivePC has 3 layers: system, app, and user. The layering technology dynamically composes the
separate layers into a single unified view. From the user’s point of view, most of their data is stored on a
familiar C: drive. But under the hood, each layer is stored on its own disk.
The individual disks that store each layer can fill up with data at different rates. The composed C: drive shows
the minimum free space across the app and user disks. This gives a view of the free space on the LivePC as a
whole. The free space displayed does not include the system disk, because most user operations write data to
the app or user disks.
The reported capacity of the C: drive is equal to the size of the largest of the three disks.
For example, if a user’s LivePC has the following disk situation, the C: drive in the LivePC would show 5 GB of
free space, with 40 GB of capacity.
Desktop Workspace 4.2
Advanced Setup Guide
12
Adjusting App And User Disk Sizes
Through Desktop Workspace layers, user data and settings are stored in the user disk, and user-installed
applications are stored in the app disk. If these disks fill up, the user will be unable to store more files or
install applications. In these cases, it’s helpful to be able to adjust disk size.
Administrators can increase the default size of the user and app disks by changing the size on Creator.
However, this will affect only new LivePC subscriptions, and won’t increase the disk of existing subscriptions.
For existing LivePC subscriptions, users can resize their LivePC user and app disks themselves through the
Player interface.
NOTE: Users can only adjust LivePC disk size when the LivePC is shut down, and if the LivePC policy
Allow user to resize LivePC disks is enabled.
Resizing Disks
1. Open Desktop Workspace Player, and find the LivePC you want to modify.
2. Click the Down triangle next to the LivePC name to open the LivePC menu.
3. In the LivePC menu, click Resize Disks. A dialog box appears.
4. Use the sliders to change the disk sizes as needed.
l
l
The first slider allows you to add disk space to the user and app disks jointly.
The second slider allows you to allocate more or less of the joint space to the user or app disks,
respectively.
Desktop Workspace 4.2
Advanced Setup Guide
13
Adjusting System Disk Size
This can only be done by the administrator as an image update in Creator.
1. Open Creator and find the LivePC you wish to modify.
2. Click the Down triangle next to the LivePC name. The LivePC Menu will open.
3. Click Configure.
4. Click the Storage tab.
Desktop Workspace 4.2
Advanced Setup Guide
14
5. Click Edit for the System disk and adjust the size as needed.
6. Publish this update to the image as a new version, to resizer the system disk for all users.
Controlling RAM
Desktop Workspace provides administrators and users flexibility in controlling memory used in a LivePC.
- Introduction
- Default Memory Settings
- Hosts With Low RAM Capacity
Introduction
You can control default LivePC RAM allocation through LivePC policies. Users can then allocate more or less
RAM, based on their preferences. LivePC RAM is adjustable, but only takes effect on restart of the LivePC. Desktop Workspace 4.2
Advanced Setup Guide
15
It is important to remember that hosts require RAM to operate. The Desktop Workspace factory defaults are
set to prevent overallocation of RAM. You can adjust these defaults through policies, but you should test
extensively before rolling out to your users. Overallocation issues such as slow performance and crashes are
sometimes intermittent and may be difficult to diagnose.
Default RAM for each LivePC is set through policies, and is based on the RAM capacity of the host. The
calculation is:
l
l
Default LivePC RAM = minimum reserved for LivePC + (Remaining host RAM x % set by policy)
Remaining host RAM = Capacity of Host – minimum reserved for Host – reserved for Fearless Browser –
(BareMetal only, if enabled) - minimum reserved for LivePC
Essentially, Player will first reserve RAM for the host and LivePC, and Fearless Browser if it’s been enabled on
a BareMetal host. Then the remaining RAM is split by a percentage set through policy. This allows you to
provide more RAM for LivePCs on large capacity hosts.
Default Memory Settings
Here are the default settings and the corresponding policies for the values that you can change.
Memory Reserved for Host (Player policy)
Host type
Default Value
Allowed Range
BareMetal
1.0 GB
Min: 512 MB
Mac
1.5 GB
Min: 1.0 GB
Windows 7
1.5 GB
Min: 1.0 GB
Windows XP
1.0 GB
Min: 512 MB
Desktop Workspace 4.2
Advanced Setup Guide
16
Memory Reserved for Fearless Browser (Fixed, not
Configurable)
Host type
Default Value
Allowed Range
BareMetal
300 MB
N/A
Memory Reserved for LivePC (Fixed, not Configurable)
LivePC type
Default Value
Allowed Range
Windows 7
1.0 GB
N/A
Windows XP
512 MB
N/A
Percentage of Available Host Memory Assigned to LivePC
(LivePC Policy)
Host type
Default Value
Allowed Range
BareMetal
80%
0% - 100%
Mac
50%
0% - 100%
Windows 7
50%
0% - 100%
Windows XP
50%
0% - 100%
NOTE: We suggest that once you’ve selected a host RAM reserved amount that works for your
organization, you do not change it. Reducing the amount can cause performance issues or instability.
Increasing the amount may cause LivePCs that had been suspended with a large amount of RAM to not
be able to start under a new, smaller host RAM reserve policy.
Maximum RAM Limits Based on Guest and Host OS
Instruction Set
Maximum LivePC RAM is bound by the host capacity as well the guest and host OS instruction set.
RAM Limit
Notes
Host OS
LivePC OS
Instruction
Set
Instruction
Set
32-bit
32 or 64-bit
1.25 GB
On a 32 bit host OS, each process is only allocated 2 GB of
RAM. Virtualization requires 0.75 GB.
64-bit
32-bit
3 GB
32-bit LivePC OS limits addressable RAM to 4 GB.
Virtualization requires 1 GB.
64-bit
64-bit
No limit besides host
RAM capacity
Host OS will require some RAM; about 1 to 1.5 GB
depending on the OS.
Desktop Workspace 4.2
Advanced Setup Guide
17
Letting Users Adjust LivePC Memory
By default, users can adjust their LivePC memory allocation through Player.
1. Turn off the LivePC.
2. Open the LivePC menu and select Adjust Memory.
The default value is determined through the policy settings and calculation described previously. The
minimum is determined by the LivePC OS type (see table) and the maximum is the host’s RAM capacity less the
minimum requirements for host, Fearless Browser (for BareMetal, if enabled), and LivePC.
You can also disallow users from adjusting memory by disabling the LivePC policy Allow the user to adjust
memory assignment.
Hosts With Low RAM Capacity
When users run Player on hosts with low RAM capacity, the RAM policies will disallow them from starting
LivePCs if sufficient RAM is unavailable. For example, for Windows 7 hosts, we set aside 1.5 GB of RAM for the host. Then, we only allow users to start
LivePCs if the host has RAM that meets a LivePC minimum. For Windows 7 LivePCs, that minimum is 1 GB. This
means that if someone has a 2 GB Windows 7 host, they will not be able to start a Windows 7 LivePC. When
starting, they will see a message much like the following.
Desktop Workspace 4.2
Advanced Setup Guide
18
If a user adjusts RAM settings for a LivePC, their setting will override any RAM setting set on the management
console. This means that once the user has used the Adjust Memory setting for a LivePC, changes to the RAM
setting on the management console will have no effect on that LivePC instance.
Controlling CPU
- How to Set Administrator Default Values Via LivePC Policy
- How to Assign Exactly 1 vCPU to a LivePC
- How to Assign One Fewer vCPUs as Host Cores
- User Control
How to Set Administrator Default Values Via
LivePC Policy
Virtual CPUs (vCPUs) are instantiated in the LivePC according to a percentage-based policy based on the
number of physical CPUs of the host. These policies establish the Administrator Default values and are applied
automatically to LivePCs.
LivePC Policy Name
Default
value
Allowed
range
Percentage of CPU cores assigned to a LivePC (BareMetal
host)
50%
0% - 100%
Percentage of CPU cores assigned to a LivePC (Mac host)
50%
0% - 100%
Percentage of CPU cores assigned to a LivePC (Windows
host)
50%
0% - 100%
In general, it’s best to set the number of vCPUs to fewer than the number of physical cores (i.e., a percentage
less than 100%). This reserves processing capacity for the host, which is recommended for best LivePC
performance.
The calculation used for instantiating vCPUs is:
Number vCPUs = Number of cores on the host x % set by policy
Or 1 vCPU, whichever is higher.
Note that the result will round down to the nearest whole number, but Desktop Workspace will always assign
at least 1 vCPU to the LivePC.
Desktop Workspace 4.2
Advanced Setup Guide
19
How to Assign Exactly 1 vCPU to a LivePC
Setting the CPU policy to 0% will assign exactly 1 CPU to the LivePC. In some cases, certain real-time
applications (such as VOIP) run with better performance when there is only a single vCPU in a LivePC.
How to Assign One Fewer vCPUs as Host Cores
Set the CPU policy to 99% - that will always result in one fewer vCPUs than number of cores on the host.
Note that Desktop Workspace will also count hyperthreaded cores when discovering the number of host cores. In general, hyperthreaded cores are desirable when working with Desktop Workspace LivePCs.
User Control
The administrator can allow end users to control the number of CPU cores to be used in the LivePC by enabling
this policy:
LivePC Policy Name (under User Control section)
Allow user to adjust memory and CPU used by a LivePC
If the policy is enabled, the end user will see the Adjust CPU option under the LivePC pull-down menu in
Desktop Workspace Player:
Selecting Adjust CPU will open the next dialog box:
Desktop Workspace 4.2
Advanced Setup Guide
20
This allows you to select the number of cores:
Desktop Workspace 4.2
Advanced Setup Guide
21
Working With User-Installed
Applications
Introduction to User-installed Applications
If allowed by policy, Desktop Workspace allows users to install personal applications onto their own images.
The ability to retain user installed applications is supported only on Windows images (regardless if they run on
a Mac or PC).
It is important to understand that user installed applications and user data are installed in their own layer
within the Desktop Workspace LivePC. Therefore, user installed applications and user data are not affected by
image updates and restarts. However, unlike user data, user installed applications are removed when a user
rejuvenates their image.
Rejuvenation allows users to return their image back to its original state. This action can be useful if a user
installed application (i.e., a virus) causes problems. Rejuvenation will remove all user installed applications
and restore the system files. Rejuvenation will not affect user data. If you require one or more user installed
applications to be persistent through rejuvenation, you must define these applications in the LivePC
personalization policy. Information on how to do this can be found later in this section.
Prerequisites
l
l
You must have a LivePC image with Desktop Workspace Guest Tools installed. For information on creating a LivePC from scratch, refer to Creating an Optimized Windows 7 LivePC
Image in the LIVEPC ADMN GUIDE.
Step 1: Setting the Policy
1. Log into the Desktop Workspace Management Console as a user who has the "Desktop
Administrator" role.
2. Open the Policies tab and select LivePC Policies > Custom.
3. Select the Targeted Group that you want to enable application persistence for. (You can also change
this from the Default tab if you like.)
4. Locate the Retain custom application installations policy, and make sure its value is set to Enable. If
you make a change, click Save afterward.
5. Start Player (or restart Player if it had already been running). This triggers a policy update check.
However, you can also wait for Player to check in automatically. This check-in time is based on Player
Policy setting in the Management Server.
6. Start the LivePC image and log into it as a user.
Desktop Workspace 4.2
Advanced Setup Guide
22
Step 2: Installing a User Application
The end user can now install applications inside their LivePC, assuming they have local administrator
permissions within Windows.
Example: Installing the Opera browser
The following example is intended to show an end user installing an application and demonstrate that the
application persists across shutdown or restart of the LivePC.
1. Download or copy an application (for example, the Opera browser, which you can find at
www.opera.com) onto your image, and install the application. (The Opera browser makes for a great
example as you get the entire executable, which is small and light weight.)
2. Run the installer.
3. Change the install options, or select Accept and Install to install with the defaults.
4. If you see the User Account Control dialog box, click Yes.
5. Opera will install and open up the browser interface. 6. Shut down the LivePC image, and restart it. This automatically restores the LivePC image’s system
layer, but does not touch the user installed apps layer or data layer.
7. Double-click the Opera Icon on your desktop to launch the browser and verify that it is installed. You
can also go to Start > Control Panel > Programs > Programs and Features. Confirm that the
application is still installed. The application remains installed even if the image’s system layer is
restored or updated.
Step 3: Rejuvenating an Image
NOTE: The Rejuvenate feature is available only when using a Layered LivePC image (and not available
with a Non-layered LivePC image).
As discussed earlier, rejuvenation allows users to return their image back to its original state. Rejuvenation
will remove all custom application installations (i.e., Opera) and restore the system files. This is also very
useful when a virus is injected by the user within the LivePC. Rejuvenation will not affect user data and
preferences. In order to verify the user data stays intact, change your desktop background or create a text file
and put it on your desktop. 1. Shut down the image.
2. On Player, click the Down triangle to expose the LivePC Settings menu.
3. Click Rejuvenate Now. This action removes custom application installations and restores the
system files.
4. Click Yes.
5. The rejuvenation process completes, which means the user application layer has been wiped
clean. Click OK.
6. Start the LivePC.
Desktop Workspace 4.2
Advanced Setup Guide
23
7. When the LivePC starts, validate that the user installed application is no longer installed and that
user data was unaffected. You may need to go to Add/Remove Programs to validate the
application removal. TIP: In some cases, desktop shortcuts and other application files may remain on the desktop even
though the application has been removed. This is because desktop shortcuts are installed as user data,
which is not wiped during the rejuvenation. Opera is a good example of the icon not being removed. If
you installed Opera, you will see the icon on your desktop, but the application will no longer be
installed. Just delete the icon or double-click it and then click Delete.
Desktop Workspace 4.2
Advanced Setup Guide
24
Installing a Standalone Image Store
- Installing a Standalone Image Store
- What if I Recieved a Warning?
- What if my Registration Failed?
- Manually Registering a Primary Image Store
Most organizations will want to install a standalone Image Store, rather than installing the Image Store and the
Management Server on the same server. You can use standalone Image Stores as replicas, or behind a load
balancer, as mirrored primary Image Stores.
NOTE: Before you install a standalone Image Store, you must download and install a Desktop Workspace
Management Server. To complete the server installation process, refer to Step 1: Install Desktop
Workspace Management Server in the QUICK START GUIDE.
To install and configure a Management Server and standalone Image Store: 1. Download and install a Management Server.
2. Install a standalone Image Store by running the server installer again and following the procedure
outlined in this document.
3. Log in to the Management Console. The server configuration wizard will run, and you will be prompted
to connect the newly installed Image Store to the Management Server by entering the Image Store's
URL and credentials.
Installing a Standalone Image Store
1. In the extracted Desktop Workspace Installation Package folder, start the Desktop Workspace Server
Installer by double clicking the Desktop Workspace Management Server installer file (MokaFive4.1.#.#-MgmtServer-Installer.exe).
2. User Account Control: Click Run.
3. Review the End-User License Agreement: Read them and click the checkbox next to I accept the
license terms and conditions, and then click Next.
Desktop Workspace 4.2
Advanced Setup Guide
25
4. Installation Components: Deselect the components you do not want to install, and check the Image
Store box. Click Next.
5. Installation Location: Click Next to accept the default installation location. Alternatively, click
Browse to specify a location.
Desktop Workspace 4.2
Advanced Setup Guide
26
6. Hostname & Port: If your installation host machine is joined to a domain, these fields will autofill with
the correct information. Click Next.
NOTE: If you check Automatically open port on Windows Firewall, a new inbound firewall rule named
MokaFive Secure Port will be created.
7. Administrator Credential: These fields autofill with the Bootstrap Admin account username. This
superuser account exists within the Desktop Workspace Management Server and Primary Image Store.
You can use the same credentials for the Management Server and Primary Image Store, or you can
create two accounts. We strongly recommend that you change the default username to something
more secure. Click Next. Desktop Workspace 4.2
Advanced Setup Guide
27
8. Component Registration: By default, the Image Store will register with the Management Server upon
installation and appear for targeting in the Management Console. If you do not register the Image Store
during installation, you must register it manually by following the steps in Best Practices for Setting Up
a Replica Image Store. NOTE: If you are installing a mirrored Image Store, do not check the Register components with the
Desktop Workspace Management Console box. Only the Primary Image Store, behind a load balancer,
should be registered with the Management Console. This insures that traffic is directed to the load
balancer, rather than being directed exclusively to one of the mirrored or replica Image Stores.
Enter your server hostname, port, and bootstrap admin credentials, and click Next.
Desktop Workspace 4.2
Advanced Setup Guide
28
9. Installation Preview: This screen summarizes the customization choices you made while running the
installer. Review your choices. Click Back to make changes, or, to accept the summary and begin the
installation, click Next.
NOTE: The Register the Image Store with the Management Server line only appears if you register
the Image Store with the Management Server in step 8.
10. The installation begins.
Congratulations! You have just installed a standalone image store!
Desktop Workspace 4.2
Advanced Setup Guide
29
What if I Recieved a Warning?
Some installations will return warning messages when they succeed. These messages appear when the Image
Store has tried and failed to register with the Management Server, or when attempts to open firewall ports
fail due to insufficient user permissions, or AV or other software (for example, third-party management tools,
such as SCCM) interfere.
If you get a warning message after a successful installation, navigate to the log file referenced in the warning.
These logs will help you identify the problem.
What if my Registration Failed?
You can register your Image Store with the Management Server manually.
Manually Registering a Primary Image
Store
If you did not register the Image Store, or if there was a problem registering the Image Store with the
Management Server, follow the next procedure to manually register the Image Store.
NOTE: If you installed a mirrored Primary Image Store (an Image Store running behind the same load
balancer as your Primary Image Store), do not register it with the Management Server.
The service takes a minute or so during initial start. After that period, do this:
1. Navigate to the Image Store's server configuration,or "iconfig" interface (https://<ris_dns_
name>/iconfig).
2. Log in with your bootstrap admin credentials.
Desktop Workspace 4.2
Advanced Setup Guide
30
3. Go to Settings > Access Keys.
4. Click the pencil icon at the end of the key and choose Delete.
5. Click Add Access Key.
6. In another browser window, log on to your Management Server’s iconfig interface.
7. Go to Settings > Access Keys.
8. Copy the Key ID and Key Secret to the empty Add Access Key fields on the Image Store’s
iconfig interface.
9. Register the Image Store with the Management Server, and log in to the Management Console with
your bootstrap admin credentials.
10. Navigate to Settings > Infrastructure and click into the Images Stores tab.
11. Click Add.
12. Enter the correct server URL for the Image Store and the Key ID and Key Secret.
13. Click Test to send a request from the Management Server to the Image Store.
14. If the test succeeds, click Save to apply the changes.
Desktop Workspace 4.2
Advanced Setup Guide
31
Adding a Replica Image Store
For more information on setting up a Replica Image Store, refer to this Knowledge Base article on the topic.
Replica image stores provide for distributed storage of images and clients so that image and client updates do
not all have to come through the primary image store. As you grow your infrastructure, we recommend adding
replica image stores as follows:
First as a “primary” replica to offload work and traffic from your management server. When you do this, the
replica may reside in the same location as the management server; but, by moving it to another box, you can
separate traffic such that updates made to the golden image in Creator get published to the primary image
store, and updates to the LivePCs running in Player all get pulled from the replica.
NOTE: When adding this first replica, you will need to: l
l
l
Set the Player policy Image Store to Use to instruct your Players to get updates from the
replica, or
In the Management Server, define a range of UIP addresses that the replica will serve
(optional).
As you need to support a growing number of remote users, you can add replica image stores in
those locations to speed up distribution of updates (as the updates can now be delivered over
the LAN instead of the WAN).
Note that when the Management Server determines that a Player or Creator needs to download LivePCs or
updates, the management server passes a URL that includes the fully qualified domain name of the
appropriate Image Store. This FQDN must be resolvable by the Player/Creator at run time, meaning that the
Primary Image Store and all Replica Image Stores must typically be set up with split DNS and Application
Gateway proxy entries to enable Players and Creators to receive updates when not on the corporate network:
Desktop Workspace 4.2
Advanced Setup Guide
32
There is one scenario wherein a Replica Image Store would not require split DNS and an Application Gateway
proxy entry--if you assigned clients to a Replica Image Store by IP address in addition to (or instead of) the
player policy Image store to use. The Player’s IP address is evaluated by the Management Server and
compared to IP address ranges assigned to each Image Store. A Player connecting from the internet would not
match the IP range for the Replica Image Store, and so would use the Primary Image Store, resolving the FQDN
of the Primary Image Store through split DNS and connecting to the Primary Image Store through the
Application Gateway proxy. The same Player would match the IP range if that Player were on the corporate
network, and would then resolve the FQDN of the Replica Image Store via internal DNS:
If deploying multiple Replicas, repeat this section on a different sheet.
Desktop Workspace 4.2
Advanced Setup Guide
33
Migrating a Derby Database to an SQL
Server Database
- Setting up a New SQL Server Database
- Migrating to an SQL Server Database
In pre-4.1 Desktop Workspace installations, you could use Derby databases for pre-production deployments.
Support for Derby databases was deprecated in Desktop Workspace 4.1. If you are using a Derby database, you
msut migrate to a SQL Server database for a production deployment.
IMPORTANT: You must migrate your Derby databases to SQL before you can upgrade to Desktop
Workspace 4.1.3.
You will need the following information to migrate to SQL Server. Save this information to use when you are
going through the SQL Server set up process.
SQL Server Hostname:
SQL Server IP Address:
Port:
Database name (e.g., m5esdb):
Database username:
Database password:
Setting up a New SQL Server Database
Your database administrator will need to create and configure your SQL Server database with the following
requirements prior to migration:
1. Configure Static TCP/IP Port Number for SQL Server Database Engine, e.g. 1433. For more information,
refer to this Microsoft knowledge base article: http://msdn.microsoft.com/enus/library/ms177440.aspx.
2. Fill out the port number in the table above.
2. Configure for Mixed Mode Authentication to support SQL Server Authentication. Desktop Workspace
requires SQL Server Authentication.
3. Create a local SQL Server database user account for use with Desktop Workspace.
4. Fill out the username and password in the table above.
5. Create a new database for use with Desktop Workspace. The default database name is m5esdb, but
yyou can set a name in line with your DBA requirements.
6. Fill out database name in the table above.
Desktop Workspace 4.2
Advanced Setup Guide
34
7. Assign the Desktop Workspace database user to the new database and set permissions for the database
user. Initially, the account should have db_owner or schema modification rights in order to have
permissions to generate tables and other information in the database. After the installation, the
account permissions can be reduced to the following roles:
l
db_datawriter
l
db_datareader
l
db_ddladmin
IMPORTANT: Desktop Workspace currently does not support named SQL Server instances (<Server
Hostname><Named Instance>). Desktop Workspace will only work with the default instance. Check with
your database administrator if you are not sure about the database server configuration.
Migrating to an SQL Server Database
1. Before proceeding with the migration, you should do the following:
a. Schedule server downtime for the database migration to ensure that no changes are lost
during the process. Temporarily block the inbound port on the firewall to the Desktop
Workspace Management server during maintenance. By default, Desktop Workspace uses port
443 for communication.
b. Back up the database. Stop the Desktop Workspace Enterprise Server service. Make a backup
copy of the Derby database folder (C:\Program Files (x86)\Mokafive\Derby), then start the
Desktop Workspace Enterprise Server.
2. Log in to Management Console as the "bootstrap user".
3. Go to M Settings > Maintenance > DB Migration and fill out the Target Database Settings with the
information from the table above.
4. Enter database settings for the target new database.
Desktop Workspace 4.2
Advanced Setup Guide
35
CAUTION: Verify that the target SQL database is the one you created earlier. The migration
process will delete and recreate the tables in the targeted SQL database. Make sure you entered
the correct database.
5. Click Start.
6. Log out and log in with the iconfig (https://<servername>/iconfig).
7. Go to Settings > Database and click Edit Settings.
8. Set up Desktop Workspace with the migrated SQL database and test the connection.
9. Click Update and restart the server.
10. Reset the inbound port firewall setting for the Desktop Workspace Management server to ALLOW. (By
default, Desktop Workspace uses port 443 for communications.)
10. Verify server functionality.
Desktop Workspace 4.2
Advanced Setup Guide
36
Adding a Forward Proxy
- Adding a Proxy Server
- Changing Existing Proxies
- Adding a Custom List of HTTP Headers
If your Management Server is installed within a corporate network, you can use a proxy server to increase
scalability without sacrificing security. A proxy relays an outside request to a server, provided that request
includes specific types of identifying information.
NOTE: We strongly recommend that you use a proxy server in conjunction with IP filters. If you do not
use an IP filter and a proxy, the proxy will direct any request with an acceptable HTTP header to the
Management Server. Adding an IP filter can protect your Management Server from malicious or
insecure requests by allowing you to only allow requests from explicitly approved IPs.
For more information, refer to Blocking and Filtering IPs Attempting to Access the Management
Console.
When you add a proxy server in front of the Management Server and you wish to use the Remote Access filter
provided by the Management Server, you must add the proxy server in the Management Console. The proxy
checks a list of approved HTTP headers against the credentials presented by the originated remote IP address
injected by the proxy server. If you specify a list of approved remote IP addresses, any request that does not
include an HTTP header from the list will be rejected.
Desktop Workspace provides a list of commonly used HTTP headers, and checks for them in the
following order:
l
X-Forwarded-For
l
Z-Forwarded-For
l
NS-Proxy-Client-IP
l
WL-Proxy-Client-IP
l
HTTP_X_FORWARDED_FOR
l
HTTP_X_FORWARDED
l
HTTP_X_CLUSTER_CLIENT_IP
l
HTTP_CLIENT_IP
l
HTTP_FORWARDED_FOR
l
HTTP_FORWARDED
l
HTTP_VIA
l
REMOTE_ADDR
Desktop Workspace 4.2
Advanced Setup Guide
37
Adding a Proxy Server
You can add a proxy server through the Desktop Workspace Management Console.
1. Log in to the Management Console using your bootstrap admin account.
2. Navigate to Settings > Infrastructure, and click on the Remote Access tab.
3. Click Add a New Proxy Server. The “Add Proxy Server” window opens.
4. Enter the proxy’s static IP or hostname (example: proxy.yourcompany.com) and click Add.
NOTE: We recommend using a static IP to identify the proxy server. If the proxy server is configured
with Dynamic Host Configuration Protocol (DHCP), it is possible to use the proxy server’s host name
instead of a static IP address, but this option is not recommended. If you use the hostname, the
Management Server will attempt to resolve the proxy server’s hostname for each request. This extra
step can lead to performance issues in high-demand environments.
5. If the setup is successful, the proxy will be added to the list in the Hostname/IP column.
Changing Existing Proxies
1. In the Infrastructure menu, find the proxy you wish to edit in the Hostname/IP column.
2. Click Edit next to the proxy name. The Modify Proxy Server window opens.
Desktop Workspace 4.2
Advanced Setup Guide
38
3. Modify the IP or hostname and click Save.
You can also delete a proxy by clicking Delete in the Action column next to the proxy name.
Adding a Custom List of HTTP Headers
The default list of HTTP headers provided by Desktop Workspace covers most commonly used headers.
You may want to upload a custom list of headers if you have special circumstances, but for most users the
default Desktop Workspace list will be sufficient.
You can define your own list of headers by modifying the properties file in your Desktop Workspace directory.
1. Navigate to your Desktop Workspace configuration directory: C:/…/MokaFive/conf
2. Click to open the m53s.properties file.
3. Find or add the following line:
m5es.proxyForwardedLookupHeaders
4. Add comma-separated HTTP headers to this line in the order you would like them checked.
For example:
m5es.proxyForwardedLookupHeaders=X-Forwarded-For,Z-Forwarded-For
5. Save the file.
NOTE: User-provided lists of HTTP headers overrule the default Desktop Workspace list. If you upload
your own list of headers, make sure it is comprehensive. The proxy will check for headers in the order
you enter them in the list.
Desktop Workspace 4.2
Advanced Setup Guide
39
Adding a Reverse Proxy Server
If your organization supports Desktop Workspace Players that check in from the internet, you may require a
Reverse Proxy Server. This server terminates SSL connections in your DMZ before forwarding application traffic
to the appropriate Desktop Workspace application server. We recommend using hardware reverse proxy servers. Alternatively, you can build and deploy your own reverse proxy server using an open-source software solution,
such as Apache. To deploy an Apache server solution, refer to Deploying a Reverse Proxy Server With Apache.
Finally, if you need RSA two-factor authentication, you can use Desktop Workspace's Desktop Application
Gateway. To deploy a Desktop Workspace Application Gateway, refer to Adding a Desktop Application Gateway. Desktop Workspace 4.2
Advanced Setup Guide
40
Deploying a Reverse Proxy Server
with Apache
- Building an SSL Terminating Reverse Proxy Server Using Apache Web Server
- Install Apache
- Verify Connectivity and Firewall Settings (port 80)
- Configure Apache
- Deploying a Reverse Proxy Server with Apache
- Configure Reverse Proxy (port 443)
- Restart Apache
- Test Reverse Proxy (Port 443)
- Last Steps
- Trusted Certificates
If your organization supports Desktop Workspace Players that check in from the internet, you may require a
Reverse Proxy Server. This server terminates SSL connections in your DMZ before forwarding application traffic
to the appropriate Desktop Workspace application server.
Building an SSL Terminating Reverse Proxy
Server Using Apache Web Server
If you do not need two-factor RSA authentication and only require termination of connections in the DMZ, you
can use a hardware- or software-based solution for reverse proxy servers and load balancers. A software SSL
terminating reverse proxy server can be built and used with popular webservers like Apache httpd or IIS.
The following procedure outlines how to deploy a reverse proxy server with Apache.
Prerequisites
l
A Desktop Workspace server at server.yourcompany.com
l
An additional server or device to act as the reverse proxy, installed at gateway.yourcompany.com
Desktop Workspace 4.2
Advanced Setup Guide
41
Overall Steps
1. Install Apache
2. Verify Connectivity and Firewall Settings (port 80)
3. Configure Apache
4. Enable Port 443
5. Enable Reverse Proxy in Apache (port 443)
6. Deploying a Reverse Proxy Server with Apache
7. Configure Reverse Proxy (port 443)
8. Restart Apache
9. Test Reverse Proxy (Port 443)
10. Last Steps
Install Apache
1. Log in to Windows on the Gateway with the built-in local Administrator account.
2. Open Internet Explorer.
3. Log in to the Desktop Workspace Customer Support Center and navigate to the download page.
4. Download the Apache HTTP Server 2.2.27 for Windows Installer (.msi file).
5. Launch the Apache HTTP Server installer.
6. Click Next and accept all default fields until you reach the "Server Settings" screen.
7. Make changes to the following fields:
a. Network Domain: Enter the domain that your Gateway belongs to.
b. Server Name: Enter the host name of your Gateway server.
c. Administrator's Email Address: Enter your email address.
d. Accept the default option to Install Apache as a Service.
8. Accept the Typical setup option and click Next, Install, and Finish.
Verify Connectivity and Firewall Settings
(port 80)
1. Log in to Windows on the Gateway with the built-in local Administrator account.
2. Open the Firewall Settings in the Windows Control Panel.
3. Ensure that the HTTP port (port 80) and HTTPS port (port 443) are allowed through the firewall.
4. On a separate computer, open a browser and navigate to http://gateway.yourcompany.com. "It
works!" should appear in the browser.
Desktop Workspace 4.2
Advanced Setup Guide
42
Configure Apache
You can configure Apache by editing a text file named http.conf. When you installed Apache for Windows, it
created a helpful shortcut in the Start Menu.
1. Log in to the File Gateway Server (via RDP) with the built-in local Administrator account.
2. On the File Gateway Server, click Start > All Programs > Apache HTTP Server 2.2 > Configure Apache
Server > Edit the Apache httpd.conf configuration file.
3. The httpd.conf file opens in a text editor. Configure the following settings in the file:
Enable Port 443
1. Within the httpd.conf file, search for the following line:
Listen 80
2. Change this value to 443.
Listen 443
3. ​Save your changes.
Enable Reverse Proxy in Apache (port 443)
1. Within the http.conf file, search for the following lines:
#LoadModule proxy_module modules/mod_proxy.so
#LoadModule proxy_connect_module modules/mod_proxy_connect.so
#LoadModule proxy_http_module modules/mod_proxy_http.so
#LoadModule rewrite_module modules/mod_rewrite.so
#LoadModule headers_module modules/mod_headers.so
#LoadModule ssl_module modules/mod_ssl.so​
#Include conf/extra/httpd-vhosts.conf
2. Make these lines active by deleting the hash symbol (#) at the beginning of each line. The hash symbol
at the beginning of a line means the line is commented out, or inactive.
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule headers_module modules/mod_headers.so
LoadModule ssl_module modules/mod_ssl.so
Include conf/extra/httpd-vhosts.conf
​ opy and Convert the Desktop Workspace
C
HTTPS Keys and Certificates
Desktop Workspace 4.2
Advanced Setup Guide
43
1. Log in to Windows on the Server with the built-in local Adminsitrator account.
2. Navigate to the directory where the Desktop Workspace server is installed (by default, C:\Program
Files\MokaFive)
3. In the conf subdirectory, locate the two PEM files containing the server's HTTP certificate and
private key:
Note: Depending on configuration, these files might have different names but one file is guaranteed to
end with “-cert.pem” and the other with “-key.pem”.
l
​ssl-selfsigned_mgmt-cert.pem
l
ssl-selfsigned_mgmt-key.pem
4. Copy these two files to a secure location.
5. Log in to Windows on the Gateway with the built-in local Administrator account. 6. Create a folder titled C:\m5certs.
7. Copy the two PEM files from the secure location you placed them in in Step 4 into C:\m5certs.
8. Using a MS-DOS command prompt, navigate to the C:\m5certs directory.
cd C:\m5certs
9. C
​ onvert the original PEM file into a format that the Apache server can understand by entering this
command: C:\Program Files (x86)\Apache Software Foundation\Apache2.2\bin\openssl.exe rsa –in
ssl-selfsigned_mgmt-key.pem –out m5_key_np.pem
Note: When the system prompts you to enter a password, enter mokafive.
10. Rename the new PEM file (which ends with cert.pem) to m5_cert.pem.
rename ssl-selfsigned_mgmt-cert.pem m5_cert.pem 11. The C:\m5certs\ directory should now contain two files named m5_key.np.pem and m5_cert.pem.
Configure Reverse Proxy (port 443)
1. Open the conf\ directory containing the httpd.conf file and navigate to the subdirectory extra\.
2. Open the httpd-vhosts.conf file with a text editor.
3. Search for this line:
NameVirtualHost *:80
4. Change the value 80 to 443. This makes Apache use port 443 (HTTPS), rather than port 80.
<NameVirtualHost *:443>
5. Within the same file, identify the section delimited by the following lines:
<VirtualHost *:80>
and
</VirtualHos​t>
6. The following text contains some highlighted sections. In the httpd-vhosts.conf file, modify the
sections identified in the previous step to match the highlighted sections of the following text. If
the httpd-vhosts.conf file does not contain some of the entries highlighted below, add them.
Desktop Workspace 4.2
Advanced Setup Guide
44
Note: Change the values of VirtualHost, ErrorLog, and CustomLog. Do not change the values
of ServerAdmin, DocumentRoot, ServerName, or ServerAlias. Do not change any lines that do not
appear in the text below.
<VirtualHost *:443>
ServerAdmin webmaster@company.com
DocumentRoot "C:/Program Files (x86)/Apache Software
Foundation/Apache2.2/"
ServerName gateway.company.com
ServerAlias gateway.company.com
ErrorLog "logs/error-ssl.log"
CustomLog "logs/access-ssl.log" common
ProxyRequests Off
ProxyPreserveHost Off
<Location />
Order allow,deny
Allow from all
</Location>
SSLEngine on
SSLCertificateFile C:/m5certs/m5_cert.pem
SSLCertificateKeyFile C:/m5certs/m5_key_np.pem
ProxyPass / https://server.company.com/
ProxyPassReverse / https://server.company.com/
SSLProxyEngine On
Header set Proxy-Test "I love reverse proxies!
RequestHeader edit Authorization "^MokaFiveAuth ticket=[a-zA-Z0-9]+\\,\ "
""
</VirtualHost>
Note: The Header set Proxy-Test "I love reverse proxies!" line makes Apache inject a HTTP header in
all responses it returns.
7. Save your changes.
Restart Apache
1. Click on Start > All Programs > Apache HTTP Server 2.2 > Control Apache Server > Restart.
Test Reverse Proxy (Port 443)
1. Log in to Windows on another computer.
2. Configure your DNS so that the name server.yourcompany.com points to the IP address of the
Application Gateway computer.
3. Launch Internet Explorer and open this URL:
https://server.yourcompany.com/mconsole
4. Verify that you can log in to the M5ES server.
5. (Optional) Use a tool such a cURL or Charles Web Proxy to view the headers contained in the responses
returned by the Gateway. Verify that they contain the HTTP header:
Proxy-Test "I love reverse proxies!"
Desktop Workspace 4.2
Advanced Setup Guide
45
6. Remove the previous line and save the changes.
7. Restart the Apache server.
Last Steps
1. Log in to Windows on the Gateway with the built-in, local Administrator account.
2. In the Windows Control Panel an select Firewall Settings.
3. Disable that ports 80 (HTTP) are allowed through the Windows Firewall.
4. In the Gateway computer, navigate to the conf\extra\ directory open the httpd-vhosts.conf file using a
text editor.
5. Search for this line:
Header set Proxy-Test "I love reverse proxies!"
6. Remove the previous line and save changes. 7. Restart the Apache server.
Trusted Certificates
When your Desktop Workspace server is configured to use certificates that are not self-signed, it is necessary
to copy a third PEM file from the server to the Gateway.
1. Log in to Windows on the server with the built-in local Administrator account.
2. Navigate to the directory where the Desktop Workspace server is installed (by default, C:\Program
Files\MokaFive\).
3. In the conf/ subdirectory, locate the third PEM file that contains the server's HTTPS certificate chain:
ssl-selfsigned_mgmt-chain.pem
NOTE: Depending on the configuration, these files might have different names. One file will end
in '-cert.pem,' and the other will end with '-key.pem.'
4. Copy these two files to a secure location.
5. Log in to Windows on the Gateway with the built-in local Administrator account.
6. Copy this PEM file from the secure location into C:\m5certs and rename the file to m5_chain.pem.
7. In the http-vhosts.conf file, search for the line:
SSLCertificateKeyFile C:/m5certs/m5_key_np.pem
8. Below that line, add the following text:
SSLCertificateChainFile C:/m5certs/m5_chain.pem
9. Save your changes and restart the Apache server.
Desktop Workspace 4.2
Advanced Setup Guide
46
Installing an Active Directory Extender
- Installation Guidance
- Enabling Active Directory Extender
- Installing Active Directory Extender
- Using Active Directory Extender in the Management Server
Some users keep their Management Server and their Active Directory in different locations. Desktop
Workspace’s Active Directory Extender connects the two when there is no direct inbound connection from the
Management Server to Active Directory. This configuration also connects cloud-based Management Servers to
local Active Directories.
The Active Directory Extender is part of the Desktop Workspace installation package you can download from
the Software Support Portal.
Installation Guidance
The Active Directory Extender is supported on the following platforms:
l
Windows 7
l
Windows 8
l
Windows Server 2008 R2
l
Windows Server 2012
You can use the Active Directory Extender for any installation where the Management Server and Active
Directory are kept in different locations.
Install the Active Directory Extender in the same network as Active Directory.
Enabling Active Directory Extender
To use the Active Directory Extender, you must enable it in the Management Console, download the Active
Directory Extender installer, and connect it to your server.
1. Log in to the Management Console with your bootstrap admin account.
2. Go to Settings > Infrastructure and click on the Directory Servers tab.
3. You can create a new domain with the Add button, or modify an existing domain by clicking the
Edit button.
4. The Add Directory Service Domain window opens.
5. Check the box labeled Use AD Extender.
Desktop Workspace 4.2
Advanced Setup Guide
47
6. Enter a Domain Name and the Base Domain DN.
7. Click Save. Installing Active Directory Extender
1. Obtain the Active Directory Extender installer by downloading the latest release of Desktop Workspace
from the Software Support Portal. This is a ZIP file.
2. Unzip the installation package and extract the Active Directory Extender Installer (Moka5-#.#.#.#ADExtender-Installer.msi).
3. Double-click on the Active Directory Extender Installer file. The Active Directory Extender Installer
wizard opens.
4. On the first screen of the setup wizard, click Next. Desktop Workspace 4.2
Advanced Setup Guide
48
5. Acknowledge the end-user license agreement and click Next. 6. Specify a location where Active Directory Extender will install, or accept the default, and
click Next.
7. Optionally, click the checkbox marked Use an HTTP proxy server for communication with Server. If
you choose this option, the fields below will become configurable. Desktop Workspace 4.2
Advanced Setup Guide
49
8. Enter your HTTP proxy server information and click Next. 9. Enter the server address and login credentials and click Next. Note: Specify the address in full, including https:// at the beginning.
10. The installation begins. During this process, Active Directory Extender contacts and registers with the
Management Server.
11. When the installation completes, the Active Directory Extender will be visible in the Management
Server under Settings > Infrastructure in the AD Extenders tab.
Desktop Workspace 4.2
Advanced Setup Guide
50
NOTE: You may have to log out and log back in to the Management Server to see the updated
list of AD Extenders.
Using Active Directory Extender in the
Management Server
You can get visibility into your installed Active Directory Extenders in the Management Console. Navigate to
Settings > Infrastructure and click the AD Extenders tab.
Field Descriptions
Security Domain Name: The name you entered during setup.
Domain Name: The domain name for the Active Directory Extender.
Hostname: The name of the host on which the Active Directory Extender is installed.
ID: The alphanumerical ID of the Active Directory Extender.
Install Time: The date and time when the Active Directory Extender was installed.
Last Status Update: The date and time when the Active Directory Extender was last modified.
Action: Click Delete in this column to remove the Active Directory Extender. This action revokes the
Active Directory Extender’s access to the server. To reconnect a deleted Active Directory Extender,
you must reinstall it.
Desktop Workspace 4.2
Advanced Setup Guide
51
Adding a Desktop Application Gateway
- Using the Desktop Workspace 4.1.3 Desktop Application Gateway
- Adding a Gateway
- Installing the Desktop Application Gateway
- Test Your Desktop Application Gateway Configuration
An application gateway allows your users to authenticate over the Internet without a needing a VPN
connection on the host machine. Use the space below to record the information you will need to set up your
Desktop Application Gateway.
IMPORTANT: The Desktop Application Gateway is recommended only if you need to include two-factor
authentication with RSA SecureID. For all other cases, we recommend using an open-source reverse
proxy server, such as Apache. For more information, refer to Deploying a Reverse Proxy Server With
Apache.
Using the Desktop Workspace 4.1.3
Desktop Application Gateway
The Desktop Application Gateway acts as a reverse proxy with SSL. It performs two primary functions:
l
l
It terminates the client connection. This protects your infrastructure from buffer overrun attacks.
It enables you to add two-factor authentication using RSA SecureID. This increases your ability to check
for authorized or unauthorized access attempts.
Hardware Requirements
CPU
4 physical cores (8 logical CPU for Intel *)
RAM
8 GB
DISK
At least 10 GB free disk space on installation drive
OS
Windows Server 2012 or Windows Server 2008 R2 SP2
Java
Java 7u51 32-bit
* Feature of Intel Hyper-threading
Desktop Workspace 4.2
Advanced Setup Guide
52
IMPORTANT: The Application Gateway scales successfully for up to 1,500 Players. For installations with
more than 1,500 Players, we recommend installing additional Application Gateways.
Adding a Gateway
1. Provide the DNS of the Management Server. Deploying Desktop Application Gateway requires split DNS.
Split DNS means having the same DNS name (e.g., m5.acme.com) registered separately to external DNS
and your company’s internal DNS server, each of which resolve to different IP addresses. That is, the
external DNS name resolves to the Application Gateway’s address; the internal DNS name resolves to
the Management Server’s address.
In this way, when Players are on your internal network, they route directly to the Management
Server without going through the Desktop Application Gateway. Alternatively, when Players are
on the Internet outside your network, they route to the Desktop Application Gateway.
2. Provide the IP address of the NIC to which you want to bind.
3. Provide the listen port to use.
Desktop Workspace 4.2
Advanced Setup Guide
53
Installing the Desktop Application Gateway
1. Log in as the Administrator to the computer onto which you are installing.
2. Copy the Desktop Application Gateway installer file (Moka5-#.#.#-DesktopGateway-Installer.jar) and
the Java installer (jre-7u51-windows-i586.exe) to the computer.
3. Start the Java installer by double-clicking on it.
4. Start the Desktop Application Gateway installer by double-clicking on it.
5. Review and accept the End User License Agreement.
6. Click Next to accept the default installation path, or edit the path.
7. Select Desktop Application Gateway and click Next.
7. Accept the default installation items by clicking Next.
8. Enter the DNS name of the Management Server. Note that the Desktop Application Gateway setup
assumes that you have split DNS for the Management Server (i.e., the same DNS entry - m5.acme.com)
that is registered with external and internal DNS differently. The external DNS name resolves to the
Application Gateway’s address; the internal DNS name resolves to the Management Server’s address.
9. Set the SSL port to be the same as your other servers.
10. Leave the default administrator username as is (recommended), or edit it.
11. Enter and confirm the administrator password. Please note this password so you don’t forget it, then
click Next.
12. Wait until installation is complete.
13. If the Desktop Application Gateway is also proxying an image store, the image store must be added
explicitly. In the Desktop Application Gateway Configurator:
a. Click the Settings tab and click the Proxy Hosts link.
b. Click Add Proxy Host link and provide the Fully Qualified Domain Name (in the Host Name
field) of the image store and the port.
c. Regenerate the self-signed certificate to cover both the FQDN of the management server and
the FQDN of the image store. Refer to Generating a new Self-signed Certificate for more details.
Desktop Workspace 4.2
Advanced Setup Guide
54
14. Configure SSL for the Desktop Application Gateway:
a. If your infrastructure uses self-signed certificates, copy the self-signed certificate to the
Trusted CA Certificates on the management server. For more information, refer to Using Selfsigned Certificates.
b. If your infrastructure uses CA-signed certificates, refer to the instructions on requesting or
installing a CA-signed certificate in Using CA-Signed Certificates.
Test Your Desktop Application Gateway
Configuration
1. Place your computer on the external network.
2. Verify your Management Server and Desktop Application Gateway are installed and started.
3. Using a browser, enter the URL and port for the Management Server. This would be of the form https://
[yourProxyserver]:[listenport]/iconfig, where [yourProxyserver] is the hostname of your Desktop
Application Gateway and [listenport] is the listen port you specified in your installation.
4. The Management Console should appear, as if you were hitting its URL directly. If you had not already
logged in, you will be asked to login. If you do not see the Management Console, please review the
steps above.
5. Download a Desktop Workspace Player installer.
Congratulations, you’ve successfully installed and configured the Desktop Application Gateway!
Desktop Workspace 4.2
Advanced Setup Guide
55
Configuring SSL
- SSL Background
- Self-Signed or CA-Signed Certificates?
- A Note on Load Balancers and Layer 7 Firewalls
- Finishing SSL Setup in a Multi-server Self-signed Configuration
- Adding a Certificate to the Management Server’s Trusted CA Certificates
- Using Self-signed Certificates
- Using CA-Signed Certificates
- Replacing Expiring Certificates
SSL certificates secure the communications between clients and servers in the Desktop Workspace system. As
of version 3.7, Desktop Workspace servers communicate out of the box using SSL and self-signed certificates.
Clients by default validate those certificates; your clients will go off-line if SSL is misconfigured.
In this chapter, you'll learn a few techniques for configuring and managing SSL certificates, including:
1. SSL setup for advanced configurations:
l
Multi-server setups
l
Multi-tenant servers
l
Application Gateways
2. Replacing certificates with those from a certificate authority (CA)
3. Importing an existing key and certificate
4. Requesting a certificate from a CA
5. Replacing certificates that have expired
6. Renaming a server/Adding names to gateway
SSL Background
Servers in the Desktop Workspace system must have SSL certificates. Clients verify that they are talking to the
right server and not some impostor by validating SSL certificates.
There are three major kinds of SSL certificates, based on who vouches for the information in the certificate:
Certificate Type
Self-Signed
Browser Behavior
Warns
Client Behavior
Accept if certificate is in Truted CA
Desktop Workspace 4.2
Advanced Setup Guide
56
certs list
Well-known CA (Verisign,
GoDaddy, etc.)
Accept
Accepts
Enterprise CA
Accepts if browser configured with
enterprise CA root
Accepts if enterprise CA root is in
Trusted CA certs list
Certificates contain two important pieces of information:
l
l
Expiration date - certificates expire on the date specified in the certificate. Clients and browsers will
reject expired certificates.
One or more DNS names (e.g m5.acme.com) that the certificate covers.
If the DNS name in the URL does not match a DNS name in the certificate, the client and/or browser will abort
the connection. The first name in a certificate is usually in the Subject field under CN= (or Common Name).
Additional names are stored in the Subject Alternate Name.
DNS names in certificates can have wildcards. For example, the wildcard *.m5.acme.com matches
foo.m5.acme.com and bar.m5.acme.com, but not m5.acme.com.
Self-Signed or CA-Signed Certificates?
You can always change from self-signed certificates to CA-signed certificates, and vice versa, without affecting
your installed clients. A common sequence is to set up self-signed certificates initially and then upgrade to CAsigned certificates.
Self-signed certificates are convenient. Desktop Workspace server can automatically generate self-signed
certificates. CA-signed certificates must be requested from an enterprise CA or purchased from a certificate
authority.
CA-signed certificates are browser-friendly. When accessing the Desktop Workspace console with a browser,
you can avoid the security warning when using a CA-signed certificate. These warnings pop up when using selfsigned certificates. CA-signed certificates can also be more compatible with third-party scripting tools.
A Note on Load Balancers and Layer 7
Firewalls
In networks with a Citrix Netscaler™ or Microsoft ISA Server™, the clients connect to the layer 7 device, which
is the device with the SSL certificate. In that case, you must configure the layer 7 device with a certificate
containing all the DNS names that go through the device.
If clients only access the server components through a layer 7 device, it may be sufficient to use self-signed
certificates on the server components and only put CA signed certificates on the layer 7 device.
Desktop Workspace 4.2
Advanced Setup Guide
57
Finishing SSL Setup in a Multi-server Selfsigned Configuration
The self-signed certificates used by all servers must be added to the Trusted CA certificates list on the
management server’s Configurator.
Open the non-management server's Configurator and the management server's Configurator in two separate
browser windows.
Opening the Configuration on the non-management server:
1. Navigate to General -> Network.
2. Under Bindings, click on the key alias.
3. Copy the entire Certificate text field, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
Adding a Certificate to the Management
Server’s Trusted CA Certificates
Working on the Management Server’s Configurator:
1. Go to General -> Certificates -> Trusted CA Certificates.
2. Click Add Certificates.
3. Paste in the text.
4. Click Add.
The added certificate should now appear in the trusted CA certificates list.
Using Self-signed Certificates
The SSL certificates generated on first-time start will be incorrect for multi-tenant management servers and
some application gateways. Specifically, these certificates will be missing additional DNS names required.
In addition, if you rename a server, a new SSL certificate will need to be generated.
Generating a new Self-signed Certificate
1. Navigate to Certificates > SSL Certificates.
2. Click Generate Key and Self-signed Certificate.
3. Enter an alias name. This is a way to identify the certificate in Configurator.
4. For DNS name, enter the DNS name(s) of the component. If the component exposes multiple names,
enter multiple names separated by commas.
Component Type
DNS name(s) in certificate
Desktop Workspace 4.2
Advanced Setup Guide
58
Single-tenant management server
DNS name of server (m5.acme.com)
Multi-tenant management server
Wildcard DNS name of server (*.m5.acme.com)
Image store or replica
DNS name of server (img.m5.acme.com)
App Gateway
DNS names of proxied servers (m5.acme.com, img.m5.acme.com)
5. The remaining fields are optional. Some CAs may require this information, so you may want to fill this
information in if you wish to upgrade to a CA-signed certificate.
NOTE: If deploying the proxy, make sure at least one of the fields (e.g. unit name) is different
between the proxy and the original component.
6. Click Generate. A private key and self-signed certificate is generated and displayed.
7. Click Import. The certificate is now available for use. Click on the alias of the certificate you just
created to view details for that certificate.
Copying Self-signed Certificate to Management
Server’s Trusted CA Certificates
1. Click on the alias of the certificate to be copied.
2. Copy the entire Certificate text field, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.
3. Add the certificate to the management server’s Trusted CA certificates. For more information, refer to
Adding a Certificate to the Management Server’s Trusted CA Certificates
Enabling the new SSL Certificate
Once you’ve imported an SSL certificate, you can enable SSL through the network bindings.
1. Navigate to General > Network.
2. Click the Pencil icon to edit the binding
3. Choose the alias of the new SSL certificate from the dropdown
4. Click Update.
5. Restart the server.
(Optional) Deleting old Certificates
1. In SSL certificates, click on the certificate alias of the unused certificate and click Delete.
2. On the management server, under Trusted CA Certificates, click the Trash Can icon on any
certificates that are no longer used.
Desktop Workspace 4.2
Advanced Setup Guide
59
Using CA-Signed Certificates
SSL certificates can be procured from authorities such as DigiCert, Verisign, or your corporate certificate
authority. These certificates can be used to avoid warnings in browsers caused by self-signed certificates. If
you already have a private key and CA-signed certificate that you can use for your server, skip to Importing
Private Key and SSL Certificates
To procure an SSL certificate from a Certificate Authority, you must provide a Certificate Signing
Request (CSR).
Generating a Certificate Signing Request (CSR)
1. Generate a self-signed certificate using the steps in Generating a new Self-signed Certificate. Do not do
any of the steps under subsequent headings.
2. Open the self-signed certificate details, by clicking the alias in the SSL certificates list.
3. Copy all of the text in the CSR field, and paste it into a text file. This is the CSR that you need to send
to your CA.
4. Send the CSR to the SSL certificate authority of your choice. Request that the reply be PEM (a.ka.
Base64) encoded and not binary encoded.
After processing your order, the authority will send you your server certificate. Some authorities will send you
both your server certificate and one or more intermediate certificates. Both the server and intermediate
certificate must be imported into the Configurator. Once you receive the signed certificate from your CA,
you’ll need to replace the self-signed certificate with the new CA-signed certificate.
Verifying the Certificate
Some CAs will strip the additional DNS names from the certificate. If you created a wildcard certificate or a
certificate with multiple names, you should verify that this did not happen.
To verify:
1. Collect the Subject and Subject Alternate Name fields from the certificates:
Windows:
a. Double-click on the certificate. If that doesn’t work, rename the certificate file to have
extension .crt and then double-click on the certificate.
b. Click the Details tab.
Mac:
a. From the Terminal, do an openssl x509 –in /path/to/cert.crt –text, where /path/to/cert.crt is
replaced by the filesystem path to the certificate.
2. Verify that all the DNS names requested appear in the certificate. For wildcard certificate, make sure
that both wildcard and non-wildcard (e.g. *.m5.acme.com and m5.acme.com) are present.
3. If not all the DNS names appear, work with your CA to determine why.
Desktop Workspace 4.2
Advanced Setup Guide
60
Replacing a Certificate
1. Open the self-signed certificate details by clicking the alias in the SSL certificates list.
2. Click the Replace button.
3. Copy and paste the certificate you received from the CA into the Certificate field and then
click Update.
4. Your certificate may require intermediate certificates. Refer to Adding Intermediate Certificates for
more details.
5. If you are using an enterprise CA, you must make sure that the enterprise root CA is in the trusted CA
certificates on the management server. Refer to Adding an Enterprise Root CA for more details.
6. Refer to Using Self-signed Certificates on how to enable the certificate on a binding.
7. Restart your server.
You will now be using a CA-signed certificate.
Importing Private Key and SSL Certificates
If you already have a private key and a CA-signed certificate, you may import those directly into the
Configurator. Note that private keys should be in PKCS#1 or PKCS#8 PEM format.
1. Navigate to Certificates > SSL Certificates.
2. Click on Import Key and Certificate.
3. Enter an alias name. This is a way to identify the certificate in Configurator.
4. Open your server certificate file (.crt) in a text editor. Copy all the text in the file, including "-----BEGIN
CERTIFICATE-----".
5. Paste the certificate into the Certificate field.
6. Open your private key file in a text editor. Private keys are typically files with a .pem or .key
extension. Copy all the text in the file and paste it into the Private Key field.
7. If the private key is encrypted using a password, enter Key Password.
8. Click Import. The SSL certificate and key are now ready for use.
9. Your certificate may require intermediate certificates. Refer to Adding Intermediate Certificates for
more details.
10. If you are using an enterprise CA, you must make sure that the enterprise root CA is in the trusted CA
certificates on the management server. Refer to Adding an Enterprise Root CA for more details.
11. Refer to Enabling the new SSL Certificate for information on how to enable the certificate on a binding.
Adding Intermediate Certificates
Some certificate authorities distribute intermediate certificates that must be used to establish a chain of trust
between the CA’s root certificate and the certificate issued by the CA for the server. Add intermediate
certificates on each server component.
Desktop Workspace 4.2
Advanced Setup Guide
61
1. On the Certificates tab, click Intermediate Certificates.
2. Open your intermediate certificate files (.crt) in a text editor. Copy all the text in the file, including "----BEGIN CERTIFICATE-----".
3. Paste the certificate into the Certificate field. In some cases, the agency from which you procured the
certificate will send you a bundle certificate with all of the certificate information in a single .crt file.
You may copy and paste the entire set of information into Configurator; Configurator will parse this
information set correctly.
4. Click Add. Configurator will automatically chain the intermediate certificates to your server
certificate(s).
5. Repeat this process to add additional intermediate certificates, if needed.
6. Verify the intermediate certificates were correctly chained:
a. Navigate to Certificates > SSL Certificates and click on your server certificate.
b. You should see the server certificate listed with chained intermediate certificates listed in the
Issued By field.
Adding an Enterprise Root CA
1. Download the enterprise root CA certificate in PEM format.
2. On the management server’s Configurator, Navigate to Certificates -> Trusted CA certificates.
3. Click Add Certificates.
4. Paste the enterprise root CA certificate into the text field, including the "----BEGIN" and "-----END" lines.
5. Click Add.
Replacing Expiring Certificates
CA-signed Certificates
Repeat the instructions above for requesting a CA-signed certificate. Instead of creating a new certificate,
click on the existing certificate.
Self-signed Certificates
You must generate a new self-signed certificate. Refer to Generating a new Self-signed Certificate.
Desktop Workspace 4.2
Advanced Setup Guide
62
Blocking and Filtering IPs Attempting to
Access the Management Console
- What is an IP Filter?
- Using IP Filters in Desktop Workspace
- Creating a New IP Filter
- Modifying an IP Filter
- Deleting an IP Filter
By default, Desktop Workspace installations are open access. Any user with the correct URL and credentials
can access the Management Console. In some cases, administrators want to restrict access to the Management
Console to known secure IP addresses, such as ones originating from a local office or network. They can control
access by creating IP filters.
NOTE: If you have a proxy server in front of the Management Server and you wish to use the Remote
Access filter provided by the Management Server, you must add the proxy server in the Management
Console. For more information on proxy servers, refer to the LIVEPC ADMIN GUIDE.
What is an IP Filter?
IP filters prevent unauthorized IP addresses from accessing a particular URL or website by creating a
“whitelist” of remote IP addresses. Only IP addresses on the whitelist will be able to access certain URLs.
An IP address that is on the whitelist can make requests to the Management Console, or to public REST
APIs, or both.
Using IP Filters in Desktop Workspace
IP filters have four components.
l
IP: A standard IPv4 address with no subnet specified.
Desktop Workspace 4.2
Advanced Setup Guide
63
NOTE: You can use a wildcard character (*) in any quadrant of the IP (example: “*.*.10.*”) to
indicate that any entry in that quadrant will be accepted.
l
l
l
Alias: (Optional) A name or description for the filter.
Web Console: (True/False) Specifies whether or not the remote host with matching IP is allowed to
access the management web console.
Public APIs: (True/False) Specifies whether or not the remote host with matching IP is allowed to sent
HTTP requests to the Desktop Workspace public REST APIs.
Creating a New IP Filter
Only users with Bootstrap Administrator access are able to create IP filters.
1. From the Management Console, navigate to Settings > Infrastructure > Remote Access.
2. Click Add a New IP Filter. The Create IP Filter dialog box opens.
3. Enter the allowed IP and optional Alias,and specify whether the IP can access the Web Console and
Public Rest APIs.
4. Click OK to create the filter.
Modifying an IP Filter
1. From the Management Console, navigate to Settings > Infrastructure > Remote Access.
2. Find the IP filter you wish to modify and click Edit in the Action column for that filter. The Modify IP
Filter dialog box opens.
3. Make changes to any of the fields in the dialog box.
4. Click Save to update the filter.
Desktop Workspace 4.2
Advanced Setup Guide
64
Deleting an IP Filter
1. From the Management Console, navigate to Settings > Infrastructure > Remote Access.
2. Find the IP filter you wish to edit and click Delete in the Action column for that filter. A confirmation
dialog box opens.
3. Click Yes to delete the filter.
Desktop Workspace 4.2
Advanced Setup Guide
65
Configuring an HTTP Proxy for
Outbound Traffic
The Management Server can be configured to use an HTTP Proxy when communicating to external resources,
such as a Replica Image Store hosted by Amazon S3, or the Desktop Workspace Licensing Server.
1. Log in to the server configurator (http://yourserver.com/iconfig) with your bootstrap admin
credentials.
2. Click the HTTP Proxy link.
3. In the HTTP Proxy Settings menu, click Edit Settings to configure the HTTP proxy.
4. Click the Enable HTTP Proxy checkbox to enable the HTTP proxy.
5. Enter the proxy settings in the appropriate fields.
NOTE: The Proxy User and Proxy Password fields are optional. If you do not have login credentials
enabled for your proxy, you do not need to fill in these fields.
6. Click Update.
Desktop Workspace 4.2
Advanced Setup Guide
66
NOTE:The Bypass Local Addresses checkbox is checked by default. This setting allows the server to
ignore the proxy when making requests to local addresses.
Desktop Workspace 4.2
Advanced Setup Guide
67
Scaling the Management Server
The Management Server controls all targeted images, group memberships, authentications, policies, and
provides the administrative console. As the number of end users grows, you may find user login times
beginning to lengthen, or the administrative console may become less responsive. These can be improved
through adjustment of check-in periods. However, as your deployment grows, you will likely require additional
Management Server instances to share the load.
The Management Server is designed to allow for additional instances to be added to the original, behind an
external load balancer.
For more information, please refer to the Dell Knowledge Base.
Desktop Workspace 4.2
Advanced Setup Guide
68
Enabling Multi-Tenancy (Service
Provider Edition)
- Prerequisites
- Wildcard Certificate
- DNS Entry
- Enabling Multi-Tenancy (Service Provider Edition)
Multi Tenancy allows an MSP to host multiple customers on a single Desktop Workspace installation. The
installation is divided into multiple Desktop Workspace Server instances that can be managed individually at
the Customer level or by an Administrator at the MSP. The customer would then connect to their Tenant from
a web browser in order to download the Desktop Workspace Player installers and the LivePC images.
Each tenant has its own domain name which is a subdomain of the main server. For example, if the main server
is m5.acme.com, the tenant fake would access the server at fake.m5.acme.com. Since it would be tedious to
add a DNS record and create a new certificate each time a tenant is added, we recommend the use of wildcard
certificates and wildcard DNS entries.
Prerequisites
The administrator must have a complete Desktop Workspace server installed and must be using the proper
license (with Service Provider Edition enabled).
l
Management Console with SSL enabled (using a self-signed certificate is OK)
l
Application Gateway on the DMZ
l
Primary Image Store on the DMZ​
Wildcard Certificate
The wildcard certificate will be in the format *.servername.domain.com in order to cover any possible subdomain (ex: *.m5.acme.com). To generate a self-signed certificate, refer to Using Self-signed Certificates. For
CA-signed certificates, refer to Using CA-Signed Certificates.
DNS Entry
On the networking side, a DNS entry must be made for each tenant hostname/URL created. A wildcard DNS
entry can be used to cover all possible sub-domains dynamically in the format *.servername.domain.com. A
Desktop Workspace 4.2
Advanced Setup Guide
69
DNS entry is required on your Internet-facing DNS service for clients from the Internet to access the Desktop
Workspace Server.
Creating a New Tenant
Creating a new tenant will create a new hostname and completely new server instance for each tenant that
will be managed separately. The hostname and subsequent URL used to manage the tenant will be a
subdomain of your original hostname/URL. (i.e. https://tenant.servername.domain.com). This can be done by
logging into the Desktop Workspace Management Console with an ID that has the "Desktop Admin" role,
clicking the Tenants tab, and then clicking the Create button.
Enter new tenant info, noting that the Tenant Name creates the URL that users will log into later to access
that tenant. Tenants can be set up using one of three types: Production, Evaluation, or NFR. The tenant type
allows MSPs to setup unpaid evaluations or not for-resale-licenses using the same infrastructure as their
production environment. Also note, the Tenant Admin User ID and Admin Password will create the bootstrap
account for the new tenant, and will be used to log into the new URL and begin assigning roles to new users.
Desktop Workspace 4.2
Advanced Setup Guide
70
Uninstalling Desktop Workspace
- Uninstalling Desktop Workspace Enterprise Server Components
- Uninstalling Desktop Workspace Clients: Windows PC
- Uninstalling Desktop Workspace Clients: Mac
- Alternate Method to Uninstall Mac Player
Uninstalling Desktop Workspace is simple and straightforward. You uninstall each server component and client
separately.
Uninstalling Desktop Workspace Enterprise
Server Components
1. Open the Start menu and select Programs > Moka5 > Moka5 Enterprise Services > Stop M5ES.
2. Open the Start menu and select Programs > Moka5 > Moka5 Enterprise Services > Uninstall M5ES.
Uninstalling Desktop Workspace Clients:
Windows PC
1. On each Windows machine that has Player or Creator installed, Open the Start menu and select
Control Panel.
2. Click Add or Remove Programs.
3. Select Desktop Workspace Player or Desktop Workspace Creator.
4. Click Change/Remove. The application is removed.
5. Some Desktop Workspace files are not deleted, to allow a user to reinstall and resume much faster
than they would if starting from scratch. To remove all Desktop Workspace files, delete the
following folder: C:\Documents and Settings[user]\Application Datamokafive, where [user] is the
name of the user.
Desktop Workspace 4.2
Advanced Setup Guide
71
Uninstalling Desktop Workspace Clients:
Mac
1. On each Mac machine that has Player or Creator installed, go to Applications and delete the Desktop
Workspace Player or Desktop Workspace Creator. The application is removed.
2. Some Desktop Workspace files are not deleted to allow a user to reinstall and resume much faster
than they would if starting from scratch. To remove all Desktop Workspace files, delete the following
folder: [user home]\Library/Application Support\mokafive, where [user home] is the home directory
for the user.
Alternate Method to Uninstall Mac Player
1. Go (menu) > Computer.
2. Double-click on your hard disk .
3. Navigate to Library > Application Support > Moka5.
4. Double-click Moka5 Uninstaller.
5. Check the boxes for Images, user data, and profile to get rid of your LivePCs.
After the uninstall, you can reinstall Player and re-download the LivePC.
Desktop Workspace 4.2
Advanced Setup Guide
72
Run Host Scripts on Mac or Windows
Host Computers
This mechanism adds flexibility for IT administrators to collect important host attributes and to perform
critical checks and actions at Desktop Workspace Player start time, before users gain access to LivePC images.
Results can be reported back to the Management Server.
This feature is intended for Desktop Workspace administrators with advanced scripting knowledge.
For more information, please refer to this Knowledge Base article on this topic.
Desktop Workspace 4.2
Advanced Setup Guide
73
Display a Custom EULA When Starting
Desktop Workspace Player
For BYO initiatives, administrators can present a custom End User License Agreement to users, and track user
acceptance from the Management Server.
For more information, please refer to the Dell Knowledge Base.
Desktop Workspace 4.2
Advanced Setup Guide
74
Creating Domain Join Packets Using
an API
This REST API provides an advanced method for administrators to implement the Domain Join Packet (also
known as AD Packet) creation process, without the need to use Desktop Workspace Creator. This can be used
by enterprises to:
l
l
Automate the creation of packets at user-provisioning time, integrated with an external
provisioning workflow
Manually recreate a packet for a specific user while preserving the same computer name
For more information, please refer to this Knowledge Base article on this topic.
Desktop Workspace 4.2
Advanced Setup Guide
75
Using REST APIs in Desktop Workspace
You can use APIs to integrate your system with Desktop Workspace’s features to give you greater control of an
end user’s experience. The current APIs outline the following scenarios.
1. Managing Active Resource Packets
2. Authentication
3. Managing Devices
4. Inventory
5. Managing Tenants
API Formatting
Each API in this document contains the following sections:
Requirements: A list of prerequisites necessary to use the API.
Access Level: The access level required to use the API. In cases where the access level is “Desktop
Administrator,” the client must authenticate with a user that has the Desktop Administrator role. When the
access level is “User,” the client can authenticate with the credentials of the user than owns the resource
(device, subscription, user, etc) being accessed.
HTTP Method: The HTTP method to be used in requests.
URL: The resource URL. For example, the URL /api/users/<domainName>/<userId> would be accessed using
https://moka5.company.com/api/users/local/user1, where “local” is a registered security domain and
“user1” is a user belonging to that domain. Elements of the URL that are surrounded by angle brackets (e.g.
<domainName>, <userId>) are expected to be replaced by the actual values (e.g. “local”, “user1”).
Expected response: The HTTP response code returned by the server.
Sample response JSON: An example of the JSON response returned by the server upon a successful request. Request/Response Parameters (if applicable): A list of specific values that the API requires, or that are
returned after a successful API call and will be required by other API functions.
Authentication and Authorization
All REST APIs outlined in this document require authentication, with the exception of Checking Server Status
and Looking Up Version Information. Authenticate with HTTP Basic Authentication and (optionally) an
authentication cookie. Using HTTP Basic Authentication
Desktop Workspace 4.2
Advanced Setup Guide
76
HTTP requests sent to REST APIs should include an authentication header containing the user name and
password of the user who is making the request. The format of the header is defined in the sections 10.2 and
11 of the HTTP specification (http://tools.ietf.org/html/rfc1945):
Header Name
Value
Authorization
Basic <user:password encoded in Base64>
The /api/login resource (refer to ) can be used to verify if the authentication details were specified correctly,
and to obtain a JSESSIONID cookie.
Using an Authentication Cookie
All responses to authenticated requests contain a cookie with a JSESSIONID token that can be used to
authenticate subsequent requests. To use this authentication mechanism, HTTP requests must present the
cookie that was returned by the server or, alternatively, include a JSESSIONID=<value of the token> in their
parameter list.
The JSESSIONID token is valid for any number of requests, but expires after 30 minutes of inactivity. If a
request contains both a valid JSESSIONID token and an HTTP Basic Authentication header, the header will be
used. Such requests will also invalidate the old JSESSIONID token and will return a cookie containing a new
JSESSIONID token.
Authorization
Requests that require authentication are executed with the permissions of the user making the request. In
most cases, users are not allowed to access resources unless they own the resource (e.g. user Bob cannot
revoke a subscription that belongs to Mike) or have the Desktop Administrator role. The only exception to this
rule is that users are not allowed to unrevoke access to devices and subscriptions that they own.
Versioning
To accommodate changes in the specification of the REST APIs, every API supports a version identifier in the
resource name to specify which version of that particular API to use. In 4.0 (Vanguard) all APIs are at version 1.
The 4.1 (Warlord) release added new APIs without breaking backwards compatibility with 4.0, therefore some
APIs would be at version 1 while others would be at version 2.
In the future it is possible that changes in some resources (such as adding/removing parameters, different
response format) might require a new version for some of the existing resources.
The version of a particular resource to use can be specified by prepending the string “v<number>/” to the
resource path. For example, the options and response of the URL /api/v1/devices/123/killed would follow
Version 1 of the “Killing a Device” scenario while /api/v8/devices/123/killed would follow Version 8.
If a version prefix is not specified then the server will use the latest version that it supports. The minimum,
maximum, and current versions supported by the server can be determined by querying the /api/version
resource (see the “Looking Up Version Information” section).
In 4.0 (Vanguard), all resources are at version 1. As of 4.1 (Warlord), all version 1 APIs are still supported and
new APIs have been added with version 2.
Desktop Workspace 4.2
Advanced Setup Guide
77
Exporting User Information
You can use a Powershell script to obtain a CSV output of all user information in a given domain, including all
device and LivecPC subscription information.
To use the script, configure the top section of the Powershell script to point to the correct Desktop Workspace
Management Server, and to authenticate with a Desktop Administrator role.
You should also configure the propertyNames parameter if you want to include results on host properties.
After configuring these basic parameters, run the following script: api-dump.ps1 -domain banana where "banana" is the name of your domain you want to export as configured within the Desktop
Workspace Management Server.
This will output a CSV file called all-users-banana.csv which contains a line for every LivePC subscription,
grouped by user and by device.
Editing the PrintCsvHeader and PrintCsvLine functions in the Powershell script itself allows you to
configure the rest of the columns. This allows greater flexibility from the CSV results. This is a more advanced
operation for which you will need to consult the public REST API documentation.
Managing Active Resource Packets
This section of the REST API provides an advanced method for administrators to implement a Domain Join
packet (or Active Resource packet) creation process without using the Desktop Workspace Creator. This gives
you increased management capabilities, such as:
l
l
Automated packet creation that occurs at the time a user is provisioned and is integrated with an
external provisioning workflow.
Manual packet recreation for specific users without changing the computer name.
Uploading an AD packet
To upload an AD packet, send a POST to your packet URL. Include JSON with specific details about the packet.
The response will display the packet location and an AVAILABLE state. Requirements
l
A LivePC environment (<livepcid1>)
l
At least two AD packet sets (batch 1, batch 2)
Access Level
l
Desktop Administrator
Request Parameters
You may also include the following parameters in the JSON message.
Desktop Workspace 4.2
Advanced Setup Guide
78
Parameter
Example value
Description
certificate
uRhDAF3dm90jk A Base64-encoded PFX/PKCS12 file containing any certificates/keys
to import into the trust store (optional). This file must be encoded
with password "foo" by default.
expiry
112233445566
The number of days after which this AD packet should be marked as
expired and no longer used.
reservedUserName
User1
The userid of the user that this AD packet should be reserved for
(optional). It must be a valid user in AD. Only this user will be able
to claim this AD packet.
reservedUserDomain company
The name of the domain to lookup the reservedUserName in
(required if reservedUserName is specified). This should be the
name of the domain as known by the management console, not the
external actual name.
userName
The name of the user who uploaded the AD packet.
jsmith
API Methods
Use the following method to upload an AD packet.
HTTP
Method
POST
URL
/api/adpackets
JSON
{ "computerName": "comp123", "domainName": "moka5.com", "batchName":
"batch1", "livepcId": "<livepcId1>", "data": "SGVyZUlzTXlQYWNrZXREYXRh" }
Expected HTTP 201
Response
Response
header
“Location”=”
Response
JSON
{ "adpacket": { "name": "<packetId1>", "computerName": "comp123",
"batchName": "batch1", "livepcId": "<livepcId1>", "state": "AVAILABLE" } }
<baseURL>/api/adpackets<packetID1>” Response Parameters
Depending on the AD packet configuration, the JSON response may include other elements.
Parameter
Example Description
Value
expiration
30
reservedUserName User1
The number of days after which this AD packet should be marked as expired
and no longer used.
The user ID of the user that this AD packet should be reserved for (optional).
It must be a valid user in AD. Only this user will be able to claim this AD
packet.
There are some additional parameters that may also be specified:• "name": The unique identifier for this AD
packet. If you choose later to use this same API to remove this packet, this is the name that must be used.•
"state": The state of the packet. Newly uploaded packets should have a state of either AVAILABLE or RESERVED.
Desktop Workspace 4.2
Advanced Setup Guide
79
Uploading a Reserved AD packet
This process assigns a reserved packet to a user in a group targeted by a LivePC. To upload a reserved packet,
send a POST to your packet URL and specify the user to whom the packet will be assigned.
Additional request and response parameters can be viewed in Uploading an AD packet.
Requirements
l
A LivePC identified by <livepcId1> l
At least one set of AD packet identified by <batch1>
Access Level
l
Desktop Administrator
HTTP
Method
POST
URL
/api/adpackets
JSON
{ "computerName": "comp123", "domainName": "moka5.com", "batchName":
"batch1", "livepcId": "<livepcId1>", "data": "SGVyZUlzTXlQYWNrZXREYXRh",
"reservedUserName": "bob", "reservedUserDomain": "local" }
Expected
Response
HTTP 201
Response
JSON
{ "adpacket": { "name": "<packetId1>", "computerName": "comp123",
"batchName": "batch1", "livepcId": "<livepcId1>", "state": "RESERVED",
"reservedUserName": "bob" } }
Getting AD packet information
To view information on a specific AD packet, send an HTTP GET to the resource where the packet
information is stored.
Additional request and response parameters can be viewed in the “Uploading an AD Packet” section.
Requirements
l
An existing AD packet identified by <packetId1>
Access Level
l
Desktop Administrator
HTTP Method GET
URL
/api/adpackets/<packetId1>
Expected
Response
HTTP 200
Response
JSON
{ "adpacket": { "name": "<packetId1>", "computerName": "comp123",
"batchName": "batch1", "livepcId": "<livepcId1>", "state": "AVAILABLE"
} }
Listing AD packets
To view a list of all AD packets, send an HTTP GET to the resource where the packet information is stored.
Desktop Workspace 4.2
Advanced Setup Guide
80
Requirements
l
At least two existing AD packets identified by <packetId1> and <packetId2>
Access Level
l
Desktop Administrator
HTTP Method GET
URL
/api/adpackets/
Expected Response
HTTP 200
Response JSON
{
"adpackets": [
{
"name": "<packetId1>",
"computerName": "comp123",
"batchName": "batch1",
"livepcId": "<livepcId1>",
"state": "AVAILABLE"
},
{
"name": "<packetId2>",
"computerName": "comp345",
"batchName": "batch2",
"livepcId": "<livepcId1>",
"state": "AVAILABLE"
}
]
}
Deleting an AD packet
Send an HTTP DELETE to remove an AD packet.
Requirements
l
An existing AD packet identified by <packetId1>
Access Level
l
Desktop Administrator
HTTP Method
DELETE
URL
/api/adpackets/<packetId1>
Expected Response
HTTP 200
Desktop Workspace 4.2
Advanced Setup Guide
81
Authentication
Use these APIs to ensure secure access to your Desktop Workspace system.
Rejecting a Login Attempt Based on Incorrect
Credentials
Send an HTTP GET to the subscription directory with the wrong password.
Requirements
l
A LivePC (foolivepc) targeted to a group (foo).
l
A user (vlad) with a password (pwd-vlad), subscribed to the LivePC and group.
Access Level
l
Desktop Administrator
HTTP Method
GET
URL
api/users/local/vlad/subscriptions
Basic Authentication
“local\vlad” = “wrong-password”
Expected Response
HTTP 401
Rejecting a Login Attempt Based on Insufficient User
Permissions
Send an HTTP GET to one user’s subscription directory using another user’s credentials.
Requirements
l
A LivePC (foolivepc) targeted to a group (foo).
l
A user (vlad) with a password (pwd-vlad), subscribed to the LivePC and group.
l
A user (joe) with a password (pwd-joe), subscribed to the LivePC and group.
Access Level
l
Desktop Administrator
HTTP Method
GET
URL
api/users/local/vlad/subscriptions
Basic
Authentication
“local\joe” = “pwd-joe”
Expected
Response
HTTP 403
Response JSON
{
Desktop Workspace 4.2
Advanced Setup Guide
82
"message" : "Access to this resource requires administrator
privileges"
}
Managing Devices
Looking Up Device Properties
Use a GET to view device properties. One method displays a simple device status. The second method displays
a more detailed list of device properties.
Method 1
Requirements
l
The device ID (represented by <deviceId1>) of a known device.
Access level
l
Desktop Administrator or device owner
HTTP
Method
GET
URL
/api/devices/<deviceId1>
Request Parameters (optional):
Parameter
Name
properties
Accepted
Values
true
Default
Value
false
false
Description Whether to include a list of device-specific properties, as outlined in the next section.
Expected
response
HTTP 200
Sample
Response
JSON
{ "device": { "deviceId": "<deviceId1>", "name": "Device 1", "status":
"ACTIVE", "clientVersion": "3.18", "serial": "12345", "model": "xpto",
"osMake": "Windows", "osModel": "Server 2012", "osVersion": “6.2”,
"registeredAt": 112233445566, "lastCheckedInAt": 112233445566 } }
Method 2
Requirements
Desktop Workspace 4.2
Advanced Setup Guide
83
l
The device id (represented by <deviceId1>) of a known device.
l
Specific device properties have been submitted, such as:
Namespace
Key
Value
Type
Device
Eula
True
TEXT
Device
Hostname
URL.com
TEXT
Device
Mac
11-22-33
TEXT
Access level
l
Desktop Administrator or device owner
HTTP
Method
GET
URL
/api/devices/<deviceId1>?properties=true
Expected
Response
HTTP 200
Sample
Response
JSON
{ "device": { "deviceId": "<deviceId1>", "name": "Device 1", "status":
"ACTIVE", "clientVersion": "3.18", "serial": "12345", "model": "xpto",
"osMake": "Windows", "osModel": "Server 2012", "osVersion": “6.2”,
"registeredAt": 112233445566, "lastCheckedInAt": 112233445566
"properties": { "device": { "eula": { "value": "true", "type": "TEXT",
"version": 0 }, "hostname": { "value": "foo.com", "type": "TEXT",
"version": 0 }, "mac": { "value": "11-22-33", "type": "TEXT", "version": 0
} } } } }
Inventory
Use these APIs to look up information about devices, LivePCs, subscriptions, users, and client packs in your
Desktop Workspace installation.
Looking Up LivePCs
Method 1 (Looking up a specific LivePC)
Send an HTTP GET to a specific LivePC directory to see information on that LivePC.
Requirements
l
A LivePC (<livepc1>).
Access Level
l
Desktop Administrator
HTTP Method
GET
URL
api/livepcs/<livepc1>
Desktop Workspace 4.2
Advanced Setup Guide
84
Expected
Response
HTTP 200
Response JSON
{
"livepc" : {
"livepcId": "<livepc1>",
"createdAt": "<Number: The time the LivePC was created>",
"modifiedAt": "<Number: The time the LivePC was last modified>",
"ownerTenantName": "<String: The tenant that owns the LivePC>",
"policyModifiedAt": "<Number: The time the LivePC was last
modified>",
"version": 1,
"versions": [ {
"version": 1,
"title": "FooLivepc",
"description": "here is the description",
"deepCopy": true,
"disabled": false,
"uuid": "<String: A unique UUID for this version>",
"domainJoined": true,
"layered": true,
"totalSize": 221027,
"creator": "<String: The user that created this version>",
"committedAt": "<Number: The time this version LivePC was
committed>",
"published": false
} ]
}
}
Method 2 (Looking up all existing LivePCs)
Send an HTTP GET to the LivePC parent directory to see a list of all LivePCs.
Requirements
l
A LivePC (<livepc1>)
Access Level
l
Desktop Administrator
Desktop Workspace 4.2
Advanced Setup Guide
85
HTTP Method
GET
URL
api/livepcs
Expected
Response
HTTP 200
Response JSON
{
"livepcs" : [ {
"livepcId": "<livepc1>",
"createdAt": "<Number: The time the LivePC was created>",
"modifiedAt": "<Number: The time the LivePC was last modified>",
"ownerTenantName": "<String: The tenant that owns the LivePC>",
"policyModifiedAt": "<Number: The time the LivePC was last
modified>",
"version": 1,
"versions": [ {
"version": 1,
"title": "FooLivepc",
"description": "here is the description",
"deepCopy": true,
"disabled": false,
"uuid": "<String: A unique UUID for this version>",
"domainJoined": true,
"layered": true,
"totalSize": 221027,
"creator": "<String: The user that created this version>",
"committedAt": "<Number: The time this version LivePC was
committed>",
"published": false
} ]
} ]
}
Looking Up Users in a Domain
Send an HTTP GET to the local users directory to see a list of all users.
Requirements
l
At least two users (“bob” and “joe”).
Access Level
Desktop Workspace 4.2
Advanced Setup Guide
86
l
Desktop Administrator
HTTP Method
GET
URL
/api/users/local
Expected Response
HTTP 200
Response JSON
{
"users": [ {
"userId": "bob",
"domain": "local",
"guid": "<String: a unique identifier for this user>",
"status": "Active",
"numTargetedLivepcs": 1,
"targetedPlayerVersions": {
"win": "3.17.1",
"osx": "3.17.1",
"baremetal": "3.17.1"
}
}, {
"userId": "joe",
"domain": "local",
"guid": "<String: a unique identifier for this user>",
"status": "Active",
"numTargetedLivepcs": 0,
"targetedPlayerVersions": {
"win": "3.17.1",
"osx": "3.17.1",
"baremetal": "3.17.1"
}
} ]
}
Looking Up Subscriptions
Send an HTTP GET to the subscriptions directory to see a list of all subscriptions.
Access Level
l
Desktop Administrator
Desktop Workspace 4.2
Advanced Setup Guide
87
HTTP
Method
GET
URL
/api/subscriptions
Expected HTTP 200
Response
Response
JSON
{ "subscriptions": [ { "subscriptionId": "<subscrId1>",
"livepcTitle": "<String: the title of the LivePC>", "livepcVersion":
"<Number, nullable: the version of the LivePC>", "hostname":
"<String, nullable: the hostname of the device>", "status":
"<String: one of ACTIVE, REVOKED or KILLED>", "clientStatus":
"<String: the status of the client>", "registeredAt": "<Number,
nullable: the time the subscription was registered with the
server>", "lastCheckedInAt": "<Number, nullable: the time the
subscriptions last reported its status>", "deviceId": "<String: the
ID of the player of this subscription>", "deviceCompName": "<String:
the name of the computer associated to this subscription>",
"deviceStatus": "<String: one of ACTIVE, REVOKED or KILLED>",
"owner": { "userId": "<String: the ID of the user that owns the
subscription>", "domain": "<String: the domain name of the user that
owns the subscription>" }
} ]
}
Looking Up Devices
Send an HTTP GET to the device directory to see a list of all devices (Players and Creators).
Requirements
l
A Player or Creator (<deviceId1>)
Access Level
l
Desktop Administrator
HTTP
Method
GET
URL
/api/devices
Expected HTTP 200
Response
"deviceId": "<deviceId1>", "name": "<String: the name of
Response { "devices": [ { the device>", "status": "<String: one of ACTIVE, REVOKED or KILLED>",
JSON
"clientVersion": "<String, nullable: the version of the player>",
"serial": "<String, nullable: the unique identifier for this player>",
"model": "<String, nullable: a string that identifies the model of this
player>", "osMake": "<String, nullable: type of operating system (e.g.
Windows)>", "osModel": "<String, nullable: version of operating system
(e.g. XP)>", "osVersion": "<String, nullable: internal version of
Desktop Workspace 4.2
Advanced Setup Guide
88
operating system (e.g. 6.1.000)>", "arch": "<Number, nullable: the
architecture of the player (32, 64)>", "registeredAt": "<Number: the time
the device first registered with the server>", "lastCheckedInAt":
"<Number, nullable: the time the device last reported its status>",
"properties": "<Object: a set of device properties>", "owner": { "userId": "<String: the ID of the user that owns the device>", "domain":
"<String: the domain name of the user that owns the device>" } } ] }
Looking Up Devices with Properties
Send an HTTP GET to the device directory to see a list of all devices (Players and Creators) including their
custom properties.
Requirements
l
A Player or Creator (<deviceId1>)
Access Level
l
Desktop Administrator
HTTP
Method
GET
URL
/api/devices?properties=true
Expected HTTP 200
Response
{"deviceId": "<deviceId1>", "name": "<String: the name of
Response {"devices": [ the device>", "status": "<String: one of ACTIVE, REVOKED or KILLED>",
JSON
"clientVersion": "<String, nullable: the version of the player>",
"serial": "<String, nullable: the unique identifier for this player>",
"model": "<String, nullable: a string that identifies the model of this
player>", "osMake": "<String, nullable: type of operating system (e.g.
Windows)>", "osModel": "<String, nullable: version of operating system
(e.g. XP)>", "osVersion": "<String, nullable: internal version of
operating system (e.g. 6.1.000)>", "arch": "<Number, nullable: the
architecture of the player (32, 64)>", "registeredAt": "<Number: the time
the device first registered with the server>", "lastCheckedInAt":
"<Number, nullable: the time the device last reported its status>",
"properties": { "device": { "eula": { "value": "true", "type": "TEXT",
"version": 0 }, "hostname": { "value": "foo.com", "type": "TEXT",
"version": 0 }, "mac": { "value": "11-22-33", "type": "TEXT", "version":
0 } } } } ]}
Looking Up Client Packs
Send an HTTP GET to the client packs directory to see a list of all client packs.
Access Level
l
Desktop Administrator
Desktop Workspace 4.2
Advanced Setup Guide
89
HTTP
Method
GET
URL
/api/clientpacks
Expected HTTP 200
Response
"version": "<String: the version of this client
Response { "clientPacks": [ { pack>", "fusionVersion": "<String, nullable: the version of VMWare Fusion
JSON
of this client pack>", "createdAt": "<Number: the time when this client
pack was uploaded>", "ownerTenantName": "<String: the version of the
player>", "platforms": { "win": true, "osx": true, "baremetal": true }
} ] }
Managing Tenants
Create a Tenant
To create a new tenant, send a POST to the /api/tenants resource. If this action is successful, the server will
respond with the details of the new tenant that has just been created.
HTTP Method
POST
URL
/api/tenants
Sample request JSON
{
"name": "cyberdyne",
"companyName": "Cyberdyne Systems Corp.",
"type": "PRODUCTION",
"admin": {
"userId": "admin1",
"password": "password"
}
}
Expected response
HTTP 200
Sample response JSON
{
"tenant": {
"name": "cyberdyne",
"companyName": "Cyberdyne Systems Corp.",
"type": "PRODUCTION",
"url": "cyberdyne.m5server.com”
"deleted": false,
"disabled": false,
Desktop Workspace 4.2
Advanced Setup Guide
90
"master": false
}
}
Update a Tenant
To update an existing tenant, send a PUT to the /api/tenants/<tenant> resource. If this action is successful,
the server will respond with the details of the tenant that has just been updated.
Requirements
l
An existing tenant identified by <tenantname>
Access Level
l
Desktop Administrator
HTTP Method
PUT
URL
/api/tenants/<tenantname>
Sample request JSON
{
"companyName": "Acme Corp.",
"type": "EVALUATION",
"admin": {
"userId": "admin1",
"password": "password"
}
}
Expected response
HTTP 200
Sample response JSON
{
"tenant": {
"companyName": "Acme Corp.",
"type": "EVALUATION",
"deleted": false,
"disabled": false,
"master": false
}
}
Retrieve Information About a Tenant
Send an HTTP GET to the specific tenant resource to see information about that tenant.
Requirements
l
An existing tenant identified by <tenantname>
Desktop Workspace 4.2
Advanced Setup Guide
91
Access Level
l
Desktop Administrator
HTTP Method
GET
URL
/api/tenants/<tenantname>
Expected Response
HTTP 200
Response JSON
{
"tenant": {
"name": "cyberdyne",
"companyName": "Cyberdyne Systems Corp.",
"type": "PRODUCTION",
"url": "cyberdyne.m5server.com”
"deleted": false,
"disabled": false,
"master": false
}
}
List All Existing Tenants
Send an HTTP GET to the tenants resource to see information about all tenants.
Access Level
l
Desktop Administrator
HTTP Method
GET
URL
/api/tenants
Expected Response
HTTP 200
Response JSON
[ {
"tenant": {
"name": "cyberdyne",
"companyName": "Cyberdyne Systems Corp.",
"type": "PRODUCTION",
"url": "cyberdyne.m5server.com”
"deleted": false,
"disabled": false,
"master": false
}
} ]
Desktop Workspace 4.2
Advanced Setup Guide
92
Delete a Tenant
Send an HTTP DELETE to the specific tenant resource to delete the tenant.
Requirements
l
An existing tenant identified by <tenantname>
Access Level
l
Desktop Administrator
HTTP Method
DELETE
URL
/api/tenants/<tenantname>
Expected Response
HTTP 200
Disable and Re-enable a Tenant
Send an HTTP PUT to the disabled resource of a tenant to disable that tenant. An optional “reason” query
parameter can be added to request.
Requirements
l
An existing tenant identified by <tenantname>
Access Level
l
Desktop Administrator
HTTP Method
PUT
URL
/api/tenants/<tenantname>/disabled
Request Parameters
“reason”: a string of text
Expected Response
HTTP 200
Send an HTTP DELETE to the disabled resource of a tenant to re-enable that tenant.
Requirements
l
An existing tenant identified by <tenantname>
Access Level
l
Desktop Administrator
HTTP Method
DELETE
URL
/api/tenants/<tenantname>/disabled
Expected Response
HTTP 200
Desktop Workspace 4.2
Advanced Setup Guide
93
For more REST APIs, refer to Desktop Workspace REST APIs,
Part 2.
Desktop Workspace 4.2
Advanced Setup Guide
94
Desktop Workspace REST APIs, Part 2
- Integrating Desktop Workspace with a Self-Service Portal
- Managing Desktop Workspace with a Service Desk
- Checking Server Status
- Looking Up Version Information
- Troubleshooting Common Errors
This document continues the list of available REST APIs in Desktop Workspace. For information about API
versioning, formatting, and more background, refer to Using REST APIs in Desktop Workspace.
Integrating Desktop Workspace with a SelfService Portal
Logging In as a User
Log in as a user by sending a HTTP GET to the login URL. See the “Authentication and Authorization” section of
this document for further details on how to use this resource.
Requirements
l
None
Access Level
l
User
HTTP
Method
GET
URL
/api/login
Expected
Response
HTTP 200
Response
JSON
{
message: "OK:
}
Other
Information
The response will also contain a JSESSIONID cookie. This cookie can be reused in requests
during the 30 minutes subsequent to the login.
Desktop Workspace 4.2
Advanced Setup Guide
95
Looking Up User Info
View specific information about a user by sending a HTTP GET to the user’s resource.
Requirements
l
A user identified by <userId> who is a member of a domain identified by <domainName>.
Access level
l
User or device administrator
HTTP Method
GET
URL
/api/users/<domainName>/<userId>
Expected Response
HTTP 200
Response JSON
{
"user": {
"userId": "bob",
"domain": "local",
"numTargetedLivepcs": 1,
}
}
Downloading the Windows Player
Download the Desktop Workspace Player for Windows by sending a GET to the player resource.
Requirements
l
A valid Desktop Workspace Client Pack identified by <version> in the Desktop Workspace server.
l
VMWare Fusion support added to the client pack.
Access Level
l
User
HTTP Method
GET
URL
/api/player/<version>/Win
Expected Response
HTTP 303
Response after redirect
HTTP 200 Downloading the Mac Player
Download the Desktop Workspace Player for Mac by sending a GET to the player resource.
Requirements
l
A valid Desktop Workspace Client Pack identified by <version> in the Desktop Workspace server.
l
VMWare Fusion support added to the client pack.
Desktop Workspace 4.2
Advanced Setup Guide
96
Access Level
l
User
HTTP Method
GET
URL
/api/player/<version>/OSX
Expected Response
HTTP 303
Response after redirect
HTTP 200 Downloading the BareMetal ISO
Download the Desktop Workspace BareMetal ISO by sending a GET to the BareMetal resource.
Requirements
l
A valid Desktop Workspace Client Pack identified by <version> in the Desktop Workspace server.
Access Level
l
User
HTTP Method
GET
URL
/api/player/<version>/BAREMETAL
Response
HTTP 303
Managing Desktop Workspace with a
Service Desk
Looking up Subscriptions
View information on a user’s subscriptions by sending a HTTP GET to the subscription resource.
Requirements
l
A user identified by <userId> who is a member of a domain identified by <domainName>.
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/users/<domainName>/<userId>/subscriptions
Desktop Workspace 4.2
Advanced Setup Guide
97
Expected Response
HTTP 200
Response JSON
{
"subscriptions": [
{
"subscriptionId": "<subscrId1>",
"livepcTitle": "FooLivepc",
"livepcVersion": "9.2",
"hostname": "guest.company.com",
"status": "ACTIVE",
"clientStatus": "ACTIVE",
"subscribedAt": 112233445566,
"lastCheckedInAt": 112233445566,
"deviceId": "123",
"deviceCompName": "host.company.com",
"deviceStatus": "ACTIVE"
}
]
}
Revoking/Unrevoking an Active Subscription
Check the status of an active subscription with a GET. Revoke an active subscription with a PUT, and unrevoke
an active subscription by sending a DELETE to the revocation URL. Requirements
l
A non-killed subscription identified by < subscrId1>.
Checking the Subscription Status
Access Level
l
Desktop Administrator or User
HTTP Method
GET
URL
api/subscriptions/<subscrId1>
Expected Response
HTTP 200
Response JSON
{
"subscription": {
"subscriptionId": "<subscrId1>",
"livepcTitle": "FooLivepc",
"livepcVersion": "9.2",
"hostname": "guest.company.com",
"status": "ACTIVE",
"clientStatus": "ACTIVE",
"subscribedAt": 112233445566,
"lastCheckedInAt": 112233445566,
"deviceId": "123",
"deviceCompName": "host.company.com",
"deviceStatus": "ACTIVE"
}
}
Desktop Workspace 4.2
Advanced Setup Guide
98
Revoking an Active Subscription
Access Level
l
Desktop Administrator or User
HTTP Method
PUT
URL
/api/subscriptions/<subscrId1>/revoked
Response
HTTP 200
First, Check the Subscription Status
Access Level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/subscriptions/<subscrId1>
Response
HTTP 200
Response JSON
{
"subscription": {
"subscriptionId": "<subscrId1>",
"status": "REVOKED"
}
}
Then, Unrevoke the Active Subscription
Access Level
l
Desktop Administrator or User
HTTP Method
DELETE
URL
/api/subscriptions/<subscrId1>/revoked
Response
HTTP 200
Then, Confirm the Subscription Status
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/subscriptions/<subscrId1>
Desktop Workspace 4.2
Advanced Setup Guide
99
Expected response
HTTP 200
Sample response JSON
{
"subscription": {
"subscriptionId": "<subscrId1>",
"status": "ACTIVE"
}
}
Killing an Active Subscription
Kill an active subscription with a PUT, then confirm its new status with a GET.
Requirements
l
A subscription identified by < subscrId1>.
Access level
l
Desktop Administrator or User
HTTP Method
PUT
URL
/api/subscriptions/<subscrId1>/killed
Expected response
HTTP 200
Then, Check the Subscription Status
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/subscriptions/<subscrId1>
Expected response
HTTP 200
Sample response JSON
{
"subscription": {
"subscriptionId": "<subscrId1>",
"status": "KILLED"
}
}
Revoking/Unrevoking a Device
Check the device status by sending a GET to the device URL. To revoke a device, PUT it in a /revoked resource.
To unrevoke a device, send a DELETE method to the revocation URL. Requirements
Desktop Workspace 4.2
Advanced Setup Guide
100
l
A device (Desktop Workspace Player) identified by < deviceId1>.
First, Check the Device Status
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/devices/<deviceId1>
Expected response
HTTP 200
Sample response JSON
{
"device": {
"deviceId": "<deviceId1>",
"status": "ACTIVE"
}
}
Then, Revoke the Device
Access level
l
Desktop Administrator or User
HTTP Method
PUT
URL
/api/devices/<deviceId1>/revoked
Expected response
HTTP 200
Then, Confirm the Device Status
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/devices/<deviceId1>
Expected response
HTTP 200
Sample response JSON
{
"device": {
"subscriptionId": "<deviceId1>",
"status": "REVOKED"
}
}
Or, Unrevoke the Device
Access level
Desktop Workspace 4.2
Advanced Setup Guide
101
l
Desktop Administrator
HTTP Method
DELETE
URL
/api/devices/<deviceId1>/revoked
Expected response
HTTP 200
Then, Check the Device Status
Access level
l
Desktop Administrator or User
HTTP Method
GET
URL
/api/devices/<deviceId1>
Expected response
HTTP 200
Sample response JSON
{
"device": {
"subscriptionId": "<deviceId1>",
"status": "ACTIVE"
}
}
Killing an Active Device
To kill an active device, PUT the device in a /killed resource. If this action is successful, a GET returns a status
of “Killed.”
Requirements
l
A device (Desktop Workspace Player) identified by < deviceId1>.
Killing the Device
HTTP Method
PUT
URL
/api/devices/<deviceId1>/killed
Expected response
HTTP 200
Then, Check the Device Status
HTTP Method
GET
URL
/api/devices/<deviceId1>
Expected response
HTTP 200
Desktop Workspace 4.2
Advanced Setup Guide
102
Sample response JSON
{
"device": { "deviceId": "<deviceId1>",
"status": "KILLED"
}
}
Checking Server Status
Check whether or not the server is up with an unauthenticated GET.
HTTP Method
Unauthenticated GET
URL
/api/status
Expected response
HTTP 200
Sample response JSON
{
"message": "OK"
}
Looking Up Version Information
Look up your version with a GET method.
HTTP Method
GET
URL
/api/version
Expected response
HTTP 200
Sample response JSON
{
"min": 1,
"max": 1,
"current": 1,
"buildVersion": "4.1.0.195"
}
Troubleshooting Common Errors
Looking Up Subscriptions for a User that Does Not
Exist
Requirements
l
An invalid user (e.g. “susan” in the “local” domain).
Desktop Workspace 4.2
Advanced Setup Guide
103
HTTP Method
URL
Expected response
Sample response JSON
GET
/api/users/local/susan/subscriptions
HTTP 404
{ "message": "User not found with id [local\\susan]" }
Looking Up Devices for a User that Does Not Exist
If you try to look up devices assigned to a user that does not exist, the system returns a 404 error.
Requirements
l
An invalid user (e.g. “susan” in the “local” domain).
HTTP Method
GET
URL
/api/users/local/susan/devices
Expected response
HTTP 404
Sample response JSON
{ "message": "User not found with id [local\\susan]" }
Revoking or Unrevoking A Subscription that Does
Not Exist
If you try to revoke or unrevoke a subscription that does not exist, the system returns a 404 error.
Requirements
l
An invalid subscription (e.g. “123”).
Revoking a Subscription that Does Not Exist
HTTP method
PUT
URL
/api/subscriptions/123/revoked
Expected response
HTTP 404
Sample response JSON
{ "message": "Subscription not found with id [123]" }
Unrevoking a Subscription that Does Not Exist
HTTP Method
DELETE
URL
/api/subscriptions/123/revoked
Expected response
HTTP 404
Sample response JSON
{ "message": "Subscription not found with id [123]" }
Desktop Workspace 4.2
Advanced Setup Guide
104
Revoking or Unrevoking a Subscription that has
Been Killed
Once a subscription is killed, attempts to revoke or unrevoked it will fail. When you try to revoke or unrevoke a
killed subscription, the system returns a 400 error.
Requirements
l
A subscription that has been killed (e.g. “123”).
Revoking a Killed Subscription
HTTP Method
PUT
URL
/api/subscriptions/123/revoked
Expected response
HTTP 400
Unrevoking a Killed Subscription
HTTP Method
DELETE
URL
/api/subscriptions/123/revoked
Expected response
HTTP 400
Killing a Device Subscription that Does Not Exist
When you try to kill a device subscription that does not exist, the system returns a 404 error.
Requirements
l
An invalid subscription (e.g. “123”).
HTTP Method
PUT
URL
/api/subscriptions/123/killed
Expected response
HTTP 404
Sample response JSON
{ "message": "Subscription not found with id [123]" }
Revoking or Unrevoking a Device that Does Not Exist
When you try to revoke, unrevoke, or delete a device that does not exist, the system returns a 404 error. Requirements
l
A device that does not exist (e.g. “123”).
Desktop Workspace 4.2
Advanced Setup Guide
105
Revoking a Device that Does Not Exist
HTTP Method
PUT
URL
/api/devices/123/revoked
Expected response
HTTP 404
Sample response JSON
{ "message": "Device not found with id [123]" }
Unrevoking a Device that Does Not Exist
HTTP Method
DELETE
URL
/api/devices/123/revoked
Expected response
HTTP 404
Sample response JSON
{ "message": "Device not found with id [123]" }
Revoking or Unrevoking a Device That Has Been
Killed
Once a device is killed, attempts to revoke or unrevoked it will fail When you try to revoke or unrevoke a killed
device, the system returns a 400 error.
Requirements
l
A device that has been killed (e.g. “123”).
Revoking a Killed Device
HTTP Method
PUT
URL
/api/devices/123/revoked
Expected response
HTTP 400
Unrevoking a Killed Device
HTTP Method
DELETE
URL
/api/devices/123/revoked
Expected response
HTTP 400
Killing a Device That Does Not Exist
If you try to kill a device that does not exist, the system returns a 404 error.
Requirements
Desktop Workspace 4.2
Advanced Setup Guide
106
l
A device that does not exist (e.g. “123”).
HTTP Method
PUT
URL
/api/devices/123/killed
Expected response
HTTP 404
Sample response JSON
{ "message": "Device not found with id [123]" }
Desktop Workspace 4.2
Advanced Setup Guide
107
Identifying the MAC Addresses of Host
Computers From the Management
Server
Administrators can verify the host MAC address reported to the Management Server for security and
auditing purposes.
For more information, please refer to the Dell Knowledge Base.
Desktop Workspace 4.2
Advanced Setup Guide
108
About Dell Software
Dell listens to customers and delivers worldwide innovative technology, business solutions and services they
trust and value. For more information, visit www.software.dell.com.
Contacting Dell Software
Technical Support:
Online Support
Product Questions and Sales:
(800) 306-9329
Email:
info@software.dell.com
Technical Support Resources
Technical support is available to customers who have purchased Dell software with a valid maintenance
contract and to customers who have trial versions. To access the Support Portal, go to
http://software.dell.com/support/.
The Support Portal provides self-help tools you can use to solve problems quickly and independently, 24 hours
a day, 365 days a year. In addition, the portal provides direct access to product support engineers through an
online Service Request system.
The site enables you to:
l
Create, update, and manage Service Requests (cases)
l
View Knowledge Base articles
l
Obtain product notifications
l
Download software. For trial software, go to Trial Downloads.
l
View how-to videos
l
Engage in community discussions
l
Chat with a support engineer
Desktop Workspace 4.2
Advanced Setup Guide
109