\input texinfo   @c -*-texinfo-*-
@setfilename swbis.info

@comment ===============================================================
@comment WARNING: Do NOT edit this file.  It was produced automatically
@comment by man2info on Sun Jul 27 20:44:50 EDT 2014
@comment for jhl@
@comment from man/man7/swbis.7
@comment in /home/jhl/swbis-1.12x/doc
@comment ===============================================================

@comment @documentencoding ISO-8859-1

@comment troff -man typesetting style: headers, footers, no paragraph indentation

@paragraphindent none

@iftex
@parskip = 0.5@normalbaselineskip plus 3pt minus 1pt
@end iftex

@set lq ``
@set rq ''

@comment TROFF INPUT: ...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
@comment ...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: ...\"	transcript compatibility for postscript use.
@comment ...\"	transcript compatibility for postscript use.
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: ...\"	synopsis:  .P! <file.ps>
@comment ...\"	synopsis:  .P! <file.ps>
@comment TROFF INPUT: ...\"
@comment ...\"
@comment TROFF INPUT: .de P!
@comment .de P!
\.
@comment TROFF INPUT: .fl			\" force out current output buffer
@comment .fl			\" force out current output buffer
\\!%PB
\\!/showpage@{@}def
@comment TROFF INPUT: ...\" the following is from Ken Flowers -- it prevents dictionary overflows
@comment ...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
@comment TROFF INPUT: .fl			\" prolog
@comment .fl			\" prolog
@comment TROFF INPUT: .sy cat \\$1\" bring in postscript file
@comment .sy cat \\$1\" bring in postscript file
@comment TROFF INPUT: ...\" the following line matches the tempdict above
@comment ...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
@comment TROFF INPUT: .sp \\$2u	\" move below the image
@comment .sp \\$2u	\" move below the image
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .de pF
@comment .de pF
@comment TROFF INPUT: .ie     \\*(f1 .ds f1 \\n(.f
@comment .ie     \\*(f1 .ds f1 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f2 .ds f2 \\n(.f
@comment .el .ie \\*(f2 .ds f2 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f3 .ds f3 \\n(.f
@comment .el .ie \\*(f3 .ds f3 \\n(.f
@comment TROFF INPUT: .el .ie \\*(f4 .ds f4 \\n(.f
@comment .el .ie \\*(f4 .ds f4 \\n(.f
@comment TROFF INPUT: .el .tm ? font overflow
@comment .el .tm ? font overflow
@comment TROFF INPUT: .ft \\$1
@comment .ft \\$1
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .de fP
@comment .de fP
@comment TROFF INPUT: .ie     !\\*(f4 \{\
@comment .ie     !\\*(f4 \@{\
@comment TROFF INPUT: .	ft \\*(f4
@comment .	ft \\*(f4
@comment TROFF INPUT: .	ds f4\"
@comment .	ds f4\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f3 \{\
@comment .el .ie !\\*(f3 \@{\
@comment TROFF INPUT: .	ft \\*(f3
@comment .	ft \\*(f3
@comment TROFF INPUT: .	ds f3\"
@comment .	ds f3\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f2 \{\
@comment .el .ie !\\*(f2 \@{\
@comment TROFF INPUT: .	ft \\*(f2
@comment .	ft \\*(f2
@comment TROFF INPUT: .	ds f2\"
@comment .	ds f2\"
'	br \@}
@comment TROFF INPUT: .el .ie !\\*(f1 \{\
@comment .el .ie !\\*(f1 \@{\
@comment TROFF INPUT: .	ft \\*(f1
@comment .	ft \\*(f1
@comment TROFF INPUT: .	ds f1\"
@comment .	ds f1\"
'	br \@}
@comment TROFF INPUT: .el .tm ? font underflow
@comment .el .tm ? font underflow
@comment TROFF INPUT: ..
@comment ..
@comment TROFF INPUT: .ds f1\"

@comment WARNING: man/man7/swbis.7:49:%%unrecognized define-string command: [.ds f1\"]

@comment TROFF INPUT: .ds f2\"

@comment WARNING: man/man7/swbis.7:50:%%unrecognized define-string command: [.ds f2\"]

@comment TROFF INPUT: .ds f3\"

@comment WARNING: man/man7/swbis.7:51:%%unrecognized define-string command: [.ds f3\"]

@comment TROFF INPUT: .ds f4\"

@comment WARNING: man/man7/swbis.7:52:%%unrecognized define-string command: [.ds f4\"]

@comment TROFF INPUT: .ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
@comment .ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
@comment TROFF INPUT: .TH "SWBIS" "7"

@headings off
@everyheading SWBIS(7) @| @| SWBIS(7)
@everyfooting  @| @thispage @|

@node Top

@chapter SWBIS" "7


@comment TROFF INPUT: .hy 0
@comment .hy 0
@comment TROFF INPUT: .if n .na
@comment .if n .na
@comment TROFF INPUT: .SH "NAME"
@c DEBUG: print_menu("Top")

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

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node NAME

@section NAME

swbis @r{---} Distributed Software Administration

@comment TROFF INPUT: .SH "SYNOPSIS"
@c DEBUG: print_menu("NAME")
@comment MAN2TEXI: EON

@node SYNOPSIS

@section SYNOPSIS

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis @i{\<sw@t{_}utility\>} [options] [software@t{_}selections] [@@targets]
@i{\<sw@t{_}utility\>} [options] [software@t{_}selections] [@@targets]
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "DESCRIPTION"
@c DEBUG: print_menu("SYNOPSIS")
@comment MAN2TEXI: EON

@node DESCRIPTION

@section DESCRIPTION

@comment TROFF INPUT: .PP

@b{swbis} is a network transparent 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 (although for most uses of the
system tar utility, only generic options are specified).
@comment TROFF INPUT: .SH "OPTIONS"
@c DEBUG: print_menu("DESCRIPTION")
@comment MAN2TEXI: EON

@node OPTIONS

@section OPTIONS

@comment TROFF INPUT: .PP

The  @b{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.
@comment TROFF INPUT: .SS "Software Selections"
@c DEBUG: print_menu("OPTIONS")

@ifnottex
@menu
* Software Selections::
* Targets::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node Software Selections

@subsection Software Selections

@comment TROFF INPUT: .PP

Software Selections specify, by a software@t{_}spec, objects which to operate.
A software@t{_}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@t{_}tag, architecture, location, denoted by
the letters @b{r,q,v,a,l}.
@comment TROFF INPUT: .PP

The important tags of familiar repute are
@i{product}.@b{tag} and
@i{product}.@b{revision} along with an optional
@i{product}.@b{vendor@t{_}tag}.
These correspond to RPMTAG@t{_}NAME, RPMTAG@t{_}VERSION, and RPMTAG@t{_}RELEASE attributes.
These are specified in a software@t{_}selection by example thusly:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   # 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'@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

 Logical alternation or 'OR' is supported by using a second software@t{_}spec on the
command line. software@t{_}specs are separated by whitespace.
@comment TROFF INPUT: .SS "Targets"
@comment MAN2TEXI: EON

@node Targets

@subsection Targets

@comment TROFF INPUT: .PP

Targets are hosts or files on a host.  The syntax follows the familiar

@comment WARNING: man/man7/swbis.7:121:%%new font B started without closing previous font R

}@b{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 '/').
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
Source and Target Specification and Logic

     Synopsis:
          Posix:
               host[:path]
               host
               host:
               /path  # Absolute path

          Swbis Extension:
               [user@@]host[:path]
               [user@@]host@t{_}port[:path]
               :path

          Swbis Multi-hop Target Extension:
               # ':' is the target delimiter
	       # '@t{_}' delimits a port number in the host field

               [user@@]host[@@@@[user@@]host[@@@@...]][:file]
               [user@@]host@t{_}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@t{_}port:host@t{_}port:
               host:host:file
               user@@host:user@@host:
               user@@host:user@@host:host:
               user@@host:user@@host:file

     A more formal description:

     target : HOST@t{_}CHARACTER@t{_}STRING ':' PATHNAME@t{_}CHARACTER@t{_}STRING
            | HOST@t{_}CHARACTER@t{_}STRING ':'
            | HOST@t{_}CHARACTER@t{_}STRING
            | PATHNAME@t{_}CHARACTER@t{_}STRING
            | ':' PATHNAME@t{_}CHARACTER@t{_}STRING   # Impl extension
            ;

       PATHNAME@t{_}CHARACTER@t{_}STRING must be an absolute path unless
                       a HOST@t{_}CHARACTER@t{_}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@t{_}CHARACTER@t{_}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@t{_}CHARACTER@t{_}STRING
             | PATHNAME@t{_}CHARACTER@t{_}STRING
             ;
    user     : PORTABLE@t{_}CHARACTER@t{_}STRING  # The user name

    DELIM    : ':'   # The multi-hop delimiter.
             ;  @r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment TROFF INPUT: .SH "EXAMPLES"
@comment MAN2TEXI: EON

@node EXAMPLES

@section EXAMPLES

@comment TROFF INPUT: .PP

Unpack a tarball on host1 and host2:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display

@comment WARNING: man/man7/swbis.7:221:%%new font R started without closing previous font R

   swcopy -s :somepackage-1.0.tar.gz --extract @@ host1 host2}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

List installed entries matching the software selections:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   swlist somepackage,"r>2" @@ host1:/ host2:/
   swlist "kde*" @@ 192.168.2.2@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

List the architectures of the specified hosts:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display

@comment WARNING: man/man7/swbis.7:236:%%new font R started without closing previous font R

   swlist -x verbose=3 -a architecture @@ localhost 192.168.2.2 host1 host2}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

Install a package from stdin to a location, l=/unionfs/foo-1.0,
and a "exp" qualification:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swinstall q=exp,l=/unionfs/foo-1.0 @@ 192.168.2.2@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment TROFF INPUT: .PP

Remove a package named somepackage
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display

@comment WARNING: man/man7/swbis.7:252:%%new font R started without closing previous font R

    swremove somepackage @@ 192.168.2.2:/}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment TROFF INPUT: .PP

Make a tarball according to the recipe file @b{myPSF}:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swpackage -s myPSF @@- | tar tvf -@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .SH "COMMANDS OVERVIEW"
@c DEBUG: print_menu("EXAMPLES")
@comment MAN2TEXI: EON

@node COMMANDS OVERVIEW

@section COMMANDS OVERVIEW

@comment TROFF INPUT: .SS "POSIX Commands"
@c DEBUG: print_menu("COMMANDS OVERVIEW")

@ifnottex
@menu
* POSIX Commands::
* Swbis Specific Commands::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node POSIX Commands

@subsection POSIX Commands

@comment TROFF INPUT: .PP

Utilities specified by C701 and ISO/IEC 15068-2:1999 include the following:
@comment TROFF INPUT: .IP "   \(bu" 6


@comment WARNING: man/man7/swbis.7:268:%%new font B started without closing previous font R

}@b{swpackage}(8)
@comment TROFF INPUT: .IP "" 10

Create a tarball according to a recipe file.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swcopy}(8)
@comment TROFF INPUT: .IP "" 10

Copy a distribution from host to host.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swverify}(8)
@comment TROFF INPUT: .IP "" 10

Verify a software distribution signature.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swinstall}(8)
@comment TROFF INPUT: .IP "" 10

Install a software distribution.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swlist}(8)
@comment TROFF INPUT: .IP "" 10

List software information.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swremove}(8)
@comment TROFF INPUT: .IP "" 10

Remove packages
@comment TROFF INPUT: .SS "Swbis Specific Commands"
@comment MAN2TEXI: EON

@node Swbis Specific Commands

@subsection Swbis Specific Commands

@comment TROFF INPUT: .PP

Utilities unique to swbis.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{swign}(1)
@comment TROFF INPUT: .IP "" 10

Create the signed meta-data directory, @b{catalog}/, of the contents of the current directory and
optionally write the entire directory, including the signed catalog as a tar archive.
@comment TROFF INPUT: .IP "   \(bu" 6

\<@i{libexecdir}\>@b{/swbis/swbistar}
@comment TROFF INPUT: .IP "" 10

Archive writing (creation) utility, useful for testing.
@comment TROFF INPUT: .IP "   \(bu" 6

\<@i{libexecdir}\>@b{/swbis/swbisparse}
@comment TROFF INPUT: .IP "" 10

Stand-alone parser of POSIX Metadata files, useful for testing.
@comment TROFF INPUT: .IP "   \(bu" 6

\<@i{libexecdir}\>@b{/swbis/arf2arf}
@comment TROFF INPUT: .IP "" 10

Archive decoder/checker, Used by swverify.
@comment TROFF INPUT: .IP "   \(bu" 6

\<@i{libexecdir}\>@b{/swbis/lxpsf}
@comment TROFF INPUT: .IP "" 10

Archive translator, used by @b{swpackage} to translate RPM packages.
@comment TROFF INPUT: .SH "RUNTIME CONFIGURATION"
@comment MAN2TEXI: EON

@node RUNTIME CONFIGURATION

@section RUNTIME CONFIGURATION

@comment TROFF INPUT: .SS "Configuration Files"
@c DEBUG: print_menu("RUNTIME CONFIGURATION")

@ifnottex
@menu
* Configuration Files::
* Strategy for Compatibility with Existing Hosts::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node Configuration Files

@subsection Configuration Files

@comment TROFF INPUT: .PP

All of the utilities share the same configuration files:
@b{swdefaults} and
@b{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.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
 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@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

The syntax is:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
 # 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

@comment WARNING: man/man7/swbis.7:343:%%new font R started without closing previous font R

 swutilityName.optionName = value}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .SS "Strategy for Compatibility with Existing Hosts"
@comment MAN2TEXI: EON

@node Strategy for Compatibility with Existing Hosts

@subsection Strategy for Compatibility with Existing Hosts

@comment TROFF INPUT: .PP

The most important utiltities on which swbis relies is a POSIX shell, the system @b{/bin/sh}, and
the system tar utility, usually @b{/bin/tar}.  The POSIX shell need not be @b{/bin/sh}.
@comment TROFF INPUT: .PP

The POSIX 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 ksh (pdksh),
OpenSolaris @b{/usr/xpg4/bin/sh},  ATT ksh (latest version such as 93t+ 2010-03-05) have this feature.
Other shells including ash, dash, and @b{/bin/sh} on BSD, UNIX(tm), BusyBox systems do not.
@comment TROFF INPUT: .PP

Therefore, the most reliable and least intrusive strategy is use the auto-detection option.
If a host does not contain bash or a suitable ksh or sh the distributed utility will fail.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis@t{_}no@t{_}getconf               = true # true or false, false=use getconf
swbis@t{_}shell@t{_}command            = detect # @{detect|sh|bash|posix|ksh@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:365:%%new font B started without closing previous font R

 Alternatively, simply make }@b{/bin/bash} a requirement on all hosts and set
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis@t{_}no@t{_}getconf               = true # true or false, false=use getconf
swbis@t{_}shell@t{_}command            = bash # @{detect|sh|bash|posix|ksh@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

NOTE: The shell requirement does not apply to the user's account shell (specified in /etc/passwd), although there
are reasons this shell should be a Bourne compatible shell.  See Acount Login Shell below
@comment TROFF INPUT: .PP

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.
@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:379:%%new font B started without closing previous font R

The configuration options, in }@b{swbisdefaults} allow some flexibilty here
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis@t{_}local@t{_}pax@t{_}write@t{_}command  = tar  # @{pax|tar|star|gtar@}
swbis@t{_}remote@t{_}pax@t{_}write@t{_}command = tar  # @{pax|tar|star|gtar@}
swbis@t{_}local@t{_}pax@t{_}read@t{_}command   = tar  # @{pax|tar|star|gtar@}
swbis@t{_}remote@t{_}pax@t{_}read@t{_}command  = tar  # @{pax|tar|star|gtar@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swverify.swbis@t{_}local@t{_}pax@t{_}write@t{_}command   = detect # @{pax|tar|star|gtar@}
swverify.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command  = detect # @{pax|tar|star|gtar@}
swlist.swbis@t{_}local@t{_}pax@t{_}write@t{_}command   =   detect  # @{pax|tar|star|gtar@}

@comment WARNING: man/man7/swbis.7:393:%%new font R started without closing previous font R

swlist.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command  =   detect  # @{pax|tar|star|gtar@}}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


This allows keeping and using the system '/bin/tar', and only using GNU tar or pax
for verification and listing.
@comment TROFF INPUT: .PP

Other important options are:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swcopy.swbis@t{_}allow@t{_}rpm       = true  # Enable automatic translation
swinstall.swbis@t{_}allow@t{_}rpm    = true  # Enable automatic translation
swcopy.swbis@t{_}no@t{_}audit        = true  # Copy as arbitrary data, true or false
swbis@t{_}remote@t{_}shell@t{_}client    = ssh   # @{ssh|rsh@}
swbis@t{_}forward@t{_}agent          = true  # Set ssh -A for multi-hop (>1) jumps
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:413:%%new font R started without closing previous font R

}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

 Here is a incomplete explanation of each option
@comment TROFF INPUT: .IP "   \(bu" 6

Extended Option: @b{swbis@t{_}local@t{_}pax@t{_}read@t{_}command}
@comment TROFF INPUT: .br
@comment .br
Extended Option: @b{swbis@t{_}remote@t{_}pax@t{_}read@t{_}command}
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .IP "" 10

If installing
on a system, any @b{tar} will work.  GNU @b{tar} is required when using @b{swign} to create a signed archive or directory.
If @b{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).
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis@t{_}local@t{_}pax@t{_}read@t{_}command = tar #@{pax|tar|gtar@}
swbis@t{_}remote@t{_}pax@t{_}read@t{_}command= tar #@{pax|tar|gtar@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .IP "   \(bu" 6


@comment WARNING: man/man7/swbis.7:435:%%new font B started without closing previous font R

Extended Option: }@b{swbis@t{_}local@t{_}pax@t{_}write@t{_}command}
@comment TROFF INPUT: .br
@comment .br
Extended Option: @b{swbis@t{_}remote@t{_}pax@t{_}write@t{_}command}
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .IP "" 10

@b{swcopy} and @b{swinstall} may use the system tar (which may not be
GNU tar or pax).
@b{swpackage} is self-contained and does not use any file system tar-like utility.
@b{swign} does not read the options files and assumes and requires that @b{tar} is GNU tar.
@b{swlist} and @b{swverify} requires either GNU tar or pax and can be set to
detect a suitable tar or pax.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swlist.swbis@t{_}local@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swlist.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swverify.swbis@t{_}local@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swverify.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swbis@t{_}local@t{_}pax@t{_}write@t{_}command = tar #@{pax|tar|gtar@}
swbis@t{_}remote@t{_}pax@t{_}write@t{_}command= tar #@{pax|tar|gtar@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment TROFF INPUT: .IP "   \(bu" 6


@comment WARNING: man/man7/swbis.7:458:%%new font B started without closing previous font R

Extended Option: }@b{swbis@t{_}shell@t{_}command}
@comment TROFF INPUT: .IP "" 10

This may be one of
@b{detect},
@b{bash},
@b{ksh},
@b{sh}, or
@b{posix}.  @b{detect} is the best choice.
ksh must be public domain ksh or ATT ksh93 (version 2009-05-05 or newer). Older versions of
ksh93 do not have the required POSIX feature.
@comment TROFF INPUT: .IP "   \(bu" 6

@b{Account Login Shell}
@comment TROFF INPUT: .IP "" 10

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 Bourne compatible or POSIX conforming shell.
This requirement is due to the escapement and processing of shell special characters which are
performed by the login shell of the intermediate host account.
@comment TROFF INPUT: .IP "   \(bu" 6

Extended Option: @b{swbis@t{_}forward@t{_}agent}
@comment TROFF INPUT: .IP "" 10

The default value is True.  This sets the @b{-A} in the @b{ssh} client for multi-hop targets.  There are security considerations when forwarding the
authentication agent.
@comment TROFF INPUT: .SH "HOST REQUIREMENTS"
@comment MAN2TEXI: EON

@node HOST REQUIREMENTS

@section HOST REQUIREMENTS

@comment TROFF INPUT: .PP

The swbis distributed utilties have no special requirements and will operate
on any full-size OpenSolaris, BSD or GNU/Linux host.  You may immediately and remotely
distribute and manage packages on these hosts with nothing more than a login account
and a ssh connection.  Below are the technical details.  The configuration file options
to allow this are the built-in defaults,  certain values in historic versions of the defaults file,
@b{swbisdefaults}, may break this functionality.
@comment TROFF INPUT: .PP

The swbis distributed utilities require
@b{bash}, public domain @b{ksh}, or
Sun's /usr/xpg4/bin/sh to be present on the target host.  If the
@b{swbis@t{_}shell@t{_}command} extended option is set to 'detect'
you don't have to know which one is present, otherwise you may specify one explicitly.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swbis@t{_}shell@t{_}command=detect #@{posix|sh|bash|ksh|detect@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

Tar or pax is used for file loading (installation) and internally for data transfer.  You may specify which one.

@comment WARNING: man/man7/swbis.7:501:%%new font B started without closing previous font R

}@b{swlist} and @b{swverify} require
either GNU tar or pax be present on a host.  You may set auto detection
for this requirement.  As of release 1.12 (c.August 2014), all invocations of the system tar utility
for archive creation use the '--format=pax' option of GNU tar.  A test is made for GNU tar and generic
options are used if no suitable version of GNU tar is present allowing generic tar to work.

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
swlist.swbis@t{_}local@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swlist.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swverify.swbis@t{_}local@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swverify.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command=detect #@{pax|tar|gtar|detect@}
swinstall.swbis@t{_}local@t{_}pax@t{_}write@t{_}command = tar #@{pax|tar|gtar@}
swinstall.swbis@t{_}remote@t{_}pax@t{_}write@t{_}command= tar #@{pax|tar|gtar@}
swinstall.swbis@t{_}local@t{_}pax@t{_}read@t{_}command  = tar #@{pax|tar|gtar@}
swinstall.swbis@t{_}remote@t{_}pax@t{_}read@t{_}command = tar #@{pax|tar|gtar@}@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:520:%%new font B started without closing previous font R

A POSIX }@b{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.
@comment TROFF INPUT: .PP

GNU Privacy Guard, gpg is required for verification and  signing.
Use of the passphrase agent @b{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.
Verification takes place on the management host. It would not be used on the
(remote) target host.
@comment TROFF INPUT: .PP

For verifying package tarballs, only @b{swverify} and @b{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.
@comment TROFF INPUT: .PP

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 @b{/bin/sh}.
Most traditional Bourne shell's are acceptable as /bin/sh, one notable exception
is @b{/bin/ash} when operating on the terminal host (due to its read block size).
However, @b{/bin/dash}, BSD @b{/bin/sh}, and Sun's /bin/sh
are all acceptable.  Note that /bin/sh need not be the system POSIX shell.
@comment TROFF INPUT: .PP

As stated above, a POSIX shell is required and the only suitable implementations (as of Sep 2010) are
@b{/bin/bash}, @b{/bin/ksh} (Public Domain or ksh93 v.2009-05-05 or newer),
Sun's @b{/usr/xpg4/bin/sh}, and MirBSD Korn Shell (@b{/bin/mksh}) all assumed
to be in these locations.
@comment TROFF INPUT: .SH "DISCUSSION"
@c DEBUG: print_menu("HOST REQUIREMENTS")
@comment MAN2TEXI: EON

@node DISCUSSION

@section DISCUSSION

@comment TROFF INPUT: .SS "Background"
@c DEBUG: print_menu("DISCUSSION")

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

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node Background

@subsection Background

@comment TROFF INPUT: .PP

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, @b{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 @b{tar}.
When the collapsed form is used, the in-band @b{catalog/} directory
is next to (in the same directory as) the payload files hence "catalog" becomes
a reserved word for package files.
@comment TROFF INPUT: .PP

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.
@comment TROFF INPUT: .SS "Distributed Software Administration"
@comment MAN2TEXI: EON

@node Distributed Software Administration

@subsection Distributed Software Administration

@comment TROFF INPUT: .PP

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.
@comment TROFF INPUT: .SS "A Directory Content Checker"
@comment MAN2TEXI: EON

@node A Directory Content Checker

@subsection A Directory Content Checker

@comment TROFF INPUT: .PP

The @b{swign} program creates the
@b{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:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   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.@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:603:%%new font B started without closing previous font R

The  }@b{checkdigest.sh} is a distributor specific shell
script that is run by swverify if it is present and part of the signed  stream.
@b{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.]
@comment TROFF INPUT: .PP

Use as a SCM (e.g. CVS, svn. etc) security tool easily follows by
making @b{catalog/} a tracked directory in the SCM.
The catalog directory is updated using the @b{swign} command.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
     export SWPACKAGEPASSFD
     SWPACKAGEPASSFD=agent
     export GNUPGNAME
     GNUPGNAME="Your Name"
     swign --name-version=somepackage-1.1 -s PSF.in --no-remove @@.@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:623:%%new font B started without closing previous font R

 See the }@b{swign} manual page for an example @b{PSF.in} file.
@comment TROFF INPUT: .SS "Package Security"
@comment MAN2TEXI: EON

@node Package Security

@subsection Package Security

@comment TROFF INPUT: .PP

As implementation extensions,
@b{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.
@comment TROFF INPUT: .SS "Extensibility"
@comment MAN2TEXI: EON

@node Extensibility

@subsection Extensibility

@comment TROFF INPUT: .PP

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.
@comment TROFF INPUT: .SS "Support for Unprivileged Users"
@comment MAN2TEXI: EON

@node Support for Unprivileged Users

@subsection Support for Unprivileged Users

@comment TROFF INPUT: .PP

Support for unprivileged users is treated as a requirement.  @b{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.
@b{swinstall} supports the @i{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.
@comment TROFF INPUT: .SH "COPYING"
@comment MAN2TEXI: EON

@node COPYING

@section COPYING

@comment TROFF INPUT: .PP

Swbis is a copyrighted work.
Non-copyright holders may use and make copies under the terms of the GNU GPL
@comment TROFF INPUT: .SH "PRONUNCIATION"
@c DEBUG: print_menu("COPYING")
@comment MAN2TEXI: EON

@node PRONUNCIATION

@section PRONUNCIATION

@comment TROFF INPUT: .PP

Swbis is a concatenation of the command name prefix 'sw' with the
Italian suffix 'bis' meaning again, or one more time.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    Pronunciation: /es dub-u bis/
                  sw - bis
     POSIX packaging - Play it again, One more time@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .SH "APPLICABLE STANDARDS"
@c DEBUG: print_menu("PRONUNCIATION")
@comment MAN2TEXI: EON

@node APPLICABLE STANDARDS

@section APPLICABLE STANDARDS

@comment TROFF INPUT: .PP

IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999),
@comment TROFF INPUT: .br
@comment .br
Open Group CAE C701,
@comment TROFF INPUT: .br
@comment .br
http://www.opengroup.org/publications/catalog/c701.htm
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SH "SEE ALSO"
@c DEBUG: print_menu("APPLICABLE STANDARDS")
@comment MAN2TEXI: EON

@node SEE ALSO

@section SEE ALSO

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
 info swbis
@comment TROFF INPUT: .br
@comment .br
 sw(5), swpackage(8), swbisparse(1), swign(1), swverify(8), swcopy(8)
@comment TROFF INPUT: .br
@comment .br
 swbis(1), swconfig(8), swlist(8), swremove(8)
@comment TROFF INPUT: .br
@comment .br
 .../libexec/swbis/lxpsf
@comment TROFF INPUT: .br
@comment .br
 .../libexec/swbis/arf2arf
@comment TROFF INPUT: .br
@comment .br
 .../libexec/swbis/swbisparse
@comment TROFF INPUT: .br
@comment .br
 .../libexec/swbis/swbistar
@comment TROFF INPUT: .br
@comment .br
http://www.gnu.org/software/swbis/sourcesign-1.2/gendocs/manual/index.html
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display

@comment WARNING: man/man7/swbis.7:696:%%new font R started without closing previous font R

}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@r{
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .SH "FILES"
@c DEBUG: print_menu("SEE ALSO")
@comment MAN2TEXI: EON

@node FILES

@section FILES

@comment TROFF INPUT: .PP


@comment WARNING: man/man7/swbis.7:704:%%new font B started without closing previous font R

}@b{/var/lib/swbis/catalog}/  # The installed software catalog
@comment TROFF INPUT: .br
@comment .br
@b{catalog}/  # The package meta-data directory
@comment TROFF INPUT: .br
@comment .br
@b{swdefaults}     # Options configuration file
@comment TROFF INPUT: .br
@comment .br
@b{swbisdefaults}  # Options configuration file
@comment TROFF INPUT: .SH "IDENTIFICATION"
@c DEBUG: print_menu("FILES")
@comment MAN2TEXI: EON

@node IDENTIFICATION

@section IDENTIFICATION

 swbis(7)
 Author: Jim Lowe   Email: jhlowe at acm.org
 Version: 1.12
 Last Updated: 2008-04-18
 Copying: GNU Free Documentation License
@comment TROFF INPUT: .SH "BUGS"
@c DEBUG: print_menu("IDENTIFICATION")
@comment MAN2TEXI: EON

@node BUGS

@section BUGS

@comment TROFF INPUT: .PP

Not everything is implemented yet.
@comment  created by instant / docbook-to-man, Sun 27 Jul 2014, 20:44
@bye
