This is info/swbis_swpackage.info, produced by makeinfo version 4.7
from stdin.

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* swpackage: (swbis).               make POSIX format packages
END-INFO-DIR-ENTRY



File: swbis_swpackage.info,  Node: Top,  Next: NAME,  Up: (dir)

1 swpackage" "8
***************

* Menu:

* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* EXTENDED OPTIONS::
* PACKAGE SIGNING::
* SIGNATURE VERIFICATION::
* SWPACKAGE OUTPUT FORMAT::
* SWPACKAGE INPUT FILE FORMAT::
* SAMPLE PRODUCT SPEC FILES::
* RETURN VALUE::
* SIDE EFFECTS::
* ENVIRONMENT::
* REQUISITE UTILITIES::
* FILES::
* APPLICABLE STANDARDS::
* SEE ALSO::
* IDENTIFICATION::
* BUGS::


File: swbis_swpackage.info,  Node: NAME,  Next: SYNOPSIS,  Prev: Top,  Up: Top

1.1 NAME
========

swpackage -- Package a software distribution.


File: swbis_swpackage.info,  Node: SYNOPSIS,  Next: DESCRIPTION,  Prev: NAME,  Up: Top

1.2 SYNOPSIS
============

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


File: swbis_swpackage.info,  Node: DESCRIPTION,  Next: OPTIONS,  Prev: SYNOPSIS,  Up: Top

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


File: swbis_swpackage.info,  Node: OPTIONS,  Next: EXTENDED OPTIONS,  Prev: DESCRIPTION,  Up: Top

1.4 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

     Not implemented.
-W bzip2

     Not implemented.
-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 output reproducible by different invocations.
-W list-psf

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

     Same as -W 2posixformat
-W 2posixformat

     Read a package on standard input and write a POSIX package on
     standard output.  Requires the Supported formats are any supported
     format of lxpsf.  Identical to: /swbis/lxpsf --psf-form2 -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.


File: swbis_swpackage.info,  Node: EXTENDED OPTIONS,  Next: PACKAGE SIGNING,  Prev: OPTIONS,  Up: Top

1.5 EXTENDED OPTIONS
====================

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

* Menu:

* Posix::
* Swbis Implementation::


File: swbis_swpackage.info,  Node: Posix,  Next: Swbis Implementation,  Up: EXTENDED OPTIONS

1.5.1 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


File: swbis_swpackage.info,  Node: Swbis Implementation,  Prev: Posix,  Up: EXTENDED OPTIONS

1.5.2 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_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"  # gnutar or ustar
     swpackage.swbis_signer_pgm               = "GPG" # GPG or PGP5 or PGP2.6


File: swbis_swpackage.info,  Node: PACKAGE SIGNING,  Next: SIGNATURE VERIFICATION,  Prev: EXTENDED OPTIONS,  Up: Top

1.6 PACKAGE SIGNING
===================

Support for embedded cryptographic signature.

* Menu:

* Description::
* Signature Generation::
* Passphrase Handling::


File: swbis_swpackage.info,  Node: Description,  Next: Signature Generation,  Up: PACKAGE SIGNING

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


File: swbis_swpackage.info,  Node: Signature Generation,  Next: Passphrase Handling,  Prev: Description,  Up: PACKAGE SIGNING

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


File: swbis_swpackage.info,  Node: Passphrase Handling,  Prev: Signature Generation,  Up: PACKAGE SIGNING

1.6.3 Passphrase Handling
-------------------------

The passphrase is read by the swpackage utility from the process
controlling terminal or stdin if there is no controlling terminal.  A
separate dedicated process reads the passphrase which may be up to 239
characters in length.  It is immediately written into a Unix pipe, read
by the signer program on file descriptor three (fd=3), its memory
location wiped, and the dedicated process exited.


File: swbis_swpackage.info,  Node: SIGNATURE VERIFICATION,  Next: SWPACKAGE OUTPUT FORMAT,  Prev: PACKAGE SIGNING,  Up: Top

1.7 SIGNATURE VERIFICATION
==========================

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

* Menu:

* Overview::
* Manual Verification::
* Manual Verification Using Standard Tools::


File: swbis_swpackage.info,  Node: Overview,  Next: Manual Verification,  Up: SIGNATURE VERIFICATION

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


File: swbis_swpackage.info,  Node: Manual Verification,  Next: Manual Verification Using Standard Tools,  Prev: Overview,  Up: SIGNATURE VERIFICATION

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


File: swbis_swpackage.info,  Node: Manual Verification Using Standard Tools,  Prev: Manual Verification,  Up: SIGNATURE VERIFICATION

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


File: swbis_swpackage.info,  Node: SWPACKAGE OUTPUT FORMAT,  Next: SWPACKAGE INPUT FILE FORMAT,  Prev: SIGNATURE VERIFICATION,  Up: Top

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


File: swbis_swpackage.info,  Node: SWPACKAGE INPUT FILE FORMAT,  Next: SAMPLE PRODUCT SPEC FILES,  Prev: SWPACKAGE OUTPUT FORMAT,  Up: Top

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

* Menu:

* EXTENDED DEFINITIONS::
* o Extended Control File Definitions::
* o Directory Mapping::
* o Recursive File Definition::
* o Explicit File Definition::
* o Default Permission Definition::
* o Excluding Files::
* o Including Files::
* SWBIS PSF CONVENTIONS::
* o Distribution Attributes::
* o Bundle Attributes::
* o Product Attributes::
* o Fileset Attributes::
* o Example Source Package PSF::
* o Example Runtime (Binary) Package PSF::


File: swbis_swpackage.info,  Node: EXTENDED DEFINITIONS,  Next: o Extended Control File Definitions,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Extended Control File Definitions,  Next: o Directory Mapping,  Prev: EXTENDED DEFINITIONS,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Directory Mapping,  Next: o Recursive File Definition,  Prev: o Extended Control File Definitions,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Recursive File Definition,  Next: o Explicit File Definition,  Prev: o Directory Mapping,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.4 o  Recursive File Definition
----------------------------------

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


File: swbis_swpackage.info,  Node: o Explicit File Definition,  Next: o Default Permission Definition,  Prev: o Recursive File Definition,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Default Permission Definition,  Next: o Excluding Files,  Prev: o Explicit File Definition,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.6 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


File: swbis_swpackage.info,  Node: o Excluding Files,  Next: o Including Files,  Prev: o Default Permission Definition,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.7 o  Excluding Files
------------------------

        exclude source
Excludes a previously included file or an entire directory.


File: swbis_swpackage.info,  Node: o Including Files,  Next: SWBIS PSF CONVENTIONS,  Prev: o Excluding Files,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.8 o  Including Files
------------------------

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


File: swbis_swpackage.info,  Node: SWBIS PSF CONVENTIONS,  Next: o Distribution Attributes,  Prev: o Including Files,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Distribution Attributes,  Next: o Bundle Attributes,  Prev: SWBIS PSF CONVENTIONS,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Bundle Attributes,  Next: o Product Attributes,  Prev: o Distribution Attributes,  Up: SWPACKAGE INPUT FILE FORMAT

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


File: swbis_swpackage.info,  Node: o Product Attributes,  Next: o Fileset Attributes,  Prev: o Bundle Attributes,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.12 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.
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 associates the vendor object from the INDEX file.
     This attribute is optional.  This attribute value should strive to
     be unique among all distributors.  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.  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.


File: swbis_swpackage.info,  Node: o Fileset Attributes,  Next: o Example Source Package PSF,  Prev: o Product Attributes,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.13 o Fileset Attributes
---------------------------

A fileset defines the fileset.  tag

     tag is the short, file system friendly, name of the fileset.  It
     is required.
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.


File: swbis_swpackage.info,  Node: o Example Source Package PSF,  Next: o Example Runtime (Binary) Package PSF,  Prev: o Fileset Attributes,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.14 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


File: swbis_swpackage.info,  Node: o Example Runtime (Binary) Package PSF,  Prev: o Example Source Package PSF,  Up: SWPACKAGE INPUT FILE FORMAT

1.9.15 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


File: swbis_swpackage.info,  Node: SAMPLE PRODUCT SPEC FILES,  Next: RETURN VALUE,  Prev: SWPACKAGE INPUT FILE FORMAT,  Up: Top

1.10 SAMPLE PRODUCT SPEC FILES
==============================

This section shows several example PSF files.

* Menu:

* o A minimal PSF to package all files in current directory ::
* o A PSF that uses directory mapping ::
* o Create a PSF from a list of files ::


File: swbis_swpackage.info,  Node: o A minimal PSF to package all files in current directory,  Next: o A PSF that uses directory mapping,  Up: SAMPLE PRODUCT SPEC FILES

1.10.1 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 *


File: swbis_swpackage.info,  Node: o A PSF that uses directory mapping,  Next: o Create a PSF from a list of files,  Prev: o A minimal PSF to package all files in current directory,  Up: SAMPLE PRODUCT SPEC FILES

1.10.2 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


File: swbis_swpackage.info,  Node: o Create a PSF from a list of files,  Prev: o A PSF that uses directory mapping,  Up: SAMPLE PRODUCT SPEC FILES

1.10.3 o   Create a PSF from a list of files.
---------------------------------------------

                find . -print |  swpackage -Wfiles-from=- -Wlist-psf


File: swbis_swpackage.info,  Node: RETURN VALUE,  Next: SIDE EFFECTS,  Prev: SAMPLE PRODUCT SPEC FILES,  Up: Top

1.11 RETURN VALUE
=================

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


File: swbis_swpackage.info,  Node: SIDE EFFECTS,  Next: ENVIRONMENT,  Prev: RETURN VALUE,  Up: Top

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


File: swbis_swpackage.info,  Node: ENVIRONMENT,  Next: REQUISITE UTILITIES,  Prev: SIDE EFFECTS,  Up: Top

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


File: swbis_swpackage.info,  Node: REQUISITE UTILITIES,  Next: FILES,  Prev: ENVIRONMENT,  Up: Top

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


File: swbis_swpackage.info,  Node: FILES,  Next: APPLICABLE STANDARDS,  Prev: REQUISITE UTILITIES,  Up: Top

1.15 FILES
==========

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


File: swbis_swpackage.info,  Node: APPLICABLE STANDARDS,  Next: SEE ALSO,  Prev: FILES,  Up: Top

1.16 APPLICABLE STANDARDS
=========================

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


File: swbis_swpackage.info,  Node: SEE ALSO,  Next: IDENTIFICATION,  Prev: APPLICABLE STANDARDS,  Up: Top

1.17 SEE ALSO
=============

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


File: swbis_swpackage.info,  Node: IDENTIFICATION,  Next: BUGS,  Prev: SEE ALSO,  Up: Top

1.18 IDENTIFICATION
===================

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


File: swbis_swpackage.info,  Node: BUGS,  Prev: IDENTIFICATION,  Up: Top

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



Tag Table:
Node: Top224
Node: NAME692
Node: SYNOPSIS840
Node: DESCRIPTION1094
Node: OPTIONS1583
Node: EXTENDED OPTIONS9220
Node: Posix9533
Node: Swbis Implementation10593
Node: PACKAGE SIGNING11884
Node: Description12167
Node: Signature Generation13011
Node: Passphrase Handling13662
Node: SIGNATURE VERIFICATION14219
Node: Overview14633
Node: Manual Verification14985
Node: Manual Verification Using Standard Tools15607
Node: SWPACKAGE OUTPUT FORMAT17774
Node: SWPACKAGE INPUT FILE FORMAT19957
Node: EXTENDED DEFINITIONS22024
Node: o Extended Control File Definitions23118
Node: o Directory Mapping24395
Node: o Recursive File Definition24968
Node: o Explicit File Definition25351
Node: o Default Permission Definition27257
Node: o Excluding Files28022
Node: o Including Files28313
Node: SWBIS PSF CONVENTIONS28645
Node: o Distribution Attributes29049
Node: o Bundle Attributes30949
Node: o Product Attributes31505
Node: o Fileset Attributes33492
Node: o Example Source Package PSF34068
Node: o Example Runtime (Binary) Package PSF35269
Node: SAMPLE PRODUCT SPEC FILES37147
Node: o A minimal PSF to package all files in current directory37543
Node: o A PSF that uses directory mapping38053
Node: o Create a PSF from a list of files40856
Node: RETURN VALUE41169
Node: SIDE EFFECTS41418
Node: ENVIRONMENT41819
Node: REQUISITE UTILITIES42550
Node: FILES42976
Node: APPLICABLE STANDARDS43233
Node: SEE ALSO43430
Node: IDENTIFICATION43638
Node: BUGS43960

End Tag Table
