Reconfigure an existing instance using configuration merge

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 PortalOpens in a new tab, 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, which can be used on both UNIX/Linux and Windows systems, applies a merge file to a running instance. For Windows operating systems, it requires OS authentication to execute. 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 absolute or relative 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 absolute or relative path to 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.

  • If the environment variables ISC_DATA_DIRECTORY and ISC_PACKAGE_INSTALLDIR are not set and target-CPF is not specified, InterSystems IRIS checks for the location of target-CPF in the operating system registry.

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 all three of the following conditions: 1) the target location is not specified, 2) neither ISC_DATA_DIRECTORY or ISC_PACKAGE_INSTALLDIR exist and 3) the operating system registry does not have the path for target-CPF defined.

After entering the command, an InterSystems IRIS terminal prompts for you to supply a username and password (if OS authentication is not enabled). Only once authentication succeeds does the command complete execution. On an unsuccessful merge, the terminal indicates which line the merge failed on and you can press any key to close the window. On a successful merge, the success message displays for three (3) seconds before the window closes automatically.

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.