Endpoint Configuration Merging
In this section:
- About Endpoint Configuration Merging
- Merge Components
- ManifestGen Tool
- Merge Configurations
- Merge Behaviors
- Live Configuration Rules
- Live Configuration Update Behavior
- Endpoint Configuration Merging Auditing Events
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.
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:
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.
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.
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:
This directory is secured so only administrators can write to it. This ensures that end users cannot affect the merge configurations
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:
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:
||The root node of the configuration.|
||The container tag for the list of AAMP files that are to be included in the merge.|
||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 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.
||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
|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:
- 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:
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.
|Suffix||Description and Usage|
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.
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.
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
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
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.
<FileEntry Name="config3.aamp" BaseConfig="true"
<FileEntry Name="config2.aamp" Checksum="e899e0f9a5afef5e4eb502072ac2e0"
<FileEntry Name="config1.aamp" Checksum="b50576a6d743cf361c37b64bcaca75"
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.
<FileEntry Name="config1.aamp" Checksum="b50576a6d743cf361c37b64bcaca75"
<FileEntry Name="config2.aamp" Checksum="e899e0f9a5afef5e4eb502072ac2e0"
<FileEntry Name="config3.aamp" Checksum="e899e0f9a5afee4eb502072a61c2eo"
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.
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:
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"
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.
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
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.
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.
The table below lists the configuration attributes which are merged and gives an explanation of their 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.|
When a live configuration is opened or saved on an endpoint, it is referred
To allow for configuration merging, the live configuration can also refer to:
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:
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.
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.
New auditing events for Configuration Endpoint Merging have been added to Application Control. When viewed in Windows Event Viewer (select Windows Log > Applications), the events provide further details such as what has caused a merge failure