Citrix Virtual Apps and Desktops 2507 SDK

View PDF

about_Broker_GroupPolicy

August 14, 2025

Contributed by:

Topic

Citrix Broker SDK - Group Policy for VDA Configurations

Short Description

Overview of Citrix Group Policy settings that control VDA behaviors.

Long Description

A VDA configuration policy is a collection of settings that specify how a VDA should initialize its environment when a user logs on. Settings that are to be enforced when a specific user session is created are user settings. Settings that are always applied to all user sessions are computer settings.

Multiple policies contianing multiple settings can be defined. Filters can be specified in a policy to define how the settings included in the policy are to be applied, based on data such as the user name, the name of the client, from which the user session is originated.

There is a policy processing engine (CSE) running on each VDA. The engine is responsible for processing the policies downloaded to the VDA from the site, to which the VDA is registered, and/or the domain the VDA is in. The engine uses policies from all the sources to calculate a net result, which is a single set of unique settings that can be used by the VDA to initialize the environment when a user logs on.

A policy object contains a set of properties that describe the object. It also contains a set of settings, which are specific VDA configuration settings, as well as a set of filters, which specify how the settings in the policy are applied.

A setting is a single piece of data that specifies a certain behavior for a user session. For example, a wallpaper setting is used to control if a wallpaper should be displayed when a user logs on.
A filter is a statement that specifies how the settings in the policy are to be applied. When evaluted with the input data required by the filter, the statement yields a Boolean value. A true result tells the policy engine that the settings should be applied. A false result tells the policy engine to not apply the settings.

To define a VDA configuration policy, specify a name for the policy and a priority that indicates a precendence for the settings in the policy when the policy is evaluated togehter with other policies by the Citrix policy engine (CSE) running on a VDA. A name and an optional brief description can be specified to help identifying the policy and its purpose.

Four types of objects are defined to store policy data. They are policy sets, policies, settings, and filters.

A policy set is a container of a collection of policies. For each site, there is always a default policy set defined and this policy set contains all the site policies.

A policy is a collection of settings and filters.

A setting specifies a configuration that will be honored and enforced by a VDA component.

A filter is a predicate that specifies the condition for the settings in the policy to be applied or not applied.

There can be multiple policies in a policy set. There can be multiple settings in a policy. There can be multiple filters in a policy. A setting can be used in multiple policies but can only be used once in a policy. Multiple filters can be specified in a policy and the final result of combining all the filters decides if the policy should be applied or not.

For detailed information about defining policy objects, see:

help New-BrokerGpoPolicySet help New-BrokerGpoPolicy help New-BrokerGpoSetting help New-BrokerGpoFilter

To use a setting in a policy, the user must know some information about a setting. For example, settings are identified by setting names, which can only be obtained by running the command Get-BrokerGpoSettingDefinition. To configure a setting, the user also needs to know the type and format of the data for the setting, which can be furnished by the command.

Similarly, to specify the conditions about how policies are to be applied, the user also needs to configure filters. To use a filter, a filter type must be specified. The available filter types and the detailed filter data format can be obtained by running the Get-BrokerGpoFilterDefinition command.

The Get-BrokerGpoSettingDefinition command returns all the settings currently available if no setting name is specified. This command can produce a long output because of the large number of settings. Each setting definition contains detailed information about the setting. For more information, see the help for this command.

The Get-BrokerGpoFilterDefinition command returns all the filters defined.

Many settings are of simple value types such as bool, int, or string. There are also many settings that take arrays of strings as values. A few settings take values that are in sophiticated formats. The best way to specify values for these settings is use the UI to create a setting, and then use the Get-BrokerGpoSetting command to find its format.

Examples

To create a policy set, use the New-BrokerGpoPolicySet command. At minimum, only the name of a policy set is required. The type of the policy set created is always DeliveryGroupPolicies.

New-BrokerGpoPolicySet "PolicySet1"
<!--NeedCopy-->

Description : GpoDataSize : 0 IsAssigned : False LastError : Name : PolicySet1 PolicyCount : 0 PolicySetGuid : a6a02f6c-543a-4bb6-b94c-2673f8e4865d PolicySetType : DeliveryGroupPolicies Scopes :

To create a policy, a policy set is required. A policy set is always identified by the policy set Guid. Usually, the name can be obtained by querying the policy set object first.

If a new policy in the policy set PolicySet1 is to be created, the policy set Guid is retrieved first:

$PolicySetGuid = (Get-BrokerGpoPolicySet “PolicySet1”).PolicySetGuid

Then a new policy can be created. Only a name is required for a new policy, although usually a description should be specified. The new policy always has the lowest priority (the highest priority number).

If IsEnabled is not specified, it is set to disabled. The settings of this policy are always disregarded in policy evaluation.

New-BrokerGpoPolicy -PolicySetGuid $PolicySetGuid "Policy0"
<!--NeedCopy-->

Description : IsEnabled : False Name : Policy0 PolicyGuid : 7630e395-fb53-4581-9955-07a859ac9d7a PolicySetGuid : a6a02f6c-543a-4bb6-b94c-2673f8e4865d Priority : 1

To configure a setting in a policy, the policy must be specified. The policy is identified by its Guid. To get the Guid of a policy, use the Get-BrokerGpoPolicy command. If multiple policies with the same name exist in multiple policy set, the policy set also must be specified. The following commands set the value of setting WemCloudConnectorList in policy Policy0 to “test.cloud.com”, assuming its current value is “test.citrix.com”.

Get-BrokerGpoPolicy -Name Policy0
<!--NeedCopy-->

Description : IsEnabled : False Name : Policy0 PolicyGuid : 07aa0fe5-fff6-4f33-960e-1b25afc822c9 PolicySetGuid : a6a02f6c-543a-4bb6-b94c-2673f8e4865d Priority : 1

Get-BrokerGpoSetting -PolicyGuid "07aa0fe5-fff6-4f33-960e-1b25afc822c9" -SettingName WemCloudConnectorList
<!--NeedCopy-->

PolicyGuid : 07aa0fe5-fff6-4f33-960e-1b25afc822c9 SettingGuid : 4d0e15ee-ff21-4524-a255-1d98e70825fb SettingName : WemCloudConnectorList SettingValue : [“test.citrix.com”] UseDefault : False

Set-BrokerGpoSetting ([Guid]"4d0e15ee-ff21-4524-a255-1d98e70825fb") -SettingValue '["test.cloud.com"]'
<!--NeedCopy-->

PolicyGuid : 07aa0fe5-fff6-4f33-960e-1b25afc822c9 SettingGuid : 4d0e15ee-ff21-4524-a255-1d98e70825fb SettingName : WemCloudConnectorList SettingValue : [“test.cloud.com”] UseDefault : False

If the setting GUID of a setting is already known, there is no need to get the policy GUID and then the setting GUID. Generally, in a script, GUIDs of settings, policies, and filters should be kept in variables for later use.

Note that in this example, the value of the setting is an array of strings with each string specifying a URL. For settings whose values are string arrays, the arrays must be specified as JSON arrays of strings.

To delete a setting, use the Remove-BrokerGpoSetting command. For example, the following command deletes the setting WemCloudConnectorList from its policy.

Remove-BrokerGpoSetting ([Guid]"4d0e15ee-ff21-4524-a255-1d98e70825fb")
<!--NeedCopy-->

Use the following command to remove all WemCloudConnectorList settings from all policies.

Remove-BrokerGpoSetting -SettingName WemCloudConnectorList
<!--NeedCopy-->

To add a filter to a policy, specify the GUID of the policy and the filter parameters. For example, the following command adds a tag filter to a policy, which is identified by its GUID.

New-BrokerGpoFilter -PolicyGuid "07aa0fe5-fff6-4f33-960e-1b25afc822c9" -FilterType DesktopTag -FilterData '{"Server": "test.citrix.com", "Uuid": "836b1f77-021c-410d-806a-ed9ee76897e3" }' -IsAllowed $true -IsEnabled $true
<!--NeedCopy-->

FilterData : {“Server”: “test.citrix.com”, “Uuid”: “836b1f77-021c-410d-806a-ed9ee76897e3” } FilterGuid : 6bf7fa92-10f0-4672-ba1a-2a353f895684 FilterType : DesktopTag IsAllowed : True IsEnabled : True PolicyGuid : 07aa0fe5-fff6-4f33-960e-1b25afc822c9

In this example, a special syntax is needed for the DesktopTag filter. The data for this filter must be a serialized JSON object that is a Server/Uuid pair. The name of the server is typically a DDC, which is used to resolve the UUID when the filter is to be resolved in a user program that is not running on a DDC. Because Web Studio always uses the DDC it is connected to resolve a filter, this server address is not used.

Because the tag is specified using a GUID, it is possible to just specify any GUID value and therefore, it is possible to define a filter that doesn’t exist. At the time when the filter is added, no attempt is made to resolve the UUID to a tag name.

The DesktopGroup filter uses the same syntax to specify its value.

The AccessControl filter takes a value that is a serialized JSON object. To see its detailed format, use Web Studio to configure such a filter, and then use the Get-BrokerGpoFilter command to see the filter data. The following example lists all filters of type AccessControl:

Get-BrokerGpoFilter -FilterType AccessControl
<!--NeedCopy-->

FilterData : {“Connection”:”WithAccessGateway”,”Condition”:”*”,”Gateway”:”test.citrix.com”} FilterGuid : cc67cae9-0123-4f3e-ae47-6a07291779f1 FilterType : AccessControl IsAllowed : True IsEnabled : True PolicyGuid : faca3f2e-0dd7-483a-8906-cbfb1a262511

FilterData : {“Connection”:”WithAccessGateway”,”Condition”:”*”,”Gateway”:”test.cloud.com”} FilterGuid : 39ceaeb3-732a-4e7a-9f53-7696d3d3028c FilterType : AccessControl IsAllowed : True IsEnabled : True PolicyGuid : faca3f2e-0dd7-483a-8906-cbfb1a262511

So, the AccessControl filter data is an object of three properties, Connection, Condition, and Gateway.

about_Broker_GroupPolicy

Topic

Short Description

Long Description

Examples

See Also

In this article