Preparing to Install InterSystems IRIS

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.

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.

File System Mount Option

Different mount options may improve performance for some workloads.

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.

See the following IBM web pages for more detailed information:

• For a complete description of each of the fields reported by vmstat, see vmstat CommandOpens in a new tab in the IBM AIX documentation.

• For instructions on how to increase these parameters, see VMM page replacement tuningOpens in a new tab in the IBM AIX documentation.

• For a complete description of managing I/O tunable parameters, see ioo CommandOpens in a new tab in the IBM AIX documentation.

AIX® Tunable Parameters

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.

Shared Library Environment Variable for InterSystems IRIS Shared Library Support

The InterSystems IRIS shared library support contain a batch file that references any installed C linker.

If you have either the standard UNIX® C libraries or any proprietary C libraries defined in the LIBPATH environment variable, then your environment is ready.

If not, append the paths for the standard UNIX® C libraries to LIBPATH; these paths are /usr/lib and /lib.

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.

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.

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.

I/O Scheduler

The I/O scheduler for SUSE Linux is responsible for ordering the I/O requests submitted to a storage device. On SUSE Linux 15, it may default to BFQ (Budget Fair Queueing) which is known to cause performance issues with InterSystems IRIS. InterSystems recommends changing this setting to NONE. For details on changing the I/O scheduler, see the SUSE documentation: Tuning I/O PerformanceOpens in a new tab.

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.

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.

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 Configuring Huge Pages on Linux 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.

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.