Configure Certificates for Workload Balancing

This section provides information about two optional tasks for securing certificates:

  • Configuring XenServer to verify a certificate from a Trusted Authority

  • Configuring XenServer to verify the default Citrix WLB self-signed certificate

Overview

XenServer 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 SSL connection to XenServer.

Note:

The self-signed certificate is a placeholder to facilitate HTTPS communication and is not from a trusted certificate authority. For added security, Citrix recommends using a certificate signed from a trusted certificate authority.

By default, Workload Balancing creates this SSL connection with XenServer automatically. You do not need to perform any certificate configurations during or after configuration for Workload Balancing to create this SSL 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 XenServer to use it.

Regardless of what certificate Workload Balancing uses, by default, XenServer does not validate the identity of the certificate before it establishes connection to Workload Balancing. To configure XenServer to check for a specific certificate, you must export the root certificate that was used to sign the certificate, copy it to XenServer, and configure XenServer to check for it when a connection to Workload Balancing is made. In this scenario, XenServer acts as the client and Workload Balancing acts as the server.

 This illustration shows how XenServer verifies that a specific certificate is present before it lets the Workload Balancing virtual appliance establish a connection to it over SSL. In this case, the real certificate (the certificate with the private key) is on the Workload Balancing server and the certificate that was used to sign it, is on the XenServer pool master.

Depending on your security goals, you can either:

Configure XenServer to verify the self-signed certificate

You can configure XenServer to verify that the Citrix WLB self-signed certificate is authentic before XenServer permits Workload Balancing to connect.

Important:

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 hostname command 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 XenServerto verify the self-signed certificate:

  1. 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 .
    
  2. If you receive a message stating that the authenticity of wlb-ip cannot be established, type yes to continue.

  3. Enter Workload Balancing virtual appliance root password when prompted, the certificate will be copied to current directory.

  4. Install the certificate. Run the pool-certificate-install command from the directory where you copied the certificate. For example:

    xe pool-certificate-install filename=server.pem
    
  5. Verify the certificate was installed correctly by running the pool-certificate-list command on the pool master:

    xe pool-certificate-list
    

    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 SSL certificates, including the certificate you just installed.

  6. Synchronize the certificate from the master to all hosts in the pool by running the pool-certificate-sync command on the pool master:

    xe pool-certificate-sync
    

    Running the pool-certificate-sync command 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.

  7. Instruct XenServer 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
    

    Tip:

    Pressing the Tab key automatically populates the UUID of the pool.

  8. (Optional) To verify this procedure worked successfully, perform the following steps:

    1. To test if the certificate synchronized to the other hosts in pool, run the pool-certificate-list command on those hosts.

    2. To test if XenServer was set to verify the certificate, run the pool-param-get command with the param-name=wlb-verify-cert parameter. For example:

      xe pool-param-get param-name=wlb-verify-cert uuid=uuid_of_pool
      

Configure XenServer to verify a certificate-authority certificate

You can configure XenServer to verify a certificate signed by a trusted certificate authority.

For trusted authority certificates, XenServer 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:

  1. Obtain a signed certificate from the certificate authority. See Task 1: Obtaining a certificate-authority certificate.

  2. Follow the instructions in Task 2: Specifying the New Certificate to specify and apply the new certificate.

  3. 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 XenServer pool master.

  • XenServer can resolve the Workload Balancing host name. (For example, you can try pinging the Workload Balancing FQDN from the XenServer console for the pool master.)

Important:

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.yourdomain, specify wlb-vpx.yourdomain in the Connect to WLB Server and provide wlb-vpx.yourdomain as 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.

Note:

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 XenServer will not allow the connection. Likewise, for certificate verification to succeed, you must store the certificates in the specific locations in which XenServer expects to find the certificates.

To create a private key file:

  1. Create a private key file:

    openssl genrsa -des3 -out privatekey.pem 2048
    
  2. Remove the password:

    openssl rsa -in privatekey.pem -out privatekey.nop.pem
    

Note:

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:

  1. Generate the CSR:

    1. Create the CSR using the private key:

      openssl req -new -key privatekey.nop.pem -out csr
      
    2. Follow the prompts to provide the information necessary to generate the CSR:

      Country Name. Enter the SSL Certificate country codes for your country. For example, CA for Canada or JM for Jamaica. You can find a list of SSL 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.

    3. Provide optional attributes or click Enter to skip providing this information.

      The CSR request is saved in the current directory and is named csr.

  2. Display the CSR in the console window by running the following commands in the Workload Balancing appliance console:

    cat csr
    
  3. 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:

  1. Download the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority.

  2. If you did not download the certificates to the Workload Balancing virtual appliance. Do one of the following:

    1. 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.

    1. 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
      
  3. 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
    
  4. 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
    
  5. Copy the merged certificate:

    mv server.pem /etc/ssl/certs/server.pem
    
  6. Copy the private key created previously:

    mv privatekey.nop.pem /etc/ssl/certs/server.key
    
  7. Make the private key readable only by root. Use chmod command to fix permissions.

    chmod 600 /etc/ssl/certs/server.key
    
  8. Restart stunnel:

    killall stunnel
    stunnel
    

Task 3: Importing the certificate chain into the pool

After obtaining certificates, you must import (install) the certificates onto the XenServer pool master and synchronize the hosts in the pool to use those certificates. Then, you can configure XenServer to check the certificate’s identity and validity each time Workload Balancing connects to a host.

  1. Copy the signed certificate, root certificate and, if the certificate authority has one, the intermediate certificate from the certificate authority onto the XenServer pool master.

  2. Install the root certificate on the pool master:

    xe pool-certificate-install filename=root_ca.pem
    
  3. If applicable, install the intermediate certificate on the pool master:

    xe pool-certificate-install filename=intermediate_ca.pem
    
  4. Verify both the certificates installed correctly by running this command on the pool master:

    xe pool-certificate-list
    

    Running this command lists all installed SSL certificates. If the certificates installed successfully, they appear in this list.

  5. Synchronize the certificate on the pool master to all hosts in the pool:

    xe pool-certificate-sync
    

    Running the pool-certificate-sync command 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.

  6. Instruct XenServer 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
    

    Tip:

    Pressing the Tab key automatically populates the UUID of the pool.

  7. 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 XenServer uses to connect must match.)

Troubleshooting tips

  • 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=true 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 SSL 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.

Configure Certificates for Workload Balancing