Finish refactoring of gather_packets/scan_incoming to use absolute names

This eliminates the need to change to the incoming directory and is a
step towards a goal of eliminating any dependency on the current directory
and presenting only absolute file names to the system.

Refactor scan_incoming as helper for gather_packets

The old scan_incoming function was very long and performed two related
but distinct tasks:  collecting a list of files eligible for processing
and collecting those files into packets.  The new scan_incoming now only
produces a list of files; the second loop to collect files into packets
has been moved to a new gather_packets function.

Improve comments

Update testsuite for terminology change

The original concept of "triplets" is now generalized to "packets" that
can contain any number of files.

Revise packet-gathering loop in scan_incoming

Since every packet must contain a directive, the process is now driven
based on the set of directives available.  This change also avoids
considering every file and fixes a related minor bug in the old code:
comments indicated that all files from each triplet were supposed to be
removed from possible consideration, but the loop was actually iterating
over a temporary list containing the keys of the %possible hash as of the
start of the loop.

This change also introduces a new internal format for the result of the
scan_incoming function and some temporary scaffolding code to convert the
new format to the old format to keep the tool working during the change.

Discard names of trash files immediately after unlink

Add comment describing expected issue on modern GNU/Linux

Improve comments in scan_incoming

Revise check for open files in scan_incoming

The old code would incorrectly assume that no files are open if the
lsof program fails to run; this new code uses a list-form pipe open
introduced in Perl 5.8.0 instead of an implied fork.

Also use File::Spec to form the arguments to lsof.

Check file sizes while scanning directory in scan_incoming

Excessively large directive and signature files are now detected while
scanning the incoming files directory and promptly removed afterward;
the testsuite is adjusted accordingly.

Check timestamps while scanning directory in scan_incoming

Recent files are now filtered out very early, before checking if they
are open; the testsuite is adjusted accordingly.

Revise directory scanning loop in scan_incoming

Files with unacceptable names are now removed immediately after scanning
the incoming files directory; the testsuite is adjusted accordingly.

Use arguments instead of globals in scan_incoming

Also move the declaration of the return array.

Use symbolic constants for limits in scan_incoming

Remove comment that does not accurately describe the code

Explicitly return empty list from scan_incoming if no files found

Remove redundant checks on symlink and archive commands

The tighter file name patterns now exclude ".." name components, so
these branches are now dead code.

Collect file name validation patterns

This results in some small semantic changes:  the new patterns are
stricter in handling symlink arguments and slightly looser for the
directory line.  However, this improves consistency, since the old
patterns could imply directories that could not be directly named.

Reduce the visibility of the log style global

While $Log_Style is now a global variable, the use of "strict" means that
it is only accessible in lexical scopes where it has been aliased using
the "our" feature.  These are limited, therefore reducing its scope from
a file-scope quasi-global lexical to only the initialization code and the
ftp_syslog function, where it is actually used.

Eliminate version_information sub that was called exactly once

Import GPLv3 license text as COPYING.GPLv3

Add initial shared directive-reading functions

Move more of the old comment blocks into POD

Use Pod::Usage and begin to develop internal documentation in Perl POD

POD is Perl's native documentation format, designed to embed an
approximate equivalent to a man page inside a Perl program or module.
POD can be particularly useful for docstring-like embedded per-function
documentation but has a different purpose from Texinfo, which will be
used when a reference manual is written.

Finish integration of CheckVulnerabilities code

Remove version 1.0 compatibility mode

Refactor log style tag into ftp_syslog

This removes references to $log_style at every call site and collects a
single reference to the renamed $Log_Style global in the ftp_syslog sub.

Fill long lines in gatekeeper script

Also update testsuite to recognize a message changed by this operation.

Emit stack backtrace if syslog call fails

Revise display of usage information

The script now reports success if run with the --help option.

Use Perl's "or" in conditionals used for control flow

Fix oversight with location of logging definitions

Revise syslog initialization in gatekeeper script

This reflects the renaming of the script and moves the syslog details to
one place nearer the top of the file.

The "ndelay" option could be added to the openlog call, but would be
redundant, as the script immediately logs its own startup.

Normalize argument unpacking in gatekeeper script

This shifts arguments out of @_ one at a time in each sub and also
removes a few cases of setting lists containing only one variable.

Update old-style sub calls in gatekeeper script

Merge CheckVulnerabilities module into main script

Move syslog initialization and final configuration check to preliminaries

This also required moving the message reporting subs farther up, since
this code uses ftp_syslog and ftp_die.

Remove sub main in gatekeeper script

Unlike C, Perl allows program code to simply appear at the top level of
the file.  Using this feature is the standard convention in Perl.

Reorganize gatekeeper script to sort subs ahead of their callers

Prior to committing, this was validated with:
(DIFF='git diff --cached';
 comm -3 <($DIFF | grep ^- | sed -e 's/^-//' | sort) \
         <($DIFF | grep ^+ | sed -e 's/^+//' | sort) )

The output shows only blank lines, comments, and a diff header were
added, and only a diff header removed, after all lines are sorted
and paired for analysis.  To replicate, change the "git diff" command
to compare this commit with its parent.

Document change of script name and update copyright years

Fix prototype on ftp_die in gatekeeper script

Currently, this prototype has no effect because the entire script has been
compiled before it is seen.  Moving ftp_die to near the beginning of the script
will cause the prototype to be checked and the incorrect prototype causes
compilation to fail.

Rename the upload-ftp tool to "gatekeeper" and update symlinks

At this time, the tool still reports as "ftp-upload" in syslog.

Remove old version of upload-ftp script

Import existing script generate-ftpindex.sh

Work around Expect bug

Improve handling of test environments in upload testsuite

This removes the argument to the new_test_environment procedure.

Clean up scratchpad files in mock tool testsuite

Remove Emacs time-stamp configuration

The files are now tracked in Git and the actual timestamp was removed
long ago -- the oldest version in the repository does not have it.

Add test for rejection of future directive signature timestamp

Correctly handle both old and new signature timestamps from GPG

Add debugging message reporting directive signature timestamp

Fix critical bug in symlink command handling found during testing

Previously, while symlink targets were checked for the string "..", symlink
names were unchecked; this allowed symlinks to be placed outside of the
permitted areas for which the signing key is authorized and even outside of the
managed file tree, requiring only that the containing directory already exist.
The test case places a symlink directly into the top-level pub/ directory to
demonstrate the issue and confirm that it is fixed.

I consider this bug critical because while the rogue symlink can only refer to
something else at or below its own location, it could replace an existing
symlink.  While I do not expect that this provides any way to crack system
security, careful misuse could certainly cause considerable nuisance, possibly
breaking the entire system if an attacker can find a symlink that is critical
for the system's operation and replace it with a dangling symlink.

Add more tests for loose directives to improve coverage

Add more tests for misconfigured package scenarios

Add more tests for invalid directives in triplets

Change DEBUG, NOMAIL, TSTAMPCHECK mode flags to constants

This simplifies coverage analysis reports, since these flags are only set
while initializing the script and never changed during a run.

Add tests for oversize directive and signature files

Improve log messages for oversize directive or signature files

The new messages are easier for the testsuite to match.

Add idle processing tests for recent uploads

Add infrastructure for testsuite coverage analysis

Tidy whitespace

Add tests for Automake vulnerability filter logic

Add tests for basic triplet handling

Ensure that upload handler syslog messages do not span lines

Meet taint mode requirements for handling test SMTP port

fix for gpgv upgrade 1.4 to 2.2.4

Clean up whitespace using Emacs

Include more information in the test log

Previously, the analyze_file_tree procedure stopped immediately when a
tree that was expected to be empty was found to contain files.  This
change causes a full list of the files found to appear in the log.

Add testsuite support for building tarballs for test cases

Add initial partial testsuite

This does not yet check actual upload handling, but the testsuite
infrastructure seems to be sufficiently developed at this point that no
major changes should be needed to support further tests.

Add "no-op" command for testing uses

This command is only recognized in test mode.

Improve recognizability of debugging message for testsuite

Avoid running generate-ftpindex during tests

The attempt to rebuild the FTP server index is normally harmless, since most
test machines will not actually have /usr/local/bin/generate-ftpindex and the
error from the inability to execute that tool is ignored anyway.

However, if the testsuite is ever actually run on the FTP upload server, this
will prevent a large amount of spurious work rebuilding the FTP indexes.

Use special tag for log messages in testing mode

Demote severity of debugging message and indicate message type

This change enables the testsuite to reliably recognize this message
instead of guessing with heuristics.  The message severity was demoted
to 'debug' because the message is only emitted in debugging mode.

Use constant for name of lsof executable to enable testing with mock

Add infrastructure for generic mock tools

Include state files in the test case directory

Add mock gpgv signature verification tool and mock tool testsuite

Ignore DejaGnu output files and scratchpad used with testsuite

Tidy minor details

Update copyright notice and rearrange test configuration to follow the
locations of files in lifecycle order.

Log startup/shutdown in mock syslog server

Relax parsing of RFC3164 syslog message format

Override configuration directories in testing mode

Use constant for name of gpgv executable to enable testing with mock gpgv

Improve shutdown logic in mock syslog server

Handle non-RFC-conforming end-of-message markers

RFC3164 states in 4.1.3 "MSG Part of a syslog Packet":
  The MSG part will fill the remainder of the syslog packet.
  ...
  There is no ending delimiter to this part.

Some implementations do not follow this.

Tidy whitespace

Announce output destination in mock syslog server

Meet taint mode requirements for handling test syslog socket name

Handle missing HOSTNAME field in mock syslog server

Add initial scaffolding for testing mode in upload-ftp script

Add initial support skeleton code for DejaGnu testsuite

Add initial mock SMTP and syslog servers

Emergency fix:  do not run with '.' in @INC

Report module search path with version information

Restore comments omitted during initial re-import

I, Jacob Bachmeyer, did this work, but the comments are presumed to have been
originally added by Ian Kelling, therefore I have listed him as the author of
this commit.

Clean up whitespace using Emacs

Add revised example of maintainers.bypkg file

docs