Citrix Storefront Multisite User Farm Mapping configuration

I’ve recently been involved in a rather large project which had lots of multisite configurations required or user farm mappings. What I did notice that whilst there is a good bit of information on the interwebs about User Farm Mapping there wasn’t much if anything that could be considered as a complete guide.

So I thought I would put together a guide and a video (on its way) on what I think is important when configuring user farm mapping or multisites. Now firstly I must say that I have seen the tech preview of StoreFront 3.1 which does include some mapping elements finally in the GUI although it appears somewhat limited see here for details, but when StoreFront 3.1 is released you might find that some of this post is irrelevent but anyway here go’s.

User Farm Mapping / Multisite purpose

The purpose of User Farm Mapping is to allow you to define which XML brokers are enumerated against based upon user group configuration while providing several load balancing and failover mechanisms. This goes over and above what the Citrix StoreFront typically provides through the manage delivery controllers node. It add’s load balancing of XML enumeration to sites along with failover capability and agregation of resources to allow the preferential display of applications if you have multiple sites which publish the same applications.

For example with agregation you have a Dev site and a live site, and a single critical application published on both sites, if you make a change to the dev application and want your users to actively use it and test it you can create an agregation of sites and utilise XenApp/XenDesktop keywords PRIMARY and SECONDARY to specify which application launch icon is displayed see HERE for details on keywords.

User Farm mapping configuration basics

There is a simple building block structure which we will look at and outline some basic behavoiurs.

<userFarmMapping name="UserMapping1">
 <groups>
 <group name="" sid="" />
 </groups>
 <equivalentFarmSets>
 <equivalentFarmSet name="" loadBalanceMode="" aggregationGroup="">
 <primaryFarmRefs>
 <farm name="" />
 </primaryFarmRefs>
 <backupFarmRefs>
 </backupFarmRefs>
 </equivalentFarmSet>
 </equivalentFarmSets>
 </userFarmMapping>

This code above will need to go in the Store web.conf file, so if you have a store called vhorizon for instance you will need to edit the web.conf file in /Citrix/vhorizon and NOT /Citrix/vhorizonWeb.

Variables

The user farm mapping has several configuration variables some are required and some are optional. All the tags must be present in the code block however some do not require an entry in the =”” part of the tag.

<userFarmMapping name=“FriendlyName”>

This is a friendly name for the user mapping section, each section must have its own
individual name so you could not have two code blocks in the same Store entitled UserMapping1 for example. This is a required entry.

<group name=“Domain\Group” sid=”S-1-5-21-xxx-xxx-xxx-xxx” />

This line reflects the user group that this usermapping section is filtered by. Both
group name and SID are required and must pre-exist otherwise errors maybe
encountered through StoreFront admin GUI and Cannot Complete your request
messages.

You can have multiple lines of groups here but they will be treated as an AND statement so the farm mapping will only apply if the user is a member of GROUPA AND GROUPB. If you need multiple groups then multiple user farm mappings will be required. These groups do no have to reflect any groups used to publish Desktops or applications. This is a required entry.

EquivalentFarmSet name=”Location1”

This tag is again a friendly name however specifies within the user farm mapping that the farms have identical applications published. This is a required entry.

LoadBalanceMode=”LoadBalanced”
LoadbalanceMode=“Failover”

This tag specifies the mode in which the separate controllers are queried, load balanced behaves as you would expect the other option is “Failover” which queries the Primary Farm specified until such time as it is unable to receive a responsefrom it where it will then go on and query the next farmset. This is a required entry.

AggregationGroup=””

This tag again is a friendly name which can be used to specify user farm mappings that should be queried together and have identical applications published. This tag entry does not require configuration.

<primaryFarmRefs>

<farm name=“XenDesktop” />

This tag is where you specify the names of the delivery controllers that will take part in
userfarm mapping. This text must match exactly the name given to the
controllers within Storefront. For example if you create a XenDesktop
configuration within Storefront entitiled
ComPanyXD with xd701.company.local and xd702.company.local the farm name
within the config must be ComPanyXD, Any typos or errors here will produce
“cannot complete your request” and StoreFront admin GUI refresh issues.

You can specify multiple farms within the PrimaryFarm Ref tag’s and the the query to
the farms will be acted upon based upon the LoadBalanceMode selected earlier (as exampled below).

<primaryFarmRefs>
<farm name=“XenDesktop1” />
<farm name=“XenDesktop2” />

This is a required entry.

<backupFarmRefs>

<farm name=“XenDesktop-Backup” />

The backupFarmRefs tag is used when you want to query a particular farm when all
PrimaryFarmRefs farms fail to respond. Errors here will be reflected in the same way as the primary farm refs tag. The BackupFarmRefs tag does not require configuration.

Configuring user farm mapping

Firstly open the Web.Conf file with notepad and then find the below line of code.

</authentication>
 <wingConfigurations>
 <add name="Default" authenticationPath="citrix.deliveryservices/wing/authentication" authenticationName="Default" farmsetPath="citrix.deliveryservices/wing/farmsets" farmsetName="Default" resourcesName="Default" resourcesPath="citrix.deliveryservices/wing/resources" />
 </wingConfigurations>
 <resources>

REMOVE the / from “citrix.deliveryservices/wing/resources” /> so that it looks like “citrix.deliveryservices/wing/resources” >

Now copy and paste the code below between the /resources” > and the </wingConfigurations> code.

<userFarmMappings>
 <clear />

Now Under the <clear /> paste the example code block (well go into this shortly).

<userFarmMapping name="UserMapping1">
 <groups>
 <group name="vhorizon\group" sid="S-1-5-21-192877713-1470444450-2752603835-1203" />
 </groups>
 <equivalentFarmSets>
 <equivalentFarmSet name="Location1" loadBalanceMode="Failover" aggregationGroup="None">
 <primaryFarmRefs>
 <farm name="XenDesktop" />
 </primaryFarmRefs>
 <backupFarmRefs>
 </backupFarmRefs>
 </equivalentFarmSet>
 </equivalentFarmSets>
 </userFarmMapping>

The text included in the <userFarmMapping></userFarmMapping> tags and be replicated as many times as you need however the xml also needs to include subsequent close tags at the end of the configuration so at the bottom of your last </userFarmMapping> tag include the following code.

</userFarmMappings>
</resourceWingConfiguration>

So with all those steps taken care of what you should end up with is something similar to the below except for the number of user farm mappings that you have created. Please note the difference between some of the very similar xml code such as <userFarmMapping> and userFarmMappings> or <resourcesWingConfiguration> and resourcesWingConfigurations> they are different and will cause an error if used incorrectly.

</protocolTransition>
 <resourcesCommon>
 <resourcesWingConfigurations>
 <resourcesWingConfiguration name="Default" wingName="Default" >
<userFarmMappings>
 <clear />
 <userFarmMapping name="UserMapping1">
 <groups>
 <group name="vhorizon\group-hk" sid="S-1-5-21-192877713-1470444450-2752603835-1203" />
 </groups>
 <equivalentFarmSets>
 <equivalentFarmSet name="Location1" loadBalanceMode="Failover" aggregationGroup="None">
 <primaryFarmRefs>
 <farm name="xd76" />
 </primaryFarmRefs>
 <backupFarmRefs>
 </backupFarmRefs>
 </equivalentFarmSet>
 </equivalentFarmSets>
 </userFarmMapping>
</userFarmMappings>
</resourcesWingConfiguration> 
 </resourcesWingConfigurations>
 </resourcesCommon>

Things to look out for

As with all things there are some common errors that crop up with slight configuration errors and I’ve listed a few below. Also during the project we have had a single StoreFront store with around 80 seperate user farm mappings (so 80 code blocks configured) and with no perceivable reduction in performance. The servers were all put extensively through login testing and didn’t fail until well over the amount of users we had spec’d the servers for.

As mentioned the farm listings within the configuration are case sensitive so if you have a case error within a configuration that a user is a member of they will receive a cannot complete your request error and the event viewer will log an Event ID 7 and an Event ID 1.

Once you have input the UFM configuration into the web.conf file the StoreFront GUI
locks out the ability to edit and manage controllers for the store as this can have a detrimental effect to UFM if the delivery controller set names are changed etc. All changes to the delivery controllers must be performed manually through the web.conf files.

I have created a video on the process required for configuring user farm mapping along with some other important information.

Author: Dale Scriven