Certificates for Workload Balancing
This section provides information about two optional tasks for securing certificates:
Configuring Citrix Hypervisor to verify a certificate from a Trusted Authority
Configuring Citrix Hypervisor to verify the default Citrix WLB self-signed certificate
Citrix Hypervisor and Workload Balancing communicate over HTTPS. Consequently during Workload Balancing Configuration, the wizard automatically creates a self-signed test certificate. This self-signed test certificate lets Workload Balancing establish an TLS connection to Citrix Hypervisor.
The self-signed certificate is a placeholder to facilitate HTTPS communication and is not from a trusted certificate authority. For added security, we recommend using a certificate signed from a trusted certificate authority.
By default, Workload Balancing creates this TLS connection with Citrix Hypervisor automatically. You do not need to perform any certificate configurations during or after configuration for Workload Balancing to create this TLS connection.
However, to use a certificate from another certificate authority, such as a signed one from a commercial authority, you must configure Workload Balancing and Citrix Hypervisor to use it.
Regardless of what certificate Workload Balancing uses, by default, Citrix Hypervisor does not validate the identity of the certificate before it establishes connection to Workload Balancing. To configure Citrix Hypervisor to check for a specific certificate, you must export the root certificate that was used to sign the certificate, copy it to Citrix Hypervisor, and configure Citrix Hypervisor to check for it when a connection to Workload Balancing is made. In this scenario, Citrix Hypervisor acts as the client and Workload Balancing acts as the server.
Depending on your security goals, you can either:
Configure Citrix Hypervisor to verify the self-signed test certificate. See Configure Citrix Hypervisorto Verify the Self-Signed Certificate.
Configure Citrix Hypervisor to verify a certificate from a trusted certificate authority. See Configure Citrix Hypervisorto Verify a Certificate-authority Certificate.
Configure Citrix Hypervisor to verify the self-signed certificate
You can configure Citrix Hypervisor to verify that the Citrix WLB self-signed certificate is authentic before Citrix Hypervisor permits Workload Balancing to connect.
To verify the Citrix WLB self-signed certificate, you must connect to Workload Balancing using its host name. To find the Workload Balancing host name, run
hostnamecommand on the virtual appliance.
If you want to configure Workload Balancing to verify the Citrix WLB self-signed certificate, perform the steps in the procedure that follows.
To configure Citrix Hypervisorto verify the self-signed certificate:
Copy the self-signed certificate from the Workload Balancing virtual appliance to the pool master. The Citrix WLB self-signed certificate is stored at /etc/ssl/certs/server.pem. Run the following on the pool master to copy the certificate:
scp root@wlb-ip:/etc/ssl/certs/server.pem .
If you receive a message stating that the authenticity of
wlb-ipcannot be established, type
Enter Workload Balancing virtual appliance root password when prompted, the certificate will be copied to current directory.
Install the certificate. Run the
pool-certificate-installcommand from the directory where you copied the certificate. For example:
xe pool-certificate-install filename=server.pem
Verify the certificate was installed correctly by running the
pool-certificate-listcommand on the pool master:
If you installed the certificate correctly, the output of this command includes the exported root certificate (for example, server.pem). Running this command lists all installed TLS certificates, including the certificate you just installed.
Synchronize the certificate from the master to all hosts in the pool by running the
pool-certificate-synccommand on the pool master:
pool-certificate-synccommand on the master synchronizes the certificate and certificate revocation lists on all the pool servers with the master. This ensures all hosts in the pool use the same certificates.
There is no output from this command. However, the next step does not work if this one did not work successfully.
Instruct Citrix Hypervisor to verify the certificate before connecting to the Workload Balancing virtual appliance. Run the following command on the pool master:
xe pool-param-set wlb-verify-cert=true uuid=uuid_of_pool
Pressing the Tab key automatically populates the UUID of the pool.
(Optional) To verify this procedure worked successfully, perform the following steps:
To test if the certificate synchronized to the other hosts in pool, run the
pool-certificate-listcommand on those hosts.
To test if Citrix Hypervisor was set to verify the certificate, run the
pool-param-getcommand with the
param-name=wlb-verify-cert parameter. For example:
xe pool-param-get param-name=wlb-verify-cert uuid=uuid_of_pool
Configure Citrix Hypervisor to verify a certificate-authority certificate
You can configure Citrix Hypervisor to verify a certificate signed by a trusted certificate authority.
For trusted authority certificates, Citrix Hypervisor requires an exported certificate or certificate chain (the intermediate and root certificates) in .pem format that contains the public key.
If you want Workload Balancing to use a trusted authority certificate, do the following:
Obtain a signed certificate from the certificate authority. See Task 1: Obtaining a certificate-authority certificate.
Follow the instructions in Task 2: Specifying the New Certificate to specify and apply the new certificate.
Install the obtained certificates and enable certificate verification on the pool master. See Task 3: Importing the Certificate Chain into the Pool.
Before beginning these tasks, ensure:
You know the IP address for the Citrix Hypervisor pool master.
Citrix Hypervisor can resolve the Workload Balancing host name. (For example, you can try pinging the Workload Balancing FQDN from the Citrix Hypervisor console for the pool master.)
If you want to use an IP address to connect to Workload Balancing, you must specify that IP address as the Subject Alternative Name (SAN) when you create the certificate.
Task 1: Obtaining a certificate-authority certificate
To obtain a certificate from a certificate authority, you must generate a Certificate Signing Request (CSR). Generating a CSR for the Workload Balancing virtual appliance is two-task process. You must (1) create a private key and (2) use that private key to generate the CSR. You must perform both of these procedures on the Workload Balancing virtual appliance.
Guidelines for specifying the Common Name
The Common Name (CN) you specify when creating a CSR must exactly match the FQDN of your Workload Balancing virtual appliance and the FQDN or IP address you specified in the Address box in the Connect to WLB Server dialog box.
To ensure the name matches, specify the Common Name using one of these guidelines:
Specify the same information for the certificate’s Common Name as you specified in the Connect to WLB Server dialog. For example, if your Workload Balancing virtual appliance is named
wlb-vpx.yourdomainin the Connect to WLB Server and provide
wlb-vpx.yourdomainas the Common Name when creating the CSR.
If you connected your pool to Workload Balancing using an IP address, use the FQDN as the Common Name and specify the IP address as a Subject Alternative Name (SAN). However, this may not work in all situations.
Certificate verification is a security measure designed to prevent unwanted connections. As a result, Workload Balancing certificates must meet strict requirements or the certificate verification will not succeed and Citrix Hypervisor will not allow the connection. Likewise, for certificate verification to succeed, you must store the certificates in the specific locations in which Citrix Hypervisor expects to find the certificates.
To create a private key file:
Create a private key file:
openssl genrsa -des3 -out privatekey.pem 2048
Remove the password:
openssl rsa -in privatekey.pem -out privatekey.nop.pem
If you enter the password incorrectly or inconsistently, you may receive some messages indicating that there is a user interface error. You can ignore the message and just rerun the command to create the private key file.
To generate the CSR:
Generate the CSR:
Create the CSR using the private key:
openssl req -new -key privatekey.nop.pem -out csr
Follow the prompts to provide the information necessary to generate the CSR:
Country Name. Enter the TLS Certificate country codes for your country. For example, CA for Canada or JM for Jamaica. You can find a list of TLS Certificate country codes on the web.
State or Province Name (full name). Enter the state or province where the pool is located. For example, Massachusetts or Alberta.
Locality Name. The name of the city where the pool is located.
Organization Name. The name of your company or organization.
Organizational Unit Name. Enter the department name. This field is optional.
Common Name. Enter the FQDN of your Workload Balancing server. This must match the name the pool uses to connect to Workload Balancing.
Email Address. This email address is included in the certificate when you generate it.
Provide optional attributes or click Enter to skip providing this information.
The CSR request is saved in the current directory and is named
Display the CSR in the console window by running the following commands in the Workload Balancing appliance console:
Copy the entire Certificate Request and use the CSR to request the certificate from the certificate authority.
Task 2: Specifying the new certificate
Use this procedure to specify Workload Balancing use a certificate from a certificate authority. This procedure installs the root and (if available) intermediate certificates.
To specify a new certificate:
Download the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority.
If you did not download the certificates to the Workload Balancing virtual appliance. Do one of the following:
- If you are copying the certificates from a Windows computer to the Workload Balancing appliance, use WinSCP or another copying utility, to copy the files.
For the host name, you can enter the IP address and leave the port at the default. The user name and password are typically root and whatever password you set during configuration.
If you are copying the certificates from a Linux computer to the Workload Balancing appliance, use SCP or another copying utility, to copy the files to the directory of your choice on the Workload Balancing appliance. For example:
scp root_ca.pem root@wlb-ip:/path_on_your_WLB
On the Workload Balancing virtual appliance, merge contents of all the certificates (root certificate, intermediate certificate (if it exists), and signed certificate) into one file. For example:
cat signed_cert.pem intermediate_ca.pem root_ca.pem > server.pem
Rename the existing certificate and key using the move command:
mv /etc/ssl/certs/server.pem /etc/ssl/certs/server.pem_orig mv /etc/ssl/certs/server.key /etc/ssl/certs/server.key_orig
Copy the merged certificate:
mv server.pem /etc/ssl/certs/server.pem
Copy the private key created previously:
mv privatekey.nop.pem /etc/ssl/certs/server.key
Make the private key readable only by root. Use
chmodcommand to fix permissions.
chmod 600 /etc/ssl/certs/server.key
killall stunnel stunnel
Task 3: Importing the certificate chain into the pool
After obtaining certificates, you must import (install) the certificates onto the Citrix Hypervisor pool master and synchronize the hosts in the pool to use those certificates. Then, you can configure Citrix Hypervisor to check the certificate’s identity and validity each time Workload Balancing connects to a host.
Copy the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority onto the Citrix Hypervisor pool master.
Install the root certificate on the pool master:
xe pool-certificate-install filename=root_ca.pem
If applicable, install the intermediate certificate on the pool master:
xe pool-certificate-install filename=intermediate_ca.pem
Verify both the certificates installed correctly by running this command on the pool master:
Running this command lists all installed TLS certificates. If the certificates installed successfully, they appear in this list.
Synchronize the certificate on the pool master to all hosts in the pool:
pool-certificate-synccommand on the master synchronizes the certificates and certificate revocation lists on all the pool servers with the pool master. This ensures all hosts in the pool use the same certificates.
Instruct Citrix Hypervisor to verify a certificate before connecting to the Workload Balancing virtual appliance. Run the following command on the pool master:
xe pool-param-set wlb-verify-cert=true uuid=uuid_of_pool
Pressing the Tab key automatically populates the UUID of the pool.
If, before you enabled certificate verification, you specified an IP address in the Connect to WLB dialog, you may be prompted to reconnect the pool to Workload Balancing.
In this case, specify the FQDN for the Workload Balancing appliance in the Address box in the Connect to WLB dialog exactly as it appears in the certificate’s Common Name (CN). (You must enter the FQDN since the Common Name and the name that Citrix Hypervisor uses to connect must match.)
If, after configuring certificate verification, the pool cannot connect to Workload Balancing, check to see if the pool can connect if you turn certificate verification off (by running
xe pool-param-set wlb-verify-cert=false uuid=uuid_of_pool). If it can connect with verification off, the issue is in your certificate configuration. If it cannot connect, the issue is in either your Workload Balancing credentials or your network connection.
Some commercial certificate authorities provide tools to verify the certificate installed correctly. Consider running these tools if these procedures fail to help isolate the issue. If these tools require specifying an TLS port, specify port 8012 or whatever port you set during Workload Balancing Configuration.
If, after following these procedures, an error message appears on the WLB tab stating, “There was an error connecting to the WLB server,” there may be a conflict between the Common Name in the certificate and the name of the Workload Balancing virtual appliance. The Workload Balancing virtual-appliance name and the Common Name of the certificate must match exactly.