Managing InterSystems IRIS on UNIX®, Linux, and macOS
This page describes specific administrative procedures on UNIX®, Linux, and macOS.
UNIX® Users, Groups and Permissions
Every InterSystems IRIS® data platform installation on a UNIX® platform has the following users and groups:
-
Root — InterSystems IRIS must be installed by root, and some processing by InterSystems IRIS system daemons runs as root.
-
Owner of instance — This user owns most installation files and has full control of the instance. If you install with Minimal initial security settings, root is the default owner; otherwise, you are prompted for the owner during installation.
-
Effective user for InterSystems IRIS superserver and its jobs — All InterSystems IRIS processes spawned by the superserver to serve incoming requests run as this user; in addition jobs hosted by job server processes, task manager jobs, and user-defined startup routines (for example, ^%ZSTART) also run as this user. By default, this user is irisusr, but you can change the user during a custom installation.
-
Effective group for InterSystems IRIS processes — All InterSystems IRIS processes automatically run as this group, which allows normal users, while inside InterSystems IRIS, to access InterSystems IRIS database and journal files to which they may not otherwise have been granted access; file permissions on these and other InterSystems IRIS files are set to allow this group to have appropriate access. On a secure system, only the Effective user for InterSystems IRIS superserver and its jobs should be a member of this group. By default, this group contains irisusr, but you can change the group during a custom installation.
-
Group allowed to start and stop instance — This group, root, and the Owner of instance can start and stop InterSystems IRIS.
All journals and journal directories must have the group ownership set to the Effective group for InterSystems IRIS processes group and grant full permissions to that group (rw for journals, rwx for journal directories). The user who owns the journal and journal directories may vary depending on how they were created.
Journals and journal directories created within InterSystems IRIS are created with the appropriate permissions. However, if you move, copy or create journal directories or journals externally (via scripts or administrator action), you must ensure that the proper permissions are maintained. Failure to set the permissions properly may lead to unexpected and serious errors.
The following example assumes the Effective group for InterSystems IRIS processes is irisusr and the Owner of instance is irisowner, although the files may have different user ownership depending on the context in which they were created. For example:
journal directory irisowner irisusr drwxrwxr-x
20170801.001 irisowner irisusr -rw-rw----
These settings are maintained, in part, as the set of permissions on the executables within the install-dir/bin directory of the InterSystems IRIS installation. Relevant properties include: ownership, group, mode, set-uid, and set-gid bits. It is important that you do not modify these permissions when performing administrative tasks at the operating-system level.
You can use the InterSystems IRIS filecheck utility to check whether permissions, owners, and groups for UNIX installations conform to required settings.
Database and Database Directory Permissions
All databases and database directories must have the group ownership set to the Effective group for InterSystems IRIS processes group and grant full permissions to that group (rw for databases, rwx for database directories). The user who owns the databases and database directories may vary depending on how they were created.
Databases and database directories created within InterSystems IRIS are created with the appropriate permissions. However, if you move, copy or create database directories or databases externally (via scripts or administrator action), you must ensure that the proper permissions are maintained. Failure to set the permissions properly may lead to unexpected and serious errors.
The following example assumes the Effective group for InterSystems IRIS processes is irisusr and the Owner of instance is irisowner, although the files may have different user ownership depending on the context in which they were created:
dataset directory irisowner irisusr drwxrwxr-x
IRIS.DAT irisowner irisusr -rw-rw----
Startup on UNIX®
The InterSystems IRIS instance uses the following resources to control starting, stopping, and creating new processes:
-
The iris.ids file in the install-dir\mgr directory.
-
Shared memory.
Daemon Resource Locks
InterSystems IRIS uses advisory file locking to prevent multiple startups of the same instance on different machines. With advisory file locking, a single lock file (in this case, the file ilock in the install-dir/mgr directory) may be used to exclusively lock multiple resources. The Control Process, Write daemon, and Journal daemon each lock a separate section of the lock file. If this section of the ilock file is already locked, startup terminates. The locks held by the different daemons are called Daemon Resource Locks.
A file lock is held by a process until the process terminates. Thus if any lock is held, it indicates that some daemon process on some node is running. It does not indicate, however, whether or not the instance is healthy and running normally.
iris.ids File
The iris.ids file contains the name of the node where InterSystems IRIS was started. The existence of the iris.ids file acts as a flag to ObjectScript utilities and customer-written scripts, indicating whether or not the instance is up and running. This file is often ignored during startup. However, if an error occurs when iris.ids is being read, it will prevent InterSystems IRIS from starting up. In previous versions of InterSystems IRIS, the shared memory identifiers were also stored in the iris.ids file, but this is no longer the case.
Startup Sequence
To best understand the startup sequence, imagine that the instance can be run from two (2) different nodes (machines), node A and node B. The iris.ids file is visible to both nodes, as are the Daemon Resource Locks (for shared files). The shared memory itself, however, is visible only on the node on which it was created (that is, the node where you started InterSystems IRIS).
Step 1. Check the Status of the Instance
The startup routine runs irisdb –cV to find out the status of the instance. It first attempts to attach to shared memory for the instance:
-
If there is no shared memory for the instance, a test is made for Daemon Resource Locks:
-
If no Daemon Resource Locks are held, the instance is reported down.
-
If Daemon Resource Locks are held, the instance is reported to be running on the node specified in the iris.ids file. If the iris.ids file does not exist, no information is available on where the daemons are running.
Action: The user must run iris stop or iris force to halt the running instance on the appropriate node. This stops the daemons and deletes the iris.ids file.
-
-
If the attach succeeded, the system is assumed to be up and running. This status is reported to the user. Startup halts.
-
If an error displays indicating that startup cannot be completed because shared memory is still attached, wait a few minutes for the memory to be released. If the error persists, there may be an error related to the iris.shid file, which tracks the shared memory ID of InterSystems IRIS on all UNIX® platforms except macOS. Contact the InterSystems Worldwide Response CenterOpens in a new tab (WRC) for support correcting the file.
-
If startup was initiated using the optional filecheck parameter, the InterSystems IRIS filecheck utility checks to ensure that permissions, owners, and groups associated with InterSystems IRIS system files match the system requirements.
Step 2. Start InterSystems IRIS
The InterSystems IRIS startup process is run. Checks are repeated to ensure that another startup is not competing for the startup resources:
-
If Daemon Resource Locks are held, indicating one or more daemons are running on some node for this instance, InterSystems IRIS reports this and exits with an error. Startup halts.
The node on which the daemons are running is unknown if the iris.ids file does not exist.
Action: The user must assume that another startup has occurred on some node. To determine on which node the instance has started, examine the iris.ids file.
InterSystems IRIS continues startup.
Managing InterSystems IRIS
From the shell, a user with any user ID in the sysmgr group can run iris (see Controlling InterSystems IRIS Instances) which invokes InterSystems IRIS executables and scripts in the install-dir/bin directory. The following sections describe how to perform these management tasks on an InterSystems IRIS instance:
The owner of the installation has full privileges to start and stop the instance, to perform system administration, and to run diagnostic programs for that instance.
Only the user ID that is the owner of the instance can and should run all diagnostic activities. This ensures that any files or resources created are owned by the owner of the instance and not root (which may make it impossible to access these resources by a nonroot user). For this reason, it is inadvisable for root to in any way administer an instance not owned by root (including starting and stopping the instance). A user running as root should only administer instances owned by root.
Starting InterSystems IRIS
To start InterSystems IRIS, run the startup procedure at the system level. This procedure activates either a default configuration file or a configuration file you specify.
If you have any trouble starting InterSystems IRIS, view the messages.log file as described in Monitoring Log Files.
If you are not on the console machine, run Telnet and connect to the target machine where InterSystems IRIS is installed. Before you can start InterSystems IRIS on UNIX®, one of the following must be true:
-
You are the superuser.
-
You have signed on as the root user. (It is acceptable to su (superuser) to root while logged in from another account.)
-
Your UNIX® group ID matches the group named during the InterSystems IRIS installation as having privileges to stop and start the system.
See Installing InterSystems IRIS on UNIX® and Linux for information on specifying such privileges during installation.
Start InterSystems IRIS using the iris command:
iris start <instname>
where instname is the name of the InterSystems IRIS instance you want to start. See Controlling InterSystems IRIS Instances for more options and information.
From the shell, a user with any user ID in the sysmgr group can run iris start. This command verifies that the instance is not currently running on the current or another node, creates shared memory and basic InterSystems IRIS daemons, including multiple auxiliary write daemons (AWDs), runs the startup (^STU) routine, which creates additional daemons (for example, ECP daemon), and then allows user logins.
Running InterSystems IRIS
From the shell, a user with any user ID and any group ID (anyuser:anygroup in this example), can run iris terminal (see Connecting to an InterSystems IRIS Instance) which executes irisuxsession in the install-dir/bin directory.
Running as anyuser:irisusr, InterSystems IRIS runs its standard startup logic, including Kerberos negotiation, to identify a $USERNAME and a set of login roles. In many cases, this $USERNAME value is associated with the actual user who invoked iris terminal. Thus, while any user may run InterSystems IRIS, the activities of that user once in InterSystems IRIS are defined and limited by the security roles assigned to that user.
Do not enter InterSystems IRIS by invoking its executable directly from the install-dir/bin directory.
The InterSystems IRIS executable is not itself a setgid-executable. It is the responsibility of the iris terminal wrapper to set the group properly on behalf of the user entering InterSystems IRIS.
In addition to iris terminal, you may run InterSystems IRIS using the irisdb executable in the /usr/bin directory. This command calls iris terminal <default-instance>, setting permissions and opening the Terminal for the default InterSystems IRIS instance. To create the irisdb executable, designate a default instance by running the iris default <instname> function.
On macOS 10.11 and later, iris and iris terminal are located in /usr/local/bin, with links from /usr/bin.
Stopping InterSystems IRIS
Normally you leave your InterSystems IRIS system running. However, if your operating system requires a restart, you should stop InterSystems IRIS before you shut down your system. The InterSystems IRIS maintenance tasks, such as backups and database repair utilities, do not require you to stop InterSystems IRIS.
To stop InterSystems IRIS on UNIX®, the same requirements exist as for starting InterSystems IRIS. One of the following must be true:
-
You are the superuser.
-
You have signed on as the root user. (It is acceptable to su (superuser) to root while logged in from another account.)
-
Your UNIX® group ID matches the group named during the InterSystems IRIS installation as having privileges to stop and start the system.
To stop InterSystems IRIS, from the command line:
-
Use the iris stop command:
iris stop <instname>
where instname is the name of the InterSystems IRIS instance you want to stop. (See Controlling InterSystems IRIS Instances for more iris options and information.)
Caution:You can stop InterSystems IRIS with the iris force command, but you should do so with caution because it may result in a loss of data.
-
This procedure invokes the InterSystems IRIS SHUTDOWN utility, which displays a status report. Check for active processes in the report to determine if the next step is necessary.
-
Should it be necessary, broadcast a message to any users on the system:
Do you want to broadcast a message to anyone? No=> Yes Send a message to other terminals. Message => Please sign off Terminal => /dev/tty/06 Terminal => Message =>
-
After sending one message you can send others, until you respond to the Message prompt by pressing Enter.
-
When the system asks if you would like to see another system status, enter Yes to see one, or press Enter if you do not want another report.
-
If you answer Yes, when the system status displays again, identify any active terminals.
-
Confirm that you want to halt by answering Yes. If you answer No, the shutdown procedure quits and InterSystems IRIS continues running.
On UNIX® platforms, when an InterSystems IRIS instance is stopped, restarted, or forced down, the instance will wait for all processes to detach from shared memory for a maximum of 30 seconds. After 30 seconds, the instance will close. If there are still processes attached to the shared memory after the instance has closed, restarting the instance will fail.