How do I reconfigure an existing instance using configuration merge?

How do I reconfigure an existing instance using configuration merge?

By automating application of the same merge file to multiple running instances, you can simultaneously reconfigure all of those instances in the same way, applying the same set of configuration changes across your application or cluster. You can avoid updating settings that may have been customized on a per-instance basis and should not be modified simply by omitting these from the merge file, while including only those you know it is safe and desirable to change. A single automated program can of course apply different merge files to different groups of instances (such as different mirror member or cluster nodes types) as described in the previous section.

Applying all configuration changes with a merge file helps you streamline the process of making changes and maintain greater control over the instance’s configuration. Rather than making numerous individual changes from the Terminal, on multiple pages of the Management Portal, or by editing an instance’s CPF manually, you can execute all the changes at once using identical syntax in a merge file. By keeping your merge files under version control, you ensure the availability of configuration history and the option of restoring a previous configuration.

The iris merge command applies a merge file to a running instance. It is executed as follows:

iris merge instance [merge-file] [target-CPF]

where:

• instance is the name of the InterSystems IRIS instance.

• merge-file is the path to the merge file, including the filename. If merge-file is not specified, the value of the ISC_CPF_MERGE_FILE environment variable is used, if it is set.

• target-CPF is the location of the active CPF for instance instance, which is assumed to be named iris.cpf. If target-CPF is not specified, the defaults are as follows:

  • For noncontainerized instances, the iris.cpf file located in the directory specified by the ISC_PACKAGE_INSTALLDIR environment variable, if it is set. For most existing instances, this variable is not set, and you must explicitly specify the location of the target CPF.

  • For containerized instances, the iris.cpf file located in the directory specified by the ISC_DATA_DIRECTORY environment variable or, if it is not set (because durable %SYS is not in use), the ISC_PACKAGE_INSTALLDIR environment variable, which is always set in an InterSystems IRIS container.

No merge is performed if:

• The specified merge file is not present, or the merge-file argument is omitted and ISC_CPF_MERGE_FILE does not exist.

• There is no CPF in the specified target location, or if the target location is not specified and neither ISC_DATA_DIRECTORY or ISC_PACKAGE_INSTALLDIR exists.

An exit code of 3 indicates a successful merge.

Some changes merged into a CPF will not take effect immediately, but require a restart. For example, a change in the value of the gmheapOpens in a new tab parameter, which determines the size of the instance’s shared memory heap, does not take effect until the instance is restarted. When your merge file contains one or more such parameters, you may need to apply the merge file as part of a restart, as in the following sample script excerpt:

# restart instance with  the necessary parameters (all on one line)
sudo ISC_CPF_MERGE_FILE=/net/merge_files/config_merge.cpf iris stop IRIS restart

On the other hand, applying a merge file with the iris merge command lets you immediately change settings that do not require a restart, including those that cannot be set during instance startup; an example, as noted in Can configuration merge customize more than the configuration?, is adding a database to an existing mirror.