Configuring the ISCAgent

The ISCAgent runs securely on a dedicated, configurable port (2188 by default) on each mirror member. When the agent receives an incoming network connection which directs it to a mirrored instance, it executes cuxagent in that instance to escalate to the privileges necessary to administer the mirror member. If the mirror is configured to require SSL/TLS, the incoming connection is authenticated before any actions are performed.

This section provides information on managing the ISCAgent in the following ways:

• Starting and Stopping the ISCAgent

• Customizing the ISCAgent Port Number

• Customizing the ISCAgent Interface

3.2.12.1 Starting and Stopping the ISCAgent

The ISCAgent, which is installed when you install or upgrade Caché, runs as user ^iscagent and as a member of the ^iscagent group by default. To acquire the group privilege, which is necessary to execute the cuxagent utility that provides it with access to a Caché instance (as described ISCAgent), the ISCAgent must be started automatically during system startup or by a user with root privileges. Once it has assigned itself its user and group privileges, the ISCAgent discards all root privileges.

The ISCAgent must be configured to start automatically when the system starts on each failover and DR async mirror member. InterSystems provides platform-specific control scripts that can be added to the initialization process by a system administrator, as described in the following sections. (Consult your operating system documentation for detailed system startup configuration procedures.)

• Starting the ISCAgent on UNIX®/Linux and Mac OS X Systems

• Starting the ISCAgent on Microsoft Windows Systems

• Starting the ISCAgent on HP OpenVMS Systems

Starting the ISCAgent on UNIX®/Linux and Mac OS X Systems

On UNIX®/Linux and Mac OS X platforms, run the ISCAgent start/stop script, which is installed in the following locations, depending on the operating system:

For example, to start ISCAgent on the IBM AIX® platform, run the following command as root: /etc/rc.d/init.d/ISCAgent start; to stop it, run the command /etc/rc.d/init.d/ISCAgent stop.

Important: To enable monitoring by local Caché instances, the ISCAgent creates a status file in /var/run on the UNIX®, Linux or Mac OS X system on which it is installed. For this reason, ^/var/run must be readable by all users.

If Caché cannot read this directory, it reports that the ISCAgent is not running, and mirror configuration is therefore not possible.

Additional ISCAgent considerations on UNIX®/Linux platforms include the following:

• As noted, the ISCAgent must be started automatically at system startup on each failover and DR async mirror member.

There may also be times at which it is useful to have a user start, stop, or restart the agent. This can be done in the following ways:

– Directly, by the root user.

– Using the agentctrl executable in the Caché instance’s /bin directory, by any user who is able to start and stop the Caché instance. For example, to start the agent, execute the following command:

/cache/bin$ ./agentctrl start

The command also takes the arguments stop and restart.

• As noted, the ISCAgent obtains the privileges it needs to administer Caché instances using cuxagent. By default, the agent has the privileges required (iscagent user/iscagent group) to execute cuxagent, and under typical configurations, no change is necessary.

Depending on your system’s security configuration, however, instances at your site may require additional privileges to navigate to the /bin directory of the mirrored instance in order execute cuxagent. If so, you must ensure that the ISCAgent’s privileges are sufficient the command. To do so, you can modify the agent’s privileges using the following procedure:

1. Create the file /etc/iscagent/iscagent.conf, or edit it if it already exists (for example, because you previously created it to customize the ISCAgent port number or interface).

2. To add group privileges, add the following line, specifying one or more groups that are required to execute cuxagent:

privileges.group=iscagent,<groupname>[,<groupname>[,...]]

Typically, adding group privileges is sufficient. Under some configurations, however, you may need to run the ISCAgent as a different user. This can also be done in /etc/iscagent/iscagent.conf, as follows:

privileges.user= <username>

Note: Because cuxagent requires ^iscagent group privileges, ^iscagent must remain in the groups list.

• Mirroring requires that the env executable script is installed in the /usr/bin directory, and that the bash shell is loaded and is in the startup environment path. One easy way to accomplish the latter is to create a symbolic link such as ln -s

<bash_dir> /usr/bin/bash, where <bash_dir> is the directory in which bash is installed (such as /usr/local/bin/bash);

because /usr/bin is in every user’s path, such a link allows all processes to automatically find bash.

• The ISCAgent uses the general-purpose logging facility, syslog, to log messages; informational messages are logged as priority ^LOG_INFO, while error messages are logged as priority ^LOG_ERR. For information about configuring the syslog facility, see the documentation for your platform.

Starting the ISCAgent on Microsoft WindowsSystems

2. On the ^Extended tab, click ^Start to start, or ^Stop to stop ISCAgent.

3. On the Extended tab, select Automatic from the Startup type drop-down list.

Starting the ISCAgent on HP OpenVMS Systems

On OpenVMS systems, the RunAgent and StopAgent scripts are located in the instance [.BIN] subdirectory. To start the ISCAgent process, run the @RUNAGENT command from the ^[.BIN] subdirectory.

3.2.12.2 Customizing the ISCAgent Port Number

As described in the ISCAgent section of this chapter, the default ISCAgent port is 2188. While this is typically all that is needed, you can change the port number if required, as described in the following subsections:

• Customizing the ISCAgent Port Number on UNIX®/Linux Systems

• Customizing the ISCAgent Port Number on Microsoft Windows Systems

• Customizing the ISCAgent Port Number on HP OpenVMS Systems Customizing the ISCAgent Port Number on UNIX®/Linux Systems

The ISCAgent process, by default, starts on port 2188. To customize the port on a UNIX®/Linux system, do the following:

1. Create the file /etc/iscagent/iscagent.conf, or edit it if it already exists.

2. Add the following line, replacing <port> with the desired port number:

application_server.port=<port>

Customizing the ISCAgent Port Number on Microsoft Windows Systems

The ISCAgent process, by default, starts on port 2188. To customize the port on a Windows system, do the following:

1. Create the file <windir>\system32\iscagent.conf, or edit it if it already exists.

2. Add the following line, replacing <port> with the desired port number:

application_server.port=<port>

Customizing the ISCAgent Port Number on HP OpenVMS Systems

The ISCAgent process, by default, starts on port 2188. To customize the port on an HP OpenVMS system, do the following:

1. Create the file iscagent.conf in the instance ^[.BIN] subdirectory, or edit it if it already exists.

2. Add the following line, replacing <port> with the desired port number:

application_server.port=<port>

3.2.12.3 Customizing the ISCAgent Interface

The ISCAgent binds to the default (or configured) port on all available interfaces. While this is typically all that is needed, you can change the ISCAgent to bind to the interface serving a specific address if required. The procedure is described in the following subsections:

• Customizing the ISCAgent Interface on UNIX®/Linux Systems

• Customizing the ISCAgent Interfacer on Microsoft Windows Systems

• Customizing the ISCAgent Port Number on HP OpenVMS Systems

Customizing the ISCAgent Interface on UNIX®/Linux Systems

The ISCAgent process binds to the default (or configured) port on all available interfaces. To customize the ISCAgent to bind to the interface serving a specific address on a UNIX®/Linux system, do the following:

1. Create the file /etc/iscagent/iscagent.conf, or edit it if it already exists.

2. Add the following line, replacing <ip_address> with the address served by the desired interface:

application_server.interface_address=<ip_address>

To explicitly bind to all available interfaces (i.e., the default), specify * as follows:

application_server.interface_address=*.

Customizing the ISCAgent Interface on Microsoft Windows Systems

The ISCAgent process binds to the default (or configured) port on all available interfaces. To customize the ISCAgent to bind to the interface serving a specific address on a Windows system, do the following:

1. Create the file named <windir>\system32\iscagent.conf, or edit it if it already exists

2. Add the following line, replacing <ip_address> with the address served by the desired interface:

application_server.interface_address=<ip_address>

To explicitly bind to all available interfaces (i.e., the default), specify * as follows:

application_server.interface_address=*. Customizing the ISCAgent Interface on HP OpenVMS Systems

The ISCAgent process binds to the default (or configured) port on all available interfaces. To customize the ISCAgent to bind to the interface serving a specific address on an HP OpenVMS system, do the following:

1. Create the file named iscagent.conf in the instance [.BIN] subdirectory, or edit it if it already exists.

2. Add the following line, replacing <ip_address> with the address served by the desired interface:

application_server.interface_address=<ip_address>

To explicitly bind to all available interfaces (i.e., the default), specify * as follows:

application_server.interface_address=*.