From: Jacob Bachmeyer Date: Sat, 8 Oct 2022 03:40:31 +0000 (-0500) Subject: Move more of the old comment blocks into POD X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=743c4343b6648a9701607fb34bd354e804fd560d;p=gatekeeper.git Move more of the old comment blocks into POD --- diff --git a/gatekeeper.pl b/gatekeeper.pl index 62dbf9f..ae078e2 100755 --- a/gatekeeper.pl +++ b/gatekeeper.pl @@ -1,27 +1,11 @@ #!/usr/bin/perl -Tw -# -# Take files that have been uploaded via ftp and move them into place on -# ftp.gnu.org. -# - - -# This program is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program. If not, see . +# This program is free software; +# see the "LICENSE" POD section at the end for the full details. =head1 NAME -gatekeeper - process uploaded files +gatekeeper - select properly signed uploads and move them into place =head1 SYNOPSIS @@ -71,92 +55,111 @@ Used for system distributions hosted or mirrored on ftp.gnu.org. =back +There are also intentionally undocumented options, which can be found in +the source code. + =head1 DESCRIPTION -... +The full reference documentation for this system will be a Texinfo manual +that has not yet been written. The below is a short overview. -=cut +=head2 Uploaded files +We expect to find (1) a directive file, specifying the directory to +store into (syntax details later); (2) the actual file to be +distributed (no signature); (3) a detached signature for (2). + +For instance: + +=over + +=item foo-1.2.tar.gz.directive.asc + +Signed (gpg --clearsign) ASCII text about what to do with the other two +files. + +=item foo-1.2.tar.gz + +The file to upload (could be anything) with no sig. + +=item foo-1.2.tar.gz.sig + +Detached binary signature (gpg -b) for uploaded file. + +=back + +The directive file in a triplet must always contain 'directory', +'version' and 'filename' directive elements. + +=head2 Other directives + +Alternatively, we expect to find only a directive file. This file must have +a name that ends in 'directive.asc', and must contain one or more of these +elements: 'symlink', 'rmsymlink' and 'archive', in addition to the obligatory +'directory' and 'version' elements. A 'filename' element is not allowed. + +Any number of 'comment' elements are always allowed. + +=head2 Permissions + +Permissions for directives are controlled on a per package basis. For each +package, one or more seperate GPG public keyrings are maintained. All +signed files that are part of a triplet must be signed by a permitted key +for the specific package named in the directive file. Each package is only +allowed write access to its own directory (with the same name as the +package) within the public ftp hierarchy. Write access to subdirectories of +that directory is allowed. Limiting write access to specific directories on +a per package basis minimizes the impact from the compromise of a +maintainer's GPG private key. The public keyrings form a hierarchy where +keys in superdirectories can apply to files uploaded to +subdirectories. Example: + + Jim can only upload to aspell/dict/en so his key is located in + packages/aspell/dict/en/pubring.gpg. Paul can upload to any aspell + directory so his key is in packages/aspell/pubring.gpg. When Paul + uploads a file to aspell/dict/en it looks for his key in + packages/aspell/dict/en/pubring.gpg first, then finds it in + packages/aspell/pubring.gpg. + +=head2 Package Configuration + +Package configuration files are: + +=over + +=item 1. $package_config_base/$package_name/pubring.gpg + +GNUPG public keyring. For a given package, the directive file and file to +be uploaded, must be signed with a key from the package's keyring. If a +file is to be uploaded into a subdirectory of the package directory, the +subdirectory in the package config directory will be checked for a +pubring.gpg first, going up to the parent directory until a match is found. + +=item 2. $package_config_base/$package_name/email + +Email addresses that are sent mail when uploads succeed or fail for a given +package. One email address per line. + +=back + +=head2 Other Notes + +This is written for use with ftp instead of as a cgi script because we +don't want to run an httpd on ftp.gnu.org. In general, it tries to do +the minimum possible. + +We execute gpgv, lsof, mkdir, mv, pwd and tar. Executions are such that +it's not possible for the shell to be invoked. We make use of Perl +module Net::SMTP to send email. + +TODO: actually avoid using the shell; the current code does use the shell. + +=cut -# -# Short overview -# -# We expect to find (1) a directive file, specifying the directory to -# store into (syntax details later); (2) the actual file to be -# distributed (no signature); (3) a detached signature for (2). -# -# For instance: -# foo-1.2.tar.gz.directive.asc, signed (gpg --clearsign) ASCII text -# about what to do with the other two files. -# foo-1.2.tar.gz, the file to upload (could be anything) with no sig. -# foo-1.2.tar.gz.sig, detached binary signature (gpg -b) for uploaded file. -# -# The directive file in a triplet must always contain 'directory', -# 'version' and 'filename' directives. -# -# Alternatively, we expect to find only a directive file. This file must have -# a name that ends in 'directive.asc', and must contain one or more of these -# directives: 'symlink', 'rmsymlink' and 'archive', in addition to the obligatory -# 'directory' and 'version' directives. A 'filename' directive is not allowed. -# -# A 'comment' directive is always allowed. -# -# Permissions of directives are controlled on a per package basis. For each -# package, one or more seperate GPG public keyrings are maintained. All signed -# files that are part of a triplet must be signed by a permitted key for the -# specific package named in the directive file. Each package is only allowed -# write access to its own directory (with the same name as the package) within -# the public ftp hierarchy. Write access to subdirectories of that directory is -# allowed. Limiting write access to specific directories on a per package basis -# minimizes the impact from the compromise of a maintainer's GPG private key. The -# public keyrings form a hierarchy where keys in superdirectories can apply to -# files uploaded to subdirectories. Example: -# -# Jim can only upload to aspell/dict/en so his key is located in -# packages/aspell/dict/en/pubring.gpg. Paul can upload to any aspell -# directory so his key is in packages/aspell/pubring.gpg. When Paul -# uploads a file to aspell/dict/en it looks for his key in -# packages/aspell/dict/en/pubring.gpg first, then finds it in -# packages/aspell/pubring.gpg. -# -# Package config files are: -# 1. $package_config_base/$package_name/pubring.gpg -# GNUPG public keyring. For a given package, the directive -# file and file to be uploaded, must be signed with a key from -# the package's keyring. -# If a file is to be uploaded into a subdirectory of the package -# directory, the subdirectory in the package config directory will -# be checked for a pubring.gpg first, going up to the parent directory -# until a match is found. -# 2. $package_config_base/$package_name/email -# Email addresses that are sent mail when uploads succeed or -# fail for a given package. One email address per line. -# -# This is written for use with ftp instead of as a cgi script because we -# don't want to run an httpd on ftp.gnu.org. In general, it tries to do -# the minimum possible. -# -# We execute gpgv, lsof, mkdir, mv, pwd and tar. Executions are such that -# it's not possible for the shell to be invoked. We make use of Perl -# module Net::SMTP to send email. -# ## Currently, this script is executed by cron as: # MAILTO=ftp-upload-script@gnu.org # SHELL=/bin/bash # * * * * * gatekpr /home/gatekpr/upload-ftp.pl -s ftp; /home/gatekpr/upload-alpha.pl -s alpha; /home/gatekpr/upload-distros.pl -s distros -# -# Originally written by Karl Berry (karl@gnu.org), October 2003. -# Additional changes by Paul Fisher (rao@gnu.org), November 2003 -# Additional functionality (v1.1) by Ward Vandewege (ward@gnu.org), May 2004 -# Additional changes (syslog) by Justin Baugh (baughj@gnu.org), August 2005 -# Additional testing, bugfixes and functionality by Ward Vandewege (ward@gnu.org), Apr 2006 - Jan 2013 -# Additional changes (update ftpindex) by Ruben Rodriguez (ruben@gnu.org), September 2017 -# Imported into Git by Jacob Bachmeyer (jcb@gnu.org), July 2020 -# Further changes are tracked in Git. - -# The CheckVulnerabilities module written by Jim Meyering -# and Ward Vandewege with internal -# timestamp 2013/01/23 20:26:29 was merged into this main script. use strict; use warnings; @@ -1800,3 +1803,32 @@ cleanup_dir($incoming_tmp); exit 0; __END__ + +=head1 AUTHORS + +These are the known authors and/or major contributors from before this +program was imported into Git: + +Karl Berry (karl@gnu.org), Paul Fisher (rao@gnu.org), Ward Vandewege +(ward@gnu.org), Justin Baugh (baughj@gnu.org), Jim Meyering +(meyering@redhat.com), and Ruben Rodriguez (ruben@gnu.org) + +Jacob Bachmeyer (jcb@gnu.org) imported the code and such history as was +available into Git. His and later contributions are tracked in Git. + +=head1 LICENSE + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . + +=cut