
    swbis - Software Administration
    --------------------------------
    Version 0.483  (February 2006)

    swbis is a GNU package
    The official home page is http://www.gnu.org/software/swbis

    Please send bug reports to <bug-swbis@gnu.org>
    
    This version and prior versions are found at SourceForge
    http://www.sourceforge.net/projects/swbis
    
    The entry in the FSF/UNESCO Free Software Directory is
    http://directory.fsf.org/GNU/swbis.html

    Introduction
    ------------
    GNU swbis is a free and from-scratch GPL'ed implementation of
    IEEE 1387.2-1995 Std (Part 2: Software Administration) which
    describes a format and utilities for software packaging.  The
    GNU implementation has extensions for including GPG signatures,
    MD5 and SHA1 message digests of the files and archive payload
    section.  [The IEEE standard is superseded by ISO 15068-2,1999,
    and it is almost identical to the Open Group spec CAE C701 which
    is available on the Internet at no monetary cost].

    The swbis project provides features similar to other packaging systems
    such as utilities for package creation, installation, and verification.
    The implementation of these features are, however, unique in that
    swbis is 1) non-intrusive to current packaging practice, 2) completely
    orthogonal to the GNU toolset, 3) makes no new requirements on system
    provisioning, and 4) is completely network transparent.
    
    It achieves the first because a POSIX package is a tar archive, and,
    swbis is general and flexible enough so that a swbis package can look
    just like a free software source tarball.  When packaging a directory,
    such as a source directory, swbis provides a tool to generate a GPG
    signed tar archive using GNU tar, avoiding use of new tools.
    Secondly, it is orthogonal with existing tools for verification and
    file loading, namely gpg and tar which swbis uses directly.  Thirdly,
    swbis can install and copy packages to all existing GNU/Linux, BSD,
    and Unix hosts whether or not swbis is installed on that host.  Swbis
    achieves this by relying on the POSIX shell's capability to read
    commands and data on the same standard input stream.  Lastly, network
    transparency is achieved because the process interface is a Unix
    pipe, namely standard input, whose location can easily be generalized
    by a remote shell client program such as ssh.
    
    * ISO/Posix Utilities:

       swcopy - Distribution copying utility.
    
             * Supports multiple ssh-hops to remote target or source.       
             * Uses ssh, sh, dd, and choice of pax, tar, star, or gtar.
             * Does not have to be installed on the target host.
             * target or source host may be any POSIX.2 conforming host.
             * Supports remote-source to remote-target copies.
    
       swpackage -  Packages files according to a PSF file.
    
             * Complete implementation of Extended Definitions.
             * Stand-alone operation, no use of temporary files.
             * Output format is bit-for-bit identical to GNU tar.
             * Supports creation of GPG embedded signature, and sha1,
               md5sum digests of the package payload section.
            
       swverify -  Authenticates a signed package.
    
             * Authenticates packages signed by swpackage.
             * Verifies installed software (partially implemented).
             * Authenticates the GPG signature in the installed software.

       swinstall  -  Install a posix package.  (alpha as of 2004-02-15)
                 
             * 'swinstall' does not have to be installed on the target host.
             * The target or source host may be any POSIX.2 conforming host.
             * creates an installed software catalog where the GPG signature
               can be verified using 'gpg'
             * Uses ssh for remote connections.
             * Supports multiple ssh-hops to remote target or source.
             * Uses tar (or pax) to install the files.
             * Supports full error monitoring during control script execution
               and records exit status and installation states.
    
    * Non-ISO/Posix (Ad Hoc) Utilities:

        swign  -  Produces signed tar archives using GNU tar and
                  swpackage and gpg as supporting tools.  This utility is
                  useful for creating signed source tarballs.
            
        lxpsf  -  The first step translator for RPM packages.  It translates
                  an RPM into a tar archive containing a PSF file which
                  further directs translation to a Posix package by 'swpackage'.
    
        arf2arf   -  Internal Library utility to extract and verify the signed
                     and digested byte streams.
    

    Howto make your own signed tarballs For the really impatient
    ------------------------------------------------------------
    Type
           swign @- | tar tvf -
             
    see the info document, type
              info swbis 
	         or
	      info -f doc/info/swbis

    Documentation
    -------------
    Info Document: type
          info swbis
              -or-
          info -f ./doc/info/swbis.info

    Manual pages:  sw(5), swcopy(8), swpackage(5), swpackage(8)
    swverify(8), swign(1)
          For example:
	    nroff -man <doc/man/man8/swpackage.8 | less -r

    How to install
    --------------
    See the file INSTALL.
 
    Features of the POSIX Standard
    ------------------------------
    
        - Uses existing data formats: tar and cpio.
    
        - Package metadata is contained in ascii text files.
    
        - The package generation spec file supports explicit
          overriding of file attributes, ability to specify a
          different source filename from the name appearing in the
          package, the ability to specify all files in a directory,
          among others.
   
        - Supports multiple products in a single distribution file.
    
        - Supports selection of products based on based on architecture
          and system identification attributes.
    
        - Allows run-time packages to have control directories and 
          a leading package directory.  This can be useful for ISVs who
          wish to support manual installation by unpacking with tar
          and execution of a custom setup script.
  
        - Supports a rich set of control scripts.
 
        - Explicitly allows for additional vendor attributes
          and additional vendor specific control files.

        - Specifies an interface for copying and installing to
          remote hosts.
    
    Features of the swbis implementation
    ------------------------------------
            
        (All of these are implemented unless stated otherwise.)
    
        - Non-root users are able to invoke root installs on
          remote hosts via ssh authentication.
    
        - Network transparent copying and installation.
          (To swbis, local and remote installs are the same.)
    
        - No new target requirements.  Relies on a POSIX shell and
          a minimal set of POSIX utilities. (swbis is not required
          on the target remote host.)
    
        - Supports multiple host-to-host hops to a target host.
            
        - Network connection is made by direct use of ssh or rsh.
    
        - 'swpackage' writes an archive to STDOUT, and makes no temporary
          copy of the package.
    
        - 'swpackage' supports nil ("") control directories which
          allows a traditional source tar archive to be cast as a POSIX
          package with no change to existing file layout, and allows a
          run-time package to have a form that is directly installable
          using tar [similar to slackware packages].

        - Supports a md5sum attribute for storage files.
    
        - Supports cryptographic authentication (Package signing) by
          use of Vendor Defined attributes consisting of a control file 
          containing a signature of the catalog section, and control files
          containing a md5 and sha1 digest of the storage section.
    
        - Multiple signature control files are supported to accommodate
          upstream and downstream signers.
    
        - All package signatures are transferred (by swinstall) into
          the installed software catalog where they can be verified
          directly by 'gpg' alone.  That is, the signature is valid
          throughout the package life-cycle, and can be verified by
          'gpg' at every point in the life-cycle.

        - swpackage mimics GNU tar formats bit-for-bit which forms a
          basis for internal testing; and, allows verification of the GPG
          signature and archive md5 digest (of the unpacked signed package)
          using GNU tar and gpg [under some circumstances and with
          constraints].
    
    Development Language
    --------------------
        swbis is written in ANSI C and C++.
        Some utilities are portable Posix shell and utilities.
        The swpackage utility is the only C++ program, all other
        programs should not use C++.  The parts of swpackage that are
        written in object-oriented (late dispatch of virtual functions)
        C++ are limited to the package compiler section.  Many of the
        C++ opjects are wrappers around C objects and do not employ
        polymorphism. Since swpackage is complete, no new C++ is
        needed for this project.
    
    
End of README
