By Mark Benson, Senior Architect and Senior Staff Engineer, End-User-Computing CTO Office, VMware
Introduction
In September 2015, I posted A Technical Introduction to Access Point for Secure Remote Access article. Access Point is a VMware virtual appliance which is used with VMware Horizon (View) and Horizon Air (DaaS). In that article I mentioned the ability to perform a scripted deployment of an Access Point virtual appliance using VMware OVF Tool in order to perform a repeatable deployment where all settings can be applied in a way that allows Access Point to be production ready on first boot. This procedure is described in the document Deploying and Configuring Access Point 2.0.
Whilst it is great to be able to specify all configuration settings in one go at deployment time, the downside of this is that the OVF Tool command line can become very long and complex. It is also easy to introduce errors on the command line as the command syntax for OVF Tool used in this way can be difficult to get right. Also, it is not possible to validate the settings with OVF Tool and it is therefore very easy to make configuration errors such as setting an admin REST API password that doesn't meet the required complexity rules.
Many Windows administrators managing a VMware Horizon environment need a much simpler way to deploy Access Point in a secure, reliable and repeatable way and to have complete control over the settings. For these reasons, we have developed a sample PowerShell script that can be used to deploy Access Point and which overcomes the main difficulties of using OVF Tool directly on the command line. As this PowerShell script is delivered as a sample script, you can also adapt it as required for your specific needs although in most cases you won't need to modify it at all. The script calls the OVF Tool command but validates the settings and automatically constructs the correct command line syntax. The settings are taken from a simple .INI file. This script runs OVF Tool in a fully supported way for Access Point according the procedure in the document Deploying and Configuring Access Point 2.0. Note that no password values or private key values are stored within the .INI configuration files.
The PowerShell script sets all configuration settings for OVF Tool at deployment time. This includes setting up the CA issued SSL Server certificate and all other possible settings. After Access Point has been deployed by this script, there is no need to make configuration changes after deployment. Access Point will be ready for production use on first boot.
What are the requirements for deploying Access Point appliances using this script?
- For Access Point itself, a vSphere ESX host with a vCenter Server is needed. Decide on the vSphere datastore to be used and the Network name to be used. A vSphere Network Protocol Profile must be associated with every referenced network name. This Network Protocol Profile specifies network settings such as IPv4 subnet mask, gateway etc. The deployment of Access Point uses these values so make sure the values are correct.
- The PowerShell script runs on a machine running Windows 8.1 (or newer) or Windows Server 2008 R2 (or newer). This can be the vCenter Server itself if it is running on Windows, or can be a separate Windows machine.
- The Windows machine running the script must also have the VMware OVF Tool command installed. Install OVF Tool 4.0.1 or newer. You can download it from here OVF Tool Software and Documentation.
How do I run the script?
- Download a version 2.0.1 Access Point virtual appliance image from VMware onto your Windows machine. This is an OVA file. e.g. euc-access-point-2.0.1.0-3084879_OVF10.ova.
- Download the apdeploy-201-v1.zip file attached below and extract the files into a folder on your Windows machine.
- On your Windows machine, open a PowerShell console and change directory to the location of your script.
- Create a .INI configuration file for your Access Point virtual appliance. In this example, I am going deploy a new Access Point appliance called AP1. I have created a .INI file called ap1.ini which contains all the configuration settings for AP1. You can use the sample .INI files contained within the apdeploy-201-v1.zip file to create your .INI file and then modify the settings to the values you want.
- Make sure script execution is unrestricted for the current user. You can do this by running the command:
set-executionpolicy -scope currentuser unrestricted
You only need to run this once and only if it is currently restricted.
If you get a warning about running this scrip, you can unblock that warning by running the command:
unblock-file -path .\apdeploy.ps1 - Run the command .\apdeploy.ps1 -iniFile ap1.ini as shown in the screenshot below. If you don't specify the -iniFile option, the script will default to ap.ini. You will be prompted to set a root password for the appliance and an optional password for the admin REST API. You will also be prompted for the vCenter password. Deployment takes around a minute depending on your host and storage performance. If you are prompted to add the fingerprint for the target machine, enter yes.
- When the script completes, the Access Point appliance is ready to use. No further configuration steps are required.
.INI File Contents
The apdeploy-201-v1.zip file attached at the bottom of this post contains two example .INI files. ap1-basic.ini is a minimal .INI file which just contains the minimum settings needed. ap2-advanced.ini is a more complex configuration file showing all possible settings available. You should start with just a basic .INI file to ensure that this deployment method works in your environment. You can then add more advanced settings in your .INI file and repeat the deployment. If you have already deployed the named Access Point appliance, then running the script again will power off the appliance, delete it, and will redeploy it with the current .INI settings. This is a useful capability to use when either upgrading the appliance to a newer version, or just to change any of the settings.
Basic .INI File Example
##############################################
[General]
name=AP1
source=C:\APs\euc-access-point-2.0.1.0-3084879_OVF10.ova
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/esx1.myco.int
ds=Local Disk 1
netInternet=VM Network
netManagementNetwork=VM Network
netBackendNetwork=VM Network
[Horizon]
proxyDestinationUrl=https://192.168.0.209
##############################################
The following table describes each configuration setting. These must be arranged in the .INI file under the appropriate Group Name shown in the first column and as shown in the sample .INI files.
Configuration Settings
| Group Name | Value | Example | Description |
|---|---|---|---|
| [General] | deploymentOption | deploymentOption=onenic | Access Point can be created with either one, two or three network interface cards (NICs). Either specify onenic, twonic or threenic. The default is onenic. |
| dns | dns=192.168.0.1 | Optional DNS server address. Default is none. | |
| ds | ds=Local Disk 1 | Datastore name which the appliance will be deployed to. | |
| name | name=AP1 | Name of the virtual appliance as shown in vCenter. It must be between 1 and 32 characters long. If name is omitted, the PowerShell script will prompt for it. | |
| netInternet | netInternet=VM Network | The name of the vSphere Network for the Access Point primary network | |
| netManagementNetwork | netManagementNetwork=VM Network | The name of the vSphere Network for the Access Point management interface network. | |
| netBackendNetwork | netBackendNetwork=VM Network | The name of the vSphere Network for the Access Point backend network. | |
| source | source=C:\Users\admin\My Images\euc-access-point-2.0.1.0-3084879_OVF10.ova | Full path filename of the Access Point .ova virtual machine image. The file can be downloaded from VMware. | |
| syslogUrl | syslogUrl=syslog://server.example.com:514 | Optional syslog server URL. This allows syslog events to be forward to a syslog management server. | |
| target | target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/esx1.myco.int | Specifies the vCenter Server information and target ESX host. Refer to the OVF Tool documentation for details of the syntax of target. PASSWORD in upper case is not the actual vCenter password but is a special term used to make OVF Tool prompt the user for the actual vCenter password value. The prompt will appear during execution of the PowerShell script. This avoids the need to store real password values in this .ini file. Note that target must reference a vCenter host. Deploying direct to a vSphere host is not supported. In this example, 192.168.0.21 is the IP address of the vCenter host and administrator@vsphere.local is the vCenter administrator username. | |
| [Horizon] | blastExternalUrl | blastExternalUrl=https://ap1.horizon.myco.com:8443 | URL used by HTML Access Clients to connect to this Access Point appliance. |
| pcoipExternalUrl | pcoipExtenalUrl=10.20.30.40:4172 | URL used by Horizon Clients to connect using PCoIP to this Access Point appliance. This must include a valid IPv4 address. | |
| proxyDestinationUrl | proxyDestinationUrl=https://cs1.view.myorg.int | URL representing the Horizon backend server such as an individual View Connection Server or a load balnced alias URL representing a group of View Connection Servers. | |
| proxyDestinationUrlThumbprints | proxyDestinationUrlThumbprints=sha1:3e ef ed c6 86 75 a6 15 ff c8 96 27 5a 4c ee 8e 16 fd 6e d3 | An optional comma separated list of certificate thumbprints of the certificates on each backend View Connection Server. If the Horizon View environment is using trusted CA signed certificates, this setting can be ignored. For self signed or otherwise untrusted certificates enter the thumbprint values preceded by sha1:. | |
| tunnelExternalUrl | tunnelExternalUrl=https://ap1.horizon.myco.com:443 | URL used by Horizon Clients to connect the secure tunnel to this Access Point appliance. | |
| [SSLCert] | pemCerts | pemCerts=C:\Users\admin\My Certs\mycaservercert.pem | Optional SSL Server certificate filename. This should reference a .PEM format file containing the SSL Server certificate to be deployed onto Access Point. The PEM file should contain the SSL Server certifacte and any intermediate and root certificates. If this is omitted, Access Point will generate a self-signed SSL server certificate instead. |
| pemPrivKey | pemPrivKey=C:\Users\admin\My Certs\mycacertrsakey.pem | Filename of the .PEM file containg the RSA private key for the SSL server certificate referenced in pemCerts above. If pemCerts is specified, then pemPrivKey must also be specified. |
Managing SSL Server Certificate Files
pemCerts and pemPrivKey configuration items in the [SSLCert] section of the .INI file reference the SSL certificates file and the RSA private key file both in PEM format. If you don't specify pemCerts and pemPrivKey, Access Point will instead generate a self-signed SSL server certificate. This self-signed certificate will not be trusted by Horizon Clients and therefore users will receive a warning when connecting via Access Point.
For production environments, it is best to obtain an SSL server certificate for use on each Access Point appliance. If you have the PEM format files for the SSL server certificate (including any intermediate CA certificates and root CA certificate) you can reference the files in the pemCerts and pemPrivKey values as described above.
You may have a certificate file with private key and certificate trust chain all in one PKCS#12 format file with either a .p12 or .pfx file extension. To use this file with Access Point you must first convert the PKCS#12 format file into the two PEM format files. You can do this with openssl by running the following example openssl commands which start with a PKCS#12 file called mycaservercert.pfx.
openssl pkcs12 -in mycaservercert.pfx -nokeys -out mycaservercert.pem
openssl pkcs12 -in mycaservercert.pfx -nodes -nocerts -out mycaservercertkey.pem
openssl rsa -in mycaservercertkey.pem -check -out mycaservercertkeyrsa.pem
Edit mycaservercert.pem and remove any unnecessary certificate entries. It should contain the one SSL server certificate followed by any necessary intermediate CA certificates and root CA certificate.
In the .INI file, add the following lines.
[SSLCert]
pemCerts=mycaservercert.pem
pemPrivKey=mycaservercertkeyrsa.pem
When the script is run, these certificates and private key will be automatically deployed to the new Access Point appliance. The private key PEM file should be deleted from the Windows machine once Access Point has been deployed.
Occasionally, there can be a problem with the Access Point software starting up when a new SSL server certificate file is applied. If this happens, then log in to the console of Access Point as root with the root password specified, and run the following commands.
supervisorctl stop esmanager
supervisorctl start esmanager
Troubleshooting Deployment Problems
1. I get a security warning about running scripts downloaded from the Internet
Verify that the PowerShell script is the script you intend to run, and then from the PowerShell console, run the command:
unblock-file .\apdeploy.ps1
2. I get an error saying "ovftool command not found".
Make sure you have installed the OVF Tool software on your Windows machine and that it is installed in the location expected by the script. OVF Tool Download.
3. I get an error saying "Invalid Network in property netmask1"
The message may state netmask0, netmask1 or netmask2, Check that a value has been set in the .INI file for each of the three networks (netInternet, netManagementNetwork and netBackendNetwork),Also check that a vSphere Network Protocol Profile has been associated with every referenced network name. This specifies network settings such as IPv4 subnet mask, gateway etc. so make sure the associated Network Protocol Profile has correct values for each of the settings.
If you have any questions about this PowerShell script leave a comment below. For any questions on Access Point itself, post a message on the discussion section of the Horizon community forum.