Skip to main content

Preparing to Install InterSystems IRIS

InterSystems IRIS® supports multiple methods of deployment, and runs on many different platforms.

The Installation Guide describes the process of installing InterSystems IRIS from an installation kit. InterSystems IRIS can also be deployed in containers, as described in Running InterSystems Products in ContainersOpens in a new tab, and provides several methods for automated deployment, which are described in Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. If you are using one of these methods, consult the documentation listed in the latter.

Before installing, confirm that InterSystems IRIS supports your server or development platform. Review the InterSystems IRIS Data Platform Supported Platforms document for the current release, which describes what technologies are supported for each release.

Before installing, you should consider the system resources that your disposal, make sure they will be sufficient for the application you will be developing and running, and manage them to optimize your system’s performance. You can read more about this process in System Resource Planning and Management.

Installation Planning Considerations

There are a few different ways to configure a new installation of InterSystems IRIS. When the installation runs, it prompts for the following information to decide which configuration to install:

The following section can be performed before or after installing InterSystems IRIS:

Installation Directory

The installation directory is the directory in which an InterSystems IRIS instance is installed. Throughout the documentation, this is referred to as install-dir. Once InterSystems IRIS is installed, it is impossible to change the installation directory.

There are several restrictions to what you can specify as the install-dir. The directory must be a fully resolved physical path, containing no symbolic links. The name of the directory can only use characters in the US ASCII character set, and cannot contain a caret (^). Also, InterSystems IRIS cannot be installed into a directory that is:

  • a UNC (non-local) path.

  • at the root level of a drive (such as C:\).

  • anywhere under the \Program Files directory.

If unspecified during installation, install-dir uses a default value. This default varies by platform, installation type, and user choice, as shown in the following table:

Platform
Installation Type
Default Directory
Windows
attended C:\InterSystems\Iris (or IrisN when multiple instances exist), unless installing user specifies otherwise.
unattended C:\InterSystems\Iris (or IrisN when multiple instances exist), unless INSTALLDIR property specifies otherwise.
UNIX®, Linux, macOS
attended No default; installing user must specify.
Do not choose the /home directory, any of its subdirectories, or the /usr/local/etc/irissys directory.
unattended No default; ISC_PACKAGE_INSTALLDIR parameter required.

Setup Type

During installation, you can choose which components of InterSystems IRIS you would like to install. The options are:

  • Development — Includes the InterSystems IRIS Database Engine (User Database, Language Gateways, Server Monitoring Tools), Studio (on Windows only), all supported language bindings, and xDBC (ODBC and JDBC) drivers. Select this option if you plan to use this instance to perform both client and server tasks.

  • Server — Includes InterSystems IRIS Database Engine (User database, Language Gateways, Server monitoring tools) and Web Gateway. Select this option if you plan to use this instance as an InterSystems IRIS database server which can be accessed by InterSystems IRIS clients.

  • Custom — Allows user to specify specific components to install or uninstall. Select this option if you to install or remove specific InterSystems IRIS components.

On Windows, you can choose from these two additional setup types:

  • Client — Includes Studio, and the xDBC (ODBC and JDBC) drivers. Select this option if you plan to use this instance as a client to an InterSystems IRIS database server on this or another computer.

  • Web Server — Includes Web Gateway (IIS, Apache 2.0, Apache 2.2). Select this option if you want to install only those parts of InterSystems IRIS that are required for the Web Gateway.

The following table identifies which components are installed for each setup type. When performing a custom installation, you may include only individual components from a group.

Components Installed by Setup Type
Component Group Components Development Server Client Web
InterSystems IRIS Database Engine (InterSystems IRIS Server)
Server Monitoring Tools
User database
Language Gateways
Agent Service (ISCAgent)
Apache FOP (Formatting Objects Processor)
InterSystems IntegratedML
X
X
   
InterSystems IRIS launcher (on Windows only)  
X
X
X
 
Studio (on Windows only)  
X
 
X
 
xDBC
ODBC Driver
Java Database Connectivity
X
 
X
 
InterSystems IRIS Application Development
Java Binding for InterSystems IRIS
InterSystems IRIS shared library support
.NET Binding for InterSystems IRIS
Threaded Server Libraries
Other Samples
X
     
Web Gateway
CSP for IIS
CSP for Apache 2.0.x
CSP for Apache 2.2.x
 
X
 
X

Preexisting CSP Gateway

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. However, the installer creates a new copy of the CSP.ini file. To preserve the CSP.ini file from the CSP Gateway, perform the following steps:

  1. Create a backup of the CSP.ini file, located in install-dir/CSP/bin.

  2. Execute the Web Gateway installer.

  3. Restore the backup of CSP.ini.

Note:

Installing the Web Gateway does not close any old connections. To remove these old connections, you must manually close them from the System Status page.

Character Width Setting

You must choose between 8-bit or Unicode (16-bit) character width for your installation. An 8-bit instance cannot process data in 16-bit format, while a Unicode instance can process both 8-bit and 16-bit data.

If you need your instance to store and process data in a language that uses only Unicode character sets, such as Japanese, you must select Unicode. If the base character set for the locale your instance uses is based on the Latin-1 character set, ISO8859-1, you can select 8-bit, but bear in mind:

  • If you select 8-bit, the data stored by your instance is portable only to 8-bit locales based on the same character set.

  • If you select Unicode, the data stored by the instance is not portable to an 8-bit instance.

Port Numbers

A standard installation sets the following port numbers for an InterSystems IRIS instance:

  • Superserver port number1972. If taken, then 51773 or the first available subsequent number.

  • Web server port number52773 or the first available subsequent number

You can assign different port numbers during a new installation by performing a Custom installation (see Setup Type). You cannot enter a port number greater than 65535.

For information about setting the port numbers on an already-installed instance of InterSystems IRIS, see Set Port Numbers in the “Using Multiple Instances of InterSystems IRIS” chapter of the System Administration Guide.

Security Setting

An InterSystems IRIS installation has three initial security configurations: Minimal, Normal, or Locked Down. Minimal is only available for InterSystems IRIS installations. If you select Normal or Locked Down, the installer prompts for additional information, such as a password and account information.

For more information, see Initial InterSystems Security Settings.

Install the VS Code - ObjectScript development

Visual Studio Code (VS Code) is a free source code editor made by Microsoft for Windows, Linux and macOS. The InterSystems ObjectScript extension for Visual Studio Code enables you to use VS Code to connect to an InterSystems IRIS server and develop code in ObjectScript. An alternative to VS Code - ObjectScript is Studio, which installs alongside InterSystems IRIS on Windows-based operating systems.

For information on downloading and using VS Code - ObjectScript, see https://intersystems-community.github.io/vscode-objectscript/Opens in a new tab.

Memory Planning and Management

Memory management is a very important factor in maximizing the performances of an InterSystems IRIS deployment. Read the following planning considerations:

Minimum Disk Space Requirements

The installation kit must be available, either on your computer or on a network, to perform an installation. InterSystems recommends you have at least 1.5 GB of disk space available before installing InterSystems IRIS. The installation procedure confirms that sufficient disk space is available before installing.

Additional Memory Resources

Correctly sizing system memory is critical for maximizing the performance and availability of InterSystems IRIS and your application. InterSystems IRIS memory usage is discussed in Memory Planning which provides guidelines for calculating initial memory requirements so you can determine whether your system has sufficient memory.

After installation, monitoring how InterSystems IRIS allocates memory is an important performance factor. If InterSystems IRIS is not allocating memory efficiently, you can adjust memory settings for processes, routine and database caches, and the generic heap. For information about how to perform these memory-related tasks, see Reviewing and Monitoring Memory Usage and Memory and Startup Settings.

Platform-Specific Preparations

The following sections contain platform-specific considerations. Review the following sections that apply to your intended installation platform:

Supported Platforms and Components

For information about supported technologies for a release version of InterSystems IRIS, including supported operating systems and web servers, see the Supported Technologies chapter of the online InterSystems Supported Platforms document for the release.

To achieve optimal journal performance and ensure journal data integrity when there is a system crash, InterSystems recommends various file systems and mount options for journal files. For specific platform details see the UNIX® File System Recommendations section of the “Journaling” chapter of the InterSystems IRIS Data Integrity Guide.

Note:

With each instance, InterSystems IRIS installs a private web server and a private Web Gateway to serve CSP pages to ensure proper operation of the Management Portal. The private web server ensures that:

  • the Management Portal runs out of the box.

  • development environments are provided with an out-of-the-box testing capability.

The private web server is not supported for any other purpose. You should not use the private web server for deployments of http-based applications, including CSP and SOAP over http or https; instead, you must install and deploy one of the supported web servers.

The private web server configuration is preserved through upgrades. You can disable the private web server using the WebServer CPF parameter

On Windows, the private web server Windows service name is “Web Server for instance name”. InterSystems IRIS installs the web server into the install-dir\httpd directory. It is uninstalled when you uninstall the corresponding InterSystems IRIS instance.

For more information, see Using or Replacing the Private Web Server.

Maximum User Process Recommendations

Ensure that the maximum user processes is set high enough to allow all InterSystems IRIS processes for a given user, as well as other default processes, to run on the system.

AIX® Platform Notes

The default settings of several AIX® parameters can adversely affect performance. The settings and recommendations are detailed for the following:

I/O Pacing Parameters

AIX® implements an I/O pacing algorithm that may hinder InterSystems IRIS write daemons. In AIX® 5.2 and AIX® 5.3, I/O pacing is automatically enabled when using HACMP clustering; beginning in AIX® 6.1, however, I/O pacing is enabled on all systems and the default high-water mark is set higher than in earlier releases.

If write daemons are slowing or stalling, you may have to adjust the high-water mark; for information, see Disk-I/O PacingOpens in a new tab in the IBM AIX documentation.

Important:

Beginning in AIX® 6.1, you should not have to make any high-water mark adjustments.

If you have questions about the impact to your system, however, contact the InterSystems Worldwide Response Center (WRC)Opens in a new tab or your AIX® supplier before making any changes. These recommendations apply to both JFS and Enhanced JFS (JFS2) file systems.

File System Mount Option

Different mount options may improve performance for some workloads.

Note:

Non-InterSystems IRIS workloads that benefit from file system caching (for example, operating system-level backups and/or file copies) are slowed by the cio mount option.

To improve recovery speed using the IRIS.WIJ file after a hard shutdown or system crash, InterSystems recommends a mount option that includes file system buffering (for example, rw) for the file system that contains the IRIS.WIJ file.

For information about mount options, see mount CommandOpens in a new tab in the IBM AIX documentation.

Memory Management Parameters

The number of file systems and the amount of activity on them can limit the number of memory structures available to JFS or JFS2, and delay I/O operations waiting for those memory structures.

To monitor these metrics, issue a vmstat -vs command, wait two minutes, and issue another vmstat -vs command. The output looks similar to the following:


# vmstat -vs
              1310720 memory pages
              1217707 lruable pages
               144217 free pages
                    1 memory pools
               106158 pinned pages
                 80.0 maxpin percentage
                 20.0 minperm percentage
                 80.0 maxperm percentage
                 62.8 numperm percentage
               764830 file pages
                  0.0 compressed percentage
                    0 compressed pages
                 32.1 numclient percentage
                 80.0 maxclient percentage
               392036 client pages
                    0 remote pageouts scheduled
                    0 pending disk I/Os blocked with no pbuf
                 5060 paging space I/Os blocked with no psbuf
              5512714 filesystem I/Os blocked with no fsbuf
               194775 client filesystem I/Os blocked with no fsbuf
                    0 external pager filesystem I/Os blocked with no fsbuf

If you see an increase in the following parameters, increase the values for better InterSystems IRIS performance:

  • pending disk I/Os blocked with no pbuf

  • paging space I/Os blocked with no psbuf

  • filesystem I/Os blocked with no fsbuf

  • client filesystem I/Os blocked with no fsbuf

  • external pager filesystem I/Os blocked with no fsbuf

When increasing these parameters from the default values:

  1. Increase the current value by 50%.

  2. Check the vmstat output.

  3. Run vmstat twice, two minutes apart.

  4. If the field is still increasing, increase again by the same amount; continue this step until the field stops increasing between vmstat reports.

Important:

Change both the current and the reboot values, and check the vmstat output regularly because I/O patterns may change over time (hours, days, or weeks).

See the following IBM web pages for more detailed information:

AIX® Tunable Parameters

AIX® Interprocess Communication Tunable Parameters

The following table lists the tunable parameters for the IBM pSeries AIX® 5.2 operating system. None of the following listed parameters require tuning because each is dynamically adjusted as needed by the kernel. For more information, see Interprocess communication tunable parametersOpens in a new tab in the AIX documentation.

Parameter Purpose Dynamic Values
msgmax Specifies maximum message size. Maximum value of 4 MB
msgmnb Specifies maximum number of bytes on queue. Maximum value of 4 MB
msgmni Specifies maximum number of message queue IDs. Maximum value of 4096
msgmnm Specifies maximum number of messages per queue. Maximum value of 524288
semaem Specifies maximum value for adjustment on exit. Maximum value of 16384
semmni Specifies maximum number of semaphore IDs. Maximum value of 4096
semmsl Specifies maximum number of semaphores per ID. Maximum value of 65535
semopm Specifies maximum number of operations per semop() call. Maximum value of 1024
semume Specifies maximum number of undo entries per process. Maximum value of 1024
semvmx Specifies maximum value of a semaphore. Maximum value of 32767
shmmax Specifies maximum shared memory segment size. Maximum value of 256 MB for 32-bit processes and 0x80000000u for 64-bit
shmmin Specifies minimum shared-memory-segment size. Minimum value of 1
shmmni Specifies maximum number of shared memory IDs. Maximum value of 4096
maxuproc

maxuproc, which specifies the maximum number of processes than can be started by a single nonroot user, is a tunable parameter that can be adjusted as described in this subsection.

If this parameter is set too low then various components of the operating system can fail as more and more users attempt to start processes; these failures include loss of CSP pages, background tasks failing, etc. Therefore, you should set the maxuproc parameter to be higher than the maximum number of processes that might be started by a nonroot user (including interactive users, web server processes, and anything that might start a process).

Note:

Do not set the value excessively high because this value protects a server from a runaway application that is creating new processes unnecessarily; however, setting it too low causes unexplained problems.

InterSystems suggests that you set maxuproc to be double your expected maximum process count which gives a margin of error but still provides protection from runaway processes. For example, if your system has 1000 interactive users and often runs 500 background processes, then a value of at least 3000 would be a good choice.

The maxuproc value can be examined and changed either from the command line or from the smit/smitty administrator utilities, both as root user, as follows:

  • From the command line, view the current setting:

    
    # lsattr -E -l sys0 -a maxuproc
    

    then modify the value:

    
    # chdev -l sys0 -a maxuproc=NNNNNN
    

    where NNNNNN is the new value.

  • From the administrator utility smit (or smitty) choose System Environments > Change / Show Characteristics of Operating System > Maximum number of PROCESSES allowed per user.

If you increase the value of maxuproc, the change is effective immediately. If you decrease the value of maxuproc, the change does not take effect until the next system reboot. In both cases the change persists over system reboots.

Required C/C++ Runtime Libraries

You must ensure that the required C/C++ runtime is installed on your IBM AIX® system before installing InterSystems IRIS.

InterSystems IRIS for AIX is compiled using the IBM XL C/C++ for AIX 16.1.0 compiler. If the system on which you are installing InterSystems IRIS does not have the corresponding version of the runtime already installed, you must install it. You can download the runtime from IBM XL C/C++ Runtime for AIX 16.1Opens in a new tab on the IBM Support website.

Use of Raw Ethernet

In order to use Raw Ethernet, an IBM AIX® machine must have the DLPI (Data Link Provider Interface) packages installed. If the machine does not have the DLPI packages, obtain them from your IBM provider and create DLPI devices through the following procedure:

  1. Log in as root.

  2. In the PSE drivers section of the /etc/pse.conf file, uncomment the four lines that refer to the DLPI drivers.

  3. Save the file.

  4. Restart the computer.

If the DLPI devices are not installed, the EthernetAddress() method of the %SYSTEM.INetInfoOpens in a new tab class returns a null string rather than information about the Ethernet device.

Red Hat Linux Platform Notes

This topic includes the information on the following adjustments:

Shared Memory Limit

The default shared memory limit (shmmax) on Linux platforms is 32 MB. This value is too small for InterSystems IRIS, but it can be changed in the proc file system without a restart. The new memory limit remains in effect until you restart the Red Hat Linux system.

For example, to allow 128 MB, type the following command:


$ echo 134217728 >/proc/sys/kernel/shmmax

You can put this command into a startup script.

Alternatively, you can use sysctl(8), if available, to set this parameter permanently. Add a line to the/etc/sysctl.conf similar to the following:


kernel.shmmax = 134217728

This file is usually processed at startup, but sysctl can also be called explicitly later.

Important:

The msgmni parameter may also be set too low if you are running more than one instance of InterSystems IRIS on a machine. Set this value to three times the number of instances of InterSystems IRIS that run simultaneously on your system.

Other parameters are sufficiently sized for an InterSystems IRIS application. To view the values of other parameters, look in the files /usr/src/linux/include/asm-xxx/shmparam.h and /usr/src/linux/include/linux/sem.h.

For more information, reference “The proc File SystemOpens in a new tab” chapter of the Red Hat Enterprise Linux 4: Reference Guide.

Locked-in Memory

On Linux platforms, if shared memory is allocated in huge pages, the pages are automatically locked in memory and no further action is required. See the Configuring Huge Pages on Linux section in this chapter for information about allocating huge pages.

If not using huge pages, you can configure InterSystems IRIS to lock the shared memory segment in memory to prevent paging. This is described in the LockSharedMemory section of the “memlock” entry in the Configuration Parameter File Reference.

Otherwise, you must increase the maximum size that may be locked into memory. The default value is 32 KB. View the current value using the ulimit command.

For example, to display all current limits:


bash$ ulimit -a 
core file size (blocks, -c) unlimited 
data seg size ( KBytes, -d) unlimited 
file size (blocks, -f) unlimited 
pending signals (-i) 1024 
max locked memory (KBytes, -l) 32 <---------- THIS ONE 
max memory size (KBytes, -m) unlimited 
open files (-n) 1024 
pipe size (512 bytes, -p) 8 
POSIX message queues (bytes, -q) 819200 
stack size ( KBytes, -s) 10240 
cpu time (seconds, -t) unlimited 
max user processes (-u) 49000 
virtual memory ( KBytes, -v) unlimited 
file locks (-x) unlimited 

To display only max-locked memory, use the -l option:


bash$ ulimit -l 
32 

If you have privileges, you can alter the value directly using the ulimit command; however, it is better to update the memlock parameter in the /etc/security/limits.conf file. If the memlock limit is too low, Linux reports a ENOMEM - "Not enough memory" error, which does not make the cause obvious. The actual memory is allocated; it is the lock that fails.

For more information, see memlock in the Configuration Parameter File Reference.

Adjusting for Large Number of Concurrent Processes

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

  1. In the /etc/xinetd.d/telnet file, add the following line:

    
    instances = unlimited
    
    
  2. In the /etc/xinetd.conf file, add or change the instances setting to:

    
    instances = unlimited
    
    
  3. After you make these modifications, restart the xinetd services with:

    
    # service xinetd restart
    
  4. The default pty (pseudo terminal connection) limit is 4096. If this is not sufficient, add or change the maximum pty line in the /etc/sysctl.conf file. For example:

    
    kernel.pty.max=10000
    

Dirty Page Cleanup

On large memory systems (for example, 8GB or larger), when doing numerous flat-file writes (for example, InterSystems IRIS backups or file copies), you can improve performance by adjusting the following parameters, which are located in proc/sys/vm/:

  • dirty_background_ratio — Maximum percentage of active that can be filled with dirty pages before pdflush begins to write them. InterSystems recommends setting this parameter to 5.

  • dirty_ratio — Maximum percentage of total memory that can be filled with dirty pages before processes are forced to write dirty buffers themselves during their time slice instead of being allowed to do more writes. InterSystems recommends setting this parameter to 10

You can set these variables by adding the following to your /etc/sysctl.conf file:

vm.dirty_background_ratio=5 
vm.dirty_ratio=10

These changes force the Linux pdflush daemon to write out dirty pages more often rather than queue large amounts of updates that can potentially flood the storage with a large burst of updates.”

Using Kerberos

To use Kerberos on the Red Hat Linux platform, you must install the krb5-devel package in addition to the krb5-libs package. Installing krb5-devel establishes the required symbolic links for using Kerberos. The package is required for production environments, not only development environments. See the Red Hat NetworkOpens in a new tab web site for more information about these components.

SUSE Linux Platform Notes

This topic includes the information on the following adjustments:

Shared Memory Limits

The default shared memory limits (shhmax and shmall) on SUSE Linux 32-bit platforms are too small for InterSystems IRIS, and can be changed in the proc file system without a restart.

InterSystems IRIS uses shared memory for database buffers, global buffers, routine buffers, as well as license use. If the machine is being used only for InterSystems IRIS, InterSystems recommends setting the shared memory to approximately half the total memory. For more information, see Memory Planning in System Resource Planning and Managment, as well as Memory and Startup Settings and Determining License Capacity and Usage in the System Administration Guide.

Note:

The recommendations to change the shared memory limits do not apply to SUSE Linux 64-bit systems.

For example, to allow 512 MB, type the following commands:


#sets shmall and shmmax shared memory
echo 536870912 >/proc/sys/kernel/shmall     #Sets shmall to 512 MB
echo 536870912 >/proc/sys/kernel/shmmax     #Sets shmmax to 512 MB

You can put these commands into a script that is run at startup. The SUSE Linux product documentation recommends you put the commands in the /etc/init.d/boot.local script file.

You can change the settings for the system memory user limits by modifying a file called /etc/profile.local. Add lines similar to the following:


#sets user limits (ulimit) for system memory resources
ulimit -v 512000     #set virtual (swap) memory to 512 MB 
ulimit -m 512000     #set physical memory to 512 MB

In this same file, you can permanently change the values for the PATH and CLASSPATH parameters by adding lines similar to the following:


#sets env values PATH and CLASSPATH
export PATH=$PATH:/usr/iris/bin:/path/to/j2sdk/bin:/.
export CLASSPATH=
      $CLASSPATH:/iris/dev/java/lib/JDK18/intersystems-jdbc-3.0.0.jar.

Important:

To avoid the risk of losing your changes during system upgrades, do not change the /etc/profile file.

Locked-in Memory

On Linux platforms, if shared memory is allocated in huge pages, they are automatically locked in memory and no further action is required. See the Huge Pages on Linux section in this chapter for information about allocating huge pages.

If not using huge pages, you can configure InterSystems IRIS to lock the shared memory segment in memory to prevent paging. This is described in the LockSharedMemory section of the “memlock” entry in the Configuration Parameter File Reference.

Otherwise, you must increase the maximum size that may be locked into memory. See the Locked-in Memory section of the Red Hat Linux Platform Notes in this chapter for instructions.

Using Kerberos

To use Kerberos on the SUSE Linux platform, you must install the krb5-devel package in addition to the krb5-libs package. Installing krb5-devel establishes the required symbolic links for using Kerberos. The package is required for production environments, not only development environments. See the SUSE documentationOpens in a new tab web site for more information about these components.

Ubuntu Platform Notes

This topic includes the information on the following adjustments:

Semaphore Deletion Setting

Under some circumstances, the OS may delete an instance’s semaphores when the instance owner connects to an Ubuntu host, for example using SSH. To prevent this, edit the /etc/systemd/logind.conf file and change RemoveIPC=yes (the default) to RemoveIPC=no.

Updating to a newer version of Ubuntu may revert RemoveIPC to the default value of yes. After updating Ubuntu, be sure to change RemoveIPC to avoid unwanted semaphore deletion.

FeedbackOpens in a new tab