KeePass   KeePass Help Center Home KeePass Home | Package Downloads | Flag Translations | Blocks Plugins | Donate Donate 
Home Help Center Home | People Forums | Award Awards | Link Links 







Locked

Enforced Configuration

Details about enforced configuration files.


Help General

Settings in an enforced configuration file take precedence over settings in global and local configuration files.

This feature is intended primarily for network administrators who want to enforce certain settings for users of a shared KeePass installation.

The format of an enforced configuration file is basically the same as the format of a regular configuration file. An enforced configuration file must be stored in the KeePass application directory (which contains KeePass.exe). Its name depends on the KeePass edition:

  • KeePass 1.x: KeePass.enforced.ini.
  • KeePass 2.x: KeePass.config.enforced.xml.

In order to create an enforced configuration file, we recommend the following procedure:

  1. Download the portable ZIP package of KeePass and unpack it. Run KeePass, configure everything as you wish, and exit it.
  2. Rename the configuration file to the enforced configuration file name.
  3. Open the enforced configuration file with a text editor and delete all settings that you do not want to enforce.
KeePass 2.x Only
Regular configuration files often contain only settings whose values differ from the default values (performance optimization). There are multiple ways to find a setting that is set to its default value:
  • Change the setting to a non-default value (using KeePass' user interface). The setting should then be stored in the configuration file (and you can change its value back to the default value).
  • Download the source code of KeePass 2.x. The files in the directory 'KeePass/App/Configuration' define the configuration file format; the root node is defined in the file 'AppConfigEx.cs'. A little bit C# knowledge is required to understand these files.
  • Open a Visual Studio Developer Command Prompt and run the following command:
    Xsd.exe KeePass.exe /type:KeePass.App.Configuration.AppConfigEx
    This generates an XSD file that defines the configuration file format.
The last two approaches have the advantage that you can also discover settings that are not configurable using the user interface of KeePass (like the ones documented on the master key and customization help pages).

In general, settings that are not present in the enforced configuration file can be configured by the user, i.e. non-enforced settings are loaded and stored from/to global and local configuration files as usual. This depends on the merge modes and options though, which are described below.

The global configuration file is stored in the KeePass application directory. As users should not have write access to any files in this directory (see the 'Security' section), any non-enforced settings should be stored in the local configuration file of the user. In order to instruct KeePass to use the local configuration file instead of the global one, the global configuration file (in the KeePass application directory) should only contain the following:

  • For KeePass 1.x, the global KeePass.ini file should only contain:
    [KeePass]
    KeePreferUserConfiguration=True
  • For KeePass 2.x, the global KeePass.config.xml file should only contain:
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Meta>
    		<PreferUserConfiguration>true</PreferUserConfiguration>
    	</Meta>
    </Configuration>

Theoretically, you can enforce all settings (for instance by specifying the content mode 'Replace' for the root element 'Configuration'). However, please note that this is very rarely a good idea. For example, positions and sizes of user interface controls depend on the current display resolution and thus often vary from user to user; it usually does not make sense to enforce certain values for such settings.


Locked Security

Users must not have write access to any files in the KeePass application directory (including the enforced configuration file). You have to ensure this using an appropriate access control list (in Windows Explorer, right-click onto the KeePass application folder → 'Properties' → tab 'Security').

Please note that the enforced configuration file only applies to the KeePass program in the same directory. If the user runs another copy of KeePass without an enforced configuration file, this copy does not know the enforced configuration file that is stored elsewhere, i.e. no settings are enforced.


Windows User Interface (2.x)

Under certain circumstances, KeePass disables user interface controls for settings that are present in an enforced configuration file (not for all controls and not in all situations).

Enforced Options

Example. The following enforced configuration file enforces the specified values/states for the settings 'Clipboard auto-clear time' (20 seconds), 'Lock workspace when locking the computer or switching the user' and 'Lock workspace when the computer is about to be suspended'. KeePass grays out the corresponding controls in the user interface, i.e. their values/states cannot be changed. All other settings can be configured by the user.

<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Security>
		<WorkspaceLocking>
			<LockOnSessionSwitch>true</LockOnSessionSwitch>
			<LockOnSuspend>true</LockOnSuspend>
		</WorkspaceLocking>
		<ClipboardClearAfterSeconds>20</ClipboardClearAfterSeconds>
	</Security>
</Configuration>

Merge Node Modes – Attribute 'MergeNodeMode' (2.x)

Given a node in the enforced configuration, the node mode specifies how the merge algorithm should create and/or open a corresponding node in the user configuration.

The desired node mode can be declared using a 'MergeNodeMode' attribute on the enforced node. This attribute is optional. The following values are supported:

Node ModeDescription
Create If there is no corresponding node in the user configuration, create such a node and open it.
Open If there is a corresponding node in the user configuration, open it.
OpenOrCreate If there is a corresponding node in the user configuration, open it. Otherwise, create such a node and open it.
Remove If there is a corresponding node in the user configuration, remove it.
None Do nothing.

This mode is for internal use only and cannot be specified using the 'MergeNodeMode' attribute. If you do not want to enforce an element, remove it from the enforced configuration file (or comment it out using '<!-- ... -->').

The first matching rule in the following list determines the node mode for the current element in the enforced configuration:

  1. If the current element has a 'MergeNodeMode' attribute, use the specified mode.
  2. If the current element is one of the following elements, use the specified mode.
    Element XPathNode Mode
    /Configuration/Application/PluginCompatibility None (★)
    /Configuration/Meta/DpiFactorX None (★)
    /Configuration/Meta/DpiFactorY None (★)
  3. Use the 'OpenOrCreate' mode.

(★) The configuration settings marked with a star depend on the user's computer (operating system, display resolution, etc.). In general, it does not make sense to enforce certain values for them.

If a corresponding node in the user configuration can be opened (possibly after creating it), the contents of the two nodes are then merged according to the content mode.

Example (Node Mode 'Remove')
User configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item>
			<Key>Example_A</Key>
			<Value>21</Value>
		</Item>
		<Item>
			<Key>Example_B</Key>
			<Value>22</Value>
		</Item>
	</Custom>
</Configuration>
Enforced configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item MergeNodeMode="Remove">
			<Key>Example_A</Key>
		</Item>
	</Custom>
</Configuration>
Result:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item>
			<Key>Example_B</Key>
			<Value>22</Value>
		</Item>
	</Custom>
</Configuration>
Comment:

In the enforced configuration, the item has a 'MergeNodeMode="Remove"' attribute. Therefore, the corresponding item in the user configuration is removed.



Merge Content Modes – Attribute 'MergeContentMode' (2.x)

Given a node in the enforced configuration and a corresponding opened node in the user configuration, the content mode specifies how the contents of the two nodes are merged.

The desired content mode can be declared using a 'MergeContentMode' attribute on the enforced node. This attribute is optional. The following values are supported:

Content ModeDescription
Merge For each (direct) child element of the current element in the enforced configuration, the merge algorithm tries to find a corresponding child element in the user configuration and calls itself (recursively).
Replace Replaces the content of the element in the user configuration by the content of the element in the enforced configuration. Any differing or additional settings in the user configuration element are lost. The content is not inspected further, i.e. any merge attributes in the content have no effect.

The first matching rule in the following list determines the content mode for the current node pair:

  1. If the current element has a 'MergeContentMode' attribute, use the specified mode.
  2. If the current element is one of the following elements, use the specified mode.
    Element XPathContent Mode
    /Configuration/Application/TriggerSystem/Triggers/Trigger Replace
    /Configuration/Defaults/KeySources/Association Replace
    /Configuration/PasswordGenerator/AutoGeneratedPasswordsProfile Replace
    /Configuration/PasswordGenerator/LastUsedProfile Replace
    /Configuration/PasswordGenerator/UserProfiles/Profile Replace
  3. If the user element or the enforced element has a child element, use the 'Merge' mode.
  4. Use the 'Replace' mode.

Example (Content Mode 'Replace')
User configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<UI>
		<TrayIcon>
			<GrayIcon>true</GrayIcon>
		</TrayIcon>
	</UI>
</Configuration>
Enforced configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<UI>
		<TrayIcon MergeContentMode="Replace">
			<SingleClickDefault>true</SingleClickDefault>
		</TrayIcon>
	</UI>
</Configuration>
Result:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<UI>
		<TrayIcon>
			<SingleClickDefault>true</SingleClickDefault>
		</TrayIcon>
	</UI>
</Configuration>
Comment:

The 'MergeContentMode="Replace"' attribute of the 'TrayIcon' element in the enforced configuration instructs KeePass to merge this element in the 'Replace' mode. So, the content of this element in the enforced configuration replaces the content of the corresponding element in the user configuration. Consequently, the user's choice to use a gray icon is lost.

If the 'MergeContentMode="Replace"' attribute would be removed from the enforced configuration, the 'Merge' mode would be used. In the resulting configuration, both 'GrayIcon' and 'SingleClickDefault' would then be set to 'true'.



Merge More Merge Options (2.x)

The following optional attributes are supported:

Attribute NameValueDescription
MergeChildrenOtherMode This attribute controls the behavior for child elements that are present in the user configuration, but not in the enforced configuration.

The default value is 'None'.

None Keep the child elements.
Remove Remove the child elements.
MergeChildrenSortOrder This attribute allows to specify how the child elements of the current element are sorted.

The default value is 'Other'.

Other The order of the child elements in the user configuration is preserved.
This The order of the child elements in the enforced configuration is preserved.


Multiple Lists (2.x)

A list is an element that contains multiple child elements with the same name. The child elements of a list are called list items.

When merging lists, KeePass has to decide which list item in the enforced configuration gets merged with which list item in the user configuration.

For some lists, this decision is made as follows: for each list item, one or more child nodes are selected and their contents are concatenated (with separators) to build a node key; list items with identical node keys in both configurations are then merged. The child node selection depends on the type of the list item:

Element XPath Node Key Selection XPath
/Configuration/Application/MostRecentlyUsed/Items/ConnectionInfo Path | UserName
/Configuration/Application/PluginCompatibility/Item .
/Configuration/Application/TriggerSystem/Triggers/Trigger Guid
/Configuration/Application/WorkingDirectories/Item .
/Configuration/Custom/Item Key
/Configuration/Defaults/KeySources/Association DatabasePath
/Configuration/Integration/AutoTypeAbortOnWindows/Window .
/Configuration/Integration/UrlSchemeOverrides/CustomOverrides/Override Scheme | UrlOverride
/Configuration/MainWindow/EntryListColumnCollection/Column Type | CustomName
/Configuration/PasswordGenerator/UserProfiles/Profile Name

For other lists, the list items are merged based on their indices.

Example (Node Keys)
User configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item>
			<Key>Example_A</Key>
			<Value>21</Value>
		</Item>
		<Item>
			<Key>Example_B</Key>
			<Value>22</Value>
		</Item>
		<Item>
			<Key>Example_C</Key>
			<Value>23</Value>
		</Item>
	</Custom>
</Configuration>
Enforced configuration:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item>
			<Key>Example_B</Key>
			<Value>40</Value>
		</Item>
	</Custom>
</Configuration>
Result:
<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
	<Custom>
		<Item>
			<Key>Example_A</Key>
			<Value>21</Value>
		</Item>
		<Item>
			<Key>Example_B</Key>
			<Value>40</Value>
		</Item>
		<Item>
			<Key>Example_C</Key>
			<Value>23</Value>
		</Item>
	</Custom>
</Configuration>
Comment:

For a '/Configuration/Custom/Item' element, the content of the 'Key' child node is used to build a node key (see the table above). In this example, the (first) item in the enforced configuration is therefore merged with the second item in the user configuration; they have the same key.



Help Examples (2.x)

  • Disable automatic update check.
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Application>
    		<Start>
    			<CheckForUpdate>false</CheckForUpdate>
    			<CheckForUpdateConfigured>true</CheckForUpdateConfigured>
    		</Start>
    	</Application>
    </Configuration>
  • Disallow exporting, printing and changing the master key.
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Security>
    		<Policy>
    			<Export>false</Export>
    			<Print>false</Print>
    			<ChangeMasterKey>false</ChangeMasterKey>
    		</Policy>
    	</Security>
    </Configuration>
  • Disallow plugins.
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Security>
    		<Policy>
    			<Plugins>false</Plugins>
    		</Policy>
    	</Security>
    </Configuration>
  • Disable trigger system.
    The following disables the trigger system. Triggers in the user configuration are preserved, but they are not executed.
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Application>
    		<TriggerSystem>
    			<Enabled>false</Enabled>
    		</TriggerSystem>
    	</Application>
    </Configuration>
  • Disable trigger system, delete user triggers.
    The following disables the trigger system and additionally deletes all triggers in the user configuration.
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Application>
    		<TriggerSystem>
    			<Enabled>false</Enabled>
    			<Triggers MergeContentMode="Replace" />
    		</TriggerSystem>
    	</Application>
    </Configuration>
  • Enforce specific triggers, disallow editing.
    The following enforces the two triggers 'Example A' and 'Example B', deletes all other triggers in the user configuration (due to the 'MergeContentMode="Replace"' attribute on the triggers element) and disallows editing triggers (policy 'EditTriggers').
    <?xml version="1.0" encoding="utf-8"?>
    <Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    	<Application>
    		<TriggerSystem>
    			<Enabled>true</Enabled>
    			<Triggers MergeContentMode="Replace">
    				<Trigger>
    					<Guid>5iVmt54rM0mxsOj1PlJPOg==</Guid>
    					<Name>Example A</Name>
    					<Events />
    					<Conditions />
    					<Actions />
    				</Trigger>
    				<Trigger>
    					<Guid>JU7vAiuxuEu15LczSCYmJQ==</Guid>
    					<Name>Example B</Name>
    					<Events />
    					<Conditions />
    					<Actions />
    				</Trigger>
    			</Triggers>
    		</TriggerSystem>
    	</Application>
    	<Security>
    		<Policy>
    			<EditTriggers>false</EditTriggers>
    		</Policy>
    	</Security>
    </Configuration>








Get KeePass