Getting Started with OKP

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.

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 Limitations'' for more information.

The recommended method for using OKP is to set up your applications on an existing OpenServer system and then copying 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

OKP is available with two licenses:

Full

This license unlocks all the features of OKP.

Lite

This license unlocks all the features of OKP except for the ability to load the OpenServer 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.

Installation and Getting Started

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:

   • 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.

   • Ensure that the files /etc/hosts.equiv and /.rhosts on the OpenServer system have 600 permissions:

        chmod 600 /.rhosts /etc/hosts.equiv
     

   • 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 you do not have one, 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. Otherwise, select Cancel installation.

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:
      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.

      1. 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. See ``Installing and Running Applications under OKP'' for a description of how to install, run, and debug applications under OKP.

   See ``OKP Features'' for a list OKP features and system services available in the OpenServer application environment.

   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 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. Remove the osrcompat set:

      pkgrm osrcompat
   

2. Reboot the system:

      shutdown -i6 -g0 -y
   

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

4. Remove the /openserver directory:

      rm -fr /openserver