Skip to main content

Adding UNIX® Installation Packages to a Caché Distribution

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

FeedbackOpens in a new tab