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

Import version as of 2019-04-03 for upload-ftp-v1.2.pl

Import version as of 2019-04-03 for upload-ftp-v1.2.pl

Import symlink as of 2018-11-19 for upload-ftp.pl

Import version as of 2013-05-14 for upload-ftp-v1.2.pl

Import version as of 2013-03-21 for upload-ftp-v1.2.pl

Import version as of 2013-03-21 for CheckVulnerabilities.pm

Import version as of 2012-12-10 for send-gpg-public-keys.sh

Import symlink as of 2012-09-21 for upload-distros.pl

Import symlink as of 2012-09-21 for upload-alpha.pl

Import version as of 2012-09-21 for upload-ftp-v1.2.pl

Import version as of 2012-08-14 for upload-ftp-v1.1.pl

Import version as of 2012-05-18 for upload-ftp-v1.1.pl

Import version as of 2012-04-20 for build-keyring.pl

Import version as of 2012-04-03 for upload-ftp-v1.1.pl

Import version as of 2011-10-05 for upload-ftp-v1.1.pl

Import version as of 2011-09-29 for upload-ftp-v1.1.pl

Import version as of 2011-08-11 for ftp-addkey.sh

Import version as of 2011-08-11 for pgpg

Import version as of 2011-07-29 for upload-ftp-v1.1.pl

Import version as of 2011-04-11 for get-maintainers-file.sh

Import version as of 2011-02-08 for upload-ftp-v1.1.pl

Import version as of 2010-08-02 for upload-ftp-v1.1.pl