unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



setld(8)							     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 pro-
      gram.

  -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 com-
      mand 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.	How-
			ever, because the PRE_L	phase of the SCP executed,
			changes	may have been made to the system.   For	exam-
			ple, 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 com-
      plete


			The PRE_L phase	of the SCP has finished	successfully,
			and the	software is ready to be	loaded onto the	sys-
			tem (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 verifica-
			tion.  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 verifica-
			tion.







      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 exe-
			cuted.	As a result of this, the subset	is not con-
			sidered	to be installed.


      post-load	com-
      pleted


			The POST_L phase of the	SCP has	finished success-
			fully, 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	con-
			figured	and therefore is not considered	to be
			installed.
      installed

			The C INSTALL phase of the SCP has finished success-
			fully, 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 installa-
			tion 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 sub-
			set.
      member loaded

			This state only	applies	to a cluster and is used to
			indicate that the member specific files	for the	sub-
			set 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	con-
      tents 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; manda-
	   tory	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 exe-
      cutes 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 distribu-
      tion media. If you specify the optional -D root-path operand, the	sub-
      sets 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 sys-
      tems 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 speci-
      fied, 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 docu-
  mented 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 possi-
       ble 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 possi-
       ble to have members in different	states.


  Chronological	Order of a Software Delete Operation


  The following	 shows the order in which states are transitioned when sub-
  sets 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 mes-
  sage 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	com-
  mand.

  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 per-
  form 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 mes-
  sage 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	off-
  line 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 sys-
  tem:

       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