# swlist(8)

### Contents

- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- IMPLEMENTATION EXTENSIONS
- USAGE EXAMPLES
  - List Products
  - Test Dependencies
- EXTENDED OPTIONS
  - POSIX
  - Swbis Implementation
- RETURN VALUE
- NOTES
- REQUISITE UTILITIES
- FILES
- APPLICABLE STANDARDS
- SEE ALSO
- IDENTIFICATION
- BUGS

### 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

           -W shell-command=NAME
                  Defaults File Option: swbis_shell_command
                  NAME may be one of "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 = false # true or false
             swlist.swbis_shell_command = posix # {sh|bash|posix|ksh}
             swlist.swbis_no_remote_kill = false # true or false
             swlist.swbis_local_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
             swlist.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar|swbistar}
             swlist.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
             swlist.swbis_remote_pax_read_command=pax #{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

           swlist requires a Posix shell accessible by the remote shell command.
           This is the remote command run by ssh (or rsh) for all operations.
           swlist makes use of the system 'awk' program for querying the installed
           software catalog, it should work.  swlist is tested with gawk (GNU awk)
           and the AT awkbook awk.

           If the --no-getconf option is set or the swlist.swbis_no_getconf
           defaults option is "true" then the remote command is '/bin/sh -s'.  Use
           of the no-getconf option is needed for communication with user accounts
           on remote machines whose login shell is not a Bourne shell (e.g. csh)
           such as root on some default BSD installations.  Other *nix systems may
           require use of getconf because their /bin/sh is broken or not Posix
           enough (e.g. Sun platforms).  Still other systems may not have getconf.

           Other utilities required to be in $PATH on the remote host are: dd, pax
           (or tar|star|gtar), mkdir, echo, test, sleep, read (if not builtin).

### FILES

           /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: 0.950
            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)