\input texinfo   @c -*-texinfo-*-

@comment $Id: swbis.texi,v 1.1 2004/07/31 03:34:48 jhl Exp jhl $
@comment %**start of header
@setfilename swbis.info
@include version.texi
@settitle Swbis Manual 
@syncodeindex pg cp
@comment %**end of header
@copying
This manual is for swbis
(version @value{VERSION}, @value{UPDATED}),
which is a implementation of the POSIX System Administration -- Part 2: Software Administration
conforming to IEEE Std 1387.2-1995 (ISO/IEC 15068-2) and Open Group CAE C701.
Currently, not all of the standard is implemented.  There are extensions for package authentication.
Extensions to the standard are indicated as such in this document.

Copyright @copyright{} 2005 James H. Lowe, Jr.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the
license is included in the section entitled ``GNU Free Documentation
License.''

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@end quotation
@end copying

@dircategory Texinfo documentation system
@direntry
* swbis: (sample)Invoking sample.
@end direntry

@titlepage
@title swbis Manual 
@subtitle for version @value{VERSION}, @value{UPDATED}
@author James H. Lowe, Jr.  (@email{jhl@infionline.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c @contents

@ifnottex
@node Top
@top swbis

@insertcopying
@end ifnottex

@menu
* Copying This Manual::
* About This Manual:: 
* Intro:: 
* Glossary:: 
* Status:: What features are working?
* Applicable Standards::
* Other Resources::
@sp 1
Using swbis
@sp 1
* Host Requirements::
* Invoking swbis::
* Configuring swbis::
* Packaging Manual::
* Creating Signed Distributions::
* Authenticating Software: (swbis_swverify)VERIFYING SIGNATURES
* Installing POSIX Distributions::
* Installing RPM Packages::
* Translating RPM Format Packages to a POSIX Distribution::
@sp 1
Notable Features of the Swbis Implementation
@sp 1
* Remote Host Operations::
* GNU Toolset Orthogonality::
* Package Layout and Interchange Format Mimicry::
@sp 1
Major Structures of Swbis
@sp 1
* Packaging Format: (swbis_swpackage)SWPACKAGE OUTPUT FORMAT
* Package Security Attributes: (swbis_sw)PACKAGE SECURITY
* Software Definitions: (swbis_sw)SOFTWARE DEFINITIONS
* Extended Definitions: (swbis_sw)EXTENDED DEFINITIONS
* Software Definitions Files: (swbis_sw)SOFTWARE DEFINITION FILES
* Packaging Layout: (swbis_sw)SOFTWARE PACKAGING LAYOUT
* Installed Software Catalog: (swbis_swinstall)INSTALLED SOFTWARE CATALOG
* User and Distributor Defined Meta-Data: (swbis_sw)DISTRIBUTOR KEYWORDS 
@sp 1
Reference
@sp 1
* Command Reference::
* Example Package: (swbis_sw)EXAMPLE PACKAGE

* Index::
@end menu

@include signing.texi
@include status.texi
@include invoke.texi
@include copying.texi
@include standards.texi
@include commands.texi
@include glossary.texi
@include configure.texi

@node Intro
@unnumbered Introduction
@chapter Intro

The swbis project is a from-scratch implementation of the POSIX
spec IEEE Std 1387.2-1995 which describes a format and utilities for
software packaging.  The scope of the POSIX spec includes a package
format, meta-data file format, and utilities for package creation,
installation, query, listing, and verification.

The swbis implementation supports package authentication meta-data in
the form embedded GPG signatures and strong cryptographic digests.

Other features of the swbis implementation are direct use of GNU Privacy
Guard for signature creation and verification, direct use of the Ssh client
for remote host operations, GNU tar format compatibility, no new utility or
program requirements for remote installation beyond POSIX compatible GNU 
utilities that are probably already present on all GNU and GNU/Linux hosts.

The swbis implementation can also install RPM packages or translate an
RPM package to a POSIX package in tar format with a single leading directory.
(Currently, swinstall does not execute installation control scripts).

@node About This Manual
@unnumbered About This Manual
This manual contains information not found in the Unix-style
Manual Pages such as a user guides, Tutorials, and Internal design features,
however, the Manual Pages and this manual share common source
and many sections transparently reference a different rendering of
the Manual Page source documents.

@node Other Resources
@unnumbered Other Resources
Other sources of documentation include ISO/IEC or IEEE printed standard,
the online version of the Open Group Specification CAE C701.

The swbis man pages are maintained and may be considered authoritative.

Documentation from other implementations based on the Standard likely
describe features that are a superset of the POSIX spec, whereas, the
swbis implementation currently is a subset, hence, may not now or
ever apply to swbis.

@node Packaging Manual
@unnumbered Packaging Manual
@menu
* Swbis Packaging Conventions: (swbis_sw)SWBIS PSF CONVENTIONS
* PSF Examples: (swbis_swpackage)SAMPLE PRODUCT SPEC FILES
@end menu

Currently, @command{swpackage} does not enforce requirements for
revision and name meta-data that other the 'swinstall' might need.
Therefore you should perform a test install of your package. The preview '-p' option
of @command{swinstall} internally simulates most of the install operation
but does not alter the file system.  The example below previews the package
on standard input.
@example
        swinstall -p -x verbose=6 -s - < your_package
@end example

Other restrictions of the swbis implementation are the default values for
the 'dfiles' and 'pfiles' attributes (which are 'dfiles' and 'pfiles') must
be used for minimal layout packages, i.e. packages that have the product and fileset
control directories specified as empty strings (i.e have a minimal package layout).


The input file to @command{swpackage}is a called a Product Specification File
or PSF.
It contains information to direct @command{swpackage} and information that is
package meta-data [that is merely transferred unchanged into the global
INDEX file].

   A PSF may contain object keywords, attributes (keyword/value pairs)
and Extended Definitions (@xref{(swbis_sw)EXTENDED DEFINITIONS}.)  An object keyword connotes
a logical object or software structure supported by the standard.  An
object keyword does not have a value field after it, as it contains
attributes and Extended Definitions.  An attribute keyword conotes an
attribute (i.e. keyword/value pair) and always has a value.

   Attribute keywords not recognized by the standard are allowed and
are transferred into the INDEX file.  Object keywords not recognized by
the standard are not allowed and will generate an error.  Extended
Definitions may only appear in a PSF (never in a INDEX or INFO created
by swpackage).  Extended Definitions are translated [by swpackage] into
object keywords (objects) and attributes recognized by the standard.

   Comments in a PSF are not transferred into the INDEX file by the
swbis implementation of @command{swpackage}.

   The file syntax is the same as a INDEX, or INFO file.
@xref{(swbis_sw)SOFTWARE DEFINITION FILES}.

A PSF may contain all objects defined by the standard as well as extended
definitions.

   For additional information see XDSA C701
http://www.opengroup.org/publications/catalog/c701.htm, or sw(5) manual
page.

@node Installing POSIX Distributions
@unnumbered Installing POSIX Distributions
This is as simple as:
@verbatim
     swinstall <your-package
@end verbatim
The default target directory is always '/'.
@xref{Command Reference}.

@node Host Requirements
@unnumbered Host Requirements

'swbis' is designed to be as non-intrusive as possible and
this applies to host requirements which are minimal.

For package creation you need @command{uuidgen} and if creating signed
distributions you need @command{gpg}.

For package installation you need
@command{sh}, @command{bash}, @command{getconf}, @command{dd}, @command{tar},
@command{hostname}, @command{mkdir}, @command{expr}, @command{echo}, @command{test}, @command{sleep}.

Installation of packages on remote hosts (i.e. using swinstall with a remote host target)
does not require swbis to be installed there.

The @command{swverify} and @command{swign} commands are shell scripts which may have additional
requirements.

Here are the technical details about requirements for @command{swinstall}, the same
apply to @command{swcopy}:

@command{swinstall} requires a Posix shell accessible by the remote shell command.
This is the remote command run by ssh (or rsh)  for  all  operations.
This command can be controlled by the --shell-command option or
the swbis_shell_command defaults file  option.   Permitted  values  are
"bash"  (/bin/bash  -s) or "sh" (/bin/sh -s) or "posix" ('PATH=`getconf
PATH` sh -s').   The default is  "posix".   @command{swinstall}  requires  the
POSIX capability of reading commands on stdin according to the specification
described in IEEE Std  1003.1,  2003  Ed.;  sh  -shell,  Section STDIN.

This requirement accommodates reading of shell program code and
data on STDIN.  This capability may not  be  present  in  some  /bin/sh
shells.   The  "/bin/sh"  on  FreeBSD-5.1 may be broken in this regard,
hence ''--shell-command=bash'' should be used for BSD hosts.  The  public
domain Korn shell (pdksh-5.2.14) seems to work OK, that is, it complies
by luck or intent with the POSIX capability of reading  data  and
code on stdin.

If  the  --no-getconf  option  is set or the swinstall.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), hostname, mkdir, expr, echo, test, sleep, read (if
not builtin).

@node Installing RPM Packages
@unnumbered Installing RPM Packages
Installing RPMs results in the RPM first being translated to a 
POSIX archive in tar format, @xref{Translating RPM Format Packages to a POSIX Distribution},
then installation by swinstall proceeds normally.
@verbatim
     swinstall --allow-rpm -s - @ host1:/mnt/test/root1 < your-0.1.arch.rpm
@end verbatim

In this example, a remote host and target path is specified.  No files will
be installed outside of the target path.
The @option{allow-rpm} may be turned on in the @file{swbisdefaults} file or
by command line option.

@node Translating RPM Format Packages to a POSIX Distribution
@unnumbered Translating RPM Format Packages

Translation of RPMs is done in memory. No temporary files are
created.  Large RPMs or RPMs with many small files may take many seconds
or several minutes to translate.

Translation is performed by the swbis library executable @command{lxpsf} and
@command{swpackage}.
@verbatim
     /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
     swpackage -Wsource=- -s@PSF
@end verbatim

The @command{lxpsf} is the only swbis program with RPM library dependencies, and
this is the program that does the actual meta-data translation.

Depending on compilation options, it is possible to disable RPM translation
ability (this is the default), or specify that the built-in library is to be
used.  The built-in library is base on RedHat rpm release 3.0.5.  If the 
built-in compile option, @option{with-self-rpm} is used there are no dependencies on
other packages.

The easiest way to invoke translation is with the @option{--unrpm} of
@command{swpackage} and @command{swcopy}.
@verbatim
       swcopy --unrpm -s - @- <your-0.1.arch.rpm | tar tvf -
           -or-
       swpackage --unrpm @- <your-0.1.arch.rpm | tar tvf -
@end verbatim

To verbosely preview the translated RPM:
@verbatim
       swcopy --unrpm -s - @- | swinstall -p -x verbose=5
@end verbatim

@node Remote Host Operations
@unnumbered
swbis is network transparent from the ground up.  It uses ssh (or rsh) to
establish remote connections.  Communication then takes place on standard
input, output and error as established by the remote shell client on the
local host.  Operations which are entirely local are symmetric with
remote operations in that swbis communicates via Unix pipes and makes
no distinction based on the locality of the communication endpoints.

swbis uses the ssh client program 'ssh' as found by the PATH variable.
swbis adds the '-T' option to disable pseudo-tty allocation.

swbis supports an extension to the POSIX target syntax to support
multiple host hops.  Use of password authentication for multi-hop
targets requires use of the SSH_ASKPASS program and redirection
of X11 connections over the secure ssh channel.  See the 'ForwardX11'
option in the ssh client configuration.  Use of public key authentication
is more reliable since the authentication agent is forwarded by use of
the '-A' ssh option.

Important Note:  When making a multi-hop connection
using either authentication method, the authentication credentials appear
on the intermediate hosts and are subject to hijack, hence, the intermediate
hosts' trust requirement should be no less than the terminal host's.

@node GNU Toolset Orthogonality
@unnumbered
One overriding design goal of swbis is zero re-invention.  To that
end, swbis uses '/usr/bin/gpg' for signing and authentication.  It uses
'rsh' and 'ssh' for remote connections.  It uses 'bash' (as a POSIX shell)
for command processing.
It uses 'pax' or 'tar' for archive installation.
It uses a file system directory structure as the database for installed 
software.

@node Package Layout and Interchange Format Mimicry
@unnumbered
swbis is non-intrusive relative to current practice
for data interchange and storage using tar archives.

swbis supports a 'minimal package layout'
(@xref{(swbis_sw)Minimal Package Layout}.)
This layout follows the POSIX spec but has nil control directories
(Note: nil control directories are not attested to in the POSIX specification).

By specifying control directories as empty strings and specifying a non-empty
leading directory for the archive, a swbis POSIX package may be used
inter-changeably with free software tar archive source packages which commonly
have a leading package directory.

Binary (run-time) packages follow the same pattern except the leading
directory is specified as an empty string as well.  The result is a run-time
package directly installable by @command{tar}.

The non-inventive nature of swbis extends into the format level as well.
swbis has its own archive writing utility, @command{swpackage}, and it is
self contained, however, it writes tar archives which are identical to
archives produced by GNU tar.  

This data format mimicry has several advantages.  It forms the basis for
a very brittle regression test, namely bit-for-bit sameness with GNU tar.
This also preserves symmetry between a package archive and package directory in
that swbis archives installed with tar can be repackaged with GNU tar with no
bit-wise change relative to the original.

Together, these layers of mimicry are put to practical application
in the @command{swign} program (@xref{(swbis_swign)}) which 
creates GPG signed POSIX packages without any data copying except by GNU tar.

@node Index
@unnumbered Index

@c @printindex cp
@c @summarycontents
@c @contents


@bye

