swlist(8)							     swlist(8)



NAME
       swlist -- List information about the software

SYNOPSIS
       swlist  [-d|-r] [-v] [-a attribute] [-l level]  [-t targetfile] \
       [-c file] [-x option=value]  [-X options_file]  [-W option] \
       [software_selections]  [@targets]

       swlist --products [software_selections]	[@targets]

       swlist --files  [@targets]

       swlist --dir [software_selections] [@targets]

       swlist --dependencies [--prerequisites sw_spec] \
       [--exrequisites sw_spec] [@targets]


DESCRIPTION
       swlist lists information about a distribution or installed software.
       Neither swlist nor any component of swbis is required on the target
       host, however, the target host must look like a Unix system at the
       shell and command-line utility level.  Remote network connections are
       made by ssh.  Ssh is the default but rsh can be selected by a command
       line option.

       swlist operates on serial archives (e.g. compressed tar archives) or on
       a file system directory representing installed software.	 The default
       target directory is '/', this default is subject to user configuration.

OPTIONS
       -a attribute

	      Specify an attribute to list.   Only the architecture attribute
	      is supported for installed_software at this time (MAR 2007).
	      The returned value is determined by running GNU config.guess on
	      the target host.


       -c FILE

	      Write the catalog to FILE. Software selections are applied.  The
	      only supported FILE is '-' causing a dump of the catalog to
	      stdout in tar format.


       -d

	      Specify the target is a distribution.


       -f FILE

	      Read the list of software selections from FILE.


       -l LEVEL

	      Specify a level to list. LEVEL is an enumerated list of objects:
	      bundle, product, fileset, control_file, file (Not yet
	      implemented)


       -r

	      Indicates that the operation is on installed software at a
	      location indicated by the the target.


       -t targetfile

	      Specify a file containing a list of targets (one per line).


       -v

	      List attribute value pairs in INDEX file format according to
	      attibutes specified by the -a option, list all attributes if -a
	      not used; or, increment the verbose level.

		     Note:  This option is overloaded. It means two different
		     things depending on the context.  If a mode is explicitly
		     given, then it means increment verbosity, otherwise it
		     means list in INDEX file format.


       -x option=value

	      Specify the extended option overriding the defaults file value.

       -X FILE

	      Specify the extended options filename, FILE,  overriding the
	      default filenames.  This option may be given more then once. If
	      the resulting specified value is an empty string then reading of
	      any options file is disabled.

       --help

	      Show help (Implementation extension)

       -W option[,option,...]

	      Specify the implementation extension option.
	      Syntax: -W option[=option_argument[,option...]
	      Options may be separated by a comma.  The implementation
	      extension options may also be given individually using the
	      '--long-option[=option_arg]' syntax.

       --products

	      List the product's tag, revision, vendor_tag and location.

       --directory

	      List the catalog directory entries.

       --files

	      List files as defined in the installed catalog

       --sys

	      List files as exists in the file system

       --dependencies

	      Run in check dependency mode.  Assert dependencies against
	      installed software catalog. Dependencies are software specs
	      given by the --prerequisites and --extrequisites options


       --prerequisites=SW_SPEC

	      Specify depencency to check, may be used multiple times.
	      Prerequisites packages are required to be installed.


       --exrequisites=SW_SPEC

	      Specify depencency to check, may be used multiple times.
	      Exrequisites packages are required not to be installed.


       -W remote-shell=SHELL

	      Defaults File Option: swbis_remote_shell_client
	      Supported shells are "ssh" and "rsh", ssh is the default.

       -W show-options-files
	      Show the complete list of options files and if they are found.

       -W show-options
	      Show the options after reading the files and parsing the command
	      line options.

       -W pax-command={tar|pax|star|gtar}
	      Set the portable archive command for all operations.  The
	      default is "pax".

       -W pax-read-command={tar|pax|star|gtar}
	      Set the read command for local and remote hosts.

       -W remote-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_remote_pax_read_command
	      Set the read command for remote hosts.  This is the command that
	      runs on the target (e.g. pax -r, tar xpf -).  The default is
	      "pax".

       -W local-pax-read-command={tar|pax|star|gtar}
	      Defaults File Option: swbis_local_pax_read_command
	      Set the read command for local hosts.  This is the command that
	      runs on the target (e.g. pax -r, tar xpf -).  The default is
	      "pax".

       -W pax-write-command={tar|pax|star|gtar|swbistar}
	      Set the write command for local and remote hosts.	 This is the
	      command that runs on the target (e.g. pax -w, tar cf -).

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set the write command for remote hosts.

       -W local-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_local_pax_write_command
	      Set the portable archive write command for local host
	      operations.  This is the command that runs on the source (e.g.
	      pax -w, tar cf -).  The default is "pax".

       -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
	      Defaults File Option: swbis_remote_pax_write_command
	      Set the portable archive write command for remote host
	      operations.  This is the command that runs on the source (e.g.
	      pax -w, tar cf -).  The default is "pax".

       -W no-defaults
	      Do not read any defaults files.

       -W no-getconf
	      Defaults File Option: swbis_no_getconf
	      Makes the remote command be '/bin/sh -s' instead of the default
	      'PATH=`getconf PATH` sh -s'.

       -W shell-command=NAME
	      Defaults File Option: swbis_shell_command
	      NAME may be one of "detect" "bash", "sh" or "posix" and
	      specifies the remote command run by the remote shell.  "posix"
	      is 'PATH=`getconf PATH` sh -s', "bash" is "/bin/bash -s", "sh"
	      is "/bin/sh -s", and "ksh" is "ksh -s".  The default is "posix".

       -W use-getconf
	      Opposite of --no-getconf.


       -W source-script-name=NAME
	      Write the script that is written into the remote shell's stdin
	      to NAME.	This is useful for debugging.

       -W target-script-name=NAME
	      Write the script that is written into the remote shell's stdin
	      to NAME.	This is useful for debugging.

       software_selections

	      Refer to the software objects (products, filesets) using
	      software spec syntax. (See sw(5) for syntax).


       target

	      Refers to the software_collection where the software selections
	      are to be applied.  Allows specification of host and pathname
	      where the software collection is located.	 A target that
	      contains only one part is assumed to be a hostname.  To force
	      interpretation as a path, use a absolute path or prefix with
	      ':'.


       Source and Target Specification and Logic

	    Synopsis:
		 Posix:
		      host[:path]
		      host
		      host:
		      /path  # Absolute path

		 Swbis Extension:
		      [user@]host[:path]
		      [user@]host_port[:path]
		      :path

		 Swbis Multi-hop Target Extension:
		      # ':' is the target delimiter
		   # '_' delimits a port number in the host field

		      [user@]host[@@[user@]host[@@...]][:file]
		      [user@]host_port[@@[user@]host[@@...]][:file]

		      # Using ':', a trailing colon is used to
		      # disambiguate between a host and file.
		   # For Example,
		      :file
		      host:
		      host
		      host:file
		      host:host:
		      host_port:host_port:
		      host:host:file
		      user@host:user@host:
		      user@host:user@host:host:
		      user@host:user@host:file

	    A more formal description:

	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
		   | HOST_CHARACTER_STRING ':'
		   | HOST_CHARACTER_STRING
		   | PATHNAME_CHARACTER_STRING
		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
		   ;

	      PATHNAME_CHARACTER_STRING must be an absolute path unless
			      a HOST_CHARACTER_STRING is given.	 Allowing
			      a relative path is a feature of the swbis
			      implementation.

		       NOTE: A '.' as a target is an implementation
			     extension and means extract in current
			     directory.

		       NOTE: A '-' indicating stdout/stdin is an
			     implementation extension.

		       NOTE: A ':' in the first character indicates a filename.
			     This is an implementation extension.

	      HOST_CHARACTER_STRING is an IP or hostname.

	   Examples:
	      Copy the	distribution /var/tmp/foo.tar.gz at 192.168.1.10
		     swcopy -s /var/tmp/foo.tar.gz @192.168.1.10:/root


       Implementation Extension Syntax (multi ssh-hop) :
	   Syntax:
	   %start   wtarget    # the Implementation Extension Target
			       # Note: a trailing ':' forces interpretation
			       # as a host, not a file.
	   wtarget   : wtarget DELIM sshtarget
		     | sshtarget
		     | sshtarget DELIM
		     ;
	   sshtarget : user '@' target # Note: only the last target
		     | target	       # may have a PATHNAME, and only a host
		     ;		       * may have a user
	   target   : HOST_CHARACTER_STRING
		    | PATHNAME_CHARACTER_STRING
		    ;
	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

	   DELIM    : ':'   # The multi-hop delimiter.
		    ;




IMPLEMENTATION EXTENSIONS
       The --dependencies, --products, and --files are implementation
       extension modes.


USAGE EXAMPLES
   Show the path of the installed software catalog.
	 swlist --show-options | grep installed_


   List Products
       * List products from a certain distributor, foo (Note:  this requires
       that the foo vendor uses foo_something_ as the product vendor_tag in
       their distributions.

	 swlist v="foo*"


       * List all products

	 swlist @/   # If distribution_target_directory=/ then "swlist" alone
		     # will suffice.


       * List products installed at alternate root

	 swlist @/mnt/test


       * List products according to a name pattern and revision, and
       distributor

	 swlist emacs"*","r>20",v=rh"*" @/



   Test Dependencies
       * Check if a given dependency passes against a given installed catalog
       on a host

	 swlist -x verbose=3 --depend --pre="foo*,r>=1.0,r<2" @192.168.3.1:/; echo $?



EXTENDED OPTIONS
       Extended options can be specified on the command line using the -x
       option or from the defaults file, swdefaults.  Shown below is an actual
       portion of a defaults file which show default values.

   POSIX
       These options are set in the /usr/lib/swbis/swdefaults or the
       ~/.swdefaults on the local (management host, host where swlist
       invoked).  These files on the target host are not used.


	  distribution_target_directory	 = /
	  installed_software_catalog  = var/lib/swbis/catalog/
	  one_liner		      = files|products	 # Mode when -v not given
	  select_local		      = false	   # Not Implemented
	  verbose		      = 1


   Swbis Implementation
       These options are set in the /usr/lib/swbis/swbisdefaults or the
       ~/.swbis/swbisdefaults file.


	 swlist.swbis_no_getconf = true # true or false
	 swlist.swbis_shell_command = detect # {detect|sh|bash|posix|ksh}
	 swlist.swbis_no_remote_kill = false # true or false
	 swlist.swbis_local_pax_write_command=detect #{pax|tar|gtar|detect}
	 swlist.swbis_remote_pax_write_command=detect #{pax|tar|gtar|detect}
	 swlist.swbis_local_pax_read_command=tar #{pax|tar|gtar|star}
	 swlist.swbis_remote_pax_read_command=tar #{pax|tar|gtar|star}
	 swlist.swbis_remote_shell_client=ssh
	 swlist.swbis_forward_agent=True


RETURN VALUE
       0 if all targets succeeded, 1 if all targets failed or internal error,
       2 if some targets failed and some succeeded.  When checking
       dependencies, 3 if the given sw_specs failed as dependencies, 0 if
       succeeded.

NOTES
	Multiple ssh-hops is an implementation extension.

REQUISITE UTILITIES
       The swbis distributed utilities require bash, public domain ksh, or
       Sun's /usr/xpg4/bin/sh to be present on the target host.	 If the
       swbis_shell_command extended option is set to 'detect' you don't have
       to know which one is present, otherwise you may specify one explicitly.

       A POSIX awk is required, and with the ability to specify several
       thousand bytes of program text as a command argument.  GNU awk  works,
       as does the ATT Awk book awk, and the awk on BSD systems.  See the
       INSTALL file for further details regarding a small issue with the
       OpenSolaris (c.2006) awk.

       Tar or pax is used for internally for data transfer.  You may specify
       which one.  swlist and swverify require either GNU tar or pax be
       present on a host.  You may set auto detection for this requirement

       swlist.swbis_local_pax_write_command=detect #{pax|tar|gtar|detect}
       swlist.swbis_remote_pax_write_command=detect #{pax|tar|gtar|detect}



       GNU Privacy Guard, gpg is required for verification of package
       signatures.

FILES
       /var/lib/swbis/catalog # Location of installed catalog
       /usr/lib/swbis/swdefaults
       /usr/lib/swbis/swbisdefaults
       $HOME/.swbis/swdefaults
       $HOME/.swbis/swbisdefaults



APPLICABLE STANDARDS
       ISO/IEC 15068-2:1999, Open Group CAE C701

SEE ALSO
       info swbis

       swbis(7), sw(5), swbisparse(1), swign(1), swverify(8)

IDENTIFICATION
	swlist(8): The query/listing utility of the swbis project.
	Author: Jim Lowe   Email: jhlowe at acm.org
	Version: 1.6
	Last Updated: 2006-07
	Copying: GNU Free Documentation License

BUGS
       swlist is subject to breakage if a user's account on an intermediate
       (or terminal) host in a target spec is not configured to use a Bourne
       compatible shell. (This breakage may be eliminated by use of the --no-
       getconf option as explained above.)

       swlist does not currently implement the -v,-a options.  Listing
       products in a distribution is not supported.  Operating on a
       distribution in directory form is not supported.	 The catalog query
       funtions are implemented in awk and subject to its bugs.



								     swlist(8)
