# hp Reliable Transaction Router
Installation Guide

Previous | Contents | Index

# Chapter 6
Full Installation on Sun Solaris

This chapter describes how to install Reliable Transaction Router on Sun Solaris systems. It includes steps for:

- Preparing for installation
- Installing RTR
- Completing RTR setup

# 6.1 Prepare for Installation

Before you start the installation, complete the preparation tasks outlined in this section.

## 6.1.1 Check Software Distribution Kit

RTR software is distributed on CD-ROM. Use the Bill of Materials (BOM) to check the contents of your RTR software distribution kit.

If your software distribution kit is damaged or incomplete, contact your HP representative.

## 6.1.2 Check Login Privileges

You must have superuser ( `root` ) privileges to install RTR software.

## 6.1.3 Check Required Hardware

To install RTR, you need the following hardware:

- Software distribution device (if installing from media)
  Locate the CD-ROM drive for the CD-ROM software distribution media. The CD booklet or the documentation for the CD-ROM drive you are using explains how to load CD-ROM media.
- Terminal
  You can use a hardcopy terminal, a video terminal, or a workstation to communicate with the operating system and respond to prompts from the installation procedure.
- Sun Server
  You must have a Sun Server that runs the Sun Solaris operating system.

See the RTR Software Product Description (SPD) for additional hardware requirements.

## 6.1.4 Check Required Software

One of the following is required:

- SunLink DNI Version 8.0
- TCP/IP as provided by the operating system

See the RTR Software Product Description (SPD) for additional software requirements.

## 6.1.5 Determine Which Subsets to Load

RTR has only one subset:

- rtrbase420
  RTR runtime and system management.

## 6.1.6 Check Required Disk Space

Table 6-1 lists the approximate disk space requirements for loading the RTR software subset. These requirements apply to the disks where you load RTR. The requirements are listed by directory for convenience if you are doing installations on systems where these directories are mount points for different disk partitions.

Table 6-1 RTR Subset Size (in Kilobytes) for Sun Solaris
Subset Title | Subset Name | /usr/opt/ | /rtr
--- | --- | --- | ---
RTR | rtrbase420 | 15500 | 8000
Total: |  | 23500 |

Using these disk space requirements, calculate the total values for the subsets you will load in each directory. You will also require at least 2MB disk space for the RTR journal, which defaults to `/rtrjnl` .

Compare the space required for the subset with the free space currently on the disks where RTR files will reside.

## 6.1.7 Check System Parameters

RTR has basic memory requirements. This section references setup instructions for the relevant system parameters.

### 6.1.7.1 Check Shared Memory Requirements

For information on how much shared memory to allocate, refer to the Reliable Transaction Router System Manager's Manual, RTR Shared Memory Sizing.

### 6.1.7.2 Check Virtual Memory Requirments

For information on how much virtual memory to allocate, refer to the Reliable Transaction Router System Manager's Manual, RTRACP Virtual Memory Sizing for All Systems.

### 6.1.7.3 TCP Services File

RTR uses TCP/IP port number 46000 for the network communication daemon `rtr rtrd` . On UNIX platforms, edit the `/etc/services` file to add the following line:

     rtracp 46000/tcp

This informs the system administrator that port number 46000/tcp is reserved for RTR. Note that the RTR daemon is started by the RTRACP, not by `inetd.`

## 6.1.8 Back Up Your System Disk

HP recommends that you back up your system disk before installing any software. For information about backing up your system disk, see the Sun Solaris documentation.

# 6.2 Install RTR

Install RTR from CD-ROM using the following procedure.

This procedure loads RTR files on to a disk belonging to the system where you perform the installation. When RTR is run, its executable images are mapped into memory on your system.

Installing RTR, including running the Installation Verification Procedure (IVP), takes approximately 10 to 15 minutes, depending on your media and system configuration.

Follow these steps to install RTR from CD-ROM:

1. Mount the CD-ROM on the appropriate disk drive.
2. Log in as superuser (login name `root` ) to the system where you will install RTR.
3. Make sure you are at the root (/) directory by entering the following command:

           # cd /

4. Use the `pkginfo` utility to check if you have a version of RTR already installed:

       # pkginfo -i | grep RTR

5. If RTR is already installed on your system, see Section B.4 for information on uninstalling RTR and removing related processes.
6. Specify the `/cd-rom` directory to be the mount point for the distribution file system on the drive. For example, if your drive is `rz0` , enter the following command:

           # mount -dr /dev/rz0c /CD-ROM

7. Install RTR from the CD-ROM directory where the kit is located. For example:

           # cd /cdrom/rtr_kit
           # pkgadd -d .

   Note By default, the IVP is not run. To run the IVP you must define the NONABI_SCRIPTS environment variable when starting the installation by issuing the following commands:
       # sh
       # NONABI_SCRIPTS=TRUE
       # pkgadd -d .

8. Select the package to install.
9. Respond to prompts during installation.
   You can accept the defaults for most questions from the `pkgadd` utility.
10. Decide whether to run the IVP.
11. Exit from the `pkgadd` utility.

## 6.2.1 Read the Release Notes

The Release Notes provide information for RTR that could not be included in the printed documentation. After installation the Release Notes are located in the directory /usr/opt/RTR420/hlp; you are advised to read the Release Notes before using RTR.

To read the release notes, navigate to the directory where RTR is installed and issue the following command:

    more rtr_relnotes.txt

## 6.2.2 Installation Example

This section explains the installation procedure prompts and displays.

### 6.2.2.1 Select Package

You must specify which package you want to load.

If the displayed package is the one you intended to choose, enter `1` .

If the displayed package is not the one you want to load, enter `q` .

### 6.2.2.2 Output During Package Loading

The installation procedure loads and verifies the selected RTR package.

The following example shows a display where the RTR package is being loaded from CD-ROM:

    # pkgadd -d .

    The following packages are available:

      1  rtr     Reliable Transaction Router
                 (sun4u) 420 (1)

    Select package(s) you wish to process (or all to process
    all packages). (default: all) [?,??,q]:  (2)

    Processing package instance <rtr> from </CDROM/rtr420/rtrkit>

    Reliable Transaction Router
    (sun4u) 420
    Hewlett-Packard Company
    Using </opt> as the package base directory.
    ## Processing package information.
    ## Processing system information.
    ## Verifying disk space requirements.
    ## Checking for conflicts with packages already installed.
    ## Checking for setuid/setgid programs.

    This package contains scripts which will be executed with
    super-user
    permission during the process of installing this package. (3)

    Do you want to continue with the installation of <rtr> [y,n,?] y

    Installing Reliable Transaction Router as <rtr>

    ## Executing preinstall script.
    (C) 1994, 2003 Hewlett-Packard Development Company, L.P.
    Confidential computer software. Valid license from HP and/or its
    subsidiaries required for possession, use or copying. Consistent
    with
    FAR 12.211 and 12.212, Commercial Computer Software, Computer
    Software
    Documentation, and Technical Data for Commercial Items are licensed
    to
    the U.S. Government under vendor's standard commercial license.

    This kit will only run on Sun Solaris 2.6 and higher.
    Installation should complete in approximately 1 minute.

    Hit any key to continue....
    ## Installing part 1 of 1. (4)
    /opt/rtr/RTR420/bin/rtr
    /opt/rtr/RTR420/bin/rtr_r
    /opt/rtr/RTR420/bin/rtr_remote
    /opt/rtr/RTR420/bin/rtr_rqif
    /opt/rtr/RTR420/bin/rtr_snapshot.sh
    /opt/rtr/RTR420/examples/ABCBook/ABCBook.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCBook.h
    /opt/rtr/RTR420/examples/ABCBook/ABCCHandlers.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCCHandlers.h
    /opt/rtr/RTR420/examples/ABCBook/ABCCommon.h
    /opt/rtr/RTR420/examples/ABCBook/ABCMagazine.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCMagazine.h
    /opt/rtr/RTR420/examples/ABCBook/ABCOrder.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCOrder.h
    /opt/rtr/RTR420/examples/ABCBook/ABCOrderProcessor.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCOrderProcessor.h
    /opt/rtr/RTR420/examples/ABCBook/ABCOrderTaker.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCOrderTaker.h
    /opt/rtr/RTR420/examples/ABCBook/ABCSClassFactory.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCSClassFactory.h
    /opt/rtr/RTR420/examples/ABCBook/ABCSHandlers.cpp
    /opt/rtr/RTR420/examples/ABCBook/ABCSHandlers.h
    /opt/rtr/RTR420/examples/ABCBook/README.html
    /opt/rtr/RTR420/examples/ABCBook/SAMPLE1.COM
    /opt/rtr/RTR420/examples/ABCBook/SAMPLE1.MMS
    /opt/rtr/RTR420/examples/ABCBook/Sample1.cpp
    /opt/rtr/RTR420/examples/ABCBook/Sample1.dsp
    /opt/rtr/RTR420/examples/ABCBook/Sample1.dsw
    /opt/rtr/RTR420/examples/ABCBook/Sample1.h
    /opt/rtr/RTR420/examples/ABCBook/Sample1.mk
    /opt/rtr/RTR420/examples/ADG/adg_client.c
    /opt/rtr/RTR420/examples/ADG/adg_header.h
    /opt/rtr/RTR420/examples/ADG/adg_server.c
    /opt/rtr/RTR420/examples/ADG/adg_shared.c
    /opt/rtr/RTR420/examples/IVP/rtr_ivp_osf.sh
    /opt/rtr/RTR420/examples/IVP/rtrreq.c
    /opt/rtr/RTR420/examples/IVP/rtrsrv.c
    /opt/rtr/RTR420/hlp/copyright.txt
    /opt/rtr/RTR420/hlp/license.txt
    /opt/rtr/RTR420/hlp/rtr.hlb
    /opt/rtr/RTR420/lib/rtr.h
    /opt/rtr/RTR420/lib/rtr_v2.h
    /opt/rtr/RTR420/lib/rtrapi.h
       .
       .
       .
    /opt/rtr/RTR420/mon/*.mon  files
       .
       .
       .
    /opt/rtr/RTR420/shlib/librtr.so
    /opt/rtr/RTR420/shlib/librtr_r.so
    /opt/rtr/RTR420/shlib/librtrapicpp.so
    /opt/rtr/RTR420/shlib/librtrapicpp_r.so
    /opt/rtr/RTR420/wbi/graphics/blank.jpg
       .
       .
       .
    /opt/rtr/RTR420/wbi/graphics/*.gif files
       .
       .
       .
    /opt/rtr/RTR420/wbi/rtr_accept_node.js
    /opt/rtr/RTR420/wbi/rtr_command_displ.js
    /opt/rtr/RTR420/wbi/rtr_command_form.js
    /opt/rtr/RTR420/wbi/rtr_create_fac.js
    /opt/rtr/RTR420/wbi/rtr_create_jou.js
    /opt/rtr/RTR420/wbi/rtr_create_par.js
    /opt/rtr/RTR420/wbi/rtr_create_tree.js
    /opt/rtr/RTR420/wbi/rtr_create_tree_sub.js
    /opt/rtr/RTR420/wbi/rtr_delete_fac.js
    /opt/rtr/RTR420/wbi/rtr_delete_par.js
    /opt/rtr/RTR420/wbi/rtr_extend_fac.js
    /opt/rtr/RTR420/wbi/rtr_left_frame.html
    /opt/rtr/RTR420/wbi/rtr_log_displ.js
    /opt/rtr/RTR420/wbi/rtr_main.html
    /opt/rtr/RTR420/wbi/rtr_modify_jou.js
    /opt/rtr/RTR420/wbi/rtr_monitor.js
    /opt/rtr/RTR420/wbi/rtr_set_btx.js
    /opt/rtr/RTR420/wbi/rtr_set_fac.js
    /opt/rtr/RTR420/wbi/rtr_set_lnk.js
    /opt/rtr/RTR420/wbi/rtr_set_log.js
    /opt/rtr/RTR420/wbi/rtr_set_par.js
    /opt/rtr/RTR420/wbi/rtr_trim_fac.js
    /opt/rtr/RTR420/wbi/smm.html
    /opt/rtr/RTR420/wbi/smm_contents.html
    /opt/rtr/RTR420/wbi/smm_contents_001.html
    /opt/rtr/RTR420/wbi/smm_contents_002.html
    /opt/rtr/RTR420/wbi/smm_index.html
    /opt/rtr/RTR420/wbi/smm_index_001.html
    [ verifying class <none> ]
    ## Executing postinstall script. (5)
    (C) 1994, 2003 Hewlett-Packard Development Company, L.P.

    Confidential computer software. Valid license from HP and/or its
    subsidiaries required for possession, use or copying. Consistent
    with FAR 12.211 and 12.212, Commercial Computer Software, Computer
    Software Documentation, and Technical Data for Commercial Items
    are licensed to the U.S. Government under vendor's standard
    commercial license.

        directory /rtr -> /var/opt/rtr created

      Starting     Reliable Transaction Router V4.2  for SunOS
      Installation Verification Procedure

    WARNING: This is not a first time install.
    WARNING: Please ensure that you have terminated *all* existing
    WARNING: rtr processes and rtr applications before continuing.(6)
    See man fuser or lsof to identify processes using
    /usr/*lib/librtr*.so

    RTR will find and reuse any existing journal files in the
    top level rtrjnl directory on each suitable filesystem, and will
    reuse any existing shared memory segment associated with
    /rtr/RTRENVPS
    Normally this is intended and should not cause any problems.

    WARNING: Any existing journal will be used and modified, otherwise
    WARNING: a new journal will be created on the default filesystem. (7)
    WARNING: Facilities RTR_IVP_FACILITY and RTR$DEFAULT_FACILITY
    will be created.
    WARNING: Result may be affected by size and contents of
    any existing journal.
    WARNING: The sample client and server do not necessarily
    complete if they
    WARNING: encounter previously journalled transactions
    for these facilities.

    NOTE: The following question is ignored in a non-interactive
    install
    NOTE: unless NONABI_SCRIPTS=TRUE, see man pkgadd for details...

    You may run the IVP separately from the installation
    procedure by executing the file:
    /opt/rtr/RTRxxx/examples/IVP/rtr_ivp_osf.sh

    Would you like to abort the IVP? (y/n)  IVP aborted (8)

    Installation of <rtr> was successful.

    The following packages are available:

      1  rtr     Reliable Transaction Router
                 (sun4u) 420

    Select package(s) you wish to process (or all to process
    all packages). (default:all) q (9)
    #

1. Lists kit name and number.
2. Select package to install.
3. Warning about use of superuser privileges.
4. Start of first installation segment, followed by list of files installed.
5. Indication of postinstallation processing.
6. Warning for reinstallation of RTR.
7. Warning about overwriting existing journal.
8. Prompt for decision to run IVP.
9. Enter `q` to exit from utility.

The "Verifying" message that precedes the postinstall message is a check to see that the files are copied correctly; it is not an Installation Verification Procedure (IVP) message.

Section 6.2.4 explains how to run the IVP after installation, and Section 6.2.5 explains how to delete old RTR subsets before installing a new version of RTR.

## 6.2.3 Stop the Installation

To stop the installation procedure at any time, press Ctrl/C. You must then delete files created up to this point interactively. The directories and files created during RTR installation are listed in the following file (on your CD-ROM):

    /rtr40/kit/instctrl/rtrbase420.inv

## 6.2.4 Run the Installation Verification Procedure

After installing RTR, you can run the Installation Verification Procedure (IVP) independently to verify that the software is available on your system. You might also want to run the IVP after a system failure to be sure that users can access RTR.

Note that the Installation Verification Procedure (IVP) requires a working C language compiler to run.

The RTR IVP verifies the installation as follows:

- Starts RTR
- Creates an RTR journal
- Creates an RTR facility
- Stops RTR
- Compiles and links the example client and server programs

To run the IVP after an installation, enter the following command:

    # /opt/rtr/RTRxxx/examples/IVP/rtr_ivp_osf.sh

### 6.2.4.1 Sample IVP Output

.
.
.

    Would you like to abort the IVP? (y/n) n
    IVP continuing ...

      keep any existing log file settings (RTR_DBG not set)
      starting RTR . . .
      creating a journal, if not already created . . .
      creating test facility . . .
      stopping RTR.

           Reliable Transaction Router V4.2 for SunOS

      Installation Verification Procedure successful

    The following packages are available:

      1 rtr      Reliable Transaction Router
                 (sun4u) 420

    Select package(s) you wish to process (or 'all' to process
    all packages). (default: all) [?,??,q]: q
    #

If the verification process fails, look in the
`/var/adm/smlogs/fverify.log` file for information to help diagnose the problem.

## 6.2.5 Delete RTR from Your System

If you must remove a version of Reliable Transaction Router from your system, delete each subset that you previously installed.

To delete subsets:

1. Log in as superuser (login name `root` ).
2. Make sure you are at the root directory (/) by entering the following command:

           # cd /

3. Enter the following form of the `pkginfo` command:

           # pkginfo -i rtr

4. Look for the word "installed" in the listing produced, and then delete the installed subsets. For example:

       # pkgrm rtr

## 6.2.6 Display Documentation from CD-ROM

The Reliable Transaction Router documentation is provided on the Reliable Transaction Router CD-ROM kit in hypertext (.html) file format. You can display the hypertext files on your workstation using an HTML browser such as Netscape or Internet Explorer.

# 6.3 Complete RTR Setup

This section explains how to make RTR ready for use after installation on Sun Solaris.

Requirements for Application Permissions If the RTR executable is modified after installation to no longer be `suid` root or the mode of the `/rtr` directory is changed, an application process (for example a client) can encounter a fatal error (Unable to locate a socket) when the client process finds it cannot create an `rtr_ipc_sock_*` file for the process ID (pid) in the `/rtr` directory. To avoid this, ensure that application processes run with user and group IDs that have access permission to create and remove files in this directory.

## 6.3.1 Check Installed Files

To see the list of files installed on your system, use the following command:

    % pkginfo i rtr

## 6.3.2 Run RTR

To run RTR, enter the following command at the system prompt:

     % RTR
     RTR>

You can then enter commands at the RTR prompt to configure facilities and partitions, and run applications that use RTR.

### 6.3.2.1 Configure RTR Facilities and Partitions

For information on configuring RTR facilities and setting up partitions, refer to the Reliable Transaction Router Getting Started manual and the Reliable Transaction Router System Manager's Manual.

## 6.3.3 Install and Run Applications

Once applications that use RTR have been designed and tested, they can be deployed on the systems configured for use with RTR. For information on designing applications, refer to the Reliable Transaction Router Application Design Guide; for information on deployment and use, refer to the Reliable Transaction Router System Manager's Manual.

Application programming interfaces that can be used to write transaction processing applications used with RTR are described in the Reliable Transaction Router C++ Foundation Classes manual and the Reliable Transaction Router C Application Programmer's Reference Manual.

Previous | Next | Contents | Index