Introduction This is a step-by-step guide to installing and configuring the Microsoft Hyper-V version of the Citrix NetScaler VPX Expr...
Introduction
This is a step-by-step guide to installing and configuring the Microsoft Hyper-V version of the Citrix NetScaler VPX Express gateway version 10.5-57.7. Citrix (or more accurately XenApp and XenDesktop) is a remote application/remote desktop delivery system.
NetScaler is Citrix's secure gateway that provides a public authentication system for connecting to the backend server. I've installed this myself several times, but it seems each time I forget something so the last time I wrote everything down. I wanted to share so others might avoid my pain. Because this tutorial is a click-by-click tutorial, it will naturally have many steps. Please don't be alarmed by the number of steps, or offended by the level of detail.
Pre-requisites (and assumptions for this tutorial):
* Citrix.com account - free to create and needed to download their software and to register for a free license
* three local static IP addresses for the NetScaler, the gateway, and the subnet
* access to your XenApp or XenDesktop server or familiarity with its settings
* a signed site SSL certificate, an intermediate certificate and a core certificate
* a XenApp storefront server running 7.6
* local domain admin credentials
* local active directory server
* Citrix.com account - free to create and needed to download their software and to register for a free license
* three local static IP addresses for the NetScaler, the gateway, and the subnet
* access to your XenApp or XenDesktop server or familiarity with its settings
* a signed site SSL certificate, an intermediate certificate and a core certificate
* a XenApp storefront server running 7.6
* local domain admin credentials
* local active directory server
Giving credit where credit is due:
RobinHobo has wonderful tutorials on everything citrix related. I have used his tutorials to remind myself of steps. I've found, however, that some of the tutorials on RobinHobo are outdated just enough that it was worth writing my own how-to. Nonetheless, I've linked to RobinHobo below in the References.
RobinHobo has wonderful tutorials on everything citrix related. I have used his tutorials to remind myself of steps. I've found, however, that some of the tutorials on RobinHobo are outdated just enough that it was worth writing my own how-to. Nonetheless, I've linked to RobinHobo below in the References.
Steps (7 total)
You'll find one-stop shopping for both the software and the license generator on their website (link in the references section below). At the bottom of that page there will be drop-downs for each version. Expand the drop-down for 10.5-57.5 and click the download link for the Hyper-V version. A popup will appear asking you to agree to a license. The download will begin when you accept. On that same page, near the bottom of the page there will be a drop-down for license. Within that drop-down you'll find a link to Get License. Clicking that link will cause another agreement pop-up to appear and when you agree, a license will be assigned.
The license is good for 1 year but is free so you can get as many as you need as often as you like. The free license is good for up to 5 simultaneous connections through the gateway and is limited on the amount of bandwidth that can pass through the gateway. If you need more than free will get you, you really should purchase a bigger license. As the Romans used to quip whenever they purchased technology: caveat emptor. Allocation of the license will occur after you have a MAC address for the new VM. For now, click on the license number that was just created to be taken to the allocation page. The first stop is to the Host Name Warning. Ignore this and click the Continue button. You'll notice that Host ID Type is automatically set to MAC Address. You'll need more information to finish the allocation. For now, just leave the browser open to that page and continue with the installation below.
Once you've got the zip file of the hyper-v version of NetScaler vpx 10.5-57.7 and you've got your license, you'll need to get it spun up. Unzip the contents of the zip file to a location accessible to your hyper-v host. On the host, launch hyper-v manager and with the hyper-v server onto which you want this VM launched selected, click the Import Virtual Machine... action on the right side of the manager.
Click next to get to the Locate Folder screen and browse to the location of that folder you just extracted, click to select the folder and click the Select Folder button. Click Next to advance to the Select Virtual Machine screen and you should see the VM already selected but, if it isn't select it. Click Next to advance to the Choose Import Type screen and choose to register the vm in-place. Click Next to see a summary of the actions and then click Finish. Before you start the VM you'll need to associate it with your virtual switch. Select the new NSVPX-HyperV-10.5-57.7 VM and click Settings... from the lower right corner of the Manager. On the settings screen that appears, select the VM-Bus Network Adapter from the list of hardware on the left and then select your virtual switch from the pull-down list on the right. When done, click OK. You are now ready to spin up your VM. With the VM selected, click the Start button on the lower right corner of the Manager. You're spinning like a hangover moments before the earth is destroyed by Vogons.
Now that your VM is up connect to it by clicking the Connect... button in the lower right corner with the VM selected to launch the connection window. When the window appears you will be prompted to enter an IP address. If that prompt is not visible, hit the enter key on your keyboard. At the prompt enter in the first of your three static IP addresses and hit enter. When prompted enter the netmask associated with the static IP and hit enter. Finally, when prompted enter your designated gateway IP address and hit enter. hit 4 to save and quit or 1, 2, or 3 to make a change before saving. The NetScaler will load with the new address settings. When it is done with the startup you will be prompted to login but don't bother. Time to close the Connection window as the rest of the configuration will be done from a web browser. Next we'll need that MAC address for the new VM in order to allocate that free license to this server. On the Hyper-V host launch an elevated power shell (run power shell as administrator). From the prompt type:
Get-VM|Get-VMNetworkAdapter | FT VMName, MACAddress
and hit enter. This will provide you with a list of MAC addresses for your VMs. Note the one for the newly created VM so you can use it for license allocation. return to the webpage you left open in step 1 above and place the cursor in what looks like a drop-down box under Host ID. Type in the MAC address you just located using power shell and click the Continue button. Click Confirm. Click the download button and save the .lic file to your computer. You'll need this in a moment to license your NetScaler vpx express.
Open a web browser and point it to the ip of your new NetScaler. You may be warned about the security of your connection. Feel free to proceed. At the logon page use nsroot for the username and nsroot for the password. You will then be taken to the initial configuration wizard.
The wizard is divided into four steps. Step 1 will show as already complete (that’s where you picked an IP and netmask). Click on Step 2 and the system will prompt you for a subnet address. This is the second of the local static ip referenced in the pre-requisite section above. Provide the IP and netmask.
Step 3 is to provide some local context for the gateway. The hostname is how the gateway will be identified on your local network and the ip address is the third of those local static IPs referenced in the pre-requisite section above. The time zone is your local time zone.
Step 4 is where you get to upload that .lic file you downloaded above. Once these four steps are complete the NetScaler will need to reboot. After it reboots you’ll need to log back in using nsroot/nsroot. You can confirm that you are licensed by expanding the System menu on the left side and clicking the Licenses link. You should see a Standard license with 5 maximum NetScaler Gateway Users Allowed.
Now that the initial configuration of the gateway is done, you’ll need to prepare it for secure transactions. Begin by expanding the Traffic Management menu on the left side and clicking the SSL link (no need to expand SSL just yet). Under SSL Keys click the Create RSA Key link. The name of the key file is whatever you like though I recommend something that makes it obvious that it is a key and the date on which it was created. I also recommend giving it a .key extension. The key size should be set to 2048, the public exponent is F4, the format is PEM, and the encoding algorithm is DES3. The passphrase can be whatever you like, but make sure it is something you can remember as this will be used later to confirm the link. You’ll repeat the passphrase in the second box (to make sure they match) and then click OK when done.
You are now ready to prepare to request a server certificate. Still on the SSL page click the Create Certificate Signing Request (CSR). Once again you can call it anything you like but I recommend giving it a name that describes that it is a CSR for this particular server and created on this particular date. I also recommend giving it a .txt extension. For the key file click the browse button and select the .key file you just created. The format is PEM and the passphrase is that passphrase you just created above. Fill in the information for country, state, org, city, email, and org unit. For Common this is your fully qualified external domain name (including the subdomain so if it is citrix.[yourdomain].com you’ll need all if it). For challenge you’ll need a passphrase again. It does not need to be the same as the passphrase you used above but it technically can be the same if you like. When done click OK. You may be prompted to view the CSR you just created. If so, click yes. If not click the Manage Certificates / Keys / CSRs under the Tools section of the SSL page, click on the CSR and click view.
With the CSR open, select the entire phrase from
-----BEGIN NEW CERTIFICATE REQUEST-----
to
-----END NEW CERTIFICATE REQUEST-----
And copy it. Open a browser window to your SSL certificate provide (your SA) and follow their procedures to either request a new key or rekey an old key to your NetScaler. When prompted, paste the request text into the issuer’s system. (In earlier builds of 10.5 NetScaler was only able to use SHA-1 certificates. It appears that in 57.7 SHA-2 are supported.) After you’re provider issues the certificate, you’ll need to download the root, intermediate, and server certificates. Download them in Apache (.crt) format.
Next click on Traffic Management::SSL::Certificates and (with no certificate selected) click the Install button along the top of the page. For the Certificate-Key Pair Name give it a meaningful name. I recommend something like Server-Cert-[cert-auth]-date so you know that this is the server certificate issued by a particular certificate authority and that it was installed today. For the Certificate File Name click the down arrow next to browse and select Local to browse your local computer so you can upload the server certificate downloaded from your provider. Next click the browse button next to the Key File Name box and select the .key file you created earlier. Leave the setting on PEM and enter that second passphrase created earlier (when you were creating the CSR) in the Password box. Leave Certificate Bundle unchecked (unless your provider has issued a bundle file—a bit of googling should help you figure out what to do with that) and, if you like, leave the Notify When Expires checked and set to 30 for the notification period. Click the Install button.
Next (again with no certificate selected), click the Install button. This time you’ll be installing the intermediate certificate so for Certificate-Key Pair Name give it something meaningful. I recommend something like intermediate-[cert auth]-date so you can see at a glance who issued the certificate and what day it was installed and see if that matches up to the server and rood certificates. For the Certificate File Name once again click the down arrow next to the Browse button and select Local to upload the intermediate certificate from your certificate provider. Leave all other setting alone and click the Install button.
Finally, we need to get the root certificate installed. Still on that same SSL::Certificates page (with no certificate selected) click the Install button. This time for the Certificate-Key Pair Name I recommend giving it a name such as root-[cert auth]-date s you can see at a glance who issued the root certificate, when you installed it, and if it matches to the intermediate and server certificates. For the Certificate File Name, again click the down-arrow next to the Browse button and select Local to upload your certificate provider’s root certificate. Leave everything else alone and click the Install button.
We are on to the final step with the SSL certificates—linking. Click the server certificate to select it. Click the Action drop-down list above and select Link. Select your intermediate certificate from the list and click OK. Next click the Intermediate certificate and follow the same procedure to link it to the root. When you’re done if you click on the server certificate and choose the action Cert Links you should see the intermediate listed, for the intermediate you should see both the root and the server certificate listed and for the root you should see the intermediate listed. Your chain is properly linked.
It is time to connect things up with your Xen server (App or desktop) by creating a virtual gateway server. On the left side of the NetScaler configuration system, click the XenApp and XenDesktop button below the Integrate with Citrix Products section. A before you begin list appears. Click the Get Started button. The Wizard then asks what type of integration you’re going for, which in the case of this how-to would be a StoreFront. Click the Continue button.
On the next screen you’ll be asked for the NetScaler gateway address. Provide the second of those local static IP addresses from above. Leave it set to port 443 (the standard SSL port). You’ll also need to give the gateway a name for reference by your StoreFront. It can be anything you like such as gateway or NSGateway. Finally, check the box to redirect traffic from port 80 to secure port (so if a user browses to http://yourserver.com it will automatically redirect them to https://yourserver.com) and then enter the fully qualified external domain name (such as citrix.[your domain name].com) and click continue.
You’ll then be prompted to select your Server Certificate. You’ll see your three certificates in the dropdown list (server, intermediate and root). Select your server certificate (if it isn’t already selected) and click continue.
You’ll next be asked to create a profile for your active directory server. Assuming everything is as Microsoft usually has it for the IP address, enter the local address of your AD server and leave it on port 389 with a time out of 3 seconds. For the Base DN most users will be able to dc=[local domain name],dc=[local domain suffix] (so if your local domain is local.lan, use dc=local,dc=lan for the Base DN).
The service account is the administrator username which has credentials sufficient to access the active directory tree. For server Logon Name Attribute use sAMAccountName and for password and confirm password use the password for the admin account referenced above. Leave secondary authentication alone and click continue.
You will then be asked to enter information about your StoreFront server. First, enter the fully qualified local domain name [servername].[local domain name].[local domain suffix] (for example vm-storefront.local.lan). For the site path enter the path from the Receiver for Web url on your StoreFront server (which is often something like /Citrix/StoreWeb but may be different on your server). For single sign-on you’ll enter your [local domain name].[local domain suffix] (for example local.lan), the store name is whatever you named your store on the StoreFront Server (such as Store), and the secure ticket authority is http://[servername].[local domain name].[local domain suffix] (for example something like http://vm-storefront.local.lan). The protocol can be left as http and the storefront server is the local ip address of your StoreFront server with a port of 443. When all that information is entered, click the continue button.
Time to point to your Xen Farm (isn’t that where actor David Carradine lived in the 70s). If you are setting up a free VPX you likely have a fairly simple farm consisting of a single store that serves both apps and a remote desktop for your users. Assuming that’s the case, select XenDesktop from the Configure dropdown list and then provide the local ip address of your server (assuming it is all housed on a single machine it will likely be the same local ip as your storefront server). Leave the rest alone and click continue. You’ll be able to optimize some of it though the rest will be unavailable due to the free license (so don’t worry if you get an error here). When you are done going through the remaining steps, click Done.
To ensure you have set everything up correctly, start by checking that the site is resolving properly using an online DNS lookup like the one at MX Toolbox listed in the references below. If that resolves to the correct external IP address go on to check if the server is live. You can use a tool like the one at iWebTool listed in the references below. You should also browse to the server (assuming that your local network settings will allow you to resolve an external address hosted on your domain). If all of that checks out, you can check to see if all your certificates are resolving properly using SSLShooper’s checker which is also listed in the references below. The final test will be to actually use your gateway to connect, download, install, and use citrix.
No comments
Post a Comment