# swpackage(8)

### Contents

- NAME
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- EXTENDED OPTIONS
  - Posix
  - Swbis Implementation
- PACKAGE SIGNING
  - Description
  - Signature Generation
  - Passphrase Handling
- SIGNATURE VERIFICATION
  - Overview
  - Manual Verification
  - Manual Verification Using Standard Tools
- SWPACKAGE OUTPUT FORMAT
- SWPACKAGE INPUT FILE FORMAT
  - EXTENDED DEFINITIONS
  - SWBIS PSF CONVENTIONS
- SAMPLE PRODUCT SPEC FILES
- RETURN VALUE
- SIDE EFFECTS
- ENVIRONMENT
  - SWPACKAGEPASSPHRASE
  - GNUPGHOME
  - GNUPGNAME
- REQUISITE UTILITIES
- FILES
- APPLICABLE STANDARDS
- SEE ALSO
- IDENTIFICATION
- BUGS

### 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 @/dev/null   # Useful for debugging

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

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

### 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.  This implementation only supports
           writing to stdout.

### 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 system directory, or device file or '-' Currently this
                  implementation only supports a serial archive written to stdout.

           -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
                  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 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
                  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
                           This is the default format but may be changed by
                           the options files.
                   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 (Not implemented).
                   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 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
                  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
                  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 no-catalog
                  Do not write the catalog section.

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

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

### 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 \
             --files-from=- --no-recursion | 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 \
             --files-from=- --no-recursion | 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 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), 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.6
            Last Updated: 2006-07-01
            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)