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.

Note:

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.

CPF Overview

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.

The default CPF, iris.cpf, is located in the installation directoryOpens in a new tab. There are multiple ways to modify the CPF, as described in the Editing the Active CPF section of this chapter.

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.

CPF Format

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.

Blank Space

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.

Section Headings

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:

[Devices]

All lines after the section heading, up to the next section name (or the end of file), are in the same section.

Parameters

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:

keyword=value

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.

Important:

Beginning with version 2022.1.1 of InterSystems IRIS, setting a parameter equal to empty quotes (parameter="") sets its value to the empty string, or no value. (In previous versions, doing so set the parameter to its default value.) You cannot set a required parameter to the empty string, so setting such a parameter to empty quotes results in an error.

Comments

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.

Sample CPF

A sample default CPF, installed as part of InterSystems IRIS version 2022.3, is shown in the following. Note, for example, the system databases defined in the [Databases] section, the default superserver and webserver ports (1972 and 52773, respectively) in the values for DefaultPort and WebServerPort parameters in the [Startup] section, and the initial memory settings such as globals in the [Config] section.

[ConfigFile]
Product=IRIS
Version=2022.3

[Databases]
IRISSYS=C:\InterSystems\20223-604-JAN27\Mgr\
IRISLIB=C:\InterSystems\20223-604-JAN27\Mgr\irislib\
IRISTEMP=C:\InterSystems\20223-604-JAN27\Mgr\iristemp\
IRISLOCALDATA=C:\InterSystems\20223-604-JAN27\Mgr\irislocaldata\
IRISAUDIT=C:\InterSystems\20223-604-JAN27\Mgr\irisaudit\
ENSLIB=C:\InterSystems\20223-604-JAN27\Mgr\enslib\
USER=C:\InterSystems\20223-604-JAN27\Mgr\user\

[Namespaces]
%SYS=IRISSYS
USER=USER

[MirrorMember]
AgentAddress=
AsyncMemberGUID=
AsyncMemberType=0
AsyncUseSystemPurgeInterval=0
JoinMirror=0
SystemName=
ValidatedMember=0
VirtualAddressInterface=

[Journal]
AlternateDirectory=C:\InterSystems\20223-604-JAN27\Mgr\journal\
BackupsBeforePurge=2
CompressFiles=1
CurrentDirectory=C:\InterSystems\20223-604-JAN27\Mgr\journal\
DaysBeforePurge=2
FileSizeLimit=1024
FreezeOnError=0
JournalFilePrefix=
JournalcspSession=0

[Startup]
CallinHalt=1
CallinStart=1
CliSysName=
DBSizesAllowed=8192
DefaultPort=51801
DefaultPortBindAddress=
EnableVSSBackup=1
EnsembleAutoStart=1
ErrorPurge=30
FIPSMode=0
IPv6=0
JobHalt=1
JobServers=0
JobStart=1
LicenseID=
MaxConsoleLogSize=5
MaxIRISTempSizeAtStart=0
PasswordHash=
ProcessHalt=1
ProcessStart=1
ShutdownTimeout=300
SystemHalt=1
SystemMode=
SystemStart=1
TempDirectory=Temp
TerminalPrompt=8,2
WebServer=1
WebServerName=
WebServerPort=52801
WebServerURLPrefix=
ZSTU=1

[WorkQueues]
Default=
SQL=

[Gateways]
%DotNet Server=.NET,53301,%Gateway_Object,N6.0
%IntegratedML Server=ML,53501,%Gateway_ML
%JDBC Server=JDBC,53701,%Gateway_SQL,,,,,,,0
%Java Server=Java,53201,%Gateway_Object
%Python Server=Python,53401,%Gateway_Object
%R Server=R,53801,%Gateway_Object
%XSLT Server=XSLT,53601,%Gateway_Object,,,,,,,0

[DeviceSubTypes]
C-ANSI=80^#,$C(27,91,72,27,91,74)^25^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^$C(27,91,72,27,91,74)^$C(8,32,8)
C-IRIS Terminal=80^#,$C(27,91,72,27,91,74)^24^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^$C(27,91,72,27,91,74)^$C(8,32,8)
C-TV925=80^#,$C(27,44)^24^$C(8)^W $C(27,61,DY+32,DX+32) S $X=DX,$Y=DY^^^$C(27,44)^$C(8,32,8)
C-VT100=80^#,$C(27,91,72,27,91,74)^24^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^^
C-VT101W=132^#,$C(27,91,72,27,91,74)^14^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^^
C-VT132=132^#,$C(27,91,72,27,91,74)^24^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^^
C-VT220=80^#,$C(27,91,72,27,91,74)^24^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^$C(27,91,72,27,91,74)^$C(8,32,8)
C-VT240=80^#,$C(27,91,72,27,91,74)^24^$C(8)^W $C(27,91)_(DY+1)_";"_(DX+1)_"H" S $X=DX,$Y=DY^$C(27,91,74)^$C(27,91,75)^$C(27,91,72,27,91,74)^$C(8,32,8)
C-VT52=80^#,$C(27,72)^24^$C(8)^W $C(27,89,DY+32,DX+32) S $X=DX,$Y=DY^^^^
M/UX=255^#^66^$C(8)^^^^^
MAIL=132^#^11^$C(8)^^^^^
P-DEC=132^#^66^$C(8)^^^^^
PK-DEC=150^#^66^$C(8)^^^^^
PK-QUME=150^#^66^$C(8)^^^^^

[Devices]
0=0^TRM^C-IRIS Terminal^^^^Principal device^
2=2^SPL^PK-DEC^^^^Spool LA120^
47=47^MT^M/UX^^("auv":0:2048)^^Magnetic tape^
48=48^MT^M/UX^^("avl":0:2048)^^Magnetic tape^
57=57^BT^M/UX^^("auv":0:2048)^^Magnetic tape^
58=58^BT^M/UX^^("avl":0:2048)^^Magnetic tape^
SPOOL=2^SPL^PK-DEC^^^^Spool LA120^
TERM=0^TRM^C-IRIS Terminal^^^^Windows Console^
|LAT|=0^TRM^C-VT220^^^^Principal device^
|PRN|=|PRN|^OTH^P-DEC^^"W"^^Windows Printer^
|TNT|=0^TRM^C-VT220^^^^Principal device^
|TRM|=0^TRM^C-IRIS Terminal^^^^Windows Console^

[MagTapes]
47=\\.\TAPE0
48=\\.\TAPE1
57=\\.\TAPE0
58=\\.\TAPE1

[config]
LibPath=
MaxServerConn=1
MaxServers=2
Path=
PythonPath=
bbsiz=-1
console=,
errlog=500
globals=0,0,0,0,0,0
gmheap=37568
history=500
ijcbuff=512
ijcnum=16
jrnbufs=64
locksiz=16777216
memlock=0
netjob=1
nlstab=50
overview=Windows (Intel)~Windows
pijdir=
routines=0
targwijsz=0
udevtabsiz=24576
wijdir=
zfheap=0,0

[Miscellaneous]
AsyncDisconnectErr=0
AsynchError=1
BreakMode=1
CollectResourceStats=0
DisconnectErr=0
FileMode=0
GlobalKillEnabled=1
IEEEError=1
LicenseAltHeaders=0
LineRecall=1
ListFormat=0
LogRollback=0
MVDefined=0
NodeNameInPid=0
NullSubscripts=0
OldZU5=0
OpenMode=0
PopError=0
RefInKind=0
ScientificNotation=1
SetZEOF=0
ShutDownLogErrors=0
StopID=0
SwitchOSdir=0
SynchCommit=0
TelnetNUL=0
TruncateOverflow=0
Undefined=0
UseNagleAlgorithm=0
ViewPastData=0
ZDateNull=0
ZaMode=0

[ECP]
ClientReconnectDuration=1200
ClientReconnectInterval=5
ServerTroubleDuration=60

[Cluster]
CommIPAddress=
JoinCluster=0

[LicenseServers]
LOCAL=127.0.0.1,4002

[Monitor]
SNMPEnabled=0

[IO]
File=^%X364
MagTape=^%XMAG
Other=^%X364
Terminal=^%X364

[SQL]
ANSIPrecedence=1
AdaptiveMode=1
AllowRowIDUpdate=0
AutoParallel=1
AutoParallelThreshold=3200
BiasQueriesAsOutlier=0
Comment=1
DBMSSecurity=1
DDLDefineBitmapExtent=1
DDLFinal=1
DDLNo201=0
DDLNo30=0
DDLNo307=0
DDLNo311=0
DDLNo315=0
DDLNo324=0
DDLNo333=0
DDLSQLOnlyCompile=0
DDLUseExtentSet=1
DDLUseSequence=1
DefaultSchema=SQLUser
DelimitedIds=1
DropDelete=1
ECPSync=0
ExtrinsicFunctions=0
FastDistinct=1
IdKey=1
IdTrxFrom=~ `!@#$%^&*()_+-=[]\{}|;':",./<>?
IdTrxTo=
LockThreshold=1000
LockTimeout=10
ODBCVarcharMaxlen=4096
ParameterSampling=0
QueryProcedures=0
RTPC=1
ReferentialChecks=1
SaveMAC=0
TCPKeepAlive=300
TODATEDefaultFormat=DD MON YYYY
TimePrecision=0

[SqlSysDatatypes]
BIGINT=%Library.BigInt
BIGINT(%1)=%Library.BigInt
BINARY=%Library.Binary(MAXLEN=1)
BINARY VARYING=%Library.Binary(MAXLEN=1)
BINARY VARYING(%1)=%Library.Binary(MAXLEN=%1)
BINARY(%1)=%Library.Binary(MAXLEN=%1)
BIT=%Library.Boolean
BLOB=%Stream.GlobalBinary
CHAR=%Library.String(MAXLEN=1)
CHAR VARYING=%Library.String(MAXLEN=1)
CHAR VARYING(%1)=%Library.String(MAXLEN=%1)
CHAR(%1)=%Library.String(MAXLEN=%1)
CHARACTER=%Library.String(MAXLEN=1)
CHARACTER VARYING=%Library.String(MAXLEN=1)
CHARACTER VARYING(%1)=%Library.String(MAXLEN=%1)
CHARACTER(%1)=%Library.String(MAXLEN=%1)
CLOB=%Stream.GlobalCharacter
DATE=%Library.Date
DATETIME=%Library.DateTime
DATETIME2=%Library.DateTime
DEC=%Library.Numeric(MAXVAL=999999999999999,MINVAL=-999999999999999,SCALE=0)
DEC(%1)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,0)'|>,MINVAL=<|'$$minval^%apiSQL(%1,0)'|>,SCALE=0)
DEC(%1,%2)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,%2)'|>,MINVAL=<|'$$minval^%apiSQL(%1,%2)'|>,SCALE=%2)
DECIMAL=%Library.Numeric(MAXVAL=999999999999999,MINVAL=-999999999999999,SCALE=0)
DECIMAL(%1)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,0)'|>,MINVAL=<|'$$minval^%apiSQL(%1,0)'|>,SCALE=0)
DECIMAL(%1,%2)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,%2)'|>,MINVAL=<|'$$minval^%apiSQL(%1,%2)'|>,SCALE=%2)
DOUBLE=%Library.Double
DOUBLE PRECISION=%Library.Double
FLOAT=%Library.Double
FLOAT(%1)=%Library.Double
IMAGE=%Stream.GlobalBinary
INT=%Library.Integer(MAXVAL=2147483647,MINVAL=-2147483648)
INT(%1)=%Library.Integer(MAXVAL=2147483647,MINVAL=-2147483648)
INTEGER=%Library.Integer(MAXVAL=2147483647,MINVAL=-2147483648)
LONG=%Stream.GlobalCharacter
LONG BINARY=%Stream.GlobalBinary
LONG RAW=%Stream.GlobalBinary
LONG VARCHAR=%Stream.GlobalCharacter
LONG VARCHAR(%1)=%Stream.GlobalCharacter
LONGTEXT=%Stream.GlobalCharacter
LONGVARBINARY=%Stream.GlobalBinary
LONGVARBINARY(%1)=%Stream.GlobalBinary
LONGVARCHAR=%Stream.GlobalCharacter
LONGVARCHAR(%1)=%Stream.GlobalCharacter
MEDIUMINT=%Library.Integer(MAXVAL=8388607,MINVAL=-8388608)
MEDIUMINT(%1)=%Library.Integer(MAXVAL=8388607,MINVAL=-8388608)
MEDIUMTEXT=%Stream.GlobalCharacter
MONEY=%Library.Currency
NATIONAL CHAR=%Library.String(MAXLEN=1)
NATIONAL CHAR VARYING=%Library.String(MAXLEN=1)
NATIONAL CHAR VARYING(%1)=%Library.String(MAXLEN=%1)
NATIONAL CHAR(%1)=%Library.String(MAXLEN=%1)
NATIONAL CHARACTER=%Library.String(MAXLEN=1)
NATIONAL CHARACTER VARYING=%Library.String(MAXLEN=1)
NATIONAL CHARACTER VARYING(%1)=%Library.String(MAXLEN=%1)
NATIONAL CHARACTER(%1)=%Library.String(MAXLEN=%1)
NATIONAL VARCHAR=%Library.String(MAXLEN=1)
NATIONAL VARCHAR(%1)=%Library.String(MAXLEN=%1)
NCHAR=%Library.String(MAXLEN=1)
NCHAR(%1)=%Library.String(MAXLEN=%1)
NTEXT=%Stream.GlobalCharacter
NUMBER=%Library.Numeric(SCALE=0)
NUMBER(%1)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1)'|>,MINVAL=<|'$$minval^%apiSQL(%1)'|>,SCALE=0)
NUMBER(%1,%2)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,%2)'|>,MINVAL=<|'$$minval^%apiSQL(%1,%2)'|>,SCALE=%2)
NUMERIC=%Library.Numeric(MAXVAL=999999999999999,MINVAL=-999999999999999,SCALE=0)
NUMERIC(%1)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,0)'|>,MINVAL=<|'$$minval^%apiSQL(%1,0)'|>,SCALE=0)
NUMERIC(%1,%2)=%Library.Numeric(MAXVAL=<|'$$maxval^%apiSQL(%1,%2)'|>,MINVAL=<|'$$minval^%apiSQL(%1,%2)'|>,SCALE=%2)
NVARCHAR=%Library.String(MAXLEN=1)
NVARCHAR(%1)=%Library.String(MAXLEN=%1)
NVARCHAR(%1,%2)=%Library.String(MAXLEN=%1)
NVARCHAR(MAX)=%Stream.GlobalCharacter
POSIXTIME=%Library.PosixTime
RAW(%1)=%Library.Binary(MAXLEN=%1)
REAL=%Library.Double
ROWVERSION=%Library.RowVersion
SERIAL=%Library.Counter
SMALLDATETIME=%Library.DateTime(MINVAL="1900-01-01 00:00:00",MAXVAL="2079-06-06 23:59:59")
SMALLINT=%Library.SmallInt
SMALLINT(%1)=%Library.SmallInt
SMALLMONEY=%Library.Currency
SYSNAME=%Library.String(MAXLEN=128)
TEXT=%Stream.GlobalCharacter
TIME=%Library.Time
TIME(%1)=%Library.Time(PRECISION=%1)
TIMESTAMP=%Library.PosixTime
TIMESTAMP2=%Library.TimeStamp
TINYINT=%Library.TinyInt
TINYINT(%1)=%Library.TinyInt
UNIQUEIDENTIFIER=%Library.UniqueIdentifier
VARBINARY=%Library.Binary(MAXLEN=1)
VARBINARY(%1)=%Library.Binary(MAXLEN=%1)
VARCHAR=%Library.String(MAXLEN=1)
VARCHAR(%1)=%Library.String(MAXLEN=%1)
VARCHAR(%1,%2)=%Library.String(MAXLEN=%1)
VARCHAR(MAX)=%Stream.GlobalCharacter
VARCHAR2(%1)=%Library.String(MAXLEN=%1)

[Telnet]
DNSLookup=ON
Port=23

[Conversions]
LastConvertTime=2023-01-26 17:43:44

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 directoryOpens in a new tab, 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 nodesOpens in a new tab, 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 mirrorOpens in a new tab, 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.

Important:

When a container is deployed with configuration merge using the ISC_CPF_MERGE_FILE environment variable to specify the merge file, that file is continuously monitored for updates, which are immediately merged when they occur, as long as the container is running. This means that you can update the configuration of a containerized instance at any time simply by updating the merge file. For more information, see How do I reconfigure an existing instance using configuration merge?Opens in a new tab in Automating Configuration of InterSystems IRIS with Configuration Merge.
Use the iris merge commandOpens in a new tab 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 a description of the command syntax, see How do I reconfigure an existing instance using configuration merge?.

Note:

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.

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 Automating Configuration of InterSystems IRIS with Configuration MergeOpens in a new tab. For information about using a merge file with InterSystems Cloud Manager (ICM), see Deploying with Customized InterSystems IRIS ConfigurationsOpens in a new tab 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 themOpens in a new tab in Using the InterSystems Kubernetes Operator.

Configuration Merge Example

This example describes how to use a merge file at startup to modify the shared memory heapOpens in a new tab and the database cacheOpens in a new tab 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
...

Note:

If the merge file specified by ISC_CPF_MERGE_FILE is not present, instance startup displays an error message and continues.

Configuration Security

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.
Abort startup.

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.

Note:

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.

Parameter Descriptions

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.

[Actions]