Skip to main content
Previous section

Adding UNIX® Installation Packages to an InterSystems IRIS Distribution

This appendix describes how to add a new UNIX® installation package to an existing InterSystems IRIS® data platform distribution. It is presented in the form of a tutorial in which we create a simple package that copies additional files into the InterSystems IRIS instance directory.

Note:

Because install packages are implemented through UNIX® shell scripts, you can also write packages that perform much more complex operations.

Tutorial

Suppose we have written an InterSystems Callout shared library (see the “Creating an InterSystems Callout Library” chapter in Using the Callout Gateway) to connect to an imaging device named Foo9000. We compile this library as libfoo9000.so and want to install it with InterSystems IRIS. 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 is stored in a configuration file in the InterSystems IRIS instance’s install-dir\mgr directory.

We start with an existing InterSystems IRIS kit:

~/kit:>ls
irisinstall   cplatname docs  lgpl.txt NOTICE
copyright.pdf dist   kitlist LICENSE package
Copy code to clipboard

... and our compiled library (libfoo9000.so):

~/lib:>ls
libfoo9000.so
Copy code to clipboard

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 .
Copy code to clipboard

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
Copy code to clipboard

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 install-dir\mgr directory.

  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."
Copy code to clipboard

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.
Copy code to clipboard

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
Copy code to clipboard

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
Copy code to clipboard

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 irisinstall, irisinstall_client or irisinstall_silent scripts (as described in InterSystems IRIS 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 InterSystems IRIS Installation Parameter File Variables table at the end of this appendix.

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
Copy code to clipboard

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
Copy code to clipboard

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 processes ours. In this case, we want our library to be installed and configured any time an InterSystems IRIS 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
Copy code to clipboard

As you can see, many packages are required to create a server installation, but now, when we run irisinstall, our package (foo9000) is configured and installed:

~/kit:>sudo ./irisinstall
Your system type is 'SuSE Linux Enterprise Server 10 (x64)'.
Currently defined instances:
IRIS instance 'TRWTURBO'
directory: /home/woodfin/TRWTURBO
versionid: 2018.1.0.508.0
conf file: iris.cpf (SuperServer port = 51773, WebServer = 57785)
status:  crashed, last used Sat Sep 22 08:37:32 2018
Enter instance name: TRWPACK1
Do you want to create IRIS 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
Copy code to clipboard

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.

InterSystems IRIS Installation Parameter File Variables
Variable name Description
(Valid values) or Example
dist.source_dir Source directory of the installation media.
/iriskit
legacy_dist.source_dir For legacy purposes, source directory of the installation media.
/iriskit
product_info.version InterSystems product version number.
2018.1.0.100.0
product_info.name Name of InterSystems product.
InterSystems IRIS
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/IRIS
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.
IRIS
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 InterSystems IRIS registry directory (must be on a local filesystem).
/usr/local/etc/irissys
server_location.iris Directory in which iris resides during installation.
/iriskit/dist/lnxrhx64/bin/shared/iris
server_location.is_dr_mirror Whether this instance is a disaster recovery (DR) mirror member.
(N/Y)
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.iris_user Effective user for the InterSystems IRIS superserver
irisusr
security_settings.iris_group Effective group for InterSystems IRIS.
irisusr
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 is cleared before the parameter file is stored.
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 irisinstall.
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.
(-1/0/1/2/3)
installer.manifest_logfile Specifies the log file name.
/manifests/IRIS-installManifestLog.txt
port_selection.superserver_port Superserver port number.
51773
port_selection.webserver_port Web server port number.
52773
port_selection.jdbcgateway_port Java Database Connectivity (jdbc) gateway port number.
62972
csp_gateway.configure Indicates whether or not to configure the Web Gateway for an external web server.
(N/Y)
csp_gateway.web_server_type Type of existing web server for the Web 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 Web Gateway to use.
/usr/netscape/server4/httpd-production
csp_gateway.directory Directory to contain the Web 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/IRIS
client_location.is_client_install Indicates whether or not it is a client install.
(N/Y)
install*
database_server
postinstall*
database_server
japanese_docs.install Indicates whether or not to install the Japanese documentation sources.
(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

  • engine_link_libraries

  • light_cpp_binding

  • addenda

  • install_confirmation

  • copyright