Skip to main content

Automating Configuration of InterSystems IRIS with Configuration Merge

This document explains how to use configuration merge to deploy or reconfigure InterSystems IRIS.

What is configuration merge?

The configuration merge feature lets you make as many changes as you wish to the configuration of any InterSystems IRIS® instance in a single operation. To use it, you simply record the changes you want to make in a declarative configuration merge file and apply that file to the instance, when it is deployed or at any later point. Configuration merge can easily be used to automatically deploy multiple instances with varying configurations from the same container image or kit, as well as to simultaneously reconfigure multiple running instances, enabling automated reconfiguration of clusters or other multi-instance deployments. Configuration merge can be used with any InterSystems IRIS instance, containerized or locally installed, on any supported UNIX® or Linux platform, including Linux cloud nodes.

For examples of using Docker Compose to deploy containers with configuration merge, including creating a namespace and database and deploying out-of-the-box InterSystems IRIS topologies such as mirrors and sharded clusters, see Useful Parameters in Automated Deployment. The Configuration Parameter File ReferenceOpens in a new tab contains a comprehensive description of all InterSystems IRIS configuration parameters.

How is InterSystems IRIS configured?

The configuration of an InterSystems IRIS instance is determined by a file in its installation directory named iris.cpf, which contains configuration parameters as name/value pairs. Every time the instance starts, including for the first time after it is deployed, it reads this configuration parameter file, or CPF, to obtain the values for these settings. This allows you to reconfigure an instance at any time by modifying its CPF and then restarting it.

For example, the globalsOpens in a new tab setting in the [config] section of the CPF determines the size of the instance’s database cache. The setting in the CPF of a newly installed instance specifies an initial cache size equal to 25% of total system memory, which is not intended for production use. To change the size of the database cache, you can open the instance’s CPF in any text editor and specify the desired cache size as the value of globals, then restart the instance. Most parameters can be changed using other methods; for example, you can also modify the value of globals using the Management PortalOpens in a new tab or using the methods in the persistent class Config.configOpens in a new tab. Updating an instance’s CPF, however, is the only general mechanism that lets you make multiple configuration changes to an instance in a single operation and automate the simultaneous configuration of multiple instances.

For an overview of the use and contents of the CPF, see the Configuration Parameter File ReferenceOpens in a new tab.

How does configuration merge work?

A configuration merge file is a partial CPF that contains any desired subset of InterSystems IRIS configuration parameters and values. When a merge file is applied to an instance with configuration merge, those settings are merged into the instance’s CPF, replacing the values, as if you had edited the CPF and changed the values manually. If a parameter in the merge file is not present in the original CPF, it is simply added in the appropriate place.

For example, the data and compute nodes in a sharded clusterOpens in a new tab typically require with a database cache that is much larger than that generally configured for other purposes, and have more shared memory configured as well. To configure an instance to have a larger database cache and more shared memory when deployed, or to reconfigure an existing instance this way, you can apply a configuration merge file that includes the globals parameter (which specifies the size of the database cache) and the gmheapOpens in a new tab parameter (which specifies the amount of shared memory) with the desired values; these replace the default values in the CPF of the instance. The following illustrates the use of a merge file to update both the parameters when deploying an instance:.

Merge File Updates Memory Settings During Deployment

Can configuration merge customize more than the configuration?

In addition to changing the values of configuration parameters, configuration merge can create, modify, and delete dozens of different InterSystems IRIS objects, such as namespaces and databases, users, roles, and resource, and mirrors and mirror members. This is done using the parameters in the [Actions]Opens in a new tab section, which is valid only in a merge file and does not appear in (and cannot be added to) an instance’s CPF. For example, to add a global mapping to an instance, you would include in the merge file an [Actions] section containing the CreateMapGlobal parameter.

To illustrate the use of [Actions] parameters, suppose you wanted to add to deployed instances a predefined account and password to enable a SQL administrator user who:

  • Has SQL access through the %Service_Bindings service (%SQL role).

  • Can read from or write to the USER database (%DB_USER role).

  • Can create and drop tables, views, procedures, functions, methods, queries, and triggers (%DB_OBJECT_DEFINITION privilege) and use the BUILD INDEX command (%BUILD_INDEX privilege) in the USER namespace.

To do this, you could use the CreateUser parameter to create the user account with password and assign it the needed roles, and the GrantAdminPrivilege parameter to grant it the needed SQL privileges, as follows:

[Actions]
CreateUser:Name=SQLAdmin,
  PasswordHash="cec6638a357e7586fddfb15c0e7dd5719a1964e774cd37466fb0c49c05,
  323cb89148c887166dd2be61c107710539af2c01b43f07dccc8d030ac2c1a8cf7c5ace4a00d57e3780f,10000,SHA512",
  Roles="%SQL,%DB_USER"
GrantAdminPrivilege:Grantee=SQLAdmin,Namespace=USER,AdminPriv="%DB_OBJECT_DEFINITION,%BUILD_INDEX"

As noted in the Server Migration GuideOpens in a new tab, an example of making multiple changes to a newly-deployed or existing instance in a single operation is enabling interoperability for a number of namespaces so interoperability productions can be used in them. To do this, you would use a merge file like the following, containing an entry for each namespace you want to be interoperability enabled:

[Actions]
ModifyNamespace:Name=NamespaceA,Interop=1
ModifyNamespace:Name=NamespaceB,Interop=1
ModifyNamespace:Name=NamespaceC,Interop=1
. . .

The operations specified in [Actions] are idempotent, meaning that they are executed only if they would result in a change — if an object to be created already exists, an object to be deleted does not exist, or an object to be modified already matches the specified change, the operation is skipped. So if you specify in a merge file the creation of a SQLAdmin account, as above, and later repeat the merge with the same file (as discussed in Managing configuration changes), no change is made and therefore no duplication of the account or other conflict results.

The [Actions] parameters can be used to manage objects on both new and existing instances. Using [Startup] and [Actions] parameters in combination can be very helpful in deployment; for example, when deploying a mirror using the [Startup] parameters MirrorSetName, MirrorMember, MirrorPrimary, and ArbiterURL, you can create the same set of mirrored databases (and namespaces associated with them) on the primary, the backup, and any DR asyncs, enabling the new mirror to be fully operational immediately following deployment. On the other hand, when used in reconfiguring an existing instance with the iris merge command, [Actions] parameters can enable you to immediately change settings that cannot be set during instance startup; a notable example is adding a new database to an existing mirror, which must be done on the running primary instance.

The operations performed by the[Actions] parameters are effected by calling methods of classes in the Config and Security packages, the SYS.DatabaseOpens in a new tab class, and the %SYSTEM.SQL.SecurityOpens in a new tab class, as well as two SQL commands.

For a discussion of some ways [Actions] parameters can be used and a link to an example, see Create, Modify, and Delete Database-related Objects and Security Items.

For lists of the [Actions] parameters by object managed, by corresponding class, and in order of processing, as well as by name, see [Actions] Parameter Reference.

How can I use configuration merge?

Their are two primary uses for configuration merge:

Regardless of the specific application of the configuration merge feature, InterSystems recommends keeping the merge files involved under version control to provide a record of all configuration changes, from deployment forward, over the life of an instance or a multi-instance topology.

When you incorporate configuration merge into your automated deployment or reconfiguration process, you can update the process by simply updating the merge files applied. Even in the case of individual instances used for purposes such as development and testing, users can be required get the latest version of the appropriate merge file before deploying or reconfiguring an instance, ensuring that its configuration matches a central specification. With version control, they can even reconfigure to an older standard by selecting a previous version of the merge file.

How do I use configuration merge in deployment?

Applying a configuration merge file during deployment lets you modify the default configurations of the deployed instance before it starts for the first time. This enables you to deploy containers with varying configurations from the same image, or install differently-configured instances from the same kit, directly into a multi-instance topology, rather than having to configure the instances into the desired topology after deployment. For example, in automated containerized deployment of a sharded cluster with compute nodesOpens in a new tab, you can apply different merge files for data node 1, the remaining data nodes, and the compute nodes in that order, as shown in the following illustration; when all of the instances are up and running, so is the sharded cluster.

Automated Deployment of a Sharded Cluster Using Configuration Merge
An InterSystems IRIS image is modified by three different merge files to deploy containers as the three node types of a shard

In similar fashion, when deploying a mirrorOpens in a new tab, you would apply different configuration merge files for the primary, backup, and async members. Even a mirrored sharded cluster is easily deployed using this approach.

Activating configuration merge during deployment requires only that the location of the merge file be specified by the environment variable ISC_CPF_MERGE_FILE, or by the field used for that purpose in one of the InterSystems IRIS automated deployment tools, InterSystems Cloud Manager (ICM) or the InterSystems Kubernetes Operator (IKO). For example, in manual or scripted deployment:

ISC_CPF_MERGE_FILE=/home/user/mergefiles/cmf_090821.cpf

The specific manner in which you specify the merge file depends on the deployment mechanism you are using and whether the instance is containerized or noncontainerized.

Deploying an InterSystems IRIS container with a merge file

When deploying an InterSystems IRIS container, the environment variable can be included in the script or docker-compose.yml file you are using. Examples are shown below.

  • In the following sample deployment script, the merge file specified by ISC_CPF_MERGE_FILE, as well as the license key, are staged on the external volume specified for durable %SYS by ISC_DATA_DIRECTORY so they are accessible inside the container. The option setting ISC_CPF_MERGE_FILE is highlighted.

    #!/bin/bash
    # script for quick demo and quick InterSystems IRIS image testing
    
    # Definitions to toggle_________________________________________
    container_image="intersystems/iris-arm64:2021.1.0.205.0"
    
    # the docker run command
    
    docker run -d 
      -p 9091:1972 
      -p 9092:52773 
      -v /data/durable263:/durable 
      -h iris 
      --name iris 
      --cap-add IPC_LOCK 
      --env ISC_DATA_DIRECTORY=/durable/irisdata
      --env ISC_CPF_MERGE_FILE=/durable/merge/CMF.cpf
      $container_image 
      --key /dur/key/iris.key 
  • This sample docker-compose.yml file uses the iris-main --license-config option to configure the instance as a license server for the licenses staged on the external volume but otherwise contains the same elements as the deployment script; again, the line setting ISC_CPF_MERGE_FILE is highlighted.

    version: '3.2'
    
    services:
      iris:
        image: intersystems/iris-arm64:2021.1.0.205.0
        command: --license-config "4691540832 iris,4002,/durable/licenses" 
        hostname: iris
    
        ports:
        # 1972 is the superserver default port
        - "9091:1972"
        # 52773 is the webserver/management portal port
        - "9092:52773"
    
        volumes:
        - /data/durable263:/durable
    
        environment:
        - ISC_DATA_DIRECTORY=/durable/irisdata
        - ISC_CPF_MERGE_FILE=/durable/merge/CMF.cpf
    

For examples of use cases for automated deployment using configuration merge, see Useful parameters in automated deployment.

Installing InterSystems IRIS from a kit with a merge file

To apply a merge file when installing InterSystems IRIS from a kit, manually or in a script, you must separate installation from startup, using these steps:

  1. Install the instance without starting it by preceding the irisinstallOpens in a new tab or irisinstall_silentOpens in a new tab script with the ISC_PACKAGE_STARTIRIS parameter, as follows:

    ISC_PACKAGE_INSTANCENAME="IRIS27" ISC_PACKAGE_STARTIRIS="N" /tmp/iriskit/irisinstall
  2. Start the instance with the iris start commandOpens in a new tab, preceding it with the ISC_CPF_MERGE_FILE variable, as follows:

    ISC_CPF_MERGE_FILE=/tmp/iriskit/CMF/merge.cpf iris start IRIS27

Using a merge file when deploying with InterSystems Cloud Manager

InterSystems Cloud Manager (ICM) is the InterSystems IRIS end-to-end provisioning and deployment solution. Using ICM, you can provision infrastructure and deploy containerized InterSystems IRIS-based services on public cloud platforms such as Google Cloud Platform, Amazon Web Services, and Microsoft Azure, or in your private VMware vSphere cloud., as well as existing virtual or hardware systems. ICM deploys your custom and third-party containers alongside those from InterSystems, and can also do containerless installs from InterSystems IRIS kits.

ICM makes the configuration merge functionality available through the UserCPF property, which you can include in either of your configuration files (defaults.json or definitions.json) to specify the location of the merge file to apply. If you include UserCPF in the defaults file, the same merge file is applied to all instances deployed; by adding it to the node definitions in definitions.json, you can apply different merge files to different node types.

For more information about using configuration merge with ICM, see Deploying with Customized InterSystems IRIS Configurations in the InterSystems Cloud Manager Guide.

Using a merge file when deploying with the InterSystems Kubernetes Operator

KubernetesOpens in a new tab is an open-source orchestration engine for automating deployment, scaling, and management of containerized workloads and services. The InterSystems Kubernetes OperatorOpens in a new tab (IKO) extends the Kubernetes API with the IrisCluster custom resource, which can be deployed as an InterSystems IRIS sharded cluster, distributed cache cluster, or standalone instance (all optionally mirrored) on any Kubernetes platform. The IKO also adds InterSystems IRIS-specific cluster management capabilities to Kubernetes, enabling automation of tasks like adding nodes to a cluster, which you would otherwise have to do manually by interacting directly with the instances.

When deploying with the IKO, you use a Kubernetes ConfigMapOpens in a new tab to integrate one or more merge files into the deployment process. For detailed information, see Create configuration files and provide a config map for them in Using the InterSystems Kubernetes Operator.

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] [existing-CPF]

where:

  • instance is the name of the InterSystems IRIS instance.

  • merge-file is the location of the merge file. If not specified, the value of the ISC_CPF_MERGE_FILE environment variable is used, if it exists.

  • existing-CPF is the location of the target CPF for the merge. If not specified, this uses the iris.cpf file located (for installed instances) in the installation directory or (for containers) in the directory specified by the ISC_DATA_DIRECTORY environment variable (or ISC_PACKAGE_INSTALLDIR if durable %SYS and ISC_DATA_DIRECTORY are not in use).

If the specified merge file is not present, or the merge-file argument is omitted and ISC_CPF_MERGE_FILE does not exist, the command fails with an error message.

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 generic memory heap (also known as the 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.

When creating a custom InterSystems IRIS container image by starting with an InterSystems IRIS image from InterSystems and adding your own code and dependencies, as described in Creating InterSystems IRIS ImagesOpens in a new tab in Running InterSystems Products in Containers, it can be very useful to execute the iris merge command in the Dockerfile to reconfigure the InterSystems IRIS instance contained in the InterSystems image. For example, you can include the iris merge command and a merge file with [Actions] parameters to add namespaces and databases to the instance, which will then be present on the instance in every container created from your custom image.

Managing configuration changes

In addition to the use of configuration merge in deployment or with an existing instance through the iris merge command or during a restart, an instance’s CPF can be altered using the Management Portal, the Config.* classes, or a text editor. These methods are generally used for modifying individual settings on individual instances as needed, rather than reconfiguring multiple instances. If you use configuration merge to automatically deploy and/or reconfigure multiple instances, the strongly recommended best practice is to confine all configuration changes to this method — even when this means, for example, using iris merge merge to change just one or two parameters on one instance. That way, assuming you version and store the merge files you employ, you can maintain a record of the configuration of each instance through time and avoid the possibility of configuration merge overwriting changes made by other means.

In a container, the potential for the latter exists because when an instance is restarted, configuration merge is activated and the merge file to apply is identified by the existence of the ISC_CPF_MERGE_FILE environment variable (which is persistent within a container). If the variable is allowed to persist within the container and the merge file it identifies exists, when the instance is restarted, configuration merge applies the merge file to the instance. This allows you to use configuration merge and a central repository of merge files to apply further changes to existing instances by updating the merge file and restarting. However, if the configuration parameters included in the merge file have been changed on the instance in the container by another method since deployment, the update merge can erase those changes, of which there may not be any record. Confining all configuration changes to configuration merge avoids this. (If the merge file does not exist, startup displays an error message and continues.)

If you do not confine changes to configuration merge, you can avoid the possibility of configuration merge making unwanted changes by including in your automation (using, for example, the iris-main --afterOpens in a new tab option) the scripting of either or both of the following after instance startup:

  • The deletion of the ISC_CPF_MERGE_FILE environment variable in each deployed container.

  • The replacement of the merge file in each container with an empty file.

Important:

When ICM uses the configuration merge file specified by the UserCPF parameter to customize containers it deploys, as described in Deploying with Customized InterSystems IRIS ConfigurationsOpens in a new tab in the ICM Guide, it automatically removes the merge file from the container after deployment, but does not delete the ISC_CPF_MERGE_FILE environment variable.

Useful parameters in automated deployment

The configuration merge feature can be used to update any combination of settings in an instance’s CPF and execute certain operations on the instance as specified in the [Actions] section. Several automated deployment use cases that you may find useful and make good examples of the power of the configuration merge feature, along with the parameters involved, are discussed in this section, including

You can find corresponding Docker Compose examples of container deployment with configuration merge in the intersystems-community/configuration-merge-file-2020.4Opens in a new tab repo on GitHub.

Important:

The examples provided on GitHub are for learning and testing only, and not for production use.

Each parameter name provided by the descriptions in the following is linked to its listing in the Configuration Parameter File ReferenceOpens in a new tab so you can easily review a parameter’s purpose and details of its usage; further links to relevant documentation are also provided.

Change the Default Password

As described in Authentication and PasswordsOpens in a new tab in Running InterSystems Products in Containers, you can use the PasswordHash setting in the [Startup] section to customize the default password of the predefined accounts on an instance at deployment, which eliminates the serious security risk entailed in allowing the default password of SYS to remain in effect. (The password of each predefined account should be individually changed following deployment.)

Password Parameter
[Startup] Parameter Specifies
PasswordHashOpens in a new tab Default password for the predefined user accounts based on a cryptographic hash of the value and its salt

For an example, see 1-Configuration-Memory_Buffers_paramsOpens in a new tab on GitHub. (The [Actions]/CreateUser parameter also takes a PasswordHash argument that accomplishes the same thing; for details, see [Actions] Parameter Reference.)

Configure and Allocate Memory

There are a number of parameters affecting an InterSystems IRIS instance’s memory usage, the optimal value of which can depend on the physical memory available, the instance’s role within the cluster, the workload involved, and performance requirements.

For example, the optimal size of an instance’s database cache, which can be specified using the globals parameter, can vary greatly depend on the instance’s role; as noted above, sharded cluster data nodes typically require a relatively large cache. But even within that role, the optimal size depends on the size of the cluster’s sharded data set, and the implemented size may be smaller than optimal due to resource constraints. (For more information, see Planning an InterSystems IRIS Sharded ClusterOpens in a new tab in the Scalability Guide.) Further, because the database cache should be carefully sized in general, the default database cache setting (the value of globals in the iris.cpf file provided in the container) is intentionally unsuitable for any production environment, regardless of the instance’s role.

Memory usage settings in the [Config] section of the CPF that you might want to update as part of deployment are listed in the following table:

Memory Parameters
[Config] Parameter Specifies
bbsizOpens in a new tab Maximum process private memory per process
globals Shared memory allocated to the database cache (not from generic memory heap)
routinesOpens in a new tab Shared memory allocated to the routine cache (not from generic memory heap)
gmheapOpens in a new tab Shared memory configured as the generic memory heap
memlockOpens in a new tab Shared memory allocation process
jrnbufsOpens in a new tab Shared memory allocated to journal buffers from the generic memory heap
locksizOpens in a new tab Maximum shared memory allocated to locks from the generic memory heap

For an example, see 1-Configuration-Memory_Buffers_paramsOpens in a new tab on GitHub; see also Memory Planning and Management for InterSystems IRISOpens in a new tab, Memory and Startup SettingsOpens in a new tab, Configuring Journal SettingsOpens in a new tab, Monitoring LocksOpens in a new tab.

Configure SQL and SQL Shell Options and Map SQL Datatypes

You can specify the SQL and SQL Shell settings for instances you are deploying by merging one or more of the parameters in the [SQL]Opens in a new tab section of the CPF. You can map SQL system data types and SQL user data types to their InterSystems IRIS data platform equivalents on deployed instances using the [SqlSysDatatypes]Opens in a new tab and [SqlUserDatatypes]Opens in a new tab sections of the CPF, respectively.

For an example of specifying a SQL setting and mapping a datatype, see 2-Configuration-SQL_paramsOpens in a new tab on GitHub; see also Configuring the SQL Shell and Data Types (SQL)Opens in a new tab.

Create, Modify, and Delete Database-related Objects and Security Items

As described in Can configuration merge customize more than the configuration?, you can use the parameters in the [Actions]Opens in a new tab section to create, modify, or delete many different types of objects on an instance as part deployment or reconfiguration, including databases, namespaces, and mappings; users, roles, and resources; and many more.

Include the operations described in the following table in the [Actions] section to create databases (both local and remote) and namespaces as part of deployment or reconfiguration.

Database and Namespace Creation Parameters
[Actions] Parameter Specifies
CreateDatabase The location on the host file system of the database file to be created and the database’s name properties to be registered in InterSystems IRIS
CreateDatabaseFile Only the location on the host file system of the database file to be created (without registering the database in InterSystems IRIS)
CreateNamespace The name and properties of the namespace to be created in InterSystems IRIS
Note:

The parameters in the table are described in [Actions] Parameter Reference.

Examples of the many situations in which you might want to do this include:

  • When you are deploying a mirror (or multiple mirrors) you can create the same set of mirrored databases, and namespaces for them, on the primary, the backup, and any DR asyncs. This enables the mirror to be fully operational immediately following deployment.

  • When you are adding a database to an existing mirror, which must be done on the running primary, you can create the database using the iris merge command.

  • When you are deploying a distributed cache cluster, you can deploy the data server with one or more local databases (and namespaces for them), then deploy the application servers with the data server configured as a remote server and remote databases corresponding to the databases you created on it using Server and LogicalOnly arguments to the CreateDatabase parameter, along with local namespaces for them. As with the mirror example, the distributed cache cluster configured in this way is fully operational immediately after deployment.

  • When you are creating a custom InterSystems IRIS container image from one provided by InterSystems, as described in Creating InterSystems IRIS ImagesOpens in a new tab in Running InterSystems Products in Containers, you can execute the iris merge command in the Dockerfile to add namespaces and databases to the instance contained in the InterSystems image, so that they will be present in every container created from your custom image. (Such user-defined databases are included in the instance-specific data cloned to durable storage by the durable %SYS featureOpens in a new tab, as long as the database files are writable.)

For an example, see 3-Configuration-Databases_and_NamespacesOpens in a new tab on GitHub; see also Configuring NamespacesOpens in a new tab, Local DatabasesOpens in a new tab, Remote DatabasesOpens in a new tab, Deploy the Distributed Cache Cluster Using the Management PortalOpens in a new tab.

For comprehensive lists of all of the [Actions] parameters, see [Actions] Parameter Reference.

Deploy Mirrors

You can deploy one or more InterSystems IRIS mirrors by calling separate configuration merge files for the different mirror roles, sequentially deploying the first failover member(s), then the second failover member(s), then DR async members. (Reporting async members must be added to the mirror after deployment.) The parameters required are shown in the following table.

You can also automatically deploy multiple failover pairs, or deploy multiple backups for existing primaries, if the deployment hosts have names ending in -nnnn (or, as a regular expression, .*-[0-9]+$), for example iris-1, iris-2, iris-3 ... . In this case you can use a single merge file for both primaries and backups, then use another to deploy any DR async members following automatic deployment of the failover pairs.

Mirroring Parameters
[Startup] Parameter Specifies
MirrorMember
Mirror member role (primary failover member, backup failover member, or DR async)
(or)
Automatic failover pairs using hostname matching (primary/backup specification not required; use one merge file for both roles)
MirrorSetNameOpens in a new tab
Name of the new mirror (when deploying the primary)
(or)
Name of mirror the member is joining (when deploying the backup or a DR async)
MirrorPrimaryOpens in a new tab
Name or IP address of primary’s host (when deploying the backup)
(or)
Automatic backups for existing primaries using hostname matching
MirrorSSLDir Location of the mirror SSL configuration for the instance.
ArbiterURLOpens in a new tab
Location of arbiter to be configured for mirror (when deploying the primary)
(or)
Location of arbiter configured for existing primary (when deploying the backup or a DR async)

For examples, see 4-Architecture-Mirror_MembersOpens in a new tab and 6-Architecture-Mirrored_ShardOpens in a new tab on GitHub; see also Mirroring Architecture and PlanningOpens in a new tab and Configuring MirroringOpens in a new tab.

Be sure to read Mirroring with InterSystems IRIS ContainersOpens in a new tab in Running InterSystems Products in Containers before planning containerized deployment of mirrors, or reconfiguring existing containerized instances into mirrors. Among other important consideration, you must ensure that the ISCAgent starts whenever the container for a failover or DR async mirror member starts.

Deploy Sharded Clusters

You can deploy one or more InterSystems IRIS sharded clusters by calling separate configuration merge files for the different node types, sequentially deploying data node 1, then the remaining data nodes, then (optionally) the compute nodes. (Because the instance configured as data node 1 must be running before the other data nodes can be configured, you must ensure that this instance is deployed and successfully started before other instances are deployed as the remaining data nodes.) The parameters required are shown in the following tables.

You can also automatically deploy a cluster of data nodes, or a mirrored cluster of data nodes, if the deployment hosts have names ending in the specified regular expression (for example .*-[0-9]+$, matching iris-1, iris-2, iris-3 ...), in which case you can use a single merge file for all data nodes including node 1. (Following automatic deployment of the data nodes, you can deploy compute nodes using a separate merge file.)

Sharding Parameters
[Startup] Parameter Specifies
EnableShardingOpens in a new tab Whether the Sharding service is enabled on the instance
ShardRoleOpens in a new tab
The role of the instance in the sharded cluster
(or)
Automatic sharded cluster of data nodes only, using hostname matching
ShardClusterURLOpens in a new tab The existing node to use as a template when adding a data or compute node to the cluster (not used for node 1)
ShardRegexpOpens in a new tab In automatic deployment of cluster using hostname matching, pattern used to validate names of hosts on which data nodes are to be deployed (ShardRole=AUTO)
ShardMasterRegexpOpens in a new tab In automatic deployment of cluster using hostname matching, pattern used to identify the host on which node 1 must be deployed (ShardRole=AUTO)
[Config] Parameter Specifies
MaxServerConnOpens in a new tab Maximum number of concurrent connections from application servers that a data server can accept; must be equal to or greater than the number of nodes in the cluster
MaxServersOpens in a new tab Maximum number of concurrent connections to data servers that an application server can maintain; must be equal to or greater than the number of nodes in the cluster
globalsOpens in a new tab Shared memory allocated to the database cache; must be significantly larger than default setting for any sharded cluster node.

For a mirrored sharded cluster, the following parameters are also used.

[Startup] Parameter Specifies
ShardMirrorMemberOpens in a new tab
A mirrored sharded cluster
(and either)
The mirror status (primary or backup) of the instance
(or)
Automatic mirrored data nodes (failover pairs) using hostname matching (in conjunction with automatic deployment of cluster using hostname matching [ShardRole=AUTO])
ArbiterURLOpens in a new tab Location of arbiter to be configured for mirrored data nodes

For examples, see 5-Architecture-Shard_InstancesOpens in a new tab and 6-Architecture-Mirrored_ShardOpens in a new tab on GitHub; see also Deploying the Sharded ClusterOpens in a new tab, Mirror Data Nodes for High AvailabilityOpens in a new tab, and Deploy Compute Nodes for Workload Separation and Increased Query ThroughputOpens in a new tab.

[Actions] Parameter Reference

As described in Can configuration merge customize more than the configuration?, the [Actions]Opens in a new tab parameters enable you to manage a wide variety of InterSystems IRIS objects through configuration merge. This section is intended to help you identify the [Actions] parameters you need as quickly as possible. Each of the tables provided lists all available parameters in a specific order, as follows:

  • By the object on which the parameter acts. For example, you can use parameters to create, delete, and modify databases, but you cannot create or delete services, only modify them.

  • In the order in which the parameters are processed, which is fixed, rather than being determined by their sequence in the configuration merge file. For example, because the default databases you specify for the CreateNamespace parameter must exist when it is executed, CreateDatabase is processed before CreateNamespace, so that when you create both a namespace and its default globals or routines database, the specified database is created first, even if CreateNamespace appears above CreateDatabase in the merge file.

  • By the class or command to which the parameter corresponds. For example, the parameters for creating, deleting, and modifying mirrors are effected by calls to methods in the class Config.mirrors.

  • In alphabetical order, which also divides the parameters by type of action (create, delete, modify).

Arguments to [Actions]parameters are specified in the format shown in the following action, in which the CreateNamespace parameter is used to create the APPDATA namespace with the APPDATA database as its default globals databases and the USER database as its default routines database:

[Actions]
CreateNamespace:Name=APPDATA,Globals=APPDATADB,Routines=USER

To review the arguments you can use with each [Actions] parameter, consult the Property Inventory of the class on which it is based in the Class Reference. (In the By corresponding class table, the listed classes are linked to their entries in the Class Reference.) For example, the inventory for the Config.NamespacesOpens in a new tab class includes the following properties:

  • Globals — The default globals database of the namespace

  • Interop (boolean) — Whether the namespace is interoperability-enabled (boolean)

  • Routines — The default routines database of the namespace

  • TempGlobals — The default database for temporary globals storage

There are a few exceptions to the above general description, as follows:

  • In the case of all parameters derived from classes in the Config package, the Name property for the name of the object is inherited from the Config.CommonMultipleMethodsOpens in a new tab class, which includes the Create(), Modify(), and Delete() methods.

  • When using the CreateDatabase parameter on a distributed cache cluster application server to add a remote database, there are two unique arguments, only the first of which is in the Config.DatabasesOpens in a new tab property inventory:

    • Server — Specifies the name of the data server on which the remote database is located (required)

    • LogicalOnly (boolean) — Specifies that the action should not create a database on the file system of the application server host (optional, default (0) is to create a database file)

  • When using the CreateUser parameter, the PasswordHash argument, which is not in the Security.UsersOpens in a new tab property inventory, specifies a hashed password, work factor, and algorithm, as shown in Can configuration merge customize more than the configuration?. PasswordHash is used in place of the Password, PasswordHashAlgorithm, and PasswordHashWorkFactor properties listed in Security.UsersOpens in a new tab.

  • All of the SQL privilege parameters — GrantPrivilege, RevokePrivilege, GrantAdminPrivilege, and RevokeAdminPrivilege — take the argument Namespace, which is not in the property inventories of the class methods or the argument lists of the commands used to effect them, because the classes and commands are designed to take effect in the namespace in which they are called or executed. The Namespace argument allows you to specify any namespace when granting or revoking privileges.

  • The SQL admin privilege parameters, GrantAdminPrivilege and RevokeAdminPrivilege, are based on the SQL commands GRANTOpens in a new tab and REVOKEOpens in a new tab rather than on classes and affect only administrator-level privileges; thus the available arguments (in addition to Namespace) include only AdminPriv, Grantee, and WithGrant, the last of which is for GrantAdminPrivilege only and adds the WITH ADMIN OPTION clause (the equivalent of the standard WITH GRANT).

  • The GrantPrivilege parameter takes the additional boolean argument withGrant (can also be wGrant) because it combines two methods, %SYSTEM.SQL.Security.GrantPrivilegeWithGrant()Opens in a new tab and %SYSTEM.SQL.Security.GrantPrivilege()Opens in a new tab; withgrant=1 selects use of the former, withgrant=1 of the latter.

Application: Create, Delete, Modify
Comport: Create, Delete, Modify
Config: Modify
Database (logical): Create, Delete, Modify
DatabaseFile: Create, Delete, Modify
Device: Create, Delete, Modify
DeviceSubType: Create, Delete, Modify
DocDB: Create, Delete, Modify
ECP: Modify
ECPServer: Create, Delete, Modify
Event: Create, Delete, Modify
Journal: Modify
LDAPConfig: Create, Delete, Modify
LicenseServer: Create, Delete, Modify
MagTapes: Create, Delete, Modify
MapGlobal: Create, Delete, Modify
MapPackage: Create, Delete, Modify
MapRoutine: Create, Delete, Modify
MirrorMember: Modify
Mirrors: Create, Delete, Modify
Miscellaneous: Modify
Monitor: Modify
Namespace: Create, Delete, Modify
Resource: Create, Delete, Modify
Role: Create, Delete, Modify
Service: Modify
Shadows: Create, Delete, Modify
SQL admin privilege: Grant, Revoke
SQL privilege: Grant, Revoke
SQL setting: Modify
SQL System Datatype: Create, Delete, Modify
SQL User Datatype: Create, Delete, Modify
Startup setting: Modify
System setting: Modify
User: Create, Delete, Modify
WorkQueue: Create, Delete, Modify
ModifySystem
ModifyEvent
DeleteEvent
CreateEvent
ModifyMonitor
ModifyJournal
ModifyConfig
ModifyECP
ModifyMiscellaneous
ModifySQL
DeleteWorkQueue
CreateWorkQueue
ModifyWorkQueue
DeleteDevice
DeleteDeviceSubType
CreateDeviceSubType
CreateDevice
ModifyDeviceSubType
ModifyDevice
DeleteMagTapes
CreateMagTapes
ModifyMagTapes
DeleteComPort
CreateComport
ModifyComport
DeleteSqlSysDatatype
CreateSqlSysDatatype
ModifySqlSysDatatype
DeleteSqlUserDatatype
CreateSqlUserDatatype
ModifySqlUserDatatype
DeleteLicenseServer
CreateLicenseServer
ModifyLicenseServer
DeleteMapPackage
DeleteMapGlobal
DeleteMapRoutine
DeleteNamespace
DeleteDatabase
DeleteDatabaseFile
DeleteECPServer
DeleteResource
CreateECPServer
ModifyECPServer
CreateResource
CreateDatabaseFile
ModifyDatabaseFile
CreateDatabase
ModifyDatabase
CreateNamespace
ModifyNamespace
CreateMapPackage
CreateMapGlobal
CreateMapRoutine
ModifyMapPackage
ModifyMapGlobal
ModifyMapRoutine
ModifyMirrorMember
DeleteMirrors
CreateMirrors
ModifyMirrors
DeleteShadows
CreateShadows
ModifyShadows
ModifyStartup
ModifyService
DeleteUser
DeleteLDAPConfig
DeleteApplication
DeleteDocDB
DeleteRole
CreateRole
CreateDocDB
CreateLDAPConfig
CreateUser
CreateApplication
ModifyResource
ModifyRole
ModifyDocDB
ModifyLDAPConfig
ModifyUser
ModifyApplication
GrantPrivilege
RevokePrivilege
GrantAdminPrivilege
RevokeAdminPrivilege
Config.CPFOpens in a new tab ActivateCPF
Config.ComPortsOpens in a new tab CreateComPort, DeleteComPort, ModifyComPort
Config.configOpens in a new tab ModifyConfig
Config.CPFOpens in a new tab CreateDatabase, DeleteDatabase, ModifyDatabase
Config.DevicesOpens in a new tab CreateDevice, DeleteDevice, ModifyDevice
Config.DeviceSubTypesOpens in a new tab CreateDeviceSubType, DeleteDeviceSubType, ModifyDeviceSubType
Config.ECPOpens in a new tab ModifyECP
Config.ECPServersOpens in a new tab CreateECPServer, DeleteECPServer, ModifyECPServer
Config.JournalOpens in a new tab ModifyJournal
Config.LicenseServersOpens in a new tab CreateLicenseServer, DeleteLicenseServer, ModifyLicenseServer
Config.MagTapesOpens in a new tab CreateMagTapes, DeleteMagTapes, ModifyMagTapes
Config.MapGlobalsOpens in a new tab CreateMapGlobal, DeleteMapGlobal, ModifyMapGlobal
Config.MapPackagesOpens in a new tab CreateMapPackage, DeleteMapPackage, ModifyMapPackage
Config.MapRoutinesOpens in a new tab CreateMapRoutine, DeleteMapRoutine, ModifyMapRoutine
Config.MirrorMemberOpens in a new tab ModifyMirrorMember
Config.MirrorsOpens in a new tab CreateMirror, DeleteMirrors, ModifyMirrors
Config.MiscellaneousOpens in a new tab ModifyMiscellaneous
Config.MonitorOpens in a new tab ModifyMonitor
Config.NamespacesOpens in a new tab CreateNamespace, DeleteNamespace, ModifyNamespace
Config.ShadowsOpens in a new tab CreateShadows, DeleteShadows, ModifyShadows
Config.SQLOpens in a new tab ModifySQL
Config.SqlSysDatatypesOpens in a new tab CreateSqlSysDatatype, DeleteSqlSysDatatype, ModifySqlSysDatatype
Config.SqlUserDatatypesOpens in a new tab CreateSqlUserDatatype, DeleteSqlUserDatatype, ModifySqlUserDatatype
Config.StartupOpens in a new tab ModifyStartup
Config.WorkQueuesOpens in a new tab CreateWorkQueue, DeleteWorkQueue, ModifyWorkQueue
Security.ApplicationsOpens in a new tab CreateApplication, DeleteApplication, ModifyApplication
Security.DocDBsOpens in a new tab CreateDocDB, DeleteDocDB, ModifyDocDB
Security.EventsOpens in a new tab CreateEvent, DeleteEvent, ModifyEvent
Security.LDAPConfigsOpens in a new tab CreateLDAPConfig, DeleteLDAPConfig, ModifyLDAPConfig
Security.ResourcesOpens in a new tab CreateResource, DeleteResource, ModifyResource
Security.RolesOpens in a new tab CreateRole, DeleteRole, ModifyRole
Security.ServicesOpens in a new tab ModifyService
Security.SystemOpens in a new tab ModifySystem
Security.UsersOpens in a new tab CreateUser, DeleteUser, ModifyUser
SQL commands GRANT, REVOKE GrantAdminPrivilege, RevokeAdminPrivlege
SYS.DatabaseOpens in a new tab CreateDatabaseFile, DeleteDatabaseFile, ModifyDatabaseFile
%SYSTEM.SQL.SecurityOpens in a new tab GrantPrivilege, RevokePrivilege
ActivateCPF
CreateApplication
CreateComPort
CreateDatabase
CreateDatabaseFile
CreateDevice
CreateDeviceSubType
CreateDocDB
CreateECPServer
CreateEvent
CreateLDAPConfig
CreateLicenseServer
CreateMagTapes
CreateMapGlobal
CreateMapPackage
CreateMapRoutine
CreateMirrors
CreateNamespace
CreateResource
CreateRole
CreateShadows
CreateSqlSysDatatype
CreateSqlUserDatatype
CreateUser
CreateWorkQueue
DeleteApplication
DeleteComPort
DeleteDatabase
DeleteDatabaseFile
DeleteDevice
DeleteDeviceSubType
DeleteDocDB
DeleteECPServer
DeleteEvent
DeleteLDAPConfig
DeleteLicenseServer
DeleteMagTapes
DeleteMapGlobal
DeleteMapPackage
DeleteMapRoutine
DeleteMirrors
DeleteNamespace
DeleteResource
DeleteRole
DeleteShadows
DeleteSqlSysDatatype
DeleteSqlUserDatatype
DeleteUser
DeleteWorkQueue
GrantAdminPrivilege
GrantPrivilege
ModifyApplication
ModifyComPort
ModifyConfig
ModifyDatabase
ModifyDatabaseFile
ModifyDevice
ModifyDeviceSubType
ModifyDocDB
ModifyECP
ModifyECPServer
ModifyEvent
ModifyJournal
ModifyLDAPConfig
ModifyLicenseServer
ModifyMagTapes
ModifyMapGlobal
ModifyMapPackage
ModifyMapRoutine
ModifyMirrorMember
ModifyMirrors
ModifyMiscellaneous
ModifyMonitor
ModifyNamespace
ModifyResource
ModifyRole
ModifyService
ModifyShadows
ModifySQL
ModifySqlSysDatatype
ModifySqlUserDatatype
ModifyStartup
ModifySystem
ModifyUser
ModifyWorkQueue
RevokeAdminPrivilege
RevokePrivilege
FeedbackOpens in a new tab