Introduction to the Configuration Parameter File
When InterSystems IRIS® data platform starts, it reads configuration values from the configuration parameter file (CPF), iris.cpf. This file defines the particular InterSystems IRIS configuration for each instance.
This topic discusses how to use and edit the CPF. The “Table of Contents” at the beginning of this reference shows each parameter in the CPF, sorted by section.
Within this document and the CPF itself, memory is depicted as powers of two. For example, a kilobyte (KB) means 1024 bytes, and a megabyte (MB) means 1024 KB.
The configuration parameter file, also called the CPF, defines an InterSystems IRIS Configuration. On startup, InterSystems IRIS reads the CPF to obtain the values for most of its settings.
InterSystems IRIS creates multiple backups of the CPF. Once per day, if the iris.cpf file is modified, InterSystems IRIS creates a backup in the same directory called iris.cpf_yyyymmdd. These backups are automatically purged after one year. Additionally, after a successful startup or shutdown, a copy of the CPF is saved in the installation directory as _LastGood_.cpf, which represents the most recent valid configuration.
A configuration parameter file is a line-oriented, UTF-8 text file with a .cpf extension. Each line ends with a carriage return and line feed. Long items cannot be continued on a following line. A line in the file is one of the following elements:
Blank Space – An empty line made up of zero or more spaces.
Section Heading – The name of a file section enclosed in square brackets .
Parameter – An InterSystems IRIS configuration parameter and its value(s).
Comment – A comment added by a user.
In general, spaces at the beginning and end of lines are without effect. Spaces within the line are usually significant. The best practice is to use no spaces in the line except where they are meaningful components of strings.
Related settings are collected into sections. The beginning of a section is marked by a line consisting of the name of the section enclosed in square brackets. For example:
All lines after the section heading, up to the next section name (or the end of file), are in the same section.
Each line beneath a section heading is the definition of a parameter. Each parameter line uses the following syntax, where keyword is a parameter name and value is a string:
When there is a set of similar items to configure, they may be displayed as keyword_#. Examples include namespaces, databases, devices, and anything else of which there is a group or set of similar items to configure, one per line. The syntax is:
keyword_1=value keyword_2=value keyword_n=value
The syntax for the value string varies widely from parameter to parameter. The string may indicate true or false using 1 or 0; it may be a number of bytes, or a number of megabytes; it may be a single value, or it may contain multiple values separated by a delimiter character on the same line. If there is a delimiter within the string, it may be a comma, semicolon, tilde (~), slash (/), colon, or some combination of these, depending on the parameter.
The CPF supports comments. These can appear on a single line or across multiple lines. Comments can start at the beginning of the line or after other content on a line.
To introduce a single-line comment use “;” (semicolon), “#” (pound sign), or “//” (two slashes).
To introduce a multiline comment, use “/*” (slash, asterisk) to begin the commend and “*/” (asterisk, slash) to end it.
Editing the Active CPF
There are multiple ways to interact with the CPF, including through the Management Portal, API calls, or a text editor. For instructions on how to change a specific parameter, review the Changing This Parameter section of the reference page for that parameter. Some changes may require the instance to be restarted to take effect.
When using a text editor to modify the CPF, you must first shut down the instance. Open the iris.cpf file, located in the installation directory, and make the desired changes. InterSystems recommends that you save a backup copy of the CPF before editing it, as an invalid CPF may cause InterSystems IRIS to fail to start. Be sure to follow the syntax described in the CPF Format section of this chapter.
You can specify the CPF for InterSystems IRIS to use with the iris start command, or you can create a partial CPF to merge into iris.cpf during deployment on UNIX® and Linux systems. These options are described in the following sections:
Choosing a CPF at Startup
If you frequently switch between two or more InterSystems IRIS configurations, such as for development and testing purposes, you can create distinct CPFs for these purposes. When starting InterSystems IRIS, you can specify which .cpf file to use to reduce time spent manually changing settings.
For example, on Windows, if the InterSystems IRIS installation directory is C:\IRIS, you might have the following CPFs:
C:\IRIS\iris.cpf ; default CPF C:\IRIS\production.cpf ; for production C:\IRIS\development.cpf ; for development C:\IRIS\testapps.cpf ; for testing C:\IRIS\iris_customerbug.cpf ; for troubleshooting
To use a different CPF, you must first stop InterSystems IRIS. Then, start the instance with the iris start command, specifying the full path of the CPF InterSystems IRIS should use. The iris start command is described in the Controlling an InterSystems IRIS Instance section of the “Using Multiple Instances of InterSystems IRIS” chapter in System Administration Guide.
At shutdown, the instance automatically saves the last known error-free configuration to a file called _LastGood_.cpf in the installation directory. You can use this file, if you need to, for recovery purposes.
Using the Configuration Merge Feature
On UNIX® and Linux, you can modify the default iris.cpf using a declarative configuration merge file. A merge file is a partial CPF that sets the desired values for any number of CPF parameters.
Configuration merge is useful for a number of purposes. A merge file lets you specify individual settings for instances deployed from the same source, supporting automated deployment and a DevOps approach. You can use configuration merge with containerized and noncontainerized InterSystems IRIS instances by doing one of the following:
At instance startup or restart, set the environment variable ISC_CPF_MERGE_FILE to the path of the configuration merge file to be applied; the existence of the variable triggers the operation, which uses the indicated merge file to modify the instance’s CPF before it starts.
Configuration merge is very useful in automated deployment because it makes the specified configuration changes before the new instance first starts, allowing you to customize the configurations of multiple instances deployed from the same container image or install kit. Automated deployment of multinode topologies can use multiple merge files to customize different groups of instances; for example, in automated deployment of a sharded cluster with compute nodes, you would apply different merge files for data node 1, the remaining data nodes, and the compute nodes in that order, and when deploying a mirror, you would apply different merge files for the primary, backup, and async members.
Automated reconfiguration of multiple instances can be achieved in the same way, by restarting groups of instances specifying the applicable merge file for each.
Use the iris merge command to specify the instance you want to reconfigure, the merge file to apply, and the CPF to modify. By default, the merge file is that specified by ISC_CPF_MERGE_FILE (if it exists) and the CPF is the instance’s current iris.cpf file, but you can specify both files on the command line, for example:
iris merge IRIS applies the merge file specified by ISC_CPF_MERGE_FILE to the instance named IRIS.
iris merge IRIS/tmp/merge.cpf applies the merge file /tmp/merge.cpf to the instance named IRIS.
iris merge IRIS/tmp/merge.cpf install-dir/iriscpf_copy.cpf applies the merge file /tmp/merge.cpf to a copy of the iris.cpf file in the installation directory of the instance named IRIS.
Some configuration changes take effect only at startup and thus, if specified in a merge file used with iris merge, will not take effect until the instance is restarted.
If the specified merge file is not present, an error message is displayed and startup continues or the command terminates with no result.
A merge file has the same syntax as a CPF (described in the CPF Format section), and can have any name and extension. The merge file may contain any of the parameters found within the CPF, though it is not necessary to include the values you are not changing.
Unlike the CPF, a merge file can contain duplicates of the same section and parameter. In this case, InterSystems IRIS prioritizes the value closer to the end of the file, which allows you to create a template merge file. For example, if you keep generally desired values at the top of the file and append instance-specific values at the bottom, InterSystems IRIS will prioritize the instance-specific values when reading the merge file.
For an example of using a merge file, see the section that follows. For more information about using a merge file when deploying InterSystems IRIS containers, see Using Configuration Merge to Deploy and Reconfigure InterSystems IRIS. For information about using a merge file with InterSystems Cloud Manager (ICM), see Deploying with Customized InterSystems IRIS Configurations in the InterSystems Cloud Manager Guide; for information about using a merge file with the InterSystems Kubernetes Operator (IKO), see configSource: Create configuration files and a config map for them in Using the InterSystems Kubernetes Operator.
Configuration Merge Example
This example describes how to use a merge file at startup to modify the generic memory heap and the database cache in a noncontainerized instance. These settings are controlled by the gmheap and globals parameters respectively.
The first step is to create the merge file. The example file below in named config_merge.cpf, though any name or extension is valid. Note that the merge file uses the same syntax as a CPF.
# Example configuration merge file. [config] globals=0,0,800,0,0,0 gmheap=256000
Next, use the iris stop command to shut down the target instance for the merge.
$ sudo iris stop IRIS
Finally, restart the instance with ISC_CPF_MERGE_FILE set, as in the following script.
When this script runs, InterSystems IRIS modifies the iris.cpf file as specified in the config_merge.cpf file.
#!/bin/bash # Start InterSystems IRIS with the necessary parameters (all on one line). sudo ISC_CPF_MERGE_FILE=/merge_files/config_merge.cpf iris start IRIS
When the instance starts up, the merge is complete! Check that the iris.cpf file contains the desired values for the gmheap and globals settings.
[config] ... errlog=500 globals=0,0,800,0,0,0 gmheap=256000 history=500,1024 ...
If the merge file specified by ISC_CPF_MERGE_FILE is not present, instance startup displays an error message and continues.
To protect against accidental or intentional misconfiguration of the CPF, you can enable Configuration Security. This option is available on the System-wide Security Parameters page of the Management Portal (System Administration > Security > System Security > System-wide Security Parameters).
When Configuration Security is enabled, if InterSystems IRIS startup detects that the configuration parameter file has been modified since the last time InterSystems IRIS was started, InterSystems IRIS startup requests a username and password to validate the changes. The user account supplied must have %Admin_Manage:Use privileges. If the appropriate username and password cannot be provided, InterSystems IRIS allows the operator to choose as follows:
Re-enter the username and password.
Start using the last known good configuration.
If the operator chooses option 2, InterSystems IRIS renames the parameter file that was invoked at startup (file.cpf) with the suffix _rejected (file.cpf_rejected). InterSystems IRIS then overwrites the file.cpf with the last known good configuration (_LastGood_.cpf) and starts up using this configuration.
This Configuration Security setting is not a substitute for operating-system–level security. InterSystems recommends that you protect the configuration file by strictly limiting the ability of users to modify it, at the operating-system level.
For more information on other system-wide security parameters, see System Management and Security.
Each parameter reference page in this book includes most of the following sections:
Synopsis – The CPF section that contains this parameter, followed by a summary of its syntax. Beneath this, a description of valid inputs and the default value.
Description – A formal description of the parameter. May include examples of valid inputs or guidelines for choosing values.
Changing this Parameter – The various ways to change this parameter, either programmatically or using the browser-based Management Portal.
See Also – Links to related parameters and relevant documentation.