setld - Software subset management utility
/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...]
Configures one subset, passing the message to the subset
control program. 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.
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. 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.
Displays command usage statements. 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. 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. Loads member specific files on a
cluster member when a software subset is in the
member load failed state. 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. 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. 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.
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. 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.
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: Magnetic tape on tape unit 0 Local
CD-ROM device Disk distribution mounted in the
/mnt/ALPHA/BASE directory Network distribution from
a RIS server, hostname. The host name must be
appended with a colon (:). 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.
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
The following shows the chronological transition of a subset
from one state to the next when it is loaded by the
setld -l command. not installed
This is the state of the system before you load a
software subset. 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 preload
completed. If the SCP returns a failure status,
it is marked as pre-load failed. 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. 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. 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. 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 cinstall
completed. If the C INSTALL phase of the
SCP returns a failure status, it is marked as cinstall
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 [Toc] [Back]
The following shows the order in which states are transitioned
when subsets are deleted by the setld -d command.
deleting
As soon as the delete process is started the subset
is changed to the deleting state. 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.
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.
The requested operation was successful. The requested
operation failed on a mandatory subset. The requested
operation failed on an optional subset.
-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.
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 offline,
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 offline
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
Log file for setld transactions Subset inventory files
Subset control files Subset control programs Subset
installed lock files Contains a value that describes the
current installation status of a software subset
depord(8) dsfmgr(8), fitset(8), fverify(8), kits(1),
kits(1) stl_comp(4), stl_ctrl(4), stl_image(4),
stl_inv(4), stl_scp(4), stl_sts(4) Guide to Preparing
Product Kits, Installation Guide
setld(8)
[ Back ] |
