InterSystems Caché Requirements

Before registering each InterSystems Caché server in ECX, ensure it meets the following requirements.

Supported Platforms/Configurations

InterSystems Caché Configuration Requirements

Database Versions/Types Server Types Operating Systems Storage Configuration Storage Systems
  • Caché 2015+ [1]
  • Caché 2016+ [1]
  • Caché 2017+ [1]
  • Caché 2018+ [1]
  • AIX 6.1 TL9+ [5]
  • AIX 7.1+ [5]
  • Fibre Channel
  • iSCSI
  • IBM Spectrum Virtualize Software 7.3 and later/8.1.2 and later:
    • IBM SAN Volume Controller [6]
    • IBM Storwize [6]
    • IBM FlashSystem V9000 and 9100 [6]
  • IBM Spectrum Accelerate 11.5.3 and later:
    • IBM FlashSystem A9000/A9000R [6]
    • IBM XIV storage systems [6]
  • Pure Storage running Pure APIs 1.5 and later:
    • FlashArray//c
    • FlashArray//m
    • FlashArray//x
    • FlashArray 4xx series


(VMware) [2, 4]

  • Red Hat Enterprise Linux 6.5+
  • Physical RDM backed by Fibre Channel or iSCSI disks attached to ESX [3]
  • VMDK (dependent as well as independent disks) on VMFS datastores backed by Fibre Channel or iSCSI disks attached to ESX
  • iSCSI disks directly attached to guest operating system [3]

[1] ECX was tested against Caché 2015.3, Caché 2017, and Caché 2018.

[2] See System Requirements for supported VMware vSphere versions.

[3] Select the Physical provider type when registering the provider in ECX. Note that NetApp ONTAP and DellEMC storage systems are not supported. All data files and log files for a given instance should reside on either a pRDM or virtual disk.

[4] InterSystems Caché servers registered as virtual must have VMware Tools installed and running.

[5] Supported platforms: IBM Power Systems (Little Endian).

[6] On IBM Systems Storage, condense is run during maintenance jobs.

InterSystems Caché Support for VMware Virtual Machines

For virtual machines, the Disk UUID option must be enabled. To enable, power off the guest machine through the vSphere client, then select the guest and click Edit Settings. Select VM Options, then Edit Configuration under the Advanced section. Add a new row that states the following:

Name: disk.enableUUID

Value: TRUE

pRDM and virtual disks are supported for VMware configurations. Note that data files and log files for a given instance should reside on either pRDMs or virtual disks. One instance cannot utilize both disk types.

Cluster Support

For cluster configurations, register the application server in ECX using the cluster IP address. ECX will utilize the cluster IP during application discovery and snapshot operations. In addition, the user configured in ECX with the cluster must be present on all cluster nodes and should preferably use the same UID and GID across all nodes.

Additionally, on each cluster node, create the file /etc/guestapps.conf with the following contents:


overrideHostname = <CLUSTER NAME>


  • The bash and sudo packages must be installed. Sudo must be version 1.7.6p2 or above. Run sudo -V to check the version.
  • Python version 2.6.x or 2.7.x must be installed.
  • AIX only: If data resides on IBM Spectrum Accelerate storage, the IBM Storage Host Attachment Kit (also known as IBM XIV Host Attachment Kit) must be installed on the server.
  • RHEL/OEL/CentOS 6.x only: Ensure the util-linux-ng package is up-to-date by running yum update util-linux-ng. Depending on your version or distribution, the package may be named util-linux.
  • RHEL/OEL/CentOS 7.3 and above: A required Perl module, Digest::MD5, is not installed by default. Install the module by running yum install perl-Digest-MD5.
  • Linux only: If data resides on LVM volumes, ensure the LVM version is or later. Run lvm version to check the version and run yum update lvm2 to update the package if necessary.
  • Linux only: If data resides on LVM volumes, the lvm2-lvmetad service must be disabled as it can interfere with ECX's ability to mount and resignature volume group snapshots/clones.
  • Run the following commands to stop and disable the service:
  • systemctl stop lvm2-lvmetad
  • systemctl disable lvm2-lvmetad
  • Additionally, disable lvmetad in the LVM config file. Edit the file /etc/lvm/lvm.conf and set:
  • use_lvmetad = 0


  • The SSH service must be running on port 22 on the server and any firewalls must be configured to allow ECX to connect to the server using SSH. The SFTP subsystem for SSH must also be enabled.
  • The server can be registered using a DNS name or IP address. DNS names must be resolvable by ECX.
  • In order to mount clones/copies of data, ECX automatically maps and unmaps LUNs to the servers. Each server must be preconfigured to connect to the relevant storage systems at that site.
    • For Fibre Channel, the appropriate zoning must be configured beforehand.
    • For iSCSI, the servers must be configured beforehand to discover and log in to the targets on the storage servers.


  • The application server must be registered in ECX using an operating system user that exists on the server (referred to as "ECX agent user" for the rest of this topic).
  • During registration you must provide either a password or a private SSH key that ECX will use to log in to the server.
  • For password-based authentication ensure the password is correctly configured and that the user can log in without facing any other prompts, such as prompts to reset the password.
  • For key-based authentication ensure the public SSH key is placed in the appropriate authorized_keys file for the ECX agent user.
    • Typically, the file is located at /home/<username>/.ssh/authorized_keys
    • Typically, the .ssh directory and all files under it must have their permissions set to 600.

OS-level authentication must be enabled on the InterSystems Caché server. From the InterSystems Caché interface, navigate to:

System Administration > Security > System Security > Authentication/CSP Session Options, then select Allow Operating System authentication.

Next, navigate to System Administration > Security > Services > %Service_Terminal, then enable Operating System if the option is not already enabled.

The user identity associated with ECX registration must have sufficient privileges to invoke some system commands, such as those used to find disk information, as well as to run InterSystems Caché’s "csession" command without asking for a database user name and password. To enable this feature, use the InterSystems Caché instance owner user after adding the user to "sudoers" file.

The ECX agent user must have the following privileges:

  • Privileges to run commands as root and other users using sudo. ECX requires this for various tasks such as discovering storage layouts and mounting and unmounting disks.
    • The sudoers configuration must allow the ECX agent user to run commands without a password.
    • The !requiretty setting must be set.

For examples on creating a new user with the necessary privileges, see Sample Configuration of an ECX Agent User.

Sample Configuration of an ECX Agent User

The commands below are examples for creating and configuring an operating system user that ECX will use to log in to the application server. The command syntax may vary depending on your operating system type and version.

  • Create the user that will be designated as the ECX agent user: useradd -m ecxagent
  • Set a password if using password-based authentication: passwd ecxagent
  • If using key-based authentication, place the public key in /home/ecxagent/.ssh/authorized_keys, or the appropriate file depending on your sshd configuration, and ensure the correct ownership and permissions are set, such as:
  • chown -R ecxagent:ecxagent /home/ecxagent/.ssh
  • chmod 700 /home/ecxagent/.ssh
  • chmod 600 /home/ecxagent/.ssh/authorized_keys
  • Place the following lines at the end of your sudoers configuration file, typically /etc/sudoers. If your existing sudoers file is configured to import configuration from another directory (for example, /etc/sudoers.d), you can also place the lines in a new file in that directory:
  • Defaults:ecxagent !requiretty
  • ecxagent ALL=(ALL) NOPASSWD:ALL

Backup Jobs

InterSystems Caché backup jobs occur at the instance level. Multiple instances can be added to a single Backup job definition, and all instances on a given host are automatically discovered.

Note that it is possible to scan in an InterSystems Caché backup failover member instance or an async member instance and run snapshots against the mirror copy instead of the primary failover member.

Virtual instances can be selected for backup (such as "cachecentos6/cache_2015.3"), but it is recommended to select Caché instances explicitly. If virtual instances are selected, the associated job definition must be adjusted when the Caché instances are upgraded to later versions.

Restore Jobs

When performing a database or filesystem restore from an XFS filesystem, the restore process may fail if the "xfsprogs" package version on the destination server is between 3.2.0 and 4.1.9. To resolve the issue, upgrade xfsprogs to version 4.2.0 or above.

Caché software is not required on the target host. However, the target host should have similar specifications to the source host, including operating system and processor.

Note that the following users and groups must be created on the target host: instance owner, effective user for InterSystems Caché superserver and its jobs, effective group for InterSystems Caché processes, and a group that has permissions to start and stop InterSystems Caché instances. The user and group IDs should match those on the source host. The instance will be brought up using the same mount points as those found on the source machine, so ensure these mounts are not in use on the target.

When restoring to a target with running InterSystems Caché instances, the instances display as valid targets. Note that ECX will not interact with these instances, but instead bring up a new instance using mapped mount points. When restoring to a target with no prior InterSystems Caché instances, ECX creates a placeholder that acts as a restore target named cache_general. Note that cache_general should only be used as a restore target and should not be selected for backup.

Single InterSystems Caché databases can be restored through an Instant Disk Restore job, which mounts physical volumes on the target machine. Granular recovery can then be performed through InterSystems Caché commands.

Performing a Caché Instant Database (DB) Restore

Though not fully accessible through the ECX interface, you may need to perform a Caché instant database (DB) restore. This process requires access to the cache server system and use of the command-line interface (CLI).

Caché instant DB restore requires an instance directory /cache with /mgr and /bin as subdirectories. The /bin subdirectory must contain the ccontrol and cstart files. Finally, the instance directory must be copied from /mnt/root to /.

Follow the steps below to perform an instant database restore:

  • Open a terminal on the cache server or use secure shell (SSH) to connect to the cache server. Default credentials for the cache server are root for the username and <root password> for the password.
  • Create the instance directory /cache and create the two subdirectories /bin and /mgr within the instance directory.
  • $ mkdir /cache

    $ cd cache

    $ mkdir bin

    $ mkdir mgr

  • Copy ccontrol and cstart from any available different instance to the newly created /cache/bin location.
  • $ cp ccontrol /cache/bin

    $ cp cstart /cache/bin

  • Run the Caché instant restore job in ECX. Running the instant restore job will create the additional directories /boot and /root under the /mnt directory. Additionally, a /cache subdirectory will be created in the /mnt/root directory.
  • Move the /cache directory created in the second step to another location and copy /cache from /mnt/root to the / location.
  • $ mv /cache /<some other location>

    $ cp -r /mnt/root/cache /

  • Bring up the restored Caché instance by issuing the following command:
  • $ cd /cache/bin

    $ ccontrol start cache



Catalogic ECX™ 2.12

© 2021 Catalogic Software, Inc. | All rights reserved. | 4/9/2021

MySupportKnowledge Base | Trademarks |