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

@comment ===============================================================
@comment WARNING: Do NOT edit this file.  It was produced automatically
@comment by man2info on Fri Nov  2 20:39:29 EDT 2018
@comment for jhl@
@comment from man/man1/swbis.1
@comment in /home/jhl/swbis-1.13.1/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/man1/swbis.1:49:%%unrecognized define-string command: [.ds f1\"]

@comment TROFF INPUT: .ds f2\"

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

@comment TROFF INPUT: .ds f3\"

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

@comment TROFF INPUT: .ds f4\"

@comment WARNING: man/man1/swbis.1: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" "1"

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

@node Top

@chapter SWBIS" "1


@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::
* INTRODUCTION::
* MAKING A PACKAGE SPECIFICATION FILE (PSF)::
* MAKING ARCHIVES::
* VERIFYING ARCHIVES::
* TRANSLATING OTHER FORMATS::
* SECURING FILE SYSTEM DIRECTORIES::
* SECURING CVS REPOSITORIES::
* COPYING FILES::
* PACKAGE MANAGEMENT FUNCTIONS::
* CONFIGURATION::
* APPLICABLE STANDARDS::
* SEE ALSO::
* FILES::
* IDENTIFICATION::
* BUGS::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node NAME

@section NAME

swbis @r{---} Software Administration User Manual

@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
Introduction
Making a Package Specification File (PSF)
Making Archives
Verifying Archives
Translating Other Formats
Securing File System Directories
Securing CVS Repositories
Copying Files
Package Management Functions
Configuration
@comment TROFF INPUT: .fi

@end display

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

@node INTRODUCTION

@section INTRODUCTION

@comment TROFF INPUT: .PP

This manual page is a very short user manual. It provides basic examples for using the swbis utilities.
For detailed description of format, syntax, and internal structures see the swbis Info document
(run 'info swbis' or 'info -f doc/info/swbis.info' from within the source package) or
other manual pages: sw(5), swpackage(5), swbis(7).
Each utility has its own manual page, see swverify(8), swlist(8), swcopy(8), swinstall(8) and swpackage(8).
For configuration help and host compatibility issues see swbis(7).
@comment TROFF INPUT: .PP

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 scope of the implementation includes a package format, meta-data file format, and utilities
for package creation, installation, query, listing, and verification.  The package management utilities
are network transparent via direct use of ssh(1).  They provide remote package management functions
to any UNIX-like remote host with a zero footprint regardless if swbis is installed on the remote host.
@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 ability to act as a
directory content integrity checker and SCM security tool.
@comment TROFF INPUT: .PP

All sections of this manual page, except the last two, describe security related application of
@b{swpackage} that integrate GNU utilities and the file system.
These applications along with the @b{swign} utility are unique to swbis.
The last section, Package Management, represents the intended focus of the spec.
@comment TROFF INPUT: .SH "MAKING A PACKAGE SPECIFICATION FILE (PSF)"
@c DEBUG: print_menu("INTRODUCTION")
@comment MAN2TEXI: EON

@node MAKING A PACKAGE SPECIFICATION FILE (PSF)

@section MAKING A PACKAGE SPECIFICATION FILE (PSF)

@comment TROFF INPUT: .PP

A PSF is a simple text file that directs @b{swpackage} on what to package. It is not included in
the package unless it lists itself as a file to include.
It can contain extra attributes (that swbis would not recognize).  These end up in the
main meta-data file named @b{catalog/INDEX}.  A PSF consists of sections that
contain keyword/value pairs.  The same keywords may appear in different sections and are indeed different
and separate attributes but they have the same definition/usage.  The sections are delimited by the
section keyword (which is recognized because it has no value) and the next section keyword.
The sections are properly called objects and the keyword is the object keyword.
Some sections contain other sections.  The parser knows and enforces the hierarchy.
@comment TROFF INPUT: .PP

White space in the PSF is not significant. A comment begins with a pound '#'.
@comment TROFF INPUT: .PP

Simple PSF's can be generated with @b{swign}.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
# Generate some generic sample PSFs
swign --show-psf -s.
swign --show-psf -s. --revision 1.1
swign --show-psf -s. -o root -g root
swign --show-psf -s. -o "" -g ""
swign --show-psf -s. -o 0 -g 0@r{
@comment TROFF INPUT: .fi

@end display

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

 Perform a test process on your PSF using the preview option
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:130:%%new font R started without closing previous font R

swign --show-psf -s.  | swpackage -p -v -s -}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SS "PSFs By Example"
@c DEBUG: print_menu("MAKING A PACKAGE SPECIFICATION FILE (PSF)")

@ifnottex
@menu
* PSFs By Example::
* o Package an entire directory::
* o Package Explicit Files::
* o Package A Directory that does not already exist::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node PSFs By Example

@subsection PSFs By Example

@comment TROFF INPUT: .PP

To test or preview the following examples use swpackage as follows:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
# Example commands that read a PSF from stdin
swpackage -p -v  # -or-
swpackage -p -vv  # -or-
swpackage -p --files -vv  # -or-
swpackage -p --files --dir=pathPrefix -vv @r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
then to make the package for real, remove the '-p' option, such as:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:149:%%new font R started without closing previous font R

	cat yourPSF | swpackage -s - @@-  | tar tvf -}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SS "o  Package an entire directory"
@comment MAN2TEXI: EON

@node o Package an entire directory

@subsection o  Package an entire directory

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
distribution
product
tag packageName
control@t{_}directory ""
revision 1.0
fileset
tag files
control@t{_}directory ""
directory .
file *
# exclude fileName
# exclude fileName2
# exclude fileName2 # ...@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SS "o   Package Explicit Files"
@comment MAN2TEXI: EON

@node o Package Explicit Files

@subsection o   Package Explicit Files

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
distribution
# owner root  # ownership of catalog
# groupt root  # ownership of catalog
product
tag packageName
control@t{_}directory ""
revision 1.0
fileset
tag files
control@t{_}directory ""
file -m 755 -o 0 -g 0 /etc/passwd /mypasswd

@comment WARNING: man/man1/swbis.1:188:%%new font R started without closing previous font R

file -m 666 -o 0 -g 0 /dev/null  /mynull}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SS "o   Package A Directory that does not already exist"
@comment MAN2TEXI: EON

@node o Package A Directory that does not already exist

@subsection o   Package A Directory that does not already exist

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
distribution
product
tag mydir
revision 0.001
fileset
tag bin
directory / /
file -o root -g bin -m 700 -t d /BB@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .PP

As a point of instruction, show the actual payload of this package
with the following command:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:210:%%new font R started without closing previous font R

   swpackage  | swinstall @@- | tar tvf -}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SH "MAKING ARCHIVES"
@comment MAN2TEXI: EON

@node MAKING ARCHIVES

@section MAKING ARCHIVES

@comment TROFF INPUT: .PP

swbis provide two programs to make a package: @b{swpackage} and @b{swign} To make a package, take your PSF that you created and use it as input to these programs.  Be aware that
both write to standard output by default.
@comment TROFF INPUT: .SS "Using swpackage"
@c DEBUG: print_menu("MAKING ARCHIVES")

@ifnottex
@menu
* Using swpackage::
* Using swign::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node Using swpackage

@subsection Using swpackage

@comment TROFF INPUT: .PP

@b{swpackage} is a self-contained tar writing utility, that is it writes a
tar archive without using /bin/tar.
@comment TROFF INPUT: .PP

Here is the command to read a PSF from stdin and write a tar archive on stdout and list
the resulting package with tar.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   swpackage -s - @@- | tar tvf -
   swpackage --gzip -s - @@- | tar ztvf -
   swpackage --bzip2 -s - @@- | tar jtvf -@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
Here are the options to use to include security attributes.  These can be set in your
defaults file (~/.swbis/swbisdefaults).
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

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

   swpackage -s - --archive-digests --file-digests --files @@-}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
The default digests for these options are md5 and sha1.  To add sha512 digests do
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   swpackage -s - --archive-sha512 --archive-digests \\
	--file-digests --file-sha512 --files @@-@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

To sign the package, that is, include an embedded GPG signature just
add the '--sign' option, along with other options.  '--sign' turns on '--archive-digest'
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   swpackage \\
      --archive-digests --file-digests --files \\

@comment WARNING: man/man1/swbis.1:255:%%new font R started without closing previous font R

      --gpg-name=yourId --gpg-path=~/.gnupg --sign}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

When swpackage asks for a passphrase it is really swpackage.
Although care is taken to handle the passphrase correctly, you can avoid having
swpackage handle your passphrase all together by using the gpg agent.
@comment TROFF INPUT: .PP

To use the agent, it must be running and the location must be set as the environment
variable @b{GPG@t{_}AGENT@t{_}INFO}. To verify this try:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   env | grep GPG@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br

@comment WARNING: man/man1/swbis.1:272:%%new font B started without closing previous font R

Now, just add the option }@b{--passphrase-fd=agent} to the swpackage invocation
or set and export the environment variable SWPACKAGEPASSFD=agent.  The result should be that
swpacakge completes without asking for a passphrase at the terminal.
@comment TROFF INPUT: .SS "Using swign"
@comment MAN2TEXI: EON

@node Using swign

@subsection Using swign

@comment TROFF INPUT: .PP

The @b{swign} utility is designed to make a package directly from
the contents of the current directory.  It combines usage of GNU tar and swpackage such
that the archive it creates is written entirely by GNU tar using the
file list, @b{catalog/dfiles/files}, generated by swpackage.  In this
way it provides more assurance against unseen data corruption, which is important when
creating signed packages.
@comment TROFF INPUT: .PP

For directories whose name has the form @b{Name-Version}, swign will
properly generate its own PSF with attributes based on the directory name.  The
name '.' is the special name for the internally generated PSF. By default, swign will
read a PSF from standard input.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   cd somepackage-1.1
   swign -s. -u yourIdName @@- | tar tvf -@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
The result is a package that looks like this
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
somepackage-1.1/
somepackage-1.1/catalog/
somepackage-1.1/catalog/INDEX
somepackage-1.1/catalog/dfiles/
somepackage-1.1/catalog/dfiles/INFO
somepackage-1.1/catalog/dfiles/md5sum
somepackage-1.1/catalog/dfiles/sha1sum
somepackage-1.1/catalog/dfiles/adjunct@t{_}md5sum
somepackage-1.1/catalog/dfiles/size
somepackage-1.1/catalog/dfiles/files
somepackage-1.1/catalog/dfiles/sig@t{_}header
somepackage-1.1/catalog/dfiles/signature
somepackage-1.1/catalog/pfiles/
somepackage-1.1/catalog/pfiles/INFO
somepackage-1.1/catalog/INFO
  ...

@comment WARNING: man/man1/swbis.1:314:%%new font R started without closing previous font R

somepackage-1.1/ ..}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

When making a package with swign, it is beneficial to include the @b{checkdigest} control script using this option:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swign -D $HOME/checkdigest.sh -s. -u yourIdName @@- | tar tvf -

    # Aside:
    # To see how the script is specified in the PSF, try
    #     swign -D /your@t{_}secure@t{_}path/checkdigest.sh -s. --psf
    #@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
This script will work unchanged for any package, and is available in the swbis source package. It may
be copied as a public domain program.  With this script included, a recipient of your signed package can

@comment WARNING: man/man1/swbis.1:333:%%new font B started without closing previous font R

verify the unpacked directory using }@b{swverify}.

@comment TROFF INPUT: .SH "VERIFYING ARCHIVES"
@comment MAN2TEXI: EON

@node VERIFYING ARCHIVES

@section VERIFYING ARCHIVES

@comment TROFF INPUT: .PP

Packages are verified by @b{swverify}
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   # This example verifies standard input
   swverify -d @@- @r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

In addition, packages that have a single path prefix (like source packages) and that
have ownerships reproducible on the local host can be verified in its unpacked form, for example:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   tar zxpf somepackage-1.1.tar.gz
   cd somepackage-1.1

@comment WARNING: man/man1/swbis.1:352:%%new font R started without closing previous font R

   swverify -d @@.}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
Verifying the unpacked form requires the @b{checkdigest} implementation
extension control script.  This script must have been included when the package was created using
the '-D NAME' option in the @b{swign}.

@comment TROFF INPUT: .SH "TRANSLATING OTHER FORMATS"
@c DEBUG: print_menu("VERIFYING ARCHIVES")
@comment MAN2TEXI: EON

@node TRANSLATING OTHER FORMATS

@section TRANSLATING OTHER FORMATS

@comment TROFF INPUT: .PP

swpackage can translate other package formats: deb, rpm, and slackware, and plain vanilla
source tarballs with a NAME-VERSION path name prefix.  In the process, the package can be signed.
@comment TROFF INPUT: .PP

The converted package is written to stdout.  The input is read from standard input or specified as
source using the @b{-s FILENAME} option.  Slackware packages cannot be read from standard
input because the revision and name is determined from the .tgz filename itself.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   swpackage --to-swbis -s somepackage.rpm  # RPM
   swpackage --to-swbis -s somepackage.deb  # DEB
   swpackage --to-swbis -s somesourcepackage-1.0.tar.gz  # Plain Source Package
     # or for slackware packages
   swpackage -s somepackage-1.0-i386.tgz --to-swbis@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br

@comment TROFF INPUT: .SH "SECURING FILE SYSTEM DIRECTORIES"
@c DEBUG: print_menu("TRANSLATING OTHER FORMATS")
@comment MAN2TEXI: EON

@node SECURING FILE SYSTEM DIRECTORIES

@section SECURING FILE SYSTEM DIRECTORIES

@comment TROFF INPUT: .PP


@comment WARNING: man/man1/swbis.1:381:%%new font B started without closing previous font R

The }@b{swign} utility can be used as a directory content integrity tool.  After
processing the current directory with swign, the directory can be verified against changes
to file contents, ownerships and permissions.
@comment TROFF INPUT: .PP

In this capacity, the @b{./catalog/} directory is a GPG signed record of
the directory contents.  It is created this way:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swign -D $HOME/checkdigest.sh -s. -u yourIdName -o "" -g "" @@.@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

Verification is simply:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:397:%%new font R started without closing previous font R

    swverify -d @@.}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br

@comment TROFF INPUT: .SH "SECURING CVS REPOSITORIES"
@c DEBUG: print_menu("SECURING FILE SYSTEM DIRECTORIES")
@comment MAN2TEXI: EON

@node SECURING CVS REPOSITORIES

@section SECURING CVS REPOSITORIES

@comment TROFF INPUT: .PP

Securing CVS (or any Source Code Management repository) is similar to securing a directory with
the additional step that the @b{./catalog/} directory is checked-in or committed
to the repository just like other ordinary directories in the project.
@comment TROFF INPUT: .PP

Slightly different options are used for signing and verification.  These have to do with file
ownerships which are not tracked and enforced.  Also the default action of removing ./catalog
is prevented by the @b{--no-remove} option.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swign -D $HOME/checkdigest.sh -s PSF.in --no-remove --name-version=somepackage-1.0 @@.@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
The exported directory (without the SCM control files) can be verified.  Since
ownerships, time stamps, and permissions are probably not preserved, use a special
option to swverify, --scm.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:422:%%new font R started without closing previous font R

     swverify --scm -d @@.}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP

The PSF.in for this usage is specialized.  Note the special exclude directives
and the replacement macros @i{%@t{_}@t{_}tag} and @i{%@t{_}@t{_}revision} which allows easy control of the current revision.
@comment TROFF INPUT: .PP

Here is a minimal example, the swign(1) manual page for more information.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   # PSF.in -- Input file to swign
   distribution
   checkdigest  \< bin/checkdigest.sh
   product
   tag %@t{_}@t{_}tag                # Replaced by swign
   control@t{_}directory ""
   revision %@t{_}@t{_}revision      # Replaced by swign
   fileset
   tag sources
   control@t{_}directory ""
   file@t{_}permissions -o 0 -g 0
   directory .
   file *
   exclude catalog
   exclude CVS
   exclude */CVS
   # exclude .svn
   # exclude */.svn@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SH "COPYING FILES"
@c DEBUG: print_menu("SECURING CVS REPOSITORIES")
@comment MAN2TEXI: EON

@node COPYING FILES

@section COPYING FILES

@comment TROFF INPUT: .PP


@comment WARNING: man/man1/swbis.1:456:%%new font B started without closing previous font R

}@b{swcopy} can be used to copy arbitrary files or data streams from host to host.
Here are a few examples.  See the manual page swcopy(8) for more.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
# Copy a file in the current directory to your home directory on HostA
   swcopy --no-audit -s :file1 @@ HostA

# Copy the data stream from a device on a remote host
   swcopy --no-audit -s 192.168.1.1:/dev/tape @@- | tar tvf -

# Show your network speed in real time
   swcopy --no-audit -s 192.168.1.1:/dev/zero --show-progress @@ /dev/null

# Read the entire file system on a remote host
   swcopy --no-audit -s 192.168.1.1:/ @@- | tar tvf -@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SH "PACKAGE MANAGEMENT FUNCTIONS"
@c DEBUG: print_menu("COPYING FILES")
@comment MAN2TEXI: EON

@node PACKAGE MANAGEMENT FUNCTIONS

@section PACKAGE MANAGEMENT FUNCTIONS

@comment TROFF INPUT: .PP

swbis supports typical package management functions for creation, installation,
listing/query, verification, and removal in a network transparent fashion with
zero new requirements for the remote host.

@comment WARNING: man/man1/swbis.1:479:%%new font B started without closing previous font R

}@b{ssh} is used directly for host access and no special
configuration is required.
@comment TROFF INPUT: .PP

The default requirements for the remote host are GNU bash, as @b{/bin/bash},
and GNU tar as @b{/bin/tar}.  Other runtime and compile configurations are
possible to allow GNU tar to be @b{/bin/gtar} and a host to be bash-less.
See swbis(7) for information on support for other POSIX shells.
@comment TROFF INPUT: .PP

Alternate root operation is supported for all operations, however, only
cooperatively enforced for control script execution, that is control scripts
must respect its relative root.
@comment TROFF INPUT: .PP

All utilities are similar in their command-line interface:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    sw<@i{utillity}> [@i{PKG@t{_}NAME@t{_}SPEC}] @@ @i{HOSTNAME}
@comment TROFF INPUT: .br
@comment .br
    sw<@i{utillity}> [@i{PKG@t{_}NAME@t{_}SPEC}] @@ :@i{FILENAME}
@comment TROFF INPUT: .br
@comment .br
    sw<@i{utillity}> [@i{PKG@t{_}NAME@t{_}SPEC}] @@ /@i{FILENAME}
@comment TROFF INPUT: .br
@comment .br
@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SS "Internal operation,  Events, and Errors"
@c DEBUG: print_menu("PACKAGE MANAGEMENT FUNCTIONS")

@ifnottex
@menu
* Internal operation Events and Errors::
* Recovery From Hangs and Crashes::
* Installation::
* Removal::
* Query::

@end menu
@end ifnottex

@comment MAN2TEXI: EON

@node Internal operation Events and Errors

@subsection Internal operation,  Events, and Errors

@comment TROFF INPUT: .PP

Operation of the distributed utilites consists of a shell script running on the target host
and the actual utility running on the management host.
These hosts may be the same or different.
Configuration data (e.g. swbisdefaults and swdefaults files) are read on the
management host only.  When verifying installed software, gpg is invoked on the management
host only using public keys from the management host only.
@comment TROFF INPUT: .PP

All the distributed utiltities operate as a utility (i.e. C program) and a shell script
read and executed from the POSIX shell's standard input.
The C program and shell script communicate via stdin, stdout and stderr using a connection
provided by an ordinary rsh or ssh client.  For local operation ssh/rsh is not invoked.
The utilities never should be installed setuid root.  Privilege escalation can be accomplished
via Ssh and a UNIX user account:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:520:%%new font I started without closing previous font R

    sw<}@i{utillity}> @@ root@@localhost
@comment TROFF INPUT: .br
@comment .br
@r{
@comment TROFF INPUT: .fi

@end display

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



The shell script is a list of tasks where each task becomes an additional shell reading from stdin.
Before the additional task shell is executed,
a Task Identification Header is read and compared with the expected Task. In addition
each task has an END event to return its status.  If any error occurs, the error is
detected by the utility (i.e. the C program on the management host); and, the main
script [on the target host] falls through with an error.

@comment TROFF INPUT: .PP

For example, here is how the 'load fileset' task script appears in a UNIX process listing:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
14073 14071  1 20:35  /bin/bash -s @t{_}swbis @t{_}swinstall
14453 14073  0 20:35  /bin/bash -s /@t{_}swbis /@t{_}swinstall load fileset
14454 14453  0 20:35  dd bs 512 count 6870
14455 14453  0 20:35  /bin/bash -s /@t{_}swbis /@t{_}swinstall load fileset

@comment WARNING: man/man1/swbis.1:542:%%new font R started without closing previous font R

14460 14455  0 20:35  tar xpvf -}
@comment TROFF INPUT: .fi

@end display

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


@comment TROFF INPUT: .PP

During operation events are generated.  They may be shown by increasing the verbosity level
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
    swinstall -x verbose=3
        # -or-
    swinstall -vv@r{
@comment TROFF INPUT: .fi

@end display

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

 For example, the events for installation look like this
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
# swinstall -x reinstall=y --no-scripts -vv @@ localhost:/tmp/aabb
swinstall: SWBIS@t{_}TARGET@t{_}BEGINS for @@localhost:/tmp/aabb
swinstall: SW@t{_}SESSION@t{_}BEGINS on target host Host20:
swinstall: SW@t{_}NOT@t{_}LOCATABLE: xorg-x11-Xnest.xorg-x11-Xnest: status=2
swinstall: SW@t{_}ANALYSIS@t{_}BEGINS on target host Host20:
swinstall: SW@t{_}SAME@t{_}REVISION@t{_}INSTALLED at @@localhost:/tmp/aabb: status=0: var/...
swinstall: SW@t{_}DEPENDENCY@t{_}NOT@t{_}MET: prerequisite xorg-x11,pr==6.8.2: status=2
swinstall: SW@t{_}SOC@t{_}LOCK@t{_}CREATED on target host Host20: lockpath=var/...
swinstall: SW@t{_}ANALYSIS@t{_}ENDS on target host Host20: status=0
swinstall: SW@t{_}EXECUTION@t{_}BEGINS on target host Host20:
swinstall: SW@t{_}SOC@t{_}LOCK@t{_}REMOVED on target host Host20: status=0
swinstall: SW@t{_}EXECUTION@t{_}ENDS on target host Host20: status=0
swinstall: SW@t{_}SESSION@t{_}ENDS on target host Host20: status=0

@comment WARNING: man/man1/swbis.1:571:%%new font R started without closing previous font R

swinstall: SWBIS@t{_}TARGET@t{_}ENDS for @@localhost:/tmp/aabb: status=0}
@comment TROFF INPUT: .fi

@end display

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

 Events have their own status, 0, 1, or 2.  Zero (0) is always sucess, 1 is an error, and
2 may be a warning or error depending on the event and options.
@comment TROFF INPUT: .SS "Recovery From Hangs and Crashes"
@comment MAN2TEXI: EON

@node Recovery From Hangs and Crashes

@subsection Recovery From Hangs and Crashes

@comment TROFF INPUT: .PP

Swbis utilites never hang and never crash and are generally signal safe, that is you
can hit ctrl-C and expect a controlled exit of the remote script and utility.
However if a utility really crashes it can leave unwanted processes on the remote host, they
may even suck up CPU cycles making the machine slow.
The first step is to kill the management utility:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   killall -9 swinstall  # or whatever the utility was@r{
@comment TROFF INPUT: .fi

@end display

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

 Then, to kill the task shells on the remote host:
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:591:%%new font R started without closing previous font R

   swremove --cleansh @@ user@@Host}
@comment TROFF INPUT: .fi

@end display

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

 using the same user and host as the crashed invocation.  This will kill all swbis process
including other users if allowed by the system.

@comment TROFF INPUT: .SS "Installation"
@comment MAN2TEXI: EON

@node Installation

@subsection Installation

@comment TROFF INPUT: .PP

Examples
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
  # Install at /
    swinstall -s :somepackage-1.1.bin.sw.tar.gz

  # Install to a alternate root, not running control scripts
    swinstall --no-scripts -vv -s:somepackage-1.1.i386.rpm @@ /tmp/foo1

  # Install to a alternate root
    swinstall -s :somepackage-1.1.bin.sw.tar.gz @@ /tmp/xx2

  # Install at /, gaining privilege via ssh
    swinstall -s :somepackage-1.1.bin.sw.tar.gz @@ root@@localhost

  # Install from standard input to /
    swinstall       # if default source directory is stdin or
    swinstall -s -  # independent of defaults file

  # Install at a remote host
    swinstall -s :somepackage-1.1.bin.sw.tar.gz @@ 192.168.1.1

  # Install to multiple targets, based on a list of one target per line
    echo 192.168.2.2 | swinstall -t - -s :somepackage-1.1.bin.sw.tar.gz@r{
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SS "Removal"
@comment MAN2TEXI: EON

@node Removal

@subsection Removal

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   # Remove a package named 'somepackage'
    swremove somepackage @@/

   # Remove everything
    swremove --allow-ambig \\* @@ /

   # Remove everything and force (e.g. override a stale lock)
    swremove --force somepackage @@ /

   # Preview what would be removed and do nothing

@comment WARNING: man/man1/swbis.1:639:%%new font R started without closing previous font R

    swremove -p -v somepackage @@ /}
@comment TROFF INPUT: .fi

@end display

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

@comment TROFF INPUT: .SS "Query"
@comment MAN2TEXI: EON

@node Query

@subsection Query

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
   # List all installed packages
    swlist # -or-
    swlist --products

   # List an installed package by name
    swlist somepackage

   # List an installed package by name and version
    swlist somepackage,r\\>1.0

   # List installed packages by name and version from several hosts
    swlist --verbose --products somepackage,r\\>1.0  @@ hostA hostB

   # Copy the installed catalog to stdout
    swlist -c - somepackage @@ root@@192.168.1.2 | tar tvf -

   # List the installed files from the catalog
    swlist --files somepackage @@ root@@192.168.1.2

   # List the installed files as found in the file system
    swlist --system somepackage @@ root@@192.168.1.2

   # List the payload of a package
    swlist --files @@- < somepackage-1.0.tar.gz

   # List the payload of a package
    swinstall @@- < somepackage-1.0.tar.gz | tar tvf -
@r{
@comment TROFF INPUT: .fi

@end display

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

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

@node CONFIGURATION

@section CONFIGURATION

@comment TROFF INPUT: .PP

See swbis(7) for detailed information on configuration and host compatibility strategies.
@comment TROFF INPUT: .SH "APPLICABLE STANDARDS"
@c DEBUG: print_menu("CONFIGURATION")
@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), swbis(7), swpackage(8), swpackage(5), swbisparse(1), swign(1), swverify(8),
@comment TROFF INPUT: .br
@comment .br
 swcopy(8), 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: .br
@comment .br
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

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

@comment WARNING: man/man1/swbis.1:708:%%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: .br
@comment .br
@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/man1/swbis.1:717:%%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(1)
 Author: Jim Lowe   Email: jhlowe at acm.org
 Version: 1.13.1
 Last Updated: 2010-02-04
 Copying: GNU Free Documentation License
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SH "BUGS"
@c DEBUG: print_menu("IDENTIFICATION")
@comment MAN2TEXI: EON

@node BUGS

@section BUGS

@comment TROFF INPUT: .PP

(This section left intensionally blank)
@comment  created by instant / docbook-to-man, Fri 02 Nov 2018, 20:39
@bye
