Avoid Potentially Destructive Configuration

Overview

Potentially destructive configuration occurs when you bootstrap YAML configuration as category config for nodes that already have existing runtime configuration, which should be classified as system (or content). For details on configuration categories, see Configuration vs Content (vs System).

This issue is especially relevant for security configuration, because changes to security settings at runtime are common and expected.

Correct Configuration Example

When defining a custom group (for example, mygroup) in your YAML bootstrap, ensure that system-managed properties are categorized correctly. The following example shows the correct approach:

definitions:
  config:
    /hippo:configuration/hippo:groups/mygroup:
      jcr:primaryType: hipposys:group
      hipposys:system: true
      hipposys:members:
        .meta:category: system
        .meta:add-new-system-values: true
        type: string
        value: []
      hipposys:securityprovider: internal
      hipposys:userroles:
        .meta:category: system
        .meta:add-new-system-values: true
        type: string
        value: [xm.cms.user, xm.content.user, xm.channel.user, xm.report.user, 
                xm.dashboard.user, xm.channel.viewer]
copy

In this example, both hipposys:members and hipposys:userroles are configured with:

.meta:category: system
.meta:add-new-system-values: true
copy

This ensures that on a new deployment to production, any members or user roles added at runtime are not overwritten.

Note 1:
You can provide initial (bootstrap) values for hipposys:members as shown below:

hipposys:members:
  .meta:category: system
  .meta:add-new-system-values: true
  type: string
  value: [user1]
copy

Note 2:
If the properties hipposys:members and/or hipposys:userroles are not present, the configuration is also valid. These properties are only processed when defined.

Example of Destructive Configuration

If you configure the group mygroup as shown below, any members or user roles added at runtime in production will be replaced on deployment. This is because the properties are defined as config instead of system.

Warning: The following configuration is destructive and should be avoided.

definitions:
  config:
    /hippo:configuration/hippo:groups/mygroup:
      jcr:primaryType: hipposys:group
      hipposys:system: true
      hipposys:members: []
      hipposys:securityprovider: internal
      hipposys:userroles: []
copy

How to Validate Your Configuration

To ensure your project does not contain destructive security configuration, search your local YAML files for the following properties:

• hipposys:members:
• hipposys:userroles:
• hipposys:groups:
• hipposys:users:

When these properties are present, verify that they use the correct .meta classifiers:

hipposys:name-of-property:
  .meta:category: system
  .meta:add-new-system-values: true
  type: string
  value: [val1, val2, val3]
copy

For more information, see System Properties with Initial Value(s).