Skip to main content

Installing Caché on UNIX®, Linux, and macOS

This chapter describes how to install Caché on a UNIX®, Linux, or macOS system. It assumes that you are familiar with UNIX®, Linux, and macOS directory structures, utilities, and commands. Before beginning this installation, be sure you have read all the information that applies to this platform in the chapter “Preparing to Install Caché”.

This chapter contains the following major sections:

You can consult the section on Calculating System Parameters for UNIX®, Linux, and macOS to verify and adjust your parameter settings before you begin the installation.

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:

Performing a 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 steps in the following sections:

  1. Uncompressing the Installation Kit (if necessary).

  2. Determining the Installation Directory

  3. Determining Owners and Groups

  4. Running the Installation Script

Uncompressing 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 
# umask 022 
# 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.

Determining the Installation Directory

You must choose a fully resolved physical path, containing no symbolic links, for the Caché installation directory; there is no default location.

Important:

Be sure to see Installation Directory in the “Preparing to Install” chapter for important information about choosing an installation directory.

Note:

The Caché registry directory, /usr/local/etc/cachesys, is always created along with the Caché installation directory.

Determining 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 macOS” chapter of the Caché System Administration Guide):

  • Owner of the instance

  • Effective user for the Caché superserver and its jobs

  • Effective group for Caché processes

  • Group allowed to start and stop the instance

Important:

The user you identify as the owner of the instance needs read and execute access to the installation kit. To that end, the installing user should have a umask value of 022 (or less restrictive) when they untar the installation kit.

Additionally, Caché must set user, group, and other permissions on files that it installs. To accomplish this, Caché sets umask to 022 for the installation process - do not modify the umask until the installation is complete.

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, the system 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 macOS” chapter of the Caché System Administration Guide for details on how Caché assigns permissions.

Running the Installation Script

The installation script, cinstall, which must be run by a user with root privileges, automatically does the following:

  • Installs the Caché system manager databases.

  • Starts Caché in installation mode.

  • Installs Caché system manager globals and routines.

  • Shuts down Caché and restarts using the default configuration file (cache.cpf). Upgrade installations restart using their updated configuration files.

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 Installing Caché as a Nonroot User 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 Uncompressing 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)Opens in a new tab 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 install the server and the CSP web server gateway, plus the tools needed for development work, including 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 Determining 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.

    For a detailed explanation of these settings, see the Initial Caché Security Settings section in the chapter “Preparing for Caché Security” om 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:

    • Superserver port number1972 or the first available subsequent number equal to or higher than 56773

    • Web server port number57772 or the first available subsequent number

    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 > Memory and Startup).

    You can change the Web server port number after installation from the Startup Settings page (System Administration > Configuration > Startup Settings).

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.

  • Superserver and Web Server Ports — You can choose to let Caché assign the port numbers as described in the standard installation procedure or you can enter custom port numbers. Upgrade installs do not offer this choice; they keep the port numbers of the original instance.

  • CSP Gateway and External Web Sever — You can configure the CSP gateway to use a supported external web server. Answer Yes and then answer additional web server configuration questions to configure the CSP gateway after the Caché installation completes.

  • Additional Security Options — If you chose Normal or Locked Down initial security, you have the option of onfiguring additional security settings (minimal installations use the default IDs):

    • Effective group for Caché — Caché internal effective group ID, which also has all privileges to all files and executables in the installation. For maximum security, no actual users should belong to this group. (Defaults to cacheusr.)

    • Effective user for the Caché superserver — Effective user ID for processes started by the superserver and Job servers. Again, for maximum security, no actual users should have this user ID. (Defaults to cacheusr.)

    See Determine Owners and Groups for additional information.

  • Client Components — You have the option of installing one or more client components. The list of components to choose from depends on the platform; the illustration below shows all possible components, some of which are not supported on some platforms.

    Client component selection
    
       [*]    1) ODBC client
       [*]    2) C++ binding
       [*]    3) C++ SDK
       [*]    4) Perl binding
       [*]    5) Python binding
       [*]    6) Cache engine link libraries (callin)
       [*]    7) Light C++ 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.

See the following guides in the Caché Language Bindings set for more information on the specific client components in the selection list:

  • Using Caché ODBC

  • Using C++ with Caché

  • Using Perl with Caché

  • Using Python with Caché

  • Using the Caché Callin API

Installing Caché Components on Linux RPM

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:

  • RPM installation can install only one Caché instance per host and does not provide any installation options.

  • The instance name is always CACHE; the installation directory is always /usr/cachesys.

  • The Unicode version of Caché is always installed.

  • The Minimal initial security setting is always used.

  • The installation does not prompt for a license key.

  • Having installed the server component, you can use the other package files to add the other components.

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 Starting 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.

Installing Caché as a Nonroot User

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 CACHESYS environment variable must be defined as an existing directory writable by the installing user, and must be present during installation and all instance operations (cstart, cstop, csession).

  • The instance can be operated only by the installing user.

  • All Caché executables and processes run as the installing user.

  • All instance files, including the registry, are owned and can be read, written, and executed by the installing user only. There is no group access.

    For example, where a standard instance might have:

    -rws--x--- 5 root develop 43282 Aug 28 07:52 cmgr
    -r-x--s--x 1 <nonroot-user> cacheusr 23058 Aug 28 07:52 cuxsession
    

    a nonroot instance would have:

    -rwx------ 5 <installing-user> develop 43282 Aug 28 07:52 cmgr
    -r-x------ 1 <installing-user> develop 23058 Aug 28 07:52 cuxsession
    

The registry is located in the directory specified by CACHESYS, and nonroot instances are found in that registry. (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 nonroot instances may be in the nonroot registry. Any attempt to access a standard instance from a nonroot registry will fail. Conversely, a nonroot 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.

Nonroot installation differs from standard installation in the following ways:

  • There is no option to configure the CSP Gateway to use an external web server.

  • The ISCAgent (see ISCAgent and Configuring the ISCAgent in the “Mirroring” chapter of the Caché High Availability Guide) is installed in the directory specified by CACHESYS.

    Note:

    For information about starting the ISCAgent for a nonroot instance, see Starting the ISCAgent for Nonroot Instances on UNIX®/Linux and macOS Systems in the “Mirroring” chapter of the Caché High Availability Guide.

    Use of a mirror Virtual IP, as described in Planning a Mirror Virtual IP (VIP) in the “Mirroring” chapter, is not possible with a nonroot instance.

  • The instance owner and the group allowed to start and stop Caché are not specified.

Installing Client-only Caché

The Caché distribution 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

ISC_PACKAGE_INSTANCENAME="<instancename>"

(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"

Note:

If this a new install, the ISC_PACKAGE_INSTALLDIR parameter is required.

ISC_PACKAGE_INSTALLDIR="<installdir>"

(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.

Note:

If this a new install, but this parameter is not specified, the installation fails and an error is thrown.

ISC_PACKAGE_PLATFORM="<platform>"

(Optional)

Specifies a platform when installing Caché on a system that supports multiple platforms on the same hardware.

Important:

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:

ISC_PACKAGE_PLATFORM="ppc"

Note:

By default, the platform is auto-detected. If the parameter is omitted and no supported platform is detected, unattended installation terminates with an error.

ISC_PACKAGE_UNICODE="Y"|"N"

(Optional)

Specifies whether or not this is a UNICODE installation; valid values are Y or N.

Note:

By default, this is set to N (8–bit); see Caché Character Width for more information.

ISC_PACKAGE_INITIAL_SECURITY="Minimal"|"Normal"|"Locked Down"

(Optional)

Specifies the initial security setting for the installation; valid values are: "Minimal", "Normal", or "Locked Down".

Note:

By default, the security level is set to "Minimal".

If it is set to "Normal" or "Locked Down", ISC_PACKAGE_USER_PASSWORD is required.

ISC_PACKAGE_MGRUSER="<user>"

(Optional)

Specifies the login name of the owner of the installation. For example:ISC_PACKAGE_MGRUSER="jcsmith"

Note:

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".

ISC_PACKAGE_MGRGROUP="<group>"

(Optional)

Specifies the group that is allowed to start and stop the instance. For example:ISC_PACKAGE_INITIAL_MGRGROUP="cacheusr"

Note:

By default, this is set to the group of the user who is installing the instance.

ISC_PACKAGE_USER_PASSWORD="<password>"

(Required for installation of secure instances.)

Specifies the required password for an instance with normal or locked down security.

Note:

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.
Note:

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.

ISC_PACKAGE_CACHEUSER="<user>"

(Optional)

Specifies the effective user for the Caché SuperServer.

Note:

By default, this is set to cacheusr.

If the security level is "Minimal", this parameter is ignored and set to the default.

ISC_PACKAGE_CACHEGROUP="<group>"

(Optional)

Specifies the effective user for Caché processes.

Note:

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).
Note:

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.
Note:

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"
Note:

By default, this is set to None.

ISC_PACKAGE_CSP_APACHE_VERSION=2.2|2.4

(Optional, with ISC_PACKAGE_CSP_SERVERTYPE="Apache")

Version of Apache web server.
Note:

By default, the version is autodetected.

ISC_PACKAGE_CSP_APACHE_USER="<username>"

(Optional, with ISC_PACKAGE_CSP_SERVERTYPE="Apache")

Username for Apache web server.
Note:

By default, the username is autodetected.

ISC_PACKAGE_CSP_APACHE_CONF="<path_to_httpd.conf>"

(Optional, with ISC_PACKAGE_CSP_SERVERTYPE="Apache")

Location of the Apache Web server configuration file, for example: /etc/httpd/conf/httpd.conf
Note:

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>"

(Optional, with ISC_PACKAGE_CSP_SERVERTYPE="SunOne")

Installation directory of the SunOne web server, for example:

/usr/netscape/server4/httpd-production

Note:

By default, the installation directory is autodetected.

ISC_PACKAGE_CSP_SUNONE_NUMBER="<number>"

(Optional, with ISC_PACKAGE_CSP_SERVERTYPE="SunOne")

SunOne web server number to configure if multiple servers are installed.
Note:

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.
Note:

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.
Note:

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.
Note:

See Using the Manifest in the chapter “Creating and Using an Installation Manifest” for more information.

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”).

ISC_PACKAGE_SUPERSERVER_PORT="<port_number>"

(Optional)

Specifies the Superserver port to be used by the instance being installed.
Note:

By default, this port is auto-determined, beginning with 51773 and increasing by 1 for each installed instance of Caché.

ISC_PACKAGE_WEBSERVER_PORT="<port_number>"

(Optional)

Specifies the Webserver port to be used by the instance being installed.
Note:

By default, this port is auto-determined, beginning with 52773 and increasing by 1 for each installed instance of Caché.

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:

    • Change the package key to match the directory name (required).

    • Add and/or remove prerequisites for your custom installation.

    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:

Starting 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 macOS” chapter of the Caché System Administration Guide.

Installing 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 Performing a Caché Client Installation in the “Installing Caché on Microsoft Windows” chapter of this book for information on installing the Windows client only. Once installed, from the Caché Cube of the Windows client, perform the following tasks:

  • Point to Preferred Server and click Add/Edit to add a remote server connection to the Caché instance just installed. Make sure you specify the appropriate port numbers for this connection.

  • Point to Remote System Access, point to Studio, and then click the appropriate connection name you entered in the previous step.

Installing Caché on Mac

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

Installation Requirements

This section describes the hardware and software requirements for installations of Caché.

Disk Space Requirements

A standard Caché installation that includes support for Caché Server Pages (CSP), needs approximately 1 GB (gigabytes) of disk space depending on the type of installation you choose.

Supported Platforms and Web Servers

The latest version of Caché is supported on the macOS operating system on Intel. For macOS, the Caché Server Pages (CSP) technology is supported on the Apache and Nginx web servers. For current information, see the “Supported Technologies” chapter of the online InterSystems Supported PlatformsOpens in a new tab document for this release.

Note:

When installing Caché and Ensemble, a 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 “Supported Web Servers” in the “Supported Technologies” chapter of the online InterSystems Supported PlatformsOpens in a new tab document for this release).

If using CSP, you must install the web server before installing Caché for the installation to configure the web server. 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 Configuration” chapter of the Using Caché Server Pages guide for more information.

Important:

For up-to-date information about platforms, versions, and features supported for each operating system, see the “Supported Technologies” chapter of the online InterSystems Supported PlatformsOpens in a new tab document for this release.

Caché UNIX® Installation

The installation of Caché on the macOS is much like the installation on any UNIX® platform.

To install Caché:

  1. Obtain the installation kit from InterSystems and install it on the desktop.

  2. Log in as user ID root. It is acceptable to su (superuser) to root while logged in from another account.

  3. See Adjustments for Large Number of Concurrent Processes and make adjustments if needed.

  4. Follow the instructions in the Run the Installation Script section and subsequent sections of the “Installing Caché on UNIX and Linux” chapter of this guide.

  5. For post-installation tasks and other information about Caché on macOS, see the Installing Caché on a UNIX® or Linux sections of the “Installing Caché on UNIX and Linux” chapter of this guide.

Adjustments for Large Number of Concurrent Processes

Make the following adjustments if you are running a system that requires a large number of processes or telnet logins:

  1. Remote connections — The number of pty (pseudo terminal) connections is limited to 128 system-wide. If your applications count on telnet or other pty-using connections for users to access, keep this in mind.

  2. Number of processes — If the pty limit is not a problem, but you need to run a larger number of processes, there are limits to that as well.

    • System-wide process limits — The kern.maxproc, kern.maxprocperuid parameters are set to 532 and 100 by default. You can change them using the following commands:

      administrator$ sudo sysctl -w kern.maxproc=2500
      kern.maxproc: 2065 -> 2500
      administrator$ sudo sysctl -w kern.maxprocperuid=2500
      kern.maxprocperuid: 2000 -> 2500
      
      administrator$ sysctl -a | grep maxproc
      kern.maxproc = 2500
      kern.maxprocperuid = 2500
      
      

      Note, however, that 2500 is the absolute unchangeable upper limit.

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:

  • “parameters” phase

  • “install” phase

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:
host1
Host host1 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 install
#!/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:

  • Where is the instance directory in which the install is being created?

  • Where is the kit we're installing from?

  • Which platform is being installed?

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 'INSTANCE1'
directory: /home/user/INSTANCE1
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: INSTANCEPACK1
Do you want to create Cache instance 'INSTANCEPACK1' ? Y
...
Please enter host name of the Foo9000 imaging server:
host1
Host host1 entered.
...
Do you want to proceed with the installation ? Y
...
Installation completed successfully
~/INSTANCEPACK1/bin:>ls libfoo*
libfoo9000.so
~/INSTANCEPACK1/mgr:>cat foo9000.cfg 
host=host1
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

(Valid values) or Example

dist.source_dir Source directory of the installation media.

/cachekit

legacy_dist.source_dir For legacy purposes, source directory of the installation media.

/cachekit

product_info.version InterSystems product version number.

2012.2.0.100.0

product_info.name Name of InterSystems product.

(Cache/Ensemble/HealthShare)

platform_selection.platform InterSystems abbreviation for install platform.

lnxrhx64

platform_selection.platform_family InterSystems abbreviation for install platform family.

lnxrhx64

platform_selection.endianness Platform endian byte order.

(big/little)

platform_selection.os Platform operating system; value of uname command.

Linux

posix_tools.user_add Portable Operating System Interface (POSIX)-compliant user add tool.

/usr/sbin/useradd

posix_tools.group_add POSIX-compliant group add tool.

/usr/sbin/groupadd

posix_tools.grep POSIX-compliant grep utility.

grep

posix_tools.id POSIX-compliant id utility.

id

posix_tools.ps_opt Extend full options for process listing.

-ef

posix_tools.gzip Gnu-compatible zip utility.

gzip

posix_tools.shared_ext Extension for shared library files.

so

posix_tools.symbolic_copy POSIX-compliant symbolic copy command.

cp -Rfp

posix_tools.tr POSIX-compliant translation utility.

tr

posix_tools.shared_ext1 Alternate extension for shared library files.

so

posix_tools.permission POSIX-compliant permissions applied to selected files.

755

posix_tools.dir_permission POSIX-compliant permissions applied to selected directories.

775

server_location.target_dir Target directory of server installation.

/test/CACHE

server_location.is_server_install Indicates whether or not this is a server installation.

(N/Y)

server_location.is_nonroot_install Indicates whether or not this is a nonroot install.

(N/Y)

server_location.instance_name Instance name.

CACHE

server_location.is_new_install Indicates whether or not this is a new install.

((N=upgrade/Y=new)

server_location.is_new_directory Indicates whether or not to create a new directory.

(N/Y)

server_location.registry_dir Location of the Caché registry directory (must be on a local filesystem).

/usr/local/etc/cachesys

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.

(N/Y)

server_location.ccontrol Directory in which ccontrol resides during installation.

/cachekit/dist/lnxrhx64/bin/shared/ccontrol

postinstall* Specifies packages to run after parameter file phase.

upgrade

install_mode.setup_type Type of installation.

(Development/Server/Custom)

unicode_selection.binary_type Binary type of install.

(unicode/eightbit)

unicode_selection.install_unicode Indicates whether or not to install the Unicode version of the product.

(N/Y)

security_settings.cache_user Effective user for the Caché superserver

cacheusr

security_settings.cache_group Effective group for Caché.

cacheusr

security_settings.manager_user Owner of the instance.

root

security_settings.manager_group Group allowed to start and stop the instance.

develop

security_settings.dbencrypted Whether to enable an encryption key at startup

(0/1)

security_settings.dbenckeyfile The path of the encryption key.

This parameter may be blank.

security_settings.dbenckeyuser The name of an administrator who can activate the key.

This parameter may be blank.

security_settings.dbenckeypassword The password for the key administrator.

This parameter may be blank.

security_settings.personal_database Indicates whether or not to use the Personal Database feature.

(N/Y)

security_settings.initial_level Initial security settings.

(Minimal/Normal/Locked Down)

security_settings.already_secured If this is an upgrade from a pre-5.1 instance, indicates the need for security settings.

(N/Y)

security_settings.password Password field cleared before the parameter file is stored if running from cinstall.
installer.manifest Location of the DefaultInstallerClass.xml (the exported %Installer class); for example:

/home/user/Downloads/DefaultInstallerClass.xml

installer.manifest_parameters Location of installer manifest parameters.

SourceDir=/home/user/Downloads

installer.manifest_loglevel Specifies the log level of the manifest.

(0/1/2/3)

installer.manifest_logfile Specifies the log file name.

/manifests/CACHE-installManifestLog.txt

manager_source_code.available Indicates whether or not to install the manager utility source code.

(N/Y)

port_selection.superserver_port Superserver port number.

1972

port_selection.webserver_port Web server port number.

57772

port_selection.jdbcgateway_port Java Database Connectivity (jdbc) gateway port number.

62972

csp_gateway.configure Indicates whether or not to configure the CSP Gateway for an external web server.

(N/Y)

csp_gateway.configure_apache

(N/Y)

csp_gateway.web_server_type Type of existing web server for the CSP Gateway to use.

(Apache/SunOne/None)

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.

/etc/httpd/conf/httpd.conf

csp_gateway.apache_pid_file File that records the process id of the Apache web server daemon.

/usr/local/apache/logs/httpd.pid

csp_gateway.apache_use32bit Indicates whether 32–bit architecture is used for the Apache web server.

Y/N

csp_gateway.sunone_server Location of the Sun ONE server for the CSP Gateway to use.

/usr/netscape/server4/httpd-production

csp_gateway.directory Directory to contain the CSP Gateway files.
license_key.enter_key Indicates whether or not to install the key during installation.

N/Y

license_key.license_file Location of the key file information if the value of enter_key is Y.
agent.user_account Username for ISCAgent.

iscagent

agent.user_group Group name for ISCAgent.

iscagent

agent.install Indicates whether or not ISCAgent is installed.

(N/Y)

client_location.target_dir Target directory of a client-only installation.

test/CACHE

client_location.is_client_install Indicates whether or not it is a client install.

(N/Y)

install*

database_server

postinstall*

database_server

install* Used to initiate the installation of the SAMPLES database.

samples

samples.install Indicates whether or not to install the SAMPLES database.

(N/Y)

japanese_docs.install Indicates whether or not to install the Japanese documentation sources.

(N/Y)

install* Used to initiate the installation of the online documentation.

docbook

docbook.install Indicates whether or not to install the DOCBOOK database for the online documentation.

(N/Y)

install* Component name to install.

* 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:

  • dev_kit

  • odbc

  • cpp_binding

  • cpp_sdk

  • perl_binding

  • python_binding

  • engine_link_libraries

  • light_cpp_binding

  • addenda

  • install_confirmation

  • copyright

Special Considerations

This section describes the following topics:

Multiple Caché Instances

You can install and simultaneously run multiple instances (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.

Uninstalling 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.

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 chapter “Creating and Using an Installation Manifest” in this book.

FeedbackOpens in a new tab