setld(8)setld(8)NAMEsetld - 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
Configures one subset, passing the message to the subset control pro‐
gram. Runs the C_INSTALL (configure installation) phase of the named
software subset's software subset control program (SCP) on the speci‐
fied 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 suc‐
cessfully 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 fail‐
ure 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 success‐
fully, 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 com‐
plete 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 sub‐
set is not considered to be installed.
post-load completed The POST_L phase of the SCP has finished suc‐
cessfully, and the software is ready to be con‐
figured (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 con‐
sidered to be installed.
installed The C INSTALL phase of the SCP has finished suc‐
cessfully, 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 per‐
formed 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 com‐
plete the copy of the member specific informa‐
tion to the current cluster member. Therefore,
the current cluster member has all of the shared
files, but does not have all of the member spe‐
cific 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 clus‐
ter member's member specific directories. How‐
ever, the subset is not considered installed at
this point because the C INSTALL phase of the
SCP has not been executed on the current clus‐
ter member.
unknown Either the subset's /usr/.smdb./*.sts file con‐
tains 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 cor‐
rupted 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 incor‐
rect 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 sub‐
set 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 sub‐
sets are listed but cannot be selected. The selected subsets are
loaded onto the system. Loads member specific files on a clus‐
ter 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 sub‐
set control program, except during installation.
Use the fverify command to verify the files of a specific sub‐
set. The fverify command reports missing files and inconsisten‐
cies 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 distri‐
bution media mounted on location.
Subsets extracted with this option are not loaded onto your sys‐
tem 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. Other‐
wise, 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 Ser‐
vices utility to set up RIS areas. If you specify subset argu‐
ments, 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 op‐
erand, 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
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 oper‐
ates 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 sys‐
tems.
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.
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 ser‐
vices (RIS) server.
The setld command is used to load and remove software subsets from sin‐
gle systems or clustered systems; there is no difference in command
syntax, with the exception that using an alternate root for any soft‐
ware 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 exis‐
tence 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 switch‐
ing 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 cur‐
rent 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. not
installed
This is the state of the system before you load a software sub‐
set. 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. ver‐
ify 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 ver‐
ification 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 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. 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.
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 opera‐
tion to an alternate root on a cluster. An alternate root is not sup‐
ported 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
The requested operation was successful. The requested operation failed
on a mandatory subset. 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 direc‐
tory_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 pro‐
gram, 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 con‐
trol program while extracting subsets. This can indicate a faulty dis‐
tribution. 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 com‐
mand 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, non‐
clustered 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 OSFX‐
MAIL540 subset on member1 of a three member cluster and delete the sub‐
set on that member: setld-m member1 -Z OSFXMAIL540
To recover from the failure of a subset load operation of the OSFX‐
MAIL540 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 cur‐
rent 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
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 sub‐
set
SEE ALSOdepord(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)