Parameterized XML Configuration¶

When working with the configuration in XML form, the same XML can be re-used between different environments by parameterizing parts of the configuration. Values such as urls, and hostnames change between environments, and makes good sense to parameterize if using the XML configuration files.

Any value in the XML can be replaced with a parameter on the format #{variableName} or #{variableName | defaultValue}

The variable is then searched for in the environment of the Curity process. If the variable is not found in the environment and a default value exists, then that default value is used instead. Otherwise the configuration processing ends with an error.

Example:¶

Listing 335 A parameterized value¶

<base-url>#{baseUrl}</base-url>

When the XML is placed in the init directory $IDSVR_HOME/etc/init it will be pre-processed before loaded into the running system. The pre-processor replaces all occurrence of parameters with the value found in the environment or with the default value. If a variable is not found in the process environment and does not have a default value, then the configuration cannot be loaded. If this happens during boot, Curity will stop and exit.

The parameterized configuration can be exported in XML format as well. It is possible to export the configuration with or without the parameters, using the appropriate flag for the idsvr command. When executing:

$ idsvr -d

then the configuration will be exported with the actual values instead of the parameters. On the contrary, when the configuration needs to be exported with the configuration parameters, then the -D flag should be used. As shown in the listing above, the -D would have been used to export the configuration parameter with the depicted format.

Both -d and -D options can take a configuration path as an optional argument in order to export only this part of the configuration.

For instance:

$ idsvr -D environments/environment/base-url

will only export the configuration segment for the path environments/environment/base-url and since the -D flag is used, then the configuration will contain the configuration parameters and will be similar to the listing below.

Listing 336 A parameterized value after being exported with a specific path as parameter¶

<config xmlns="http://tail-f.com/ns/config/1.0">
  <environments xmlns="https://curity.se/ns/conf/base">
  <environment>
    <base-url>#{baseUrl}</base-url>
  </environment>
  </environments>
</config>

Default Values¶

If a variable isn’t defined in the environment and a default value should be used, it is possible to set this using a pipe-like syntax. In particular, after the variable name, but inside the braces, add a pipe followed by the default value. As an example, assume that the baseUrl variable shown in Listing 336 above should have a default value of https://login.example.com. This could be achieved by altering the macro slightly to have a pipe after the name and then this default value as shown in the following, abbreviated listing:

Listing 337 A parameterized value with a default that should be used when the variable is not defined.¶

<environment>
    <base-url>#{baseUrl | https://login.example.com}</base-url>
</environment>

Using startup.properties¶

Instead of placing variable values in the process environment, the variables can be placed in startup.properties. This will have the same result as placing them in the environment. startup.properties takes precedence over the process environment.

Important

Parameterized configuration cannot be loaded using the REST or RESTCONF APIs. Currently it’s only possible to load these via the $IDSVR_HOME/etc/init directory.