Configuring System Information
InterSystems IRIS stores system-wide configuration information in a file called the configuration parameter file (CPF). This file is an important tool, as it contains most of the configurable settings for an InterSystems IRIS instance. A default CPF is deployed with every instance and is located in the installation directory. You can modify the CPF directly in a text editor, or indirectly from the Management Portal or the Terminal. On UNIX® and Linux, you can also customize the CPF during deployment by specifying a configuration merge file, which InterSystems IRIS uses to update the default CPF before the instance starts for the first time. For more information about the CPF and its parameters, see the “Introduction to the Configuration Parameter File” chapter in Configuration Parameter File Reference; for information about the configuration merge feature, see Using Configuration Merge to Deploy and Reconfigure InterSystems IRISOpens in a new tab.
There are several startup settings that you must change for any newly installed instance, and others you should review. This section discusses these settings to consider initially:
Memory and Startup Settings
When you first install InterSystems IRIS, you should review and adjust the memory allocations, among other configuration settings. There are three primary actions you must take in determining the way an InterSystems IRIS instance uses memory, as follows:
Allocate memory to the database and routine caches, using the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup); see Allocating Memory to the Database and Routine Caches.
Set the maximum memory an InterSystems IRIS process can use; see Setting the Maximum Per-Process Memory.
Configure the size of the shared memory heap, which determines the memory available to InterSystems IRIS for purposes other than the routine and database caches; see Configuring Shared Memory Heap (gmheap).
When InterSystems IRIS is first installed, database and routine cache memory allocation is set to Automatically, under which InterSystems IRIS allocates 25% of total physical memory for the database cache (global buffers).
This setting is not appropriate for production use. For guidelines for allocating memory to an InterSystems IRIS instance’s routine and database caches and the shared memory heap, see Configuring InterSystems IRIS Shared Memory.
Other than the memory settings, the Memory and Startup page includes the following:
Auto-start on System Boot — On Windows systems, an InterSystems IRIS instance is configured by default to start automatically when the host system starts. You can change this behavior, so that the instance does not start automatically on system startup, by clearing this check box.
On UNIX ® systems, InterSystems IRIS does not provide this option and does not restart when the host system restarts. If you want InterSystems IRIS to restart when the host system restarts, use OS-level scripting as appropriate for your environment.Note:
You may occasionally need to prevent IRIS from starting with the host system while the host system is down (for example during restores). This can only be done at the OS level and is dependent on your configuration.
Superserver Port Number — The superserver port is the TCP port used by an InterSystems IRIS instance to accept incoming client requests. When you change this setting (which should be done with caution, as many clients may be configured to connect to the instance using this port), the change will not take effect until you restart the instance.
System Mode — You can enter a label to be displayed in the Management Portal header, or select one from the drop-down list.
Click Save to save your modifications to these settings.
Some changes on this page require an InterSystems IRIS restart and some do not. If you modify a setting that requires a restart and save your changes, none of the changes take effect until you restart InterSystems IRIS, even those that by themselves do not require a restart. If a restart is required, the message Modification saved. You must restart system for the new values to take effect. displays. After you close the page, the warning message does not appear again to remind you that a restart is required, and it is therefore best to restart the instance immediately.
Allocating Memory to the Database and Routine Caches
The database cache is system memory allocated for buffering data, and is sometimes referred to as the global buffer pool. The routines cache is system memory allocated for buffering routines.
When InterSystems IRIS is first installed, configuration of the database cache is set to the Initial, under which InterSystems IRIS allocates 25% of total system physical memory for the database cache (global buffers). This setting is not appropriate for production use. Before deploying the system for production use or before performing any tests or benchmarking intended to simulate production use, you must manually create an appropriate memory allocation for the database cache using the procedure described here.
By default, the configuration of the routine cache is set to Automatic, under which InterSystems IRIS allocates to the routine cache an amount of memory equal to 10% of the database cache for the default 8-kilobyte buffer size, with a minimum of 80 MB and a maximum of 1020 MB. For typical production instances, if the database cache size is appropriately configured, automatic allocation of the routines cache is sufficient; however, the ideal allocation for a given application depends on may factors, and adjustment may be necessary to optimize performance.
For guidelines for allocating memory on an InterSystems IRIS instance, including to the database and routine caches, see Estimating Memory RequirementsOpens in a new tab.
To allocate memory to the database and routine caches:
On the Management Portal, navigate to the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup).
For Configure Database Cache (Global Buffers), select Specify Amount and enter the database cache memory allocation, in megabytes.
If you have enabled database block sizes other than the default 8-kilobyte size using the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup), enter an allocation for each enabled block size; the range for each size is displayed on the page. Both block size and the maximum number of buffers available have implications for performance; to determine how many global buffers InterSystems IRIS will create for a particular block size, divide the allocation for a block size by the block size. For guidelines for selecting the appropriate block sizes for your applications, see Large Block Size Considerations.Important:
If you are configuring a large ECP system, allocate at least 50 MB of 8 KB buffers for ECP control structures in addition to the 8 KB buffers required to serve your 8 KB blocks over ECP. See Increase Data Server Database Caches for ECP Control Structures in the “Horizontally Scaling Systems for User Volume with InterSystems Distributed Caching” chapter of the Scalability Guide for details.
For Configure Routine Cache, you can accept the default Automatic setting to allocate an amount of memory equal to 10% of the database cache for the default 8-kilobyte buffer size, or select Specify Amount and enter the routine cache memory allocation, in megabytes.
Setting the Maximum Per-Process Memory
The Maximum Per-Process Memory (KB) setting on the Memory and Startup page specifies the maximum memory that can be allocated to a new process running on this InterSystems IRIS instance. The allowed range is 256 KB to 2147483647 KB; the default is the initial value of the bbsiz parameter. InterSystems recommends setting this equal to -1 (which resolves to the maximum value) for most circumstances.
It is not necessary to reset this value unless you have set it lower than its default. If you receive <STORE> errors, increase the size and restart the process that created the error.
Process private memory, which is used for symbol table allocation and various other memory requirements (for example I/O device access structures and buffers), is allocated in increasing extents as required by the application until the specified maximum is reached. Once private memory is allocated to a process, it is not deallocated until the process exits.
See bbsiz for more information about this setting, including how to change it programmatically. For a detailed discussion of process memory in InterSystems IRIS, see Process Memory in InterSystems Products.
Configuring Shared Memory Heap (gmheap)
The shared memory heap is the memory used by InterSystems IRIS for purposes other than the routine and database caches. This setting is not on the Memory and Startup page. You can configure gmheap on the Advanced Memory page (System Administration > Configuration > Additional Settings > Advanced Memory) or programmatically; for more information, see gmheap in Configuration Parameter File Reference.
To see details of used and available memory for gmheap, navigate to the Shared Memory Heap Usage page (System Operation > System Usage) and click the Shared Memory Heap Usage link; for more information, see Shared Memory Heap Usage in the “Monitoring InterSystems IRIS Using the Management Portal” chapter of the Monitoring Guide.
If your application will utilize a large number of SQL queries or if you plan on enabling parallel dejournaling, you will need to allocate additional memory to gmheap. For more information, see Shared Memory Considerations in Parallel Query Processing and System Requirements for Parallel Dejournaling.
You can enable or disable the use of IPv6 addresses in InterSystems IRIS by navigating to the Startup Settings page (System Administration > Configuration > Additional Settings > Startup) page; in the IPv6 row, click Edit. Select IPv6 to enable this option.
This option is visible only if the network to which this InterSystems IRIS instance is connected permits IPv6 addressing.
When IPv6 is enabled, InterSystems IRIS accepts IPv6 addresses, IPv4 addresses, or DNS forms of addressing (host names, with or without domain qualifiers); when IPv6 is disabled, InterSystems IRIS accepts only IPv4 addresses or DNS forms of addressing.
When dotted-decimal IPv4 addresses (for example, 188.8.131.52) are specified, an IPv4 connection is attempted; when colon-separated IPv6 addresses (for example, 2001:fecd:ba23:cd1f:dcb1:1010:9234:4085) are specified, an IPv6 connection is attempted. When a DNS name (for example, mycomputer.myorg.com) is specified, it resolves to an actual IP address: first, it attempts to make an IPv4 connection; then, if an IPv4 connection cannot be made, it attempts an IPv6 connection.
InterSystems IRIS allows Internet addresses to be supplied in DNS, IPv4 and IPv6 formats. For example, “localhost”, 127.0.0.1, and ::1 are representations of the loopback address in each format, respectively. Detailed information about IPv6 addressing can be found in the following Internet Engineering Task Force documents:
IPv6 addressing can also be checked and controlled using the IPv6FormatOpens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class (for the current process) or the IPv6Opens in a new tab method of the Config.StartupOpens in a new tab class (for the system generally).
Even though an InterSystems IRIS instance may be using an IPv4 network, IPv6 addresses can still be used as input to the various services provided that the IPv6 address supplied has a valid IPv4 equivalent. The loopback address used earlier in this section is such an example; RFC 4291 describes several more formats. Thus, the various InterSystems services will accept either IPv4 or IPv6 addresses without error as long as the address form given can be validly converted for use on the connected network. So all of these forms (and several more) are acceptable
::FFFF:127.0.0.1 (IPv4 mapped IPv6 format)
0:0:0:0:0:0:0:1 (full IPV6)
::1 (compressed IPv6)
as valid representations of the loopback address.
Generally, when asked for an Internet address that has been supplied to an InterSystems service earlier, InterSystems IRIS does not alter the address format. Addresses supplied in IPv4, or IPv6 format are returned as IPv4 or IPv6, respectively. The only exception is that addresses supplied as host names and translated by the Domain Name Server (DNS) may be returned in whatever form the DNS returns.
InterSystems IRIS does not support the use of wildcard characters or ranges in IPv6 addresses.