 |
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 [-D root-path] [-m member_ID] -C subset [subset...]
/usr/sbin/setld [-D root-path] [-m member_ID] -Z subset [subset...]
/usr/sbin/setld [-D root-path] [-m member_ID] -u subset [subset...]
OPTIONS
-c subset message
Configures one subset, passing the message to the subset control
program.
-C 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 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 root directory for an operation.
·
If you specify the -D root-path operand, the setld command operates
on the software rooted at the specified directory (root-path).
·
If you do not specify the -D root-path operand, the default is root
( / ) for all operations except -x, when the default is the current
directory ( . ).
This optional operand is useful for installing software to offline
systems on removable media or dual-ported disk drives.
[-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.
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 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. 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.
The location argument specifies the location of the distribution. This
location can be the name of a directory, a device special file name, or the
name of a remote installation server. The specified location determines the
type of media to be used. Valid location specifiers can be similar to the
following examples:
/dev/tape/tape0h
Magnetic tape on tape unit 0
/mnt/ALPHA/BASE
Disk distribution in the /mnt/ALPHA/BASE directory
hostname:
Remote distribution from server hostname
The subset argument specifies the name of a subset on which an operation is
to be performed. Subset names are strings of seven or more characters used
to uniquely identify subsets, for example: OSFXMAIL100.
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 try to install software into an NFS mounted file system.
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 dir
The setld command could not create the required directory dir. 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 OSFXMAIL100 subset from tape unit 2:
setld -l /dev/tape/tape2h OSFXMAIL100
To load the OSFXMAIL100 subset from tape unit 2 to an offline system rooted
at /mnt:
setld -D /mnt -l /dev/tape/tape2h OSFXMAIL100
To load the OSFXMAIL100 subset from installation server houston to an
offline system rooted at /mnt:
setld -D /mnt -l houston: OSFXMAIL100
To load the OSFXMAIL100 subset from a disk distribution in /mnt2/ALPHA/BASE
to an offline system rooted at /mnt:
setld -D /mnt -l /mnt2/ALPHA/BASE OSFXMAIL100
To recover from the failure of a subset delete operation of the OSFXMAIL100
subset on member1 of a three member cluster and delete the subset on that
member:
setld -m member1 -Z OSFXMAIL100
To recover from the failure of a subset load operation of the OSFXMAIL100
subset on member1 of a three member cluster and load the subset on that
member:
setld -m member1 -C OSFXMAIL100
To delete the OSFXMAIL100 and OSFSYSV100 subsets from a single system:
setld -d OSFXMAIL100 OSFSYSV100
To delete OSFXMAIL100 and OSFSYSV100 subsets from the offline system rooted
at /mnt:
setld -D /mnt -d OSFXMAIL100 OSFSYSV100
To display the status of all subsets known to the system:
setld -i
To display the status of all subsets known to the offline system rooted at
/mnt:
setld -D /mnt -i
To display the contents of the OSFXMAIL100 subset:
setld -i OSFXMAIL100
To check for the existence of the OSFCLINET100 subset on the running
system:
setld -v OSFCLINET100
To send the configuration message REPORT to the OSFXMIT100 subset:
setld -c OSFXMIT100 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
Logfile 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:
dsfmgr(8), fitset(8), fverify(8), kits(1), kits(1)
Files:
depord(4), stl_comp(4), stl_ctrl(4), stl_image(4), stl_inv(4),
stl_scp(4)
Documents:
Guide to Preparing Product Kits, Installation Guide
|
Index for
Section 8 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|