OpenServer Kernel Personality (OKP)
for UnixWare 7.1.3
Release Notes

July 7, 2003

This document provides installation instructions and release notes for the OpenServer Kernel Personality (OKP) for UnixWare 7.1.3. After you read this document and install OKP, go to the UnixWare online documentation, served by DocView on http://hostname:8458, where hostname is the network name or IP address of your UnixWare system. Select OpenServer Kernel Personality to view the OKP documentation.

Contents

Getting Started with OKP
OKP Notes and Limitations

Getting Started with OKP

The OpenServer Kernel Personality (OKP) enables unmodified OpenServer 5 application programs to run on UnixWare 7 systems, allowing customers to take advantage of UnixWare 7 technologies without rewriting and recompiling existing applications.

OpenServer applications run in an OpenServer execution environment. Key OpenServer runtime utilities, libraries, system calls, internationalization and localization facilities, as well as terminal and console definitions are available in this environment.

System Requirements

OKP requires a UnixWare 7.1.3 system with one of the following software configurations:

For good OKP performance, we recommend a minimum of 128MB RAM, 400MB free disk space for OKP and the OpenServer image, and additional disk space for applications and application data. While OKP will run on any processor on which UnixWare will run, a faster processor will yield better overall system performance.

OKP is designed to work with OpenServer 5 Release 5.0.4 through 5.0.7 system images; see OpenServer System Image.

OKP Installation and Setup Overview

The general process for installing and setting up OKP to run your OpenServer applications is to:

  1. If you have an existing OpenServer system, install and configure required applications on the OpenServer system.

  2. Install the osrcompat set.

  3. Copy an OpenServer system image either from an existing OpenServer system or the OKP Full CD product.

  4. If you used the OKP Full CD product, log in to OKP to install and configure applications.

  5. Log in to UnixWare to create the required users and groups for your OpenServer applications.

  6. Log in to OKP and start your OpenServer applications.

The remainder of this document explains these steps in detail.

OpenServer System Image

Before you can use OKP, you must populate the OpenServer compatibility directory, /openserver, with the files and directories from an OpenServer 5 system.

This can be done during installation or afterwards from the command line, as summarized in the following figure.

If you have the CD-ROM version of the product and the appropriate license (see OKP Licensing), you can use the generic OpenServer 5.0.7 image provided on the CD. Using OKP with this image means that you will need to install your OpenServer application under OKP, after populating /openserver. Be aware that some restrictions on installing applications directly under OKP exist; see the section OKP Notes and Limitations in the online documentation on http://hostname:8458 under OpenServer Kernel Personality. for more information.

The recommended method for using OKP is to set up your applications on an existing OpenServer system and then copy the OpenServer system over to the UnixWare/OKP system. Migrating your application from a running OpenServer system has the advantage of preserving the application execution environment, eliminating the need to configure the application under OKP.

In some cases, this will be the only way to migrate an application to OKP. One example is any software that requires a license on installation; since OpenServer licensing is not supported by the UnixWare licensing software, such an application cannot be installed directly under OKP. Instead, it must be migrated from an OpenServer system.

Migration from an existing OpenServer system is accomplished in one of two ways:

Since the system image is large (at least 200MB, plus your applications and data), we recommend using osragent(1M) if you don't want to tie up your network transferring the system image. You can copy the image to tape or recordable CD on OpenServer for installation on UnixWare/OKP. This is also a useful way of keeping a backup copy of the OpenServer system for OKP.

Note that osragent(1M) must be copied from the UnixWare system to the OpenServer system, and then run on OpenServer to create the image.

The procedure in the section ``Installation and Getting Started'' includes instructions for performing these tasks.

OKP Licensing

There are two versions of the OKP product:

OKP Lite

Includes all the features of OKP except for the ability to load the OpenServer 5.0.7 image from the CD-ROM version of the OKP product. This license requires that you have an existing OpenServer system available to migrate to OKP.

OKP Lite consists of the OKP Package Set, osrcompat_060303_Lite.image, and the OKP Lite license, which is available free of charge. The OKP Package Set is approximately 140kb in size, and contains:

To use OKP Lite, download the OKP Package Set and install using the instructions under Installation and Getting Started. You will need to provide OKP license activation information. When prompted, use the following OKP license activation data: 

    License Number:     UWOKPLITE
    License Code:       dvxwknwt
OKP Full

If you want to use the Full version of OKP, you need to purchase a separately orderable license. This license permits the use of the complete OpenServer 5.0.7 product contained on the OKP CD ISO image.

The OKP CD ISO image, osrcompat_060303_Full.iso, contains the OKP Package Set and the OpenServer 5.0.7 product image. The OKP CD ISO image is approximately 280Mb in size.

To use OKP Full, download the OKP CD ISO image and install using the instructions under Installation and Getting Started. Enter the OKP license information for the license you purchased when prompted.

OKP Installation and Setup

Follow this procedure to install and begin using OKP:

  1. If you are using the OpenServer image provided on the optional OKP CD-ROM, skip this step.

    If you want to copy an OpenServer system image over the network from an existing OpenServer system, you must:

  2. Install the osrcompat package on UnixWare: 
       pkgadd -d device osrcompat

    Where device gives the location of the package. Use cdrom1, for example, for the first CD-ROM drive. If you have a package image (a file named osrcompat.image), use path/osrcompat.image for the device, where path is the full pathname to the file.

  3. The installation program checks for an OKP license. If it does not find a license on your system and you choose to Continue the installation, the License Manager is launched so you can enter an OKP license. Select License > Add in the License Manager and enter the license information. After you install the license, select Host > Exit to return to the OKP installation. See OKP Licensing for more information.

  4. After installing the software, the installation program asks if you want to populate the OpenServer compatibility directory. Choose one of the following by using the left and right arrow keys at the Migrate: prompt.

    From an existing networked OpenServer system
    Select this option and specify the system name of an OpenServer system on the network as the image source. The installation program will copy the image from that system over the network. if you have a problem accessing the OpenServer system, make sure you performed the required setup on the OpenServer system, as shown in Step 1. Note that the transfer of the system image can take significant time, and network errors can occur during the transfer.

    From a prepared OpenServer system image
    Select this option if you've already installed OKP on another UnixWare 7 system and have a system image available that you created using the osragent(1M) command. The installation program will ask for the location of the image on your UnixWare 7 system.

    From a generic OpenServer image on CD-ROM
    Select this option to populate the compatibility directory using the OpenServer image on the OKP CD-ROM media. Note that this option requires the full product license (see OKP Licensing).

    Defer migration for now
    Select this option to complete osrcompat installation now and populate the compatibility directory later.

  5. After the install is finished, reboot your system using a command like the following: 
       shutdown -i6 -g0 -y
    or the scoadmin shutdown manager.

  6. If you deferred the population of the OpenServer compatibility directory above, use one of these three methods to populate OKP with an OpenServer image:

    1. To load an image from an existing OpenServer system on the network:

      1. Use the migrate command to populate /openserver from the OpenServer system: 
           /usr/lib/okp/bin/migrate -h <system_name>

        If there is a problem accessing the OpenServer system, make sure you enabled root access as outlined in Step 1. The migrate command can take significant time and network errors can occur during the transfer.

      2. Once the migrate command completes successfully, run the import command to prepare the /openserver directory for use under OKP: 
           /usr/lib/okp/bin/import

    2. To use an image created on an OpenServer 5 system:

      1. Copy /usr/lib/okp/bin/osragent from the UnixWare 7/OKP system to the OpenServer system.

      2. On the OpenServer system:

        1. Enter (as root): 
             /tmp/osragent >/tmp/bigfile

        2. Copy bigfile via tape, writeable CD-ROM, or some other method, to a file system on the Unixware 7 system (for example, /var/pkg/spool). Be sure the file system has enough space to accommodate the image, which will be large (at least 200MB).

      3. On the Unixware 7 system (at a Unix shell), enter (as root): 
           /usr/lib/okp/bin/migrate -i /var/pkg/spool/bigfile

      4. Once the migrate command is successful, enter: 
           /usr/lib/okp/bin/import

    3. To use the OpenServer image provided on the OKP CD-ROM:

      1. Insert the OKP CD in the primary CD-ROM drive and enter: 
           mount /dev/cdrom/cdrom1 /mnt
   ls -l /mnt/okp_images
   /usr/lib/okp/bin/migrate -v -i /mnt/okp_images/<filename>

        Where <filename> is the name of the image file on the CD.

      2. Once the migrate command is successful, enter: 
           /usr/lib/okp/bin/import

    After you run migrate and import, you can begin using OKP.

  7. Use the UnixWare useradd(1M) command or the UnixWare scoadmin account manager to add the user accounts you will be using under OKP to the system. This includes any necessary user accounts that existed on the OpenServer system, as well as any accounts required by applications you are going to install under OKP.

    If you are moving a large number of accounts from an existing OpenServer system, you can use the ap utility to automate the transfer. There is a version of ap on both OpenServer and UnixWare. The basic process for using ap is to run it on OpenServer, copy the output to the UnixWare system, and run ap on UnixWare using the OpenServer account information as input. See the ap(1M) manual page on UnixWare, and the ap(ADM) manual page on OpenServer.

  8. To learn more about OKP, see the following sections in the UnixWare online documentation on http://hostname:8458 under OpenServer Kernel Personality:

Checking OKP Installation

Once installed, use the following command to confirm that the osrcompat set has completely installed. The system should respond with output similar to that shown in the example below: 

   # pkginfo -lc set osrcompat
      PKGINST:  osrcompat
         NAME:  OpenServer and Xenix Personality
     CATEGORY:  set
         ARCH:  IA32
      VERSION:  1.0.0
       VENDOR:  SCO
         DESC:  OpenServer and Xenix Personality for UnixWare
       PSTAMP:  scowl20030326194332
     INSTDATE:  May 30 2003 09:22 AM
       STATUS:  completely installed

If the STATUS field indicates anything other than completely installed, there was some problem during installation of the set. Re-install the set and record any error messages displayed.

Re-importing /openserver

Follow these instructions to remove an already imported /openserver directory from the system and repopulate it using the import command. Be sure that you no longer need any of the data currently under /openserver, or save a copy to backup media, before beginning.

  1. Run the unimport(1M) command: 
       /usr/lib/okp/bin/unimport

  2. Reboot: 
       shutdown -i6 -g0 -y

  3. Remove the /openserver directory: 
       rm -fr /openserver

  4. You can now repopulate the /openserver directory using the migrate and import commands, as shown in Step 6 in the previous section, ``Installation and Getting Started''.

Removing OKP

To completely remove OKP, the OpenServer system image, and all OpenServer applications and data from your system, enter the following commands, logged in as root.

  1. Make backup copies of any data needed from /openserver.

  2. Reboot the system into single user mode:

    1. Enter: 
      shutdown -i6 -g0 -y
    2. Interrupt the boot process at the UnixWare logo by pressing any key. At the [boot] prompt, type the following to boot the system into single user mode:

      INITSTATE=S
boot
  3. Remove the osrcompat set: 
    pkgrm osrcompat
  4. Run the unimport(1M) command: 
    /usr/lib/okp/bin/unimport

  5. Remove the /openserver directory: 
    rm -fr /openserver

OKP Notes and Limitations

This section lists the known problems that affect installation, or that were discovered too late to be included in the online documentation. See the OKP Notes and Limitations section in the online documentation on http://hostname:8458 under OpenServer Kernel Personality.

A: UnixWare 7.1.3 Known Problems

Unable to execute openserver command after migrate and import:

Errors have been observed when an rsh command is used in a pipe, as is done internally by the import(1M) command. While import does not return an error, executing the openserver(1) command returns:

UX: openserver: WARNING: unable to change directory into /unixware/
UX: openserver: ERROR: Exec error: Exec format error

To work around this error, run the import(1M) command again.
527265

B: OKP Known Problems

Installation: Cancelled Installation Leaves Partial Install

If you choose to cancel installation of the osrcompat set, or if the installation is aborted because a license was not found or entered, the okpdoc or xemul (or both) packages may still be installed, depending on when the install was cancelled. If xemul is installed, the kernel will be rebuilt on the next reboot. If you intend to re-install osrcompat, there is no need to remove these packages. If you do want to remove them, enter one or both of the following commands as root:

pkgrm -n okpdoc
pkgrm -n xemul

527924

Netscape: Harmless Error on Startup

When starting the OpenServer version of Netscape under OKP, one or more of the following errors may be displayed:

/opt/netscape/netscape: too big
/dev/rroot: not found

These error messages are harmless and can be ignored.
527927/527913

Removal: Reboot Into Single-User State Before Removing OKP

The unimport process performs a number of cleanup tasks, including attempting to remove any lingering mounted file systems whose content might be deleted unintentionally when the /openserver directory is removed. Some mounts may be left behind by the unimport command, however, if there are OpenServer processes running when unimport is executed. This can lead to data loss. To prevent this, the system should be rebooted into single user mode before running unimport, as shown in the section Removing OKP.


© Copyright 2003 The SCO Group, Inc. All rights reserved.