This is ../info/swbis.info, produced by makeinfo version 4.7 from
swbis.texi.

   This manual is for swbis (version 1.0pre0, 08 Aug 2008), 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 (C) 2008 James H. Lowe, Jr.

     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."

INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Swbis: (swbis).               POSIX software packaging utilities.
END-INFO-DIR-ENTRY


File: swbis.info,  Node: A PSF for Source Packages,  Prev: A Minimal PSF,  Up: Making PSFs for Package Creation

A PSF for Source Packages
=========================

This PSF packages all the files in the directory where `swpackage' is
invoked.  It uses NUL control directory names which maintain the
package directory structure.

# File: Example PSF for source packages
#  This file may be copied without restriction.

# The distribution object is required, thought it need not
# have any attributes.

distribution

# Attributes in the distribution are mostly ignored by the utilities
# although distributor control files that pertain to the
# distribution as a whole are properly placed here.  Two examples
# of files that are useful here are:

AUTHORS < AUTHORS   # This places the file in ./catalog/dfiles
COPYING < COPYING   # This places the file in ./catalog/dfiles

# This places the checkdigest script in ./catalog/dfiles/checkdigest
# For a description of the checkdigest script see info 'swbis'

  checkdigest  < bin/checkdigest.sh

# The vendor object provides attributes to describe
# the distributor.  At this time, how these attributes
# are used is not addressed.

# The vendor object is optional

vendor
   the_term_vendor_is_misleading True  # One of: True, False
   tag shortName # Or use a short name of your organization of your
                       # or your initials, etc.
   title Your Name
   qualifier author
   description "Maintainer of somepackage"

# The bundle object is optional
# Most packages do not need a bundle.  At this point in swbis'
# development 'bundles' are mostly ignored.  Bundles are meta
# packages, it is an object that contains other bundles and
# products whether included in this distribution tarball or not.
# The tag is the name of the meta-package.

bundle
   tag somepackage

# The product object contains the attributes of common
# interest such as the description, version and name.

# The product object is required.
# The product object contains the package info

product
   description "This is the
description of your
package"
   title "Short one line description"
   tag somepackage                      # This is the package name
   revision 1.99                        # This is the package version
   vendor_tag shortName
   control_directory ""   # Empty string, Important

# The fileset object contains the files.
# The fileset.tag and revision are ignored by swbis at
# this time.

# Only a fileset object contains files, hence it is required.
fileset
    tag somepackage-sources              # Not used currently
    control_directory ""                 # Empty string, Important
    title somepackage source code
    description "The source distribution of somepackage"

# file_permissions:
#
# NOTE:  Using "file_permissions -o 0 -g 0" is preferred if
# you want the package users to more easily verify the
# directory (unpacked) form of the package using standard
# non-swbis tools.  This is accomplished by using GNU tar
# with correct options to create a byte stream that hashes
# to match the GPG signature and payload digests.

#   file_permissions -u 000  # To use ownerships of source files
    file_permissions -o 0 -g 0 # --numeric --owner=root --group=root

# The following two (2) lines mean include every file in the current
# directory.

    directory .
    file *

# You want to exclude the files in ./catalog because it
# should not be part of the payload section.

    exclude catalog   # Important

# You may also want other excludes such as:

    exclude CVS
    exclude */CVS
    # exclude .svn
    # exclude */.svn

# End of PSF


File: swbis.info,  Node: Installing POSIX Distributions,  Next: Installing RPM Packages,  Prev: (swbis_swverify)VERIFYING SIGNATURES,  Up: Top

Installing POSIX Distributions
******************************

This is as simple as:

     swinstall <your-package
        # or
     swinstall -s :foo-1.1.tar.gz  @ 192.168.3.2 <your-package
        # or
     swinstall -x reinstall=y <your-package
        # or
     swinstall --no-scripts -x reinstall=y <your-package
        # or
     swinstall --no-scripts -x reinstall=y @ /tmp/test  <your-package
 The default target directory is always '/'.  *Note Command Reference::.


File: swbis.info,  Node: Host Requirements,  Next: Configuring swbis,  Prev: Other Resources,  Up: Top

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 `uuidgen' and if creating signed
distributions you need `gpg'.

   For package installation you need `sh', `bash', `dd', `tar',
`hostname', `mkdir', `expr', `echo', `test', `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 `swverify' and `swign' commands are shell scripts which may have
additional requirements.

   Here are the technical details about requirements for `swinstall',
the same apply to `swcopy':

   `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.  The
recommended value is 'detect' which performs auto-detection of a
sutable shell.

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

* Menu:

* More on Host Requirments: (swbis_swbis)HOST REQUIREMENTS


File: swbis.info,  Node: Installing RPM Packages,  Next: Translating Other Formats,  Prev: Installing POSIX Distributions,  Up: Top

Installing RPM Packages
***********************

Installing RPMs results in the RPM first being translated to a POSIX
archive in tar format, *Note Translating Other Formats::, then
installation by swinstall proceeds normally.

     swinstall --allow-rpm -s - @ host1:/mnt/test/root1 < your-0.1.arch.rpm

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


File: swbis.info,  Node: Translating Other Formats,  Next: Remote Host Operations,  Prev: Installing RPM Packages,  Up: Top

Translating Other Formats
*************************

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 `lxpsf' and
`swpackage'.  Internally, this is

     /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
     swpackage -Wsource=- -s@PSF

   The `lxpsf' is the only swbis program with RPM library dependencies,
and this is the program that does the actual meta-data translation.

   The easiest way to invoke translation is with the `--unrpm' of
`swpackage' and `swcopy'.

       swcopy --unrpm -s - @- <your-0.1.arch.rpm | tar tvf -
           -or-
       swpackage --unrpm @- <your-0.1.arch.rpm | tar tvf -
           -or-
       swpackage --to-sw <your-0.1.arch.rpm | tar tvf -

   To verbosely preview the translated RPM:

       swcopy --unrpm -s - @- | swinstall -p -x verbose=5

* Menu:

* More Specifics on Translating Other Formats: (swbis_user)TRANSLATING OTHER FORMATS


File: swbis.info,  Node: Remote Host Operations,  Next: GNU Toolset Orthogonality,  Prev: Translating Other Formats,  Up: Top



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.


File: swbis.info,  Node: GNU Toolset Orthogonality,  Next: Package Layout and Interchange Format Mimicry,  Prev: Remote Host Operations,  Up: Top



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.


File: swbis.info,  Node: Package Layout and Interchange Format Mimicry,  Next: (swbis_swpackage)SWPACKAGE OUTPUT FORMAT,  Prev: GNU Toolset Orthogonality,  Up: Top



swbis is non-intrusive relative to current practice for data
interchange and storage using tar archives.

   swbis supports a 'minimal package layout' (*Note (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 `tar'.

   The non-inventive nature of swbis extends into the format level as
well.  swbis has its own archive writing utility, `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 `swign' program (*Note (swbis_swign)::) which creates GPG signed
POSIX packages without any data copying except by GNU tar.


File: swbis.info,  Node: Index,  Prev: (swbis_sw)EXAMPLE PACKAGE,  Up: Top

Index
*****


