\input texinfo   @c -*-texinfo-*-
@setfilename swpackage.info
@comment direntry.in
@dircategory Individual utilities
@direntry
* swpackage: (swbis).               make POSIX format packages
@end direntry
@comment ===============================================================
@comment WARNING: Do NOT edit this file.  It was produced automatically
@comment by man2info on Sun Feb 19 20:52:22 EST 2006
@comment for jhl@
@comment from man/man8/swpackage.8
@comment in /home/jhl/swbis-0.483/doc
@comment ===============================================================
@comment @documentencoding ISO-8859-1
@comment troff -man typesetting style: headers, footers, no paragraph indentation
@paragraphindent none
@iftex
@parskip = 0.5@normalbaselineskip plus 3pt minus 1pt
@end iftex
@set lq ``
@set rq ''
@comment TROFF INPUT: .TH "swpackage" "8"
@headings off
@everyheading SWPACKAGE(8) @| @| SWPACKAGE(8)
@everyfooting  @| @thispage @|
@node Top
@chapter swpackage" "8
@c DEBUG: print_menu("Top")
@ifnottex
@menu
* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* EXTENDED OPTIONS::
* PACKAGE SIGNING::
* SIGNATURE VERIFICATION::
* ::
* SAMPLE PRODUCT SPEC FILES::
* SWPACKAGE OUTPUT FORMAT::
* RETURN VALUE::
* SIDE EFFECTS::
* ENVIRONMENT::
* REQUISITE UTILITIES::
* FILES::
* APPLICABLE STANDARDS::
* SEE ALSO::
* IDENTIFICATION::
* BUGS::
@end menu
@end ifnottex
@comment TROFF INPUT: .SH "NAME"
@node NAME
@section NAME
@c DEBUG: print_menu("NAME")
swpackage @r{---} Package a software distribution.
@comment TROFF INPUT: .SH "SYNOPSIS"
@node SYNOPSIS
@section SYNOPSIS
@c DEBUG: print_menu("SYNOPSIS")
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@b{swpackage}  [@minus{}p]  [@minus{}s @i{psf@t{_}file}]  [@minus{}f @i{file}] [@minus{}x @i{option=value}] \@tie{}
[@minus{}X @i{options@t{_}file}] [@minus{}W @i{option}] [software@t{_}selections] [@@targets]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "DESCRIPTION"
@node DESCRIPTION
@section DESCRIPTION
@c DEBUG: print_menu("DESCRIPTION")
@comment TROFF INPUT: .PP
@b{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 '@minus{}' as the target.
This implementation only supports writing to stdout.
@comment TROFF INPUT: .SH "OPTIONS"
@node OPTIONS
@section OPTIONS
@c DEBUG: print_menu("OPTIONS")
@comment TROFF INPUT: .PP
@b{software@t{_}selections}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Refer to the software objects (products, filesets)
on which to be operated. (Not yet implemented)
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{targets}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Refers to the software@t{_}collection where the software
selections are to be applied.  To specify standard output
use a  dash '@minus{}', this overrides media@t{_}type setting to 'serial'.
Target may be a file system directory, or device file or '@minus{}'
Currently this implementation only supports a serial archive
written to stdout.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-f FILE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Reads software@t{_}selections from FILE. (Not implemented).
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-p}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-s PSF}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the PSF file, "@minus{}" is standard input.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-x option=value}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the extended option overriding the defaults file value.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-X FILE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-v}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
(Implementation extension.) Given one time it is identical to @minus{}x verbose=2.
This option can be given multiple times with increasing effect.
@comment TROFF INPUT: .br
@comment .br
     level 0: silent on stdout and stderr (not implemented).
@comment TROFF INPUT: .br
@comment .br
     level 1: fatal and warning messages.
@comment TROFF INPUT: .br
@comment .br
@minus{}v   level 2: level 1 plus file list and trailer message.
@comment TROFF INPUT: .br
@comment .br
@minus{}vv  level 3: level 2 verbose tar-like listing.
@comment TROFF INPUT: .br
@comment .br
@minus{}vvv level 4: level 3 extra verbose tar listing.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-b BYTES}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Set blocksize to BYTES number of bytes (octets).  The default is 10240.
(implementation extension)
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{@minus{}@minus{}version, @minus{}V}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Show version. (Implementation extension)
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{@minus{}@minus{}help}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Show help (Implementation extension)
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W option[,option,...]}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Specify the implementation extension option.
@comment TROFF INPUT: .br
@comment .br
Syntax: @minus{}W option[=option@t{_}argument[,option...]
@comment TROFF INPUT: .br
@comment .br
Options may be separated by a comma.  The implementation extension
options may also be given individually using the '@minus{}@minus{}long-option[=option@t{_}arg]' syntax.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W cksum}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Compute posix cksum of the individual files.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W file-digests}
@b{-W digests}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Compute md5 digests of the individual files.
(@minus{}W digests is deprecated, use @minus{}W file-digests).
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W files}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Store the distribution file list in .../dfiles/files.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W dir=NAME}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Use NAME as the path name prefix of a distribution and also
as the value of the distribution.control@t{_}directory and
distribution.tag attribute (if not set).  May be set to an
empty string to eliminate stray leading "./".
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W sign}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Compute the
md5sum, sha1sum and adjunct@t{_}md5sum digests
and sign the package.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W dummy-sign}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as @minus{}W sign except use a dummy signature.
The signer program is not run and no password is required.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W signer-pgm=SIGNER}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W archive-digests}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Compute the md5sum, sha1sum and adjunct@t{_}md5sum digests.
See sw(5) for info on the digest and signed data input files.
The sha1sum and md5sum attributes have identical input streams.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W no-sha1}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Do not compute the sha1 digest even if directed to by other options.
(Deprecated: There is limited reason to use this option).
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W signed-file}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Write only the signed data to the specified target but do not sign.
(Deprecated: There is limited reason to use this option).
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W gpg-name=NAME}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Use NAME as the user ID to sign.  NAME becomes the option arg of the gpg @minus{}@minus{}local-user option.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W gpg-path=PATH}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Use PATH as the gpg homedir.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W gzip}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Not implemented.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W bzip2}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Not implemented.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W source=FILE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W numeric-owner}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as GNU tar option.  Emitted archive has only uid and gids.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W absolute-names}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as GNU tar option.  Leading slash '/' are always stripped unless
this option is given.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W format=FORMAT}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
FORMAT is one of:
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
 ustar   is the POSIX.1 tar format capable of storing
         pathnames up to 255 characters in length.
         Identical to GNU tar 1.15.1 @minus{}@minus{}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 @minus{}@minus{}posix @minus{}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 @minus{}@minus{}format=gnu
 oldgnu  Identical to GNU tar version 1.13 and later with
             block size set to 1. i.e. with option @minus{}b1.
         Also identical to GNU tar 1.15.1 @minus{}@minus{}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 @minus{}b 512.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W create-time=TIME}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Applies to catalog files and the create@t{_}time attribute.
TIME is the seconds since the Unix Epoch.
You must use this option to make output
reproducible by different invocations.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W list-psf}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Write the PSF to stdout after having processed the extended
definitions.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W unrpm}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Same as @minus{}W 2posixformat
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W 2posixformat}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Read a package on standard input and write a POSIX
package on standard output.  Requires the
@comment TROFF INPUT: .../libexec/swbis/lxpsf program.
@comment .../libexec/swbis/lxpsf program.
Supported formats are any supported format of lxpsf.
Identical to:
@comment TROFF INPUT: .br
@comment .br
/swbis/lxpsf @minus{}@minus{}psf-form2 @minus{}H ustar | swpackage @minus{}Wsource=@minus{} @minus{}s@@PSF
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W passphrase-fd=N}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Read the passphrase on file descriptor N.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W passfile=FILE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W dir-owner=OWNER}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W dir-group=OWNER}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W dir-modep=MODE}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Set the file permissions mode of the leading directory archive member to MODE.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W catalog-owner=OWNER}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Set the owner of the catalog section to OWNER.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W catalog-group=GROUP}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Set the group of the catalog section to GROUP.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W files-from=NAME}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Read a list of files from file NAME.  Directories are not descended recursively.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W show-options-files}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Show the complete list of options files and if they are found.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W show-options}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Show the options after reading the files and parsing the command line options.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W no-catalog}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Do not write the catalog section.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-W no-front-dir}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
Do not write the directory archive members that preceed the catalog section.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "EXTENDED OPTIONS"
@node EXTENDED OPTIONS
@section EXTENDED OPTIONS
@c DEBUG: print_menu("EXTENDED OPTIONS")
@ifnottex
@menu
* Posix::
* Swbis Implementation::
@end menu
@end ifnottex
@comment TROFF INPUT: .PP
These extended options can be specified on the command line using the @minus{}x option
or from the defaults file, swdefaults.
@comment TROFF INPUT: .SS "Posix"
@node Posix
@subsection Posix
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
swpackage.distribution@t{_}target@t{_}directory  = /var/spool/sw   # Not used
swpackage.distribution@t{_}target@t{_}serial     = @minus{}        # Not used
swpackage.enforce@t{_}dsa                    = false    # Not used
swpackage.follow@t{_}symlinks                = false    # Not used
swpackage.logfile          = /var/lib/swbis/swpackage.log   # Not used
swpackage.loglevel                       = 1         # Not used
swpackage.media@t{_}capacity                 = 0         # Not used
swpackage.media@t{_}type                     = serial    # Not used
swpackage.psf@t{_}source@t{_}file                = @minus{}         # Not used
swpackage.software                       =           # Not used
swpackage.verbose                        = 1         # May be 1 2 or 3
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "Swbis Implementation"
@node Swbis Implementation
@subsection Swbis Implementation
@comment TROFF INPUT: .PP
These extended options can be specified on the command line using @minus{}Woption=optionarg
or @minus{}@minus{}option=optionarg syntax.
@comment TROFF INPUT: .PP
These options are set in the /usr/lib/swbis/swbisdefaults or the ~/.swbis/swbisdefaults
file.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
swpackage.swbis@t{_}cksum                    = "false"   # true or false
swpackage.swbis@t{_}file@t{_}digests             = "false"   # true or false
swpackage.swbis@t{_}files                    = "false"   # true or false
swpackage.swbis@t{_}sign                     = "false"   # true or false
swpackage.swbis@t{_}archive@t{_}digests          = "false"   # true or false
swpackage.swbis@t{_}gpg@t{_}name                 = ""
swpackage.swbis@t{_}gpg@t{_}path                 = "~/.gnupg"
swpackage.swbis@t{_}gzip                     = "false"   # true or false
swpackage.swbis@t{_}bzip2                    = "false"   # true or false
swpackage.swbis@t{_}numeric@t{_}owner            = "false"   # true or false
swpackage.swbis@t{_}absolute@t{_}names           = "false"   # true or false
swpackage.swbis@t{_}format                   = "ustar"  # gnutar or ustar
swpackage.swbis@t{_}signer@t{_}pgm               = "GPG" # GPG or PGP5 or PGP2.6
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "PACKAGE SIGNING"
@node PACKAGE SIGNING
@section PACKAGE SIGNING
@c DEBUG: print_menu("PACKAGE SIGNING")
@ifnottex
@menu
* Description::
* Signature Generation::
* Passphrase Handling::
@end menu
@end ifnottex
@comment TROFF INPUT: .PP
Support for embedded cryptographic signature.
@comment TROFF INPUT: .SS "Description"
@node Description
@subsection Description
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SS "Signature Generation"
@node Signature Generation
@subsection Signature Generation
@comment TROFF INPUT: .PP
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
@b{-Wsigner-pgm} command line option and the
@b{swpackage.swbis@t{_}signer@t{_}pgm} defaults file option.  The options and program can the displayed with the
@b{-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.
@comment TROFF INPUT: .SS "Passphrase Handling"
@node Passphrase Handling
@subsection Passphrase Handling
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SH "SIGNATURE VERIFICATION"
@node SIGNATURE VERIFICATION
@section SIGNATURE VERIFICATION
@c DEBUG: print_menu("SIGNATURE VERIFICATION")
@ifnottex
@menu
* Overview::
* Manual Verification::
* Manual Verification Using Standard Tools::
@end menu
@end ifnottex
@comment TROFF INPUT: .PP
swpackage does not perform verification of the embedded
cryptographic signature, although, a description is included here
for completness.
@comment TROFF INPUT: .SS "Overview"
@node Overview
@subsection Overview
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SS "Manual Verification"
@node Manual Verification
@subsection Manual Verification
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SS "Manual Verification Using Standard Tools"
@node Manual Verification Using Standard Tools
@subsection Manual Verification Using Standard Tools
@comment TROFF INPUT: .PP
Verification using standard GNU/Linux tools is possible if the archive is installed in the file system.
Success depends on the following factors:
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
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 @minus{}Wformat=gnutar or, @minus{}Wformat=ustar
   with no file name longer than 99 octets.
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 Recreating the signed and digested byte streams is then accomplished using GNU tar and the file list stored in
the \<@i{path}\>/catalog/dfiles/files attribute file as follows:
@comment TROFF INPUT: .PP
In this example, the package has a single path name prefix called, @b{namedir} and
the file owner/group are root.  These restrictions are suited to source packages.
@comment TROFF INPUT: .br
@comment .br
Verify the signature:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  tar cf @minus{} @minus{}b1 @minus{}@minus{}owner=root @minus{}@minus{}group=root \@tie{}
  @minus{}@minus{}exclude=namedir/catalog/dfiles/signature  \@tie{}
  namedir/catalog | gpg @minus{}@minus{}verify namedir/catalog/dfiles/signature @minus{}
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 If this fails try using GNU tar option @minus{}@minus{}posix.
If this fails then you are out of luck as nothing in the catalog section can be trusted.
@comment TROFF INPUT: .PP
Verify the payload digests:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  grep @minus{}v namedir/catalog  namedir/catalog/dfiles/files | \@tie{}
  tar cf @minus{} @minus{}b1 @minus{}@minus{}owner=root @minus{}@minus{}group=root \@tie{}
  @minus{}@minus{}files-from=@minus{} @minus{}@minus{}no-recursion | md5sum
  cat namedir/catalog/dfiles/md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 Likewise for the sha1 digest.
@comment TROFF INPUT: .PP
If the package has symbolic links, Verify the adjunct@t{_}md5sum:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
  #!/bin/sh
  grep @minus{}v namedir/catalog  namedir/catalog/dfiles/files | \@tie{}
  ( while read file; do if [ ! @minus{}h $file ]; then echo $file; fi done; )|\@tie{}
  tar cf @minus{} @minus{}b1 @minus{}@minus{}owner=root @minus{}@minus{}group=root \@tie{}
  @minus{}@minus{}files-from=@minus{} @minus{}@minus{}no-recursion | md5sum
  cat namedir/catalog/dfiles/adjunct@t{_}md5sum
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
 The symbolic link files must be verified manually by comparing to the INFO file
information.
@comment TROFF INPUT: .SH ""
@node
@section
@c DEBUG: print_menu("")
@ifnottex
@menu
* SWPACKAGE INPUT FILE FORMAT::
* 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::
@end menu
@end ifnottex
@comment TROFF INPUT: .SS "SWPACKAGE INPUT FILE FORMAT"
@node SWPACKAGE INPUT FILE FORMAT
@subsection SWPACKAGE INPUT FILE FORMAT
@comment TROFF INPUT: .PP
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].
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
Comments in a PSF are not transferred into the INDEX file by the swbis implementation of swpackage.
@comment TROFF INPUT: .PP
The file syntax is the same as a @b{INDEX}, or @b{INFO} file.
A PSF may contain all objects defined by the standard as well as extended definitions.
@comment TROFF INPUT: .br
@comment .br
For additional information see
@comment TROFF INPUT: .br
@comment .br
XDSA C701 http://www.opengroup.org/publications/catalog/c701.htm, or
@comment TROFF INPUT: .br
@comment .br
sw manual page.
@comment TROFF INPUT: .SS "EXTENDED DEFINITIONS"
@node EXTENDED DEFINITIONS
@subsection EXTENDED DEFINITIONS
@comment TROFF INPUT: .PP
A Product Specification File (PSF) can contain Extended Definitions in the
@b{fileset}, @b{product} or @b{bundle} software definitions.  They would have the same level or containment
relationship as a
@b{file} or
@b{control@t{_}file} definition in the same contaning object.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SS "o  Extended Control File Definitions"
@node o Extended Control File Definitions
@subsection o  Extended Control File Definitions
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
     checkinstall  @i{source}  [@i{path}]
     preinstall    @i{source}  [@i{path}]
     postinstall   @i{source}  [@i{path}]
     verify        @i{source}  [@i{path}]
     fix           @i{source}  [@i{path}]
     checkremove   @i{source}  [@i{path}]
     preremove     @i{source}  [@i{path}]
     postremove    @i{source}  [@i{path}]
     configure     @i{source}  [@i{path}]
     unconfigure   @i{source}  [@i{path}]
     request       @i{source}  [@i{path}]
     unpreinstall  @i{source}  [@i{path}]
     unpostinstall @i{source}  [@i{path}]
     space         @i{source}  [@i{path}]
     control@t{_}file  @i{source}  [@i{path}]
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
The @i{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
@i{tag} attribute
and tells the utilities when to execute the script.
The @i{path} attribute is optional and specifies the file name in the packages distribution
relative to the control@t{_}directory for software containing the script. If not given the
@i{tag} value is used as the filename.
@comment TROFF INPUT: .SS "o  Directory Mapping"
@node o Directory Mapping
@subsection o  Directory Mapping
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
   directory  @i{source}  [@i{destination}]
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
Applies the @i{source} attribute as the directory under which
the subsequently listed files are located.  If
@i{destination} is defined it will be used as a prefix to the
@i{path} (implied) file definition.
@i{source} is typically a temporary or build
location and
@i{dest} is its unrealized absolute pathname destination.
@comment TROFF INPUT: .SS "o  Recursive File Definition"
@node o Recursive File Definition
@subsection o  Recursive File Definition
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
  file *
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
Specifies every file in current source directory.
The @i{directory} extended definition must be used before the recursive specification.
@comment TROFF INPUT: .SS "o  Explicit File Definition"
@node o Explicit File Definition
@subsection o  Explicit File Definition
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
  file [@minus{}t @i{type}] [@minus{}m @i{mode}] [@minus{}o @i{owner}[,@i{uid}]] [@minus{}g @i{group}[,@i{gid}]] [@minus{}n] [@minus{}v] source [@i{path}]
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@b{source}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@comment TROFF INPUT: .PP
@i{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 @b{directory} keyword, if set.
If @b{directory} keyword is not set then the search is relative to the
current working directory of the swpackage utility's invocation.
@comment TROFF INPUT: .PP
All attributes for the destination file are taken from the source file, unless a
@b{file@t{_}permissions} keyword is active, or the @minus{}m, @minus{}o, or @minus{}g options are also
included in the file specification.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{path}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{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
@b{directory} keyword must be active and will be used as the path prefix.
If path is not specified then
@i{source} is used as the value of path and directory mapping applied (if active).
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-t type}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{type} may one of 'd' (directory), or  'h' (hard link), or 's' (symbolic link).
@comment TROFF INPUT: .PP
@minus{}t d  Create a directory.
@comment TROFF INPUT: .br
@comment .br
If @i{path} is not specified
@i{source} is used as the path attribute.
@comment TROFF INPUT: .PP
@minus{}t h  Create a hard link.
@comment TROFF INPUT: .br
@comment .br
@i{path} and @i{source} are specified.
@i{source} is used as the value of the
@i{link@t{_}source} attribute, and
@i{path} is the value of the path attribute.
@comment TROFF INPUT: .PP
@minus{}t s  Create a symbolic link.
@comment TROFF INPUT: .br
@comment .br
@i{path} and @i{source} are specified.
@i{source} is used as the value of the
@i{link@t{_}source} attribute, and
@i{path} is the value of the path attribute.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{-m mode}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{mode} defines the octal mode for the file.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "o  Default Permission Definition"
@node o Default Permission Definition
@subsection o  Default Permission Definition
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
  file@t{_}permissions [@minus{}m @i{mode}] [@minus{}u @i{umask}] [@minus{}o [@i{owner}[,]][@i{uid}]] [@minus{}g [@i{group}[,]][@i{gid}]]
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
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 @b{file@t{_}permissions} definitions
simply replace previous definitions (resetting all the options).
@comment TROFF INPUT: .PP
To reset the file@t{_}permission state (i.e. turn it off) use one of the following:
    file@t{_}permissions ""
@comment TROFF INPUT: .br
@comment .br
	or the preferred way is
@comment TROFF INPUT: .br
@comment .br
    file@t{_}permissions @minus{}u 000
@comment TROFF INPUT: .SS "o  Excluding Files"
@node o Excluding Files
@subsection o  Excluding Files
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
   exclude source
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
Excludes a previously included file or an entire directory.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SS "o  Including Files"
@node o Including Files
@subsection o  Including Files
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
   include <@i{filename}
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
The contents of @i{filename} may be more definitions for files.
The syntax of the included file is PSF syntax.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SS "SWBIS PSF CONVENTIONS"
@node SWBIS PSF CONVENTIONS
@subsection SWBIS PSF CONVENTIONS
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .SS "o Distribution Attributes"
@node o Distribution Attributes
@subsection o Distribution Attributes
@comment TROFF INPUT: .PP
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 @b{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
@b{product}.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
@b{tag}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{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@t{_}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 ''@minus{}W dir'' option.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{control@t{_}directory}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{control@t{_}directory}, in a distribution object, is the constant leading package path.
Providing this attribute is optional.
A distribution control@t{_}directory attribute and swpackage's response to it is an implementation extension.
The leading package path can also be controlled with the ''@minus{}W dir'' option.  This attribute will be
generated by swpackage if not set in a PSF.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "o Bundle Attributes"
@node o Bundle Attributes
@subsection o Bundle Attributes
@comment TROFF INPUT: .PP
A @b{bundle} defines a collection of products whether or not
the distribution has all the products present.
@comment TROFF INPUT: .PP
@b{tag}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "o Product Attributes"
@node o Product Attributes
@subsection o Product Attributes
@comment TROFF INPUT: .PP
A @b{product} defines the software product.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@b{tag}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{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@t{_}NAME attribute.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{control@t{_}directory}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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
@i{tag} is used.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{revision}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{vendor@t{_}tag}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
This is a short identifying name of the distributor that supplied the product and
associates the @b{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@t{_}software catalog (not as a path name component) by swinstall.
If this attribute exists there should also be a
@b{vendor} object in the PSF in the distribution object that has this tag.
This attribute is assigned the value of RPMTAG@t{_}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@t{_}RELEASE or "debian@t{_}revision" attributes.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "o Fileset Attributes"
@node o Fileset Attributes
@subsection o Fileset Attributes
@comment TROFF INPUT: .PP
A @b{fileset} defines the fileset.
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .PP
@b{tag}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
@i{tag} is the short, file system friendly, name of the fileset.
It is required.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@b{control@t{_}directory}
@comment TROFF INPUT: .RS
@c ---------------------------------------------------------------------
@quotation
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
@i{tag} is used.
@comment TROFF INPUT: .RE
@end quotation
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SS "o Example Source Package PSF"
@node o Example Source Package PSF
@subsection o Example Source Package PSF
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
 distribution
   description "fooit @minus{} a program from fooware
that does everything."
   title "fooit @minus{} a really cool program"
   COPYING < /usr/local/fooware/legalstuff/COPYING
 vendor
   the@t{_}term@t{_}vendor@t{_}is@t{_}misleading false
   tag fooware
   title fooware Consultancy Services, Inc.
   description ""
 vendor
   the@t{_}term@t{_}vendor@t{_}is@t{_}misleading true
   tag myfixes1
   title Bug fixes, Set 1
   description "a place for more detailed description"
 product
   tag fooit
   control@t{_}directory ""
   revision 1.0
   vendor@t{_}tag myfixes1  # Matches the vendor object above
 fileset
    tag fooit-SOURCE
    control@t{_}directory ""
    directory .
    file *
    exclude catalog
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "o Example Runtime (Binary) Package PSF"
@node o Example Runtime (Binary) Package PSF
@subsection o Example Runtime (Binary) Package PSF
@comment TROFF INPUT: .PP
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=* .
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .br
@comment .br
 distribution
   description "fooit @minus{} a program from fooware
that does everything."
   title "fooit @minus{} a really cool program"
   COPYING < /usr/local/fooware/legalstuff/COPYING
     vendor
        the@t{_}term@t{_}vendor@t{_}is@t{_}misleading false
        tag fooware
        title fooware Consultancy Services, Inc.
        description "Provider of the programs
 that do everything"
     vendor
        the@t{_}term@t{_}vendor@t{_}is@t{_}misleading true
         tag fw0
         title fooware fixes
         description "More fixes from the fooware users"
#  Bundle definition:  Use a bundle
     bundle
         tag fooit
         vendor@t{_}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@t{_}tag fw0 # This is a release name e.g. RPMTAG@t{_}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
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "SAMPLE PRODUCT SPEC FILES "
@node SAMPLE PRODUCT SPEC FILES
@section SAMPLE PRODUCT SPEC FILES
@c DEBUG: print_menu("SAMPLE PRODUCT SPEC FILES")
@ifnottex
@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 ::
@end menu
@end ifnottex
@comment TROFF INPUT: .PP
This section shows several example PSF files.
@comment TROFF INPUT: .SS "o   A minimal PSF to package all files in current directory."
@node o A minimal PSF to package all files in current directory
@subsection o   A minimal PSF to package all files in current directory.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
 distribution
 product
   tag prod
   control@t{_}directory ""
   revision 1.0
 fileset
    tag files
    control@t{_}directory ""
    directory .
    file *
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "o   A PSF that uses directory mapping."
@node o A PSF that uses directory mapping
@subsection o   A PSF that uses directory mapping.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
 distribution
 product
   tag somepackage  # this is the package name
   control@t{_}directory ""
   revision 1.0  # this is the package revision
 fileset
    tag files
    control@t{_}directory ""
    file@t{_}permissions @minus{}o root @minus{}g root
    directory swprogs /usr/bin
    file swpackage
    file swinstall
    file swverify
    file @minus{}m 755 @minus{}o root @minus{}g root / /usr/libexec/swbis
    directory swprogs /usr/libexec/swbis
    file swbisparse
    directory swsupplib/progs /usr/libexec/swbis
    file swbistar
    file @minus{}m 755 @minus{}o root @minus{}g root / /usr/share/doc/swbis
    directory . /usr/share/doc/swbis
    file @minus{}m 444 ./README
    file @minus{}m 444 CHANGES
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
When this PSF is processed by the command:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
            swpackage @minus{}Wsign @minus{}s @minus{} @@@minus{} | tar tvf @minus{}
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
It produces the following:
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
 drwxr-x@minus{}@minus{}- root/root      0 2003-06-03 ... catalog/
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root    307 2003-06-03 ... catalog/INDEX
 drwxr-x@minus{}@minus{}- root/root      0 2003-06-03 ... catalog/dfiles/
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root     65 2003-06-03 ... catalog/dfiles/INFO
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root     33 2003-06-03 ... catalog/dfiles/md5sum
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root     41 2003-06-03 ... catalog/dfiles/sha1sum
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root     33 2003-06-03 ... catalog/dfiles/adjunct@t{_}md5sum
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root    512 2003-06-03 ... catalog/dfiles/sig@t{_}header
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root   1024 2003-06-03 ... catalog/dfiles/signature
 drwxr-x@minus{}@minus{}- root/root      0 2003-06-03 ... catalog/pfiles/
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root     65 2003-06-03 ... catalog/pfiles/INFO
 @minus{}rw-r@minus{}@minus{}@minus{}@minus{}- root/root   1503 2003-06-03 ... catalog/INFO
 @minus{}rwxr-xr-x root/root 510787 2003-06-03 ... usr/bin/swpackage
 @minus{}rwxr-xr-x root/root 301255 2003-06-03 ... usr/bin/swinstall
 @minus{}rwxr-xr-x root/root   4105 2003-06-03 ... usr/bin/swverify
 drwxr-xr-x root/root      0 2003-06-03 ... usr/libexec/swbis/
 @minus{}rwxr-xr-x root/root 365105 2003-06-03 ... usr/libexec/swbis/swbisparse
 @minus{}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/
 @minus{}r@minus{}@minus{}r@minus{}@minus{}r@minus{}@minus{} root/root   8654 2003-05-27 ... usr/share/doc/swbis/README
 @minus{}r@minus{}@minus{}r@minus{}@minus{}r@minus{}@minus{} root/root  10952 2003-06-03 ... usr/share/doc/swbis/CHANGES
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SS "o   Create a PSF from a list of files."
@node o Create a PSF from a list of files
@subsection o   Create a PSF from a list of files.
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
           find . @minus{}print |  swpackage @minus{}Wfiles-from=@minus{} @minus{}Wlist-psf
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "SWPACKAGE OUTPUT FORMAT"
@node SWPACKAGE OUTPUT FORMAT
@section SWPACKAGE OUTPUT FORMAT
@c DEBUG: print_menu("SWPACKAGE OUTPUT FORMAT")
@comment TROFF INPUT: .PP
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 "@minus{}b1 @minus{}@minus{}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.
@comment TROFF INPUT: .PP
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 '@minus{}@minus{}format=oldgnu'.
Also supported is the gnu format of GNU tar 1.15.1 specified by '@minus{}@minus{}format=gnu'
@comment TROFF INPUT: .PP
The defacto cpio formats are also supported.
"new ASCII" (sometimes called SVR4 cpio) and "crc" cpio formats with header magic "070701" and "070702"
respectively.
@comment TROFF INPUT: .PP
Support for "pax Interchange Format" (Extended header tar) described in IEEE 1003.1-2001
under the "pax" manual page is planned.
@comment TROFF INPUT: .PP
The entirety of the output byte stream is a single valid file of one the formats mentioned above.
@comment TROFF INPUT: .PP
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.
@comment TROFF INPUT: .PP
The swbis implementation is biased, in terms of capability and default settings, to the tar format.
Package signing is only supported in tar format.
@comment TROFF INPUT: .SH "RETURN VALUE"
@node RETURN VALUE
@section RETURN VALUE
@c DEBUG: print_menu("RETURN VALUE")
@comment TROFF INPUT: .PP
0 on success, 1 on error and target medium not modified, 2 on error if
target medium modified.
@comment TROFF INPUT: .SH "SIDE EFFECTS"
@node SIDE EFFECTS
@section SIDE EFFECTS
@c DEBUG: print_menu("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.
@comment TROFF INPUT: .SH "ENVIRONMENT"
@node ENVIRONMENT
@section ENVIRONMENT
@c DEBUG: print_menu("ENVIRONMENT")
@comment TROFF INPUT: .PP
The environment variable SWPACKAGEPASSFD sets the passphrase file descriptor
(See option @minus{}Wpassphrase-fd).
@comment TROFF INPUT: .SH "REQUISITE UTILITIES"
@node REQUISITE UTILITIES
@section REQUISITE UTILITIES
@c DEBUG: print_menu("REQUISITE UTILITIES")
@comment TROFF INPUT: .PP
Swpackage does not use any archive writing utilities, it has its own code to
generate archives.
@comment TROFF INPUT: .br
@comment .br
Package signing uses one of the following:
 /usr/bin/gpg
 /usr/bin/pgp   (PGP 2.6.x)
 /usr/bin/pgps  (PGP 5)
@comment TROFF INPUT: .PP
Swpackage will use /usr/bin/uuidgen if present to create the uuid.
@comment TROFF INPUT: .SH "FILES"
@node FILES
@section FILES
@c DEBUG: print_menu("FILES")
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .nf
@c ---------------------------------------------------------------------
@display
libdir/swbis/swdefaults
libbir/swbis/swbisdefaults
$HOME/.swbis/swdefaults
$HOME/.swbis/swbisdefaults
@comment TROFF INPUT: .fi
@end display
@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP
@comment TROFF INPUT: .SH "APPLICABLE STANDARDS"
@node APPLICABLE STANDARDS
@section APPLICABLE STANDARDS
@c DEBUG: print_menu("APPLICABLE STANDARDS")
@comment TROFF INPUT: .PP
ISO/IEC 15068-2:1999, Open Group CAE C701.
@comment TROFF INPUT: .SH "SEE ALSO"
@node SEE ALSO
@section SEE ALSO
@c DEBUG: print_menu("SEE ALSO")
@comment TROFF INPUT: .PP
info swbis
@comment TROFF INPUT: .PP
sw(5), swpackage(5), swbisparse(1), swign(1), swverify(8)
@comment TROFF INPUT: .SH "IDENTIFICATION"
@node IDENTIFICATION
@section IDENTIFICATION
@c DEBUG: print_menu("IDENTIFICATION")
 swpackage(8): The packaging utility of the swbis project.
 Author: Jim Lowe   Email: jhlowe at acm.org
 Version: swbis 0.481
 Date: 2006-02-15
 Copying: GNU Free Documentation License
@comment TROFF INPUT: .SH "BUGS"
@node BUGS
@section BUGS
@c DEBUG: print_menu("BUGS")
@comment TROFF INPUT: .PP
A comment after an object keyword is wrongly not allowed by this PSF parser.
The @minus{}@minus{}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.
@comment  created by instant / docbook-to-man, Sun 19 Feb 2006, 20:52
@bye
