 |
Index for
Section 8 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
setld(8)
NAME
setld - Software subset management utility
SYNOPSIS
/usr/sbin/setld [-D root_path] -c subset message
/usr/sbin/setld [-D root_path] [-f] -d subset...
/usr/sbin/setld [-D root_path] -h
/usr/sbin/setld [-D root_path] -i [subset...]
/usr/sbin/setld [-D root_path] -l location [subset...]
/usr/sbin/setld [-D root_path] -v subset...
/usr/sbin/setld [-D root_path] -x location [subset...]
/usr/sbin/setld [-m member_ID] -C subset [subset...]
/usr/sbin/setld [-m member_ID] -Z subset [subset...]
/usr/sbin/setld [-m member_ID] -u subset [subset...]
OPTIONS
-c subset message
Configures one subset, passing the message to the subset control
program.
-C subset...
Runs the C_INSTALL (configure installation) phase of the named software
subset's software subset control program (SCP) on the specified cluster
member. This option must be used in conjunction with the -m operand,
and is used for disaster recovery purposes only.
-d subset...
Deletes each specified subset from a single or clustered system.
Subsets can be marked during manufacture so that they cannot be
deleted. If you try to delete such subsets, an appropriate diagnostic
message is generated.
If a subset being deleted is required by other subsets installed on the
system, those subsets are listed and you must confirm that the target
subset is to be deleted.
You cannot use the -d option to delete subsets extracted with the -x
option.
-f Forces the continuation of a delete operation despite receiving errors
from a subset control program (SCP). Using this flag is a last resort.
If an SCP is reporting an error, the error should be resolved and the
setld -d operation attempted again. The only time the -f flag should be
used is if the errors cannot be resolved and the subset must be removed
from the system
After running setld -d -f on a cluster, all cluster members except
those members that are down will have the software removed. For each
cluster member that is down, run the setld -Z command once the member
or members come back up. If necessary, run setld -Z -f if the first
setld -Z command fails.
-h Displays command usage statements.
-i [subset...]
Displays the inventory status of the system or any specified subset. If
you do not specify a subset, the system state is listed on standard
output in three columns: Subset, Status, and Description.
Code developers should never use a value displayed by the setld -i
command or a value displayed in any error messages because the values
might be revised or internationalized in a future release. The Guide to
Preparing Product Kits manual contains information about writing SCPs
and the available routines that code developers should use to determine
the installation status of a software subset.
Subset status may be one of the following:
______________________________________________________________________
Value Description
______________________________________________________________________
not installed
There is no trace of the software on the system.
This could be because there was never an attempt
to install the software or the software was
installed on the system, but it was removed
successfully at some point.
deleting
The setld -d (delete) command was started but
was never completed.
pre-load failed
The software started to load, but the PRE_L
phase of the subset's subset control program
(SCP) returned a failure status, and therefore,
none of the files from the software subset were
placed on the system. However, because the
PRE_L phase of the SCP executed, changes may
have been made to the system. For example, if
the first command in the SCP exits with a
failure status, then no changes were made. If
the first command made changes and a later
command returned a failure status, then changes
were made.
pre-load complete
The PRE_L phase of the SCP has finished
successfully, and the software is ready to be
loaded onto the system (that is, the next step
is to place the files on the system).
load failed
The software subset was loaded, the files are
on the system, but one or more of the files
failed verification. The verification check
compares the size and checksum of the file on
the system against the size and checksum in the
inventory record. If either size or checksum
does not match, the file fails verification.
load completed
The software subset has been loaded onto the
system, which means that all of the files in the
subset are now present on the system and all of
the files have been verified. This does not
mean that the software is installed. This state
means that the files are present on the system,
but they may not be usable. In order for the
subset to be considered installed, the POST_L
and C INSTALL phases of the SCP file must
complete as well. In addition, protected system
files and *.upd.. files have to be moved into
place.
post-load failed
The software has successfully loaded (that is,
the files have been placed on the system), but
the POST_L phase of the SCP returned a failure
status, and therefore the C INSTALL phase will
not be executed. As a result of this, the
subset is not considered to be installed.
post-load completed
The POST_L phase of the SCP has finished
successfully, and the software is ready to be
configured (that is, the next step is to execute
the C INSTALL phase).
c-install failed
The POST_L phase has completed successfully, but
the C INSTALL phase of the SCP has returned a
failure status. As a result, the software is
not fully configured and therefore is not
considered to be installed.
installed
The C INSTALL phase of the SCP has finished
successfully, and the software now has been
installed. At this point there are no other
installation steps to be performed. However,
the software may require that steps must be
performed after the installation has completed.
These steps are not part of the installation
process, but may be required in order to use the
software.
member load failed
This state only applies to a cluster and is used
to indicate that the subset has completed the
POST_L phase of the SCP but was unable to
complete the copy of the member specific
information to the current cluster member.
Therefore, the current cluster member has all of
the shared files, but does not have all of the
member specific files for this subset.
member loaded
This state only applies to a cluster and is used
to indicate that the member specific files for
the subset have been copied to the current
cluster member's member specific directories.
However, the subset is not considered installed
at this point because the C INSTALL phase of the
SCP has not been executed on the current
cluster member.
unknown
Either the subset's /usr/.smdb./*.sts file
contains a string other than one of the valid
strings or the code is attempting to set a value
that does not exist (that is, a variable is
corrupted and it is trying to set the software
to a state that does not exist). Of the two
reasons, the more likely cause is that the
*.sts file contains a string that does not map
to a state known to the installation software.
This can be caused by editing the file and
placing an incorrect value in the file or the
file is corrupt.
______________________________________________________________________
If you specify a subset name as an argument, the names of the files in
each named subset are listed. Named subsets are listed with their
contents whether they are installed or not.
You cannot use the -i option to list subsets extracted with the -x
option.
-l location [subset...]
Loads software onto single or clustered systems from the distribution
media mounted on location.
· If you specify subset arguments, only those subsets are loaded.
· If you do not specify subset arguments, a menu is displayed that
lists the optional subsets available on the distribution;
mandatory subsets are listed but cannot be selected. The selected
subsets are loaded onto the system.
-u Loads member specific files on a cluster member when a software subset
is in the member load failed state.
-v subset...
Verifies the existence of the installed subset. The -v option also
executes any V phase processing included in the subset control program,
except during installation.
Use the fverify command to verify the files of a specific subset. The
fverify command reports missing files and inconsistencies in file size,
checksum, user ID, group ID, permissions, and file type.
You cannot use the -v option to check the existence of subsets
extracted with the -x option.
-x location [subset...]
Extracts subsets from the distribution media mounted on location.
Subsets extracted with this option are not loaded onto your system but
are copied in their exact format, compressed or not, from the
distribution media. If you specify the optional -D root_path operand,
the subsets are copied to root_path. Otherwise, the subsets are copied
to the current directory.
Because these subsets are not installed, you cannot use the -d, -i, or
-v options to delete, inventory, or check the existence of extracted
subsets in the directory to which they are copied.
The -x option is used primarily by the Remote Installation Services
utility to set up RIS areas.
· If you specify subset arguments, only the specified subsets are
extracted.
· If you do not specify subset arguments, a menu is displayed that
lists the subsets on the distribution media. Subsets chosen from
this menu are then extracted.
-Z subset...
Runs the C_DELETE (configure delete) phase of the named software
subset's SCP on the specified cluster member. This option must be used
in conjunction with the -m operand, and is used for disaster recovery
purposes only.
After running setld -d -f on a cluster, all cluster members except
those members that are down will have the software removed. For each
cluster member that is down, run the setld -Z command once the member
or members come back up. If necessary, run setld -Z -f if the first
setld -Z command fails.
OPERANDS
[-D root_path]
Specifies root_path as the alternate root directory for an operation.
Using an alternate root is not supported in a cluster.
If you specify the -D root_path operand, the setld command operates on
the software rooted at the specified directory (root_path). The
software that is installed to an alternate root is only used when the
alternate root is running as the root of the operating system.
If you do not specify the -D root_path operand, the default is root
( / ) for all operations except -x (extraction), when the default is
the current directory ( . ).
You can use this feature to install software onto a disk and then move
the disk to a different system. When you use the -D option, the
software is loaded onto the disk, however, it is not configured. You
must use the setld -c command to configure the software.
[-m member_ID]
Sets the cluster member ID for recovery purposes when a load or delete
operation fails on one or more members in a cluster. This option is
only valid with the -C and -Z options. If a member_ID is not
specified, the operation defaults to the current system. This operand
is not valid on nonclustered systems.
This operand is to be used for recovery purposes only. It is not the
intended nor the supported method to remove or install software on a
cluster.
location
Specifies the location of the software distribution. This location can
be the name of a directory, a device special file name, or the name of
a remote installation services (RIS) server. The specified location
determines the type of media to be used. Valid location specifiers are
similar to the following examples:
/dev/tape/tape0h
Magnetic tape on tape unit 0
/dev/disk/cdrom0c
Local CD-ROM device
/mnt/ALPHA/BASE
Disk distribution mounted in the /mnt/ALPHA/BASE directory
hostname:
Network distribution from a RIS server, hostname. The host name
must be appended with a colon (:).
subset [subset...]
Specifies the name of a subset or subsets on which an operation is to
be performed. Subset names are strings of seven or more characters that
are used to uniquely identify software, for example: OSFXMAIL540.
DESCRIPTION
The setld command is an interactive program for installing and managing
software subsets. Software products are organized into subsets that may be
loaded, configured, inventoried, and deleted. The load operation reads
software from disk, tape, CD-ROM, or a remote installation services (RIS)
server.
The setld command is used to load and remove software subsets from single
systems or clustered systems; there is no difference in command syntax,
with the exception that using an alternate root for any software operation
(with the -D option) is not supported on a cluster. The setld command can
be invoked from any member of a cluster to install or remove software
across the entire cluster.
The setld command also is used to extract the contents of installation
media onto a disk so that the disk can be used as the distribution media.
Extracted subsets are not loaded onto the system and you cannot use the -d,
-i, or -v options to delete, inventory, or check the existence of
extracted subsets in the directory to which they are copied.
Installing Software to an Alternate Root
An alternate root is a directory that can be used as the root directory of
a system. Installing software to an alternate root is accomplished through
the setld -D root_path command. When the alternate root becomes the root
directory of a system, only those files and directories within the
alternate root directory are accessible. For example, the files in the
typical /, /usr, /sbin, and /var directories are not accessible . The
software that is installed to an alternate root is only used when the
alternate root is running as the root of the system. The switch to
alternate root is typically done through a reboot of the system. Using an
alternate root for any software operation (with the -D option) is not
supported on a cluster.
Software installed to an alternate root must abide by the following rules:
· Software can only be used when the single system is running from the
alternate root. If the system is not running from the alternate root,
the software cannot be used. For example, you cannot install software
to an alternate root and then run the software without switching the
system to use the alternate root.
· Software installed to an alternate root must only reference (that is,
read and write) files that exist in the directory tree that starts
with the alternate root. The software cannot reference files outside
of the alternate root directory tree because when the system uses the
alternate root, only those files in the alternate root directory tree
are available.
When you use the -D option to install software to an alternate root,
specify the software subsets to load on the command line. If you do not
specify the software subset names, setld displays an interactive software
selection menu for you to choose the subsets. If you use the software
selection menu to choose the subsets to install, errors may occur.
Recovering from setld Software Load and Delete Failures
Recovering from software load and delete failures depends upon the current
status of the software subsets in question. Recovery procedures are
documented in the Installation Guide.
Chronological Order of a Software Load Operation
The following shows the chronological transition of a subset from one state
to the next when it is loaded by the setld -l command.
1. not installed
This is the state of the system before you load a software subset.
2. pre-load failed or pre-load completed
If the PRE_L phase of the SCP returns a success status, the state of
the subset is marked as pre-load completed. If the SCP returns a
failure status, it is marked as pre-load failed.
3. verify failed or verify completed
Once the tar command or the pax command have finished placing the
files on the system, the fverify command is executed to verify that
the files were all loaded correctly (that is, none were missed or
corrupted during the load). If the verification succeeds, the subset
is marked as verify completed. If the verification fails, the subset
is marked as verify failed.
4. post load failed or post load completed
After the subset files are loaded and verified, the POST_L phase of
the subset's SCP file is executed. If the POST_L phase of the SCP
returns a success status, the state of the subset is marked as post
load completed. If the POST_L phase of the SCP returns a failure
status, the state of the subset is marked as post load failed.
5. member load failed or member loaded
These states apply to a cluster; single-system machines cannot attain
these states.
After the POST_L phase is executed in a cluster, the member specific
files from the subset are copied to each member of the cluster. If
the copy operation succeeds on each member of the cluster, the subset
is marked as member loaded on that member of the cluster. If
the copy operation fails, the subset is marked as member load failed
on that member of the cluster.
Because this state occurs on a per cluster member basis, it is
possible to have members in different states.
6. c-install failed or c-install completed
If the C INSTALL phase of the SCP returns a success status, the state
of the subset is marked as c-install completed. If the C INSTALL
phase of the SCP returns a failure status, it is marked as c-install
failed.
On a single system, the C INSTALL phase of the SCP is executed after
the POST_L phase completes successfully.
On a cluster, the C INSTALL phase is executed on the cluster members
that have successfully populated the member specific files (that is,
they have reached the member loaded stage).
Because this state occurs on a per cluster member basis, it is
possible to have members in different states.
Chronological Order of a Software Delete Operation
The following shows the order in which states are transitioned when
subsets are deleted by the setld -d command.
1. deleting
As soon as the delete process is started the subset is changed to the
deleting state.
2. not installed
Once all of the delete phases (C DELETE, PRE_D, file removal, and
POST_D) have been executed, the subset is marked as not installed.
RESTRICTIONS
The setld utility does not handle white space in directory names.
Do not install software into an NFS mounted file system.
You cannot use the -D root_path option to perform any software operation to
an alternate root on a cluster. An alternate root is not supported on
cluster configurations.
You cannot use the -d option to delete subsets extracted with the -x
option.
You cannot use the -i option to list subsets extracted with the -x option.
You cannot use the -v option to check the existence of subsets extracted
with the -x option.
You cannot use the -m option on nonclustered systems.
EXIT STATUS
0 The requested operation was successful.
1 The requested operation failed on a mandatory subset.
>1 The requested operation failed on an optional subset.
ERRORS
-x can be used by super-user only
You do not have root privileges and you tried to use the setld command with
the -x option, one of the root-only options. The -i option is the only
setld function available to nonprivileged users.
error in Args()
The setld command cannot understand the command line arguments. This
message is always preceded by a usage message or another diagnostic.
Temp directory /usr/tmp/stltmpXXXXXX already in use
The temporary directory that setld creates for itself already exists. Run
setld again.
Cannot create directory directory_name
The setld command could not create the required directory directory_name.
This error can happen if parts of the system are NFS mounted but not root-
mapped.
error in Dirs()
This message always accompanies the preceding two messages but also can
accompany messages generated by commands that are called by the setld
command.
subset: not currently installed, cannot configure.
The subset argument to the -c option refers to a subset not installed on
the system.
subset: missing control program, cannot configure.
The setld command tried to configure subset, but the program needed to
perform the configuration is missing. Delete the subset and install it
again before trying the operation again.
subset: not currently installed, cannot delete
The subset argument to the -d option refers to a subset not installed on
the system.
ReadCtrlFile(): cannot find filename.ctrl
The setld command cannot read the control file filename.ctrl.
ReadCtrlFile(): filename.ctrl is incomplete
The control file filename.ctrl either is empty or it names attributes with
no values specified.
setld: Sorry, You may not delete the description
(subset) subset
The subset was marked during manufacture as a subset that cannot be
deleted; it cannot be removed from the system by the setld command.
subset: deletion declined by subset control program
The subset control program subset has determined that the subset should not
be deleted. Depending on the individual subset control program, this
message also can be seen with a diagnostic issued directly from the subset
control program. Consult the product's documentation.
Installation declined by subset control program
description (subset) will not be loaded.
The subset control program for subset has determined that the subset should
not be loaded. Depending on the individual subset control program, this
message also can be seen with a diagnostic issued directly from the subset
control program. Consult the product's documentation.
Tape Positioning Error
The setld command detected an error while positioning the tape for a read
operation with the -l or -x option. This can indicate a faulty tape or a
transient tape subsystem error. Check the error log and try the operation
again.
Error Extracting subset
An unrecoverable error has occurred while trying to extract subset from the
distribution.
Control Info Error on subset
The setld failed to access a control or inventory file or subset control
program while extracting subsets. This can indicate a faulty distribution.
Try the operation again.
subset: extract checksum error
The extracted copy of subset has a checksum error. This can indicate a
transient tape subsystem error. Check the error log and retry the
operation.
Error contacting server hostname: message
The setld command could not contact installation server hostname. The error
message provides more information.
Device location not supported for installations.
The setld command did not recognize the location specified on the command
line as a valid input location for a load (-l) or extract (-x) operation.
Cannot access /dev/ntape/tapeNh
The device special file /dev/ntapeNh either does not exist or is not a
character special file. Remake the file with the dsfmgr command and try the
operation again.
subset: Unknown subset
A subset argument to the -i option does not correspond to any subset known
to the system. Check the command line for spelling errors.
location/instctrl: no such file or directory
The disk distribution location specified on the command line does not point
to a valid directory. Check the command line for spelling errors.
EXAMPLES
To load software subsets from tape unit 2:
setld -l /dev/tape/tape2h
To load the OSFXMAIL540 subset from tape unit 2:
setld -l /dev/tape/tape2h OSFXMAIL540
To load the OSFXMAIL540 subset from tape unit 2 to an off-line,
nonclustered system rooted at /mnt:
setld -D /mnt -l /dev/tape/tape2h OSFXMAIL540
To load the OSFXMAIL540 subset from installation server houston to an off-
line, nonclustered system rooted at /mnt:
setld -D /mnt -l houston: OSFXMAIL540
To load the OSFXMAIL540 subset from a disk distribution in /mnt2/ALPHA/BASE
to an off-line, nonclustered system rooted at /mnt:
setld -D /mnt -l /mnt2/ALPHA/BASE OSFXMAIL540
To recover from the failure of a subset delete operation of the OSFXMAIL540
subset on member1 of a three member cluster and delete the subset on that
member:
setld -m member1 -Z OSFXMAIL540
To recover from the failure of a subset load operation of the OSFXMAIL540
subset on member1 of a three member cluster and load the subset on that
member:
setld -m member1 -C OSFXMAIL540
To delete the OSFXMAIL540 and OSFSYSV540 subsets from a single system:
setld -d OSFXMAIL540 OSFSYSV540
To delete OSFXMAIL540 and OSFSYSV540 subsets from the off-line system
rooted at /mnt:
setld -D /mnt -d OSFXMAIL540 OSFSYSV540
To display the status of all subsets known to the system:
setld -i
To display the status of all subsets except those that are not installed:
setld -i | grep -v "not installed"
To display the status of all subsets known to the off-line system rooted at
/mnt:
setld -D /mnt -i
To display the contents of the OSFXMAIL540 subset:
setld -i OSFXMAIL540
To check for the existence of the OSFCLINET540 subset on the running
system:
setld -v OSFCLINET540
To send the configuration message REPORT to the OSFXMIT540 subset:
setld -c OSFXMIT540 REPORT
To extract subsets from the distribution on tape unit 0 into the current
directory:
setld -x /dev/ntape/tape0h
To extract subsets from the disk distribution in /mnt/ALPHA/stuff into
/usr/bigdisk:
setld -D /usr/bigdisk -x /mnt/ALPHA/stuff
FILES
/var/adm/smlogs/setld.log
Log file for setld transactions
root_path/usr/.smdb./*.inv
Subset inventory files
root_path/usr/.smdb./*.ctrl
Subset control files
root_path/usr/.smdb./*.scp
Subset control programs
root_path/usr/.smdb./*.lk
Subset installed lock files
root_path/usr/.smdb./*.sts
Contains a value that describes the current installation status of a
software subset
SEE ALSO
Commands:
depord(8) dsfmgr(8), fitset(8), fverify(8), kits(1), kits(1)
Files:
stl_comp(4), stl_ctrl(4), stl_image(4), stl_inv(4), stl_scp(4),
stl_sts(4)
Documents:
Guide to Preparing Product Kits, Installation Guide
|
Index for
Section 8 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|