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 file, 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:\MyIRIS, you might have the following CPFs:
C:\MyIRIS\iris.cpf ; default CPF C:\MyIRIS\production.cpf ; for production C:\MyIRIS\development.cpf ; for development C:\MyIRIS\testapps.cpf ; for testing C:\MyIRIS\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.
Creating and Using a CPF Merge File
On UNIX® and Linux, you can modify the default iris.cpf using a declarative CPF merge file. A merge file is a partial CPF that sets the desired values for any number of parameters upon instance startup. The CPF merge operation works only once for each instance.
In InterSystems IRIS version 2020.1, the CPF merge feature is part of durable %SYS. However, the specified CPF merge file must not be located in the durable %SYS directory (although it can be located on the same mounted volume as the durable %SYS directory.
Durable %SYS is a container feature that persistently stores instance-specific data outside the container, and has no application for noncontainerized instances other than CPF merge.
CPF merge is useful for a number of purposes. For InterSystems IRIS containers, the opportunity to use a merge file is typically during deployment, as containerized instances usually deploy with durable %SYS. A merge file lets you specify individual settings for instances deployed from the same source, supporting automated deployment and a DevOps approach. Noncontainerized instances also support automated deployment with CPF merge, but can instead use CPF merge to automatically reconfigure the CPF at a later time; simply restart a group of instances using a merge file that specifies the desired changes.
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; 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.
See the section below for an example of using a merge file. For more information about using a merge file when deploying InterSystems IRIS containers, see Deploying Customized InterSystems IRIS Instances in Running InterSystems Products in Containers. For information about using a merge file with ICM, see the Deploying with Customized InterSystems IRIS Configurations section of the “ICM Reference” chapter in InterSystems Cloud Manager Guide.
CPF Merge Example
This example describes how to use a merge file 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.
In a noncontainerized instance, you must specify the durable %SYS directory with the ISC_DATA_DIRECTORY in order to use CPF merge. When you do, InterSystems IRIS moves all writable files into that directory, while the other files will remain in the installation directory. As such, for noncontainerized instances you should place durable %SYS in the same parent directory as the installation directory.
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 CPF 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 and ISC_DATA_DIRECTORY set, as in the following script. If the instance uses mirroring, also start the ISCAgent.
When this script runs, durable %SYS moves all writable files for the instance into the directory specified by ISC_DATA_DIRECTORY, then modifies the iris.cpf file as specified in the config_merge.cpf file.
#!/bin/bash # Start the ISCAgent (if using mirroring) sudo systemctl start ISCAgent.service # Start IRIS with the necessary parameters (all on one line). sudo ISC_DATA_DIRECTORY=/intersystems/irisdata ISC_CPF_MERGE_FILE=/intersystems/merge_files/config_merge.cpf iris start IRIS
When the instance starts up, the merge is complete! Check that the iris.cpf file (now located in the durable %SYS directory) 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 InterSystems IRIS startup detects that the configuration parameter file has been modified by a text editor since the last time InterSystems IRIS was started, and if Configuration Security is enabled, InterSystems IRIS startup requests a username and password to validate the changes. The username 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.
For more information on other system-wide security parameters, see the “System Management and Security” chapter in the Security Administration Guide.
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.