Skip to main content

Security for InterSystems IRIS Containers

Security for InterSystems IRIS Containers

When working with InterSystems IRIS images from InterSystems it is important to understand the security-related mechanisms and options, including:


While InterSystems IRIS security is comprehensive and container images from InterSystems are engineered to support the strictest security requirements, there are some important security practices designed for noncontainerized instances to which containerized instances present a challenge. In particular, operations requiring human intervention are not suitable for automated containerized deployment and operation. For example, startup with interactive key activationOpens in a new tab (which is the default behavior for an instance with a database encryption key activated) interrupts startup with a prompt for the location of the key, to which an operator must respond. Other tasks, such as configuring an instance to use delegated authorizationOpens in a new tab, are typically done using the interactive ^SECURITY routine.

The configuration merge featureOpens in a new tab can help in some cases by allowing you to automatically deploy containerized instances with any desired configuration, but some security tasks are best addressed by using the features of container orchestrators such as Kubernetes, which rely on security mechanisms designed for containerized software. For example, secretsOpens in a new tab are a widely used mechanism in which a small amount of sensitive information is placed in an object that can then be provided by the platform when needed, letting you avoid the inclusion of confidential data in application code; this would be a suitable and safe means of providing an encryption key to a containerized InterSystems IRIS instance configured for startup with unattended key activationOpens in a new tab, which does not require human intervention. In addition, third-party tools, such as Hashicorp’s Vault, work with Kubernetes and other platforms to provide additional support for managing and safeguarding sensitive data with policies and multiple options to fit a range of needs.


For important information about security for Web Gateway containers, see Web Gateway Container Security.

Ownership and Directories

The InterSystems IRIS instance in a container created from an InterSystems image is always named IRIS and is nonrootOpens in a new tab, meaning it was installed and is owned by a user account, irisowner (UID 51773), which does not have root privileges. All file system entities comprising the instance are owned by irisowner, and nothing is therefore owned by root. Operating system-based authenticationOpens in a new tab is enabled on the instance, which means that an irisowner process or client authenticated on another system can connect to the instance without authentication. Because commands issued from outside the container using docker execOpens in a new tab are executed inside the container as irisowner, you can use this command to conveniently connect to the instance without authentication. For example, to open the InterSystems TerminalOpens in a new tab for an instance in a container named iris273 without being prompted for credentials, you could use the following command:

docker exec -it iris273 iris terminal IRIS 

The installation directory (containing the mgr/ subdirectory) within the container is /usr/irissys/. The working directory (containing files such as iris-main.log) is /home/irisowner/, while the registry directory is /home/irisowner/irissys/.

For information about the installation parameters used to specify these configuration details, see Required Environment Variables. For more information on these general installation-related topics, see Install on UNIX®, Linux, and macOSOpens in a new tab.

InterSystems provides tools that allow you to determine these configuration details for InterSystems IRIS-based images that you create, as described in InterSystems IRIS Containerization Tools.


When using the durable %SYS feature to provide a containerized InterSystems IRIS instance with persistent storage, the host file system location mounted and specified for this purpose must be writable by user 51773. (You will most likely need root privileges to effect this.)

When using durable %SYS with an InterSystems IRIS container deployed with the Pod Manager tool (podman), you must do the following:

  • Issue the following command before starting the container:

    podman unshare chown 51773:51773 $INSTANCEDIR

    where $INSTANCEDIR is the host file system location that will contain the durable %SYS directory.

  • If Red Hat Security-Enhanced Linux (SELinux) is active, include the --privileged=true flag when creating the container.

When using durable %SYS on Kubernetes without the InterSystems Kubernetes OperatorOpens in a new tab, you must include the following security contextOpens in a new tab setting in the pod specification:

  fsGroup: 51773

Before upgrading an InterSystems IRIS container that uses durable %SYS to version 2021.2 or later, you must make the existing durable directory writable by user 51773.


If the irisowner user account is not defined in the /etc/passwd file on the system hosting the container, it is represented by its UID (51773) on that system.

Authentication and Passwords

OS-based authentication (see Operating System–Based AuthenticationOpens in a new tab) is enabled for the InterSystems IRIS instance in a container created from an InterSystems image, and password authentication is disabled for the owner (irisowner).

InterSystems IRIS is installed with several predefined user accounts, including the _SYSTEM account (see Predefined User AccountsOpens in a new tab). The default password for the predefined accounts is SYS. For effective security, it is important that this default password be changed immediately upon deployment of your container, which can be done using one of the following approaches. Any of these methods can be incorporated into automated deployment.


If you do not use one of the methods listed here to modify the default password, it is critical that you either log in to each predefined account and change the password or disableOpens in a new tab the accounts as soon as possible.

Only the iris-main --password-file option, described below, changes the password (SYS) for the predefined CSPSystem account, which is often configured in the InterSystems Web Gateway as the account used to authenticate to the InterSystems IRIS instances in its server access profiles. If you do not use the --password-file option in particular to change the default password, you must log in to the CSPSystem account and change the password as soon as possible after deployment. For more information about configuring Web Gateway authentication, see Web Gateway Container Security.


Once the instance is deployed and running with the new default password, you should log in to each of the predefined accounts, which are configured to require a password change on first login, so that they are all secured with new individual passwords of your choosing rather than sharing a password; as an alternative, you can also disableOpens in a new tab one or more of them.


To avoid the expiration of passwords 90 days after an InterSystems IRIS image is built, which would occur using the default settings, a containerized instance is configured so that the passwords of the instance owner and the predefined accounts do not expire.

  • The PasswordHash CPF setting

    During automated deployment of InterSystems IRIS on UNIX and Linux platforms, you can change the default password for one or more instances before they are first started using the configuration parameter file (CPF) PasswordHash setting in conjunction with the configuration merge featureOpens in a new tab.

    Rather than recording the plain-text password for each account (a security risk), InterSystems IRIS stores only an irreversible cryptographic hash of that password; when the user logs in, the password value entered is hashed using the same algorithms, and the two versions are compared to authenticate the user. For more information about the stored password hash, see Instance AuthenticationOpens in a new tab.

    You can set or change the stored password hash (and thus the password) for all of a newly-deployed instance’s predefined accounts (enabled user accounts that have at least one assigned role) using the PasswordHashOpens in a new tab setting, which is in the [Startup] section of the CPF. When included in a configuration merge fileOpens in a new tab at deployment (on UNIX® and Linux systems only), this setting customizes the default password of the predefined accounts on the instance (except CSPSystem, which does not have an assigned role), replacing SYS with the password of which the provided value is a hash.

    Immediately after deployment, as noted above, you should individually change the passwords of the predefined accounts from the new default password set by PasswordHash. The PasswordHash parameter works just once for a given instance, and can therefore be left in an instance’s CPF without having any effect.

    The arguments to the PasswordHash parameter are a hashed password and its salt, and optionally the hashing algorithm and work factor used to hash the password (the defaults for the latter are SHA512 and 10000, respectively). All of these arguments are shown in the following example:


    A description of the algorithms used to convert a plain-text password to these values is contained in Instance AuthenticationOpens in a new tab, and tools for applying them are available in the %SYSTEM.EncryptionOpens in a new tab API. However, undertaking this conversion as a manual procedure is not recommended, as it is likely to be error-prone and time-consuming. For your convenience, the InterSystems Container Registry (described in Downloading the InterSystems IRIS Image) provides the image for a nanocontainer, passwordhash, that does this conversion for you and displays the result in the context of the PasswordHash parameter. You can optionally specify the workfactor and algorithm you want to use; if not, the default are used. The following is an example of using this container:

    $ docker run --rm -it -algorithm SHA512 -workfactor 10000
    Enter password:
    Enter password again:

    You would then copy and paste the output and place it in the [Startup] section of your configuration merge file as shown above. After deployment, the default password for the predefined accounts (other than CSPSystem) is what you entered at the prompts.


    You can display usage information using the iris-main --help option as shown:

    $ docker run --help
    Usage of /passwordhash:
      -algorithm string
            Pseudorandom function to use (default "SHA512")
      -workfactor int
            PBKDF2 Work Factor (default 10000)

    You can also provide the password to be hashed as input in the command, for example:

    $ echo **** | docker run --rm -i

    The PasswordHash property can be used just once on any given InterSystems IRIS instance, and only if the default password has not yet been changed for any of the predefined accounts. Because allowing the default password to remain unchanged following deployment is a serious security risk, the PasswordHash setting should be used in a configuration merge operation to change the default password during deployment and not later. (For information on how to change an individual user’s password, see Edit an Existing User Account.)


    Blank passwords cannot be used with the PasswordHash setting.

  • The iris-main --password-file option

    This option to the iris-main entrypoint application changes the default password of an InterSystems IRIS instance’s predefined accounts, including the CSPSystem account, to the contents of a user-provided file during its initial startup in the container, then deletes the password file and creates a sentinel file that prevents it from running again, so that the option will not be invoked every time the container is started. In details, the following steps are taken:

    • If a sentinel file exists in the directory containing the specified password file, the script exits without attempting to change the password.

    • If a sentinel file does not exist, the script

      1. Reads the new password from the specified file.

      2. Shuts down the instance if it is running.

      3. Makes an API call to change the password of all enabled user accounts with at least one role, effectively changing the default password of the instance.

      4. On successful completion of the password change, makes another API call to change the password of the predefined CSPSystem account (as described earlier in this section).

      5. If the password file is writeable, the script:

        • Deletes the password file.

        • Creates a sentinel file.

        If the password file is read-only, no sentinel file is created; this provides compatibility with Docker Secrets, Kubernetes Secrets, and similar technologies.

        The iris-main --password-file option invokes a script,, which can be found in dev/Container/ under the InterSystems IRIS installation directory on Linux platforms (including within an InterSystems-provided iris container). You can call this script in other ways in order to integrate it into your own tools.

    For information about the --password-file option, see The iris-main Program.

  • The SYS.ContainerOpens in a new tab API

    InterSystems IRIS is distributed with an API call, SYS.Container.ChangePassword()Opens in a new tab, that is also useful in scripts and other automation. SYS.Container.ChangePassword()Opens in a new tab changes the password of all of an instance’s enabled user accounts that have at least one assigned role to the contents of a user-provided file. (The option of specifying a read-only password file is provided for compatibility with Docker Secrets, Kubernetes Secrets, and similar technologies.) The change is made during the instance’s first startup, before login is possible, and is called by the script and thus by the iris-main --password-file option. When using it, bear in mind the risks of committing the password to a file for any significant length of time.

    The API also includes the SYS.Container.ChangeGatewayMgrPassword()Opens in a new tab call (also called by the script) which changes the password of the CSPSystem account on both the InterSystems IRIS instance and the local Web Gateway, if any.

    For information about the SYS.Container API, see SYS.Container API.

Locked Down InterSystems IRIS Container

To support the strictest security requirements, InterSystems provides an image named iris-lockeddown, from which you can deploy a highly secure InterSystems IRIS container. The differences between containers from this image and those from the standard iris image are detailed here.


The characteristics of the iris-lockeddown image are subject to change as best practices evolve. We may add, remove, or change features in response to our best understanding of current security practices and the requirements of the production container orchestrators in use by our customers.

  • The instance in a locked down InterSystems IRIS container was installed with Locked Down securityOpens in a new tab, as opposed to the Normal security installation of an instance in the standard InterSystems IRIS container. For details on the differences between Locked Down and Normal security, see Prepare for InterSystems SecurityOpens in a new tab in Securing Your Instance.

  • If InterSystems System Alerting and Monitoring (SAM)Opens in a new tab is deployed with the instance, you must give it access to the instance by changing the Allowed Authentication Method setting of the /api/monitor web application from Password to Unauthenticated. To do this, on the Web Applications page of the Management Portal (System Administration > Security > Applications > Web Applications), click /api/monitor in the left-hand column to display the Edit Web Application page, make the needed change in the Security Settings section, and click Save.

  • In addition to the environment variables defined in the standard container, as listed in the following section, the SYS_CONTAINER_LOCKEDDOWN variable is defined as 1 in a locked down container.

FeedbackOpens in a new tab