Endpoint Configuration Merging

In this section:

About Endpoint Configuration Merging
Merge Components
ManifestGen Tool
Manifests
Merge Configurations
Merge Behaviors
Live Configuration Rules
Live Configuration Update Behavior
Endpoint Configuration Merging Auditing Events

About Endpoint Configuration Merging

Endpoint Configuration Merging uses the Application Control Agent to combine multiple AAMP configuration files, saved on one endpoint, into a single configuration. Attributes such as group, user, custom and other rule types along with application and policy libraries from each configuration are added to the merged configuration.

The merge is done by adding the individual configurations to a directory on the endpoint and specifying, in a manifest file, the configurations which are to be merged. The Agent monitors the merge directory and automatically merges configurations when a manifest file is added to the directory.

Endpoint Configuration Merging allows different areas of a business to work independently on a particular area of a configuration, which can then be merged to create a single configuration.

System Center Configuration Manager Integration is not supported in Endpoint Configuration Merging.

Merge Components

Base Components

Every merge must have a base configuration - this is the first configuration in the merge onto which the other configurations are added. A merged configuration takes the global attributes such as Message Settings, Auditing, and any Default settings, from the base configuration.

It is therefore essential that the settings that are not merged are defined in the base.

By default, the base configuration is set as the AAMP file that is created when a live configuration is saved on an endpoint:

%PROGRAMDATA%\AppSense\Application Manager\Configuration\configuration.aamp

However, any configuration in the merge can be set as the base configuration.

Only AAMP files which are at the latest version can be included in a merge.

Component Configurations

A merged configuration is made up of a base configuration and one or more component configurations. Component configurations are AAMP files that are added to the base configuration during a merge. To be part of a merge, component configurations must be stored in the MergeConfigs directory.

MergeConfigs Directory

This directory is where component configurations for merging are stored and where a merge is triggered when a valid manifest is detected.

When you start the AMAgentService on an endpoint, the MergeConfigs directory is created:

%PROGRAMDATA%\AppSense\Application Manager\MergeConfigs

This directory is secured so only administrators can write to it. This ensures that end users cannot affect the merge configurations

ManifestGen Tool

Application Control includes a command line tool to assist when merging configurations and snippets. The ManifestGen tool creates the XML manifest file used to define and trigger a configuration merge. The XML file contains details of the AAMP files to be merged and can dictate whether the system configuration.aamp or a component configuration is used as the base in the merge.

To make using the tool easier, add its location to Advanced System Properties > Environment Variables > Path:

%PROGRAMFILES%\AppSense\Application Manager\Console

Manifests

The manifest is an XML file that includes details of the configurations to be merged and dictates whether or not the base configuration is included. The manifest initiates the merge when detected in the MergeConfigs directory - if detected by the agent, the merge begins.

Manifests are created using the ManifestGen command line tool.

The table below shows the attributes and tags which make up a manifest XML file:

Attribute/Tag	Description
`MergeManifest`	The root node of the configuration.
`MergeFiles`	The container tag for the list of AAMP files that are to be included in the merge.
`FileEntry Name`	Identifies a configuration to be included in the merge. The file must be present in the MergeConfigs directory to be included in a merge
`UseSystemBase`	UseSystemBase is set to "true" by default if not present in the manifest. It can be set to "true" or "false", and instructs to either include or exclude the default Configuration.aamp in the merge. This is the live Configuration.aamp file found in %ProgramData%\AppSense\Application Manager\Configuration\configuration.aamp. If set to "true", the base configuration must already be present on endpoints when the manifest is deployed, otherwise the merge will fail. If set to "false" the first configuration in the MergeFiles list is used as the base configuration unless otherwise defined by the BaseConfig attribute.
`WaitForConfigs`	Determines the behavior when a manifest .xml is detected in the MergeConfigs directory and not all named configurations are present. Can be set to: True - This is the default setting if it is not already present in the manifest. The merge will wait indefinitely until all configurations referenced in the manifest are present and then complete the merge. This is ideal if you are deploying the manifest with the configurations and you cannot be sure in what order they will be added to the directory. For example, when you are using an MSI. False - The merge will fail if a manifest is detected in the MergeConfigs directory which references a configuration which is not present. If you are using an installer, such as an MSI, to push out configurations and a manifest to endpoints, it is recommended that you set this to "true" as you cannot guarantee in what order the configurations and manifest will be added. This does not apply if using the SystemBase Configuration.aamp file. If the manifest merge is triggered and the Configuration.aamp is not present, the merge will fail - it will not wait for the base
Checksum (Optional)	An MD5 checksum unique to an AAMP file. If included in the manifest, the AAMP file in the MergeConfigs folder must have the same checksum to be included in the merge. Base configurations are not referenced by a checksum.

Create a Manifest

Save the configurations you want to be merged in the MergeConfigs directory:

%PROGRAMDATA%\AppSense\Application Manager\MergeConfigs
Open the Command Line Interface.
Enter cd %programdata%\AppSense\Application Manager to change the directory.
Enter manifestgen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp".

If you run manifestgen in the MergeConfigs folder, the agent picks up the manifest as soon as it is created and immediately start the merge.

If successful, a merge_manifest.xml file is created in:

%PROGRAMDATA%\AppSense\Application Manager

The manifest can now be used to trigger the merge and create a configuration.

If a merge_manifest.xml already exists in the output directory, the tool fails and a new manifest is not created - the current one is not overwritten.

Additional Commands

Suffix	Description and Usage
`-o`	Output file - Specify where the merged configuration is generated, for example, manifestGen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp" -o C:\Configs creates a manifest that will create a merged configuration in the Configs folder on the C drive.
`-b`	Base configuration - Identify the base configuration and exclude the system base configuration. For example, manifestGen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp" -b Config1.aamp creates a manifest that will create a merged configuration with Config1.aamp set as the base configuration.
`-nc`	No checksum entries - By default, each configuration listed in the manifest has an MD5 checksum which allows unique identification of a configuration. If the checksum in the manifest does not match that of the configuration the merge will fail. Using the -nc suffix with the ManifestGen tool will not list checksums in the manifest and means that merges will succeed if the configuration file names are correct, regardless of the checksum value. For example: manifestgen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp" -nc
`-nw`	The default behavior when a manifest is added to the MergeConfigs directory is to wait indefinitely until all configurations in the manifest are present and then perform the merge. However, the merge does not wait when a baseconfig and layer is missing and will fail immediately. Using the -nw suffix, a merge will fail if the configurations listed are not present when the manifest is added to the MergeConfigs directory. For example: manifestgen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp" -nw If the manifest lists five configurations and only four are present when the manifest is added to the MergeConfigs directory, the merge will fail. If you are using an installer, such as an MSI, to push out configurations and manifests to endpoints, it is recommended that you do not use this suffix as you cannot guarantee in what order the configurations and manifests will be added.

Edit a Manifest

Once created, a manifest file can be edited to change the attributes such as the base configuration and the order in which the merge should take place.

Although manifests can be edited and created in a text editor, it is recommended that you use the ManifestGen tool because it ensures the merge_manifest.xml file is in the correct format. If, for example, you have an "&" in a file name, the ManifestGen tool will escape this to make sure it is a valid XML file.

For example, the command:

manifestgen "C:\ProgramData\AppSense\Application Manager\MergeConfigs\*.aamp" -b mergeconfigs\config3.aamp

creates a manifest in which the system base configuration is not included and config3.aamp is set as the base.

<MergeManifest UseSystemBase="false" WaitForConfigs="true">

<MergeFiles>

<FileEntry Name="config3.aamp" BaseConfig="true" Checksum="e899e0f9a5afee4eb502072a61c2eo" />

<FileEntry Name="config2.aamp" Checksum="e899e0f9a5afef5e4eb502072ac2e0" />

<FileEntry Name="config1.aamp" Checksum="b50576a6d743cf361c37b64bcaca75" />

</MergeFiles>

</MergeManifest>
To edit the manifest, open the manifest in a text editor, make the required changes and save the file.

In this example, UseSystemBase is set to "true" and the BaseConfig-"true" command has been removed from config3.aamp. The order of the merge has also been changed.

<MergeManifest UseSystemBase="true" WaitForConfigs="true">

<MergeFiles>

<FileEntry Name="config1.aamp" Checksum="b50576a6d743cf361c37b64bcaca75" />

<FileEntry Name="config2.aamp" Checksum="e899e0f9a5afef5e4eb502072ac2e0" />

<FileEntry Name="config3.aamp" Checksum="e899e0f9a5afee4eb502072a61c2eo" />

</MergeFiles>

</MergeManifest>
When merged, the system base configuration.aamp file is included in the merge as the base configuration and the order in which the component configurations are merged onto the base is reversed.

Setting BaseConfig="true" for a configuration and UseSystemBase="true" in the same manifest will cause a conflict and the merge will fail.

Empty Manifest

Adding an empty manifest to the MergeConfigs directory automatically merges all AAMP configurations within that directory. It will merge all configurations in alphabetical order and set the base as the configuration.aamp found in:

%ProgramData%\AppSense\Application Manager\Configuration

If this AAMP is not present, the merge will fail.

To create an empty manifest, open a new file in a text editor, create a zero-byte file and save as merge_manifest.xml.

The same merge can be achieved using a manifest that, whilst not totally empty, does not include details of the AAMP files to be merged:

<MergeManifest UseSystemBase="true" WaitForConfigs="true"

</MergeManifest>

This provides the same results as a blank manifest but allows you to use the UseSystemBase attribute. If you set this to "false" the merge will use the configuration which is first alphabetically in the MergeConfigs directory, as the base.

Merge Configurations

Once you have created a manifest and have your configurations on your endpoints in place for merging, you can trigger the merge and create a new configuration.

A merge is triggered when a merge_manifest.xml is detected in the MergeConfigs directory which should contain all the configurations you want to merge.

If the manifest lists configurations which are not in the MergeConfigs directory, the merge will be delayed until all configurations are present.

Using the -nw tag, a manifest can be created which will fail a merge if all configurations are not present

Successful Merges

If the manifest is correct and the configurations listed are present in the MergeConfigs directory, the merged_configuration.aamp is created and used as the live configuration on endpoints.

In addition to the new configuration (merged_configuration.aamp) a copy of the successful manifest (last_merge_manifest.xml) is added to the folder to provide a record of the merge and a backup of the manifest. The original merge_manifest.xml file is deleted when the merge is complete.

The configuration.aamp file is not altered during a merge and is no longer used by the agent unless updated or the Merged_Configuration.aamp is not present.

Unsuccessful Merges

If an error occurs during the merge, it will fail and a new configuration file will not be created. Merges can fail if:

The checksums specified in the manifest do not match those of the actual configurations and WaitForConfigs is set to "false".
The manifest includes the -nw command and one or more configurations listed in the manifest are not present in the MergeConfigs directory when it is added.
Friendly names are the same in two of the configurations being merged.
UseSystemBase is set to "true" and a base Configuration.aamp is not present when the merge is triggered.
A manifest is invalid.
One or more configurations are corrupt.

Following an unsuccessful merge, the merge_manifest.xml file is deleted and a copy of the unsuccessful manifest (failed_merge_manifest.xml) is added to the directory.

Further details about merging errors can be found by using Windows Event Viewer (select Windows Log > Applications). The event will show the reason for the failure and which configuration is causing the merge to fail.

Merge Behaviors

The table below lists the configuration attributes which are merged and gives an explanation of their behavior.

Configuration Attribute	Merged?	Behavior
Rules (Groups, Users, Scripted, Custom, Device and Process)	Yes	The merged configuration contains all the Rules from each of the separate configurations. If two rules which affect the same application exist in the same trigger, they will run in parallel. The contents of individual rules are not merged.
Application Groups	Yes	The merged configuration will contain all Application Groups from the configuration layers. Application Groups remain unique to the non-base configuration and are all merged into the final merged configuration.
URM Policies	Yes	The merged configuration will contain all URM Policies from the configuration layers. URM Policies remain unique to the non-base configurations and are all merged into the final merged configuration.
Auditing	No	The events from the base are used in the merged configuration whilst the events from the component configurations are ignored.
Engineering Keys	No	Merged configurations inherit their Engineering Keys from the base configuration. Settings from any component configuration in the merge are discarded. It is therefore important that the Engineering Keys you require in the merged configuration are added to the base configuration.
Default Options	No	Merged configurations inherit their Default Options from the base configuration, for example Enabling User Privilege Management. Settings from any component configuration in the merge are discarded. It is therefore important that the Default keys you require in the merged configuration are added to the base configuration.
Message Settings	No	Merged configurations inherit their Settings from the base configuration, for example the message a user will see when a user self-elevates an item. Settings from any component configuration in the merge are discarded.
Archive Settings	No	Merged configurations inherit their Archive Settings from the base configuration, for example Enabling archiving. Settings from any component configuration in the merge are discarded.
Privilege Discovery Mode Configurations	No	Merged configurations inherit their Privilege Discovery Mode Settings from the base configuration, for example hidden applications and files. Settings from any component configuration in the merge are discarded.
URL Redirection Setting	No	Merged configurations inherit any URL Settings from the base configuration, for example configured connection types or IP ranges. Settings from any component configuration in the merge are discarded.
Audit Event Filtering Settings	No	Merged configurations inherit their Audit Event Filtering Settings from the base configuration. Settings from any component configuration in the merge are discarded.

Live Configuration Rules

When a live configuration is opened or saved on an endpoint, it is referred to:
%ProgramData%\AppSense\Application Manager\Configuration\configuration.aamp

To allow for configuration merging, the live configuration can also refer to:

%ProgramData%\AppSense\Application Manager\Configuration\Merged_Configuration.aamp

The agent monitors the %ProgramData%\AppSense\Application Manager\Configuration directory for new configurations. When a change is detected the agent loads a new configuration using the following order of precedence:

Merged_Configuration.aamp
configuration.aamp

If a Merged_Configuration.aamp exists in the directory, it will be the live configuration. If removed, the agent continues to use the in-memory version - it will not switch to the configuration.aamp file until the agent is restarted.

Live Configuration Update Behavior

The BaseConfigMergeBehavior engineering key allows you to define how the live configuration is affected when a Configuration.aamp file is pushed out to endpoints by the Management Center or other deployment method.

By defining the BaseConfigMergeBehavior engineering key, you can modify the live configuration behavior:

Remerge - When the configuration is detected on an endpoint by the agent, a merge, based on the last_merge_manifest.xml, is triggered and includes the new configuration.aamp. The merge creates a new Merged_Configuration.aamp which replaces the current live configuration. A last_merge_manifest.xml must be present otherwise the merge will fail.
Replace - When the configuration is detected on an endpoint by the agent, it replaces the Merged_Configuration.aamp as the live configuration. Following the successful deployment of the new Configuration.aamp, the Merged_Configuration.aamp is deleted from the directory.