# Swbis Manual

Next: Copying This Manual, Up: (dir)

## swbis

This manual is for swbis (version 1.13.1, 24 Jul 2014), which is an implementation of the POSIX System Administration Standard – Part 2: Software Administration IEEE Std 1387.2-1995 (ISO/IEC 15068-2) (both now withdrawn) and the Open Group Specification CAE C701. Currently, most of the the standard is implemented. Most notably the implementation lacks the ability to operate on packages with multiple fileset or products. There are extensions for package authentication using GNU Privacy Guard. Extensions to the standard are indicated as such in this document.

Copyright © 2008,2014 Jim Lowe

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

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

Next: Signing File System Directories, Previous: Making PSFs for Package Creation, Up: Top

## 1 Creating Signed Distributions

The first step in package signing is to obtain GNU Privacy Guard and its command line program `gpg`. The next step is to invoke it directly to test your gpg configuration. The `gpg` program is invoked by `swpackage` with the following options:

          gpg --no-tty --no-secmem-warning --armor --passphrase-fd 3 -sb -o -

The `--passphrase-fd` and `--no-tty` options would not be used if running the `gpg` utility from the command line. The option swpackage `--gpg-name` option maps to gpg `--local-user` option and the swpackage `--gpg-path` option maps to gpg `--homedir` option. The default id to sign and home directory depends on `gpg`'s defaults, the default home directory is is usually `~/.gnupg`.

If you experience difficulty signing a test file using `gpg` then consult the gpg manual, since configuring `gpg` is outside the scope of swbis.

Once you know `swpackage` works without signing enabled simply invoke it with the additional option `--sign` and possibly `--gpg-name=YOUR_ID` and `--gpg-path=PATH`. `swpackage` should ask for your passphrase. Note that the `--sign` turns on `--archive-digests` automatically since a package is not fully verifiable without archive digests.

Other `swpackage` options you may which to use are `--files` and `--file-digests`.

For example:

            swpackage -Wsign,files,gpg-name="Test User" -s PSF @- >/dev/null

There are defaults file options which can be set to your preferences. The command line options always override the the defaults file settings.

         swpackage.swbis_file_digests       = "true"   # true or false
         swpackage.swbis_files              = "false"   # true or false
         swpackage.swbis_sign               = "false"   # true or false
         swpackage.swbis_gpg_name           =
         swpackage.swbis_gpg_path           = "~/.gnupg"
         swpackage.swbis_signer_pgm	        = "GPG"

In addition, signed packages can be created using the ad-hoc extension utility `swign`. It was designed especially to create signed POSIX packages of free software source packages.

The operational constraints for using `swign` are that every file in the current directory is packaged, all files have the same ownerships, the archive will have a single leading package directory equal to the current directory name, and the package will contain the `catalog` directory. Other than the additional `catalog` directory, the package can be identical to the non-POSIX package created with `tar`.

`swign` is designed to be fail safe. `swign` uses `swpackage` and GNU `tar` as tools in a fashion such that all data copied to the user is generated by GNU `tar` from a file list generated by `swpackage`. Therefore, there is no chance the archive is corrupt, and because of sanity checks on the file list using existing GNU file system utilities, little to no chance of missing data.

`swign` requires GNU `tar` version 1.13.25 or 1.14 or 1.15.x. Using a version other than these will produce a valid archive, but the signature may not be valid.

Next: Creating a signed directory using <samp><span class="command">swign</span></samp>, Up: Creating Signed Distributions

### Creating a signed POSIX archive

`swign` packages all the files in the current directory, makes the path name prefix the name of the current directory, and all the files will have the same ownerships. These constraints are suited to GNU and Unix free software source packages.

Creating a signed package with `swign` is easy. Just change directory to the directory you want to archive, verify the documented side-effect of removing and replacing a directory name `catalog` is not a problem. If your directory has a file named catalog (that is not a POSIX exported catalog) that belongs to your data set you must rename it. For better or worse 'catalog' is a keyname of the POSIX standard.

Then type:

           swign -o 0 -o 0 --show-psf
                     -or-
           swign --show-psf

to show the internally PSF to stdout. It tries to make a reasonable PSF using the name of the current directory. You can supply you own PSF from a file or on standard input like this

           swign -o 0 -o 0 --show-psf  | swign -s - --show-psf

Now, make a package for real.

           swign -o 0 -o 0 --show-psf  | swign -u "My GPG Name" @- >../my_new_signed_tarball

`swign` writes to stdout. You must redirect the archive to a more useful file.

You could verify it like this:

           swign -u "My GPG Name" @- | swverify -d @-
                   -or like this-
           swverify -d @:../my_new_signed_tarball

If a `checkdigest` script is included then you should unpack the package at a new location and run 'swverify –checksig "."' in the new location. See Providing a `checkdigest` script.

Next: Environment Variables that direct <samp><span class="command">swign</span></samp>, Previous: Creating a signed POSIX archive using <samp><span class="command">swign</span></samp>, Up: Creating Signed Distributions

### Creating a signed directory

Creating a signed directory is actually the first step that `swign` does when creating a signed archive. Using the `-S` simply causes `swign` to exit early.

Aside:

          This feature exposes a regression test constraint, namely
          that the byte stream generated by 'swpackage' and installed
          by 'tar' is identical to the byte stream generated by GNU 'tar'
          from the newly installed 'catalog' directory.

To sign the directory, and then verify it:

           swign -S; swverify -d @.

This produces the output:

        swign: Generating the catalog and installing with tar...
        swpackage: Warning: exclude definition source [catalog] does not exist.
        Enter Password:
        swverify: GPG signature verified.
        swverify: checkdigest script not found
        swverify: Package authenticity not confirmed.

For more information about the 'checkdigest' script:

See (swbis_swverify)IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS, and

See (swbis_swverify)Verifying the Directory Form of a Distribution.

Swign can be used to sign any directory using the file ownerships of the source files. The following commands act as a test of swpackage's ability to generate an archive identical to GNU tar. (Note: checkdigest.sh is found in ./bin of the source distribution.)

          swign -D $HOME/checkdigest.sh -u "Test User" -o "" -g "" -S;
          swverify -d @.

Next: Providing a <samp><span class="file">checkdigest</span></samp> script, Previous: Creating a signed directory using <samp><span class="command">swign</span></samp>, Up: Creating Signed Distributions

### Environment Variables that direct `swign`

`swverify` is affected by the following environment variables: SWPACKAGEPASSFD, SWPACKAGEPASSPHRASE, GNUPGHOME, and GNUPGNAME. For more information: (See (swbis_swpackage)ENVIRONMENT.)

Next: Using <samp><span class="command">swign</span></samp> in an Automake target, Previous: Environment Variables that direct <samp><span class="command">swign</span></samp>, Up: Creating Signed Distributions

### Providing a `checkdigest` script

The `checkdigest` script is a distributor extension script. Only the swbis implementation of `swverify` knows how to use it. An example file is found in the swbis source package.

You need to supply a checkdigest script only if you wish your customers to be able to verify the directory form (i.e. unpacked archive) of a POSIX package. There are constraints on the usefulness of this script which are the same as when attempting to verify manually. See (swbis_swverify)Verifying a POSIX Distribution Directory Manually. It is not used when verifying the archive file form. Also, since it should only use non-swbis standard GNU tools and is a shell script, it does not do anything that the end user could not do themselves.

The script is included in the package one of two ways: using the `-D` option of the `swign` command or by specifying in a PSF to be processed by `swpackage`. The syntax for referencing from a PSF is:

          checkdigest < /path/name/to/your/checkdigest.sh

This line should be added in the distribution object of the PSF.

Previous: Providing a <samp><span class="file">checkdigest</span></samp> script, Up: Creating Signed Distributions

### Using `swign` in an Automake target

Here is a target to put in your Makefile.am (This example was tested with Automake version 1.9):

    # Provide am__remove_distdir ourselves since am__remove_distdir may be a
    # private automake variable.
    sw_am__remove_distdir = \
      { test ! -d $(distdir) \
          || { find $(distdir) -type d ! -perm -200 -exec chmod u+w {} ';' \
                   && rm -fr $(distdir); }; }
    dist-swbis: distdir
            (cd $(distdir) && swign -s PSF.in --name-version=$(distdir) @-) | GZIP=$(GZIP_ENV) gzip -c >$(distdir).tar.gz
            $(sw_am__remove_distdir)

An example invocation using the environment controls:

            (SWPACKAGEPASSFD="agent"; GNUPGNAME="Your Name"; make dist-swbis)

The `PSF.in` should employ the replacement strings '%__tag' and '%__revision' as in this example PSF.in (See (swbis_swign)SAMPLE SOURCE PACKAGE PSF.)

Next: Applicable Standards, Previous: Glossary, Up: Top

## 2 What features are working?

In summary, the swbis supports network-transparent package management but is restricted to packages with a single fileset and product. It has utilities for stand-alone creation of tarballs with meta-data including embedded GPG signatures. There exists also the ability to translate dpkg, rpm, and slackware directly into POSIX format.

`swpackage` is the most complete utility. It implements all of the ISO/IEC 15068-2 features of the Product Specification File, the input file of `swpackage`. `swpackage` can create packages with multiple filesets and products even though the the other utilities cannot operate on them.

`swpackage` can create POSIX tar archives with a POSIX file layout with an embedded GPG signature and payload digest (md5 and sha1). This capability is mature and safe, but for those who are paranoid about using a new tool to create archives of your data, there is `swign`. `swign` signs the current working directory, presumably a directory containing your source tree, and then uses `tar` to emit the archive. The result is a package, created by GNU tar, which looks like a source tar archive with a leading directory. The archive has the ./catalog/ directory which contains the package metadata, GPG signature and digests which are stored as separate regular files, and as ascii text of course.

Below is more detail about current capabilities.

- Installing POSIX packages

  Command: `swinstall` can install, make dependency downdate and reinstall checks.

- Copying POSIX packages

  Command: `swcopy`

  `swcopy` is missing many features specified in the POSIX spec. Several degenerative basic features work and can be useful. It can unpack compressed tar archives handling compression transparently. It can copy directories from host to host. It can be used as a copying tool for arbitrary data, however this is not its intended application. Unfortunately, many of its intended uses don't work yet.

- Handling RPM Packages

  Command: `swinstall` or `swcopy`

  `swcopy` can translate RPMs to a tar archive. This is useful for installing the contents of a source RPM into a single directory.

  `swinstall` can install a RPM as a POSIX package (i.e by translating first).

- Package Creation

  Command: `swpackage`

  `swpackage` is at a beta release level. It supports all Product Specification File (PSF) features in the IEEE spec.

- Package Verification

  Command: `swverify`

  `swverify` is used to verify the payload digests and GPG signature (if any) of a POSIX package (i.e. tar archive in POSIX format). `swverify` also is used for verification of installed software.

- Package Removal

  Command: `swremove`

  `swremove` is used to remove installed software.

- Package Listing

  Command: `swlist`

  `swlist` is used to list information about the installed software.

- Package Configuration

  Command: `swconfig`

  `swconfig` is used to configure installed software. It provides a stand-alone execution interface to the package configure scripts.

- Creating GPG Signed Source Packages.

  Command: `swign`

  `swign` is a ad-hoc implementation extension utility.

  `swign` is used to create a GPG signed POSIX package from the contents of the current directory. The intended use is for creation of signed source tar archives.

  It is a shell script that uses `swpackage` and `gpg` and GNU `tar`. Since the created archive is written to stdout by GNU `tar` and makes sanity checks using standard utilities it is safe to use.

Next: Command Reference, Previous: Configuring swbis, Up: Top

## 3 How to invoke swbis

The utilities are invoked from the command line.

The commands share a common syntax that is:

           <sw_utility> [options] [software_selections] [@Targets]

The current swbis utilities are `swpackage`, `swinstall`, `swverify`, `swcopy`, `swign`.

A central element of all the commands is the target syntax. See Target Syntax.

Here are several rules worth remembering about the Target:

- The '@' is required exactly once even when there are multiple targets.
- Multiple targets are separated by whitespace.
- A simple name is assumed to be a host name unless it begins with a '/' in which case it is assumed to be a path on the local host. The POSIX standard requires the target path be an absolute path. The swbis implementation relaxes this somewhat for remote host operations. That is, when a HOSTNAME is given the path may be relative and if so is relative to the login directory for the user [according to how the remote host and ssh are configured].

  If the target path is not given for a remote target, the target path is either '.' or '/' depending on the utility and the defaults files. (The default target path for `swinstall` is always '/')

- The Target Syntax can be applied to the source. The source is specified by the -s option.
- The swbis implementation supports a '-' as a target meaning stdin/stdout, as well as a '.' meaning the current directory.

Here are several example of Targets:

- remote host with a different user:

                @ root@host1

- Two hop target with different user on each host and a path specification on the terminal host:

                @ root@host1@@guest@host2:/tmp/mnt/test

- home directory of the user on host1

                @ user@host1:.

- file named file1 in current directory

                @ :file1     # Impl Extension

The command `swbis` can be used to invoke the swbis utilities. The `swbis` command is useful if the utilities are not installed in $PATH. Alternatively, individual utilities can be invoked by themselves.

Here are some example invocations:

-               swbis --version

-               swbis --help

- Create a signed tar archive descibed by the PSF `/tmp/mypsf`:

                swpackage --sign --gpg-name="Your GPG Identity" --format=ustar -s /tmp/mypsf  >/tmp/foo.tar

- Verify a signed distribution:

                swverify -d @/tmp/foo.tar

- Install a package from stdin to `/`:

                swinstall -s -

- Translate an RPM format package to POSIX format:

                swcopy -s /tmp/myrpm.rpm --audit --allow-rpm @- | tar tvf -

- Create a signed archive of `.`:

                swign -u "Your GPG Identity" @- | tar tvf -

Up: Invoking swbis

### Target Syntax

    Source and Target Specification and Logic

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

              Swbis Extension:
                   [user@]host[:path]
                   [user@]host_port[:path]
                   :path

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

                   [user@]host[@@[user@]host[@@...]][:file]
                   [user@]host_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_port:host_port:
                   host:host:file
                   user@host:user@host:
                   user@host:user@host:host:
                   user@host:user@host:file

         A more formal description:

         target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
                | HOST_CHARACTER_STRING ':'
                | HOST_CHARACTER_STRING
                | PATHNAME_CHARACTER_STRING
                | ':' PATHNAME_CHARACTER_STRING   # Impl extension
                ;

           PATHNAME_CHARACTER_STRING must be an absolute path unless
                           a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
                 | PATHNAME_CHARACTER_STRING
                 ;
        user     : PORTABLE_CHARACTER_STRING  # The user name

        DELIM    : ':'   # The multi-hop delimiter.
                 ;

Next: About This Manual, Previous: Top, Up: Top

## Appendix A Copying This Manual

Up: Copying This Manual

### A.1 GNU Free Documentation License

Version 1.2, November 2002

         Copyright © 2000,2001,2002 Free Software Foundation, Inc.
         59 Temple Place, Suite 330, Boston, MA  02111-1307, USA

         Everyone is permitted to copy and distribute verbatim copies
         of this license document, but changing it is not allowed.

0. PREAMBLE

   The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

   This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

   We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

   This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

   A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

   A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

   The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

   The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

   A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

   Examples of suitable formats for Transparent copies include plain ascii without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

   The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

   A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

   The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. VERBATIM COPYING

   You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

   You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

   If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

   If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

   If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

   It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

   You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
   4. Preserve all the copyright notices of the Document.
   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
   8. Include an unaltered copy of this License.
   9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
   11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
   13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
   14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
   15. Preserve any Warranty Disclaimers.

   If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

   You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

   You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

   The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

   You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

   The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

   In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

6. COLLECTIONS OF DOCUMENTS

   You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

   You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

   A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

   If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. TRANSLATION

   Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

   If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. TERMINATION

   You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

#### A.1.1 ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

           Copyright (C)  year  your name.
           Permission is granted to copy, distribute and/or modify this document
           under the terms of the GNU Free Documentation License, Version 1.2
           or any later version published by the Free Software Foundation;
           with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
           A copy of the license is included in the section entitled ``GNU
           Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:

             with the Invariant Sections being list their titles, with
             the Front-Cover Texts being list, and with the Back-Cover Texts
             being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Next: Other Resources, Previous: Status, Up: Top

## 2 Applicable Standards

The related standards are IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), OpenGroup CAE C701.

ISO/IEC 15068-2:1999 is identical to 1387.2 except for its name.

CAE C701 is nearly identical to 1387.2 and can be viewed online at http://www.opengroup.org/publications/catalog/c701.htm

The implementation reference specification is a printed postscript rendering of the C701 pdf file available at http://www.opengroup.org/publications/catalog/c701.htm (size: 696095 bytes; md5sum: a98e5fd7d723db63e27136c70bfff7aa) and a copy of IEEE Std 1387.2-1995 (ISBN 1-55937-537-X). These two documents match up line-for-line except for chapter ordering and where there are descriptions of C701's additional attributes.

(The IEEE standard is superseded by and identical to ISO/IEC 15068-2:1999).

Next: Making PSFs for Package Creation, Previous: Invoking swbis, Up: Top

## Appendix A Command Reference

Commands

Formats

Conventions, User Manual

Next: (swbis_swinstall), Previous: (swbis_swpackage), Up: Command Reference

### swpackage.8 in one text file

    swpackage(8)		    System Manager's Manual		  swpackage(8)

    NAME
           swpackage — Package a software distribution.

    SYNOPSIS
           swpackage    # Filter: read PSF on stdin, write a tar archive to stdout

           swpackage -s- @-	 # Absolutely explicit, same as above

           swpackage @FILE

           swpackage  [-p]	[-s psf_file]  [-f file] [-x option=value] \
           [-X options_file] [-W option] [software_selections] [@targets]

           swpackage --help # more authoritative documentation

           swpackage  [options] --to-swbis [-s package_file]   # format translator

           swpackage  [options] --resign [-s package_file]	 # modify signatures
           swpackage  [options] --remove-signature=N [-s package_file]
           swpackage  [options] --replace-signature=N [-s package_file]

    DESCRIPTION
           swpackage reads a Product Specification File (PSF) and writes a
           distribution to the specified target.  If no options are given a PSF is
           read on stdin and a distribution is written to the default target
           either a directory, device, or standard output.	To specify standard
           output use a dash '-' as the target.

    OPTIONS
           software_selections
    	      Refer to the software objects (products, filesets) on which to
    	      be operated. (Not yet implemented)

           targets
    	      Refers to the software_collection where the software selections
    	      are to be applied.  To specify standard output use a  dash '-',
    	      this overrides media_type setting to 'serial'.  Target may be a
    	      file, or device file or '-'

           -f FILE
    	      Reads software_selections from FILE. (Not implemented).

           -p
    	      Preview the package.  Perform all the packaging operations
    	      except writing the target.  In verbose level 1, nothing is
    	      written.	Higher verbose levels write information on stdout.
    	      Error and warning messages are written to stderr for verbose
    	      levels 1 and higher.

           -s PSF
    	      Specify the PSF file, "-" is standard input.

           -x option=value
    	      Specify the extended option overriding the defaults file value.

           -X FILE
    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           -v
    	      (Implementation extension.) Given one time it is identical to -x
    	      verbose=2.  This option can be given multiple times with
    	      increasing effect.
    		   level 0: silent on stdout and stderr (not implemented).
    		   level 1: fatal and warning messages.
    	      -v   level 2: level 1 plus file list and trailer message.
    	      -vv  level 3: level 2 verbose tar-like listing.
    	      -vvv level 4: level 3 extra verbose tar listing.

           -b BYTES
    	      Set blocksize to BYTES number of bytes (octets).	The default is
    	      10240.  (implementation extension)

           --version, -V
    	      Alternate Mode: Show version. (Implementation extension)

           --help
    	      Alternate Mode: Show help (Implementation extension)

           -W option[,option,...]
    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           -W cksum
    	      Compute POSIX cksum of the individual files.

           -W file-digests -W digests
    	      Compute md5 digests of the individual files.  (-W digests is
    	      deprecated, use -W file-digests).

           -W files
    	      Store the distribution file list in .../dfiles/files.

           -W dir=NAME
    	      Use NAME as the path name prefix of a distribution and also as
    	      the value of the distribution.control_directory and
    	      distribution.tag attribute (if not set).	May be set to an empty
    	      string to eliminate stray leading "./".

           -W sign
    	      Compute the md5sum, sha1sum and adjunct_md5sum digests and sign
    	      the package.

           -W dummy-sign
    	      Same as -W sign except use a dummy signature.  The signer
    	      program is not run and no password is required.

           -W signer-pgm=SIGNER
    	      Recognized SIGNERs are GPG, PGP2.6, and PGP5.  swverify only
    	      supports GPG, however, other types can be verified manually
    	      using the options of swverify and command line utilities.

           -W archive-digests
    	      Compute the md5sum, sha1sum and adjunct_md5sum digests.  See
    	      sw(5) for info on the digest and signed data input files.	 The
    	      sha1sum and md5sum attributes have identical input streams.

           -W no-sha1
    	      Do not compute the sha1 digest even if directed to by other
    	      options.	(Deprecated: There is limited reason to use this
    	      option).

           -W signed-file
    	      Write only the signed data to the specified target but do not
    	      sign.  (Deprecated: There is limited reason to use this option).

           -W gpg-name=NAME
    	      Use NAME as the user ID to sign.	NAME becomes the option arg of
    	      the gpg --local-user option.

           -W gpg-path=PATH
    	      Use PATH as the gpg homedir.

           -W gzip
    	      compress output with file system gzip utilty

           -W bzip2
    	      compress output with file system bzip2 utility
           -W lzma
    	      compress output with file system lzma utility

           -W symmetric
    	      encrypt output with file system gpg utility

           -W encrypt-for-recipient=NAME
    	      encrypt with NAME's public key using file system gpg utility

           -W source=FILE
    	      Use serial archive located at FILE as the source instead of the
    	      file system.  The files referred by the PSF are taken from the
    	      serial archive and not the file system.

           -W numeric-owner
    	      Same as GNU tar option.  Emitted archive has only uid and gids.

           -W absolute-names
    	      Same as GNU tar option.  Leading slash '/' are always stripped
    	      unless this option is given.

           -W format=FORMAT
    	      The default format is 'pax'.  The pax format will only generate
    	      extended headers if needed.  FORMAT is one of:

    	       ustar   is the POSIX.1 tar format capable of storing
    		       pathnames up to 255 characters in length.
    		       Identical to GNU tar 1.15.1 --format=ustar
    	       ustar0  is a different POSIX.1 tar personality.
    		       Identical to GNU tar 1.13.25 --posix -b1 for 99 char pathnames
    		       Has different rendering of device numbers for non-device files,
    		       but otherwise identical to 'ustar'
    	       gnu     Identical to GNU tar version 1.15.1 --format=gnu
    	       oldgnu  Identical to GNU tar version 1.13 and later with
    			   block size set to 1. i.e. with option -b1.
    		       Also identical to GNU tar 1.15.1 --format=oldgnu
    	       gnutar  same as oldgnu, oldgnu preferred.
    	       pax     Extended header tar (Default)
    	       odc     Posix.1 cpio (magic 070707).
    	       newc    cpio format (magic 070701).
    	       crc     cpio format (magic 070702).
    	       bsdpax3 Identical to pax v3.0, ustar format with option -b 512.

           -W pax-header-pid=NUMBER
    	      Sets the number used in any pax header naming scheme to NUMBER.
    	      You must use this option to make archive identical in subsequent
    	      (back-to-back) invocations.

           -W uuid=STRING
    	      Sets the uuid string to STRING instead of calling uuid(1) You
    	      must use this option to make the catalog directory identical in
    	      subsequent (back-to-back) invocations.

           -W create-time=TIME
    	      Applies to catalog files and the create_time attribute.  TIME is
    	      the seconds since the Unix Epoch.	 You must use this option to
    	      make the catalog directory identical in subsequent (back-to-
    	      back) invocations.

           -W list-psf
    	      Write the PSF to stdout after having processed the extended
    	      definitions.

           -W to-swbis
    	      Alternate Mode: Read a package on standard input and write a
    	      POSIX package on standard output.	 Requires the
    	      .../libexec/swbis/lxpsf program.	Supported formats are any
    	      supported format of lxpsf.  Identical to:
    	      /swbis/lxpsf --psf-form3 -H ustar | swpackage -Wsource=- -s@PSF

           -W passphrase-fd=N
    	      Read the passphrase on file descriptor N.

           -W passfile=FILE
    	      Read the passphrase from FILE in the file system.	 Setting FILE
    	      to /dev/tty resets (i.e unsets) all passphrase directives, thus
    	      establishing the default action, reading from the terminal.

           -W dir-owner=OWNER
    	      Set the owner of the leading directory archive member to OWNER.
    	      If the option arg is "", then the owner is the owner of the
    	      current directory.

           -W dir-group=OWNER
    	      Set the group of the leading directory archive member to OWNER.
    	      If the option arg is "", then the owner is the owner of the
    	      current directory.

           -W dir-modep=MODE
    	      Set the file permissions mode of the leading directory archive
    	      member to MODE.

           -W catalog-owner=OWNER
    	      Set the owner of the catalog section to OWNER.

           -W catalog-group=GROUP
    	      Set the group of the catalog section to GROUP.

           -W files-from=NAME
    	      Read a list of files from file NAME.  Directories are not
    	      descended recursively.

           -W show-options-files
    	      Alternate Mode: Show the complete list of options files and if
    	      they are found.

           -W show-options
    	      Alternate Mode: Show the options after reading the files and
    	      parsing the command line options.

           -W no-catalog
    	      Do not write the catalog section.

           -W no-front-dir
    	      Do not write the directory archive members that preceed the
    	      catalog section.

           Signature Modification Options.	The source file via '-s' option is a
           previously signed archive file.

           --addsign
    	      Alternate Mode: Same as --add-signature-first

           --delsign
    	      Alternate Mode: Opposite of --addsign,  Same as --remove-
    	      signature=1

           --add-signature-first
    	      Alternate Mode: Add signature first in the list of package
    	      signatures.  The last signature, by convention, is the primary
    	      signature.

           --add-signature-last
    	      Alternate Mode: Add signature last in the list of package
    	      signatures.  The last signature, by convention, is the primary
    	      signature.
           --replace-signature=N
    	      Alternate Mode: Replace Nth signature, 0 means last signature.
           --remove-signature=N
    	      Alternate Mode: Remove Nth signature, 0 means last signature.
           --resign
    	      Alternate Mode: Same as --replace-signature=0
           --resign-test, --zfilter
    	      Alternate Mode: Copy from source to target without altering.
    	      Does not generate a signature.  The output should be identical
    	      to the input.   Also has unintended use of accessing the
    	      compression pipeline function of swpackage.

           --recompress
    	      Modifier to alternate Mode: Applies when modifying signature.
    	      The compression methods of the input file are detected and the
    	      output is compressed to match.

           --overwrite
    	      Modifier to alternate Mode: Overwrites file specified as the
    	      source name (by the -s FILE option).  Will likely do so safely.

    EXTENDED OPTIONS
           These extended options can be specified on the command line using the
           -x option or from the defaults file, swdefaults.

       Posix
           Shown below is an actual portion of a defaults file which show default
           values.	These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults file.

           swpackage.distribution_target_directory	= /var/spool/sw	  # Not used
           swpackage.distribution_target_serial	= -	   # Not used
           swpackage.enforce_dsa			= false	   # Not used
           swpackage.follow_symlinks		= false	   # Not used
           swpackage.logfile	  = /var/lib/swbis/swpackage.log   # Not used
           swpackage.loglevel			= 1	    # Not used
           swpackage.media_capacity			= 0	    # Not used
           swpackage.media_type			= serial    # Not used
           swpackage.psf_source_file		= -	    # Not used
           swpackage.software			=	    # Not used
           swpackage.verbose			= 1	    # May be 1 2 or 3

       Swbis Implementation
           These extended options can be specified on the command line using
           -Woption=optionarg or --option=optionarg syntax.

           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ~/.swbis/swbisdefaults file.

           swpackage.swbis_cksum			= "false"   # true or false
           swpackage.swbis_file_digests		= "false"   # true or false
           swpackage.swbis_file_digests_sha2	= "false"   # true or false
           swpackage.swbis_files			= "false"   # true or false
           swpackage.swbis_sign			= "false"   # true or false
           swpackage.swbis_archive_digests		= "false"   # true or false
           swpackage.swbis_archive_digests_sha2	= "false"   # true or false
           swpackage.swbis_gpg_name			= ""
           swpackage.swbis_gpg_path			= "~/.gnupg"
           swpackage.swbis_gzip			= "false"   # true or false
           swpackage.swbis_bzip2			= "false"   # true or false
           swpackage.swbis_numeric_owner		= "false"   # true or false
           swpackage.swbis_absolute_names		= "false"   # true or false
           swpackage.swbis_format			= "ustar"  # gnutar or ustar
           swpackage.swbis_signer_pgm		= "GPG" # GPG or PGP5 or PGP2.6

    USAGE EXAMPLES
           Here are some commonly used options.

       Options and Option Files
           Show the option file options and the option files that determine the
           default values.

    	    swpackage --show-options
    		 # and
    	    swpackage --show-options-files

       Preview the output
           Show a verbose tar-like file listing on stdout

    	    swpackage -pv
    		  # or
    	    swpackage -pvv

       Create a signed package
           Read the PSF on standard input, sign using 'admin' key using the gpg-
           agent.  Include sha2 digests for the files and archive. Include the
           file list, compress the output using xz writing to standard output.

    	    swpackage -s - --sign --use-agent --gpg-name=admin --files \
    		 --sha1 --sha2 --xz @-

       Resign a package
           Resign a previously signed package, overwriting the original file

    	    swpackage --resign -s foo.tar.gz --overwrite --recompress

       Idempotent Invocation
           Use special options to obtain an identical package two or more times

    	    swpackage --create-time=1406254892 \
    		 --uuid=ed3b9432-3ba1-4c01-a125-e22fb94588e2 \
    		 --pax-header-pid=1001

       ALternative Format Translation
           Execute the internally generated pipeline for format translation
           manually

    	    # the following is equivalent to  'swpackage --to-swbis'

    		 /usr/local/libexec/swbis/lxpsf --psf-form3 \
    			-H ustar | swpackage -Wsource=- -s@PSF

    PACKAGE SIGNING
           Support for embedded cryptographic signature

       Description
           Package signing is accomplished by including, as a package attribute, a
           detached signature in the package metadata (the catalog section of the
           package).  The signed data is the catalog section of the package (see
           sw(5) for a description) excluding the signature files archive header
           and data.  The package leading directory that does not contain the
           /catalog/ directory in its name is not included in the signed stream.
           The signed stream is terminated by two (2) null tar blocks (which are
           not in the actual package file).	 The storage section (or payload) of
           the package is included in the signed data by computing its md5 and
           sha1 message digests and storing these as attributes in the catalog
           section.

       Signature Generation
           The signature is generated by the file system signing utility.
           Currently, swpackage supports GPG PGP-2.6 and PGP-5.  The default is
           GPG but can be selected using the -Wsigner-pgm command line option and
           the swpackage.swbis_signer_pgm defaults file option.  The options and
           program can the displayed with the -Wshow-signer-pgm option.  The
           options in each case produce a detached ascii-armored signature.	 The
           maximum length for the ascii armored file is 1023 bytes.

       Passphrase Handling
           The passphrase can be read from the tty, a file descriptor, and
           environment variable or the GNUpg passphrase agent.  These are
           controlled by the options or the environment variables SWPACKAGEPASSFD
           and SWPACKAGEPASSPHRASE.	 Placing your passphrase in an environment
           variable is insecure but may be usefull to sign packages with a test
           key and later replace it [when on a different host for example].

    SIGNATURE VERIFICATION
           swpackage does not perform verification of the embedded cryptographic
           signature, although, a description is included here for completness.

       Overview
           Verification requires verifying the payload section md5 and sha1
           message digests and then verifying the signature.  Naturally, it is
           required that the signed data include the payload messages digests.
           See swverify.

       Manual Verification
           Verification requires re-creating the signed and digested byte streams
           from the archive file.  This is not possible using any known extant tar
           reading utility because of a lack of ability to write selected archive
           members to stdout instead of installing in the file system; however,
           the swverify utility can be used to write these bytes streams to stdout
           allowing manual inspection and verification.  See swverify.

       Manual Verification Using Standard Tools
           Verification using standard GNU/Linux tools is possible if the archive
           is installed in the file system.	 Success depends on the following
           factors:

           1) The tar utility preserves modification times
    	  (e.g. not GNU tar 1.3.19).
           2) The archive does not contain Symbolic Links
    	  (see sw(5) for explanation).
           3) The file system is a Unix file system (e.g. ext2).
           4) The package was created using -Wformat=gnutar or, -Wformat=ustar
    	  with no file name longer than 99 octets.

    	Recreating the signed and digested byte streams is then accomplished
           using GNU tar and the file list stored in the
           <path>/catalog/dfiles/files attribute file as follows:

           In this example, the package has a single path name prefix called,
           namedir and the file owner/group are root.  These restrictions are
           suited to source packages.
           Verify the signature:

    	 #!/bin/sh
    	 tar cf - -b1 --owner=root --group=root \
    	 --exclude=namedir/catalog/dfiles/signature  \
    	 namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -

    	If this fails try using GNU tar option --posix.	 If this fails then
           you are out of luck as nothing in the catalog section can be trusted.

           Verify the payload digests:

    	 #!/bin/sh
    	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
    	 tar cf - -b1 --owner=root --group=root \
    	 --no-recursion --files-from=- | md5sum
    	 cat namedir/catalog/dfiles/md5sum

    	Likewise for the sha1 digest.

           If the package has symbolic links, Verify the adjunct_md5sum:

    	 #!/bin/sh
    	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
    	 ( while read file; do if [ ! -h $file ]; then echo $file; fi done; )|\
    	 tar cf - -b1 --owner=root --group=root \
    	 --no-recursion --files-from=- | md5sum
    	 cat namedir/catalog/dfiles/adjunct_md5sum

    	The symbolic link files must be verified manually by comparing to the
           INFO file information.

    SWPACKAGE OUTPUT FORMAT
           The output format is either one of two formats specified in POSIX.1
           (ISO/IEC 9945-1) which are tar (header magic=ustar) or cpio (header
           magic=070707).  The default format of the swbis implementation is
           "ustar".	 The POSIX spec under specifies definitions for some of the
           ustar header fields.  The personality of the default swbis ustar format
           mimics GNU tar 1.15.1 and is designed to be compliant to POSIX.1.  The
           personality of the "ustar0" format mimics, for pathnames less than 99
           octets,	GNU tar 1.13.25 using the "-b1 --posix" options.  This bit-
           for-bit sameness does not exist for pathnames greater than 99 chars as
           swbis follows the POSIX spec and GNU tar 1.13.25 does not.  The
           "ustar0" ustar personality is deprecated.  It is only slightly
           different from 'ustar' in how device number fields are filled (with
           spaces, zeros or NULs) for non-device files.

           In addition the swbis implementation supports several other tar
           variants including bit-for-bit mimicry of GNU tar (1.13.25) default
           format which uses a non-standard name split and file type (type 'L').
           This format is known as '--format=oldgnu'.  Also supported is the gnu
           format of GNU tar 1.15.1 specified by '--format=gnu'

           The defacto cpio formats are also supported.  "new ASCII" (sometimes
           called SVR4 cpio) and "crc" cpio formats with header magic "070701" and
           "070702" respectively.

           Support for "pax Interchange Format" (Extended header tar) described in
           IEEE 1003.1-2001 under the "pax" manual page has been implemented for
           POSIX file attributes as of release 1.12 (c Aug2014).  The 'swpackage'
           utility will generate extended headers on an as needed basis when the
           --format=pax is used.  Support for POSIX ACL and SELinux attributes is
           planned.

           The entirety of the output byte stream is a single valid file of one
           the formats mentioned above.

           The swbis implementation writes its output to stdout.  The default
           output block size is 10240 bytes.  The last block is not padded and
           therefore the last write(2) may be a short write.  The selected block
           size does not affect the output file contents.

           The swbis implementation is biased, in terms of capability and default
           settings, to the tar format.  Package signing is only supported in tar
           format.

    SWPACKAGE INPUT FILE FORMAT
           The input file is called a product specification file or PSF.  It
           contains information to direct swpackage and information that is
           package meta-data [that is merely transferred unchanged into the global
           INDEX file].

           A PSF may contain object keywords, attributes (keyword/value pairs) and
           Extended Definitions (described below).	An object keyword connotes a
           logical object (i.e. software structure) supported by the standard.  An
           object keyword does not have a value field after it, as it contains
           Attributes and Extended Definitions.  An attribute keyword conotes an
           attribute which is always in the form of a keyword/value pair.

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

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

           The file syntax is the same as a INDEX, or INFO file.  A PSF may
           contain all objects defined by the standard as well as extended
           definitions.

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

       EXTENDED DEFINITIONS
           A Product Specification File (PSF) can contain Extended Definitions in
           the fileset, product or bundle software definitions.  They would have
           the same level or containment relationship as a file or control_file
           definition in the same contaning object.

           Extended Definitions represent a minimal, expressive form for
           specifying files and file attributes.  Their use in a PSF is optional
           in that an equivalent PSF can be constructed without using them,
           however, their use is encouraged for the sake of brevity and
           orthogonality.

           The swbis implementation requires that no [ordinary] attributes appear
           after Extended Definitions in the containing object, and, requires that
           Extended Definitions appear before logically contained objects.	That
           is, the parser uses the next object keyword to syntacticly and
           logically terminate the current object even if the current object has
           logically contained objects.

       o  Extended Control File Definitions
    	    checkinstall  source  [path]
    	    preinstall	  source  [path]
    	    postinstall	  source  [path]
    	    verify	  source  [path]
    	    fix		  source  [path]
    	    checkremove	  source  [path]
    	    preremove	  source  [path]
    	    postremove	  source  [path]
    	    configure	  source  [path]
    	    unconfigure	  source  [path]
    	    request	  source  [path]
    	    unpreinstall  source  [path]
    	    unpostinstall source  [path]
    	    space	  source  [path]
    	    control_file  source  [path]

           The source attribute defines the location in distributors's development
           system where the swpackage utility will find the script.	 The keyword
           is the value of the tag attribute and tells the utilities when to
           execute the script.  The path attribute is optional and specifies the
           file name in the packages distribution relative to the
           control_directory for software containing the script. If not given the
           tag value is used as the filename.

       o  Directory Mapping
    	  directory  source  [destination]

           Applies the source attribute as the directory under which the
           subsequently listed files are located.  If destination is defined it
           will be used as a prefix to the path (implied) file definition.	source
           is typically a temporary or build location and dest is its unrealized
           absolute pathname destination.

       o  Recursive File Definition
    	 file *

           Specifies every file in current source directory.  The directory
           extended definition must be used before the recursive specification.

       o  Explicit File Definition
    	 file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]

           source

    	      source defines the pathname of the file to be used as the source
    	      of file data and/or attributes.  If it is a relative path, then
    	      swpackage searches for this file relative to the the source
    	      argument of the directory keyword, if set.  If directory keyword
    	      is not set then the search is relative to the current working
    	      directory of the swpackage utility's invocation.

    	      All attributes for the destination file are taken from the
    	      source file, unless a file_permissions keyword is active, or the
    	      -m, -o, or -g options are also included in the file
    	      specification.

           path

    	      path defines the destination path where the file will be created
    	      or installed.  If it is a relative path, then the destination
    	      path of the of the directory keyword must be active and will be
    	      used as the path prefix.	If path is not specified then source
    	      is used as the value of path and directory mapping applied (if
    	      active).

           -t type

    	      type may one of 'd' (directory), or  'h' (hard link), or 's'
    	      (symbolic link).

    	      -t d  Create a directory.
    	      If path is not specified source is used as the path attribute.

    	      -t h  Create a hard link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

    	      -t s  Create a symbolic link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

           -m mode

    	      mode defines the octal mode for the file.

       o  Default Permission Definition
    	 file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]

           Applies to subsequently listed file definitions in a fileset.  These
           attributes will apply where the file attributes were not specified
           explicitly in a file definition.	 Subsequent file_permissions
           definitions simply replace previous definitions (resetting all the
           options).

           To reset the file_permission state (i.e. turn it off) use one of the
           following:
    	   file_permissions ""
    	    or the preferred way is
    	   file_permissions -u 000

       o  Excluding Files
    	  exclude source

           Excludes a previously included file or an entire directory.

       o  Including Files
    	  include <filename

           The contents of filename may be more definitions for files.  The syntax
           of the included file is PSF syntax.

       SWBIS PSF CONVENTIONS
           This section describes attribute usage and conventions imposed by the
           swbis implementation.  Not all attributes are listed here.  Those that
           are have important effects or particular interest.

       o Distribution Attributes
           The standard defines a limited set of attributes for the distribution
           object.	An expanded set is suggested by the informative annex however
           a conforming implementation is not required act on them.	 The reason
           for this is a distribution may be acted upon by a conforming utility in
           such a way that attributes of the distribution become invalid.  For
           this reason, some attributes that refer to an entire "package" [in
           other package managers] are referred from the product object and attain
           their broadened scope by the distributor's convention that their
           distribution contains just one product.

           For example, the package NAME and VERSION are referred from the product
           tag and revision, not the distribution's.  This convention supports
           multiple products in a distribution and is consistent with the
           standard.

           tag

    	      tag is the short, file system friendly, name of the
    	      distribution.  Providing a distribution tag is optional.	The
    	      swbis implementation will use this as the [single] path name
    	      prefix if there is no distribution.control_directory attribute.
    	      A distribution tag attribute and swpackage's response to it is
    	      an implementation extension.  The leading package path can also
    	      be controlled with the ''-W dir'' option.

           control_directory

    	      control_directory, in a distribution object, is the constant
    	      leading package path.  Providing this attribute is optional.  A
    	      distribution control_directory attribute and swpackage's
    	      response to it is an implementation extension.  The leading
    	      package path can also be controlled with the ''-W dir'' option.
    	      This attribute will be generated by swpackage if not set in a
    	      PSF.

       o Bundle Attributes
           A bundle defines a collection of products whether or not the
           distribution has all the products present.

           tag

    	      tag is the short, file system friendly, name of the bundle.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  If it is not
    	      present the product tag is used.

       o Product Attributes
           A product defines the software product.

           tag

    	      tag is the short, file system friendly, name of the product.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  It is required.
    	      The swbis implementation uses it in a way that is analogous to
    	      the RPMTAG_NAME attribute, namely as the public recognizable
    	      name of the package.

           control_directory

    	      Is the directory name in the distribution under which the
    	      product contents are located.  This value has no affect on the
    	      installed software catalog.  If it is not given in a PSF then
    	      the tag is used.

           revision

    	      Is the product revision.	It should not contain a "RELEASE"
    	      attribute part or other version suffix modifiers.	 This value is
    	      used by the swbis implementation as a path name component in the
    	      installed software catalog.  It is required by swinstall.

           vendor_tag

    	      This is a short identifying name of the distributor that
    	      supplied the product and may associate (refer to) a vendor
    	      object from the INDEX file that has a matching tag attribute.
    	      This attribute is optional.  This attribute value should strive
    	      to be unique among all distributors. The swbis implementation
    	      modifies the intended usage slightly as a string that strives to
    	      be globally unique for a given product.tag and product.revision.
    	      In this capacity it serves to distinguish products with the same
    	      revision and tag from the same or different distributor.	It
    	      most closely maps to the RPMTAG_RELEASE or "debian_revision"
    	      attributes.  It is one of the version distinguishing attributes
    	      of a product specified by the standard.  It is transfered into
    	      the installed_software catalog (not as a path name component) by
    	      swinstall.  If this attribute exists there should also be a
    	      vendor object in the PSF in the distribution object that has
    	      this tag.	 This attribute is assigned the value of
    	      RPMTAG_RELEASE by swpackage when translating an RPM.

           architecture

    	      This string is one of the version attributes.  It is used to
    	      disambiguate products that have the same tag, revision and
    	      vendor_tag.  It is not used for determining a products
    	      compatibility with a host.  The form is implementation defined.
    	      swbis uses the output of GNU config.guess as the value of this
    	      string.  A wildcard pattern should not be used.  The canonical
    	      swbis architecture string can be listed with swlist. For example

    	      swlist -a architecture @ localhost

    	       Here are some example outputs from real systems.

    		  System      `uname -srm`		architecture
    	      Red Hat 8.0:  Linux 2.4.18 i686	     i686-pc-linux-gnu
    	      OpenSolaris:  SunOS 5.11 i86pc	     i386-pc-solaris2.11
    	      NetBSD 3.1:   NetBSD 3.1 i386	     i386-unknown-netbsdelf3.1
    	      Red Hat 4.1:  Linux 2.0.36 i586	     i586-pc-linux-gnulibc1
    	      Debian 3.1:   Linux 2.6.8-2-386 i686   i686-pc-linux-gnu

           os_name os_release os_version machine_type

    	      These attributes are used to determine compatibility with a
    	      host.  They correspond to the uname attributes defined by
    	      POSIX.1.	If an value is nil or non-existent it is assumed to
    	      match the host.  All attributes must match for there to be
    	      compatibility.  Distributors may wish to make these values a
    	      shell pattern in their PSF's so to match the intended collection
    	      of hosts.	 swbis uses fnmatch (with FLAGS=0) to determine a
    	      match.

       o Fileset Attributes
           A fileset defines the fileset.

           tag

    	      tag is the short, file system friendly, name of the fileset.  It
    	      is required although selection of filesets is  not yet supported
    	      therefore the end user will have little to do with the fileset
    	      tag.

           control_directory

    	      Is the directory name in the product under which the fileset
    	      contents are located.  This value has no affect on the installed
    	      software catalog.	 If it is not given in a PSF then the tag is
    	      used.

       o Example Source Package PSF
           This PSF packages every file is current directory. It uses nil control
           directories so the package structure does not change relative to a
           vanilla tarball.

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING
    	vendor
    	  the_term_vendor_is_misleading false
    	  tag fooware
    	  title fooware Consultancy Services, Inc.
    	  description ""
    	vendor
    	  the_term_vendor_is_misleading true
    	  tag myfixes1
    	  title Bug fixes, Set 1
    	  description "a place for more detailed description"
    	product
    	  tag fooit
    	  control_directory ""
    	  revision 1.0
    	  vendor_tag myfixes1  # Matches the vendor object above
    	fileset
    	   tag fooit-SOURCE
    	   control_directory ""
    	   directory .
    	   file *
    	   exclude catalog

       o Example Runtime (Binary) Package PSF
           This is a sample PSF for a runtime package.  It implies multiple
           products (e.g. sub-packages) using the bundle.contents attribute.
           Since the bundle and product tags exist in a un-regulated namespace and
           are seen by end users they should be carefully chosen.	Note that the
           bundle and product have the same tag which may force downstream users
           to disambiguate using software selection syntax such as fooit,bv=* or
           fooit,pv=* .

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING

    	    vendor
    	       the_term_vendor_is_misleading false
    	       tag fooware
    	       title fooware Consultancy Services, Inc.
    	       description "Provider of the programs
    	that do everything"

    	    vendor
    	       the_term_vendor_is_misleading true
    		tag fw0
    		title fooware fixes
    		description "More fixes from the fooware users"

           #  Bundle definition:  Use a bundle
    	    bundle
    		tag fooit
    		vendor_tag fooware
    		contents fooit,v=fw0 fooit-devel fooit-doc

           #  Product definition:
    	    product
    		tag fooit   # This is the package name
    		revision 1.0 # This is the package version
    		vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
    		postinstall scripts/postinstall
    	    fileset
    		 tag fooit-RUN
    		 file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
    		 file src/fooit /usr/bin/fooit

    SAMPLE PRODUCT SPEC FILES
           This section shows several example PSF files.

       o   A minimal PSF to package all files in current directory.
    	distribution
    	product
    	  tag prod
    	  control_directory ""
    	  revision 1.0
    	fileset
    	   tag files
    	   control_directory ""
    	   directory .
    	   file *

       o   A PSF that uses directory mapping.
           This PSF creates a package with live system paths from source that is
           installed in non-live temporary locations. It is modeled on the swbis
           source package.

    	distribution
    	product
    	  tag somepackage  # this is the package name
    	  control_directory ""
    	  revision 1.0	# this is the package revision
    	fileset
    	   tag files
    	   control_directory ""

    	   file_permissions -o root -g root
    	   directory swprogs /usr/bin
    	   file swpackage
    	   file swinstall
    	   file swverify

    	   file -m 755 -o root -g root / /usr/libexec/swbis

    	   directory swprogs /usr/libexec/swbis
    	   file swbisparse

    	   directory swsupplib/progs /usr/libexec/swbis
    	   file swbistar

    	   file -m 755 -o root -g root / /usr/share/doc/swbis
    	   directory . /usr/share/doc/swbis
    	   file -m 444 ./README
    	   file -m 444 CHANGES

           When this PSF is processed by the command:

    		   swpackage -Wsign -s - @- | tar tvf -

           It produces the following:

    	drwxr-x--- root/root	  0 2003-06-03 ... catalog/
    	-rw-r----- root/root	307 2003-06-03 ... catalog/INDEX
    	drwxr-x--- root/root	  0 2003-06-03 ... catalog/dfiles/
    	-rw-r----- root/root	 65 2003-06-03 ... catalog/dfiles/INFO
    	-rw-r----- root/root	 33 2003-06-03 ... catalog/dfiles/md5sum
    	-rw-r----- root/root	 41 2003-06-03 ... catalog/dfiles/sha1sum
    	-rw-r----- root/root	 33 2003-06-03 ... catalog/dfiles/adjunct_md5sum
    	-rw-r----- root/root	512 2003-06-03 ... catalog/dfiles/sig_header
    	-rw-r----- root/root   1024 2003-06-03 ... catalog/dfiles/signature
    	drwxr-x--- root/root	  0 2003-06-03 ... catalog/pfiles/
    	-rw-r----- root/root	 65 2003-06-03 ... catalog/pfiles/INFO
    	-rw-r----- root/root   1503 2003-06-03 ... catalog/INFO
    	-rwxr-xr-x root/root 510787 2003-06-03 ... usr/bin/swpackage
    	-rwxr-xr-x root/root 301255 2003-06-03 ... usr/bin/swinstall
    	-rwxr-xr-x root/root   4105 2003-06-03 ... usr/bin/swverify
    	drwxr-xr-x root/root	  0 2003-06-03 ... usr/libexec/swbis/
    	-rwxr-xr-x root/root 365105 2003-06-03 ... usr/libexec/swbis/swbisparse
    	-rwxr-xr-x root/root 243190 2003-06-03 ... usr/libexec/swbis/swbistar
    	drwxr-xr-x root/root	  0 2003-06-03 ... usr/share/doc/swbis/
    	-r--r--r-- root/root   8654 2003-05-27 ... usr/share/doc/swbis/README
    	-r--r--r-- root/root  10952 2003-06-03 ... usr/share/doc/swbis/CHANGES

       o   Create a PSF from a list of files.
    		  find . -print |  swpackage -Wfiles-from=- -Wlist-psf

    RETURN VALUE
           0 on success, 1 on error and target medium not modified, 2 on error if
           target medium modified.

    SIDE EFFECTS
    	No temporary files are used in the package generation process.	When
           using the default target of stdout (directed to /dev/null), there are
           no file system side effects from swpackage.  GNU Privacy Guard (gpg)
           may alter its keys when invoked for package signing.

    ENVIRONMENT
           SWPACKAGEPASSFD
    	      Sets the --passphrase-fd option.	Set the option arg to a
    	      integer value of the file descriptor, or to "env" to read the
    	      passphrase from the environment variable SWPACKAGEPASSPHRASE, or
    	      to "agent" to cause gpg to use gpg-agent, or to "tty" to restore
    	      default behavoir to reading passphrase from the terminal.

           SWPACKAGEPASSPHRASE
    	      Use the value as the passphrase if --passphrase-fd is set to
    	      "env"

           GNUPGHOME
    	      Sets the --gpg-home option.

           GNUPGNAME
    	      Sets the --gpg-name option, which is turn set the --local-user
    	      option of gpg.

    REQUISITE UTILITIES
           Swpackage does not use any archive writing utilities, it has its own
           code to generate archives.
           Package signing uses one of the following:
    	/usr/bin/gpg
    	/usr/bin/pgp   (PGP 2.6.x)
    	/usr/bin/pgps  (PGP 5)

           Swpackage will use /usr/bin/uuidgen if present to create the uuid.

    FILES
           libdir/swbis/swdefaults
           libbir/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701.

    SEE ALSO
           info swbis

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

    IDENTIFICATION
    	swpackage(8): The packaging utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2014-07-15
    	Copying: GNU Free Documentation License

    BUGS
           A comment after an object keyword is wrongly not allowed by this PSF
           parser.	The --dir="" does not do what one would expect sometimes.  The
           output stream content is unaffected by the blocksize, that is the last
           write may be short write.  Signing is broken for cpio format archives.

    								  swpackage(8)

Next: (swbis_swremove), Previous: (swbis_swinstall), Up: Command Reference

### swinstall.8 in one text file

    swinstall(8)		    System Manager's Manual		  swinstall(8)

    NAME
           swinstall — Install POSIX and RPM packages.

    SYNOPSIS
           swinstall [-p] [-r] [-s source_file] [-f file] \
           [-t targetfile] [-x option=value]  [-X options_file] [-W option] \
           [software_selections] [@target [target1...]]

           swinstall -s -	 # Minimum unambiguous invocation.

    DESCRIPTION
           swinstall installs a POSIX distribution from a source archive to a
           target directory.  A POSIX distribution is a package, typically a
           compressed tarball with metadata files in the prescribed file layout.
           Neither swinstall nor any component of swbis is required on the target
           host, however, the target host must look like a Unix system at the
           shell and command-line utility level and have a POSIX shell.  Remote
           network connections are made by ssh.  Ssh is the default but rsh can be
           selected by a command line option.

           By default and with no external influences (i.e. swdefaults file)
           swinstall will read an archive on stdin and install all products and
           filesets of package in "/" directory on the target host.	 An alternate
           root may be specified using the target syntax.  The distribution source
           directory (swbis default: stdin) is selectable via the defaults file,
           therefore it should be specified in uncontrolled environments.

           swinstall operates on  cpio or tar archives.  swinstall supports cpio
           archives by first translating to tar format, therefore, to reduce the
           data transformations performed by swinstall, distributors encouraged to
           deliver products in tar format.

           swinstall will create an entry in an installed software catalog.	 This
           is a directory usually located at /var/lib/swbis/catalog.  Using this
           information checks for upgrade, downdate, dependencies, and
           reinstallation are made.

    OPTIONS
           -f FILE

    	      Reads software_selections from FILE. (Not implemented).

           -p

    	      Preview the operation.  Depending on the verbose level
    	      information is written to stdout.	 The target is not modified
    	      although a remote connection is established.

           -r

    	      This option has no affect.

           -s SOURCE

    	      Specify the source file SOURCE, "-" is standard input.  The
    	      syntax is the same as for a target.  SOURCE may be an archive
    	      file or stdin.

           -t targetfile

    	      Specify a file containing a list of targets (one per line).

           -x option=value

    	      Specify the extended option overriding the defaults file value.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           -v

    	      Given one time it is identical to -x verbose=2.  This option can
    	      be given multiple times with increasing effect.  (Implementation
    	      extension option).
    	      -v  is level 2, -vv is level 3,... etc.
    		  level 0: silent on stdout and stderr.
    		  level 1: fatal and warning messages to stderr.
    	      -v  level 2: level 1 plus a progress bar.
    	      -vv level 3: level 2 plus script stderr.
    	      -vvv level 4: level 3 plus events.
    	      -vvvv level 5: level 4 plus events.
    	      -vvvvv level 6: level 5 plus set shell -vx option.
    	      -vvvvvv level 7 and higher: level 6 plus debugging messages.

           --version, -V

    	      Show version (Implementation extension)

           --help

    	      Show help (Implementation extension)

           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           -W preview-tar-file=FILE

    	      This is a testing/development option.  Writes the fileset
    	      archive to FILE.	This is the same data stream that would have
    	      been loaded on the target.  This option should only be used with
    	      the '-p' option.	The output sent to FILE is a tar archive but
    	      without trailer blocks.

           -W remote-shell=NAME

    	      Defaults File Option: swbis_remote_shell_client

    	      This is the remote connection client program on the management
    	      (originating host).  The path NAME may be an absolute path (not
    	      located in $PATH).  The basename of NAME is used for
    	      intermediate hops.  Supported shells are "ssh" and "rsh".	 The
    	      default is "ssh".

           -W quiet-progress

    	      Defaults File Option: swbis_quiet_progress_bar Disable progress
    	      bar, which is active for verbose levels 2 and higher (i.e. -v).

           -W show-options-files
    	      Show the complete list of options files and if they are found.

           -W show-options
    	      Show the options after reading the files and parsing the command
    	      line options.

           -W pax-command={tar|pax|star|gtar}
    	      Set the portable archive command for all operations.  The
    	      default is "pax".

           -W pax-read-command={tar|pax|star|gtar}
    	      Set the read command for local and remote hosts.

           -W remote-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_remote_pax_read_command
    	      Set the read command for remote hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W local-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_local_pax_read_command
    	      Set the read command for local hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W pax-write-command={tar|pax|star|gtar|swbistar}
    	      Set the write command for local and remote hosts.	 This is the
    	      command that runs on the target (e.g. pax -w, tar cf -).

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the write command for remote hosts.

           -W local-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_local_pax_write_command
    	      Set the portable archive write command for local host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the portable archive write command for remote host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W no-defaults
    	      Do not read any defaults files.

           -W no-remote-kill
    	      Defaults File Option: swbis_no_remote_kill
    	      Disables the use of a second remote connection to tear down the
    	      first in the event of SIGINT or SIGTERM or SIGPIPE.  Only has
    	      effect if the number of ssh hops is greater than 1.  A single
    	      host remote connection (ssh hop = 1) never uses a second remote
    	      connection.

           -W no-getconf
    	      Defaults File Option: swbis_no_getconf
    	      Makes the remote command be '/bin/sh -s' instead of the default
    	      'PATH=`getconf PATH` sh -s'.

           -W shell-command=NAME
    	      Defaults File Option: swbis_shell_command
    	      This is the interactive shell on the target host.	 NAME may be
    	      one of "detect" "bash", "sh", "ksh"  or "posix" and specifies
    	      the remote command run by the remote shell.  "posix" is
    	      'PATH=`getconf PATH` sh -s', "bash" is "/bin/bash -s", "sh" is
    	      "/bin/sh -s", and "ksh" is "ksh -s".  The default is "detect".

           -W use-getconf
    	      Opposite of --no-getconf.

           -W allow-rpm
    	      Defaults File Option: swbis_allow_rpm
    	      Enable automatic detection, translation to POSIX format, and
    	      installation of RPMs.

           -W pump-delay1=NANOSECONDS
    	      Adds a NANOSECONDS delay (999999999 nanoseconds ~ 1 second)
    	      every ADJSIZE bytes in the file data byte pump.  A delay of
    	      10111000 nanoseconds (~1/100th second) is added for 2-hop or
    	      greater target (i.e more than 1 remote host in the target spec).
    	      This is a work around for a bug in OpenSSH [or Linux kernel]
    	      that is seen for multi-hop installs where the intermediate host
    	      is a Linux kernel.  If 2-hop install fails, try it again, you
    	      may get lucky, or, increase this delay, or, use ssh protocol
    	      version 1 by using ''--ssh-options=1'', or try a 2-hop install
    	      where the middle host is BSD.  To disable delay for multi-hop
    	      targets specify zero.  For more information about this bug see
    	      the README file from the source distribution.

           -W burst-adjust=ADJSIZE
    	      ADJSIZE is the pumped data size, in bytes, between the
    	      NANOSECONDS delays.  This is a work around for a bug in OpenSSH
    	      or the Linux kernel that is seen for multi-hop installs where
    	      the intermediate host is a Linux kernel.	The default is 72000
    	      for 2-hops or greater, and zero for single hop and localhost
    	      installs.

           -W ssh-options=OPTIONS
    	      ssh client program options.  For example -W ssh-options=1 sets
    	      the '-1' ssh client option which specifies protocol version 1.

           -W source-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           -W target-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           software_selections

    	      Refers to the software objects (products, filesets) on which to
    	      be operated. This is not implemented, however, specification of
    	      a location and qualifier are supported.  location allow
    	      specification of a alternate relative root path within the
    	      target path, and qualifier allows specification of a user-
    	      selectable modifier.  For example:

    	      swinstall q=exp @ 192.168.1.1  # Tag the package as experimental
    	      swinstall l=/unionfs/somepackage-1.0 @ 192.168.1.1  # Allows multiple
    					    # packages with same tag to exist in the
    					    # same target path, where the location
    					    # disambiguates.

           target

    	      Refers to the software_collection where the software selections
    	      are to be applied.  Allows specification of host and pathname
    	      where the software collection is to be located.  A target that
    	      contains only one part is assumed to be a hostname.  To force
    	      interpretation as a path, use an absolute path or prefix with
    	      ':'.  The default target path for 'swinstall' is always '/'.

           Source and Target Specification and Logic

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

    		 Swbis Extension:
    		      [user@]host[:path]
    		      [user@]host_port[:path]
    		      :path

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

    		      [user@]host[@@[user@]host[@@...]][:file]
    		      [user@]host_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_port:host_port:
    		      host:host:file
    		      user@host:user@host:
    		      user@host:user@host:host:
    		      user@host:user@host:file

    	    A more formal description:

    	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
    		   | HOST_CHARACTER_STRING ':'
    		   | HOST_CHARACTER_STRING
    		   | PATHNAME_CHARACTER_STRING
    		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
    		   ;

    	      PATHNAME_CHARACTER_STRING must be an absolute path unless
    			      a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
    		    | PATHNAME_CHARACTER_STRING
    		    ;
    	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

    	   DELIM    : ':'   # The multi-hop delimiter.
    		    ;

    INSTALLATION
           Installation consists of an analysis phase and an execution phase.

       Analysis Phase
           The installed software catalog is queried and checks are made to detect
           reinstallation, downdating (installing an older version).  Dependency
           tests are made at this point.  If these checks pass or are overridden
           by options, then the installed software catalog entry is created
           (moving the old entry).	The checkinstall script is exectuted.  This
           script should be non-interactive, idempotent, and read-only from the
           system's perspective.  This script may exit with status of 0,1,2, or 3.
           If the exit status is 3 (or 1) installation is rejected and the
           installed catalog is restored.

       Execution Phase
           The preinstall script is executed, the fileset files are loaded by the
           system tar utility and postinstall is executed.

       o   Execution Script Environment
           swinstall sets certain enviroment variables during execution.  The
           values set are hard-coded in the control.sh script generated by
           swinstall.

           For example, execution of the postinstall script in package
           foobar-1.0.tar.gz with the following layout

           foobar-1.0/
           foobar-1.0/catalog/
           foobar-1.0/catalog/INDEX
           foobar-1.0/catalog/dfiles/
           foobar-1.0/catalog/foobar/
           foobar-1.0/catalog/foobar/pfiles/
           foobar-1.0/catalog/foobar/pfiles/INFO
           foobar-1.0/catalog/foobar/pfiles/postinstall
           foobar-1.0/catalog/foobar/bin/
           foobar-1.0/catalog/foobar/bin/INFO

           installed with the following command:

           swinstall -x installed_software_catalog=/var/software/catalog \
    		 @ /mnt/test

           will result in the following environment (among others, inspect
           control.sh):

    	    SW_PATH=/bin:/usr/bin
    	    SW_ROOT_DIRECTORY=/mnt/test
    	    SW_CATALOG=var/software/catalog/foobar/foobar/1.0/0
    	    SW_CONTROL_TAG= postinstall
    	    SW_CONTROL_DIRECTORY=/mnt/test/var/software/catalog/\
    		      foobar/foobar/1.0/0/export/foobar-1.0/catalog/foobar/pfiles
    	    SW_SESSION_OPTIONS=/mnt/test/var/software/catalog/\
    		      foobar/foobar/1.0/0/session_options

           SW_PATH is constructed using getconf(1) to locate the posix level
           utilites, otherwise it is the same as PATH.

           If the interpreter attribute from the INFO file, is 'sh' or unset, the
           executed shell interpreter is /bin/bash,	 sh as found in the PATH
           specified by getconf(1),	 or /bin/sh in this order.

           As of swbis-1.12 (Version 1.12), control script execution begins with a
           current working directory ($PWD) of SW_ROOT.  Prior to version 1.12,
           initial current working directory was equivalent to
           $SW_ROOT/$SW_CATALOG.

    INSTALLED SOFTWARE CATALOG
           The form or format of an installed software catalog is not specified by
           the ISO/IEC spec although it does specify an interface to it (e.g.
           swlist utility) and operations on it.

           This implementation creates a de-facto installed software catalog
           rooted at the file system path specified by the value of the
           installed_software_catalog extended option.  The catalog is a file
           system hierarchy containing regular files and directories.

           The catalog is typically located relative to the target path.  As of
           swbis version 1.5, the catalog location may be specified using the file
           URL syntax to indicate an absolute path.	 Any other form, such as an
           unadorned absolute UNIX path will be treated as a path relative to the
           target path.

           For Example:
           Below are example values of the installed_software_catalog extended
           option found in the swdefaults file usually located in
           $HOME/.swbis/swdefaults

    	  var/lib/swbis/catalog	  # Default, relative to target path

    	  /var/lib/swbis/catalog  # Same, leading slash not respected

    	  file://localhost/var/lib/swbis/catalog  # Really absolute

    	  file:///var/lib/swbis/catalog		  # Note triple leading slash

       CATALOG FILE LAYOUT
    	<path>/
    	<path>/<ISC>/
    	<path>/<ISC>/<bundle>/
    	<path>/<ISC>/<bundle>/<product>/
    	<path>/<ISC>/<bundle>/<product>/<pr>/
    	<path>/<ISC>/<bundle>/<product>/<pr>/<seqence_number>/
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/export/catalog.tar.sig<N>
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/INSTALLED
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/control.sh
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/session_options
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/vendor_tag
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/location
    	<path>/<ISC>/<bundle>/<product>/<pr>/<sequence_number>/qualifier

           <path> is the target path.  <ISC> is the value of the
           installed_software_cataglog extended option.  <bundle> and <product>
           are bundle and product tags.  If there is no bundle in the distribution
           the product tag is used.	 <pr> is the product revision.	Other items
           are explained below.

       CATALOG LOCATION
           /<path>/
           /<path>/<installed_software_catalog>/
           /<path>/<installed_software_catalog>/...

           * Root or Alternate Root
           /<path>/

           <path>/ is the target path specified in the target syntax. By default
           "/".

           * Catalog Relative Root Directory
           /<path>/
           /<path>/<installed_software_catalog>/

           <installed_software_catalog>/ is the value of the extended option by
           the same name.  By default "var/lib/swbis/catalog".

       PACKAGE CATALOG RELATIVE ROOT
           /<{bundle|prod}.tag>/<prod.tag>/<prod.revision>/...

    	In other words, if 'product' and 'bundle' refers to tags, and
           product_revision is the value of the product.revision attribute then
           the path segment is:

    	/bundle/product/product_revision

       CATALOG SEQUENCE NUMBER
    	/<sequence_number>/
    	/<sequence_number>/...

           sequence_number is a decimal integer starting with '0'.	It is chosen
           by swinstall to be unique at the time of installation.

       CATALOG CONTENTS
           <sequence_number>/
    	<sequence_number>/export/
    	<sequence_number>/export/catalog.tar
    	<sequence_number>/export/catalog.tar.sig
    	<sequence_number>/INSTALLED
    	<sequence_number>/control.sh
    	<sequence_number>/session_options
    	<sequence_number>/vendor_tag
    	<sequence_number>/location
    	<sequence_number>/qualifier

           The export directory
    	export/
    	export/...
    	export/catalog.tar
    	export/catalog.tar.sig
    	export/catalog.tar.sig2
    		      ...
    	export/catalog.tar.sigN

           The export/ is a file system directory and its name is constant for all
           packages and is unique to the swbis implementation.  The
           export/catalog.tar file is the signed file from the POSIX distribution.
           The export/catalog.tar.sig file is the signature file from the
           distribution.  If there is more than one signature, then it is the last
           one.  export/catalog.tar.sig2 is the next to last signature, and
           export/catalog.tar.sigN is the first one, where N is the total number
           of signatures.

           INSTALLED -- The state metadata file
    	<sequence_number>/INSTALLED

           The INSTALLED file is similar to an INDEX file in its grammar and
           syntax.	Unlike an INDEX file, it may contain control_file definitions.
           The INSTALLED file stores the control script return codes and fileset
           installation state.  It is updated several times during the operation
           of 'swinstall'.	It can be parsed using	libexec/swbisparse and the
           '--installed' option.

           control.sh -- The master control script
    	<sequence_number>/control.sh
    	 SYNOPSIS: control.sh tag_spec script_tag

           The control.sh file is a POSIX shell script that is automatically
           generated by swinstall.	It provides a common interface for control
           script execution.  Its primary purpose is to set up the script's
           execution environment and map script tags to the control script
           pathnames.  It assumes that 'export/catalog.tar' is unpacked in
           export/.

           session_options -- The extended options
    	<sequence_number>/session_options

           This file contains the extended options in a form that may be executed
           by the shell '.' (dot) command.	It is automatically generated by
           swinstall.  The value of the SW_SESSION_OPTIONS environment variable is
           the absolute pathname of the this file.

       EXAMPLE CATALOG ENTRY
           Below is an example entry of the catalog created by swbis version
           0.405.  In this example, the target path is '/mnt/test', the
           installed_software_catalog is '/var/lib/swbis/catalog/', the bundle tag
           is 'foobare', the product tag is 'foobare-doc', and the product
           revision attribute is '0.902'.

           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/export/catalog.tar.sig
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/INSTALLED
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/control.sh
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/vendor_tag
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/location
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/qualifier
           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/0/session_options

    	A deleted old catalog entry begin with '_', for example

           /mnt/test/var/lib/swbis/catalog/foobare/foobare-doc/0.902/_0/...

           Although swinstall does not depend on the file name as this
           accommodates installing from standard input, a typical name for this
           package would be:

    	      foobare-doc-0.902-sl04.tar.gz

    	where 'sl04' is the vendor tag.

    IMPLEMENTATION EXTENSIONS
       Software Specification Targets
           A dash '-' is supported and means stdout or stdin.  Operations with
           stdout and stdin on a remote host is not supported.

           A decimal '.' is supported and means the current directory.  This is
           supported for remote and non-remote targets.  If the source is standard
           input, the distribution will be unpacked (e.g. pax -r) in the directory
           '.'.  If the source is a regular file then a regular file in '.' will
           be created with the same name.

       RPM Translation
           RPM (RedHat Package Manager) format packages are installed by first
           translating to an equivalent ISO/IEEE file layout in POSIX tar format
           and then installing as a POSIX package.	This translation and detection
           is transparent to the user if the ''--allow-rpm'' option is set in the
           command line args or the swbis_allow_rpm is set to "true" by the
           defaults files, otherwise an error occurs.

           Since translation is done on the local (management) host, RPM is not
           required on the remote (target) host.

           The translation is (internally) equivalent to :

    	  cat your-0.0-1.bin.rpm |
    	  /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
    	  swpackage -W source=- -s @PSF | swinstall -s - @/

       Testing with RPM
    	To test the swbis components, a completely independent means to
           install and verify a package is needed.	RPM provides this means and
           can be used in the following way:

    	  rpm -i --nodeps --force your-0.0-1.i386.rpm  # Install
    	  rpm --verify --nodeps your-0.0-1	       # Show that all is well
    	  rpm -e --nodeps your-0.0-1		       # Remove it.
    	  rpm -i --nodeps --justdb your-0.0-1.i386.rpm # Install just the database.
    	  rpm --verify --nodeps your-0.0-1	       # Shows the files are missing.
    	  swinstall --allow-rpm -s - < your-0.0-1.i386.rpm
    	  rpm --verify --nodeps your-0.0-1	       # Show that all is well again

    EXTENDED OPTIONS
           Extended options can be specified on the command line using the -x
           option or from the defaults file, swdefaults.  Shown below is an actual
           portion of a defaults file which show default values.

       POSIX
           These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults

    	 allow_downdate		     = false	  # Not Implemented
    	 allow_incompatible	     = false	  # Not Implemented
    	 ask			     = false	  # Not Implemented
    	 autoreboot		     = false	  # Not Implemented
    	 autorecover		     = false	  # Not Implemented
    	 autoselect_dependencies     = false	  # Not Implemented
    	 defer_configure	     = false	  # Not Implemented
    	 distribution_source_directory	 = -	    # Stdin
    	 enforce_dependencies	     = false	  # Not Implemented
    	 enforce_locatable	     = false	  # Not Implemented
    	 enforce_scripts	     = false	  # Not Implemented
    	 enforce_dsa		     = false	  # Not Implemented
    	 installed_software_catalog  = var/lib/swbis/catalog
    	 logfile	     = /var/lib/sw/swinstall.log #Not Implemented
    	 loglevel		     = 0	  # Not Implemented
    	 reinstall		     = false	  # Not Implemented
    	 select_local	   = false	# Not Implemented
    	 verbose	   = 1

       Swbis Implementation
           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ${HOME}/.swbis/swbisdefaults file.

    	 swinstall.swbis_no_getconf = true # true or false
    	 swinstall.swbis_shell_command = detect # {detect|sh|bash|ksh|posix}
    	 swinstall.swbis_no_remote_kill = false # true or false
    	 swinstall.swbis_no_audit = false # true or false
    	 swinstall.swbis_quiet_progress_bar = false # true or false
    	 swinstall.swbis_local_pax_write_command=pax #{pax|tar|star|gtar}
    	 swinstall.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar}
    	 swinstall.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
    	 swinstall.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
    	 swinstall.swbis_enforce_sig=false # true or false
    	 swinstall.swbis_enforce_file_md5=false # true or false
    	 swinstall.swbis_allow_rpm=false # true or false
    	 swinstall.swbis_remote_shell_client=ssh
    	 swinstall.swbis_install_volatile=true
    	 swinstall.swbis_volatile_newname=     #empty string, e.g. ".rpmnew"

    RETURN VALUE
           0 if all targets succeeded, 1 if all targets failed, 2 if some targets
           failed and some succeeded.

    NOTES
    	Multiple ssh-hops is an implementation extension.

    REQUISITE UTILITIES
           The swbis distributed utilities require bash, public domain ksh, or
           ksh93 (version 2009-05-05), or Sun's /usr/xpg4/bin/sh to be present on
           the target host.	 If the swbis_shell_command extended option is set to
           'detect' you don't have to know which one is present, otherwise you may
           specify one explicitly.

           A POSIX 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.

    FILES
    	/var/lib/swbis/catalog # Location of installed catalog
    	/usr/lib/swbis/swdefaults
    	/usr/lib/swbis/swbisdefaults
    	$HOME/.swbis/swdefaults
    	$HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701

    SEE ALSO
           info swbis

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

    IDENTIFICATION
    	swinstall(8): The installation utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2014-02-12
    	Copying: GNU Free Documentation License

    BUGS
           swinstall is subject to breakage if a user's account on an intermediate
           (or terminal) host in a target spec is not configured to use a Bourne
           compatible shell. (This breakage may be eliminated by use of the --no-
           getconf option as explained above.)

           A multiple ssh hop source spec  (more than 1 remote host involved in
           the source transfer) upon a SIGINT may result in sshd and ssh processes
           being left on on the intermediate host(s), this despite, swinstall's
           action of sending a SIGTERM to the remote script's parent process.

           swinstall does not currently implement Software Selections, not fileset
           dependencies, and much more.  Only packages with one product and one
           fileset are supported.

    								  swinstall(8)

Next: (swbis_swcopy), Previous: (swbis_swremove), Up: Command Reference

### swremove.8 in one text file

    swremove(8)		    System Manager's Manual		   swremove(8)

    NAME
           swremove — Remove installed software

    SYNOPSIS
           swremove	 [-d|-r] [-v] [-t targetfile] \
           [-x option=value]  [-X options_file]  [-W option] \
           [software_selections]  [@targets]

           swremove --cleansh [options] [@targets]

    DESCRIPTION
           swremove removes installed software.  swremove is a distributed
           utility.	 Neither swremove nor any component of swbis is required on
           the target host, however, the target host must look like a Unix system
           at the shell and command-line utility level.  Remote network
           connections are made by ssh.  Ssh is the default but rsh can be
           selected by a command line option.

           swremove operates on installed software identified by a software
           selection and target.

    OPTIONS
           -d

    	      Specify the target is a distribution.

    		     Note:  This is currently not supported by this
    		     implementation.

           -f FILE

    	      Read the list of software selections from FILE.

           -p

    	      Preview mode, establish contact with target host, however,
    	      modify nothing.

           -r

    	      Indicates that the operation is on installed software at a
    	      location indicated by the the target.

    		     Note:  This is the default mode among -d and -r

           -t targetfile

    	      Specify a file containing a list of targets (one per line).

           -v

    	      Increment the verbose level.

           -x option=value

    	      Specify the extended option overriding the defaults file value.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           --help

    	      Show help (Implementation extension)

           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           --allow-ambig

    	      Allows swremove to act on all matching entries.  Without this
    	      option a software selection that matches more than one installed
    	      software entry is an error.

           --sig-level=N

    	      Specify number of required GPG signatures, N equal to 0 means
    	      don't require the catalog to be signed.

           --cleansh

    	      Kill stray or zombied processes that match the pattern ``sh
    	      -s.*_swbis''.  These may be caused by a distributed utility
    	      segfaulting or a signal handling defect in the swbis utility.

           -W remote-shell=SHELL

    	      Defaults File Option: swbis_remote_shell_client
    	      Supported shells are "ssh" and "rsh", ssh is the default.

           -W show-options-files
    	      Show the complete list of options files and if they are found.

           -W show-options
    	      Show the options after reading the files and parsing the command
    	      line options.

           -W pax-command={tar|pax|star|gtar}
    	      Set the portable archive command for all operations.  The
    	      default is "pax".

           -W pax-read-command={tar|pax|star|gtar}
    	      Set the read command for local and remote hosts.

           -W remote-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_remote_pax_read_command
    	      Set the read command for remote hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W local-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_local_pax_read_command
    	      Set the read command for local hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W pax-write-command={tar|pax|star|gtar|swbistar}
    	      Set the write command for local and remote hosts.	 This is the
    	      command that runs on the target (e.g. pax -w, tar cf -).

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the write command for remote hosts.

           -W local-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_local_pax_write_command
    	      Set the portable archive write command for local host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the portable archive write command for remote host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W no-defaults
    	      Do not read any defaults files.

           -W no-getconf
    	      Defaults File Option: swbis_no_getconf
    	      Makes the remote command be '/bin/sh -s' instead of the default
    	      'PATH=`getconf PATH` sh -s'.

           -W shell-command=NAME
    	      Defaults File Option: swbis_shell_command
    	      NAME may be one of "bash", "sh" or "posix" and specifies the
    	      remote command run by the remote shell.  "posix" is
    	      'PATH=`getconf PATH` sh -s', "bash" is "/bin/bash -s", "sh" is
    	      "/bin/sh -s", and "ksh" is "ksh -s".  The default is "posix".

           -W use-getconf
    	      Opposite of --no-getconf.

           -W source-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           -W target-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           software_selections

    	      Refer to the software objects (products, filesets) using
    	      software spec syntax. (See sw(5) for syntax).

           target

    	      Refers to the software_collection where the software selections
    	      are to be applied.  Allows specification of host and pathname
    	      where the software collection is located.	 A target that
    	      contains only one part is assumed to be a hostname.  To force
    	      interpretation as a path, use a absolute path or prefix with
    	      ':'.

           Source and Target Specification and Logic

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

    		 Swbis Extension:
    		      [user@]host[:path]
    		      [user@]host_port[:path]
    		      :path

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

    		      [user@]host[@@[user@]host[@@...]][:file]
    		      [user@]host_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_port:host_port:
    		      host:host:file
    		      user@host:user@host:
    		      user@host:user@host:host:
    		      user@host:user@host:file

    	    A more formal description:

    	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
    		   | HOST_CHARACTER_STRING ':'
    		   | HOST_CHARACTER_STRING
    		   | PATHNAME_CHARACTER_STRING
    		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
    		   ;

    	      PATHNAME_CHARACTER_STRING must be an absolute path unless
    			      a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
    		    | PATHNAME_CHARACTER_STRING
    		    ;
    	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

    	   DELIM    : ':'   # The multi-hop delimiter.
    		    ;

    USAGE EXAMPLES
       Remove everything at 192.168.1.2 from the root directory
    	 swremove --allow-ambig \* @ root@192.168.1.2:/

       Preview removal of every package listing every file, but modify nothing
    	 swremove -vv -p --allow-ambig \* @ root@192.168.1.2:/

       Remove everything at 192.168.1.2 from the home directory of user
           'jailbird'.
    	 swremove --allow-ambig \* @ jailbird@192.168.1.2:.

       Remove package foo from the root '/', or elevate your credentials via ssh
    	 swremove foo @ /
    	 swremove foo @ root@localhost:/

       Show the options
    	 swremove --show-options

    EXTENDED OPTIONS
           Extended options can be specified on the command line using the -x
           option or from the defaults file, swdefaults.  Shown below is an actual
           portion of a defaults file which show default values.

       POSIX
           These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults on the local (management host, host where swremove is
           invoked).  These files on the target host are not used.

    	 autoselect_dependencies       = false
    	 distribution_target_directory = /
    	 enforce_dependencies	       = false
    	 enforce_scripts	       = true
    	 installed_software_catalog    = var/lib/swbis/catalog/
    	 logfile		       = /var/log/sw.log
    	 loglevel		       = 1
    	 select_local		       = true
    	 verbose		       = 1

       Swbis Implementation
           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ~/.swbis/swbisdefaults file.

    	  swremove.swbis_no_getconf = true # true or false
    	 swremove.swbis_shell_command = posix # {sh|bash|posix|ksh}
    	 swremove.swbis_no_remote_kill = false # true or false
    	 swremove.swbis_local_pax_write_command=tar #{pax|tar|star|gtar}
    	 swremove.swbis_remote_pax_write_command=tar #{pax|tar|star|gtar}
    	 swremove.swbis_local_pax_read_command=tar #{pax|tar|gtar|star}
    	 swremove.swbis_remote_pax_read_command=tar #{pax|tar|gtar|star}
    	 swremove.swbis_local_pax_remove_command=tar
    	 swremove.swbis_remote_pax_remove_command=tar
    	 swremove.swbis_remote_shell_client=ssh
    	 swremove.swbis_forward_agent=True
    	 swremove.swbis_sig_level=0
    	 swremove.swbis_enforce_all_signatures=false

    RETURN VALUE
           0 if all targets succeeded, 1 if all targets failed or internal error,
           2 if some targets failed and some succeeded.

    NOTES
    	Multiple ssh-hops is an implementation extension.

    REQUISITE UTILITIES
           The swbis distributed utilities require bash, public domain ksh, or
           Sun's /usr/xpg4/bin/sh to be present on the target host.	 If the
           swbis_shell_command extended option is set to 'detect' you don't have
           to know which one is present, otherwise you may specify one explicitly.

           A POSIX 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.

           GNU Privacy Guard, gpg is required for verification of package
           signatures.

           swremove uses rm and rmdir for file and directory removal.

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

    FILES
           /var/lib/swbis/catalog # Location of installed catalog
           /usr/lib/swbis/swdefaults
           /usr/lib/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701

    SEE ALSO
           info swbis

           swbis(7), sw(5), swlist(8)

    IDENTIFICATION
    	swremove(8): The package removal utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2008-04-18
    	Copying: GNU Free Documentation License

    BUGS
           swremove is subject to breakage if a user's account on an intermediate
           (or terminal) host in a target spec is not configured to use a Bourne
           compatible shell. (This breakage may be eliminated by use of the --no-
           getconf option as explained above.) swremove does not support rollback
           if an error occurs during processing.

    								   swremove(8)

Next: (swbis_swlist), Previous: (swbis_swcopy), Up: Command Reference

### swcopy.8 in one text file

    swcopy(8)		    System Manager's Manual		     swcopy(8)

    NAME
           swcopy — Copy POSIX and RPM packages.

    SYNOPSIS
           swcopy [-p] [-s source_file] [-f file] [-t targetfile] \
           [-x option=value] [-X options_file] [-W option] \
           [software_selections] [@target [target1...]]

    DESCRIPTION
           swcopy copies a POSIX distribution from a source archive or directory
           to a target archive directory.  Neither swcopy nor any component of
           swbis is required on the target host, however, the target host must
           look like a Unix system at the shell and command-line utility level.
           Remote network connections are made by ssh.  Ssh is the default but rsh
           can be selected by a command line option.

           Before and during data transfer to the target, the distribution is
           audited.	 Package auditing includes parsing the INDEX and INFO meta-
           data files.  The package pathnames are checked for consistency with a
           valid layout.  swcopy can be made to operate on arbitrary data or
           archives not in POSIX format by using the --no-audit option.  By
           default and with no external influences (i.e. swdefaults file) swcopy
           will read a archive on stdin and write an audited archive on stdout.
           The uncompressed audited output file will be identical to the
           uncompressed input file unless an error occurs.	Compressed archives
           that are audited will be re-compressed in the same format, however, the
           resulting file may not be identical to the input file (i.e. date,
           filename, and other stored data in the compressed format will be
           different).

           swcopy operates on serial archives (e.g. compressed tar archives) or on
           file system directories.	 It will attempt to preserve the form (archive
           or directory) and compression state of the source object.  An exception
           is "." as a target (See Implementation Extensions below).

    OPTIONS
           -f FILE

    	      Reads software_selections from FILE. (Not implemented).

           -p

    	      Preview the operation. Information is written to stdout.	The
    	      target is not written and no remote connections are established.

           -s SOURCE

    	      Specify the source file SOURCE, "-" is standard input.  The
    	      syntax is the same as for a target.  SOURCE may be a directory
    	      or archive file.

           -t targetfile

    	      Specify a file containing a list of targets (one per line).

           -x option=value

    	      Specify the extended option overriding the defaults file value.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           -v

    	      Given one time it is identical to -x verbose=2.  This option can
    	      be given multiple times with increasing effect.  (Implementation
    	      extension option).
    	      -v  is level 2, -vv is level 3,... etc.
    		  level 0: silent on stdout and stderr.
    		  level 1: fatal and warning messages to stderr.
    	      -v  level 2: level 1 plus a progress bar.
    	      -vv level 3: level 2 plus script stderr.
    	      -vvv level 4: level 3 plus events.
    	      -vvvv level 5: level 4 plus events.
    	      -vvvvv level 6: level 5 plus set shell -vx option.
    	      -vvvvvv level 7 and higher: level 6 plus debugging messages.
    	       The progress meter is suppressed if swcopy is using stdout for
    	      data.

           -b SIZE

    	      Set block size, same as --block-size=N (Implementation extension
    	      option).

           --version, -V

    	      Show version (Implementation extension)

           --help

    	      Show help (Implementation extension)

           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           -W no-audit

    	      Defaults File Option: swbis_no_audit
    	      Do not audit the transferred file.  This allows copying of
    	      arbitrary data.

           -W audit

    	      Do audit the transferred file.  Useful for overriding
    	      swbisdefaults file.

           -W block-size=SIZE

    	      SIZE is number of octets.

           -W login

    	      Establishes a interactive shell on the (remote) target host.
    	      Intended for debugging/verifying ssh operation.

           -W gzip

    	      Compress output using gzip.

           -W bzip

    	      Compress output using bzip2.

           -W extract

    	      Install the source using the archive reading utility at the
    	      target.

           -W create

    	      Force copy as a tar archive

           -W no-extract

    	      For installation to a file, not as a tar archive to be
    	      extracted.

           -W pty

    	      Do use pseudo-tty.  The system Ptys are only used for the
    	      --login feature.	A warning is emitted to stderr which says that
    	      the usage may be insecure.

           -W no-pty

    	      Do not use pseudo-tty.  The system Ptys are only used by default
    	      for the --login feature, otherwise they are not used and this
    	      option would have no effect.  If ptys are used a warning is
    	      emitted to stderr which says that the usage may be insecure.

           -W uncompress

    	      Write output archive that is uncompressed.

           -W remote-shell=SHELL

    	      Defaults File Option: swbis_remote_shell_client
    	      Supported shells are "ssh" and "rsh", ssh is the default.

           -W quiet-progress

    	      Defaults File Option: swbis_quiet_progress_bar
    	      Disable progress bar, which is active for verbose levels 2 and
    	      higher (i.e. -v).

           -W show-progress

    	      Enables progress bar.(i.e. -v).

           -W show-options-files
    	      Show the complete list of options files and if they are found.

           -W show-options
    	      Show the options after reading the files and parsing the command
    	      line options.

           -W pax-command={tar|pax|star|gtar}
    	      Set the portable archive command for all operations.  The
    	      default is "pax".

           -W pax-read-command={tar|pax|star|gtar}
    	      Set the read command for local and remote hosts.

           -W remote-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_remote_pax_read_command
    	      Set the read command for remote hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W local-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_local_pax_read_command
    	      Set the read command for local hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W pax-write-command={tar|pax|star|gtar|swbistar}
    	      Set the write command for local and remote hosts.	 This is the
    	      command that runs on the target (e.g. pax -w, tar cf -).

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the write command for remote hosts.

           -W local-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_local_pax_write_command
    	      Set the portable archive write command for local host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the portable archive write command for remote host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W no-defaults
    	      Do not read any defaults files.

           -W no-remote-kill
    	      Defaults File Option: swbis_no_remote_kill
    	      Disables the use of a second remote connection to tear down the
    	      first in the event of SIGINT or SIGTERM or SIGPIPE.  Only has
    	      effect if the number of ssh hops is greater than 1.  A single
    	      host remote connection (ssh hop = 1) never uses a second remote
    	      connection.

           -W no-getconf
    	      Defaults File Option: swbis_no_getconf
    	      Makes the remote command be '/bin/sh -s' instead of the default
    	      'PATH=`getconf PATH` sh -s'.

           -W shell-command=NAME
    	      Defaults File Option: swbis_shell_command
    	      NAME may be one of "detect" "bash", "sh" or "posix" and
    	      specifies the command run by the remote shell.  The default is
    	      "detect".

           -W use-getconf
    	      Opposite of --no-getconf.

           -W allow-rpm
    	      Defaults File Option: swbis_allow_rpm
    	      Allows detection and translation of RPMs.	 (--audit must also be
    	      set.)

           -W unrpm
    	      Turns on options --allow-rpm and --audit.

           -W source-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           -W target-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           software_selections

    	      Refer to the software objects (products, filesets) on which to
    	      be operated. (Not implemented).  The implementation defined
    	      behavior for no selections is to operate on the entire
    	      distribution.

           target

    	      Refers to the software_collection where the software selections
    	      are to be applied.  Allows specification of host and pathname
    	      where the software collection is located.	 A target that
    	      contains only one part is assumed to be a hostname.  To force
    	      interpretation as a path, use a absolute path or prefix with
    	      ':'.

           Source and Target Specification and Logic

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

    		 Swbis Extension:
    		      [user@]host[:path]
    		      [user@]host_port[:path]
    		      :path

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

    		      [user@]host[@@[user@]host[@@...]][:file]
    		      [user@]host_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_port:host_port:
    		      host:host:file
    		      user@host:user@host:
    		      user@host:user@host:host:
    		      user@host:user@host:file

    	    A more formal description:

    	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
    		   | HOST_CHARACTER_STRING ':'
    		   | HOST_CHARACTER_STRING
    		   | PATHNAME_CHARACTER_STRING
    		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
    		   ;

    	      PATHNAME_CHARACTER_STRING must be an absolute path unless
    			      a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
    		    | PATHNAME_CHARACTER_STRING
    		    ;
    	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

    	   DELIM    : ':'   # The multi-hop delimiter.
    		    ;

    TARGET COPYING RULES
       Rules
           If a target directory on the host does not exist it will be created
           using mkdir -p using the file creation mask of the originating swcopy
           process.	 A trailing slash in the target spec signifies that the last
           path component should be a directory.  A source spec that is a
           directory will be created on the target as a directory with the same
           name in the target directory.  If the source spec is stdin then the
           existence of directories in the target spec and a trailing slash in the
           target spec path determines whether the created file will be a regular
           file or directory, that is, stdin will be copied as a file unless the
           last target path component is a directory or ends in a slash '/'.  If
           the source spec is a regular file, the source basename will be used as
           the basename in the target if the last target path component is a
           directory or ends in a slash '/', otherwise, the target basename is the
           last path component of the target spec.	The implementation option
           --extract biases these rules to install using the archive reading
           command (e.g.  pax -r).

       Examples
    	      Copy a regular file via tar archive creation and extraction.
    	      This will preserve the permissions of the file to the extent tar
    	      can preserve them.

    		swcopy --no-audit --create --extract -s :README @ HostA

    	       Copy a directory to another host

    		swcopy --no-audit  -s /usr @ HostA:/usr/local/tmp/HostA/

    	       Copy several directories to another host as a compressed
    	      archive file.

    		  swcopy --no-audit --no-extract \
    			   -s /usr -s /etc @ HostA:/tmp/usr-etc.tar.bz2

    	       Install a tarball in the current directory: Note: Must use
    	      stdin as source and "." as the target.

    		   swcopy --no-audit -s - @. < foo.tar.gz

    	       Copy thru a firewall:

    			  swcopy -s /var/tmp/foo.tar.gz \
    			       @root@host1:root@host2:/var/tmp

    	       Copy Stdin to a remote host:

    		  Unpack the archive on stdin in the directory
    		  /a/b/c if 'c' is a directory, otherwise copy
    		  the archive file to a file named 'c' in
    		  directory /a/b creating it if possible and
    		  overwriting if required.
    		      swcopy -s - @host1:/a/b/c

    	       Copy Stdin to a remote host:

    		     Unpack the serial archive on stdin in the
    		     directory /a/b/c if 'c' is a directory,
    		     otherwise make the directory 'c' but fail if
    		     directory 'c' cannot be created.
    			 swcopy -s - @host1:/a/b/c/
    				   # Note trailing slash.

    	       Copy a regular file:

    		 Copy file yy to directory /aa/bb/cc/ on the
    		 remote host, creating it if required and possible.
    		 If cc is a regular file then fail.
    		    swcopy -s /xx/yy @host1:/aa/bb/cc/

    	       Copy a regular file thru intermediate host 'fw':

    		     Copy file yy to home directory of user1 on host1
    		     thru a an intermediate host fw,
    			 swcopy -s /xx/yy @ fw:user1@host1:.

    	       Copy a directory from one host to another

    		     Copy directory yy into directory cc if cc exists,
    		     otherwise create cc and copy yy into it. If cc
    		     is and copy as yy.
    			 swcopy -s /xx/yy @host1:/aa/bb/cc

    IMPLEMENTATION EXTENSIONS
       Software Specification Targets
           A dash '-' is supported and means stdout or stdin.  Operations with
           stdout and stdin on a remote host is not supported.

           A decimal '.' is supported and means the current directory.  This is
           supported for remote and non-remote targets.  If the source is standard
           input, the distribution will be unpacked (e.g. pax -r) in the directory
           '.'.  If the source is a regular file then a regular file in '.' will
           be created with the same name.

           Thus,

    		  # swcopy -s `pwd`/myarchive.tgz @.  # Do NOT do this even
    						      # though in most cases
    						      # swcopy is a coward.

    	will destroy the source file myarchive.tgz, whereas

    		  # swcopy -s - @. <`pwd`/myarchive.tgz

    	will install it with the configured archive reading utility.

       RPM Translation
           RPM (RedHat Package Manager) format packages are copied by first
           translating to an equivalent ISO/IEEE file layout in POSIX tar format
           and then copying as a POSIX package.  The RPM detection and translation
           occurs if the ''--allow-rpm'' option is on (either by the command line
           args or defaults file) and the ''--audit'' option is on.	 If the
           ''--allow-rpm'' option is not set an error occurs.  If the ''--audit''
           is not set, the RPM is copied as arbitrary data and translation does
           not occur.

           Since translation is done on the local (management) host, RPM is not
           reqired on the remote (target) host.

           The translation is (internally) equivalent to :

    	  cat your-poor-poor-0.0.bin.rpm |
    	  /usr/lib/swbis/lxpsf --psf-form2 -H ustar |
    	  swpackage -Wsource=- -s@PSF

    EXTENDED OPTIONS
           Extended options can be specified on the command line using the -x
           option or from the defaults file, swdefaults.  Shown below is an actual
           portion of a defaults file which show default values.

       Posix
           These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults

    	  autoselect_dependencies     = false	   # Not Implemented
    	  compress_files	      = false	   # Not Implemented
    	  compression_type	      = none	   # Not Implemented
    	  distribution_source_directory	  = -
    	  distribution_target_directory	  = -
    	  enforce_dependencies	      = false	    # Not Implemented
    	  enforce_dsa		      = false	    # Not Implemented
    	  logfile		      = /var/lib/sw/swcopy.log #Not Implemented
    	  loglevel		      = 1	   # Not Implemented
    	  recopy		      = false	   # Not Implemented
    	  select_local	       = false	    # Not Implemented
    	  uncompress_files	       = false	   # Not Implemented
    	  verbose		       = 1

       Swbis Implementation
           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ~/.swbis/swbisdefaults file.

    	 swcopy.swbis_no_getconf = true # true or false
    	 swcopy.swbis_shell_command = detect # {detect|sh|bash|posix|ksh}
    	 swcopy.swbis_no_remote_kill = false # true or false
    	 swcopy.swbis_no_audit = false # true or false
    	 swcopy.swbis_quiet_progress_bar = false # true or false
    	 swcopy.swbis_local_pax_write_command=pax #{pax|tar|star|gtar}
    	 swcopy.swbis_remote_pax_write_command=pax #{pax|tar|star|gtar}
    	 swcopy.swbis_local_pax_read_command=pax #{pax|tar|gtar|star}
    	 swcopy.swbis_remote_pax_read_command=pax #{pax|tar|gtar|star}
    	 swcopy.swbis_allow_rpm = false	 # true or false
    	 swcopy.swbis_remote_shell_client=ssh

    RETURN VALUE
           0 if all targets succeeded, 1 if all targets failed, 2 if some targets
           failed and some succeeded.

    NOTES
    	Multiple ssh-hops is an implementation extension.

    REQUISITE UTILITIES
           The swbis distributed utilities require bash, public domain ksh, or
           Sun's /usr/xpg4/bin/sh to be present on the target host.	 If the
           swbis_shell_command extended option is set to 'detect' you don't have
           to know which one is present, otherwise you may specify one explicitly.

           A POSIX 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.

           Tar or pax is used for archive transfer.	 You may specify which one.

           swcopy.swbis_local_pax_write_command=tar #{pax|tar|gtar}
           swcopy.swbis_remote_pax_write_command=tar #{pax|tar|gtar}

    FILES
           /usr/lib/swbis/swdefaults
           /usr/lib/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701

    SEE ALSO
           info swbis

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

    IDENTIFICATION
    	swcopy(8): The archive copying utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2006-07
    	Copying: GNU Free Documentation License

    BUGS
           Swcopy is subject to breakage if a user's account on an intermediate
           (or terminal) host in a target spec is not configured to use a Bourne
           compatible shell. (This breakage may be eliminated by use of the --no-
           getconf option as explained above.)

           A multiple ssh hop source spec  (more than 1 remote host involved in
           the source transfer) upon a SIGINT may result in sshd and ssh processes
           being left on on the intermediate host(s), this despite, swcopy's
           action of sending a SIGTERM to the remote script's parent process.

           Swcopy does not currently implement Software Selections nor the events
           of the Selection and Analysis Phases nor dependency copying nor fileset
           state transitions.  The Execution (copying) phase is done on the entire
           distribution by the utility selected in .../swbisdefaults which is
           pax(1) by default.  Pax is not found on all GNU/Linux systems.  Also,
           the pax version shipped with some (older) GNU/Linux systems mangles the
           pathname of files whose pathname is exactly 100 octets long.  Despite
           this pax is the the builtin default.  GNU tar is widely used and
           trusted but creates non-standard archives for long pathnames.  Perhaps
           the best compromise is to use star (with -H ustar header option)	 for
           archive creation and (GNU) tar for archive reading.  If your
           environment is 100% GNU/Linux using GNU tar is safe (GNU tar 1.13.25 is
           recommended).  Swcopy does not support using the cpio utility since its
           archive writing interface is unlike pax and tar, although, future
           support is possible for archive reading.

    								     swcopy(8)

Next: (swbis_swverify), Previous: (swbis_swlist), Up: Command Reference

### swlist.8 in one text file

    swlist(8)		    System Manager's Manual		     swlist(8)

    NAME
           swlist — List information about the software

    SYNOPSIS
           swlist  [-d|-r] [-v] [-a attribute] [-l level]  [-t targetfile] \
           [-c file] [-x option=value]  [-X options_file]  [-W option] \
           [software_selections]  [@targets]

           swlist --products [software_selections]	[@targets]

           swlist --files  [@targets]

           swlist --dir [software_selections] [@targets]

           swlist --dependencies [--prerequisites sw_spec] \
           [--exrequisites sw_spec] [@targets]

    DESCRIPTION
           swlist lists information about a distribution or installed software.
           Neither swlist nor any component of swbis is required on the target
           host, however, the target host must look like a Unix system at the
           shell and command-line utility level.  Remote network connections are
           made by ssh.  Ssh is the default but rsh can be selected by a command
           line option.

           swlist operates on serial archives (e.g. compressed tar archives) or on
           a file system directory representing installed software.	 The default
           target directory is '/', this default is subject to user configuration.

    OPTIONS
           -a attribute

    	      Specify an attribute to list.   Only the architecture attribute
    	      is supported for installed_software at this time (MAR 2007).
    	      The returned value is determined by running GNU config.guess on
    	      the target host.

           -c FILE

    	      Write the catalog to FILE. Software selections are applied.  The
    	      only supported FILE is '-' causing a dump of the catalog to
    	      stdout in tar format.

           -d

    	      Specify the target is a distribution.

           -f FILE

    	      Read the list of software selections from FILE.

           -l LEVEL

    	      Specify a level to list. LEVEL is an enumerated list of objects:
    	      bundle, product, fileset, control_file, file (Not yet
    	      implemented)

           -r

    	      Indicates that the operation is on installed software at a
    	      location indicated by the the target.

           -t targetfile

    	      Specify a file containing a list of targets (one per line).

           -v

    	      List attribute value pairs in INDEX file format according to
    	      attibutes specified by the -a option, list all attributes if -a
    	      not used; or, increment the verbose level.

    		     Note:  This option is overloaded. It means two different
    		     things depending on the context.  If a mode is explicitly
    		     given, then it means increment verbosity, otherwise it
    		     means list in INDEX file format.

           -x option=value

    	      Specify the extended option overriding the defaults file value.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           --help

    	      Show help (Implementation extension)

           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           --products

    	      List the product's tag, revision, vendor_tag and location.

           --directory

    	      List the catalog directory entries.

           --files

    	      List files as defined in the installed catalog

           --sys

    	      List files as exists in the file system

           --dependencies

    	      Run in check dependency mode.  Assert dependencies against
    	      installed software catalog. Dependencies are software specs
    	      given by the --prerequisites and --extrequisites options

           --prerequisites=SW_SPEC

    	      Specify depencency to check, may be used multiple times.
    	      Prerequisites packages are required to be installed.

           --exrequisites=SW_SPEC

    	      Specify depencency to check, may be used multiple times.
    	      Exrequisites packages are required not to be installed.

           -W remote-shell=SHELL

    	      Defaults File Option: swbis_remote_shell_client
    	      Supported shells are "ssh" and "rsh", ssh is the default.

           -W show-options-files
    	      Show the complete list of options files and if they are found.

           -W show-options
    	      Show the options after reading the files and parsing the command
    	      line options.

           -W pax-command={tar|pax|star|gtar}
    	      Set the portable archive command for all operations.  The
    	      default is "pax".

           -W pax-read-command={tar|pax|star|gtar}
    	      Set the read command for local and remote hosts.

           -W remote-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_remote_pax_read_command
    	      Set the read command for remote hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W local-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_local_pax_read_command
    	      Set the read command for local hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W pax-write-command={tar|pax|star|gtar|swbistar}
    	      Set the write command for local and remote hosts.	 This is the
    	      command that runs on the target (e.g. pax -w, tar cf -).

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the write command for remote hosts.

           -W local-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_local_pax_write_command
    	      Set the portable archive write command for local host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the portable archive write command for remote host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W no-defaults
    	      Do not read any defaults files.

           -W no-getconf
    	      Defaults File Option: swbis_no_getconf
    	      Makes the remote command be '/bin/sh -s' instead of the default
    	      'PATH=`getconf PATH` sh -s'.

           -W shell-command=NAME
    	      Defaults File Option: swbis_shell_command
    	      NAME may be one of "detect" "bash", "sh" or "posix" and
    	      specifies the remote command run by the remote shell.  "posix"
    	      is 'PATH=`getconf PATH` sh -s', "bash" is "/bin/bash -s", "sh"
    	      is "/bin/sh -s", and "ksh" is "ksh -s".  The default is "posix".

           -W use-getconf
    	      Opposite of --no-getconf.

           -W source-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           -W target-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           software_selections

    	      Refer to the software objects (products, filesets) using
    	      software spec syntax. (See sw(5) for syntax).

           target

    	      Refers to the software_collection where the software selections
    	      are to be applied.  Allows specification of host and pathname
    	      where the software collection is located.	 A target that
    	      contains only one part is assumed to be a hostname.  To force
    	      interpretation as a path, use a absolute path or prefix with
    	      ':'.

           Source and Target Specification and Logic

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

    		 Swbis Extension:
    		      [user@]host[:path]
    		      [user@]host_port[:path]
    		      :path

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

    		      [user@]host[@@[user@]host[@@...]][:file]
    		      [user@]host_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_port:host_port:
    		      host:host:file
    		      user@host:user@host:
    		      user@host:user@host:host:
    		      user@host:user@host:file

    	    A more formal description:

    	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
    		   | HOST_CHARACTER_STRING ':'
    		   | HOST_CHARACTER_STRING
    		   | PATHNAME_CHARACTER_STRING
    		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
    		   ;

    	      PATHNAME_CHARACTER_STRING must be an absolute path unless
    			      a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
    		    | PATHNAME_CHARACTER_STRING
    		    ;
    	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

    	   DELIM    : ':'   # The multi-hop delimiter.
    		    ;

    IMPLEMENTATION EXTENSIONS
           The --dependencies, --products, and --files are implementation
           extension modes.

    USAGE EXAMPLES
       Show the path of the installed software catalog.
    	 swlist --show-options | grep installed_

       List Product from a certain distributor
    	List products from a certain distributor, foo (Note:  this requires
           that the foo vendor uses foo_something_ as the product vendor_tag in
           their distributions.

    	 swlist v="foo*"

       List all products
    	 swlist @/   # If distribution_target_directory=/ then "swlist" alone
    		     # will suffice.

       List products installed at alternate root  /mnt/test
    	 swlist @/mnt/test

       List the files of package foo as they exist in the file system
           swlist -vv --files --sys foo @ root@localhost

       List products according to a name pattern and revision, and distributor
    	 swlist emacs"*","r>20",v=rh"*" @/

       Test Dependencies
           Check if a given dependency passes against a given installed catalog on
           a host

    	 swlist -x verbose=3 --depend --pre="foo*,r>=1.0,r<2" @192.168.3.1:/; echo $?

    EXTENDED OPTIONS
           Extended options can be specified on the command line using the -x
           option or from the defaults file, swdefaults.  Shown below is an actual
           portion of a defaults file which show default values.

       POSIX
           These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults on the local (management host, host where swlist
           invoked).  These files on the target host are not used.

    	  distribution_target_directory	 = /
    	  installed_software_catalog  = var/lib/swbis/catalog/
    	  one_liner		      = files|products	 # Mode when -v not given
    	  select_local		      = false	   # Not Implemented
    	  verbose		      = 1

       Swbis Implementation
           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ~/.swbis/swbisdefaults file.

    	 swlist.swbis_no_getconf = true # true or false
    	 swlist.swbis_shell_command = detect # {detect|sh|bash|posix|ksh}
    	 swlist.swbis_no_remote_kill = false # true or false
    	 swlist.swbis_local_pax_write_command=detect #{pax|tar|gtar|detect}
    	 swlist.swbis_remote_pax_write_command=detect #{pax|tar|gtar|detect}
    	 swlist.swbis_local_pax_read_command=tar #{pax|tar|gtar|star}
    	 swlist.swbis_remote_pax_read_command=tar #{pax|tar|gtar|star}
    	 swlist.swbis_remote_shell_client=ssh
    	 swlist.swbis_forward_agent=True

    RETURN VALUE
           0 if all targets succeeded, 1 if all targets failed or internal error,
           2 if some targets failed and some succeeded.  When checking
           dependencies, 3 if the given sw_specs failed as dependencies, 0 if
           succeeded.

    NOTES
    	Multiple ssh-hops is an implementation extension.

    REQUISITE UTILITIES
           The swbis distributed utilities require bash, public domain ksh, or
           Sun's /usr/xpg4/bin/sh to be present on the target host.	 If the
           swbis_shell_command extended option is set to 'detect' you don't have
           to know which one is present, otherwise you may specify one explicitly.

           A POSIX 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.

           Tar or pax is used for internally for data transfer.  You may specify
           which one.  swlist and swverify require either GNU tar or pax be
           present on a host.  You may set auto detection for this requirement

           swlist.swbis_local_pax_write_command=detect #{pax|tar|gtar|detect}
           swlist.swbis_remote_pax_write_command=detect #{pax|tar|gtar|detect}

           GNU Privacy Guard, gpg is required for verification of package
           signatures.

    FILES
           /var/lib/swbis/catalog # Location of installed catalog
           /usr/lib/swbis/swdefaults
           /usr/lib/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701

    SEE ALSO
           info swbis

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

    IDENTIFICATION
    	swlist(8): The query/listing utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2006-07
    	Copying: GNU Free Documentation License

    BUGS
           swlist is subject to breakage if a user's account on an intermediate
           (or terminal) host in a target spec is not configured to use a Bourne
           compatible shell. (This breakage may be eliminated by use of the --no-
           getconf option as explained above.)

           swlist does not currently implement the -v,-a options.  Listing
           products in a distribution is not supported.  Operating on a
           distribution in directory form is not supported.	 The catalog query
           funtions are implemented in awk and subject to its bugs.

    								     swlist(8)

Next: (swbis_swconfig), Previous: (swbis_swverify), Up: Command Reference

### swverify.8 in one text file

    swverify(8)		    System Manager's Manual		   swverify(8)

    NAME
           swverify — Verify Software

    SYNOPSIS
           Posix:

           swverify	 [-d|-r]  [-F]	[-f file]  [-t targetfile] \
           [-x option=value]  [-X options_file]  [-W option] \
           [software_selections]  [@targets]

           swverify	 # Verify standard input

           swverify selection [@ target] # Verify Installed Software

           swverify -d [@ target]

           swverify -d @-	# dash means standard input

           swverify [--scm|--order-files] -d @.  # . means current directory

           swverify [--scm|--order-files] -d @:package_directory

           Implementation Extension:

           swverify [-Wd] -Wemit-digest-file [portable_archive_file]

           swverify [-Wd] -Wemit-signed-file [portable_archive_file]

           swverify [-Wd] [-Wsha1] -Wemit-digest-file [portable_archive_file]

           swverify [-Wd] -Wget-sig-if=sigfilename [portable_archive_file]

    DESCRIPTION
           The swverify utility checks the accuracy of software in distributions
           and installed_software.	If no options are given, a serial distribution
           on stdin is verified.

           Currently, swverify does not read the defaults files.  "/" is the
           default target for installed software.  Stdin is the default target for
           distributions.  The built-in value of "installed_software_catalog" is
           "var/lib/swbis/catalog".

    OPTIONS
           -d

    	      Specify to operate on a distribution rather than installed
    	      software.

           -r

    	      Specify that target is an alternate root target. (Not currently
    	      used)

           software_selections

    	      See other man pages.

           targets

    	      See other man pages.  Currently, only one (1) target can be
    	      specified.

           -x option=value

    	      Specify the extended option overriding the defaults file value.
    	      This option not yet implemented.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filename.	 This option not yet implemented.

           Other POSIX options not implemented.

    POSIX EXTENDED OPTIONS
           Not yet implemented.

    IMPLEMENTATION EXTENSION OPTIONS
           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.

           --checksig | -W checksig

    	      This is the default action and is the same as the POSIX syntax
    	      "-d @target".  If target file is not a directory then verify
    	      archive md5 and sha1 and gpg signature directly from the file.
    	      If target file is a directory, attempt to verify the signature
    	      using GNU tar and gpg and if successful execute the distributor
    	      extension script checksig.  If checksig does not exist then exit
    	      with failure.
    	      FILE may be "." (current directory) or "-" (standard input).  A
    	      serial archive file may be compressed with gzip, bzip2, or Unix
    	      compress.

           --order-catalog

    	      Use the order of files in catalog/dfiles/files to recreate the
    	      signed data when verifying the directory (unpacked tarball) form
    	      of the package.

           --cvs

    	      Read and process information in the ./catalog (before it is
    	      authenticated) to correct the file sytem meta-data in an attempt
    	      to verify the GPG signature.  It only affects verification on
    	      the directory (unpacked tarball), not tarball verification.  It
    	      is required when verifying an exported or working SCM (Source
    	      Code Management, such as CVS) directory if the SCM does not
    	      preserve and restore file system meta-data.  This option also
    	      emliminates the dependency on the order of files in file system
    	      directories.

           --scm

    	      Currently, same as the --cvs option.

           --no-checkdigest

    	      When verifying the directory form, do not run the checkdigest
    	      script even if the GPG signed data contains the checkdigest
    	      script.

           --signed-file  [FILE]

    	      Write the GPG signed portion of the package to stdout without
    	      verifying it.  Read archive file FILE or standard input and
    	      write the signed file (i.e. gpg's signed stuff) to stdout.  This
    	      is the catalog section of the Posix package.  This option is
    	      supported for the tarball file and unpacked tarball directory.
    	      Use of the --scm option may be required for the unpacked tarball
    	      directory form.

           --digest-file  [FILE]

    	      Write the payload portion of the package to stdout without
    	      verifying its digest matches the digest in the signed data.
    	      This is the storage section of the Posix package.	 This option
    	      is not supported for the unpacked tarball form.

           -W emit-signed-file | -W C

    	      Same as --signed-data.  Also the same as -WC

           -W emit-digest-file [FILE]

    	      Same as --digest-data.  Also the same as -WS

           -W show-auth-files | -W d

    	      Writes the relevent security file to stderr.  Applies to emit-
    	      digest-file and emit-signed-file modes.

           -W sig-number=N

    	      Operates on the Nth signature, 0 is last, 1 is the first.

           -W get-sig-if=outputfile

    	      Verifies the archive digests by comparing to the digests in the
    	      catalog and if they match write the sigfile to outputfile and
    	      the signed data to stdout.

    DISTRIBUTOR SCRIPTS
           Not yet implemented.

    IMPLEMENTATION EXTENSION DISTRIBUTOR SCRIPTS
       checkdigest <path>/catalog/<dfiles>/checkdigest
           This script was named 'checksig'.  As of 2006-03-28, the name of this
           script should be 'checkdigest'.	The name 'checksig' should be
           considered deprecated for new packages.

           A software distributor may choose to provide a checkdigest script.  The
           checkdigest  script is part of the distribution object.	It is used to
           verify the directory form of a distribution  (as distinguished from
           installed_software).  The verified attributes are the same as those
           verified from the archive file form with the addition of the
           distribution file list.	In addition the script may chose to verify the
           adjunct_md5sum and file.md5 digests and symbolic links.	Due to the
           constraints of reproducing the archive message digests from the
           directory, which include tar utility dependence and file owner/group
           specification, this script may not be useful to all distributors.

       Execution Environment
    	The script may require the SW_CONTROL_TAG environment variable be set
           to "checkdigest" or "checkfile" and if not exit with failure.  swverify
           will set this variable to "checkfile" if the --scm or --cvs option is
           used, and otherwise to "checkdigest".  The script may take different
           action based on the value.  Currently, the checkdigest script used by
           the swbis source package will omit the archive digests checks if set to
           SW_CONTROL_TAG="checkfile" since reproducing the archive digest is not
           possible when the package is exported from CVS due to file system meta-
           data non-preservation. In this case the file list is checked and the
           md5 and sha1 digests are verified for each regular file.

    VERIFYING SIGNATURES
           The design separates the payload and catalog, therefore, verification
           requires verifying the storage section md5 and sha1 message digests and
           then verifying the signature of the catalog.  Naturally, it is required
           that the signed data include the storage section message digests and
           that they match the storage sections.  The storage section digests are
           stored as separate attribute files in the dfiles catalog directory.

           The checksig (i.e. swverify -d @-) mode verifies a tarballs embedded
           signature.  This mode checks all the security files in the package and
           is the preferred way to authenticate a package.	The emit-signed-file,
           emit-digest-file modes are useful for testing, sanity checks and custom
           applications.  The get-sig-if is the function used when verifying a
           tarball.

       Verifying a POSIX Distribution Archive Manually
           The design of the authentication attributes supports manual
           verification of the archive file (e.g. tarball) form of the
           distribution, that is verification take place on the uncompressed
           archive using 'gpg', GNU 'tar' and the swbis utility 'swverify' (or the
           library utility 'arf2arf').

           The authentication requires the following steps:

           1) Obtain the signature from the package.
           2) Recreate the signed data and present this byte stream and
    	  the signature to GNU privacy guard (gpg) for authentication.
           3) Obtain the message digest (md5, sha1,) contained in the
    	  control file in the authenticated archive byte stream.
           4) Recreate the digest byte stream and present to the appropriate
    	  hash generation program to generate the message digest.
           5) Compare the digest message generated in step 4 to the
    	  authenicated digest obtained in step 3.

    	1) Obtain the signature from the package.

    	 #!/bin/sh
    	 tar zxf - -O \*/catalog/dfiles/signature < swbis-0.460.tar.gz

           2)  Recreate the signed data

    	 #!/bin/sh
    	 swverify -WC < swbis-0.460.tar.gz | gpg --verify /dev/tty -
    	 # Cut and paste the signature file obtained in step 1

           3)  Obtain the message digest

    	 #!/bin/sh
    	 swverify -WC < swbis-0.460.tar.gz | \
    	 tar xf - -O \*/catalog/dfiles/md5sum

           4)  Create the digested byte stream

    	 #!/bin/sh
    	 swverify -WS < swbis-0.460.tar.gz | md5sum

       Verifying a POSIX Distribution Directory Manually
           Verifying the unpacked tarball package form.

           The design of the authentication attributes supports manual
           verification of the directory (unpacked) form of the distribution, that
           is verification takes place on the leading package directory and its
           contents. It should be noted that it is left to the user to verify that
           the archive installed no files outside of this directory as this would
           likely indicate a trojan'ed package.

           If authenticating on a GNU/Linux system using GNU tar it is possible to
           validate the archive message digests and signature if the following are
           true:

           1) The package file is a tar archive.
           2) The installed version of GNU tar produces archives with
    	  bit-for-bit sameness relative to the swpackage(8) utility
    	  that generated the signature and message digests.  For packages
    	  made with swbis versions >= 0.474 and with format option "ustar"
    	  you will need GNU tar 1.14 or 1.15.*
           3) The package has a single leading package directory, like a source
    	  package.
           4) The package catalog contains the 'checkdigest' script.
           5) The package catalog contains the distribution file list.
           6) The ownership names are present and have the same uid's and gid's.
           7) The package was unpacked with a version of tar that
    	  preserves all file times.  Use for example "tar xpf".

           In this example, the package has a single path name prefix called,
           namedir and the file owner/group are root.  These restrictions are
           suited to source packages.
    	Verify the signature:

    	 #!/bin/sh
    	 tar cf - -b1 --owner=root --group=root \
    	 --exclude=namedir/catalog/dfiles/signature  \
    	 namedir/catalog | gpg --verify namedir/catalog/dfiles/signature -

           If this fails try using GNU tar option --posix.	If this fails then,
           try experimenting with the owner, group, and numeric-id options.	 If
           you are unable to verify a tar byte stream using gpg(1) that contains
           the storage section message digests, then the package cannot be
           authenticated.

           Assuming you successfully verified the catalog as shown above, now
           generate the message digest and compare it to the md5sum file attribute
           from the same byte stream that gpg(1) claims is authenticate.

    	 #!/bin/sh
    	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
    	 tar cf - -b1 --owner=root --group=root \
    	 --no-recursion --files-from=- | md5sum

    	 tar cf - -b1 --owner=root --group=root \
    	 --exclude=namedir/catalog/dfiles/signature  \
    	 namedir/catalog | tar xf - -O	namedir/catalog/dfiles/md5sum

           Likewise for the sha1 digest.

           If the package has symbolic links, Verify the adjunct_md5sum:

    	 #!/bin/sh
    	 grep -v namedir/catalog  namedir/catalog/dfiles/files | \
    	 ( while read file; do if [ ! -h $file ]; then echo $file; fi done; )|\
    	 tar cf - -b1 --owner=root --group=root \
    	 --no-recursion --files-from=- | md5sum
    	 cat namedir/catalog/dfiles/adjunct_md5sum

           The symbolic link files must be verified manually by comparing to the
           INFO file information.

       Verifying a POSIX distribution in tar format
           Below is output from successful authentication.	The authentication
           requires checking the archive md5 message digest (and sha1 if present).
           All present message digests must succeed and if this is true then the
           signed file is written and gpg proceeds to check the signature.	If the
           sig_header file is present then the requirement that its data be
           identical to the ustar header of every signature file is enforced.  If
           any one of these checks fails, authentication fails.

    	  #!/bin/sh
    	  swverify --checksig mypackage-00.1.tar.gz
    	       # - or -
    	  swverify -d @- < mypackage-00.1.tar.gz

           gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
           gpg: please use "keyserver-options honor-http-proxy" instead
           gpg: WARNING: using insecure memory!
           gpg: please see http://www.gnupg.org/faq.html for more information
           swbis: Archive digest: md5 OK (Good)
           swbis: Archive digest: sha1 OK (Good)
           gpg: Signature made Sun Mar 16 20:28:23 2003 EST using DSA key ID 82B0DBE4
           gpg: Good signature from "Test User (pass=Iforgot) localhost>"
           Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4

       Verifying the Directory Form of a Distribution
           Authenticating using 'swverify' is subject to the same constraints as
           verifying manually using GNU tools because swverify implements this
           using GNU tools.

           'swverify' when verifying the directory form of a distribution attempts
           to authenticate the exported catalog signature.	If it is successful it
           executes the 'checkdigest' script found in the 'catalog/dfiles'
           directory of the exported catalog.  If the 'checkdigest' script does
           not exist, authentication fails. 'swverify' will only attempt to run
           the 'checkdigest' script if it is found in the dfiles directory of an
           authenticated catalog.

           'swverify' currently has no provision to verify the archive section
           (i.e. the file storage structure) of a directory (unpacked) form of a
           POSIX distribution.  It is the role of the checkdigest script to do
           this.

           For example, if filemypackage-00.1 is a directory unpacked with a tar
           reading utility that preserved file times then try,

    	  #!/bin/sh
    	  swverify --checksig mypackage-00.1

    	or change directory into mypackage-00.1 and use the POSIX syntax:

    	  swverify -d @.

    	  swverify -d @`pwd`/mypackage-00.1

    	Below is example output of a package with a 'checksig' script.

           swverify: Attempting to verify using --posix tar option.
           gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
           gpg: please use "keyserver-options honor-http-proxy" instead
           gpg: WARNING: using insecure memory!
           gpg: please see http://www.gnupg.org/faq.html for more information
           gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
           gpg: BAD signature from "Test User (pass=Iforgot) localhost>"
           swverify: First attempt failed.
           swverify: Attempting to verify without using --posix tar option.
           gpg: /home/jhl/.gnupg/options:82: deprecated option "honor-http-proxy"
           gpg: please use "keyserver-options honor-http-proxy" instead
           gpg: WARNING: using insecure memory!
           gpg: please see http://www.gnupg.org/faq.html for more information
           gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
           gpg: Good signature from "Test User (pass=Iforgot) localhost>"
           gpg: WARNING: This key is not certified with a trusted signature!
           gpg:	     There is no indication that the signature belongs to the owner.
           Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4
           swverify: GPG signature verified.
           swverify: Got it!
           swverify: The vendor extension script checksig can now be executed.
           checksig: Checking files OK (Good)
           checksig: Checking Archive md5 OK (Good)
           checksig: Checking Archive sha1 OK (Good)
           gpg: /home/userx/.gnupg/options:82: deprecated option "honor-http-proxy"
           gpg: please use "keyserver-options honor-http-proxy" instead
           gpg: WARNING: using insecure memory!
           gpg: please see http://www.gnupg.org/faq.html for more information
           gpg: Signature made Sun Mar 16 21:00:54 2003 EST using DSA key ID 82B0DBE4
           gpg: Good signature from "Test User (pass=Iforgot) localhost>"
           gpg: WARNING: This key is not certified with a trusted signature!
           gpg:	     There is no indication that the signature belongs to the owner.
           Primary key fingerprint: 77BB A98E B3A2 ED4C 217E  8A25 2BF4 28AB 82D0 DDE4
           checksig: Signature proper OK (Good)
           checksig: /usr/bin/gpg exit status : 0

       Verifying Installed Software
           (This capability is only partially implemented.)	 Verifying Installed
           Software involves comparing the package meta-data to the live file
           system.	The validity of a successful comparison depends on the
           validity of the installed software catalog.  swverify makes no attempt
           to check the validity of the entire catalog, however, it can use the
           distribution GPG signature, which is stored in the catalog, to
           authenticate the meta-data of the selected package.

           Below is an example. Note, the package is selected on the basis of its
           product or bundle tag.

           $ swverify -r your_product_tag @ /
           swverify: verifying installed software at:
           swverify: //var/lib/swbis/catalog/swbis/your_product_tag/0.000/0
           gpg: WARNING: --honor-http-proxy is a deprecated option.
           gpg: please use "--keyserver-options honor-http-proxy" instead
           gpg: Signature made Fri Feb 20 00:21:00 2004 EST using DSA key ID 82B0DBE4
           gpg: Good signature from "Test User (pass=Iforgot) localhost>"
           Fingerprint: 77BB B98D A3A2 ED4C 217E  9A25 8BF4 05AB 82B0 DBE4
           swverify: Warning: file checks not implemented
           swverify: signature verification return status=0

       Create the digest byte stream -Wemit-digest-file mode:
           Here are some examples that verify the archive digests.

    	  #!/bin/sh
    	  cat your-tarball | swverify -Wd -WS | md5sum

           Your should see a pair of identical digests. Use the -Wsha1 option to
           check the sha1 digest in a similar manner.

           ** IMPORTANT **
           This does not mean that the data is authenticate in the sense of being
           attributable to a person, merely that the md5sum attribute and the
           payload byte stream match.

           To inspect the digested data, try:

    	 #!/bin/sh
    	 cat your-tarball | swverify -WS | tar tvf -

       Create the signed byte stream -Wemit-signed-file mode:
           Here is an example which allows inspection of the signed file.

    	 cat your-tarball | swverify -WC | tar tvf -

       -Wget-sig-if mode:
           This is the mode that is used internally when verifying a tarball.
           Below is an example of using this mode manually.

    	 #!/bin/sh
    	 cat your-tarball | swverify -Wget-sig-if=/dev/tty | \
    	 gpg --verify  /dev/tty -

           Now try to copy and paste the sigfile and gpg should attempt to verify
           the signature.

    	      Note:  This verifies the md5 or sha1 digests before writing the
    	      signed data to stdout.  If the sha1 or md5 match fails then an
    	      empty file is written to stdout.

    EXAMPLES
           Examples of verifying distributions and installed software.

       Distribution Verification
           * Verify a tar archive

    	 swverify -d < foo-1.1.tar.gz
    		  or
    	 swverify -d @`pwd`/foo-1.1.tar.gz
    		  or
    	 swverify -d @:foo-1.1.tar.gz
    		  or
    	 cat foo-1.1.tar.gz | swverify -d @-

    		 Note: --checksig and '-d' perform the same operations.

           * Verify a unpacked distribution

    	 swverify -d @`pwd`/foo-1.1
    		  or
    	 cd foo-1.1; swverify -d @.
    		  or
    	 swverify -d @:foo-1.1

    		 Note: --checksig and '-d' perform the same operations.

           * Verify an exported SCM Directory

    	 # This is the same as directory verification except the '--cvs' option is needed.

       Installed Software Verification
           * Verify installed software

    	 swverify foo.foo @/tmp/test
    		  or
    	 swverify foo.foo  # at default target

    RETURN VALUE
           Exit status of the checksig script or gpg utility for --checksig
           directory operation.  0 if successful on all targets, 1 if failed on
           all targets, 2 if failed on some targets.

    FILES
           /var/lib/swbis/catalog # Location of installed catalog
           /usr/lib/swbis/swdefaults
           /usr/lib/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           IEEE Std 1387.2-1995 (ISO/IEC 15068-2:1999), Open Group CAE C701.

    SEE ALSO
           info swbis

           sw(5), swbis(1), swign(1), swpackage(8), gpg(1), libexec/swbis/arf2arf

    IDENTIFICATION
    	swverify: The verification utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2010-02-04
    	Copying: GNU Free Documentation License

    BUGS
           The signature file's archive header (or data) is not part of the signed
           data therefore it may be subject to undetectable tampering, however,
           swverify does perform sanity checks on the pathname, permissions and
           filetype if the sig_header file (See sw(5) manual page.) is not present
           [due to being signed by a old swpackage version], and if sig_header is
           present, swverify requires that it match the sig file header.  The
           ability to verify the unpacked directory form of the package depends on
           many factors not immediately obvious, among them are the tar header
           uname and gname, and whether they are preserved by the reading utility,
           and whether these names are in the system database files /etc/passwd
           and /etc/group, and if so, whether they assign the same uid/gid as the
           package.

           Verification of the directory form of a distribution (i.e. the
           installed tarball path name prefix) such as running 'swverify -d @.'
           after running 'swign @.' will fail if the order of directory entries is
           not compatible with traditional Unix file system directory entry
           ordering, which is the order of file creation.  This ordering is almost
           always apparent on Ext2 file system for small directories (but not
           always for big directories).  Ext3, reiserFS, and DarwinOS et.al file
           systems do not have this ordering, use of the '--order-catalog' option
           is therefore required.  Use of the '--cvs' or '--order-catalog' options
           is theoretically problematic because it causes the use and
           interpretation of data in the verification of that same data therefore
           opening possible attack vectors.

    								   swverify(8)

Next: (swbis_swign), Previous: (swbis_swconfig), Up: Command Reference

### swconfig.8 in one text file

    swconfig(8)		    System Manager's Manual		   swconfig(8)

    NAME
           swconfig — Configure installed software

    SYNOPSIS
           swconfig	 [-p] [-u]  [-c catalog] [-f file] [-t targetfile] \
           [-x option=value]  [-X options_file]  [-W option] \
           [software_selections]  [@targets]

    DESCRIPTION
           swconfig configures, unconfigures, and reconfigures installed software
           on a host.  swconfig is a distributed utility.  Neither swconfig nor
           any component of swbis is required on the target host, however, the
           target host must look like a Unix system at the shell and command-line
           utility level.  Remote network connections are made by ssh.  Ssh is the
           default but rsh can be selected by a command line option.

           swconfig operates on installed software and performs configuration
           primarily by executing the configure or unconfigure control scirpts.
           If these scripts do not exists for an installed package, then swconfig
           takes no action.

    OPTIONS
           -f FILE

    	      Read the list of software selections from FILE.

           -p

    	      Preview mode, establish contact with target host, however,
    	      modify nothing.

           -u

    	      Undo, run the unconfigure script.

           -c catalog

    	      Specify a file of PSF or INDEX syntax or a directory containing
    	      the exported catalog.

    		     Note:  This option is not yet implemented.

           -t targetfile

    	      Specify a file containing a list of targets (one per line).

           -v

    	      Increment the verbose level.

           -x option=value

    	      Specify the extended option overriding the defaults file value.

           -X FILE

    	      Specify the extended options filename, FILE,  overriding the
    	      default filenames.  This option may be given more then once. If
    	      the resulting specified value is an empty string then reading of
    	      any options file is disabled.

           --help

    	      Show help (Implementation extension)

           -W option[,option,...]

    	      Specify the implementation extension option.
    	      Syntax: -W option[=option_argument[,option...]
    	      Options may be separated by a comma.  The implementation
    	      extension options may also be given individually using the
    	      '--long-option[=option_arg]' syntax.

           --postinstall

    	      run the postinstall or unpostinstall script

           --force-locks

    	      override locking and delete existing lock

           --send-environment

    	      Include existing environment variables in the remote host's
    	      execution environment.  System and common varaiables are
    	      excluded and checks are made for tainted values.

           --allow-ambig

    	      Allows swconfig to act on all matching entries.  Without this
    	      option a software selection that matches more than one installed
    	      software entry is an error.

           --sig-level=N

    	      Specify number of required GPG signatures, N equal to 0 means
    	      don't require the catalog to be signed.

           -W remote-shell=SHELL

    	      Defaults File Option: swbis_remote_shell_client
    	      Supported shells are "ssh" and "rsh", ssh is the default.

           -W show-options-files
    	      Show the complete list of options files and if they are found.

           -W show-options
    	      Show the options after reading the files and parsing the command
    	      line options.

           -W pax-command={tar|pax|star|gtar}
    	      Set the portable archive command for all operations.  The
    	      default is "pax".

           -W pax-read-command={tar|pax|star|gtar}
    	      Set the read command for local and remote hosts.

           -W remote-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_remote_pax_read_command
    	      Set the read command for remote hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W local-pax-read-command={tar|pax|star|gtar}
    	      Defaults File Option: swbis_local_pax_read_command
    	      Set the read command for local hosts.  This is the command that
    	      runs on the target (e.g. pax -r, tar xpf -).  The default is
    	      "pax".

           -W pax-write-command={tar|pax|star|gtar|swbistar}
    	      Set the write command for local and remote hosts.	 This is the
    	      command that runs on the target (e.g. pax -w, tar cf -).

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the write command for remote hosts.

           -W local-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_local_pax_write_command
    	      Set the portable archive write command for local host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W remote-pax-write-command={tar|pax|star|gtar|swbistar}
    	      Defaults File Option: swbis_remote_pax_write_command
    	      Set the portable archive write command for remote host
    	      operations.  This is the command that runs on the source (e.g.
    	      pax -w, tar cf -).  The default is "pax".

           -W no-defaults
    	      Do not read any defaults files.

           -W no-getconf
    	      Defaults File Option: swbis_no_getconf
    	      Makes the remote command be '/bin/sh -s' instead of the default
    	      'PATH=`getconf PATH` sh -s'.

           -W shell-command=NAME
    	      Defaults File Option: swbis_shell_command
    	      NAME may be one of "bash", "sh" or "posix" and specifies the
    	      remote command run by the remote shell.  "posix" is
    	      'PATH=`getconf PATH` sh -s', "bash" is "/bin/bash -s", "sh" is
    	      "/bin/sh -s", and "ksh" is "ksh -s".  The default is "posix".

           -W use-getconf
    	      Opposite of --no-getconf.

           -W source-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           -W target-script-name=NAME
    	      Write the script that is written into the remote shell's stdin
    	      to NAME.	This is useful for debugging.

           software_selections

    	      Refer to the software objects (products, filesets) using
    	      software spec syntax. (See sw(5) for syntax).

           target

    	      Refers to the software_collection where the software selections
    	      are to be applied.  Allows specification of host and pathname
    	      where the software collection is located.	 A target that
    	      contains only one part is assumed to be a hostname.  To force
    	      interpretation as a path, use a absolute path or prefix with
    	      ':'.

           Source and Target Specification and Logic

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

    		 Swbis Extension:
    		      [user@]host[:path]
    		      [user@]host_port[:path]
    		      :path

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

    		      [user@]host[@@[user@]host[@@...]][:file]
    		      [user@]host_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_port:host_port:
    		      host:host:file
    		      user@host:user@host:
    		      user@host:user@host:host:
    		      user@host:user@host:file

    	    A more formal description:

    	    target : HOST_CHARACTER_STRING ':' PATHNAME_CHARACTER_STRING
    		   | HOST_CHARACTER_STRING ':'
    		   | HOST_CHARACTER_STRING
    		   | PATHNAME_CHARACTER_STRING
    		   | ':' PATHNAME_CHARACTER_STRING   # Impl extension
    		   ;

    	      PATHNAME_CHARACTER_STRING must be an absolute path unless
    			      a HOST_CHARACTER_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_CHARACTER_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_CHARACTER_STRING
    		    | PATHNAME_CHARACTER_STRING
    		    ;
    	   user	    : PORTABLE_CHARACTER_STRING	 # The user name

    	   DELIM    : ':'   # The multi-hop delimiter.
    		    ;

    USAGE EXAMPLES
       Run the configure script for package foo on 192.168.1.2:/
    	 swconfig foo @ root@192.168.1.2:/

       Show the options
    	 swconfig --show-options

    EXTENDED OPTIONS
           Extended options can be specified on the command line using the -x
           option or from the defaults file, swdefaults.  Shown below is an actual
           portion of a defaults file which show default values.

       POSIX
           These options are set in the /usr/lib/swbis/swdefaults or the
           ~/.swdefaults on the local (management host, host where swconfig is
           invoked).  These files on the target host are not used.

    	 allow_incompatible	       = false # Not implemented
    	 allow_multiple_versions       = false # Not implemented
    	 ask			       = false # Not implemented
    	 autoselect_dependencies       = true # Not implemented
    	 autoselect_dependents	       = true # Not implemented
    	 enforce_dependencies	       = true # Not implemented
    	 installed_software_catalog    = var/lib/swbis/catalog/
    	 logfile		       = /var/log/sw.log
    	 loglevel		       = 1
    	 select_local		       = true # Not implemented
    	 reconfigure		       = false
    	 verbose		       = 1

       Swbis Implementation
           These options are set in the /usr/lib/swbis/swbisdefaults or the
           ~/.swbis/swbisdefaults file.

    	  swconfig.swbis_no_getconf = true # true or false
    	 swconfig.swbis_shell_command = posix # {sh|bash|posix|ksh}
    	 swconfig.swbis_no_remote_kill = false # true or false
    	 swconfig.swbis_local_pax_write_command=tar #{pax|tar|star|gtar}
    	 swconfig.swbis_remote_pax_write_command=tar #{pax|tar|star|gtar}
    	 swconfig.swbis_local_pax_read_command=tar #{pax|tar|gtar|star}
    	 swconfig.swbis_remote_pax_read_command=tar #{pax|tar|gtar|star}
    	 swconfig.swbis_local_pax_remove_command=tar
    	 swconfig.swbis_remote_pax_remove_command=tar
    	 swconfig.swbis_remote_shell_client=ssh
    	 swconfig.swbis_forward_agent=True
    	 swconfig.swbis_sig_level=0
    	 swconfig.swbis_enforce_all_signatures=false

    RETURN VALUE
           0 if all targets succeeded, 1 if all targets failed or internal error,
           2 if some targets failed and some succeeded.

    NOTES
    	Multiple ssh-hops is an implementation extension.

    REQUISITE UTILITIES
           The swbis distributed utilities require bash, public domain ksh, or
           Sun's /usr/xpg4/bin/sh to be present on the target host.	 If the
           swbis_shell_command extended option is set to 'detect' you don't have
           to know which one is present, otherwise you may specify one explicitly.

           A POSIX 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.

           GNU Privacy Guard, gpg is required for verification of package
           signatures.

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

    FILES
           /var/lib/swbis/catalog # Location of installed catalog
           /usr/lib/swbis/swdefaults
           /usr/lib/swbis/swbisdefaults
           $HOME/.swbis/swdefaults
           $HOME/.swbis/swbisdefaults

    APPLICABLE STANDARDS
           ISO/IEC 15068-2:1999, Open Group CAE C701

    SEE ALSO
           info swbis

           swbis(7), sw(5), swlist(8)

    IDENTIFICATION
    	swconfig(8): The package configuration utility of the swbis project.
    	Author: Jim Lowe   Email: jhlowe at acm.org
    	Version: 1.13.1
    	Last Updated: 2010-01-22
    	Copying: GNU Free Documentation License

    BUGS
           This section is left intentionally black

    								   swconfig(8)

Next: (swbis_lxpsf), Previous: (swbis_swign), Up: Command Reference

### swign.1 in one text file

    swign(1)		    General Commands Manual		      swign(1)

    NAME
           swign — Create a tar archive of a directory with an embedded GPG
           signature.

    SYNOPSIS
           swign [options] [-u gpg-name] [--homedir=gpg-homedir] @- # Write to stdout

           swign [options] [-u gpg-name] [--homedir=gpg-homedir] @.	 # Sign directory

           swign -S [options] [-u gpg-name] [--homedir=gpg-homedir]

           swign -E [options] [-u gpg-name] [--homedir=gpg-homedir]

    DESCRIPTION
           swign reads a PSF (Product Specfication File) to generate and load the
           package catalog into the current directory and then writes the
           cooresponding archive to stdout.	 The PSF is read from standard input
           by default.  To use an internally generated PSF with name and revision
           attributes determined from the name of the current directory use '-s.'.

           The PSF is scanned for replacement tokens for tag and revision
           attributes determined from the current directoy name.  It is expected
           that the current directory name have the form: 'tag-revision'.  The
           replacement string has the form '%__NAME' where NAME is 'tag' or
           'revision'.  The directory derived values can be overridden with the
           '--revision' or '--name-version' options.

           swign by default will remove and re-create the ./catalog/ meta-data
           directory, then use GNU tar to write the current directory as a tar
           archive to stdout.  The result is a tar archive written entirely with
           GNU tar that contains an embedded GPG signature in the control file
           './catalog/dfiles/signature'.  The contents of './catalog/' are
           consistent with the POSIX packaging standard ISO/IEC 15068-2:1999.  The
           package layout of the resulting archive is unchanged except for the
           addition of the './catalog' directory.

           The contents of the archive is the contents of the current directory
           ".".  The pathnames in the archive are prefixed by the base name of
           ".".  The owner and group of all the files in the emitted archive are
           specified by the PSF file and command line options.

           In order for the signature to be valid, the file ownerships specified
           in the PSF must be consistent with the 'swign' command.	swign will
           read the PSF to determine these ownerships automatically from the
           'file_permissions' directive unless the '-o' or '-g' command line
           options are used or if this feature is disabled using the '--no-psf-
           detect' option is given.

           The default ownerships for all the files are the current user's owner
           and group.  If the -o (or -g) option is used with a empty string for
           the option arg then the file ownerships of the source files are used.
           This script assumes GNU tar is installed.

           After writing the ./catalog/ file and before writing the archive, the
           file list stored in ./catalog/dfiles/files is compared to the current
           directory contents, if any difference is found the archive is not
           written and error returned.

    OPTIONS
           --help
    	      show help.

           --show-psf
    	      show the PSF to stdout, and then exit.

           --no-psf-detect
    	      Disable automatic detection of the PSF's file ownerships policy.

           --no-remove
    	      Don't remove the ./catalog directory before overwriting.

           --file-ownerships
    	      Use the file ownerships and permissions of the source files.

           -u, --local-user name
    	      Use name as the user ID to sign.

           --homedir=DIR
    	      Set the name of the home directory to DIR.  If not specified
    	      then use "~/.gnupg".

           -s, --source=FILE
    	      Specify a PSF file name or one of two special names, '-' for
    	      stdin, and '.' for the internally generated PSF.

           -T, --show-names-only
    	      show some info (for help and debugging) and exit.

           -t, --run-sanity-check
    	      Instead of writing stdout, write the archive to
    	      ../packageDirName.swigntest.tar.gz and run some sanity tests.

           -S, --sign-only
    	      Write the ./catalog/ file containing the digest and signature
    	      into "." and then exit without writing the archive to stdout.
    	      Same as using "." as the target such as 'swign @.'

           -E, --emit-only
    	      Do not write the ./catalog/ file containing the digest and
    	      signature into "." and then write the archive to stdout.	This
    	      does not affect the directory contents.

           -D, --with-checkdigest FILE
    	      Include the checkdigest control script sourced from FILE.	 This
    	      is only needed when not supplying a PSF, that is this option
    	      modifies an internally generated PSF.

           -o, --owner OWNER
    	      Specify owner.  Use an empty string "" to specify the source
    	      file owner.

           -g, --group GROUP
    	      Specify group.  Use an empty string "" to specify the source
    	      file group.

           --name-version=NAME-REV
    	      Specify a product tag and revision as dash delimited.

           -r, --revision REV
    	      Specify a product revision.  This will override a revision part
    	      of the current directory's name.

           -x format
    	      Specify the archive format.  Must be one of the formats of
    	      swpackage.

           @-
    	      Target, only supported target is standard output.

    EXTERNAL EFFECTS
           The program will remove and replace a file in "." named ./catalog/.
           Nothing outside of './catalog/' is modified.
           Standard output is the target for the tar archive.
           When using the '-t' option an archive file is written to
           ../packageDirName.swigntest.tar.gz

           A copy of the PSF is made in /var/tmp/swign$$.  It is normally created
           and erased by the program.

    EXAMPLES
           Show the internally generated PSF to stdout.  Change directory into the
           directory to package, then type

    	  swign -s. --show-psf
    	  #
    	  # or specify a owner and group policy
    	  swign -s. -o 0 -g 0 --show-psf

           Create a signed metadata (i.e. catalog/) directory of a live directory,
           for example /bin

    	      swign -D $HOME/checkdigest.sh -u "YourGPGNAME" -o "" -g "" @.

           Generate the package (and verify it) using a PSF that you supply on
           standard input.	Change directory into the directory to package, then
           type

    	  swign -o 0 -g 0 --show-psf | swign -s - -u "gpgName" @- | swverify -d @-

           Example of directory signing and authentication.

    	  swign -u YourGPGName -s. --file-ownerships -D /HOME/checkdigest.sh --sign-only
    	  swverify -d @.
    	  swign	 --file-ownerships -emit-only | swverify -d @-

    TESTING
           After running successfully with options -S  and -D FILE	the following
           should be true (report no error).

    		 swverify --checksig .	 # Deprecated form
    		     -or-
    		 swverify -d @.	    # POSIX syntax

           Similarly,

    		 swign -u "your GPG Name" @- | swverify --checksig -
    		     -or-
    		 swign -u "your GPG Name" @- | swverify -d @-

           If a checkdigest script is included then you should unpack the package
           at a new location and run  swverify -d @. in the new location.  The
           checkdigest script is a vendor extension control file that is part of
           the GPG signed ./catalog directory.  As an implementation extension
           behavior the swverify program will execute this script after
           verification of the signature.  The script may take any action at this
           point, but the intention is that it be used to verify the contents of
           the package directory using GNU tools such as md5sum, sha1sum, and tar.

           If a checkdigest script is not included, then the package user will
           have to manually execute the commands that would have been executed by
           the script using the file meta-data in an authenticated INFO file.
           When verifying the unpacked directory form of a package,	 the swverify
           program will return an error if the checkdigest script is not present,
           though, it is not required for verification of the tar archive file
           itself using swverify.

           Swign can be used to sign any directory using the file ownerships of
           the source files.  The following commands act as a test of swpackage's
           ability to generate an archive identical to GNU tar.  (Note: the script
           checkdigest.sh is found in ./bin of the source distribution.)

    	      swign -D $HOME/checkdigest.sh -u "Test User" -o "" -g "" -S;
    	      swverify -d @.

    PSF ATTRIBUTE REPLACEMENT
           A PSF that is provided using the '-s' option will be scanned for a
           special character sequence '%__NAME'  where NAME is either 'tag' or
           'revision'.  'tag' is replaced with the package name portion of the
           currrent directory.  'revision' is replaced with the version portion.

    SAMPLE SOURCE PACKAGE PSF
           # PSF.in	 -- INPUT file to swign
           # This file contains the replacement macros %__tag and %__revision which
           # are only processed by swign.

           # The distribution object need not have any attributes.
           distribution

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

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

           # This places the checkdigest script in ./catalog/dfiles/checkdigest
           # For a description of the checkdigest script see the info document for
           # 'swbis' or the swverify manual page.
           # The checkdigest script is a verification hook for swverify used when
           # verifying the unpacked tarball (i.e. the package path name
           # prefix directory).

    	 checkdigest  < bin/checkdigest.sh

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

           # The Vendor object is optional
           vendor
    	  the_term_vendor_is_misleading True  # One of: True, False
    	  tag shortName	   # Other vendor tags could be the short name of your
    				# organization name, or	 your initials, etc.
    	  title Your Name
    	  qualifier author
    	  description "Maintainer of somepackage"

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

           # The Bundle object is optional
           bundle
    	  tag somepackage

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

           product
    	  description "somepackage description
           can be mult-line"
    	  tag %__tag			   # This is the package name
    	  revision %__revision		   # This is the package version
    	  vendor_tag shortName		   # Match vendor.tag above
    	  title "somepackage - software"
    	  control_directory ""		   # Empty string, Important

           # The fileset object contains the files.	 The tag, revision,
           # and description attributes are mostly ignored.
           # At this time swbis supports only one (1) fileset.

           fileset
    	   tag sources
    	   control_directory ""	  # Empty string, Important
    	   title somepackage source code
    	   description "The source distribution of somepackage"

           # file_permissions:
           # Here is an important policy.  This will cause 'swpackage'
           # to create the tar achive with all files owned by uid and
           # gid zero (0), the user name 'root' will not be included
           # in the uname and gname tar header fields.  This is similar
           # to the effect of GNU tar options --numeric --owner=root
           # --group=root .
           # To use the name and ids of the source files delete the line
           # or reset the file_permissions adding after or changing to:
           #    file_permissions -u 000
           #
           # NOTE:	Using "file_permissions -o 0 -g 0"  is preferred
           # because it will allow the end user to more easily verify
           # the directory (unpacked) form of the package using standard
           # non-swbis tools.

           #   file_permissions -u 000  # To use ownerships of source files
    	   file_permissions -o 0 -g 0

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

    	   directory .
    	   file *

           # You want to exclude the files in ./catalog because it
           # should not be part of the paylaod section.  This is
           # mandatory.

    	  exclude catalog

           # You may also want other excludes

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

           # End of PSF

    ENVIRONMENT
           SWPACKAGEPASSFD
    	      Sets the swpackage --passphrase-fd option.  Set the option arg
    	      to a integer value of the file descriptor, or to "env" to read
    	      the passphrase from the environment variable
    	      SWPACKAGEPASSPHRASE, or to "agent" to cause gpg to use gpg-
    	      agent, or "tty" to read from the terminal.

           SWPACKAGEPASSPHRASE
    	      Use the value as the passphrase if swpackage's --passphrase-fd
    	      is set to "env"

           GNUPGHOME
    	      Sets the --gpg-home option of swpackage.

           GNUPGNAME
    	      Sets the --gpg-name option of swpackage, which is turn set the
    	      --local-user option of gpg.

    RETURN VALUE
           0 on success, non-zero on failure.

    FILES
    	<path>/catalog/

    SEE ALSO
           info swbis

           swpackage(8), gpg

    IDENTIFICATION
    	swign(1): The source directory signing utility of the swbis project.
    	Author: J. Lowe jhlowe@acm.org
    	Version: 1.13.1
    	Last Updated: 2008-01
    	Copying: GNU Free Documentation License

    BUGS
           Symbolic links in a package are problematic for verifying the unpacked
           form of a package since the modification time is not preserved.	They
           have no affect on verification of the tar archive file using
           'swverify'.

           If a directory is signed using the '-S' option and has a file path
           greater than 99 chars in length then it will be unverifiable if the
           'ustar0' format and GNU tar 1.13.25 was used.

           Verification of the directory form of a distribution (i.e. the
           installed tarball path name prefix) such as running 'swverify -d @.'
           after running 'swign -S' will fail if the order of directory entries is
           not compatible with traditional Unix file system directory entry
           ordering.  This incompatibility may be present in the Ext3, reiserFS,
           and DarwinOS et.al file systems.

           The file ownership policy of the PSF, the checkdigest script (if any)
           and the command line options must agree.	 The default file ownership
           policies of this program are suited to packaged products where file
           user and group ownerships are not a critical feature.

    								      swign(1)

Next: (swbis_sw), Previous: (swbis_lxpsf), Up: Command Reference

### lxpsf.1 in one text file

    LXPSF(1)		    General Commands Manual		      LXPSF(1)

    NAME
           lxpsf - Translate packages to a tar archive with a PSF.

    SYNOPSIS
           lxpsf [options] [package_file]

    DESCRIPTION
           Lxpsf  reads the input package and writes a tar or cpio archive to std‐
           out, depending on the native (or	 encapsulated)	format	of  the	 input
           package.	  The  output  layout  has  a  single  leading directory named
           according to the name, version, and release attributes.

           The first regular file is ``PSF'', and is a IEEE	 1387.2-1995  (ISO/IEC
           15068-2:1999)  Product  Specification File containing the package meta‐
           data.  Subsequent files are control data represented as files, and, the
           files  of  the  distribution.   The output is designed so the swpackage
           utility is able to form a Posix package from the installed output.

           Currently,  RPM format v3 (both source and binary), Debian Package for‐
           mat,  Slackware	runtime	 packages  and	plain vanilla tarballs (with a
           leading directory path) are supported for translation.

       Options
           -p ,--psf-only
    	      Write only the psf file to stdout.

           -A ,--psf-form1
    	      A PSF form for RPM translation (deprecated).

           -A ,--psf-form2
    	      A second PSF form for RPM translation (deprecated).

           -A ,--psf-form3
    	      A third PSF form for RPM translation (current).

           -H format
    	      Force the specified format.  The	choices	 are  currently
    	      (only) ustar.

           -x ,--use-recursive-fileset
    	      Use  "file  *"  instead of individual file definitions in
    	      the PSF.

           -r ,--no-leading-path
    	      use "." as the leading archive path.

           -o ,--info-only
    	      Write the INFO file for the rpm archive to stdout.

           -D ,debug-level=TYPE
    	      Always set to "link"

    HOWTO Use with swpackage
           Either install into file system or use the -W source=- option of
           GNU swpackage.

    	 cat your_rpm.rpm |
    	 lxpsf --format=ustar --psf-form3 |
    	 (mkdir /tmp/swbis; cd /tmp/swbis && tar xpf -; exit $?) &&
    	 (cd /tmp/swbis && swpackage -s PSF @- ) | tar tvf -

    	 cat your_rpm.rpm |
    	 lxpsf --format=ustar --psf-form3 |
    	 swpackage -W source=- -s@PSF @- | tar tvf -

    FILES
    RELATED STANDARDS
           POSIX.1, IEEE 1387.2, XDSA C701

    IDENTIFICATION
    	The RPM translation program of the swbis project.
    	DATE: 2010-02-22
    	Revision: 1.5

    SEE ALSO
           swbisparse(1), swpackage(8)

    BUGS
           Probably	 many. A de-facto conversion policy is intimated in the
           PSF by this program.

    								      LXPSF(1)

Next: (swbis_user), Previous: sw.5 in one text file, Up: Command Reference

### swpackage.5 in one text file

    swpackage(5)		      File Formats Manual		  swpackage(5)

    NAME
           swpackage — file formats

    SYNOPSIS
           Output format - Data Interchange Formats
           Input format - Product Specification File (PSF)

    SWPACKAGE OUTPUT FORMAT
           The output format is either one of two formats specified in POSIX.1
           (ISO/IEC 9945-1) which are tar (header magic=ustar) or cpio (header
           magic=070707).  The default format of the swbis implementation is
           "ustar".	 The POSIX spec under specifies definitions for some of the
           ustar header fields.  The personality of the default swbis ustar format
           mimics GNU tar 1.15.1 and is designed to be compliant to POSIX.1.  The
           personality of the "ustar0" format mimics, for pathnames less than 99
           octets,	GNU tar 1.13.25 using the "-b1 --posix" options.  This bit-
           for-bit sameness does not exist for pathnames greater than 99 chars as
           swbis follows the POSIX spec and GNU tar 1.13.25 does not.  The
           "ustar0" ustar personality is deprecated.  It is only slightly
           different from 'ustar' in how device number fields are filled (with
           spaces, zeros or NULs) for non-device files.

           In addition the swbis implementation supports several other tar
           variants including bit-for-bit mimicry of GNU tar (1.13.25) default
           format which uses a non-standard name split and file type (type 'L').
           This format is known as '--format=oldgnu'.  Also supported is the gnu
           format of GNU tar 1.15.1 specified by '--format=gnu'

           The defacto cpio formats are also supported.  "new ASCII" (sometimes
           called SVR4 cpio) and "crc" cpio formats with header magic "070701" and
           "070702" respectively.

           Support for "pax Interchange Format" (Extended header tar) described in
           IEEE 1003.1-2001 under the "pax" manual page has been implemented for
           POSIX file attributes as of release 1.12 (c Aug2014).  The 'swpackage'
           utility will generate extended headers on an as needed basis when the
           --format=pax is used.  Support for POSIX ACL and SELinux attributes is
           planned.

           The entirety of the output byte stream is a single valid file of one
           the formats mentioned above.

           The swbis implementation writes its output to stdout.  The default
           output block size is 10240 bytes.  The last block is not padded and
           therefore the last write(2) may be a short write.  The selected block
           size does not affect the output file contents.

           The swbis implementation is biased, in terms of capability and default
           settings, to the tar format.  Package signing is only supported in tar
           format.

    SWPACKAGE INPUT FILE FORMAT
           The input file is called a product specification file or PSF.  It
           contains information to direct swpackage and information that is
           package meta-data [that is merely transferred unchanged into the global
           INDEX file].

           A PSF may contain object keywords, attributes (keyword/value pairs) and
           Extended Definitions (described below).	An object keyword connotes a
           logical object (i.e. software structure) supported by the standard.  An
           object keyword does not have a value field after it, as it contains
           Attributes and Extended Definitions.  An attribute keyword conotes an
           attribute which is always in the form of a keyword/value pair.

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

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

           The file syntax is the same as a INDEX, or INFO file.  A PSF may
           contain all objects defined by the standard as well as extended
           definitions.

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

       EXTENDED DEFINITIONS
           A Product Specification File (PSF) can contain Extended Definitions in
           the fileset, product or bundle software definitions.  They would have
           the same level or containment relationship as a file or control_file
           definition in the same contaning object.

           Extended Definitions represent a minimal, expressive form for
           specifying files and file attributes.  Their use in a PSF is optional
           in that an equivalent PSF can be constructed without using them,
           however, their use is encouraged for the sake of brevity and
           orthogonality.

           The swbis implementation requires that no [ordinary] attributes appear
           after Extended Definitions in the containing object, and, requires that
           Extended Definitions appear before logically contained objects.	That
           is, the parser uses the next object keyword to syntacticly and
           logically terminate the current object even if the current object has
           logically contained objects.

       o  Extended Control File Definitions
    	    checkinstall  source  [path]
    	    preinstall	  source  [path]
    	    postinstall	  source  [path]
    	    verify	  source  [path]
    	    fix		  source  [path]
    	    checkremove	  source  [path]
    	    preremove	  source  [path]
    	    postremove	  source  [path]
    	    configure	  source  [path]
    	    unconfigure	  source  [path]
    	    request	  source  [path]
    	    unpreinstall  source  [path]
    	    unpostinstall source  [path]
    	    space	  source  [path]
    	    control_file  source  [path]

           The source attribute defines the location in distributors's development
           system where the swpackage utility will find the script.	 The keyword
           is the value of the tag attribute and tells the utilities when to
           execute the script.  The path attribute is optional and specifies the
           file name in the packages distribution relative to the
           control_directory for software containing the script. If not given the
           tag value is used as the filename.

       o  Directory Mapping
    	  directory  source  [destination]

           Applies the source attribute as the directory under which the
           subsequently listed files are located.  If destination is defined it
           will be used as a prefix to the path (implied) file definition.	source
           is typically a temporary or build location and dest is its unrealized
           absolute pathname destination.

       o  Recursive File Definition
    	 file *

           Specifies every file in current source directory.  The directory
           extended definition must be used before the recursive specification.

       o  Explicit File Definition
    	 file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]

           source

    	      source defines the pathname of the file to be used as the source
    	      of file data and/or attributes.  If it is a relative path, then
    	      swpackage searches for this file relative to the the source
    	      argument of the directory keyword, if set.  If directory keyword
    	      is not set then the search is relative to the current working
    	      directory of the swpackage utility's invocation.

    	      All attributes for the destination file are taken from the
    	      source file, unless a file_permissions keyword is active, or the
    	      -m, -o, or -g options are also included in the file
    	      specification.

           path

    	      path defines the destination path where the file will be created
    	      or installed.  If it is a relative path, then the destination
    	      path of the of the directory keyword must be active and will be
    	      used as the path prefix.	If path is not specified then source
    	      is used as the value of path and directory mapping applied (if
    	      active).

           -t type

    	      type may one of 'd' (directory), or  'h' (hard link), or 's'
    	      (symbolic link).

    	      -t d  Create a directory.
    	      If path is not specified source is used as the path attribute.

    	      -t h  Create a hard link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

    	      -t s  Create a symbolic link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

           -m mode

    	      mode defines the octal mode for the file.

       o  Default Permission Definition
    	 file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]

           Applies to subsequently listed file definitions in a fileset.  These
           attributes will apply where the file attributes were not specified
           explicitly in a file definition.	 Subsequent file_permissions
           definitions simply replace previous definitions (resetting all the
           options).

           To reset the file_permission state (i.e. turn it off) use one of the
           following:
    	   file_permissions ""
    	    or the preferred way is
    	   file_permissions -u 000

       o  Excluding Files
    	  exclude source

           Excludes a previously included file or an entire directory.

       o  Including Files
    	  include <filename

           The contents of filename may be more definitions for files.  The syntax
           of the included file is PSF syntax.

       SWBIS PSF CONVENTIONS
           This section describes attribute usage and conventions imposed by the
           swbis implementation.  Not all attributes are listed here.  Those that
           are have important effects or particular interest.

       o Distribution Attributes
           The standard defines a limited set of attributes for the distribution
           object.	An expanded set is suggested by the informative annex however
           a conforming implementation is not required act on them.	 The reason
           for this is a distribution may be acted upon by a conforming utility in
           such a way that attributes of the distribution become invalid.  For
           this reason, some attributes that refer to an entire "package" [in
           other package managers] are referred from the product object and attain
           their broadened scope by the distributor's convention that their
           distribution contains just one product.

           For example, the package NAME and VERSION are referred from the product
           tag and revision, not the distribution's.  This convention supports
           multiple products in a distribution and is consistent with the
           standard.

           tag

    	      tag is the short, file system friendly, name of the
    	      distribution.  Providing a distribution tag is optional.	The
    	      swbis implementation will use this as the [single] path name
    	      prefix if there is no distribution.control_directory attribute.
    	      A distribution tag attribute and swpackage's response to it is
    	      an implementation extension.  The leading package path can also
    	      be controlled with the ''-W dir'' option.

           control_directory

    	      control_directory, in a distribution object, is the constant
    	      leading package path.  Providing this attribute is optional.  A
    	      distribution control_directory attribute and swpackage's
    	      response to it is an implementation extension.  The leading
    	      package path can also be controlled with the ''-W dir'' option.
    	      This attribute will be generated by swpackage if not set in a
    	      PSF.

       o Bundle Attributes
           A bundle defines a collection of products whether or not the
           distribution has all the products present.

           tag

    	      tag is the short, file system friendly, name of the bundle.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  If it is not
    	      present the product tag is used.

       o Product Attributes
           A product defines the software product.

           tag

    	      tag is the short, file system friendly, name of the product.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  It is required.
    	      The swbis implementation uses it in a way that is analogous to
    	      the RPMTAG_NAME attribute, namely as the public recognizable
    	      name of the package.

           control_directory

    	      Is the directory name in the distribution under which the
    	      product contents are located.  This value has no affect on the
    	      installed software catalog.  If it is not given in a PSF then
    	      the tag is used.

           revision

    	      Is the product revision.	It should not contain a "RELEASE"
    	      attribute part or other version suffix modifiers.	 This value is
    	      used by the swbis implementation as a path name component in the
    	      installed software catalog.  It is required by swinstall.

           vendor_tag

    	      This is a short identifying name of the distributor that
    	      supplied the product and may associate (refer to) a vendor
    	      object from the INDEX file that has a matching tag attribute.
    	      This attribute is optional.  This attribute value should strive
    	      to be unique among all distributors. The swbis implementation
    	      modifies the intended usage slightly as a string that strives to
    	      be globally unique for a given product.tag and product.revision.
    	      In this capacity it serves to distinguish products with the same
    	      revision and tag from the same or different distributor.	It
    	      most closely maps to the RPMTAG_RELEASE or "debian_revision"
    	      attributes.  It is one of the version distinguishing attributes
    	      of a product specified by the standard.  It is transfered into
    	      the installed_software catalog (not as a path name component) by
    	      swinstall.  If this attribute exists there should also be a
    	      vendor object in the PSF in the distribution object that has
    	      this tag.	 This attribute is assigned the value of
    	      RPMTAG_RELEASE by swpackage when translating an RPM.

           architecture

    	      This string is one of the version attributes.  It is used to
    	      disambiguate products that have the same tag, revision and
    	      vendor_tag.  It is not used for determining a products
    	      compatibility with a host.  The form is implementation defined.
    	      swbis uses the output of GNU config.guess as the value of this
    	      string.  A wildcard pattern should not be used.  The canonical
    	      swbis architecture string can be listed with swlist. For example

    	      swlist -a architecture @ localhost

    	       Here are some example outputs from real systems.

    		  System      `uname -srm`		architecture
    	      Red Hat 8.0:  Linux 2.4.18 i686	     i686-pc-linux-gnu
    	      OpenSolaris:  SunOS 5.11 i86pc	     i386-pc-solaris2.11
    	      NetBSD 3.1:   NetBSD 3.1 i386	     i386-unknown-netbsdelf3.1
    	      Red Hat 4.1:  Linux 2.0.36 i586	     i586-pc-linux-gnulibc1
    	      Debian 3.1:   Linux 2.6.8-2-386 i686   i686-pc-linux-gnu

           os_name os_release os_version machine_type

    	      These attributes are used to determine compatibility with a
    	      host.  They correspond to the uname attributes defined by
    	      POSIX.1.	If an value is nil or non-existent it is assumed to
    	      match the host.  All attributes must match for there to be
    	      compatibility.  Distributors may wish to make these values a
    	      shell pattern in their PSF's so to match the intended collection
    	      of hosts.	 swbis uses fnmatch (with FLAGS=0) to determine a
    	      match.

       o Fileset Attributes
           A fileset defines the fileset.

           tag

    	      tag is the short, file system friendly, name of the fileset.  It
    	      is required although selection of filesets is  not yet supported
    	      therefore the end user will have little to do with the fileset
    	      tag.

           control_directory

    	      Is the directory name in the product under which the fileset
    	      contents are located.  This value has no affect on the installed
    	      software catalog.	 If it is not given in a PSF then the tag is
    	      used.

       o Example Source Package PSF
           This PSF packages every file is current directory. It uses nil control
           directories so the package structure does not change relative to a
           vanilla tarball.

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING
    	vendor
    	  the_term_vendor_is_misleading false
    	  tag fooware
    	  title fooware Consultancy Services, Inc.
    	  description ""
    	vendor
    	  the_term_vendor_is_misleading true
    	  tag myfixes1
    	  title Bug fixes, Set 1
    	  description "a place for more detailed description"
    	product
    	  tag fooit
    	  control_directory ""
    	  revision 1.0
    	  vendor_tag myfixes1  # Matches the vendor object above
    	fileset
    	   tag fooit-SOURCE
    	   control_directory ""
    	   directory .
    	   file *
    	   exclude catalog

       o Example Runtime (Binary) Package PSF
           This is a sample PSF for a runtime package.  It implies multiple
           products (e.g. sub-packages) using the bundle.contents attribute.
           Since the bundle and product tags exist in a un-regulated namespace and
           are seen by end users they should be carefully chosen.	Note that the
           bundle and product have the same tag which may force downstream users
           to disambiguate using software selection syntax such as fooit,bv=* or
           fooit,pv=* .

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING

    	    vendor
    	       the_term_vendor_is_misleading false
    	       tag fooware
    	       title fooware Consultancy Services, Inc.
    	       description "Provider of the programs
    	that do everything"

    	    vendor
    	       the_term_vendor_is_misleading true
    		tag fw0
    		title fooware fixes
    		description "More fixes from the fooware users"

           #  Bundle definition:  Use a bundle
    	    bundle
    		tag fooit
    		vendor_tag fooware
    		contents fooit,v=fw0 fooit-devel fooit-doc

           #  Product definition:
    	    product
    		tag fooit   # This is the package name
    		revision 1.0 # This is the package version
    		vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
    		postinstall scripts/postinstall
    	    fileset
    		 tag fooit-RUN
    		 file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
    		 file src/fooit /usr/bin/fooit

    APPLICABLE STANDARDS
           POSIX.1, IEEE Std 1387.2-1995 (Identical to ISO 15068-2:1999), Open
           Group CAE C701.

    SEE ALSO
    	XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm
    	info swbis
    	sw(5)
    	swpackage(8)
    	swbisparse(1) -- An implementation extension parser utility.

    IDENTIFICATION
    	Copyright (C) 2004,2005 Jim Lowe
    	Version: 1.13.1
    	Last Updated: 2006-07-01
    	Copying Terms: GNU Free Documentation License

    BUGS
           None

    								  swpackage(5)

Next: swpackage.5 in one text file, Previous: (swbis_sw), Up: Command Reference

### sw.5 in one text file

    sw(5)			      File Formats Manual			 sw(5)

    NAME
           sw — POSIX Software Packaging

    SYNOPSIS
           Software Packaging Layout
           Software Definitions
           Software Selections
           Extended Definitions
           Distributor Keywords
           Package Security
           Software Definition Files: INFO, INDEX, PSF
           Example Package

    SOFTWARE PACKAGING LAYOUT
           A package may exist in two forms: as a directory in a file system, or a
           serial access tar or cpio archive file.	A package consists of two main
           sections: 1) the exported catalog structure, and, 2) the software file
           storage structure.  Each section may contain path name components which
           serve to segregate distribution, product and fileset objects.

           Shown below is an example with one (1) product and one (1) fileset.

    	<path>/
    	<path>/catalog/
    	<path>/catalog/INDEX
    	<path>/catalog/<dfiles>
    	<path>/catalog/<dfiles>/...
    	<path>/catalog/<prod_dir>/
    	<path>/catalog/<prod_dir>/<pfiles>/INFO
    	<path>/catalog/<prod_dir>/<pfiles>/...
    	<path>/catalog/<prod_dir>/<fileset_dir>/
    	<path>/catalog/<prod_dir>/<fileset_dir>/INFO
    	<path>/catalog/<prod_dir>/<fileset_dir>/...
    	<path>/catalog/<prod_dir>/<fileset_dir>/<script>
    	<path>/<prod_dir>/
    	<path>/<prod_dir>/<fileset_dir>/
    	<path>/<prod_dir>/<fileset_dir>/<distribution_files>
    	<path>/<prod_dir>/<fileset_dir>/<distribution_files>/...

           The exported catalog structure consists of the files with pathnames
           that begin <path>/catalog.  Note that catalog is not a legal prod_dir
           name. Also, "dfiles", and "pfiles" should not be used as control
           directory names, they are the default names for the Distribution and
           Product files directories.  The dfiles and pfiles defaults are commonly
           accepted.

           The order of files in a serial access archive is specified and shown
           above.  The order of products and filesets within a product is not
           specified, although they must be grouped together.  Notably, the INDEX
           file is the first regular file in the package, followed by the <dfiles>
           directory.  For each product, the <prod_dir> is followed immediately by
           the <prod_dir>/<pfiles> directory.

       Minimal Package Layout
           To support extant usage of tar archives, this implementation supports a
           minimal package layout.	The layout is non-intrusive to the current
           practice of extracting a 'binary' package in the '/' directory where
           <path>/ is nil and, likewise to 'source' packages where <path> is
           typically the package name and version.	The use of nil control
           directories is not attested to in the POSIX standard.

    	<path>/
    	<path>/catalog/
    	<path>/catalog/INDEX
    	<path>/catalog/dfiles/
    	<path>/catalog/dfiles/INFO
    	<path>/catalog/dfiles/...
    	<path>/catalog/pfiles/INFO
    	<path>/catalog/pfiles/...
    	<path>/catalog/INFO
    	<path>/<distribution_files>/...

           In this layout a single product and fileset have control_directory
           attributes specified as an empty string.

       Distribution Files
           catalog/<dfiles>/...

           <dfiles> is the value of the dfiles attribute and the default value is
           "dfiles".  This directory can store an INDEX file or INFO file
           pertaining to the distribution.	It can also store an attribute of the
           distribution as a separate file where file name is the name of the
           attribute and the file contents the value.

       Product Files
           catalog/<prod_dir>/<pfiles>/...

           <pfiles> is the value of the pfiles attribute and the default value is
           "pfiles".  This directory can store an INFO file pertaining to the
           product control_files,  control scripts defined in the INFO file, and
           all other distributor-defined control_files.  It can also store an
           attribute of the product as a separate file.

       Fileset Files
           catalog/<prod_dir>/<fileset_dir>/...

           This directory contains information in the same form as does the
           Product Files although pertaining to the fileset.

       Control Directory Names
           The <prod_dir>/<fileset_dir> names are the values of the
           control_directory attribute for the product and fileset respectively.
           The default value is the value of the tag attribute.  <prod_dir> must
           be unique within a distribution and <fileset_dir> must be unique within
           a product.

       File Storage
           <prod_dir>/<fileset_dir>/<distribution_files>/...

           The listing of control directories in the exported catalog structure is
           repeated and files of the distribution appear under these directories
           in a location determined by the metadata.

           The standard does not require that files that are not regular files
           appear in the storage section.

    SOFTWARE DEFINITIONS
           The Software Definitions are metadata representations of the objects
           and attributes recognized by the standard.  The right hand column in
           each definition shows the default attribute value.  The defining
           standard for each attribute is indicated as a comment (leading '#'
           sign) if it is not IEEE-1387.2,	other defining standards are XDSA C701
           (C701), and, this implementation (impl.).

       Host Definition
    	host
    	  hostname     hostname	      None
    	  os_name      os_name	      None
    	  os_release   os_release     None
    	  os_version   os_version     None
    	  machine_type machine_type   None

           The host definition was attested to only in the informative annex of
           the standard.  An implementation may chose to define this class.

           A host object can contain a distribution, or installed_software object.

       Distribution Definition
    	distribution
    	  layout_version layout_version	 1.0
    	  path		 path		 Implementation Defined
    	  dfiles	 dfiles		 dfiles
    	  pfiles	 pfiles		 pfiles
    	  uuid		 uuid		 Empty string

           The path attribute is not in a PSF nor INDEX files.  A PSF does not
           contain a uuid attribute.  An INDEX file will contain a layout_version
           attribute as the first attribute.

           A distribution object can contain bundles, products, and, media in the
           form of software definitions.

           The following attributes are recognized as valuable by the Informative
           Annex of POSIX.7.2.

    	  tag		     tag		Empty string
    	  title		     title		Empty string
    	  description	     description	Empty string
    	  revision	     revision		Empty string
    	  media_type	     media_type		Empty string
    	  copyright	     copyright		Empty string
    	  create_time	     create_time	Empty string
    	  number	     number		Empty string
    	  architecture	     architecture	Empty string

           The following attributes are recognized by this implementation.

    	  signature	     < pathname	 None	# impl.
    	  sig_header   < pathname  None	  # impl.
    	  sha1sum	     < pathname	 None	# impl.
    	  sha512sum	      < pathname  None	 # impl.
    	  md5sum	     < pathname	 None	# impl.
    	  adjunct_md5sum     < pathname	 None	# impl.
    	  files		     < pathname	   None	 # impl.
    	  control_directory  control_directory	    Empty string   # impl.
    	  owner		     name			    root   # impl.
    	  group		     name			    root   # impl.
    	  mode		     mode			    0755    # impl.
    	  signer_pgm	     utility_name		    GPG	   # impl.
    	  signer_pgm_version version			    1	 # impl.
    	  tar_format_emulation_options program_options		# impl.
    	  tar_format_emulation_utility software spec		# impl.

           The url attribute is the universal record locator of the packager
           qualified vendor.  The control_directory attribute in the distribution
           object appears as the <path> leading directory path in the a serial
           archive package.	 The owner, group, and mode attributes control the
           file attributes of the single path name prefix.	The signature,
           sig_header, md5sum, and adjunct_md5sum attributes are described below
           and are stored as separate files in the dfiles directory. The
           tar_format_emulation_* options define the GNU tar version and format
           options that the archive file mimics, these attributes are used by the
           'checkdigest' script.

       Installed_software Definition
    	installed_software
    	  layout_version layout_version	 1.0
    	  path		 path		 Implementation Defined
    	  dfiles	 dfiles		 dfiles
    	  pfiles	 pfiles		 dfiles
    	  catalog	 catalog	 Undefined
    	  install_time	 install_time	 Undefined	 # impl.

           A software object can be listed (written to stdout) in the form of an
           INDEX file by the swlist utility.

       Media Definition
    	media
    	  sequence_number sequence_number  1

           An INDEX file must contain the sequence_number attribute if the
           distribution spans multiple media.

       Vendor Definition
    	vendor
    	  the_term_vendor_is_misleading	 true		       True or False  #impl
    	  tag	      tag	    Empty string
    	  title	      title	    Empty string
    	  description description   Empty string
    	  qualifier   qualifier	    Empty string  # impl.
    	  url	      url	    Empty string  # impl.
    	  vendor_tag  tag	    Empty string  # impl.

           The tag attribute is required.  The the_term_vendor_is_misleading is
           required in a PSF file to avert a (harmless) warning, please use it.
           It exists to allow persons, for example, who are distributors (of
           existing free software) to qualify themselves away from the
           connotations of a "vendor" which has specific meaning not applicable to
           a free software distributor.  A INDEX and PSF files can contain vendor
           definitions.  The vendor_tag attribute contains the vendor.tag of the
           upstream distributor.  The qualifier attribute value may be one of:
           seller, author, packager, maintainer.  A distribution may have more
           than one vendor definition.  They may form a chain of references from
           the product.vendor_tag to the last vendor referred to by the
           vendor.vendor_tag attributes.

       Bundle Definition
    	bundle
    	  tag	       tag    architecture architecture	   Empty string
    	  location     location	       <bundle.directory>
    	  qualifier    qualifier       Empty string
    	  revision     revision	       Empty string
    	  vendor_tag   vendor_tag      Empty string
    	  create_time  create_time     None
    	  description  description     Empty string
    	  contents     contents	       Empty string
    	  copyright    copyright       Empty string
    	  directory    directory       Empty string
    	  instance_id  instance_id     1
    	  is_locatable is_locatable    true
    	  layout_version layoyt_version	 1.0
    	  machine_type machine_type    Empty string
    	  mod_time     mod_time	       Empty string
    	  number       number	       Empty string
    	  os_name      os_name	       Empty string
    	  os_release   os_release      Empty string
    	  os_version   os_version      Empty string
    	  size	       size	       Empty string
    	  title	       title	       Empty string
    	  category_tag category_tag    Empty list or patch  # C701
    	  is_patch     is_patch	       false		    # C701

           The tag and contents attributes are required in INDEX and PSF files.
           The size attribute is not allowed in either file. The value of size is
           generated dynamically.  An INDEX file will contain a instance_id
           attribute.  Bundle definitions for distributions will not contain
           either the location or qualifier, installed_software objects may
           contain these attributes.

       Product Definition
    	product
    	  tag		    tag		      None
    	  architecture	    architecture      Empty string
    	  location	    location	      <product.directory>
    	  qualifier	    qualifier	      Empty string
    	  revision	    revision	      Empty string
    	  vendor_tag	    vendor_tag	      Empty string
    	  all_filesets	    all_filesets      Empty list
    	  control_directory control_directory <product.tag>
    	  copyright	    copyright	      Empty string
    	  create_time	    create_time	      None
    	  directory	    directory	      /
    	  description	    description	      Empty string
    	  instance_id	    instance_id	      1
    	  is_locatable	    is_locatable      true
    	  postkernel	    postkernel	      Implemen. defined
    	  layout_version    layout_version    1.0
    	  machine_type	    machine_type      Empty string
    	  number	    number	      Empty string
    	  os_name	    os_name	      Empty string
    	  os_release	    os_release	      Empty string
    	  os_version	    os_version	      Empty string
    	  mod_time	    mod_time	      None
    	  size		    size	      None
    	  title		    title	      title
    	  category_tag	    category_tag      Empty list # C701
    	  is_patch	    is_patch	      false	 # C701
    	  copyrighters	    copyrighters      None	 # impl.
    	  build_root	    build_root	      None	 # impl.
    	  build_host	    build_host	      None	 # impl.
    	  source_package    source_package    None	 # impl.
    	  source_rpm	    source_rpm	      None	 # impl.
    	  all_patches	    all_patches	      None	 # impl.
    	  url		    url		      None	 # impl.
    	  rpm_provides	    rpm_provides      None	 # impl.
    	  change_log	    change_log	      None	 # impl.

           The tag and control_directory attributes are required.  The size
           attribute is not allowed in either file. The value of size is generated
           dynamically.  An INDEX file will contain a instance_id attribute.  A
           product object can contain control_files, files, and, subproducts in
           the form of software definitions.

           The product.vendor_tag refers to the downstream distributor.  This
           value is be the analogous to the RPMTAG_RELEASE or debian_release
           attributes.  The original upstream author's package, for example, would
           not use this attribute because that package would not have a release
           part in its name, but could (or should) provide a vendor object in the
           PSF.

           The architecture attribute contains an implementation defined name
           describing the architecture.  This attribute may be a pattern.  The
           swbis implementation uses the output of GNU config.guess
           (timestamp=2007-01-15) as the string to be matched by this pattern.

       Category Definition
    	category
    	  tag		tag	       None		# C701
    	  title		title	       Empty string	# C701
    	  description	description    Empty string	# C701
    	  revision	revision       Empty string	# C701

           The Category definition describes attributes of products and bundles
           related to its category. If is_patch is "true" then category.tag must
           equal "patch".

       Subroduct Definition
    	subproduct
    	  tag		tag	       None
    	  create_time	create_time    None
    	  description	description    Empty string
    	  mod_time	mod_time       None
    	  size		size	       None
    	  title		title	       Empty string
    	  contents	contents       Empty list
    	  category_tag	category_tag   Empty list   # C701
    	  is_patch	is_patch       false	    # C701

           The tag and contents attributes are required.

       Fileset Definition
    	fileset
    	  tag		    tag		      None
    	  create_time	    create_time	      None
    	  mod_time	    mod_time	      None
    	  control_directory control_directory <fileset.tag>
    	  corequisites	    corequisites      Empty list
    	  description	    description	      Empty string
    	  exrequisites	    exrequisites      Empty list
    	  is_kernel	    is_kernel	      false
    	  is_locatable	    is_locatable      true
    	  is_reboot	    is_reboot	      false
    	  location	    location	      <product.directory>
    	  media_sequence_number media_sequence_number 1
    	  prerequisites	    prerequisites     Empty list
    	  revision	    revision	      None
    	  size		    size	      None
    	  state		    state	      None
    	  title		    title	      Empty string
    	  is_sparse	    is_sparse	     "false"	    # C701
    	  is_patch	    is_patch	     "false"	    # C701
    	  category_tag	    category_tag      empty list    # C701
    	  ancestor	    ancestor	      <product.tag>,ver_id # C701
    	  applied_patches   applied_patches   empty list    # C701
    	  patch_state	    patch_state	      applied or,   # C701
    						  committed or,
    						    superseded, (no default).
    	  saved_files_directory	 saved_files_directory None # C701
    	  supersedes	   supersedes	       None	    # C701
    	  superseded_by	   superseded_by       None	    # C701

           The tag and control_directory attributes are required.  A PSF should
           not contain the location, media_sequence_number, size, or state
           attributes.  A fileset object can contain control_files, files, in the
           form of software definitions.

       File Definition
    	file
    	  path		     path		None
    	  cksum		    cksum	      None
    	  compressed_cksum  compressed_cksum  None
    	  compressed_size    compressed_size	None
    	  compression_state  compression_state	uncompressed
    	  compression_type   compression_type	Empty string
    	  revision	     revision		Empty string
    	  size		     size		None
    	  source	     source		None
    	  gid		     gid		Undefined
    	  group		     group		Empty string
    	  is_volatile	     is_volatile	false
    	  link_source	     link_source	None
    	  major		     major		None
    	  minor		     minor		None
    	  mode		     mode		None
    	  mtime		     mtime		None
    	  owner		     owner		Empty string
    	  type		     type		f
    	  uid		     uid		undefined
    	  archive_path	  archive_path	  empty string	  # C701
    	  md5sum	  md5sum      empty string    # impl.
    	  sha1sum	  sha1sum      empty string    # impl.
    	  sha512sum	  sha512sum	 empty string	 # impl.
    	  rdev		  rdev		  empty string	  # impl.
    	  rpm_fileflags	  rpm_fileflags	  empty string	  # impl.

           A PSF must contain source attribute.  A source  attribute in an INFO
           will be ignored.	 A PSF should not contain the cksum, compressed_cksum,
           compressed_size, compression_state, compression_type, or size
           attributes.

       Control File Definition
    	control_file
    	  tag		     tag		None
    	  cksum		    cksum	      None
    	  compressed_cksum  compressed_cksum  None
    	  compressed_size    compressed_size	None
    	  compression_state  compression_state	uncompressed
    	  compression_type   compression_type	Empty string
    	  revision	     revision		Empty string
    	  size		     size		None
    	  source	     source		None
    	  path		     path		None
    	  interpreter	     interpreter	sh
    	  result	     result		none

           A control_file defines a control script such as those listed below (see
           Extended Control File Definitions) or an attribute stored as a file.

    SOFTWARE SELECTIONS
           The Software Selections provide a means to specify and select (possibly
           with a shell matching pattern) specific Software objects.  A selection
           is made using a software spec.  A software spec may not contain white
           space (a list of multiple selections is white space delimited).	A
           software spec consists of tag values and	 version_ids.  Multiple tags
           are '.' (dot) delimited with the leftmost specifying the broadest (most
           general) software object such as a bundle or product and the rightmost
           being most specific (The swbis implementation does not support fileset
           tags in a software spec). The tags may be followed by nothing, or a
           comma and one or more Version Identifiers which are ',' comma
           delimited.

           Dependency Specs are software specs.

       Version Identifiers
           Version Identifiers specify specific attributes of a software object.
           There are five (5) specified. They are signified by a single letter:
           r,a,v,l,q.  An implementation may support additional ones and may
           support qualification to a specific object type by prefixing a 'p' or
           'b' or 'f' for bundle, product, or fileset respectively.	 The value of
           the attribute follows an equals sign '=', or in the case of a revision
           id, a relational operator.

    	Letter	   Attribute
    	  r    revision	  r<relop>revsion
    				    # A relop may be ==,<,>,<=,>=
    	  v    vendor_tag    v=vendor_tag
    	  q    qualifier     q=qualifier
    	  l    location	     l=location
    	  a    architecture  a=arch

           Implementation Extension Version Ids are the following:

    	Letter	   Attribute
    	  i    catalog_instance_id   i=number

    	The catalog instance_id is a directory in the installed software
           catalog that distinguishes installed instances of packages with the
           same name and revision but at different locations.

       Example Software Specs
    	   emacs,r==21.2
    	   kde.kdegames # This assumes that 'kde' was specified as the bundle
    			# in the kdegames package
    	   foobar,r>1.0,v=tycoon003
    	   somepackage,r>1.0,r<=1.3  # revision is the product revision by default
    	   somepackage,pr>1.0,pr<=1.3  # explicitly specify revision is the product revision

    DEPENDENCY SPECS
           A dependency spec is a software spec.  There are three types:
           prerequisites, exrequisites, corequisites.  These attributes apply to
           the fileset and are placed in the fileset object in a PSF file.	A
           prerequisites is something that must be installed, and a exrequisites
           is something that must not be installed.	 A corequisites is something
           that must be installed with, corequisites are not supported at this
           time.  prerequisites map to RPMTAG_REQUIRENAME, RPMTAG_REQUIREVERSION,
           and RPMTAG_REQUIREFLAGS attributes.

       Dependency Spec Examples
    	  # Alternation	 Require a package named foo1 or foo2
    	  prerequisite	 foo1|foo2

    	  # Require a package named foo1 and foo2
    	  prerequisite	 foo1 foo2

    	  # multiple prerequisite keywords can be used
    	  prerequisite	foo1
    	  prerequisite	foo2

    	  # Require a revision range and a certain vendor_tag
    	  prerequisite	foo1,r>2,r<3,v=mydist*

    EXTENDED DEFINITIONS
           A Product Specification File (PSF) can contain Extended Definitions in
           the fileset, product or bundle software definitions.  They would have
           the same level or containment relationship as a file or control_file
           definition in the same contaning object.

           Extended Definitions represent a minimal, expressive form for
           specifying files and file attributes.  Their use in a PSF is optional
           in that an equivalent PSF can be constructed without using them,
           however, their use is encouraged for the sake of brevity and
           orthogonality.

           The swbis implementation requires that no [ordinary] attributes appear
           after Extended Definitions in the containing object, and, requires that
           Extended Definitions appear before logically contained objects.	That
           is, the parser uses the next object keyword to syntacticly and
           logically terminate the current object even if the current object has
           logically contained objects.

       o  Extended Control File Definitions
    	    checkinstall  source  [path]
    	    preinstall	  source  [path]
    	    postinstall	  source  [path]
    	    verify	  source  [path]
    	    fix		  source  [path]
    	    checkremove	  source  [path]
    	    preremove	  source  [path]
    	    postremove	  source  [path]
    	    configure	  source  [path]
    	    unconfigure	  source  [path]
    	    request	  source  [path]
    	    unpreinstall  source  [path]
    	    unpostinstall source  [path]
    	    space	  source  [path]
    	    control_file  source  [path]

           The source attribute defines the location in distributors's development
           system where the swpackage utility will find the script.	 The keyword
           is the value of the tag attribute and tells the utilities when to
           execute the script.  The path attribute is optional and specifies the
           file name in the packages distribution relative to the
           control_directory for software containing the script. If not given the
           tag value is used as the filename.

       o  Directory Mapping
    	  directory  source  [destination]

           Applies the source attribute as the directory under which the
           subsequently listed files are located.  If destination is defined it
           will be used as a prefix to the path (implied) file definition.	source
           is typically a temporary or build location and dest is its unrealized
           absolute pathname destination.

       o  Recursive File Definition
    	 file *

           Specifies every file in current source directory.  The directory
           extended definition must be used before the recursive specification.

       o  Explicit File Definition
    	 file [-t type] [-m mode] [-o owner[,uid]] [-g group[,gid]] [-n] [-v] source [path]

           source

    	      source defines the pathname of the file to be used as the source
    	      of file data and/or attributes.  If it is a relative path, then
    	      swpackage searches for this file relative to the the source
    	      argument of the directory keyword, if set.  If directory keyword
    	      is not set then the search is relative to the current working
    	      directory of the swpackage utility's invocation.

    	      All attributes for the destination file are taken from the
    	      source file, unless a file_permissions keyword is active, or the
    	      -m, -o, or -g options are also included in the file
    	      specification.

           path

    	      path defines the destination path where the file will be created
    	      or installed.  If it is a relative path, then the destination
    	      path of the of the directory keyword must be active and will be
    	      used as the path prefix.	If path is not specified then source
    	      is used as the value of path and directory mapping applied (if
    	      active).

           -t type

    	      type may one of 'd' (directory), or  'h' (hard link), or 's'
    	      (symbolic link).

    	      -t d  Create a directory.
    	      If path is not specified source is used as the path attribute.

    	      -t h  Create a hard link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

    	      -t s  Create a symbolic link.
    	      path and source are specified.  source is used as the value of
    	      the link_source attribute, and path is the value of the path
    	      attribute.

           -m mode

    	      mode defines the octal mode for the file.

       o  Default Permission Definition
    	 file_permissions [-m mode] [-u umask] [-o [owner[,]][uid]] [-g [group[,]][gid]]

           Applies to subsequently listed file definitions in a fileset.  These
           attributes will apply where the file attributes were not specified
           explicitly in a file definition.	 Subsequent file_permissions
           definitions simply replace previous definitions (resetting all the
           options).

           To reset the file_permission state (i.e. turn it off) use one of the
           following:
    	   file_permissions ""
    	    or the preferred way is
    	   file_permissions -u 000

       o  Excluding Files
    	  exclude source

           Excludes a previously included file or an entire directory.

       o  Including Files
    	  include <filename

           The contents of filename may be more definitions for files.  The syntax
           of the included file is PSF syntax.

    DISTRIBUTOR KEYWORDS
           A software definition file (INFO, INDEX or psf) may contain keywords
           not recognized by the standard.	Such keywords will be parsed as an
           attribute keyword, that is as an attribute of the containing object
           (keyword) software definition.

    PACKAGE SECURITY
           The Package Security Attributes are distribution attributes stored as
           separate files.	They are implementation extensions.  They consist of
           archive digests, catalog signature, catalog signature header, and
           individual file md5, sha1, and sha512 digests.

       Archive Digests
           md5sum, sha1sum, and sha512sum are the md5 and sha1 and sha512 digests
           (ascii representations) of the leading package directories that do not
           have the catalog pathname component followed by the software file
           storage structure portion of the uncompressed serial access package
           file including all archive format trailer blocks.

    	      <path>/catalog/<dfiles>/md5sum
    	      <path>/catalog/<dfiles>/sha1sum
    	      <path>/catalog/<dfiles>/sha512sum

       Adjunct Md5 Digest
           adjunct_md5sum is the same as the md5sum excluding symbolic links.  If
           a package does not contain symbolic links the md5sum and adjunct_md5sum
           will be identical.

    	      <path>/catalog/<dfiles>/adjunct_md5sum

           Explanation: This attribute is called 'adjunct' because it is a digest
           of a subset of the files in the package.	 It exists to facilitate
           verifying file integrity of the directory form of a package in an
           environment where the modification time of symbolic link files are not
           preserved from the serial archive by the tar utility or operating
           system.	The ability to verify even the adjunct_md5sum from the
           directory form of the package is dependent on the tar creating utility
           and other attributes of a POSIX.2 environment.

       Catalog Signature Header
           The sig_header file is a ustar header that is identical bit-for-bit to
           the ustar header of the signature file.	It always precedes the
           signature file archive members.

    	      <path>/catalog/<dfiles>/sig_header

           The sig_header protects the tar header of the signature files from
           tampering.  This is required because neither the signature file bytes
           nor the signature tar header are included in the signed data.

       Catalog Signature
           The signature protects the metadata section of the archive.  The
           contents of payload section are only included in the form of a
           crytographic digest.  The sha1 digest is preferred over the md5 digest
           for technical reasons.  If the metadata section does not contain the
           payload section digests then there is no way to verify the payload from
           the signature.

    	      <path>/catalog/<dfiles>/signature

           The signed data is the exported catalog structure of the uncompressed
           serial archive package file up to but not including the first byte of
           the software file storage structure followed by two (2) 512 byte null
           blocks if tar format, and no trailer bytes if not tar format.  The
           signature file archive member itself is not included in the signed
           stream, it is intended that the <path>/catalog/<dfiles>/md5sum file is
           included in the signed stream.

           The signature file is ASCII armored.  The last printable character of
           the signature is followed by one or more newline characters (0x0A).
           The total length of the file must match the file size specified in the
           size field of the sig_header file.  The ustar header of every signature
           archive member shall be identical to the sig_header file.  The padded
           size is predetermined [by swpackage] and currently set to be 1024
           octets.	This means the armored sig file has a length limitation of
           1023 octets.

           If multiple signature archive members exist they must follow one
           another in the archive with no other intervening files; and, the same
           sig_header file is the ustar header for all the signature archive
           members.	 A signature archive member, whether alone or one of many, is
           never part of the signed data stream.

       File Digests
           File digests are attributes of the file software definition. They
           appear in the INFO file.
    	      file.cksum
    	      file.md5sum
    	      file.sha1sum
    	      file.sha512sum

           Each file can have none or all of these digests.

    SOFTWARE DEFINITION FILES
           The metadata files, INDEX, INFO and PSF, contain information about the
           software in the form of software definitions.  The INDEX and INFO files
           appear in a package directory structure.	 They are automatically
           generated by the 'swpackage' command.  The location in the directory
           structure indicates the higher level object to which their data
           pertains.  The PSF file does not appear in the package.	It is created
           by a person or program and it directs the action of the swpackage
           utility.	 It is internal data unless released by the distributor.

           The files contain keywords (and values) to represent the attributes
           defined in the standard.	 There are three (3) different keyword types:
           object, attribute, and, extended. The object keyword type has no value
           and there are eleven (11) of these corresponding to the Software
           Definitions defined above: installed_software, distribution, media,
           bundle, vendor, category, product, subproduct, fileset, control_file,
           file.

           Each object keyword is followed by and newline and attributes in the
           form of keyword/value pairs.  Whitespace separates the keyword and
           value.  Whitespace outside of a quoted value is not significant.	 A
           quoted value can span multiple lines.  An object keyword with its list
           of attribute keywords (and values) forms a Software Definition.	A
           Software Definition is terminated by the start of the next Software
           Definition.  Extended keywords (meaning Extended Definitions) only
           appear in a PSF file.

           The order  of objects (i.e Software Definitions) is significant and a
           containment  hierarchy is determined according to parser's grammar.

       Additional Syntax Rules
    	  ·  A '#' (pound) character designates a comment.  A comment may
    	     begin a line or appear at the end of a single line containing the
    	     keyword/value pair.

    	  ·  A value may be quoted by the '"' (double quote) character; and,
    	     multi-line values must be quoted.	Trailing white space from an
    	     unquoted value will be removed.

    	  ·  The order of attributes is not significant although the INDEX
    	     file grammar requires the layout_version attribute appear first
    	     in distribution or installed software object.

    	  ·  The ", #, and, \ characters must be escaped with a backslash (\)
    	     in a quoted value.

    	  ·  If a value begins with a < (less than), the value is interpreted
    	     as a filename whose contents will be treated as a quoted value
    	     although the storage of the attribute will be in the form of a
    	     control file (i.e. a separate file in the control directory).
    	     For INDEX files, the filename is relative to the control
    	     directory in which this attribute is contained.  For PSF files,
    	     the filename is a path on the host.

       Software Definition File Grammar
           A PSF may contain all Software Definitions.  An INDEX file does not
           contain control_file, or file definitions. An INFO file contains only
           control_file, and file definitions.

    	    software_definition_file : INDEX
    				     | INFO
    				     | PSF
    				     ;

    	    PSF :  distribution_definition
    		   swo_contents
    		   ;

    	    INDEX : swo_definition
    		    swo_contents
    		   ;

    	    INFO : fileset_contents
    		   ;

    	    swo_definition : distribution_definition
    			   | installed_software
    			   ;

    	    distribution_definition : distribution
    						media
    				    ;

    	    swo_contents : vendor(s)
    			  | category(s)
    			  | products
    			  | bundles
    			  ;

    	    products : product
    		       product_contents
    		       ;

    	    bundles : bundle
    		       ;

    	    product_contents :	control_files
    	      /* control_files not valid in INDEX file */
    			    | subproducts
    			    |  filesets
    		      ;

    	    filesets : fileset
    	     /* fileset_contents not valid in INDEX file */
    		       fileset_contents
    		       ;

    	    fileset_contents :	control_files
    			     | files
    			     ;

    EXAMPLE PACKAGE
       Layout
    	swm-1.0/catalog
    	swm-1.0/catalog/INDEX
    	swm-1.0/catalog/dfiles
    	swm-1.0/catalog/dfiles/INFO
    	swm-1.0/catalog/dfiles/md5sum
    	swm-1.0/catalog/dfiles/sha1sum
    	swm-1.0/catalog/dfiles/adjunct_md5sum
    	swm-1.0/catalog/dfiles/sig_header
    	swm-1.0/catalog/dfiles/signature
    	swm-1.0/catalog/gsoft_swm
    	swm-1.0/catalog/gsoft_swm/pfiles
    	swm-1.0/catalog/gsoft_swm/pfiles/INFO
    	swm-1.0/catalog/gsoft_swm/pfiles/remove
    	swm-1.0/catalog/gsoft_swm/pfiles/configure
    	swm-1.0/catalog/gsoft_swm/bin
    	swm-1.0/catalog/gsoft_swm/bin/INFO
    	swm-1.0/catalog/gsoft_swm/bin/postinstall
    	swm-1.0/catalog/gsoft_swm/bin/configure
    	swm-1.0/catalog/gsoft_swm/doc
    	swm-1.0/catalog/gsoft_swm/doc/INFO
    	swm-1.0/catalog/gsoft_swm/doc/postinstall
    	swm-1.0/gsoft_swm
    	swm-1.0/gsoft_swm/bin
    	swm-1.0/gsoft_swm/bin/usr/bin/swpackage
    	swm-1.0/gsoft_swm/bin/usr/bin/sw_build
    	swm-1.0/gsoft_swm/doc
    	swm-1.0/gsoft_swm/doc/usr/man/man1/swpackage.1
    	swm-1.0/gsoft_swm/doc/usr/man/man1/sw_build.1

       Hypothetical PSF file
    	distribution
    	  control_directory swm-1.0  #Implementation Extension.
    	  vendor
    	    the_term_vendor_is_misleading  false # True or False
    	    tag greatsoft
    	    title Greatersoft Corporation
    	    description "Greatersoft Corporation, Inc."
    	  product
    	    tag swm
    	    title POSIX 1387 package builder
    	    revision 1.0
    	    control_directory gsoft_swm
    	    vendor_tag greatsoft
    	    description A package building Utility.
    	    machine_type i386
    	    control_file
    		 path remove
    	       source /var/tmp/sw/remove.source
    	    configure /var/tmp/sw/configure.source
    	    fileset
    	       tag bin
    	       control_directory bin
    	       title Executable Files
    	       state available
    		 postinstall /var/tmp/sw/bin/postinstall
    	       configure /var/tmp/sw/bin/configure
    	       file -m 0755 -o root -g root /var/tmp/sw/build/bin/swpackage  \
    			    /usr/bin/swpackage
    	       file -m 0755 -o root -g root /var/tmp/sw/build/bin/sw_build  \
    			    /usr/bin/sw_build
    	  fileset
    	     tag doc
    	     control_directory doc
    	     title Manual Pages
    	     state available
    	     postinstall /var/tmp/sw/bin/postinstall
    	     file -m 0644 -o root -g root /var/tmp/sw/build/man/swpackage.1 \
    		       /usr/man/man1/swpackage.1
    	     file
    		mode 0644
    		owner root
    		group  root
    		source /var/tmp/sw/build/man/sw_build.1
    		path /usr/man/man1/sw_build.1

       INDEX File swm-1.0/catalog/INDEX
    	distribution
    	  layout_version 1.0
    	  tag swm-1.0
    	  uuid 880ccf8b-de2c-4422-bff0-fd686279da73
    	  md5sum < md5sum
    	  adjunct_md5sum < adjunct_md5sum
    	  sig_header < sig_header
    	  signature < signature
    	  media
    	    sequence_number 1
    	  vendor
    	    the_term_vendor_is_misleading  false # True or False
    	    tag greatsoft
    	    title Greatersoft Corporation
    	    description "Greatersoft Corporation, Inc."
    	  product
    	    tag swm
    	    title POSIX 1387 package builder
    	    revision 1.0
    	    instance_id 1
    	    control_directory gsoft_swm
    	    vendor_tag greatsoft
    	    description A package building Utility.
    	    machine_type i386
    	    fileset
    	       tag bin
    	       control_directory bin
    	       size 196643
    	       title Executable Files
    	       state available
    	    fileset
    	       tag doc
    	       control_directory doc
    	       size 19643
    	       title Manual Pages
    	       state available

       INFO File swm-1.0/catalog/dfiles/INFO
    	control_file
    	  path INFO
    	  tag INFO
    	  size 92
    	control_file
    	  path md5sum
    	  tag md5sum
    	  size 36
    	control_file
    	  path adjunct_md5sum
    	  tag adjunct_md5sum
    	  size 36
    	control_file
    	  path sig_header
    	  tag sig_header
    	  size 512
    	control_file
    	  path signature
    	  tag signature
    	  size 512

       INFO File swm-1.0/catalog/gsoft_swm/bin/INFO
    	control_file
    	  path INFO
    	  tag INFO
    	  size 337

    	control_file
    	  path postinstall
    	  type f
    	  size 803
    	  cksum 3928827394
    	  mode 550
    	  uid 0
    	  gid 0
    	  owner root
    	  group root
    	  mtime 739080341

    	control_file
    	  path configure
    	  type f
    	  size 432
    	  cksum 3934546394
    	  mode 550
    	  uid 0
    	  gid 0
    	  owner root
    	  group root
    	  mtime 739340771

    	file
    	  path /usr/bin/swpackage
    	  type f
    	  size 80860
    	  cksum 3929827394
    	  mode 755
    	  uid 0
    	  gid 0
    	  owner root
    	  group root
    	  mtime 739080771

    	file
    	  path /usr/bin/sw_build
    	  type f
    	  size 120860
    	  cksum 9894925524
    	  mode 755
    	  uid 0
    	  gid 0
    	  owner root
    	  group root
    	  mtime 7393808731

    SWBIS PSF CONVENTIONS
           This section describes attribute usage and conventions imposed by the
           swbis implementation.  Not all attributes are listed here.  Those that
           are have important effects or particular interest.

       o Distribution Attributes
           The standard defines a limited set of attributes for the distribution
           object.	An expanded set is suggested by the informative annex however
           a conforming implementation is not required act on them.	 The reason
           for this is a distribution may be acted upon by a conforming utility in
           such a way that attributes of the distribution become invalid.  For
           this reason, some attributes that refer to an entire "package" [in
           other package managers] are referred from the product object and attain
           their broadened scope by the distributor's convention that their
           distribution contains just one product.

           For example, the package NAME and VERSION are referred from the product
           tag and revision, not the distribution's.  This convention supports
           multiple products in a distribution and is consistent with the
           standard.

           tag

    	      tag is the short, file system friendly, name of the
    	      distribution.  Providing a distribution tag is optional.	The
    	      swbis implementation will use this as the [single] path name
    	      prefix if there is no distribution.control_directory attribute.
    	      A distribution tag attribute and swpackage's response to it is
    	      an implementation extension.  The leading package path can also
    	      be controlled with the ''-W dir'' option.

           control_directory

    	      control_directory, in a distribution object, is the constant
    	      leading package path.  Providing this attribute is optional.  A
    	      distribution control_directory attribute and swpackage's
    	      response to it is an implementation extension.  The leading
    	      package path can also be controlled with the ''-W dir'' option.
    	      This attribute will be generated by swpackage if not set in a
    	      PSF.

       o Bundle Attributes
           A bundle defines a collection of products whether or not the
           distribution has all the products present.

           tag

    	      tag is the short, file system friendly, name of the bundle.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  If it is not
    	      present the product tag is used.

       o Product Attributes
           A product defines the software product.

           tag

    	      tag is the short, file system friendly, name of the product.
    	      This value is used by the swbis implementation as a path name
    	      component in the installed software catalog.  It is required.
    	      The swbis implementation uses it in a way that is analogous to
    	      the RPMTAG_NAME attribute, namely as the public recognizable
    	      name of the package.

           control_directory

    	      Is the directory name in the distribution under which the
    	      product contents are located.  This value has no affect on the
    	      installed software catalog.  If it is not given in a PSF then
    	      the tag is used.

           revision

    	      Is the product revision.	It should not contain a "RELEASE"
    	      attribute part or other version suffix modifiers.	 This value is
    	      used by the swbis implementation as a path name component in the
    	      installed software catalog.  It is required by swinstall.

           vendor_tag

    	      This is a short identifying name of the distributor that
    	      supplied the product and may associate (refer to) a vendor
    	      object from the INDEX file that has a matching tag attribute.
    	      This attribute is optional.  This attribute value should strive
    	      to be unique among all distributors. The swbis implementation
    	      modifies the intended usage slightly as a string that strives to
    	      be globally unique for a given product.tag and product.revision.
    	      In this capacity it serves to distinguish products with the same
    	      revision and tag from the same or different distributor.	It
    	      most closely maps to the RPMTAG_RELEASE or "debian_revision"
    	      attributes.  It is one of the version distinguishing attributes
    	      of a product specified by the standard.  It is transfered into
    	      the installed_software catalog (not as a path name component) by
    	      swinstall.  If this attribute exists there should also be a
    	      vendor object in the PSF in the distribution object that has
    	      this tag.	 This attribute is assigned the value of
    	      RPMTAG_RELEASE by swpackage when translating an RPM.

           architecture

    	      This string is one of the version attributes.  It is used to
    	      disambiguate products that have the same tag, revision and
    	      vendor_tag.  It is not used for determining a products
    	      compatibility with a host.  The form is implementation defined.
    	      swbis uses the output of GNU config.guess as the value of this
    	      string.  A wildcard pattern should not be used.  The canonical
    	      swbis architecture string can be listed with swlist. For example

    	      swlist -a architecture @ localhost

    	       Here are some example outputs from real systems.

    		  System      `uname -srm`		architecture
    	      Red Hat 8.0:  Linux 2.4.18 i686	     i686-pc-linux-gnu
    	      OpenSolaris:  SunOS 5.11 i86pc	     i386-pc-solaris2.11
    	      NetBSD 3.1:   NetBSD 3.1 i386	     i386-unknown-netbsdelf3.1
    	      Red Hat 4.1:  Linux 2.0.36 i586	     i586-pc-linux-gnulibc1
    	      Debian 3.1:   Linux 2.6.8-2-386 i686   i686-pc-linux-gnu

           os_name os_release os_version machine_type

    	      These attributes are used to determine compatibility with a
    	      host.  They correspond to the uname attributes defined by
    	      POSIX.1.	If an value is nil or non-existent it is assumed to
    	      match the host.  All attributes must match for there to be
    	      compatibility.  Distributors may wish to make these values a
    	      shell pattern in their PSF's so to match the intended collection
    	      of hosts.	 swbis uses fnmatch (with FLAGS=0) to determine a
    	      match.

       o Fileset Attributes
           A fileset defines the fileset.

           tag

    	      tag is the short, file system friendly, name of the fileset.  It
    	      is required although selection of filesets is  not yet supported
    	      therefore the end user will have little to do with the fileset
    	      tag.

           control_directory

    	      Is the directory name in the product under which the fileset
    	      contents are located.  This value has no affect on the installed
    	      software catalog.	 If it is not given in a PSF then the tag is
    	      used.

       o Example Source Package PSF
           This PSF packages every file is current directory. It uses nil control
           directories so the package structure does not change relative to a
           vanilla tarball.

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING
    	vendor
    	  the_term_vendor_is_misleading false
    	  tag fooware
    	  title fooware Consultancy Services, Inc.
    	  description ""
    	vendor
    	  the_term_vendor_is_misleading true
    	  tag myfixes1
    	  title Bug fixes, Set 1
    	  description "a place for more detailed description"
    	product
    	  tag fooit
    	  control_directory ""
    	  revision 1.0
    	  vendor_tag myfixes1  # Matches the vendor object above
    	fileset
    	   tag fooit-SOURCE
    	   control_directory ""
    	   directory .
    	   file *
    	   exclude catalog

       o Example Runtime (Binary) Package PSF
           This is a sample PSF for a runtime package.  It implies multiple
           products (e.g. sub-packages) using the bundle.contents attribute.
           Since the bundle and product tags exist in a un-regulated namespace and
           are seen by end users they should be carefully chosen.	Note that the
           bundle and product have the same tag which may force downstream users
           to disambiguate using software selection syntax such as fooit,bv=* or
           fooit,pv=* .

    	distribution
    	  description "fooit - a program from fooware
           that does everything."
    	  title "fooit - a really cool program"
    	  COPYING < /usr/local/fooware/legalstuff/COPYING

    	    vendor
    	       the_term_vendor_is_misleading false
    	       tag fooware
    	       title fooware Consultancy Services, Inc.
    	       description "Provider of the programs
    	that do everything"

    	    vendor
    	       the_term_vendor_is_misleading true
    		tag fw0
    		title fooware fixes
    		description "More fixes from the fooware users"

           #  Bundle definition:  Use a bundle
    	    bundle
    		tag fooit
    		vendor_tag fooware
    		contents fooit,v=fw0 fooit-devel fooit-doc

           #  Product definition:
    	    product
    		tag fooit   # This is the package name
    		revision 1.0 # This is the package version
    		vendor_tag fw0 # This is a release name e.g. RPMTAG_RELEASE
    		postinstall scripts/postinstall
    	    fileset
    		 tag fooit-RUN
    		 file doc/man/man1/fooit.1 /usr/man/man1/fooit.1
    		 file src/fooit /usr/bin/fooit

    APPLICABLE STANDARDS
           IEEE Std 1387.2-1995 (Identical to ISO 15068-2:1999), Open Group CAE
           C701

    SEE ALSO
    	XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm
    	swbisparse(1) -- An implementation extension parser utility.
    	swcopy(8)
    	swinstall(8)
    	swbis(7)
    	swbis(1)
    	swpackage(5)
    	swpackage(8)
    	swverify(8)

    IDENTIFICATION
    	Copyright (C) 2005 Jim Lowe
    	Version: 1.13.1
    	Last Updated: 2006-01
    	Copying Terms: GNU Free Documentation License

    BUGS
           None

    									 sw(5)

Next: Status, Previous: Introduction, Up: Top

## Glossary

(This section is currently under construction).

Distribution
  This refers to the package in either a directory form (unpacked) or a serial archive form (e.g. a compressed tarball). A distribution is always in the form of the POSIX software packaging layout.
Exported Catalog Structure
  This refers to the first portion of the distribution, the portion of the distribution that is contained in the `catalog` directory.
File Storage Structure
  This refers to the second portion of the distribution, the portion that is not the catalog portion but follows it. The control directory names for products and filesets are repeated from the Exported Catalog Structure and serve to segregate and annotate the files that make up the fileset.
Installed Software
  This refers abstractly to installed software files and installed software catalog.
Installed Software Catalog
  This refers to the catalog of installed software. The form of this catalog is not specified by the standard.
software_spec
  A software_spec follows a specific syntax of dot separated tags optionally followed by a comma (,) and then a comma separated list of version identifiers.
Software Selection
  A software selection has the form of a software_spec. A Software Selection appears before the '@' and the targets on the command lines.
Target
  A target specifies a host and file name on the host. The GNU implementation also supports a syntax to specify a user name on the host. A list of one or more targets is given after a single '@' and are the the last arguments on the command line.

Next: Invoking swbis, Previous: Host Requirements, Up: Top

## 2 How to configure swbis

The configuration file is called a defaults file. The defaults file contains extended options which also can be specified using the '-x' option.

There are two (2) defaults files, the POSIX file named `swdefaults` and the swbis specific file named `swbisdefaults`. The swbis extension options all begin with "swbis_".

For all users the following config file values are recommended (these are the builtin defaults):

    swbis_local_pax_write_command  = tar  # {pax|tar|star|gtar}
    swbis_remote_pax_write_command = tar  # {pax|tar|star|gtar}
    swbis_local_pax_read_command   = tar  # {pax|tar|star|gtar}
    swbis_remote_pax_read_command  = tar  # {pax|tar|star|gtar}
    swbis_no_getconf               = true # true or false
    swlist.swbis_local_pax_write_command  = detect  # {pax|tar|gtar|detect}
    swlist.swbis_remote_pax_write_command = detect  # {pax|tar|gtar|detect}
    swverify.swbis_local_pax_write_command  = detect  # {detect|pax|tar|gtar}
    swverify.swbis_remote_pax_write_command = detect  # {detect|pax|tar|gtar}

    swbis_shell_command            = detect # {detect|sh|bash|posix|ksh}
    swbis_allow_rpm                = true
    swcopy.swbis_no_audit          = true # true or false

The files are located in two places, in the package library directory such as `/usr/lib/swbis`, and in the user's home directory in the `.swbis` directory.

To show these locations:

                  swinstall --show-options-files

To show the options:

                  swinstall --show-options

To show the compiled in defaults if no defaults files are read:

                  swinstall --no-defaults --show-options

Next: swbisdefaults configuration file, Up: Configuring swbis

### swdefaults

    # File: sw defaults
    ## uncomment options as needed.

    installed_software_catalog	= var/lib/swbis/catalog

    #swinstall.allow_downdate			= false
    #swinstall.allow_incompatible			= false
    #swinstall.ask					= false
    #swinstall.autoreboot				= false
    #swinstall.autoselect_dependencies		= false
    #swinstall.defer_configure			= false
    #swinstall.distribution_source_directory	= -
    #swinstall.enforce_dependencies			= false
    #swinstall.enforce_dsa				= false
    #swinstall.enforce_locatable			= false
    #swinstall.enforce_scripts			= false
    #swinstall.installed_software_catalog		= var/lib/swbis/catalog
    #swinstall.logfile				= /var/log/swinstall.log
    #swinstall.loglevel				= 1
    #swinstall.reinstall				= false
    #swinstall.select_local				=
    #swinstall.software				=
    #swinstall.targets				=
    #swinstall.verbose				= 1

    #swcopy.autoselect_dependencies			= false		# Support not implemented.
    #swcopy.compress_files				= false 	# Support not implemented.
    #swcopy.compression_type			= none  	# Support not implemented.
    #swcopy.distribution_source_directory		= -	# Standard input
    #swcopy.distribution_target_directory		= -	# Standard output
    #swcopy.enforce_dependencies			= false		# Support not implemented.
    #swcopy.enforce_dsa				= false		# Support not implemented.
    #swcopy.logfile					= /var/log/swcopy.log
    #swcopy.loglevel				= 0		# Support not implemented.
    #swcopy.recopy					= false		# Support not implemented.
    #swcopy.select_local				= false		# Support not implemented.
    #swcopy.software				=
    #swcopy.targets					=
    #swcopy.uncompress_files			= false		# Support not implemented.
    #swcopy.verbose					= 1

    #swremove.autoselect_dependencies		= true
    #swremove.distribution_target_directory		= /var/spool/sw
    #swremove.enforce_dependencies			= true
    #swremove.enforce_scripts			= true
    #swremove.enforce_dsa				= true
    #swremove.installed_software_catalog		= var/lib/swbis/catalog
    #swremove.logfile				= /var/log/swremove.log
    #swremove.loglevel				= 1
    #swremove.select_local				= true
    #swremove.software				=
    #swremove.targets				=
    #swremove.verbose				= 1

    #swconfig.allow_incompatible			= false
    #swconfig.allow_multiple_versions		= false
    #swconfig.ask					= false
    #swconfig.autoselect_dependencies		= true
    #swconfig.autoselect_dependents			= false
    #swconfig.enforce_dependencies			= true
    #swconfig.installed_software_catalog		= var/lib/swbis/catalog
    #swconfig.logfile				= /var/log/swconfig.log
    #swconfig.loglevel				= 1
    #swconfig.reconfigure				= false
    #swconfig.select_local				= true
    #swconfig.software				=
    #swconfig.targets				=
    #swconfig.verbose				= 1

    #swask.autoselect_dependencies			= true
    #swask.distribution_source_directory		= /var/spool/sw
    #swask.distribution_source_serial		= -
    #swask.logfile					= /var/log/swask.log
    #swask.loglevel					= 1
    #swask.select_local				= true
    #swask.software					=
    #swask.targets					=
    #swask.verbose					= 1

    #swmodify.distribution_target_directory		= /var/spool/sw
    #swmodify.installed_software_catalog		= var/lib/swbis/catalog
    #swmodify.files					=
    #swmodify.logfile				= /var/log/swmodify.log
    #swmodify.loglevel				= 1
    #swmodify.select_local				= true
    #swmodify.software				=
    #swmodify.targets				=
    #swmodify.verbose				= 1

    #swverify.allow_incompatible			= false
    #swverify.autoselect_dependencies		= true
    #swverify.check_contents			= true
    #swverify.check_permissions			= true
    #swverify.check_requisites			= true
    #swverify.check_scripts				= true
    #swverify.check_volatile			= false
    #swverify.distribution_target_directory		= /var/spool/sw
    #swverify.enforce_dependencies			= true
    #swverify.enforce_locatable			= true
    #swverify.installed_software_catalog		= var/lib/swbis/catalog
    #swverify.logfile				= /var/log/swverify.log
    #swverify.loglevel				= 1
    #swverify.select_local				=
    #swverify.software				=
    #swverify.targets				=
    #swverify.verbose				= 1

    #swlist.distribution_target_directory		= /
    #swlist.installed_software_catalog		= var/lib/swbis/catalog
    #swlist.one_liner				= products # {products|files|dir}
    #swlist.select_local				= true
    #swlist.software				=
    #swlist.targets					=
    #swlist.verbose					= 1

    #swpackage.distribution_target_directory	= /var/spool/sw
    #swpackage.distribution_target_serial		= -
    #swpackage.enforce_dsa				= false
    #swpackage.follow_symlinks			= false
    #swpackage.logfile				= /var/log/swpackage.log
    #swpackage.loglevel				= 1
    #swpackage.media_capacity			= 0
    #swpackage.media_type				= serial
    #swpackage.psf_source_file			= -
    #swpackage.software				=
    #swpackage.verbose				= 1

    # end of swdefaults file

Next: Archive Reading/Writing Utility Selection, Previous: swdefaults configuration file, Up: Configuring swbis

### swbisdefaults

    # File: swbisdefaults
    ## Uncomment options as needed.

    # Suggested Defaults

    #swbis_no_getconf		= true # true or false, Deprecated.
    #swbis_shell_command		= detect # {sh|detect|bash|posix|ksh}
    #swbis_no_remote_kill		= true  # true or false
    #swbis_quiet_progress_bar	= true  # true or false
    #swlist.swbis_local_pax_write_command    = detect
    #swlist.swbis_remote_pax_write_command   = detect
    #swverify.swbis_local_pax_write_command  = detect
    #swverify.swbis_remote_pax_write_command = detect
    #swbis_local_pax_write_command 	= tar  # {pax|tar|star|gtar|swbistar}
    #swbis_remote_pax_write_command  = tar  # {pax|tar|star|gtar|swbistar}
    #swbis_local_pax_read_command 	= tar  # {pax|tar|star|gtar}
    #swbis_remote_pax_read_command 	= tar  # {pax|tar|star|gtar}
    #swbis_remote_shell_client	= ssh
    #swbis_allow_rpm		= true
    #swbis_forward_agent		= false # Forward ssh agent. true=yes false=no

    #swcopy.swbis_no_getconf			= false # true or false, Deprecated.
    #swcopy.swbis_shell_command			= detect # {sh|bash|posix|ksh|detect}
    #swcopy.swbis_no_remote_kill			= false # true or false
    #swcopy.swbis_quiet_progress_bar		= true  # true or false
    #swcopy.swbis_no_audit				= true # true or false
    #swcopy.swbis_local_pax_write_command 		= pax  # {pax|tar|star|gtar|swbistar}
    #swcopy.swbis_remote_pax_write_command 		= pax  # {pax|tar|star|gtar|swbistar}
    #swcopy.swbis_local_pax_read_command 		= pax  # {pax|tar|star|gtar}
    #swcopy.swbis_remote_pax_read_command 		= pax  # {pax|tar|star|gtar}
    #swcopy.swbis_remote_shell_client		= ssh
    #swcopy.swbis_forward_agent			= true

    #swinstall.swbis_no_getconf			= false # true or false, Deprecated.
    #swinstall.swbis_shell_command			= detect # {sh|bash|posix|ksh|detect}
    #swinstall.swbis_no_remote_kill			= false # true or false
    #swinstall.swbis_quiet_progress_bar		= true  # true or false
    #swinstall.swbis_local_pax_write_command 	= pax  # {pax|tar|star|gtar|swbistar}
    #swinstall.swbis_remote_pax_write_command 	= pax  # {pax|tar|star|gtar|swbistar}
    #swinstall.swbis_local_pax_read_command 	= pax  # {pax|tar|star|gtar}
    #swinstall.swbis_remote_pax_read_command 	= pax  # {pax|tar|star|gtar}
    #swinstall.swbis_sig_level			= 0    # number of signatures to require
    #swinstall.swbis_enforce_file_md5		= false
    #swinstall.swbis_allow_rpm			= false
    #swinstall.swbis_remote_shell_client		= ssh
    #swinstall.swbis_install_volatile		= true
    #swinstall.swbis_volatile_newname		= ""     # e.g. ".rpmnew"
    #swinstall.swbis_forward_agent			= true
    #swinstall.swbis_ignore_scripts			= false

    #swpackage.swbis_cksum				= "false"   # true or false
    #swpackage.swbis_file_digests			= "true"   # true or false
    #swpackage.swbis_files				= "false"   # true or false
    #swpackage.swbis_sign				= "false"   # true or false
    #swpackage.swbis_archive_digests		= "false"   # true or false
    #swpackage.swbis_gpg_name			= ""
    #swpackage.swbis_gpg_path			= "~/.gnupg"
    #swpackage.swbis_gzip				= "false"   # true or false
    #swpackage.swbis_bzip2				= "false"   # true or false
    #swpackage.swbis_numeric_owner			= "false"   # true or false
    #swpackage.swbis_absolute_names			= "false"   # true or false
    #swpackage.swbis_format				= "ustar"
    #swpackage.swbis_signer_pgm			= "GPG"
    #swpackage.swbis_check_duplicates		= "true"

    #swlist.swbis_no_getconf			= false # true or false, Deprecated.
    #swlist.swbis_shell_command			= detect # {sh|bash|posix|ksh}
    #swlist.swbis_no_remote_kill			= false # true or false
    #swlist.swbis_local_pax_write_command 		= detect # {pax|tar|star|gtar|swbistar|detect}
    #swlist.swbis_remote_pax_write_command 		= detect # {pax|tar|star|gtar|swbistar|detect}
    #swlist.swbis_local_pax_read_command 		= detect # {pax|tar|star|gtar|detect}
    #swlist.swbis_remote_pax_read_command 		= detect # {pax|tar|star|gtar|detect}
    #swlist.swbis_remote_shell_client		= ssh
    #swlist.swbis_any_format			= false # true or false
    #swlist.swbis_forward_agent			= true
    #swlist.swbis_sig_level				= 0 # Number of required valid signatures
    #swlist.swbis_enforce_all_signatures		= false

    #swremove.swbis_no_getconf			= false # true or false, Deprecated.
    #swremove.swbis_shell_command			= detect # {sh|bash|posix|ksh}
    #swremove.swbis_no_remote_kill			= false # true or false
    #swremove.swbis_local_pax_write_command 	= tar  # {pax|tar|star|gtar|swbistar}
    #swremove.swbis_remote_pax_write_command 	= tar  # {pax|tar|star|gtar|swbistar}
    #swremove.swbis_local_pax_read_command 		= tar  # {pax|tar|star|gtar}
    #swremove.swbis_remote_pax_read_command 	= tar  # {pax|tar|star|gtar}
    #swremove.swbis_local_pax_remove_command 	= tar  # {tar|gtar}  Must have the --remove-files option
    #swremove.swbis_remote_pax_remove_command 	= tar  # {tar|gtar}  Must have the --remove-files option
    #swremove.swbis_remote_shell_client		= ssh
    #swremove.swbis_forward_agent			= false
    #swremove.swbis_sig_level			= 0 # Number of required valid signatures
    #swremove.swbis_enforce_all_signatures		= false

    #swverify.swbis_no_getconf			= false # true or false, Deprecated.
    #swverify.swbis_shell_command			= detect # {sh|bash|posix|ksh}
    #swverify.swbis_no_remote_kill			= false # true or false
    #swverify.swbis_local_pax_write_command 	= detect # {pax|tar|star|gtar|swbistar|detect}
    #swverify.swbis_remote_pax_write_command 	= detect # {pax|tar|star|gtar|swbistar|detect}
    #swverify.swbis_local_pax_read_command 		= detect # {pax|tar|star|gtar|detect}
    #swverify.swbis_remote_pax_read_command 	= detect # {pax|tar|star|gtar|detect}
    #swverify.swbis_remote_shell_client		= ssh
    #swverify.swbis_forward_agent			= false
    #swverify.swbis_sig_level			= 0 # Number of required valid signatures
    #swverify.swbis_enforce_all_signatures		= false

    # end of swbisdefaults file

Next: Shell Selection, Previous: swbisdefaults configuration file, Up: Configuring swbis

### Archive Reading/Writing Utility Selection

    swbis_local_pax_write_command  = tar  # {pax|tar|star|gtar|swbistar}
    swbis_remote_pax_write_command = tar  # {pax|tar|star|gtar|swbistar}
    swbis_local_pax_read_command   = tar  # {pax|tar|star|gtar}
    swbis_remote_pax_read_command  = tar  # {pax|tar|star|gtar}
    swlist.swbis_local_pax_write_command   = detect  # {detect|pax|tar|gtar}
    swlist.swbis_remote_pax_write_command  = detect  # {detect|pax|tar|gtar}
    swverify.swbis_local_pax_write_command   = detect  # {detect|pax|tar|gtar}
    swverify.swbis_remote_pax_write_command  = detect  # {detect|pax|tar|gtar}

Next: (swbis_swbis)RUNTIME CONFIGURATION, Previous: Archive Reading/Writing Utility Selection, Up: Configuring swbis

### Shell Selection

Setting swbis_shell_command to 'detect' is the best choice here. The swbis_no_getconf option is headed for legacy status, disable it by setting this to 'true'.

    swbis_no_getconf               = true # true or false
    swbis_shell_command            = detect # {detect|sh|bash|posix||ksh}

Next: Glossary, Previous: About This Manual, Up: Top

## Introduction

## 3 Introduction

You are reading about GNU Swbis, the GNU implementation of the POSIX Software Administration Standard ISO/IEC 15068-2:1999 (formerly IEEE Std 1387.2-1995). This spec describes a interchange format, package file layout, meta-data file format and utilities for package creation, installation, query, listing, and verification.

The GNU implementation adds capabilities for package authentication using strong cryptographic digests and GPG signatures that are embedded in the package as an ordinary control files as allowed by the standard.

The GNU implementation is compatible with traditional free software distribution package file layouts by supporting empty names for control directories in the POSIX layout. This makes a swbis package no different from current packages except for the addition of the meta-data directory.

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

GNU Swbis also can translate and install packages in RPM format.

Next: Introduction, Previous: Copying This Manual, Up: Top

## About This Manual

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

Next: Host Requirements, Previous: Applicable Standards, Up: Top

## Other Resources

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

The swbis man pages are maintained and may be considered authoritative. See also swbis(1) and swbis(7) (via man 7 swbis or, man 1 swbis)

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

Next: Creating Signed Distributions, Previous: Command Reference, Up: Top

## Making PSFs for Package Creation

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

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

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

Comments in a PSF are not transferred into the INDEX file by the swbis implementation of `swpackage`.

The file syntax is the same as a INDEX, or INFO file. See (swbis_sw)SOFTWARE DEFINITION FILES.

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

Currently, `swpackage` does not enforce requirements for revision and name meta-data that other the 'swinstall' might need. Therefore you should perform a test install of your package. The preview '-p' option of `swinstall` internally simulates most of the install operation but does not alter the file system. The example below previews the package on standard input.

                 swinstall -p -x verbose=6 -s - < your_package

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

Next: A PSF for Source Packages, Previous: (swbis_sw)EXTENDED DEFINITIONS, Up: Making PSFs for Package Creation

### PSF.minimal

    # This PSF packaged all files in the current
    # directory.
    distribution
    dfiles dfiles
    product
    title somepackage version 0.1
    description Source package for somepackage version 0.1
    tag somepackage      # < Change this to your package name
    revision 0.1         # < Change this to your package version
    control_directory ""
    fileset
    tag somepackage-sources   # Not used by swbis currently
    control_directory ""
    file_permissions -o 0  -g 0
    directory .
    file *
    exclude catalog

Previous: A Minimal PSF, Up: Making PSFs for Package Creation

### A PSF for Source Packages

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

Next: Translating and Installing Other Formats, Previous: (swbis_swverify)VERIFYING SIGNATURES, Up: Top

## Installing POSIX Distributions

This is as simple as:

         swinstall <your-package
            # or
         swinstall -s :foo-1.1.tar.gz  @ 192.168.3.2 <your-package
            # or
         swinstall -x reinstall=y <your-package
            # or
         swinstall --no-scripts -x reinstall=y <your-package
            # or
         swinstall --no-scripts -x reinstall=y @ /tmp/test  <your-package

The default target directory is always '/'. See Command Reference.

Next: Configuring swbis, Previous: Other Resources, Up: Top

## Host Requirements

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

For package creation you need `uuidgen` and if creating signed distributions you need `gpg`.

For package installation you need `sh`, `bash`, `dd`, `tar`, `hostname`, `mkdir`, `expr`, `echo`, `test`, `sleep`.

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

The `swverify` and `swign` commands are shell scripts which may have additional requirements.

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

`swinstall` requires a POSIX shell accessible by the remote shell command. This is the remote command run by ssh (or rsh) for all operations. This command can be controlled by the –shell-command option or the swbis_shell_command defaults file option. The recommended value is 'detect' which performs auto-detection of a sutable shell.

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

Next: Creating a Catalog of Installed Packages, Previous: Creating Signed Distributions, Up: Top

## Signing File System Directories

To swbis, a signed directory is any directory that contains the GPG signed distribution catalog directory `./catalog/`. The signature protects the signed bytes which is a tar archive representation of `./catalog/`. The contents of directory `./catalog/` contain meta data about the contents of the current directory `./`.

Used is this way, the distribution catalog directory, `./catalog/`, is a GPG signed directory manifest.

The `./catalog/` directory is created by `swpackage`. A separate ad-hoc utility, `swign` makes signing a directory much easier.

Next: (swbis_swverify)VERIFYING SIGNATURES, Previous: Signing File System Directories, Up: Top

## Creating a Catalog of Installed Packages

Suppose your distribution uses a packaging format that does not provide an installed software catalog. Using swbis you can create your own provided you have the original package files.

To do this you translate the orignal package (that is already installed) to swbis format and install just the catalog. Like this:

          swinstall --justdb -s- @/

which writes that catalog at `/var/lib/swbis/catalog`. You can control the location of the catalog via the command line option.

          swinstall --justdb -x installed_software_catalog=/$HOME/my_catalog

Translation is done by the `lxpsf` utility. It can be invoked transparently using `swpackage` and sent via a pipe to swinstall:

            swpackage --to-swbis -s /Your/system/somepackage-1.0.type |
            swinstall --justdb

Then the catalog can be queried and used for verification purposes.

         swlist somepackage;  # list the package
         swlist;   # list all the installed software
         swverify --sig-level=0 -vv somepackage @ / ;  # Use sig-level=1 if you
                                                          # signed the package

This works really well for RPM distributions. Users of Debian and Slackware may want to take more detailed control to exclude extraneous system directories that hamper clean verification. Like this:

         lxpsf --psf-form3  --exclude-system-dirs somepackage-1.0.tar.xz |
         swpackage -Wsource=- -s @PSF @- | # Use special options to swpackage
         swinstall --justdb

Then verify. Slackware users may use the specific option to ignore the `./install` directory and its files.

         swlist;
         swverify --ignore-slack -x check_volatile=no somepackage @ /

All of package signing and security options are available when using swpackage as shown above. In fact it was assumed that they were all on by default. Creating a catalog without signatures or file digests or file list is of little use. Here is a last example showing some of these options.

The `lxpsf` is located in the LIBEXEC directory, for example `/usr/lib/swbis/lxpsf`.

        lxpsf --psf-form3  --exclude-system-dirs somepackage-1.0.tar.xz |
        swpackage \
           --files \
           --sha2  \
           --sha1  \
           --sign  \
           --passphrase=fd=agent \
           --gpg-name=NAME \
           -Wsource=- -s @PSF @- |
         swinstall --justdb

Next: Remote Host Operations, Previous: Installing POSIX Distributions, Up: Top

## Translating and Installing Other Formats

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

Translation is performed by the swbis library executable `lxpsf` and `swpackage`. Internally, this is

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

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

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

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

To verbosely preview the translated RPM:

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

Next: GNU Toolset Orthogonality, Previous: Translating and Installing Other Formats, Up: Top

##

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

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

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

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

Next: Package Layout and Interchange Format Mimicry, Previous: Remote Host Operations, Up: Top

##

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

Next: (swbis_swpackage)SWPACKAGE OUTPUT FORMAT, Previous: GNU Toolset Orthogonality, Up: Top

##

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

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

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

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

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

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

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

Previous: (swbis_sw)EXAMPLE PACKAGE, Up: Top

## Index