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 IRIS.
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 generic memory heap (also known as the shared memory heap), which determines the memory available to InterSystems IRIS for purposes other than the routine and database caches; see Configuring Generic 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 generic memory heap, see Memory Management and Scaling for InterSystems IRIS in the “Vertical Scaling” chapter of the Scalability Guide.
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.
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
When InterSystems IRIS is first installed, memory for the routine and database caches is set to the Initial, automatic allocation. With this default, InterSystems IRIS allocates 25% of total 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 and routine caches by selecting Specify Amount and using the following procedures. To allocate memory for the routine and database caches:
On the Management Portal, navigate to the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup).
Select Specify Amount.
For more information about specifying the database and routine caches, see the globals and routines parameters in the Configuration Parameter File Reference. See Calculating Memory Requirements and Allocation in the Scalability Guide for additional guidelines for allocating memory on an InterSystems IRIS instance.
Allocating Memory to the Database Cache
Memory Allocated for [blocksize] Database Cache (MB) — The database cache specifies the system memory allocated for buffering data; this is also called creating global buffers. The database cache and the memory allocated to it are sometimes referred to as the global buffer pool.
Enter a separate allocation for each enabled database block size. The Memory and Startup page displays the range of allocations for each block size; as 8K blocks are required, the absolute minimum is 32MB. To enable more database block sizes (16K, 32K, 64K), use the DBSizesAllowed setting on the Startup Settings page (System Administration > Additional Settings > Startup).
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 databases with a particular block size, divide the allocation for a block size by the block size; the smaller the block size, the larger the number of global buffers that will be created for databases with that block size. For guidelines for selecting the appropriate block sizes for your applications, see Large Block Size Considerations.
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.
You can also allocate memory to the database cache using the globals parameter in the iris.cpf file; for more information, see globals in the Configuration Parameter File Reference.
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 Generic Memory Heap (gmheap)
The generic memory heap (also known as 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 Generic (Shared) Memory Heap Usage in the “Monitoring InterSystems IRIS Using the Management Portal” chapter of the Monitoring Guide.
For guidelines for sizing the generic memory heap, see Calculating Memory Requirements and Allocation in the Scalability Guide.
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, 18.104.22.168) 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 IPv6Format method of the %SYSTEM.Process class (for the current process) or the IPv6 method of the Config.Startup 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.