This is info/swbis_swbis.info, produced by makeinfo version 4.9 from
stdin.


File: swbis_swbis.info,  Node: Top,  Next: NAME,  Up: (dir)

1 SWBIS" "7
***********

* Menu:

* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* EXAMPLES::
* COMMANDS OVERVIEW::
* CONFIGURATION::
* HOST REQUIREMENTS::
* DISCUSSION::
* COPYING::
* PRONUNCIATION::
* APPLICABLE STANDARDS::
* SEE ALSO::
* FILES::
* IDENTIFICATION::
* BUGS::


File: swbis_swbis.info,  Node: NAME,  Next: SYNOPSIS,  Prev: Top,  Up: Top

1.1 NAME
========

swbis -- Distributed Software Administration


File: swbis_swbis.info,  Node: SYNOPSIS,  Next: DESCRIPTION,  Prev: NAME,  Up: Top

1.2 SYNOPSIS
============

     swbis \<sw_utility\> [options] [software_selections] [@targets]
     \<sw_utility\> [options] [software_selections] [@targets]


File: swbis_swbis.info,  Node: DESCRIPTION,  Next: OPTIONS,  Prev: SYNOPSIS,  Up: Top

1.3 DESCRIPTION
===============

swbis is a software administration system for GNU/Linux systems and
systems that are UNIX system-like. It implements the Open Group's CAE
Spec C701 (XDSA) Distributed Software Administration.  This spec
closely follows ISO/IEC 15068-2:1999 (now withdrawn) which was
identical to IEEE 1387.2:1995.  The implementation relies on POSIX
functionality as provided by a typical GNU system.  It has security
enhancement extensions that use GNU Privacy Guard.  Although swpackage
is a self-contained tar writing utility and swinstall will use generic
tar for file loading, several features are based on bit-for-bit
sameness with the GNU tar POSIX tar interchange format, hence, GNU tar
is a special tool requirement for swbis.


File: swbis_swbis.info,  Node: OPTIONS,  Next: EXAMPLES,  Prev: DESCRIPTION,  Up: Top

1.4 OPTIONS
===========

The  selection@target syntax supports multiple selections and targets.
The same selection spec applies to all the targets.  A single
'Commercial at' '@' separates the two lists.  Software selections apply
within a single distribution tarball or within a single directory
representing installed  software.  Software selections don't specify a
source file.  The source file is specified by a separate option for
utilites that use the  target as a destination, and by the target if
the source is the destination.

* Menu:

* Software Selections::
* Targets::


File: swbis_swbis.info,  Node: Software Selections,  Next: Targets,  Up: OPTIONS

1.4.1 Software Selections
-------------------------

Software Selections specify, by a software_spec, objects which to
operate.  A software_spec consists of a period '.' delimited list of
tags followed by a comma and a comma delimited list of version
identifiers for revision, qualifier, vendor_tag, architecture,
location, denoted by the letters r,q,v,a,l.

The important tags of familiar repute are product.tag and
product.revision along with an optional product.vendor_tag.  These
correspond to RPMTAG_NAME, RPMTAG_VERSION, and RPMTAG_RELEASE
attributes.  These are specified in a software_selection by example
thusly:

        # Note: Quotes are needed to prevent command-line interpretation
        "*"                        # all packages
        r==3.1                     # Any package with revision 3.1
        somepackage                # all packages named 'somepackage'
        somepackage,r">"2          # and revision greater than 2
        somepackage,r">"2,r"<"3    # and revision greater than 2 and less than 3
        somepackage,r">"2,v=hal    # and by vendor 'hal'

Logical alternation or 'OR' is supported by using a second
software_spec on the command line. software_specs are separated by
whitespace.


File: swbis_swbis.info,  Node: Targets,  Prev: Software Selections,  Up: OPTIONS

1.4.2 Targets
-------------

Targets are hosts or files on a host.  The syntax follows the familiar
host:file convention but differs in that an unadorned name is a host
not a file.  To impose interpretation as a file prefix with a colon ':'
or use an absolute path (i.e. 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.
                  ;


File: swbis_swbis.info,  Node: EXAMPLES,  Next: COMMANDS OVERVIEW,  Prev: OPTIONS,  Up: Top

1.5 EXAMPLES
============

Unpack a tarball on host1 and host2:

        swcopy -s :somepackage-1.0.tar.gz --extract @ host1 host2

List installed entries matching the software selections:

        swlist somepackage,"r>2" @ host1:/ host2:/
        swlist "kde*" @ 192.168.2.2

List the architectures of the specified hosts:

        swlist -x verbose=3 -a architecture @ localhost 192.168.2.2 host1 host2

Install a package from stdin to a location, l=/unionfs/foo-1.0, and a
"exp" qualification:

         swinstall q=exp,l=/unionfs/foo-1.0 @ 192.168.2.2

Remove a package named somepackage

         swremove somepackage @ 192.168.2.2:/

Make a tarball according to the recipe file myPSF:

         swpackage -s myPSF @- | tar tvf -


File: swbis_swbis.info,  Node: COMMANDS OVERVIEW,  Next: CONFIGURATION,  Prev: EXAMPLES,  Up: Top

1.6 COMMANDS OVERVIEW
=====================

* Menu:

* POSIX Commands::
* Swbis Specific Commands::


File: swbis_swbis.info,  Node: POSIX Commands,  Next: Swbis Specific Commands,  Up: COMMANDS OVERVIEW

1.6.1 POSIX Commands
--------------------

Utilities specified by C701 and ISO/IEC 15068-2:1999 include the
following:

swpackage(8)

Create a tarball according to a recipe file.

swcopy(8)

Copy a distribution from host to host.

swverify(8)

Verify a software distribution signature.

swinstall(8)

Install a software distribution.

swlist(8)

List software information.

swremove(8)

Remove packages


File: swbis_swbis.info,  Node: Swbis Specific Commands,  Prev: POSIX Commands,  Up: COMMANDS OVERVIEW

1.6.2 Swbis Specific Commands
-----------------------------

Utilities unique to swbis.

swign(1)

Create the signed meta-data directory, catalog/, of the contents of the
current directory and optionally write the entire directory, including
the signed catalog as a tar archive.

\<libexecdir\>/swbis/swbistar

Archive writing (creation) utility, useful for testing.

\<libexecdir\>/swbis/swbisparse

Stand-alone parser of Posix Metadata files, useful for testing.

\<libexecdir\>/swbis/arf2arf

Archive decoder/checker, Used by swverify.

\<libexecdir\>/swbis/lxpsf

Archive translator, used by swpackage to translate RPM packages.


File: swbis_swbis.info,  Node: CONFIGURATION,  Next: HOST REQUIREMENTS,  Prev: COMMANDS OVERVIEW,  Up: Top

1.7 CONFIGURATION
=================

* Menu:

* Configuration Files::
* Strategy for Compatibility with Existing Hosts::


File: swbis_swbis.info,  Node: Configuration Files,  Next: Strategy for Compatibility with Existing Hosts,  Up: CONFIGURATION

1.7.1 Configuration Files
-------------------------

All of the utilities share the same configuration files: swdefaults and
swbisdefaults.  The files are sourced on the local management host and
ignored (if present) on the remote target host. Below are commands that
give information about them.  All the utilities support these options
and the defaults are separate for each utility, swcopy is shown as an
example.

      swcopy --show-options-files  # Show locations of existing files to stdout
      swcopy --show-options     # Show options with a shell assignment syntax
      swcopy --no-defaults --show-options  # Show builtin defaults

The syntax is:

      # Comment
      # Here optionName applies to all utilities
      # the whitespace around the '=' is optional
      optionName = value # Comment

      # In addition a option can be applied to a specific utility
      # overriding the general one and the built-in default
      swutilityName.optionName = value


File: swbis_swbis.info,  Node: Strategy for Compatibility with Existing Hosts,  Prev: Configuration Files,  Up: CONFIGURATION

1.7.2 Strategy for Compatibility with Existing Hosts
----------------------------------------------------

The most important utiltities on which swbis relies is a POSIX shell,
/bin/sh, and the system tar utility, usually /bin/tar.

The shell must have specific compliance to POSIX described the POSIX
sh(1) manual page (IEEE Std 1003.1, 2004 Edition, Section STDIN)
regarding its use of stdin when it invokes a command that also uses
stdin.  GNU Bash, public-domain Korn shell (pdksh), and OpenSolaris
/usr/xpg4/bin/sh have this feature.  Other shells including ash, dash,
ATT ksh93, and /bin/sh on BSD and UNIX(tm) system do not.  Most
GNU/Linux systems linked /bin/sh to bash however this is not always the
case.

Therefore, the most reliable and least intrusive strategy is to install
GNU Bash as /bin/bash all on host that must interoperate with swbis and
set the appropriate defaults described below.

     swbis_no_getconf               = true # true or false, false=use getconf
     swbis_shell_command            = bash # {sh|bash|posix|ash|ksh}

Regarding tar, it is used for file loading (installation) and also
during verfication of installed software (as a means to copy and
inspect the installed files state).  For installation, any tar will
work as no non-traditional options are specified.  For verification of
installed software, GNU tar is required due to the use of reading a
list of files to archive.

The configuration options, in swbisdefaults allow some flexibilty here

     # swbis_local_pax_write_command  = tar  # {pax|tar|star|gtar}
     # swbis_remote_pax_write_command = tar  # {pax|tar|star|gtar}
     # swbis_local_pax_read_command   = tar  # {pax|tar|star|gtar}
     # swbis_remote_pax_read_command  = tar  # {pax|tar|star|gtar}
     #    tar is the built-in default
     swverify.swbis_local_pax_read_command   = gtar  # {pax|tar|star|gtar}
     swverify.swbis_remote_pax_read_command  = gtar  # {pax|tar|star|gtar}

This allows keeping and using the system '/bin/tar', and only using GNU
tar installed as /bin/gtar for verification.

Other important options are:

     swcopy.swbis_allow_rpm       = true  # Enable automatic translation
     swinstall.swbis_allow_rpm    = true  # Enable automatic translation
     swcopy.swbis_no_audit        = true  # Copy as arbitrary data, true or false
     swbis_remote_shell_client    = ssh   # {ssh|rsh}
     swbis_forward_agent          = true  # Set ssh -A for multi-hop (>1) jumps


Here is a incomplete explanation of each option

Extended Option: swbis_local_pax_read_command Extended Option:
swbis_remote_pax_read_command

If installing on a system, any tar will work.  GNU tar is required when
using swign to create a signed archive or directory.  If pax is
selected as the archive read command (for installing), errors will be
returned if the installation is not by a root user (or if not root, if
the package contained files with different ownerships than the current
user).

Extended Option: swbis_local_pax_write_command Extended Option:
swbis_remote_pax_write_command

These are relevant to swcopy.  swpackage is self-contained and does not
use any file system tar-like utility.  swign does not read the options
files and assumes that tar is GNU tar.

Extended Option: swbis_shell_command

This is the command bash -s, or ksh -s, etc. which is run on the remote
host.  If the value is posix then the command is PATH=getconf PATH sh
-s hence the need to interpret back quotes and the need for getconf.
The /bin/sh on most systems, except GNU systems will not work with
swbis.  The best solution, of course, is to put bash on all your hosts
and disable use of getconf.  Some systems such as NetBSD have neither
bash nor getconf. On these systems set the option to ksh, which for
example, NetBSD does have.

Account Login Shell

The login shell may be any shell, however, if a host will ever be a
intermediate host in a multi-hop target, then it should be a POSIX
shell.  This requirement is due to the escapement of PATH=`getconf
PATH` sh -s which assumes processing by a intermediate host.

Extended Option: swbis_forward_agent

The default value is True.  This sets the -A in the ssh client for
multi-hop targets.  There are security considerations when forwarding
the authentication agent.


File: swbis_swbis.info,  Node: HOST REQUIREMENTS,  Next: DISCUSSION,  Prev: CONFIGURATION,  Up: Top

1.8 HOST REQUIREMENTS
=====================

Requirements are: a POSIX shell (either GNU bash or public domain ksh)
and tar.  Swbis may be configure to use pax or GNU tar installed as
gtar.  GNU tar is required by swign when making signed archives or
directories.  Neither tar nor pax is required by swpackage which itself
is a self-contained tar writing utility.  Swbis can be configure to
find the POSIX shell via getconf such as /usr/xpg4/bin/sh on Solaris
hosts.

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.

GNU Privacy Guard, gpg is required for verification and  signing.  Use
of the passphrase agent gpg-agent is supported so as to avoid telling
swpackage your passphrase.  When swverify uses gpg, a FIFO  is
constructed and deleted.  /dev/null and /dev/zero are required.

For verifying package tarballs, only swverify and gpg is required.  For
verifying the unpacked tarball (i.e. as a signed directory) GNU  tar,
awk,  sha1sum,  md5sum  (or  openssl)  and  various other utilities are
required.

When a host is participating in remote connections via ssh/rsh, either
as the terminal target host or intermediate host, the login shell for
the user must be a Bourne compatible shell, for example /bin/sh.  Note:
this need not be the system POSIX shell.


File: swbis_swbis.info,  Node: DISCUSSION,  Next: COPYING,  Prev: HOST REQUIREMENTS,  Up: Top

1.9 DISCUSSION
==============

* Menu:

* Background::
* Distributed Software Administration::
* A Directory Content Checker::
* Package Security::
* Extensibility::
* Support for Unprivileged Users::


File: swbis_swbis.info,  Node: Background,  Next: Distributed Software Administration,  Up: DISCUSSION

1.9.1 Background
----------------

The spec describes a format for storing package meta-data in a software
distribution and a set of utilities.  The meta-data is stored in-band
for format level compatibility.  The meta-data is separated by placement
in a specially named directory, catalog/.  The spec goes further and
describes how multiple products, for example a distribution archive
containing products for multiple architectures, can be placed in a
separate control directories within the distribution archive.  This is
supported along with an extension to allow these directories to be nil
collapsing the layout into the familiar form of a free software tarball
or run-time distribution directly installable by tar.  When the
collapsed form is used, the in-band catalog/ directory is next to (in
the same directory as) the payload files hence "catalog" becomes a
reserved word for package files.

While the swbis system has features comparable with package managers,
it has features that are of general purpose usefulness to system
administrators and developers.  These include host-to-host copying of
file system directories, advanced tarball creation methods, backward
compatibility with uses of plain tarballs, and the capability to act as
a directory content integrity checker, and the ability to translate and
install RPM format packages.


File: swbis_swbis.info,  Node: Distributed Software Administration,  Next: A Directory Content Checker,  Prev: Background,  Up: DISCUSSION

1.9.2 Distributed Software Administration
-----------------------------------------

The XDSA spec describes a syntax for distributed operations, but does
not specify any implementation approach to the problem of remote
command invocation.  The approach taken by swbis is to require nothing
that is not already present on all POSIX systems. To that end, swbis
uses rsh (or ssh) for remote connections and uses bash (A POSIX shell)
for command processing specifically using the 'bash -s' invocation for
all operations.  Using bash in this manner casts all swbis utilties as
programs that dynamically write and deliver shell program code to the
remote 'bash -s' through its standard input, which can be a secure ssh
channel.  This eliminates the requirement that swbis be installed on
the remote target host.


File: swbis_swbis.info,  Node: A Directory Content Checker,  Next: Package Security,  Prev: Distributed Software Administration,  Up: DISCUSSION

1.9.3 A Directory Content Checker
---------------------------------

The swign program creates the catalog/ directory which is, in effect, a
GPG signed manifest of the directory.  GNU tar is then used to recreate
the signed and digest  byte  streams  from the directory contents which
are never removed nor altered (except for the creation of catalog/). It
is able to do so because swpackage, which generated the original byte
streams,  matches GNU tar's output bit-for-bit. For example:

        swign  -D /usr/local/bin/checkdigest.sh  -o "" -g ""  -u  "Test User" @.
        swverify --order-catalog -d @.
               # If your file system is Ext2, then --order-catalog
               # is not required.

The  checkdigest.sh is a distributor specific shell script that is run
by swverify if it is present and part of the signed  stream.
checkdigest.sh then checks the archive MD5 and SHA1.  If this fails, it
checks the individual files'  MD5 and SHA1 digests.  [In current
versions of checkdigest,  the ownerships and permissions are not
checked individually, as swign was originally intended as a source
directory/archive signer tool.]

Use as a SCM (e.g. CVS, svn. etc) security tool easily follows by
making catalog/ a tracked directory in the SCM.  The catalog directory
is updated using the swign command.

          export SWPACKAGEPASSFD
          SWPACKAGEPASSFD=agent
          export GNUPGNAME
          GNUPGNAME="Your Name"
          swign --name-version=somepackage-1.1 -s PSF.in --no-remove @.

See the swign manual page for an example PSF.in file.


File: swbis_swbis.info,  Node: Package Security,  Next: Extensibility,  Prev: A Directory Content Checker,  Up: DISCUSSION

1.9.4 Package Security
----------------------

As implementation extensions, swbis supports creation and verification
of tar archives with embedded digital signatures, and cryptographic
digests of the archive (payload) and individual files.  The design
supports multiple signatures (each signing an identical byte stream)
and offers full package life-cycle relevance, that is, the signature
and the signed bytes are transferred into the installed catalog.


File: swbis_swbis.info,  Node: Extensibility,  Next: Support for Unprivileged Users,  Prev: Package Security,  Up: DISCUSSION

1.9.5 Extensibility
-------------------

The distribution form is extensible at the format and layout levels.
Additional distributor specific attributes (i.e. keywords) are allowed
in the meta-data files, and distributor specific control files are
allowed in the meta-data directory file layout.  The security files are
implemented as control files.  This allows adding new stronger
cryptograpic digests in the file layout while preserving back
compatibility.  The format, POSIX tar, is extensible by adoption of the
Extended Header Format specified in later POSIX revisions.


File: swbis_swbis.info,  Node: Support for Unprivileged Users,  Prev: Extensibility,  Up: DISCUSSION

1.9.6 Support for Unprivileged Users
------------------------------------

Support for unprivileged users is treated as a requirement.  swpackage
does not use a central repository and makes no copies of the source
files.  The utilities support alternate target paths and all activity
is confined within the target path.  swinstall supports the location
attribute which locates the installed files in target path but uses the
installed software catalog at the un-located target path.  Access to
the installed software catalog can be controlled via the catalog
directory sticky bit per local administrative policy.


File: swbis_swbis.info,  Node: COPYING,  Next: PRONUNCIATION,  Prev: DISCUSSION,  Up: Top

1.10 COPYING
============

Swbis is a copyrighted work.  Non-copyright holders may use and make
copies under the terms of the GNU GPL


File: swbis_swbis.info,  Node: PRONUNCIATION,  Next: APPLICABLE STANDARDS,  Prev: COPYING,  Up: Top

1.11 PRONUNCIATION
==================

Swbis is a concatenation of the command name prefix 'sw' with the
Italian suffix 'bis' meaning again, or one more time.

         Pronunciation: /es dub-u bis/
                       sw - bis
          POSIX packaging - Play it again, One more time


File: swbis_swbis.info,  Node: APPLICABLE STANDARDS,  Next: SEE ALSO,  Prev: PRONUNCIATION,  Up: Top

1.12 APPLICABLE STANDARDS
=========================

IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701,
http://www.opengroup.org/publications/catalog/c701.htm


File: swbis_swbis.info,  Node: SEE ALSO,  Next: FILES,  Prev: APPLICABLE STANDARDS,  Up: Top

1.13 SEE ALSO
=============

      info swbis
      sw(5), swpackage(8), swbisparse(1), swign(1), swverify(8), swcopy(8)
      .../libexec/swbis/lxpsf
      .../libexec/swbis/arf2arf
      .../libexec/swbis/swbisparse
      .../libexec/swbis/swbistar
     http://www.gnu.org/software/swbis/sourcesign-1.2/gendocs/manual/index.html



File: swbis_swbis.info,  Node: FILES,  Next: IDENTIFICATION,  Prev: SEE ALSO,  Up: Top

1.14 FILES
==========

catalog/  # The meta-data directory swdefaults     # Options
configuration file swbisdefaults  # Options configuration file


File: swbis_swbis.info,  Node: IDENTIFICATION,  Next: BUGS,  Prev: FILES,  Up: Top

1.15 IDENTIFICATION
===================

swbis(7)  Author: Jim Lowe   Email: jhlowe at acm.org  Version: 0.950
Last Updated: 2008-04-18  Copying: GNU Free Documentation License


File: swbis_swbis.info,  Node: BUGS,  Prev: IDENTIFICATION,  Up: Top

1.16 BUGS
=========

Not everything is implemented yet.



Tag Table:
Node: Top77
Node: NAME421
Node: SYNOPSIS564
Node: DESCRIPTION810
Node: OPTIONS1652
Node: Software Selections2323
Node: Targets3633
Node: EXAMPLES7228
Node: COMMANDS OVERVIEW8060
Node: POSIX Commands8263
Node: Swbis Specific Commands8772
Node: CONFIGURATION9511
Node: Configuration Files9743
Node: Strategy for Compatibility with Existing Hosts10849
Node: HOST REQUIREMENTS15259
Node: DISCUSSION16875
Node: Background17174
Node: Distributed Software Administration18631
Node: A Directory Content Checker19581
Node: Package Security21300
Node: Extensibility21883
Node: Support for Unprivileged Users22589
Node: COPYING23307
Node: PRONUNCIATION23535
Node: APPLICABLE STANDARDS23927
Node: SEE ALSO24206
Node: FILES24635
Node: IDENTIFICATION24873
Node: BUGS25137

End Tag Table
