Useful Action Parameters in Automated Deployment

Create, Modify, and Delete Security Objects

Include the operations described in the following table in the [Actions] section to create and modify security objects as part of deployment or reconfiguration.

To illustrate the use of action parameters with security objects, suppose you wanted to add to deployed instances a predefined account for 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"

For information about the operations performed by these action parameters and the values of their properties, see Authentication and Passwords, About InterSystems Authorization, and SQL Users, Roles, and Privileges.

Security Macros

InterSystems IRIS supports a set of macros that you can use in the [Actions] section of the configuration merge file (CMF). These macros relate to the AutheEnabled property for the Security.ApplicationsOpens in a new tab, Security.ServicesOpens in a new tab, Security.SystemOpens in a new tab, and Security.UsersOpens in a new tab classes as well as the LDAPFlags property in the Security.LDAPConfigsOpens in a new tab class. Supported macros are listed below.

AutheEnabled macros:

• AutheK5CCache — Enables Kerberos credential cache authentication.

• AutheK5Prompt — Enables Kerberos password prompt authentication.

• AutheK5API — Enables Kerberos username and password authentication.

• AutheK5KeyTab — Enables Kerberos keytab file authentication.

• AutheOS — Enables operating system authentication.

• AuthePassword — Enables password authentication.

• AutheUnauthenticated — Enables unauthenticated access.

• AutheKB — Enables Kerberos base connection security level.

• AutheKBEncryption — Enables Kerberos with Encryption connection security level.

• AutheKBIntegrity — Enables Kerberos with Packet Integrity connection security level.

• AutheLDAP — Enables LDAP authentication.

• AutheLDAPCache — Enables LDAP cached credentials for LDAP authentication.

• AutheDelegated — Enables delegated authentication.

• AutheLoginToken — Enables creation of Login Cookies.

• AutheKerberosDelegated — Enables using Kerberos for authentication then uses delegated authorization.

• AutheOSDelegated — Enables using the operating system to authenticate the user then uses delegated authorization.

• AutheOSLDAP — Enables Operating Systems authentication then LDAP authorization.

• AutheTwoFactorSMS — Enables SMS two factor authentication for a user.

• AutheTwoFactorPW — Enables one-time password two factor authentication for a user.

• AutheAlwaysTryDelegated — Enables using delegated authentication code for users authenticating with instance authentication.

• AutheMutualTLS — Enables mutual TLS when modifying %Service_WebGateway.

LDAPFlags macros:

• LDAPActiveDirectory — Indicates that the LDAP server is a Windows Active Directory server.

• LDAPTLSConnection — Enables use of TLS for LDAP sessions.

• LDAPAllowISCLDAPCONFIGURATION — Enables use of the ISC_LDAP_CONFIGURATION environment variable if using OS-based LDAP and multiple domains to determine which LDAP configuration to use for authentication.

• LDAPUseGroups — Enables using LDAP groups for Roles/Routine/Namespace.

• LDAPUseNestedGroups — Enables searching to return all of a user's nested LDAP groups.

• LDAPUniversalGroups — Enables searches using attributes on the LDAP server that are relevant for all InterSystems IRIS instances.

• LDAPEnabled — Enables the LDAP configuration.

• LDAPKerberosOnly — Enables use of Kerberos only for an LDAP configuration.

Example of enabling password authentication and unauthenticated access for %Service_ComPort:

[Actions] 
ModifyService:Name=%Service_ComPort,AutheEnabled=$$$AuthePassword+$$$AutheUnauthenticated

Example of using some LDAPFlags macros to create a new LDAP configuration. Note that the values for LDAPBaseDN and LDAPBaseDNForGroups contain “=”, so the values must be enclosed in quotes.

[Actions]
CreateLDAPConfig:Name=TestLDAP,LDAPBaseDNForGroups="DC=testcompany,DC=com",LDAPHostNames="testcompany",LDAPBaseDN="DC=testcompany,DC=com",LDAPSearchUsername="ldapadmin",LDAPSearchPassword=SYS,LDAPFlags=$$$LDAPActiveDirectory+$$$LDAPUseGroups+$$$LDAPUseNestedGroups+$$$LDAPEnabled

Create, Modify, and Delete Database Objects

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

To illustrate the use of action parameters with database-related objects, suppose you wanted to:

• Create a database and a resource for it, then modify an existing namespace to make the database you created its global database and enable interoperability.

• Create a second database with resources, then create an interoperability-enabled namespace with the database as its default global database.

The following example shows how you could do this with a merge file:

[Actions]

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/database-path/APPA,ResourceName=%DB_APPA
ModifyNamespace:Name=APPA,Globals=APPA,Interop=1

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/database-path/APPB,ResourceName=%DB_APPB
CreateNamespace:Name=APPB,Globals=APPB,Interop=1

Suppose that at a later point you wanted to add mappings of globals and routines in database APPA to namespace APPB. You could do this with a merge file like the following:

[Actions]
CreateMapGlobal:Name="global-name(1):(101)",Namespace=APPB,Database=APPA
CreateMapRoutine:Namespace=APPB,Name=routine-spec,Database=APPA

For information about the operations performed by these action parameters and the values of their properties, see Create/Modify a Namespace, Create a Local Database, and Add Global, Routine, and Package Mapping to a Namespace.

Deploy a Distributed Cache Cluster

With a few simple changes to the merge file example in the previous section, you can create merge files to deploy a distributed cache cluster.

For information about the operations performed by these action parameters in the following sections and the values of their properties, see Remote Databases and Deploying a Distributed Cache Cluster.

Deploy the Data Server

The merge file below would be used to deploy the nonmirrored data server. In addition to creating the application databases and their associated resources and namespaces, it does the following:

• Enables the ECP service with an action parameter.

• Uses an update parameter to set the maximum number of concurrent application server connections the data server can accept to 16.

Differences from the previous sample merge file are emphasized.

# nonmirrored data server merge file

[Config]

MaxServerConn=16

[Actions]

ModifyService:Name=%service_ecp,Enabled=1

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/database-path/APPA,ResourceName=%DB_APPA
CreateNamespace:Name=APPA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/database-path/APPB,ResourceName=%DB_APPB
CreateNamespace:Name=APPB,Globals=APPB

Deploy the Application Servers

This merge file, which would be used to deploy all of the application servers, does the following:

• Adds the data server as a remote server with an update parameter

• Modifies the CreateDatabase actions above by adding the Server and LogicalOnly properties and updating the Directory argument to point to existing databases on the remote server, rather than a local directory in which to create a local database.

Differences from the sample merge file in the previous section are emphasized.

# app servers merge file

[ECPServers]

dataAB=dataserver-address,port,0

[Actions]

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Server=dataAB,Directory=/database-path-on-dataserver-dataAB/APPA,ResourceName=%DB_APPA,
  LogicalOnly=1,
CreateNamespace:Name=APPDBA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Server=dataAB,Directory=/database-path-on-dataserver-dataAB/APPB,ResourceName=%DB_APPB,
  LogicalOnly=1
CreateNamespace:Name=APPB,Globals=APPB

Deploy the Application Servers with Mirrored Data Server

If you are deploying an application server who’s data server is mirrored, the merge file must be altered. This merge file alters the application server merge file previously shown only by changing the 0 at the end of the remote server definition action in [ECPServers] to 1, as emphasized, to indicate that the remote server is a mirror, which allows application connections to transparently switch to the new primary after failover.

# app servers merge file

[ECPServers]

dataAB=dataserver-address,port,1

[Actions]

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/database-path-on-dataserver-dataAB/APPA,ResourceName=%DB_APPA,
  Server=dataAB,LogicalOnly=1
CreateNamespace:Name=APPDBA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/database-path-on-dataserver-dataAB/APPB/,ResourceName=%DB_APPB,
  Server=dataAB,LogicalOnly=1
CreateNamespace:Name=APPB,Globals=APPB

Mirror the Cluster’s Data Server

To deploy one or more InterSystems IRIS mirrors, you can use separate configuration merge files, each containing the ConfigMirror action parameter, for the different mirror roles, sequentially deploying the first failover member(s), then the second failover member(s), then DR async members, then any reporting async members if desired.

You can also deploy using a single merge file and hostname matching, which determines which member to deploy on each of a set of hosts the names of which match the required pattern.

This section provides examples of each approach, see ConfigMirror for information on the available properties for the ConfigMirror action parameter.

For detailed information about mirror configuration, see Mirroring Architecture and Planning and Creating a Mirror. Be sure to read Mirroring with InterSystems IRIS Containers before planning containerized deployment of mirrors, or reconfiguring existing containerized instances into mirrors. Among other important considerations, you must ensure that the ISCAgent starts whenever the container for a failover or DR async mirror member starts.

Deploy the Mirror Using Separate Merge Files

In planning deployment using separate merge files it is important to bear in mind that the instance configured as the mirror primary must be running before other members can be added, so you must ensure that this instance is deployed and successfully started before other instances are deployed as the remaining members.

Deploy the Data Server Mirror Members

The following merge files deploy the distributed cache cluster’s data server as a mirror with a DR async member by doing the following:

• Including the ConfigMirror action parameter to create the mirror and add members.

• On the primary, adding the created databases to the mirror (they will be automatically added on the other members).

Differences from the corresponding merge file in the previous section are emphasized.

# mirrored data server primary merge file

[Config]
MaxServerConn=16

[Actions]

ModifyService:Name=%service_ecp,Enabled=1 

ConfigMirror:Name=CLUSTERAB,SSLDir=ssl-directory-path,
  Member=primary,Primary=localhost,ArbiterURL=address:port

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/ddatabase-path/APPA,ResourceName=%DB_APPA,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPA
CreateNamespace:Name=APPA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/ddatabase-path/APPB,ResourceName=%DB_APPB,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPB
CreateNamespace:Name=APPB,Globals=APPB

# mirrored data server merge file to add backup, DR async, read-only reporting async, or read-write reporting async;
# for ConfigMirror Member argument enter either =backup, =drasync, =rorasync, or =rwrasync as appropriate

[Config]
MaxServerConn=16

[Actions]

ModifyService:Name=%service_ecp,Enabled=1

ConfigMirror:Name=CLUSTERAB,SSLDir=ssl-directory-path,
  Member=backup|drasync|rorasync|rwrasync,Primary=primary-address:,ArbiterURL=address:port

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/ddatabase-path/APPA,ResourceName=%DB_APPA,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPA
CreateNamespace:Name=APPA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/ddatabase-path/APPB,ResourceName=%DB_APPB,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPB
CreateNamespace:Name=APPB,Globals=APPB

Note:

To copy existing databases to the mirror created by the ConfigMirror action instead of creating empty ones, you could use the Seed parameter of the CreateDatabase action to specify the path names of the databases to copy, as shown in this modified excerpt from either section (primary or backup/DR async) of the previous example:

ConfigMirror:Name=CLUSTERAB,SSLDir=ssl-directory-path,
  Member=backup|drasync,Primary=primary-address:,ArbiterURL=address:port

CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/ddatabase-path/APPA,ResourceName=%DB_APPA,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPA,Seed=/mnt/databases/DB1
CreateNamespace:Name=APPA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/ddatabase-path/APPB,ResourceName=%DB_APPB,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPB,Seed=/mnt/databases/DB2
CreateNamespace:Name=APPB,Globals=APPB

Deploy the Mirror Using Hostname Matching

You can automatically deploy one or more mirrors from a single merge file if the deployment hosts have names ending in -number (or, as a regular expression, .*-[0-9]+$), for example iris-000, iris-001, iris-002 ..., or in -number-number, for example iris-0-0, iris-0-1, iris-1-0, iris-1-1 .... You do this by

• Setting the Map argument (not used with the separate merge file approach) to the pattern you want (it is primary,backup by default, but can also contain up to 14 DR async members as in primary,backup,drasync,...)

• Setting the Member and Primary arguments to auto.

For example, if you used the following ConfigMirror action parameter, mirror members would be deployed on appropriately named hosts as shown in the table after the example:

ConfigMirror:Name=AUTOMIRROR,SSLDir=ssl-directory-path,
  Map=”primary,backup,drasync”,
  Member=auto,Primary=auto,ArbiterURL=address:port

To allow multiple independent InterSystems IRIS clusters to communicate without mirror member name collisions, you can offset the hostnames of one of the clusters by a number to prevent overlap using the optional Ordinal property. For example, if Ordinal is set to 100, then the corresponding hostnames are iris-100, iris-101, iris-102 ...

As another example, if you used the following ConfigMirror action parameter, mirror members would be deployed on appropriately named hosts as shown in the table after the example:

ConfigMirror:Name=AUTOMIRROR,SSLDir=ssl-directory-path,
  Map=”primary,backup,drasync”,
  Member=auto,Primary=auto,ArbiterURL=address:port
  Ordinal=100

Deploy Mirror Members by Hostname

Incorporating a ConfigMirror action like the one above, you could use hostname matching to deploy a three-member mirrored data server using the following single merge file on three sequentially named hosts such as iris-001, iris-002, and iris-003 rather than three merge files as shown in the previous section.

# mirrored data server using single merge file and hostname mapping

[Config]
MaxServerConn=16

[Actions]

ModifyService:Name=%service_ecp,Enabled=1
 
ConfigMirror:Name=CLUSTERAB,SSLDir=ssl-directory-path,
  Map=”primary,backup,drasync”,Member=auto,
  Primary=auto,ArbiterURL=address:port
CreateResource:Name=%DB_APPA,Description="APPA database"
CreateDatabase:Name=APPA,Directory=/ddatabase-path/APPA,ResourceName=%DB_APPA,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPA
CreateNamespace:Name=APPA,Globals=APPA

CreateResource:Name=%DB_APPB,Description="APPB database"
CreateDatabase:Name=APPB,Directory=/ddatabase-path/APPB,ResourceName=%DB_APPB,
  MirrorSetName=CLUSTERAB,MirrorDBName=APPB
CreateNamespace:Name=APPB,Globals=APPB

See Also

• Configuration Merge in Deployment

• Reconfigure an Existing Instance Using Configuration Merge

• Useful Update Parameters in Automated Deployment