Installing InterSystems IRIS on UNIX®, Linux, and macOS

Uncompressing the Installation Kit

If your installation kit is in the form of a .tar file, for example iris-2019.3.0.710.0-lnxrhx64.tar.gz, uncompress the file into a temporary directory to avoid permissions issues, as shown in the following example.

# mkdir /tmp/iriskit 
# chmod og+rx /tmp/iriskit 
# umask 022 
# gunzip -c /download/iris-<version_number>-lnxrhx64.tar.gz | ( cd /tmp/iriskit ; tar xf - )

The installation files uncompress into a directory with the same name as the .tar file, for example /tmp/iriskit/iris-2019.3.0.710.0-lnxrhx64.

Determining Owners and Groups

The installation process prompts for the following user and group information:

• Owner of the instance

• Effective user for the InterSystems IRIS superserver and its jobs

• Effective group for InterSystems IRIS processes

• Group allowed to start and stop the instance

For more information about these categories, see the UNIX® User and Group Identifications section in the “Using InterSystems IRIS on UNIX®, Linux, and macOS” chapter of System Administration Guide.

The user account you identify as Owner of the instance and the group you identify as Group allowed to start and stop the instance must both exist before you begin installation. If an entry you provide at one of these prompts does not exist, the prompt is repeated, so verify that the user and group you intend to provide exist before you begin installation.

If your operating system contains the useradd and groupadd utilities (or mkgroup and mkuser on AIX®), the system creates the account for the effective user for InterSystems IRIS superserver and the effective group for InterSystems IRIS processes, if the entries you provide do not exist. However, if these utilities are not present and an entry you provide does not exist, the prompt is repeated. If you are not sure that your system has these utilities, verify that the user and group you intend to provide exist before you begin installation.

Tools used on UNIX® operating systems to display process ownership may or may not show effective versus real ownership. See the “UNIX® Users, Groups and Permissions” chapter of the System Administration Guide for details on how InterSystems IRIS assigns permissions.

Installing the Required Dependencies

As part of the installation process, the InterSystems IRIS installer checks whether the system has the required dependencies. If the system is missing any dependencies, the installation fails with a message specifying which dependencies to install before rerunning the installer.

You can run the requirements checker independently from an installation by running irisinstall with the prechecker option (e.g. # irisinstall --prechecker). This is useful when modifying or upgrading an InterSystems IRIS dependency to ensure the requirements are still met after the change.

The requirements checker always runs during instance startup. The startup fails if the requirements are not met.

Choosing a Configuration Strategy

There are several methods to configure InterSystems IRIS before installation. These methods are particularly useful when considering automated deployment, as they reduce the need to adjust settings after the installation is complete.

Before installing InterSystems IRIS, consider whether to use any of these methods:

• Configuration merge allows you to define an InterSystems IRIS configuration in a merge file. A merge file specifies desired settings and can also perform administrative actions such as creating users, namespaces, and databases. You may apply a merge file during or after installation.

• Installation manifests describe a specific InterSystems IRIS configuration, and can be used with either the irisinstall or irisinstall_silent commands.

• Adding Unix® Installation Packages to an InterSystems IRIS Distribution describes how to add new packages to an InterSystems IRIS distribution.

Standard InterSystems IRIS Installation Procedure

Standard InterSystems IRIS installation consists of a set of modular package scripts. The scripts conditionally prompt for information based on input to previous steps, your system environment, and whether or not you are upgrading an existing instance. The first stage of the installation stores all gathered information about the install in a parameter file. You then confirm the specifics of the installation before the actual install takes place. The final phase performs the operations that are contingent upon a successful install, such as instance startup.

The installation script, irisinstall, does the following:

• Installs the InterSystems IRIS system manager databases.

• Starts InterSystems IRIS in installation mode.

• Installs InterSystems IRIS system manager globals and routines.

• Shuts down InterSystems IRIS and restarts using the default configuration file (iris.cpf). Upgrade installations restart using their updated configuration files.

To perform the standard InterSystems IRIS server installation, follow the installation procedure.

1. Log in as user ID root. The standard InterSystems IRIS installation must be run by a user with root privileges. It is acceptable to su (superuser) to root while logged in from another account.

   Note:

   If root is unavailable, you can perform a non-standard, limited InterSystems IRIS installation as a nonroot user. For details, read the Installing InterSystems IRIS as a Nonroot User section below before continuing the installation procedure.

2. As a user with root privileges, start the installation procedure by running the irisinstall script, located at the top level of the installation files:

   # /<pathname>/irisinstall
   

   

   where pathname is the location of the installation kit, typically the temporary directory to which you have extracted the kit, as described in the Uncompressing the Installation Kit section of this chapter.

3. The installation script identifies your system type and validates it against the installation type on the distribution media. If your system supports more than one type, for example, 32-bit and 64-bit, or if the install script cannot identify your system type, it prompts you with additional questions. This may include asking for the “platform name” in the format of the string at the end of the installer kit name. If your system type does not match that on the distribution media, the installation stops. Contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab for help in obtaining the correct distribution.

4. The script displays a list of any existing InterSystems IRIS instances on the host.

5. At the Enter instance name: prompt, enter an instance name, using only alphanumeric characters, underscores, and dashes. If an instance with this name already exists, the program asks if you wish to upgrade it. If no such instance exists, it asks if you wish to create it and asks you to specify its installation directory. If the directory you specify does not exist, it asks if you want to create it. The default answer to each of these questions is Yes. Be sure to review the Installation Directory section in the “Preparing to Install InterSystems IRIS” chapter for more important information about choosing an installation directory.

   Note:

   If you select an existing instance that is of the same InterSystems IRIS version as the installation kit, the installation is considered an upgrade, and you can use the Custom selection, described in the following step, to modify the installed client components and certain settings.

   The InterSystems IRIS registry directory, /usr/local/etc/irissys, is always created along with the InterSystems IRIS installation directory.

6. Next, select the installation type from the choices:

   Select installation type.
       1) Development - Install IRIS server and all language bindings
       2) Server only - Install IRIS server
       3) Custom - Choose components to install
   Setup type <1>? 
   

   Note:

   If the CSP Gateway is already installed on your system when you install the Web Gateway, the installer automatically upgrades the CSP Gateway to the Web Gateway. For details, see Preexisting CSP Gateway.

   Review the Setup Type section in the “Preparing to Install InterSystems IRIS” chapter of this book to decide which installation type is appropriate. The default for new instances is Development, which contains a complete installation of InterSystems IRIS; if you are upgrading an existing instance, the default is the option that was used to originally install the instance.

   Note:

   If you choose the Custom option, see the InterSystems IRIS Custom Installation section for additional installation steps.

7. Next, indicate whether to install InterSystems IRIS with 8-bit or Unicode character support. On upgrade, you can convert from 8-bit to Unicode, but not the reverse.

8. For new instances, you must next specify security settings. (Security settings cannot be changed when upgrading.)

   First, decide how restrictive you want the initial InterSystems security settings to be: choose from Minimal (1), Normal (2), and Locked Down (3). For a detailed explanation of these security settings, see Initial InterSystems Security Settings.

   Minimal is only available for InterSystems IRIS installations. If you choose this, you can skip the next step; the installer sets the owner of the instance as root.

   Important:

   There are additional security settings that you can choose only through a custom install. See InterSystems IRIS Custom Installation for details.

9. If you enter 2 or 3, the script asks for additional information:

   1. Instance owner — Enter the username of the account under which to run InterSystems IRIS processes. See Determining Owners and Groups for information about this account. Once InterSystems IRIS is installed, you cannot change the owner of the instance.

   2. Password for the instance owner — Enter the password for the username you entered at the previous prompt, and enter it again to confirm it. A privileged InterSystems IRIS user account is created for this user with the %All role.

      This password is used not only for the InterSystems IRIS privileged user account, but also for the _SYSTEM, Admin, and SuperUser predefined user accounts. For more details on these predefined users, see Predefined User Accounts.

   3. Password for the CSPSystem predefined user.

   Note:

   The passwords must meet the criteria described in the Initial User Security Settings table. Passwords entered during this procedure cannot include space, tab, or backslash characters; the installer reject such passwords.

10. At this point in the installation, you are asked which group should be allowed to start and stop InterSystems IRIS. Only one group can have these privileges, and it must be a valid group on the machine; see Determine Owners and Groups for more information. Enter the name or group ID number of an existing group; InterSystems IRIS verifies that the group exists before proceeding.

11. Finally, for a new instance, or if the script does not detect an iris.key file in the mgr directory of an existing instance when upgrading, you are prompted for a license key file. If you specify a valid key, the license is automatically activated and the license key copied to the instance’s mgr directory during installation, and no further activation procedure is required. If you do not specify a license key, you can activate a license key following installation. See Activating a License Key in the “Managing InterSystems IRIS Licensing” chapter of the System Administration Guide for information about licenses, license keys and activation.

    Note:

    On macOS, you may receive a prompt regarding network connections for irisdb. If so, select Allow.

12. Review your installation options and press enter to proceed with the installation. File copying does not begin until you answer Yes.

When the installation completes, you are directed to the appropriate URL for the Management Portal to manage your InterSystems IRIS system. See the “Using the Management Portal” chapter of the System Administration Guide for more information.

Continue to the Post-Installation Tasks section to complete the installation process.

Client-Only InterSystems IRIS Installation Procedure

The InterSystems IRIS distribution contains a separate script to install a client-only version of InterSystems IRIS. The installation process is fairly simple. You do not need to install as root. The files from this install have the user and group permissions of the installing user. To perform the InterSystems IRIS client installation:

1. Start the installation procedure by running the irisinstall_client script, located at the top level of the installation files:

   # /<pathname>/irisinstall
   
   

   

   where pathname is the location of the installation kit, typically the temporary directory to which you have extracted the kit, as described in the Uncompressing the Installation Kit section of this chapter.

2. The installation script identifies your system type and validates it against the installation type on the distribution media. If your system supports more than one type, for example, 32-bit and 64-bit, or if the install script cannot identify your system type, it prompts you with additional questions. If your system type does not match that on the distribution media, the installation stops. Contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab for help in obtaining the correct distribution.

3. At the Enter a destination directory for client components prompt, specify the installation directory. If the directory you specify does not exist, it asks if you want to create it. The default answer is Yes. Be sure to review the Installation Directory section in the “Preparing to Install InterSystems IRIS” chapter for more important information about choosing an installation directory. Press Enter to continue with the installation.

   Note:

   The InterSystems IRIS registry directory, /usr/local/etc/irissys, is always created along with the InterSystems IRIS installation directory.

4. Choose from the available client component options. Components that require the InterSystems IRIS server on the same machine do not appear in the list. For example:

   Client component selection
   
      [*]    1) ODBC client
      [*]    2) C++ binding
      [*]    3) C++ SDK
             +) Select all
   
   Enter the number of each component you wish to install.
   Enter the number of an already selected component to deselect it.
   Multiple selections can be separated by spaces.
   Enter a blank line to continue.
   

   You can use the plus sign (+) to select all components.

The list of client-only components does not include the shared library support or the light C++ binding because these components require a server installation.

You cannot use this script to update client components in server installations. Use the irisinstall script instead.

See the following guides in the InterSystems IRIS Language Bindings set for more information on the specific client components in the selection list:

• Using the InterSystems ODBC Driver

Continue to the Post-Installation Tasks section to complete the installation process.

Installing as a Nonroot User

When installing InterSystems IRIS in a production environment, InterSystems recommends using root privileges. It is possible to run an InterSystems IRIS installation without root privilege, but these installations have several limitations. The following sections describe these limitations and the differences from a standard InterSystems IRIS installation.

• Why InterSystems IRIS Installation Uses Root

• Nonroot Installation Limitations

• Nonroot Installation Differences

Unattended Installation Parameters

The following table describes the parameters used with the irisinstall_silent script in unattended installation.

Unattended Installation Packages

The installation scripts for each component are contained in the packages directory below the directory containing the irisinstall_silent script. Each package is in its own directory, and each package directory contains a manifest.isc file defining prerequisite packages for the package in that directory.

The standard_install package is the starting point for a server install in which all packages are installed. To define a custom package, you can use the manifest.isc file for the standard_install package as a template, as follows:

1. Copy the standard_install directory to a new directory.

   For example, copy it to a directory named custom_install; initially, the manifest.isc file in the new directory is similar to the following:

   #This is the target for a standard (non-client-only) install
   package: standard_install
   prerequisite: install_mode
   prerequisite: database_server
   prerequisite: databases
   prerequisite: gadget
   prerequisite: fop
   prerequisite: renderserver
   prerequisite: printserver
   prerequisite: excelexporter
   prerequisite: callin_components
   prerequisite: client_components
   prerequisite: addenda
   prerequisite: install_confirmation
   prerequisite: copyright
   

2. In the new directory, modify the manifest.isc file as follows:

   • Set the package key to the value of the directory name (required).

   • Add and/or remove prerequisites for your custom installation.

   For example, in the following manifest.isc file, the value of the package key has been changed to match the directory name (custom_install).

   #This is the target for a custom (non-client-only) install
   package: custom_install
   prerequisite: install_mode
   prerequisite: database_server
   prerequisite: gadget
   prerequisite: fop
   prerequisite: renderserver
   prerequisite: printserver
   prerequisite: excelexporter
   prerequisite: callin_components
   prerequisite: client_components
   prerequisite: addenda
   prerequisite: install_confirmation
   prerequisite: copyright
   

Then you can specify the new custom package when performing unattended installations; for example: sudo ISC_PACKAGE_INSTANCENAME="MyIris" ./irisinstall_silent custom_install.

Unattended Installation Examples

The following examples illustrate how you can use the irisinstall_silent script for unattended installation of InterSystems IRIS on UNIX® platforms.

In this example, all packages are installed with minimal security:

sudo ISC_PACKAGE_INSTANCENAME="MyIris" ISC_PACKAGE_INSTALLDIR="/opt/MyIris1" ./irisinstall_silent

If the MyIris instance already exists, it is upgraded; otherwise, it is installed in the /opt/MyIris1 directory.

In this example, the installation is aborted and an error is thrown if the instance named MyIris does not already exist:

sudo ISC_PACKAGE_INSTANCENAME="MyIris" ./irisinstall_silent

In this example, only the database_server and odbc packages and the odbc client binding are installed with minimal security:

sudo ISC_PACKAGE_INSTANCENAME="MyIris" ISC_PACKAGE_INSTALLDIR="/opt/MyIris2"
ISC_PACKAGE_CLIENT_COMPONENTS="odbc" ./irisinstall_silent database_server odbc

Starting InterSystems IRIS

For most installations, InterSystems IRIS starts automatically when the install completes. If you need to start InterSystems IRIS, first log in to your operating system, then start InterSystems IRIS using the iris command:

iris start <instname>

Where instname is the instance name that you chose during the installation. On Red Hat Linux, the start command is:

service <instname> start

Use the iris command to start and stop InterSystems IRIS. It is described in greater detail in the Controlling InterSystems IRIS Instances section of the System Administration Guide.

Once InterSystems IRIS is started, initiate an InterSystems IRIS session using the iris terminal command, as described in Connecting to an InterSystems IRIS Instance in the “Using Multiple Instances of InterSystems IRIS” chapter of the System Administration Guide:

iris terminal <instname> [parameters]

Where instname is the instance name that you chose during the installation.

For more information, see the “Using InterSystems IRIS on UNIX®, Linux, and macOS” chapter of the System Administration Guide.

Installing a Development Environment

InterSystems IRIS installs a private Apache Web server so you can access the Management Portal, but does not include a development environment on UNIX®; therefore, you must choose between Studio, which must be run on a Windows client, and the InterSystems ObjectScript extensions for Visual Studio CodeOpens in a new tab.

To install a Windows client, follow the instructions in the Installing Client Components Only section of the “Installing InterSystems IRIS on Microsoft Windows” chapter in this book. Once the Windows client is installed, perform the following tasks to connect Studio to your instance:

1. Open the InterSystems IRIS launcher on the Windows client.

2. Point to Preferred Server and click Add/Edit to add a remote server connection to the InterSystems IRIS instance just installed. Make sure you specify the appropriate port numbers for this connection.

3. Point to Remote System Access, point to Studio, and then click the appropriate connection name you entered in the previous step.

Multiple InterSystems IRIS Instances

You can install and simultaneously run multiple instances on a single machine. To do so, install InterSystems IRIS as for a single installation, giving each instance a unique name, a unique installation directory, and a unique port number.

For more information, reference the Configuring Multiple InterSystems IRIS Instances section of the “Using Multiple Instances of InterSystems IRIS” chapter in System Administration Guide.

Uninstalling InterSystems IRIS

To safely uninstall InterSystems IRIS, follow this procedure:

1. Find the name of the InterSystems IRIS instance you wish to delete using the iris list command to list all the instances on your machine:

   iris list
   

   

2. Verify the instance is stopped. If it is not, stop it with the iris stop command:

   iris stop <instname>
   

   

   Where instname is the instance name that you chose during the installation. If it hangs, force it down using iris force:

   iris force <instname>
   

   

3. Remove the instance using the iris delete command:

   iris delete <instname>
   

   

4. Remove the installation directory using the following operating system command:

   rm -r <directory>
   

   
   Important:

   Be aware that this removes files you may wish to keep. For example: the license key (iris.key), the configuration file (iris.cpf), and the user database file (iris.dat).

The uninstall procedure removes all files installed and created during normal InterSystems IRIS processing, including journal and temporary database files.

Adjustments for Large Number of Concurrent Processes on macOS

Make the following adjustments if you are running a system that requires a large number of processes or telnet logins:

1. Remote connections — The number of pty (pseudo terminal) connections is limited to 128 system-wide. If your applications count on telnet or other pty-using connections for users to access, keep this in mind.

2. Number of processes — If the pty limit is not a problem, but you need to run a larger number of processes, there are limits to that as well.

   • System-wide process limits — The kern.maxproc, kern.maxprocperuid parameters are set to 532 and 100 by default. You can change them using the following commands:

     administrator$ sudo sysctl -w kern.maxproc=2500
     kern.maxproc: 2065 -> 2500
     administrator$ sudo sysctl -w kern.maxprocperuid=2500
     kern.maxprocperuid: 2000 -> 2500
     
     administrator$ sysctl -a | grep maxproc
     kern.maxproc = 2500
     kern.maxprocperuid = 2500
     
     

     

     Note, however, that 2500 is the absolute unchangeable upper limit.