Caché Installation Guide
Installing Caché on UNIX® and Linux
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to install Caché on a UNIX® or Linux system. It assumes that you are familiar with UNIX® and Linux directory structures, utilities, and commands. This chapter contains the following major sections:

You can consult the appendix on Calculating System Parameters for UNIX® and Linux to verify and adjust your parameter settings before you begin the installation.
Installation Requirements
The following sections describe the hardware and software requirements for new and upgrade installations of Caché:
Disk Space Requirements
A standard Caché installation that includes support for Caché Server Pages (CSP) needs 1600 – 1950 MB (megabytes) of disk space depending on the type of installation you choose.
In addition, 200 MB of space is required in the Caché installation directory. The installation procedure confirms that this disk space is available in the specified location before installing.
Supported Platforms and Features
The latest version of Caché is supported on the following operating systems. Be sure to review the systems requirements and other special considerations for your platform.
Important:
For up-to-date information about platforms, versions, and features supported for each operating system, see InterSystems Supported Platforms.
Caché installs a private Apache Web server with each instance to ensure proper operation of the Management Portal and Caché Online Documentation. If you are using a web server for CSP other than the private one installed with Caché, you must install it before installing Caché if you want to configure it automatically. Its support on each operating system is dependent on the operating system vendor and is subject to change. See the Web Server Configuration section of the “CSP Architecture” chapter of the Using Caché Server Pages guide for more information.
Note:
The private version of Apache is installed to ensure that:
  1. The Management Portal runs out of the box.
  2. An out-of-the-box testing capability is provided for development environments.
The private Apache Web server is not supported for any other purpose.
For deployments of http-based applications, including CSP, Zen, and SOAP over http or https, you should not use the private web server for any application other than the Management Portal; instead, you must install and deploy one of the supported web servers (for information, see “CSP Supported Web Servers” in the “Supported Technologies” chapter of InterSystems Supported Platforms).
Supported Upgrade Paths and Procedures
If you are performing an upgrade, first read and perform all necessary procedures described in the Upgrading Caché chapter of this guide.
When upgrading, back up your Caché instance after completing all the pre-installation upgrade tasks and before installing Caché.
Caché Installation
There are four main starting points to run an attended Caché installation on a UNIX® platform. The following sections explain each in detail:
Standard Caché Installation
Standard Caché installation consists of a set of modular package scripts. The scripts conditionally prompt for information based on input to previous steps, your system environment, and whether or not you are upgrading an existing instance. The first stage of the installation stores all gathered information about the install in a parameter file. You then confirm the specifics of the installation before the actual install takes place. The final phase performs the operations that are contingent upon a successful install, such as instance startup.
To install a Caché server, log in as user ID root. It is acceptable to su (superuser) to root while logged in from another account.
Once you are logged into your operating system, perform the following steps:
Uncompress the Installation Kit
If your installation kit is in the form of a .tar file, for example cache-2015.2.0.600.0-lnxrhx64.tar.gz, uncompress the file into a temporary directory to avoid permissions issues, as shown in the following example.
Important:
Do not uncompress the file into or run Caché installation from the /home directory, or any of its subdirectories.
# mkdir /tmp/cachekit 
# chmod og+rx /tmp/cachekit 
# gunzip -c /download/cache-2016.2.0.600.0-lnxrhx64.tar.gz | ( cd /tmp/cachekit ; tar xf - )
The installation files uncompress into a directory with the same name as the .tar file, for example /tmp/cachekit/cache-2016.2.0.600.0-lnxrhx64 in the preceding example.
Note:
The pathname of the temporary directory cannot contain spaces.
Because legacy tar commands may fail silently if they encounter long pathnames, InterSystems recommends that you use GNU tar to untar this file. To determine if your tar command is a GNU tar, run tar --version.
Determine the Installation Directory
You must choose a fully resolved physical path, containing no symbolic links, for the Caché installation directory.
Note:
The Caché registry directory, /usr/local/etc/cachesys, is always created along with the Caché installation directory.
Determine Owners and Groups
The installation process prompts for the following user and group information (see the UNIX® User and Group Identifications section in the “Using Caché on UNIX®, Linux, and Mac OS X” chapter of the Caché System Administration Guide):
Important:
The user you identify as the owner of the instance must have read and execute access to the installation kit during the installation process
In addition, during installation Caché must set user, group, and other permissions on files that it installs; therefore, do not modify the default umask value during installation.
The user account you identify as the instance owner and the group you identify as the instance start/stop group must exist before you begin installation. If an entry you provide at one of these prompts does not exist, the prompt is repeated, so verify that the user and group you intend to provide exist before you begin installation.
If your operating system contains the useradd and groupadd utilities, Caché creates the account for the effective user for Caché superserver and the effective group for Caché processes, if the entries you provide do not exist. However, if these utilities are not present and an entry you provide does not exist, the prompt is repeated. If you are not sure that your system has these utilities, verify that the user and group you intend to provide exist before you begin installation.
Note:
If your operating system uses Network Information Services (NIS) or another form of network-based user/group database, the groupadd and useradd utilities may create a local user and/or group that could conflict with existing entries in the network database. To avoid this problem, it may be best to create the Caché effective group and effective user in your network database using the appropriate administration tools prior to beginning installation, rather than allowing the utilities to create them.
Tools used on UNIX® operating systems to display process ownership may or may not show effective versus real ownership. See the Using Caché on UNIX®, Linux, and Mac OS X chapter of the Caché System Administration Guide for details on how Caché assigns permissions.
Run the Installation Script
The installation script, cinstall, which must be run by a user with root privileges, automatically does the following:
Note:
If the profile of the user executing cinstall has a value set for the CDPATH variable, the installation fails.
A user without root privileges can perform a non-standard, limited Caché installation; see Caché Non-root Installation for details.
Install Procedures
To perform the standard Caché server installation:
  1. As a user with root privileges, start the installation procedure by running the cinstall script, located at the top level of the installation files:
    # /<pathname>/cinstall
    
    where pathname is the location of the installation kit, typically the temporary directory to which you have extracted the kit, as described in Uncompress the Installation Kit.
  2. The installation script identifies your system type and validates it against the installation type on the distribution media. If your system supports more than one type, for example, 32-bit and 64-bit, or if the install script cannot identify your system type, it prompts you with additional questions. If your system type does not match that on the distribution media, the installation stops. Contact the InterSystems Worldwide Response Center (WRC) for help in obtaining the correct distribution.
  3. The script displays a list of any existing Caché instances on the host.
  4. At the Enter instance name: prompt, enter an instance name, using alphanumeric characters only. If an instance with this name already exists, the program asks if you wish to upgrade it. If no such instance exists, it asks if you wish to create it and asks you to specify its installation directory. If the directory you specify does not exist, it asks if you want to create it. The default answer to each of these questions is Yes; press Enter to continue with the installation.
    Note:
    If you select an existing instance that is of the same Caché version as the installation kit, the installation is considered an upgrade, and you can use the Custom selection, described in the following step, to modify the installed client components and certain settings.
  5. Next select the setup type.
    The core of a functioning Caché instance is the Caché server. You can do the install the server and the CSP web server gateway, plus the tools needed for development work, including Caché Studio, the ODBC and JDBC drivers, and all supported language bindings. You can also install the server and the CSP gateway only, without the development tools. Finally, you can do a custom install in which you choose the components to install and specify some additional installation options. These choices are shown in the following:
    Select installation type.
        1) Development - Install Cache server and all language bindings
        2) Server only - Install Cache server
        3) Custom - Choose components to install
    Setup type <1>? 
    The default for new instances is Development; if you are upgrading an existing instance, the default is the option that was used to originally install the instance. See Caché Custom Installation section for details on the Custom option.
  6. Next, indicate whether to install Caché with 8-bit or Unicode character support. On upgrade, you can convert from 8-bit to Unicode, but not the reverse.
  7. For new instances, you must next specify security settings. (Security settings cannot be changed when upgrading.)
    First, decide how restrictive you want the initial Caché security settings to be: choose from Minimal (1), Normal (2), and Locked Down (3). The default is Minimal; if you choose this, the owner of the instance becomes root and the installation continues with the next step.
    If you enter 2 or 3, the script asks for additional information:
    1. Instance owner — Enter the username of the account under which to run Caché processes. Once Caché is installed, you cannot change the owner of the instance. See Determine Owners and Groups for information about this account. A Caché user account is created with this username and the password you enter at the next prompt.
    2. Password for the instance owner — Enter the password for the username you entered at the previous prompt, and enter it again to confirm it.
      This password is used not only for the Caché user account is created for the instance owner username, but also for the _SYSTEM, Admin, and SuperUser predefined user accounts. For more details on these predefined users, see the Predefined User Accounts section of the “Users” chapter of the Caché Security Administration Guide.
    3. Password for the CSPSystem predefined user.
    Note:
    Passwords entered during this procedure cannot include space, tab, or backslash characters; the installer reject such passwords. (On Oracle Solaris platforms, however, the installer cannot detect the entry of a single backslash character.)
    For a detailed explanation of these settings, see the Initial Caché Security Settings section of the “Preparing for Caché Security” appendix of this guide.
    Important:
    There are additional security settings that you can choose only through a custom install. See Caché Custom Installation for details.
  8. At this point in the installation, you are asked which group should be allowed to start and stop Caché. Only one group can have these privileges, and it must be a valid group on the machine; see Determine Owners and Groups for more information. Enter the name or group ID number of an existing group; Caché verifies that the group exists before proceeding.
  9. Finally, for a new instance, or if the script does not detect a cache.key file in the mgr directory of an existing instance when upgrading, you are prompted for a license key file. If you specify a valid key, the license is automatically activated and the license key copied to the instance’s mgr directory during installation, and no further activation procedure is required. If you do not specify a license key, you can activate a license key following installation. See Activating a License Key in the “Managing Caché Licensing” chapter of the Caché System Administration Guide for information about licenses, license keys and activation.
  10. Review your installation options and press enter to proceed with the installation. File copying does not begin until you answer Yes.
    A standard installation sets the following port numbers for a Caché instance:
    If you want to assign different port numbers during a new installation, you must choose the custom option. See the Caché Custom Installation section for details.
    You can change the Superserver port number after installation from the Memory and Startup page (System Administration > Configuration > System Configuration > Memory and Startup) of the Management Portal.
    You can change the Web server port number after installation from the Startup Settings page (System Administration > Configuration > Additional Settings > Startup) of the Management Portal.
When the installation completes, you are directed to the appropriate URL for the Management Portal to manage your Caché system. See the Using the Management Portal chapter of the Caché System Administration Guide for more information.
Caché Custom Installation
If you choose a custom installation, you must answer additional questions throughout the procedure about installing several individual components. The defaults appear in brackets before the question mark (?); press Enter to accept the default.
See the following guides in the Caché Language Bindings set for more information on the specific client components in the selection list:
Linux RPM Caché Component Installation
For Linux platforms only, InterSystems provides RPM installation kits for component installations. Using these kits, you can perform the following types of Caché installs:
Please note the following points about RPM installation:
Install from the appropriate RPM package file using the following command:
# rpm -ivh cache-development-2016.2.0.569.0-1.rh.x86_64.rpm
For an upgrade from an RPM package file, use the following command:
# rpm -U cache-development-2016.2.0.569.0-1.rh.x86_64.rpm
Note:
Caché does not support the --relocate option of the rpm command, due to the complexity of the package file.
Important:
RPM installation of a new Caché instance does not start the instance following installation.When you start Caché the first time after the installation, it performs the required initialization actions including initializing the databases and creating the configuration file. See the Start Caché section for details on how to start Caché after the installation.
An RPM upgrade install stops the Caché instance before it replaces files and starts it afterwards, if it was running before the upgrade.
Caché Non-root Installation
Although Caché is typically installed as root, it is possible for an instance to be installed and run by another user on a system on which root is not available. The operation of Caché in such an environment is identical to that of standard Caché instances, except for the following:
The registry is located in the directory specified by CACHESYS, and instances are found in that directory. (The ccontrol and csession executables are in that directory as well.) Users who employ CACHESYS as a registry location for root-installed instances are unaffected. Note, however, that only non-root instances may be in the non-root registry. Any attempt to access a standard instance from a non-root registry will fail. Conversely, a non-root instance may be defined in a root-registry, but an attempt to access the instance by any user other than the owner will fail.
Note:
InterSystems recommends that the registry be placed in a directory that is local to the machine on which the instance is installed, not an NFS directory. Note that the standard location /usr/local/etc is such a directory.
Non-root installation differs from standard installation in the following ways:
Caché Client Installation
The Caché distribution also contains a separate script to install a client-only version of Caché. The installation process is fairly simple. You do not need to install as root. The files from this install have the user and group permissions of the installing user. To perform the Caché client installation:
  1. Start the installation procedure by running the cinstall_client script, located at the top level of the installation files:
    # /pathname/cinstall_client
    
  2. Choose from the available client component options. Components that require the Caché server on the same machine do not appear in the list. For example:
    Client component selection
    
       [*]    1) ODBC client
       [*]    2) C++ binding
       [*]    3) C++ SDK
       [*]    4) Perl binding
       [*]    5) Python binding
              +) Select all
    
    Enter the number of each component you wish to install.
    Enter the number of an already selected component to deselect it.
    Multiple selections can be separated by spaces.
    Enter a blank line to continue.
    You can use the plus sign (+) to select all components. If this is an upgrade and you clear a previously installed component, that component is neither upgraded nor uninstalled.
The list of client-only components does not include the engine link libraries or the light C++ binding because these components require a server installation.
You cannot use this script to update client components in server installations. Use the cinstall script instead.
See the following guides in the Caché Language Bindings set for more information on the specific client components in the selection list:
Unattended Caché Installation
You can perform unattended installation and upgrade of Caché instances on your systems using the cinstall_silent script. Whereas a standard install operation obtains the required specifications and selections in the form of user responses to prompts, an unattended operation gets this information from the configuration parameters and the packages specified on the cinstall_silent command line. Each specified package represents a Caché component; the installation scripts for each component are contained in the packages directory below the directory containing the cinstall_silent script.
The general format for the cinstall_silent command line is to precede the command itself by setting environment variables to define the installation parameters, as follows:
sudo ISC_PACKAGE_INSTANCENAME="<instancename>"
 ISC_PACKAGE_INSTALLDIR="<installdir>"
 ISC_PACKAGE_PLATFORM="<platform>" ISC_PACKAGE_UNICODE="Y"|"N"
 ISC_PACKAGE_INITIAL_SECURITY="Minimal"|"Normal"|"Locked Down"
 ISC_PACKAGE_MGRUSER="<instanceowner>" ISC_PACKAGE_MGRGROUP="<group>"
 ISC_PACKAGE_USER_PASSWORD="<pwd>"  ISC_PACKAGE_CSPSYSTEM_PASSWORD="<pwd>"
 ISC_PACKAGE_CACHEUSER="<user>" ISC_PACKAGE_CACHEGROUP="<group>"
 ISC_PACKAGE_CLIENT_COMPONENTS="<component1> <component2> ..."
 ISC_PACKAGE_STARTCACHE="Y"|"N"
 ./cinstall_silent [<pkg> ...]]
This section contains the following subsections:
Unattended Installation Parameters
The following table describes the parameters used with the cinstall_silent script in unattended installation.
Unattended Installation Parameters
Parameter Description
(Required)
Specifies the name of the instance to be installed or upgraded: if the instance does not exist, this is a new installation; if it does exist, this is an upgrade. For example:
ISC_PACKAGE_INSTANCENAME="MyCache"
If this a new install, the ISC_PACKAGE_INSTALLDIR parameter is required.
(Required for new instances)
Specifies the installation directory for the new instance to be installed; for example:
ISC_PACKAGE_INSTALLDIR="/opt/MyCache"
If the specified directory does not exist, the installation attempts to create it. This parameter is ignored if you are upgrading an installation.
If this a new install, but this parameter is not specified, the installation fails and an error is thrown.
(Optional)
Specifies a platform when installing Caché on a system that supports multiple platforms on the same hardware.
Currently, the only ISC-supported platform that supports this feature is IBM AIX®; valid values are ppc (32–bit system) and ppc64 (64–bit system). For example:
By default, the platform is auto-detected. If the parameter is omitted and no supported platform is detected, unattended installation terminates with an error.
(Optional)
Specifies whether or not this is a UNICODE installation; valid values are Y or N.
By default, this is set to N (8–bit); see Caché Character Width for more information.
(Optional)
Specifies the initial security setting for the installation; valid values are: "Minimal", "Normal", or "Locked Down".
By default, the security level is set to "Minimal".
If it is set to "Normal" or "Locked Down", ISC_PACKAGE_USER_PASSWORD is required.
(Optional)
Specifies the login name of the owner of the installation. For example:
ISC_PACKAGE_MGRUSER="jcsmith"
By default, this is set to the username of the user who is installing the instance.
If the security level is "Minimal", this parameter is ignored, and ISC_PACKAGE_MGRUSER is set to "root".
(Optional)
Specifies the group that is allowed to start and stop the instance. For example:
ISC_PACKAGE_INITIAL_MGRGROUP="cacheusr"
By default, this is set to the group of the user who is installing the instance.
(Required for installation of secure instances.)
Specifies the required password for an instance with normal or locked down security.
If the security level is "Minimal", this parameter is ignored.
If the security level is "Normal" or "Locked Down" and this parameter is not specified, the installation fails and an error is thrown.
ISC_PACKAGE_CSPSYSTEM_PASSWORD="<password>" Specifies the password for the CSPSystem user.
If the security level is "Minimal", this parameter is ignored.
If the security level is "Normal" or "Locked Down" and this parameter is not specified, the value of ISC_PACKAGE_USER_PASSWORD is used.
(Optional)
Specifies the effective user for the Caché SuperServer.
By default, this is set to cacheusr.
If the security level is "Minimal", this parameter is ignored and set to the default.
(Optional)
Specifies the effective user for Caché processes.
By default, this is set to cacheusr.
If the security level is "Minimal", this parameter is ignored and set to the default.
ISC_PACKAGE_CLIENT_COMPONENTS="<component1> <component2> ..."
(Optional)
Specifies the client bindings to be installed from the client_components package (see Unattended Installation Packages).
By default, all client bindings are installed. Specified components (bindings) must be space-delimited. Available components are listed in package/client_components/manifest.isc. Installation validates the specified components and removes those that do not exist or are not supported on a particular system.
ISC_PACKAGE_CSP_CONFIGURE="Y"|"N"
(Optional)
Specifies whether or not to configure the CSP Gateway for an external web server.
By default, this is set to N (do not configured the gateway for an external web server).
ISC_PACKAGE_CSP_SERVERTYPE="Apache"|"SunOne"|"None"
(Optional)
Type of existing web server for the CSP Gateway to use. For example: ISC_PACKAGE_CSP_SERVERTYPE="Apache"
By default, this is set to None.
ISC_PACKAGE_CSP_APACHE_VERSION=2.2|2.4 Version of Apache web server.
By default, the version is autodetected.
ISC_PACKAGE_CSP_APACHE_USER="<username>" Username for Apache web server.
By default, the username is autodetected.
ISC_PACKAGE_CSP_APACHE_CONF="<path_to_httpd.conf>" Location of the Apache Web server configuration file, for example: /etc/httpd/conf/httpd.conf
By default, installation attempts to autodetect file in one of several stardard locations. Installation exits with error if ISC_PACKAGE_CSP_SERVERTYPE="Apache" and httpd.conf location is undetermined.
ISC_PACKAGE_CSP_SUNONE_DIR="<sunone_installation_dir>" Installation directory of the SunOne web server, for example:
By default, the installation directory is autodetected.
ISC_PACKAGE_CSP_SUNONE_NUMBER="<number>" SunOne web server number to configure if multiple servers are installed.
By default, value is 1.
ISC_PACKAGE_CSP_GATEWAY_DIR=”<csp_gateway_directory>”
(Optional, for new CSP Gateway installations only)
Directory to contain the CSP Gateway files.
By default, the directory is /opt/cspgateway_.
ISC_PACKAGE_STARTCACHE="Y"|"N"
(Optional)
Specifies whether or not to start the installed Caché instance following installation.
By default, this is set to Y, to start the instance.
ISC_INSTALLER_MANIFEST="<location>" When installing with an installation manifest, specifies the location of the exported manifest class.
ISC_INSTALLER_PARAMETERS="<var>=<value>,<var>=<value> ..." When installing with an installation manifest, specifies variable name/value pairs.
ISC_INSTALLER_LOGFILE="<filename>" When installing with an installation manifest, specifies the log file name.
ISC_INSTALLER_LOGLEVEL="<level>" When installing with an installation manifest, specifies the log level, from 0 (“none”) to 3 (“verbose”).
Unattended Installation Packages
The installation scripts for each component are contained in the packages directory below the directory containing the cinstall_silent script. Each package is in its own directory, and each package directory contains a manifest.isc file defining prerequisite packages for the package in that directory.
The standard_install package is the starting point for a server install in which all packages are installed. To define a custom package, you can use the manifest.isc file for the standard_install package as a template, as follows:
  1. Copy the standard_install directory to a new directory.
    For example, copy it to a directory named custom_install; initially, the manifest.isc file in the new directory is similar to the following:
    #This is the target for a standard (non-client-only) install
    package: standard_install
    prerequisite: install_mode
    prerequisite: database_server
    prerequisite: databases
    prerequisite: gadget
    prerequisite: fop
    prerequisite: renderserver
    prerequisite: printserver
    prerequisite: excelexporter
    prerequisite: callin_components
    prerequisite: client_components
    prerequisite: addenda
    prerequisite: install_confirmation
    prerequisite: copyright
  2. In the new directory, modify the manifest.isc file as follows:
    For example, in the following manifest.isc file, the package key has been changed to match the directory name (custom_install) and the databases prerequisite has been removed to exclude the Samples and Docbook databases from the installation:
    #This is the target for a custom (non-client-only) install
    package: custom_install
    prerequisite: install_mode
    prerequisite: database_server
    prerequisite: gadget
    prerequisite: fop
    prerequisite: renderserver
    prerequisite: printserver
    prerequisite: excelexporter
    prerequisite: callin_components
    prerequisite: client_components
    prerequisite: addenda
    prerequisite: install_confirmation
    prerequisite: copyright
Then you can specify the new custom package when performing unattended installations; for example: sudo ISC_PACKAGE_INSTANCENAME="MyCache" ./cinstall_silent custom_install.
Note:
See Adding UNIX® Installation Packages to a Caché Distribution for information about creating your own UNIX® installation packages and adding them to a Caché distribution.
Unattended Installation Examples
The following examples illustrate how you can use the cinstall_silent script for unattended installation of Caché on UNIX® platforms.
Example 1
In this example, the 8-bit versions of all packages are installed with minimal security:
sudo ISC_PACKAGE_INSTANCENAME="MyCache" ISC_PACKAGE_INSTALLDIR="/opt/mycache1" ./cinstall_silent
If the MyCache instance already exists, it is upgraded; otherwise, it is installed in the /opt/mycache1 directory.
Example 2
In this example, the installation is aborted and an error is thrown if the instance named MyCache does not already exist:
sudo ISC_PACKAGE_INSTANCENAME="MyCache" ./cinstall_silent
Example 3
In this example, the 8–bit versions of only the database_server and odbc packages and the odbc client binding are installed with minimal security:
sudo ISC_PACKAGE_INSTANCENAME="MyCache" ISC_PACKAGE_INSTALLDIR="/opt/mycache2"
ISC_PACKAGE_CLIENT_COMPONENTS="odbc" ./cinstall_silent database_server odbc
Post-installation Tasks
Once you have completed running the installation procedure, perform the following tasks:
Start Caché
The evaluation RPM Linux install does not start Caché when it completes. Start and stop Caché using the standard Linux methods. For example:
/etc/init.d/cache start
On Red Hat Linux, you can also use the following:
service <instname> start
Where instname is the instance name that you chose during the installation.
All other installs leave Caché running. If you need to start Caché, first log into your operating system, then start Caché using the ccontrol command:
ccontrol start <instname>
Where instname is the instance name that you chose during the installation.
Use the ccontrol command to start and stop Caché. It is described in greater detail in the Controlling Caché Instances section of the Caché System Administration Guide.
Note:
If the permissions on all elements of the path to the mgr subdirectory do not provide read access to the cacheusr group (at a minimum), the instance fails to fully start and the following message is recorded in cconsole.log: Element of path manager_subdirectory could not be read (errno 2).
Once Caché is started, initiate a Caché session using the csession command:
csession <instname> [parameters]
Where instname is the instance name that you chose during the installation.
For more information, see the Using Caché on UNIX®, Linux, and Mac OS X chapter of the Caché System Administration Guide.
Install Caché Client on Windows for Development
Caché installs a private Apache Web server so that you can access the Management Portal; therefore, a UNIX® system does not require a Caché client on a Windows machine to perform system configuration and management tasks.
You do, however, require a Windows client to use the Studio development tool. See Caché Client Installation in the “Installing Caché on Microsoft Windows” chapter of this guide for information on installing the Windows client only. Once installed, from the Caché Cube of the Windows client, perform the following tasks:
Special Considerations
The following sections describe particular issues or tasks associated with specific platforms or kinds of installations:
Using an Installation Manifest
You can define an installation manifest that describes a specific Caché configuration and use it with either of the cinstall or cinstall_silent commands. For more information on installation manifests, see the appendix Creating and Using an Installation Manifest.
Maximum User Process Recommendations
Ensure that the maximum user processes is set high enough to allow all Caché processes for a given user, as well as other default processes, to run on the system.
Journal File System Recommendations
To achieve optimal journal performance and ensure journal data integrity when there is a system crash, InterSystems recommends various file systems and mount options for journal files. For specific platform details see the UNIX® File System Recommendations section of the “Journaling” chapter of the Caché Data Integrity Guide.
Multiple Caché Instances
You can install and simultaneously run multiple instances of Caché 4.0 and later on a single machine. Install Caché as for a single installation, giving each instance a unique name, a unique installation directory, and a unique port number.
Please reference the Configuring Multiple Caché Instances section of the Caché System Administration Guide.
Uninstall Caché
To safely uninstall Caché, perform the following tasks:
  1. Find the name of the Caché instance you wish to delete using the ccontrol command to list all the instances on your machine:
    ccontrol list
  2. Verify the instance is stopped. If it is not, stop it with the following command:
    ccontrol stop <instname>
    Where instname is the instance name that you chose during the installation. If it hangs, use the following command to force it down:
    ccontrol force <instname>
  3. Remove the instance using the following command:
    ccontrol delete <instname>
  4. Remove the installation directory using the following operating system command:
    rm -r <directory>
    Important:
    Be aware that this removes files you may wish to keep. For example: the license key (cache.key), the configuration file (cache.cpf), and the user database file (cache.dat).
RPM Uninstall
If you installed Caché using the RPM package, uninstall using the following option:
# rpm -e cache-server
The uninstall procedure removes all files installed and created during normal Caché processing, including journal and temporary database files.
Important:
The SUSE Linux Enterprise Server 9 platform uses asynchronous scriptlets, so the uninstall process cannot guarantee that Caché stops before it removes files. InterSystems recommends you stop Caché on this platform before you run the RPM uninstall command.
HP-UX Considerations
See the HP-UX Platform Notes section of the Calculating System Parameters for UNIX® and Linux appendix for detailed configuration information.
Processor
Following are the recommended processor requirements:
Software and Patches
Following are the minimum software requirements:
Location of Patches and Service PAK’s
All Service PAKs and patches are available for download from the IT Resource Center (ITRC) at the following URL: http://www2.itrc.hp.com/service/home/hpMaint.do.
Storage
LUNs should be configured as follows:
Important:
In the interests of performance and recoverability, InterSystems recommends placing the primary and alternate journal directories on storage devices that are separate from the devices used by databases and the write image journal (WIJ), as well as separate from each other. For practical reasons, these different devices may be different logical unit numbers (LUNs) on the same storage area network (SAN), but the general rule is the more separation the better, with separate sets of physical drives highly recommended. Be sure to see Journaling Best Practices in the “Journaling” chapter of this guide for important information about ensuring journal availability for recovery.
LVM/VxVM
LVM/VxVM striping should not be used. If a filesystem requires the use of multiple LUNs, use concatenation or, if striping is required, use only extent-based striping. If possible, avoid LVM/VxVM mirroring.
File systems (VxFS)
At least 3 separate filesystems are required:
Software installation directories may be included in the WIJ filesystem. All filesystems should be created with: mkfs -F vxfs -o bsize=8192,largefiles [special].
Create /etc/vx/tunefstab, including the lines:
[block-device for wij] discovered_direct_iosz=512K,\
write_pref_io=256K,max_diskq=1M,max_buf_data_size=64K
[block-device for DBfs1] max_diskq=16M
[block-device for DBfs2] max_diskq=16M
.
.
.
The file must contain the /dev/... special device files used to mount the filesystems, not the paths to the filesystems themselves.
Mount all filesystems with the mount options "delaylog,largefiles". On VxFSV5, also include the mount option "noqio".
Do NOT use DirectIO (mount options "mincache=direct,convosync=direct") for the WIJ. Although DirectIO (or Concurrent IO on VxFSV5) may be used for database file systems, it can have an effect on write performance, which may cause problems with heavy write loads (for example, during batch updates); for additional information, see File System Mount Options on UNIX®/Linux Platforms in the “General File System and Disk/Storage Subsystem Configuration Recommendations” chapter of this guide.
HP-UX pwgrd Daemon
HP-UX distributions run a daemon (pwgrd) that caches password and group information from network queries. InterSystems does not explicitly enable or disable it, but prior to the 9/2008 Release of HP-UX 11iV3, it was enabled by default; beginning with that version, however, it is disabled by default. As a result of pwgrd being disabled, when installing Caché with a network user as the instance owner, users may see the following error: chown: unknown user id integ. To prevent the error from occurring, you should enable pwgrd.
HP-UX Kerberos Client Requirements
For Kerberos to work properly on the HP-UX 11i platform you must have the Kerberos Client (KRB5CLIENT) version 1.3.5. Verify you have the latest upgrade for HP-UX 11i v2 that includes this version. HP-UX 11i v3 includes the proper version of the client.
HP-UX Random Number Generator
Caché requires the HP-UX Strong Random Number Generator component for true entropy for its cryptographic random number generator. HP-UX 11i v2 now includes this component by default.
HP-UX fastbind Requirements
If you relink the cache binary on HP-UX or upgrade HP-UX after installing Caché, run the following command on the cache binary in the install-dir\bin directory:
$ /usr/css/bin/fastbind ./cache
IBM AIX® Considerations
The default settings of several AIX® parameters can adversely affect performance. For detailed information on the settings and recommendations, see the AIX® Platform Notes section of the Calculating System Parameters for UNIX® and Linux appendix.
System Requirements
For information about current system requirements, see the “Supported Technologies” chapter of InterSystems Supported Platforms.
Required C/C++ Runtime Libraries
You must ensure that the required C/C++ runtime is installed on your IBM AIX® system before installing Caché.
Caché for AIX is compiled using the IBM XL C/C++ for AIX 13.1 compiler. If the system on which you are installing Caché does not have the corresponding version of the runtime already installed, you must install these three runtime file sets from runtime package IBM_XL_CPP_RUNTIME_V13.1.0.0_AIX.tar.Z:
If these files are not present, Caché installation will not complete.
Full information about and download of this package is available at IBM XL C/C++ Runtime for AIX 13.1.
Shared Library Environment Variable for Caché Engine Link Libraries
The Caché Engine link libraries contain a batch file that references any installed C linker.
If you have either the standard UNIX® C libraries or any proprietary C libraries defined in the LIBPATH environment variable, then your environment is ready.
If not, append the paths for the standard UNIX® C libraries to LIBPATH; these paths are /usr/lib and /lib.
Use of Raw Ethernet
In order to use raw Ethernet, an IBM AIX® machine must have the DLPI (Data Link Provider Interface) packages installed. If the machine does not have the DLPI packages, obtain them from your IBM provider and create DLPI devices through the following procedure:
  1. Log in as root.
  2. In the PSE drivers section of the /etc/pse.conf file, uncomment the four lines that refer to the DLPI drivers.
  3. Save the file.
  4. Restart the computer.
If the DLPI devices are not installed, the EthernetAddress() method of the %SYSTEM.INetInfo class returns a null string rather than information about the Ethernet device.
Red Hat Linux Considerations
The following considerations may apply to your environment:
Oracle Solaris Considerations
Using Kerberos on Solaris SPARC Release 10 requires two Patch IDs 120469-03 and 121239-01. You can download these patches from the Oracle Support website.
If the Ethernet adapters are protected against access by non-root users, the EthernetAddress() method of the %SYSTEM.INetInfo class invoked by a non-root user returns a null string rather than information about the Ethernet device.
If you install Caché in a non-global zone, you must perform the following additional configuration steps:
Note:
This procedure must be performed while in the global zone.
  1. Assure that /usr/bin and /usr/local subdirectories in the non-global zone have write permission, as shown in the following steps:
    1. Create the subdirectories (with write permission) in the global zone, as shown in the following example:
      bash-3.00# mkdir -p /export/zones/test-zone/local 
      bash-3.00# mkdir -p /export/zones/test-zone/bin  
      
      bash-3.00# chmod 700 /export/zones/test-zone/local 
      bash-3.00# chmod 700 /export/zones/test-zone/bin 
    2. Configure the /usr/bin and /usr/localsubdirectories (with read-write permission) for the non-global zone to use the subdirectories created above in the global zone, as shown in the following example:
      bash-3.00# zonecfg -z test-zone 
      zonecfg:test-zone> add fs 
      zonecfg:test-zone:fs> set dir=/usr/local 
      zonecfg:test-zone:fs> set special=/export/zones/test-zone/local 
      zonecfg:test-zone:fs> set type=lofs 
      zonecfg:test-zone:fs> set options=[rw,nodevices] 
      zonecfg:test-zone:fs> end 
      zonecfg:test-zone> verify 
      zonecfg:test-zone> commit 
      zonecfg:test-zone> exit  
      
      bash-3.00# zonecfg -z test-zone 
      zonecfg:test-zone> add fs 
      zonecfg:test-zone:fs> set dir=/usr/bin 
      zonecfg:test-zone:fs> set special=/export/zones/test-zone/bin 
      zonecfg:test-zone:fs> set type=lofs 
      zonecfg:test-zone:fs> set options=[rw,nodevices] 
      zonecfg:test-zone:fs> end 
      zonecfg:test-zone> verify 
      zonecfg:test-zone> commit 
      zonecfg:test-zone> exit
    3. Copy all binaries to the newly created /usr/bin subdirectory for the non-global zone to ensure that the non-global zone boots properly, as shown in the following example:
      bash-3.00# cp -rp /usr/bin/* /export/zones/test-zone/bin
  2. For ECP connections to work properly in non-global zones, proc_priocntrl privileges must be specified within the zone, as shown in the following example:
    bash-3.00# zonecfg -z test-zone
    zonecfg:test-zone> set limitpriv=”default,proc_priocntl”
    zonecfg:test-zone> verify
    zonecfg:test-zone> commit
    zonecfg:test-zone> exit
    
See the Oracle Solaris Platform Notes section of the Calculating System Parameters for UNIX® and Linux appendix for more information.
SUSE Linux Considerations
The following considerations may apply to your environment:
See the SUSE Linux Platform Notes section of the Calculating System Parameters for UNIX® and Linux appendix for detailed configuration information.
Adding UNIX® Installation Packages to a Caché Distribution
This section describes how to add a new UNIX® installation package to an existing Caché distribution. It is presented in the form of a tutorial in which we create a simple package that copies additional files into the Caché instance directory.
Note:
Because install packages are implemented through UNIX® shell scripts, you can also write packages that perform much more complex operations.
Suppose we have written a Caché Callout shared library (see the Creating a Caché Callout Library chapter in Using the Caché Callout Gateway) to connect to an imaging device named Foo9000. We compile this library as libfoo9000.so and want to install it with Caché. In addition, we want the installation to prompt users to provide the network server name for the device (Foo9000) to which we want the library to connect. This information will be stored in a configuration file in the Caché instance manager's directory (install-dir\mgr).
We start with an existing Caché kit:
~/kit:>ls
cinstall   cplatname docs  lgpl.txt NOTICE
copyright.pdf dist   kitlist LICENSE package
... and our compiled library (libfoo9000.so):
~/lib:>ls
libfoo9000.so
First, we need to choose a location in the kit to store our library, then copy the library to that location. By convention, platform-specific libraries go in dist/package/platform directories (for example, ~/kit/dist/foo9000/lnxsusex64):
~/kit:>cd dist
~/kit/dist:>mkdir foo9000
~/kit/dist:>cd foo9000
~/kit/dist/foo9000:>mkdir lnxsusex64
~/kit/dist/foo9000:>cd lnxsusex64
~/kit/dist/foo9000/lnxsusex64:>cp ~/lib/libfoo9000.so .
Next, we need to create the installation package directory and add the manifest.isc file (which describes the package) to it. In its simplest form, the manifest.isc file includes only the name of the package, which must be identical to the name of the package directory (foo9000).
~/kit/package:>mkdir foo9000
~/kit/package:>cd foo9000
~/kit/package/foo9000:>emacs manifest.isc
package: foo9000
Without any content the package does not do anything, but in this tutorial we want to do the following:
  1. Prompt users for the name of the server hosting the Foo9000.
  2. Save this information in a configuration file in the manager's directory (install-dir\mgr).
  3. Copy the library (libfoo9000.so) into the instance binary directory.
The package installer performs actions in phases, the most important of which are the following:
Note:
Packages can contain Bourne shell scripts, with the same name as the phase, for each phase. The package installer runs the script for each package at the appropriate time during the phase. If your package script successfully completes its given phase, it returns an error code of 0 explicitly or implicitly via its final command; otherwise it returns a non-zero error code.
The “parameters” phase collects information necessary for the package's installation, typically by prompting users, and should not make any permanent changes to the system. Users are typically given the opportunity to cancel the installation after the “parameters” phase; if they do so, the installation should have had no effect on their system.
The “install” phase modifies the system. During the install phase users should not be prompted for information because the install may be unattended or automated.
Some packages do not require information from users and, therefore, do not need a “parameters” script. If the script for a particular phase is not included in a package, no actions are performed for that package during the phase.
Here is our first attempt at a “parameters” script for the foo9000 package:
~/kit/package/foo9000:>emacs parameters
#!/bin/sh
echo "Please enter host name of the Foo9000 imaging server: "
read host
echo "Host $host entered."
If we try running this script, as follows, we see that it does indeed prompt us for the host name. which it records in the host variable:
~/kit/package/foo9000:>sh parameters
Please enter host name of the Foo9000 imaging server:
cupertino
Host cupertino entered.
However, what do we do with the host value once we've acquired it? When the script is finished running, it will be lost and unavailable when we need to write it to the configuration file during the “install” phase.
Note:
Remember that we do not want to create the configuration file now because the “parameters” phase should have no effect on the user's system.
The package installer provides a convenient pair of functions – Import and Export – that let multiple phases and multiple packages share information. We can use these functions by including them in the parameters.include file through the usual shell script mechanism:
#!/bin/sh
. parameters.include
echo "Please enter host name of the Foo9000 imaging server: "
read host
echo "Host $host entered."
Export foo9000.host $host
The Export function takes the name of a parameter variable to export and its value, typically from a variable local to the script. The Import function works in reverse: the first argument is the local variable into which you want to import the previously exported value, and the second argument is the name of the parameter variable to which it was exported.
Note:
By convention, parameter variables are given a name of package name.local variable name (for example, foo9000.host).
Since our “parameters” script now collects all the Foo9000 information needed to complete the installation, we can turn to writing the “install” script:
~/kit/package/foo9000:>emacs parameters
#!/bin/sh
. parameters.include 
Import host foo9000.host
echo host=$host > ????/mgr/foo9000.cfg
cp ????/dist/foo9000/????/libfoo9000.so ????/bin
There are a few details (???? in the preceding script) we need to provide:
Although we could include these questions in the “parameters” script, that may confuse users because they already entered that information earlier in the install. Instead, we import parameter variables from other packages that can provide the information we need. This is possible because each successful installation using the cinstall, cinstall_client or cinstall_silent scripts (as described in Caché Installation) creates the parameters.isc file, which contains these variables and their values, in the installation directory. The variables in the parameters.isc file are listed in the Caché Installation Parameter File Variables table at the end of this chapter.
Note:
For security reasons, the parameters.isc file is accessible only by the root user.
In order to use the parameter variables from a particular package, we must inform the package installer that our package (foo9000) depends on the other package and, therefore, our package must be processed later in each phase than the other package. We do this by adding “prerequisite” values to our package's manifest.isc file:
~/kit/package/foo9000:>emacs manifest.isc
package: foo9000
prerequisite: server_location
prerequisite: legacy_dist
prerequisite: platform_selection
Now we can import parameter variables from these packages and use them to complete our install script:
~/kit/package/foo9000:>emacs install
#!/bin/sh                                    
. parameters.include
Import host foo9000.host
Import tgtdir "server_location.target_dir"
Import srcdir "legacy_dist.source_dir"
Import platform_family "platform_selection.platform_family"
echo host=$host > $tgtdir/mgr/foo9000.cfg
cp $srcdir/dist/foo9000/$platform_family/libfoo9000.so $tgtdir/bin
Our package (foo9000) is nearly complete. The final task is to add our package to the prerequisite list for an appropriate preexisting package. Then, to complete installation of that package, the package installer will process ours. In this case, we want our library to be installed and configured any time a Caché server is installed, so we add our new package to the “database_server” package's prerequisite list inside its manifest.isc file:
~/kit/package/database_server:>emacs manifest.isc
package: database_server
prerequisite: legacy_dist
prerequisite: platform_selection
prerequisite: server
prerequisite: server_location
prerequisite: upgrade
prerequisite: available_disk_space
prerequisite: posix_tools
...
prerequisite: isql
prerequisite: zlib
prerequisite: udp
prerequisite: bi
prerequisite: foo9000
As you can see, many packages are required to create a server installation, but now, when we run cinstall, our package (foo9000) is configured and installed:
~/kit:>sudo ./cinstall
Your system type is 'SuSE Linux Enterprise Server 10 (x64)'.
Currently defined instances:
Cache instance 'TRWTURBO'
directory: /home/woodfin/TRWTURBO
versionid: 2008.2.0.456.0
conf file: cache.cpf (SuperServer port = 1972, WebServer = 57785)
status:  crashed, last used Sat Sep 13 08:37:32 2008
Enter instance name: TRWPACK1
Do you want to create Cache instance 'TRWPACK1' ? Y
...
Please enter host name of the Foo9000 imaging server:
cupertino
Host cupertino entered.
...
Do you want to proceed with the installation ? Y
...
Installation completed successfully
~/TRWPACK1/bin:>ls libfoo*
libfoo9000.so
~/TRWPACK1/mgr:>cat foo9000.cfg 
host=cupertino
Contents of the parameters.isc File
The following table lists the variables in the parameters.isc file with a description and an example value or a list of valid values.
Caché Installation Parameter File Variables
Variable name Description
dist.source_dir Source directory of the installation media.
legacy_dist.source_dir For legacy purposes, source directory of the installation media.
product_info.version InterSystems product version number.
product_info.name Name of InterSystems product.
platform_selection.platform InterSystems abbreviation for install platform.
platform_selection.platform_family InterSystems abbreviation for install platform family.
platform_selection.endianness Platform endian byte order.
platform_selection.os Platform operating system; value of uname command.
posix_tools.user_add Portable Operating System Interface (POSIX)-compliant user add tool.
posix_tools.group_add POSIX-compliant group add tool.
posix_tools.grep POSIX-compliant grep utility.
posix_tools.id POSIX-compliant id utility.
posix_tools.ps_opt Extend full options for process listing.
posix_tools.gzip Gnu-compatible zip utility.
posix_tools.shared_ext Extension for shared library files.
posix_tools.symbolic_copy POSIX-compliant symbolic copy command.
posix_tools.tr POSIX-compliant translation utility.
posix_tools.shared_ext1 Alternate extension for shared library files.
posix_tools.permission POSIX-compliant permissions applied to selected files.
posix_tools.dir_permission POSIX-compliant permissions applied to selected directories.
server_location.target_dir Target directory of server installation.
server_location.is_server_install Indicates whether or not this is a server installation.
server_location.instance_name Instance name.
server_location.is_new_install Indicates whether or not this is a new install.
((N=upgrade/Y=new)
server_location.registry_dir Location of the Caché registry directory (must be on a local filesystem).
server_location.ensemble_registry_dir n/a
server_location.convert_ensemble_registry If you are upgrading a pre-4.0 Ensemble instance this indicates to consolidate the old Ensemble registry with the Caché registry.
server_location.ccontrol Directory in which ccontrol resides during installation.
server_location.enscontrol (n/a) n/a
postinstall* Specifies packages to run after parameter file phase.
install_mode.setup_type Type of installation.
unicode_selection.binary_type Binary type of install.
unicode_selection.install_unicode Indicates whether or not to install the Unicode version of the product.
security_settings.cache_user Effective user for the Caché superserver
security_settings.cache_group Effective group for Caché.
security_settings.manager_user Owner of the instance.
security_settings.manager_group Group allowed to start and stop the instance.
security_settings.personal_database Indicates whether or not to use the Personal Database feature.
security_settings.initial_level Initial security settings.
security_settings.already_secured If this is an upgrade from a pre-5.1 instance, indicates the need for security settings.
security_settings.password Password field cleared before the parameter file is stored if running from cinstall.
manager_source_code.available Indicates whether or not to install the manager utility source code.
port_selection.superserver_port Superserver port number.
port_selection.webserver_port Web server port number.
port_selection.jdbcgateway_port Java Database Connectivity (jdbc) gateway port number.
csp_gateway.configure Indicates whether or not to configure the CSP Gateway for an external web server.
csp_gateway.web_server_type Type of existing web server for the CSP Gateway to use.
csp_gateway.apache_version Version of Apache web server
csp_gateway.apache_user Username for Apache web server
csp_gateway.apache_conf_file Location of the Apache Web server configuration file.
csp_gateway.apache_pid_file File that records the process id of the Apache web server daemon.
csp_gateway.apache_use32bit Indicates whether 32–bit architecture is used for the Apache web server.
csp_gateway.sunone_server Location of the Sun ONE server for the CSP Gateway to use.
csp_gateway.directory Directory to contain the CSP Gateway files.
license_key.enter_key Indicates whether or not to install the key during installation.
license_key.license_file Location of the key file information if the value of enter_key is Y.
agent.user_account Username for ISCAgent.
agent.user_group Group name for ISCAgent.
agent.install Indicates whether or not ISCAgent is installed.
install*
postinstall*
install* Used to initiate the installation of the SAMPLES database.
samples.install Indicates whether or not to install the SAMPLES database.
japanese_docs.install Indicates whether or not to install the Japanese documentation sources.
install* Used to initiate the installation of the online documentation.
docbook.install Indicates whether or not to install the DOCBOOK database for the online documentation.
client_location.target_dir Target directory of a client-only installation.
client_location.is_client_install Indicates whether or not it is a client install.
install* Component name to install.
installer.manifest Location of the DefaultInstallerClass.xml (the exported %Installer class); for example:
installer.manifest_parameters Location of installer manifest parameters; for example:.
* The install variable appears several times in the parameter file, once for every component to install. A custom or client-only install conditionally generates any or all of the following: