setld man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=setld&af=0&tf=2&of=DigitalUNIX

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 [-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 ALSO
       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)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net