Untitled

Next: NAME, Up: (dir)

## 1 SWBIS" "1

Next: SYNOPSIS, Previous: Top, Up: Top

### 1.1 NAME

swbis — Software Administration User Manual

Next: INTRODUCTION, Previous: NAME, Up: Top

### 1.2 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

Next: MAKING A PACKAGE SPECIFICATION FILE (PSF), Previous: SYNOPSIS, Up: Top

### 1.3 INTRODUCTION

This manual page is a very short user manual. It provide 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).

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.

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.

All sections of this manual page, except the last two, describe security related application of swpackage that integrate GNU utilities and the file system. These applications along with the swign utility are unique to swbis. The last section, Package Management, represents the intended focus of the spec.

Next: MAKING ARCHIVES, Previous: INTRODUCTION, Up: Top

### 1.4 MAKING A PACKAGE SPECIFICATION FILE (PSF)

A PSF is a simple text file that directs 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 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.

White space in the PSF is not significant. A comment begins with a pound '#'.

Simple PSF's can be generated with swign.

            # Generate some 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

To test your PSF, do this

            swpackage −s yourPSF −p −vv  # −or-
            cat yourPSF | swpackage −p −s − −vv

Next: o Package an entire directory, Up: MAKING A PACKAGE SPECIFICATION FILE (PSF)

#### 1.4.1 PSFs By Example

Here are examples that preview only using the −p option

         	# 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

then to make the package for real, remove the '−p' option, such as:

         	swpackage | tar tvf −

Next: o Package Explicit Files, Previous: PSFs By Example, Up: MAKING A PACKAGE SPECIFICATION FILE (PSF)

#### 1.4.2 o Package an entire directory

         distribution
         product
         tag packageName
         control_directory ""
         revision 1.0
         fileset
         tag files
         control_directory ""
         directory .
         file *
         # exclude fileName
         # exclude fileName2
         # exclude fileName2 # ...

Next: o Package A Directory that does not already exist, Previous: o Package an entire directory, Up: MAKING A PACKAGE SPECIFICATION FILE (PSF)

#### 1.4.3 o Package Explicit Files

         distribution
         # owner root  # ownership of catalog
         # groupt root  # ownership of catalog
         product
         tag packageName
         control_directory ""
         revision 1.0
         fileset
         tag files
         control_directory ""
         file −m 755 −o 0 −g 0 /etc/passwd /mypasswd
         file −m 666 −o 0 −g 0 /dev/null  /mynull

Previous: o Package Explicit Files, Up: MAKING A PACKAGE SPECIFICATION FILE (PSF)

#### 1.4.4 o Package A Directory that does not already exist

         distribution
         product
         tag mydir
         revision 0.001
         fileset
         tag bin
         directory / /
         file −o root −g bin −m 700 −t d /BB

As a point of instruction, show the actual payload of this package with the following command:

            swpackage  | swinstall @− | tar tvf −

Next: VERIFYING ARCHIVES, Previous: MAKING A PACKAGE SPECIFICATION FILE (PSF), Up: Top

### 1.5 MAKING ARCHIVES

swbis provide two programs to make a package: swpackage and 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.

Next: Using swign, Up: MAKING ARCHIVES

#### 1.5.1 Using swpackage

swpackage is a self-contained tar writing utility, that is it writes a tar archive without using /bin/tar.

Here is the command to read a PSF from stdin and write a tar archive on stdout and list the resulting package with tar.

            swpackage −s − @− | tar tvf −
            swpackage −−gzip −s − @− | tar ztvf −
            swpackage −−bzip2 −s − @− | tar jtvf −

Here are the options to use to include security attributes. These can be set in your defaults file (~/.swbis/swbisdefaults).

            swpackage −s − −−archive-digests −−file-digests −−files @−

The default digests for these options are md5 and sha1. To add sha512 digests do

            swpackage −s − −−archive-sha512 −−archive-digests \
         	−−file-digests −−file-sha512 −−files @−

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'

            swpackage \
               −−archive-digests −−file-digests −−files \
               −−gpg-name=yourId −−gpg-path=~/.gnupg −−sign

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.

To use the agent, it must be running and the location must be set as the environment variable GPG`_`AGENT`_`INFO. To verify this try:

            env | grep GPG

Now, just add the option −−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.

Previous: Using swpackage, Up: MAKING ARCHIVES

#### 1.5.2 Using swign

The 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, catalog/dfiles/files, generated by swpackage. In this way it provides more assurance against unseen data corruption, which is important when creating signed packages.

For directories whose name has the form 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.

            cd somepackage-1.1
            swign −s. −u yourIdName @− | tar tvf −

The result is a package that looks like this

         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_md5sum
         somepackage-1.1/catalog/dfiles/size
         somepackage-1.1/catalog/dfiles/files
         somepackage-1.1/catalog/dfiles/sig_header
         somepackage-1.1/catalog/dfiles/signature
         somepackage-1.1/catalog/pfiles/
         somepackage-1.1/catalog/pfiles/INFO
         somepackage-1.1/catalog/INFO
           ...
         somepackage-1.1/ ..

When making a package with swign, it is beneficial to include the checkdigest control script using this option:

             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_secure_path/checkdigest.sh −s. −−psf
             #

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 verify the unpacked directory using swverify.

Next: TRANSLATING OTHER FORMATS, Previous: MAKING ARCHIVES, Up: Top

### 1.6 VERIFYING ARCHIVES

Packages are verified by swverify

            # This example verifies standard input
            swverify −d @−

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:

            tar zxpf somepackage-1.1.tar.gz
            cd somepackage-1.1
            swverify −d @.

Verifying the unpacked form requires the checkdigest implementation extension control script. This script must have been included when the package was created using the '−D NAME' option in the swign.

Next: SECURING FILE SYSTEM DIRECTORIES, Previous: VERIFYING ARCHIVES, Up: Top

### 1.7 TRANSLATING OTHER FORMATS

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.

The converted package is written to stdout. The input is read from standard input or specified as source using the -s FILENAME option. Slackware packages cannot be read from standard input because the revision and name is determined from the .tgz filename itself.

            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

Next: SECURING CVS REPOSITORIES, Previous: TRANSLATING OTHER FORMATS, Up: Top

### 1.8 SECURING FILE SYSTEM DIRECTORIES

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

In this capacity, the ./catalog/ directory is a GPG signed record of the directory contents. It is created this way:

             swign −D $HOME/checkdigest.sh −s. −u yourIdName −o "" −g "" @.

Verification is simply:

             swverify −d @.

Next: COPYING FILES, Previous: SECURING FILE SYSTEM DIRECTORIES, Up: Top

### 1.9 SECURING CVS REPOSITORIES

Securing CVS (or any Source Code Management repository) is similar to securing a directory with the additional step that the ./catalog/ directory is checked-in or committed to the repository just like other ordinary directories in the project.

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 −−no-remove option.

             swign −D $HOME/checkdigest.sh −s PSF.in −−no-remove −−name-version=somepackage-1.0 @.

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.

              swverify −−scm −d @.

The PSF.in for this usage is specialized. Note the special exclude directives and the replacement macros %`_` `_`tag and %`_` `_`revision which allows easy control of the current revision.

Here is a minimal example, the swign(1) manual page for more information.

            # PSF.in −− Input file to swign
            distribution
            checkdigest  \< bin/checkdigest.sh
            product
            tag %__tag                # Replaced by swign
            control_directory ""
            revision %__revision      # Replaced by swign
            fileset
            tag sources
            control_directory ""
            file_permissions −o 0 −g 0
            directory .
            file *
            exclude catalog
            exclude CVS
            exclude */CVS
            # exclude .svn
            # exclude */.svn

Next: PACKAGE MANAGEMENT FUNCTIONS, Previous: SECURING CVS REPOSITORIES, Up: Top

### 1.10 COPYING FILES

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.

         # 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 −

Next: CONFIGURATION, Previous: COPYING FILES, Up: Top

### 1.11 PACKAGE MANAGEMENT FUNCTIONS

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. ssh is used directly for host access and no special configuration is required.

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

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.

All utilities are similar in their command-line interface:

             sw<utillity> [PKG_NAME_SPEC] @ HOSTNAME

             sw<utillity> [PKG_NAME_SPEC] @ :FILENAME

             sw<utillity> [PKG_NAME_SPEC] @ /FILENAME

Next: Recovery From Hangs and Crashes, Up: PACKAGE MANAGEMENT FUNCTIONS

#### 1.11.1 Internal operation, Events, and Errors

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.

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:

             sw<utillity> @ root@localhost

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.

For example, here is how the 'load fileset' task script appears in a UNIX process listing:

         14073 14071  1 20:35  /bin/bash −s _swbis _swinstall
         14453 14073  0 20:35  /bin/bash −s /_swbis /_swinstall load fileset
         14454 14453  0 20:35  dd bs 512 count 6870
         14455 14453  0 20:35  /bin/bash −s /_swbis /_swinstall load fileset
         14460 14455  0 20:35  tar xpvf −

During operation events are generated. They may be shown by increasing the verbosity level

             swinstall −x verbose=3
                 # −or-
             swinstall −vv

For example, the events for installation look like this

         # swinstall −x reinstall=y −−no-scripts −vv @ localhost:/tmp/aabb
         swinstall: SWBIS_TARGET_BEGINS for @localhost:/tmp/aabb
         swinstall: SW_SESSION_BEGINS on target host low20.lowland.com:
         swinstall: SW_NOT_LOCATABLE: xorg-x11-Xnest.xorg-x11-Xnest: status=2
         swinstall: SW_ANALYSIS_BEGINS on target host low20.lowland.com:
         swinstall: SW_SAME_REVISION_INSTALLED at @localhost:/tmp/aabb: status=0: var/...
         swinstall: SW_DEPENDENCY_NOT_MET: prerequisite xorg-x11,pr==6.8.2: status=2
         swinstall: SW_SOC_LOCK_CREATED on target host low20.lowland.com: lockpath=var/...
         swinstall: SW_ANALYSIS_ENDS on target host low20.lowland.com: status=0
         swinstall: SW_EXECUTION_BEGINS on target host low20.lowland.com:
         swinstall: SW_SOC_LOCK_REMOVED on target host low20.lowland.com: status=0
         swinstall: SW_EXECUTION_ENDS on target host low20.lowland.com: status=0
         swinstall: SW_SESSION_ENDS on target host low20.lowland.com: status=0
         swinstall: SWBIS_TARGET_ENDS for @localhost:/tmp/aabb: status=0

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.

Next: Installation, Previous: Internal operation Events and Errors, Up: PACKAGE MANAGEMENT FUNCTIONS

#### 1.11.2 Recovery From Hangs and Crashes

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:

            killall −9 swinstall  # or whatever the utility was

Then, to kill the task shells on the remote host:

            swremove −−cleansh @ user@Host

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

Next: Removal, Previous: Recovery From Hangs and Crashes, Up: PACKAGE MANAGEMENT FUNCTIONS

#### 1.11.3 Installation

Examples

           # 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

Next: Query, Previous: Installation, Up: PACKAGE MANAGEMENT FUNCTIONS

#### 1.11.4 Removal

            # 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
             swremove −p −v somepackage @ /

Previous: Removal, Up: PACKAGE MANAGEMENT FUNCTIONS

#### 1.11.5 Query

            # 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 −

Next: APPLICABLE STANDARDS, Previous: PACKAGE MANAGEMENT FUNCTIONS, Up: Top

### 1.12 CONFIGURATION

See swbis(7) for detailed information on configuration and host compatibility strategies.

Next: SEE ALSO, Previous: CONFIGURATION, Up: Top

### 1.13 APPLICABLE STANDARDS

IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701, http://www.opengroup.org/publications/catalog/c701.htm

Next: FILES, Previous: APPLICABLE STANDARDS, Up: Top

### 1.14 SEE ALSO

          info swbis

          sw(5), swpackage(8), swbisparse(1), swign(1), swverify(8), swcopy(8), swbis(7)

          .../libexec/swbis/lxpsf

          .../libexec/swbis/arf2arf

          .../libexec/swbis/swbisparse

          .../libexec/swbis/swbistar

         http://www.gnu.org/software/swbis/sourcesign-1.2/gendocs/manual/index.html

Next: IDENTIFICATION, Previous: SEE ALSO, Up: Top

### 1.15 FILES

catalog/ # The meta-data directory swdefaults # Options configuration file swbisdefaults # Options configuration file

Next: BUGS, Previous: FILES, Up: Top

### 1.16 IDENTIFICATION

swbis(1) Author: Jim Lowe Email: jhlowe at acm.org Version: 0.950 Last Updated: 2008-04-18 Copying: GNU Free Documentation License

Previous: IDENTIFICATION, Up: Top

### 1.17 BUGS

(This section left intensionally blank)