make README be a basic overview of this package

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..c2bc685
--- /dev/null
+++ b/README
@@ -0,0 +1,120 @@
+The Secure Software Gatekeeper
+
+or just gatekeeper for short.
+
+For a software releases website like https://ftp.gnu.org, this program:
+
+* Securely authorizes package maintainers to publish new releases and
+  manage existing files via uploading GPG signed releases and text files
+  containing directive commands (there is no managing of any other kind
+  of of authorization secret like a login password).
+
+* Does basic checks to prevent mistakes and publication of software
+  containing a some easily detected security vulnerabilities.
+
+* Sends email notifications to mailing list and maintainers to stay
+  informed of what is going on.
+
+* Uses publication conventions that Software Heritage supports for
+  copying into their archive.
+
+History and status:
+
+It was originally written just to run on the GNU releases sever (aka the
+GNU ftp) in 2003 and it has been in use on that server ever since. In
+2021, Jacob Bachmeyer took on the task of turning it into a general
+purpose free software program, with the assistance of FSF sysadmin Ian
+Kelling.
+
+It has yet to have an official public release, but we hope to do that in
+the 1st half of 2023. It is primarily missing documentation, central
+configuration, and a lot of polish. It has undergone a security review,
+it has a comprehensive test suite, and it has been heavily refactored
+for general code quality.
+
+The GNU project plans to adopt this program as a GNU package once it is
+ready for it's first release.
+
+Patches are welcome, send them to:
+Jacob Bachmeyer <jcb@gnu.org>, Ian Kelling <iank@fsf.org>
+
+
+How it works:
+
+The process from the
+uploader's perspective is best documented here:
+https://www.gnu.org/prep/maintain/html_node/Automated-FTP-Uploads.html#Automated-FTP-Uploads
+
+On the server, there are a set of software packages that each gets a
+directory and a set of maintainer's GPG keys that are authorized to sign
+and publish releases. This program enforces that authorization via GPG
+signature validation, without the need for any separate secret like an
+ssh key or password, by using anonymous ftp uploads.
+
+
+
+Basic incomplete documentation:
+
+The server should run an anonymous ftp for uploads. Vsftp is what we
+know works. It can run under xinetd or an init, an example
+configuration:
+
+/etc/vsftpd-upload.conf:
+listen=NO
+anonymous_enable=YES
+write_enable=YES
+anon_upload_enable=YES
+seccomp_sandbox=NO
+dirmessage_enable=YES
+xferlog_enable=YES
+connect_from_port_20=YES
+chown_uploads=YES
+chown_username=gatekpr
+xferlog_file=/var/log/vsftpd-upload.log
+xferlog_std_format=YES
+log_ftp_protocol=YES
+ftpd_banner=GNU Upload FTP server ready.
+one_process_model=NO
+no_anon_password=YES
+ftp_username=upload
+lock_upload_files=YES
+secure_chroot_dir=/var/run/vsftpd
+pam_service_name=vsftpd
+rsa_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
+rsa_private_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
+pasv_min_port=20000
+pasv_max_port=29999
+
+/etc/passwd:
+gatekpr:x:3009:3009::/home/gatekpr:/bin/bash
+
+gatekeeper.pl is run via cronjob every minute. In gatekeeper.pl, see
+package_config_base and comments near the top of the file.
+
+ftp-addkey.sh is used to add an authorized GPG key.
+
+
+About the maintainers_bypkg file. It is an artifact of how GNU records
+maintainers, and it is optional. It's format is, on each line, a package
+name then a list of maintainers like so:
+
+gatekeeper - Jacob Bachmeyer <jcb@gnu.org>, Ian Kelling <iank@fsf.org>
+
+The server should run an auto-indexing web server in order for people to
+download releases.
+
+
+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 <http://www.gnu.org/licenses/>.