\input texinfo   @c -*-texinfo-*-
@setfilename swign.info

@comment ===============================================================
@comment WARNING: Do NOT edit this file.  It was produced automatically
@comment by man2info on Sat Nov  5 15:41:27 EST 2005
@comment for jhl@
@comment from man/man1/swign.1
@comment in /home/jhl/swbis-0.473/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 "swign" "1"

@headings off
@everyheading SWIGN(1) @| @| SWIGN(1)
@everyfooting  @| @thispage @|

@node Top

@chapter swign" "1
@c DEBUG: print_menu("Top")

@ifnottex
@menu
* NAME::
* SYNOPSIS::
* DESCRIPTION::
* OPTIONS::
* EXTERNAL EFFECTS::
* TESTING::
* ENVIRONMENT::
* RETURN VALUE::
* FILES::
* SEE ALSO::
* IDENTIFICATION::
* BUGS::

@end menu
@end ifnottex


@comment TROFF INPUT: .SH "NAME"

@node NAME

@section NAME
@c DEBUG: print_menu("NAME")

swign @r{---} Tar archive signing utility for source distributions.
@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{swign} [options] [@minus{}u gpg-name] [@minus{}@minus{}homedir=gpg-homedir] @@@minus{}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
@b{swign} @minus{}S [options] [@minus{}u gpg-name] [@minus{}@minus{}homedir=gpg-homedir]
@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{swign} loads a signed metadata catalog file into the current directory and then,
using GNU tar and the distribution file list, writes the archive to stdout.
The contents of the archive is the contents of the current directory ".".
The pathnames in the archive are prefixed by the directory name of ".".
The owner and group of all the files in the emitted archive are
specified by the PSF file and command line options.
@comment TROFF INPUT: .PP

If a PSF is provided using the @minus{}s option then the specified ownership
must be consistent with the 'swign' command line options for ownerships
otherwise the signature will not be valid.  The default ownerships for all the files
are the current user's owner and group.
If the @minus{}o (or @minus{}g) option is used with a empty string for the option arg
then the file ownerships of the source files are used.
This script assumes GNU tar is installed.
@comment TROFF INPUT: .PP

After writing the ./catalog/ file and before writing the archive, the file list stored in ./catalog/dfiles/files is compared
to the current directory contents, if any difference is found the
archive is not written and error returned.
@comment TROFF INPUT: .SH "OPTIONS"

@node OPTIONS

@section OPTIONS
@c DEBUG: print_menu("OPTIONS")

@comment TROFF INPUT: .PP

@b{@minus{}@minus{}help}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
show help.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{@minus{}@minus{}psf}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
show the PSF to stdout, and then exit.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-u, @minus{}@minus{}local-user name}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Use name as the user ID to sign.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{@minus{}@minus{}homedir=DIR}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Set the name of the home directory to DIR.  If not specified
then use "~/.gnupg".
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-s, @minus{}@minus{}source=FILE}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Specify a PSF or '@minus{}' for stdin.  If this is not given then the internally
generated PSF is used.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-T, @minus{}@minus{}show-names-only}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
show some info (for help and debugging) and exit.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-t, @minus{}@minus{}run-sanity-check}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Instead of writing stdout, write the archive to ../packageDirName.swigntest.tar.gz and run some sanity tests.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-S, @minus{}@minus{}sign-this}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Write the ./catalog/ file containing the digest and signature into "." and then exit without
writing the archive to stdout.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-D, @minus{}@minus{}with-checksig FILE}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Include the checksig control script sourced from FILE.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-o, @minus{}@minus{}owner OWNER}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Specify owner.
Use an empty string "" to specify the source file owner.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-g, @minus{}@minus{}group GROUP}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Specify group.
Use an empty string "" to specify the source file group.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{-x format}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Specify the archive format.
Must be one of the formats of swpackage.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@b{@@@minus{}}
@comment TROFF INPUT: .RS

@c ---------------------------------------------------------------------
@quotation
Target, only supported target is standard output.
@comment TROFF INPUT: .RE

@end quotation

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .SH "EXTERNAL EFFECTS"

@node EXTERNAL EFFECTS

@section EXTERNAL EFFECTS
@c DEBUG: print_menu("EXTERNAL EFFECTS")

@comment TROFF INPUT: .PP

The program will remove and replace a file in "." named ./catalog/.
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .br
@comment .br
When using the '@minus{}t' option an archive file is written to ../packageDirName.swigntest.tar.gz
@comment TROFF INPUT: .br
@comment .br
@comment TROFF INPUT: .SH "TESTING"

@node TESTING

@section TESTING
@c DEBUG: print_menu("TESTING")

@comment TROFF INPUT: .PP

After running successfully with options
@b{-S}  and
@b{-D FILE}  the following should be true (report no error).
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
          swverify @minus{}@minus{}checksig .
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

Similarly,
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
          swign @minus{}u gpgname @@@minus{} | swverify @minus{}@minus{}checksig @minus{}
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

If a checksig script is included then you should unpack the package at a
new location and run  swverify @minus{}@minus{}checksig "." in the new location.
@comment TROFF INPUT: .PP

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

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
       swign @minus{}D $HOME/checksig.sh @minus{}u "Test User" @minus{}o "" @minus{}g "" @minus{}S;
       swverify @minus{}d @@.
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@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.
@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, non-zero on failure.
@comment TROFF INPUT: .SH "FILES"

@node FILES

@section FILES
@c DEBUG: print_menu("FILES")

@comment TROFF INPUT: .br
@comment .br
  \<@i{path}\>/@b{catalog}/
@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

swpackage(8), gpg
@comment TROFF INPUT: .SH "IDENTIFICATION"

@node IDENTIFICATION

@section IDENTIFICATION
@c DEBUG: print_menu("IDENTIFICATION")

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .PP

@comment TROFF INPUT: .nf

@c ---------------------------------------------------------------------
@display
 swign(1): The source directory signing utility of the swbis project.
 Author: J. Lowe jhlowe@@acm.org
 Version: 0.473
 Date: 2005-11-05
 Copying: GNU Free Documentation License
@comment TROFF INPUT: .fi

@end display

@c ---------------------------------------------------------------------
@comment TROFF INPUT: .PP

@comment TROFF INPUT: .SH "BUGS"

@node BUGS

@section BUGS
@c DEBUG: print_menu("BUGS")

@comment TROFF INPUT: .PP

If a directory is signed using the '@minus{}S' option and has a file path greater than
99 chars in length then it will be unverifiable if the 'ustar0' format and
GNU tar 1.13.25 was used.
@comment TROFF INPUT: .PP

Verification of the directory form of a distribution (i.e. the installed tarball
path name prefix) such as running 'swverify @minus{}d @@.' after running 'swign @minus{}S'
will fail if the order of directory entries is not compatible with
traditional Unix file system directory entry ordering.  This incompatibility may be present in
the Ext3, reiserFS, and DarwinOS et.al file systems.
@comment TROFF INPUT: .PP

Use of the '@minus{}o USER @minus{}g GROUP' is dependent on the checksig script.
The default file ownership policies of this program are suited to packaged products
where file user and group ownerships are not a critical feature.
@comment  created by instant / docbook-to-man, Sat 05 Nov 2005, 15:41
@bye
