Chapter 2 Installing and Removing SunVTS

This chapter describes how to install and remove the SunVTS diagnostic program.

• "SunVTS Packages"

• "Installing SunVTS"

• "To Set Up Access to the SunVTS Man Pages"

• "To Perform Additional Setup When SunVTS Is Installed in a Directory Other Than /opt"

• "SunVTS Security"

• "Additional Instructions for Localized Environments"

• "Removing SunVTS"

• "Adding a Custom Test"

SunVTS Packages

The SunVTS software is installed from the packages shown in Table 2-1.

SunVTS packages are located on the Sun Computer Systems Supplement CD that ships with the Solaris release.

Installation Requirements

• The Solaris 9 operating environment must be installed (with the End-user cluster at minimum), and booted to multi-user level (run level 3).

• You must be superuser.

• There must be at least 62 Mbytes of available disk space in the partition where SunVTS will reside. The /opt directory is the default installation location.

Refer to Appendix B, Frequently Asked Questions for information about which revisions of SunVTS are supported on different Solaris operating environment releases.

Installing SunVTS

There are several utilities available for installing packages. This chapter describes how to use the pkgadd utility to load SunVTS from a local CD-ROM drive. For information on how to install packages using other installation methods, see the Solaris 9 Sun Hardware Platform Guide.

To Install SunVTS With the pkgadd Command

1. Login to the system and become superuser:

   % su

2. Check to see if any SunVTS packages are currently installed on the system:

   # pkginfo -c sunvts

   • If the system does not display anything then no SunVTS packages are installed and you can proceed with the installation.

   • If you see any messages such as the following message, then SunVTS is installed and you should remove the existing SunVTS software before proceeding. See "Removing SunVTS".

     system SUNWvts SunVTS

3. Load the Software Supplement for the Solaris Operating Environment CD (the Supplement CD) into the CD-ROM drive.

   Volume Manager automatically mounts the CD.

4. Install SunVTS using pkgadd as shown in one of the examples below.

   • The following command installs SunVTS in the default directory (/opt):

     # pkgadd -d /cdrom/cdrom0/SunVTS_5.0/Product SUNWvts

   • The following command prompts you to enter the directory where SunVTS will reside instead of using the default (/opt) directory.

     # pkgadd -a none -d /cdrom/cdrom0/SunVTS_5.0/Product SUNWvts

     ---

     Note -

     If you install SunVTS in a directory other than the default (/opt) directory, you must set the VTS_PM_PATH variable before you use the SunVTS CDE interface. See "To Perform Additional Setup When SunVTS Is Installed in a Directory Other Than /opt".

     ---

5. Answer the installation questions.

   You are asked if you want to enable the Kerberos-based, Sun Enterprise Authentication Mechanism (SEAM) security which provides the highest level of SunVTS security. You should only enable this if you have the SEAM software installed and the SEAM server and clients configured in your networked environment. Refer to "SunVTS Security". You can always answer no to this question, even when SEAM is configured in your environment.

   If you choose to run SunVTS with SEAM security, use the following SEAM assignments:

   • Principal--set to sunvts

   • Complete Service Name--set to sunvts@host, where host is the fully qualified domain name of the host where the SunVTS kernel is running.

   ---

   Note -

   You may see installation messages that inform you of other package requirements. These notifications do not prevent the successful installation or execution of SunVTS. The following steps explain how to install these other packages.

   ---

6. Install the SunVTS supporting packages that are appropriate for your configuration. (See "SunVTS Packages" for more details.)

   Example:

   # pkgadd -d /cdrom/cdrom0/SunVTS_5.0/Product SUNWvtsx SUNWvtsmn SUNWvtsol

   ---

   Note -

   Type -a none option again if you used it for the installation of SUNWvts.

   ---

   ---

   Note -

   The SUNWvtsx package only installs on systems that have the 64-bit Solaris Operating Environment installed.

   ---

   ---

   Note -

   The configd packages (SUNWeswsa, SUNWsycfd, SUNWesnta, and SUNWeswga) are no longer needed, and no longer supplied, for physical mapping support.

   ---

7. Verify the presence of the packages:

   # pkginfo SUNWvts SUNWvtsx SUNWvtsmn SUNWvtsol system SUNWvts SunVTS system SUNWvtsmn SunVTS Man Pages system SUNWvtsx 64-bit SunVTS

To Set Up Access to the SunVTS Man Pages

The SunVTS man pages are installed in the SunVTS_install_dir/man directory (/opt/SUNWvts/man by default). To access them, add this directory to your MANPATH shell variable in the initialization file that corresponds to your login shell (usually .profile for the Bourne and Korn shells or .login for the C shell).

The steps that follow assume that the default SunVTS installation directory (/opt) was used when the SunVTS packages were installed. If this is not the case, adjust the instructions to use the directory where the man pages were installed.

1. Using an editor, add the SunVTS man directory (/opt/SUNWvts/man by default) to the MANPATH variable in the appropriate initialization file.

   Bourne, Korn Shell example:

   MANPATH=/usr/share/man:/usr/man:/opt/SUNWvts/man;export MANPATH

   C shell example:

   setenv MANPATH /usr/share/man:/usr/man:/opt/SUNWvts/man

2. Have the shell read the modified initialization file by sourcing it (with the . [dot] or source command) or log out and log back in.

3. Verify that the SunVTS man directory is part of the MANPATH variable:

   # echo $MANPATH /usr/share/man:/usr/man:/opt/SUNWvts/man

   ---

   Note -

   For more information about customizing a user's work environment, shell variables, and initialization files, refer to your Solaris system administration guides.

   ---

To Perform Additional Setup When SunVTS Is Installed in a Directory Other Than /opt

When you install SunVTS in a directory other than the default directory (/opt), you must set the VTS_PM_PATH environment variable before you can use the SunVTS CDE user interface. This variable is used to locate graphic elements in the SunVTS CDE interface.

The VTS_PM_PATH variable is not required if SunVTS is installed in the default directory (/opt).

1. Using an editor, open the appropriate initialization file such as .profile (for the Bourne or Korn shells) or .login (for the C shell).

2. Add the VTS_PM_PATH variable as shown:

   Bourne or Korn Shell example:

   VTS_PM_PATH=your_base_install_dir/SUNWvts/bin/pm;export VTS_PM_PATH

   C shell example:

   setenv VTS_PM_PATH your_base_install_dir/SUNWvts/bin/pm

3. Have the shell read the modified initialization file by sourcing it (with the . [dot] or source command) or log out and log back in.

SunVTS Security

SunVTS has two security mechanisms that you can choose from:

• Basic Security--a local file is maintained that lists the valid users, groups, and hosts that are permitted to use SunVTS. This level of security does not provide secure network authentication and should not be used in an environment where network security is an issue.

• SEAM Security--uses the Sun Enterprise Authentication Mechanism^TM (SEAM) to provide secure user authentication, data integrity and privacy, for transactions over networks using a Kerberos V5 technology.

The SunVTS installation process prompts you to specify which security mechanism you want to use. You must use one or the other, and the SEAM security implementation is the default if you press the return key through the installation questions.

Basic Security

The SunVTS user interface (vtsui, vtsui.ol,and vtstty) must connect to the SunVTS kernel (vtsk) before it can be used to control testing. The SunVTS kernel selectively accepts "connect to" requests from the SunVTS interface based on entries in the SunVTS_install_dir/bin/.sunvts_sec file. Connection permission is governed by three categories in this file as follows:

• HOSTS--if the requesting user is on a host that belongs to the HOSTS category, then this request is granted without any authentication.

• GROUPS--if the requesting user is a member in a group that is a member of GROUPS category, then the user interface will prompt the user for a password. The SunVTS kernel compares this password against the password database on the system under test (SUT). If the password does not match, or if the user is not on the list, then the connection is rejected.

• USERS--if the requesting user is a member of the USER category, then the user interface will prompt the user for a password. The SunVTS kernel compares this password against the password database on the SUT. If the password does not match, or the user is not on the list, then the connection is rejected.

A plus (+) entry in one of these categories means all hosts, groups, or users, are trusted.

The user password needed for authentication is the same password used to log in to the system under test.

The check for connection permission starts with the HOSTS category, then the GROUP category, and finally, the USERS category. A connection is granted as soon as the connection request matches an entry.

If a security file entry is invalid or if there is no entry in the file, all access except root is denied on the local machine. However, you can correct an entry in this file even while the SunVTS kernel is running.

When you specify the -e option while starting the SunVTS kernel, the kernel accepts "connect to" requests from any host, regardless of the entries in the .sunvts_sec file.

As of SunVTS 3.1, the .sunvts_sec file, by default, is configured for root on the system under test. All other "connect to" requests are rejected.

The .sunvts_sec file is bypassed if you enable the SEAM security.

The following shows the contents of the default .sunvts_sec file.

Code Example of the Security File (.sunvts_sec):

#This file should be <SunVTS 5.0 install directory>/bin/.sunvts_sec
#
#Any line beginning with a # is a comment line
#
# Trusted Hosts entry
# One hostname per line.
# A "+" entry on a line indicates that
ALL hosts are Trusted Hosts.
# No password authentication is done.
# The line with the label HOSTS: is required to have the
list of hosts
#
HOSTS:
#+
#host1
#host2
#
# Trusted Groups entry
# One groupname per line.
# A "+" entry on a line indicates that
ALL groups are Trusted Groups.
# User password authentication is done.
# The line with the label GROUPS: is required to have the
list of groups
#
GROUPS:
#group1
#
# Trusted Users entry
# One username per line.
# A "+" entry on a line indicates that
ALL users are Trusted Users.
# User password authentication is done.
# The line with the label USERS: is required to have the
list of users.
USERS:
root
#user1
#user2

SEAM Security

To use SEAM-based security with SunVTS, you must have the following:

• The complete SEAM 1.0.1 client/server application must be installed and running in your network environment.

• The systems for which you install SunVTS must have, at minimum, the SEAM 1.0.1 client software installed.

• Select the SEAM-based security (Kerberos V5) choice during the SunVTS installation.

Refer to the following documents for more information on SEAM: o Sun Enterprise Administration Mechanism 1.0.1 Guide o SEAM 1.0.1 Installation and Release Notes These documents are part of the Sun Enterprise Authentication Mechanism 1.0.1 AnswerBook Collection, and available at http://docs.sun.com. The SEAM software is part of the Solaris release.

The SunVTS SEAM security system is based on Kerberos V5 technology, which revolves around the concept of a ticket. A ticket is a set of electronic information that serves as identification for a user or a service. When you connect to another host through SunVTS, you transparently send a request for a ticket to a Key Distribution Center (KDC), which accesses a database to authenticate your identity. The KDC returns a ticket granting you permission to access the other machine. "Transparently" means that you do not need to explicitly request a ticket; it happens in the background as part of the remote connection. No user password is transmitted in the network. Only the authenticated client can get a ticket for a specific service; another client cannot gain access under an assumed identity.

If you choose to run SunVTS with SEAM security, use the following SEAM assignments:

• Principal--set to sunvts

• Complete Service Name--set to sunvts@host, where host is the fully qualified domain name of the host where the SunVTS kernel is running.

Controlling SunVTS Security

To Control SunVTS Security mode at Installation Time

The best time to establish the SunVTS security mode is during the SunVTS installation.

1. Decide which level of security you want to use with SunVTS.

   If you decide to use the SEAM security (highest level of security), make sure that your system is running SEAM.

2. Install SunVTS as described in "Installing SunVTS".

   The installation program asks you if you want SEAM security enabled. Answer accordingly:

   • Yes (the default)--The Kerberos SEAM security is enabled for SunVTS. No additional action is required to administer SunVTS security. SunVTS uses the authentication as defined in the SEAM software configuration in your network environment to grant and deny access to SunVTS. Do NOT select this security scheme if you do not have the SEAM software installed and configured in your network environment.

   • No--The basic security file is used, and SEAM is not enabled. When the installation is complete, you can access SunVTS as superuser on the system under test, or modify the .sunvts_sec file to authorize other users.

To Switch SunVTS Security After Installation

If you need to switch the security from SEAM to basic, or vice-versa, after you have installed SunVTS, follow these steps:

1. Become superuser.

2. Make sure that SunVTS is not started.

3. Change directories to the SunVTS binary directory:

   # cd /opt/SUNWvts/bin

   ---

   Note -

   If SunVTS is installed in a directory other than /opt, adjust your references accordingly.

   ---

4. With an editor, open the .sunvts_sec_gss file.

   This file contains one line that is appended with one of the following:

   • ON--indicates SEAM security is enabled.

   • OFF--indicates SEAM security is disabled, and basic security is used.

5. Change the ON (or OFF) value to the opposite value, save the change, and quit the editor.

   ---

   Note -

   The ON and OFF values are case sensitive. Make sure you specify them using capital letters.

   ---

6. Start SunVTS.

   The security mechanism that you specified is enabled.

SunVTS Environmental Variables

Use environmental variables to control certain aspects of SunVTS as described in Table 2-2. Except for the MANPATH variable, you only use these variables when you need to alter the default characteristics of SunVTS.

Additional Instructions for Localized Environments

SunVTS software is available in English, and is Internationalization (I18N) compliant, which means it is structured in a way that a user who is familiar with internationalization can take advantage of this feature to run SunVTS in a localized environment.

In a localized environment, you can run SunVTS in English or with localized fonts. Perform one of the two following procedures based on how you want SunVTS to run.

To Run SunVTS in English, in a Non-English Environment

Set the LANG variable to English before you start SunVTS. The following is an example using the C shell:

1. Set the LANG variable:

   # setenv LANG C

To Set Up the GUI resource File for Localized Environments

1. As superuser, create a directory as follows:

   # mkdir -p /opt/SUNWvts/lib/locale/LANG/app-defaults

   Where LANG is the language code (for example, ja for Japan EUC, or fr for French) for the language that you are using.

2. Copy the SunVTS Xresource (Vtsui) file into the directory you just created:

   # cp /opt/SUNWvts/lib/Vtsui /opt/SUNWvts/lib/locale/LANG/app-defaults

   ---

   Note -

   The example above is based on installing SunVTS in the default (/opt) directory. If SunVTS is installed in different directory, adjust the pathnames accordingly.

   ---

3. Customize the font definitions in the Vtsui file to accommodate font specifications required by your localized environment.

Adding a Custom Test

Developers can add their own custom tests to the SunVTS environment. This book does not describe custom test development, but does list the tasks necessary to add a custom test into the SunVTS environment.

To Add a Custom Test

1. Copy your custom test binary to the SunVTS bin directory based on the 32-bit or 64-bit functionality of your binary test:

   • 32-bit: /opt/SUNWvts/bin

   • 64-bit: /opt/SUNWvts/bin/sparcv9

2. Modify one of the following .customtest files based on the 32-bit or 64-bit functionality of your binary test:

   • 32-bit: /opt/SUNWvts/bin/.customtest

   • 64-bit: /opt/SUNWvts/bin/sparcv9/.customtest

   The format of the .customtest file is described in "The .customtest File Format".

3. Restart SunVTS or reprobe the system.

When invoked, SunVTS displays the custom test in the SunVTS user interface.

The .customtest File Format

The .customtest file defines the test options and the default option values for your custom test. The tester can change these options using the option dialog boxes through the SunVTS user interface. However, the Reset button returns the options to the default settings as defined in the .customtest file.

Each line in this file is made up of two or more fields that are separated by a semicolon where:

• The first field is the label or device name (mandatory field).

• The second field is the test name (mandatory field).

• The third field is an option line (optional field). If used, this field must be in the format specified.

• The fourth field is used if the test is scalable. If used, append the keyword SCA to this field.

Examples:

• To add a test with no options:

  % your_label_name;your_test_name

• To add the scalability option, append the keyword SCA:

  % your_label_name;your_test_name;SCA

• To custom build an option menu, add an option specification:

  % Option_Name<Option_Type|Value|Default_Value|Command_Line_Option>

• To specify more than one option, separate each option by a comma:

  % label_name;test_name;Numeric<NUMERIC|0,100|50|numeric>, Exc_Choice<EXC_CHOICE|Top,Middle,Bottom|Middle|exc_choice>, Inc_Choice <INC_CHOICE|Left,Center,Right|Left+Center+Right|inc_choice>, Toggle<TOGGLE|This,That|This|toggle>, Text<TEXT|20|Type_Here|text>, Slidebar<SLIDEBAR|0,10|5|slidebar>, Errors<CYCLE|Yes,No|No|errors>, Cycle<CYCLE|First,Second,Third|First|cycle>;SCA

SunVTS invokes the above test as follows:

% ./test_name -s[vq..] [-i n] 

-o dev=user[0,1..],Command_Line_Option=Value...

You cannot use the .customtest file when a test has a probe attached. You must ensure that the binaries are compatible with the version of the Solaris kernel on which SunVTS is currently running.

If .customtest is renamed as .customtest-group, all of the associated tests will appear under the specified group.

Removing SunVTS

It is necessary to remove SunVTS before installing a new version. The following instructions describe how to remove SunVTS using the pkgrm command.

To Remove SunVTS With the pkgrm Command

1. Log in to the system and become superuser.

   % su

2. Remove the packages with the pkgrm command:

   # pkgrm SUNWvtsx SUNWvtsmn SUNWvtsol [As of SunVTS 4.3, the SUNWodu package is an obsolete SunVTS package that will only be present if you have an older version of SunVTS installed. If you have this package installed, you should remove it before reinstalling any version of SunVTS.] SUNWodu [As of SunVTS 5.0, the SUNWvtsol package is obsolete. You should remove it if it is installed on the system for which you plan to install SunVTS 5.0.] SUNWvts

   ---

   Note -

   As of SunVTS 4.3, the SUNWodu package is an obsolete SunVTS package that will only be present if you have an older version of SunVTS installed. If you have this package installed, you should remove it before reinstalling any version of SunVTS.

   ---

   Answer y (yes) to the removal questions.

   You should see Removal of package_name was successful.