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 o System Requirements o OKP Installation and Setup Overview o OpenServer System Image o OKP Licensing o OKP Installation and Setup o Checking OKP Installation o Re-importing /openserver o Removing 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: * Maintenance Pack 2 (or later) * Update Pack 1 and PTF9001 * Update Pack 2 (or later) 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. [See the HTML version of this file on the OKP web site or OKP Full CD for this 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: * Copy an image over the network from the existing OpenServer 5 system using migrate(1M). * Create an image on the running OpenServer 5 system using osragent(1M) copy it over to the OKP system, and then use migrate(1M) to place the image contents under /openserver. 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: o The OKP package o The Xenix emulation package o The OKP doc package 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: o Enable rsh on the OpenServer system for root access. To do this, edit the file /.rhosts on the OpenServer system, and add the system name (or IP address) of the UnixWare/OKP system to the file. Save your changes to the file. o Ensure that the files /etc/hosts.equiv and /.rhosts on the OpenServer system have 600 permissions: chmod 600 /.rhosts /etc/hosts.equiv o To test access to the OpenServer system, enter the following command as root on the UnixWare system. You should get the reply shown: # rsh sysname uname -s SCO_SV 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: A. 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 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 B. 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: a. Enter (as root): /tmp/osragent >/tmp/bigfile b. 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 C. 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/ Where 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: o See Installing and Running Applications under OKP for a description of how to install, run, and debug applications under OKP. o See OKP Features for a list OKP features and system services available in the OpenServer application environment. o See OKP Limitations for a list of limitations on applications running under OKP. ------------------------------------------------------------------------ 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. ------------------------------------------------------------------------ (c) Copyright 2003 The SCO Group, Inc. All rights reserved.