20221212

[devspec.git] / devspec.en_US / gnu-spec / ftp-space.txt

\r
------------------------------------------------------------------------------\r
Next: Announcements, Previous: Test Releases, Up: Distributions   [Contents][Index]\r
\r
11.6 Automated FTP Uploads\r
In order to upload new releases to ftp.gnu.org or alpha.gnu.org, you first need to register the necessary information. Then, you can perform uploads yourself, with no intervention needed by the system administrators.\r
\r
The general idea is that releases should be cryptographically signed before they are made publicly available.\r
\r
• Automated Upload Registration:                \r
• Automated Upload Procedure:           \r
• FTP Upload Release File Triplet:              \r
• FTP Upload Directive File:            \r
• FTP Upload Directory Trees:           \r
• FTP Upload File Replacement:          \r
• FTP Upload Standalone Directives:             \r
• FTP Upload Directive File - v1.1:             \r
• FTP Upload Directive File - v1.0:             \r
\r
------------------------------------------------------------------------------\r
Next: Automated Upload Procedure, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.1 Automated Upload Registration\r
Here is how to register your information so you can perform uploads for your GNU package:\r
\r
Create an account for yourself at https://savannah.gnu.org, if you don’t already have one. By the way, this is also needed to maintain the web pages at https://www.gnu.org for your project (see Web Pages).\r
In the ‘My Account Conf’ page on savannah, upload the GPG key (in ASCII-armored format) that you will use to sign your packages. If you haven’t created one before, you can do so with the command gpg --gen-key (you can accept and/or confirm the default answers to its questions). Then, to get the ASCII-armored version, run ‘gpg --export --armor your_key_id’.\r
Optional but recommended: Send your key to a GPG public key server: gpg --keyserver keys.gnupg.net --send-keys keyid, where keyid is the eight hex digits reported by gpg --list-public-keys on the pub line before the date. For full information about GPG, see https://www.gnu.org/software/gpg.\r
\r
Compose a message with the following items in some msgfile. Then GPG-sign it by running gpg --clearsign msgfile, and finally email the resulting msgfile.asc as an attachment to ftp-upload@gnu.org.\r
Name of package(s) that you are the maintainer for, your preferred email address, and your Savannah username.\r
The ASCII armored copy of your GPG key, as an attachment.\r
A list of names and preferred email addresses of other individuals you authorize to make releases for which packages, if any (in the case that you don’t make all releases yourself).\r
ASCII armored copies of GPG keys for any individuals listed in (3).\r
The administrators will acknowledge your message when they have added the proper GPG keys as authorized to upload files for the corresponding packages.\r
\r
The upload system will email receipts to the given email addresses when an upload is made, either successfully or unsuccessfully.\r
\r
Should you later have to update your GPG key, you’ll have to re-submit it to both Savannah and ftp-upload@gnu.org, as these systems are not connected.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Release File Triplet, Previous: Automated Upload Registration, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.2 Automated Upload Procedure\r
Once you have registered your information as described in the previous section, you can and should do ftp uploads for your package. There are two basic kinds of uploads (details in the following sections):\r
\r
Three related files (a “triplet”) to upload a file destined for ftp.gnu.org or alpha.gnu.org: see FTP Upload Release File Triplet.\r
A single (signed) standalone “directive file” to perform operations on the server: see FTP Upload Standalone Directives.\r
In either case, you upload the file(s) via anonymous ftp to the host ftp-upload.gnu.org. If the upload is destined for ftp.gnu.org, place the file(s) in the directory /incoming/ftp. If the upload is destined for alpha.gnu.org, place the file(s) in the directory /incoming/alpha.\r
\r
Uploads are processed every five minutes. Uploads that are in progress while the upload processing script is running are handled properly, so do not worry about the timing of your upload. Spurious and stale uploaded files are deleted automatically after 24 hours.\r
\r
Your designated upload email addresses (see Automated Upload Registration) are sent a message if there are problems processing an upload for your package. You also receive a message when an upload has been successfully processed.\r
\r
One programmatic way to create and transfer the necessary files is to use the gnupload script, which is available from the build-aux/ directory of the gnulib project at https://savannah.gnu.org/projects/gnulib. Run gnupload --help for a description and examples. (With gnupload, you specify a destination such as ‘ftp.gnu.org:’pkgname rather than using the ‘ftp-upload’ hostname.)\r
\r
gnupload invokes the program ncftpput to do the actual transfers; if you don’t happen to have the ncftp package installed, the ncftpput-ftp script in the build-aux/ directory of gnulib can serve as a replacement. It uses the plain command line ftp program.\r
\r
If you have difficulties with an upload, email ftp-upload@gnu.org. You can check the archive of uploads processed at https://lists.gnu.org/archive/html/ftp-upload-report.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Directive File, Previous: Automated Upload Procedure, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.3 FTP Upload Release File Triplet\r
Ordinarily, the goal is to upload a new release of your package, let’s say, the source archive foo-1.0.tar.gz. To do this, you simultaneously upload three files:\r
\r
The file to be distributed; in our example, foo-1.0.tar.gz.\r
Detached GPG binary signature file for (1); for example, foo-1.0.tar.gz.sig. Make this with ‘gpg -b foo-1.0.tar.gz’.\r
A clearsigned directive file; for example, foo-1.0.tar.gz.directive.asc, created with ‘gpg --clearsign foo-1.0.tar.gz.directive’. Its contents are described in the next section.\r
The names of the files are important. The signature file must have the same name as the file to be distributed, with an additional .sig extension. The directive file must have the same name as the file to be distributed, with an additional .directive.asc extension. If you do not follow this naming convention, the upload will not be processed.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Directory Trees, Previous: FTP Upload Release File Triplet, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.4 FTP Upload Directive File\r
To repeat, a (signed) directive file must be part of every upload. The unsigned original is just a plain text file you can create with any text editor. Its name must be, e.g., foo-1.0.tar.gz.directive for accompanying an upload of foo-1.0.tar.gz.\r
\r
After creating the file, run ‘gpg --clearsign foo-1.0.tar.gz.directive’, which will create foo-1.0.tar.gz.directive.asc; this is the file to be uploaded.\r
\r
When part of a triplet for uploading a release file, the directive file must always contain the directives version, filename and directory. In addition, a comment directive is optional. These directives can be given in any order.\r
\r
Continuing our example of uploading foo-1.0.tar.gz for a package named foo to ftp.gnu.org, the values would be as follows:\r
\r
version\r
must be the value ‘1.2’ (the current version, as of May 2012):\r
version: 1.2\r
\r
filename\r
must be the name of the file to be distributed:\r
filename: foo-1.0.tar.gz\r
\r
directory\r
specifies the final destination directory where the uploaded file and its .sig companion are to be placed. Here we will put our file in the top level directory of the package, as is the most common practice:\r
directory: foo\r
\r
comment\r
is optional, and ignored if present:\r
comment: let's hope this works!\r
\r
Putting all of the above together, the complete contents of the directive file foo-1.0.tar.gz.directive for our example would be:\r
\r
version: 1.2\r
directory: foo\r
filename: foo-1.0.tar.gz\r
comment: let's hope this works!\r
Then you ‘gpg --clearsign’ the file as given above, and upload (using anonymous ftp) the three files:\r
\r
foo-1.0.tar.gz\r
foo-1.0.tar.gz.sig\r
foo-1.0.tar.gz.directive.asc\r
to the host ftp-upload.gnu.org, directory /incoming/ftp (for official releases), or the directory /incoming/alpha (for test releases).\r
\r
After the system authenticates the signatures, the files foo-1.0.tar.gz and foo-1.0.tar.gz.sig are placed in the directory gnu/foo/ on ftp.gnu.org. That is, we’ll have made our release available at ‘https://ftp.gnu.org/gnu/foo/foo-1.0.tar.gz’ (and then from our many mirrors via ‘https://ftpmirror.gnu.org/foo/foo-1.0.tar.gz’). Whew.\r
\r
A common reason for the upload not succeeding is your GPG signature not being registered with the upload system. There is nothing that makes this happen automatically. You must email the system administrators as described above (see Automated Upload Registration).\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload File Replacement, Previous: FTP Upload Directive File, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.5 FTP Upload Directory Trees\r
You can make any directory hierarchy you like under your package directory. The system automatically creates any intermediate directories you specify in the directory directive.\r
\r
Slightly modifying the example above, the following directive file:\r
\r
version: 1.2\r
directory: foo/foo-1.0\r
filename: foo-1.0.tar.gz\r
comment: creates per-version subdirectory as needed\r
would put the tar file in the foo-1.0/ subdirectory of the package foo, thus ending up at ‘ftp.gnu.org:gnu/foo/foo-1.0/foo-1.0.tar.gz’.\r
\r
However, to keep things simpler for users, we recommend not using subdirectories, unless perhaps each release of your package consists of many separate files.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Standalone Directives, Previous: FTP Upload Directory Trees, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.6 FTP Upload File Replacement\r
You can replace existing files that have already been uploaded by including a directive line replace: true. For example, you might like to provide a README file in the release directory and update it from time to time. The full directive file for that would look like this:\r
\r
replace: true\r
version: 1.2\r
directory: foo\r
filename: README\r
comment: replaces an existing README\r
It is ok if the file to be replaced doesn’t already exist; then the new file is simply added, i.e., the replace directive has no effect.\r
\r
When an existing file is replaced, the original is archived to a private location. There is no automated or public access to such archived files; if you want to retrieve or view them, please email sysadmin@fsf.org.\r
\r
We very strongly discourage replacing an actual software release file, such as foo-1.0.tar.gz. Releases should be unique, and forever. If you need to make fixes, make another release. If you have an exigent reason for a particular release file to no longer be available, it can be explicitly archived, as described in the next section.\r
\r
If you want to make the current release available under a generic name, such as foo-latest.tar.gz, that is better done with symlinks, also as described in the next section.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Directive File - v1.1, Previous: FTP Upload File Replacement, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.7 FTP Upload Standalone Directives\r
The previous sections describe how to upload a file to be publicly released. It’s also possible to upload a directive file by itself to perform a few operations on the upload directory. The supported directives are:\r
\r
symlink\r
creates a symlink.\r
\r
rmsymlink\r
removes a symlink.\r
\r
archive\r
takes a file or directory offline.\r
\r
As for the directives described above, the directory and version directives are still required, the comment directive remains optional, and the filename directive is not allowed.\r
\r
The .sig file should not be explicitly mentioned in a directive. When you specify a directive to operate on a file, its corresponding .sig file will be handled automatically.\r
\r
When uploaded by itself, the name of the directive file is not important. But it must be still be signed, using ‘gpg --clearsign’; the resulting .asc file is what should be uploaded.\r
\r
Here’s an example of the full directive file to create a foo-latest.tar.gz symlink:\r
\r
version: 1.2\r
directory: foo\r
symlink: foo-1.1.tar.gz foo-latest.tar.gz\r
comment: create a symlink\r
If you include more than one directive in a standalone upload, the directives are executed in the sequence they are specified in. If a directive results in an error, further execution of the upload is aborted.\r
\r
Removing a symbolic link (with rmsymlink) which does not exist results in an error. On the other hand, attempting to create a symbolic link that already exists (with symlink) is not an error. In this case symlink behaves like the command ln -s -f: any existing symlink is removed before creating the link. (But an existing regular file or directory is not replaced.)\r
\r
Here’s an example of removing a symlink, e.g., if you decide not to maintain a foo-latest link any more:\r
\r
version: 1.2\r
directory: foo\r
rmsymlink: foo-latest.tar.gz\r
comment: remove a symlink\r
And here’s an example of archiving a file, e.g., an unintended upload:\r
\r
version: 1.2\r
directory: foo\r
archive: foo-1.1x.tar.gz\r
comment: archive an old file; it will not be\r
comment: publicly available any more.\r
The archive directive causes the specified items to become inaccessible. This should only be used when it is actively bad for them to be available, e.g., you uploaded something by mistake.\r
\r
If all you want to do is reduce how much stuff is in your release directory, an alternative is to email sysadmin@fsf.org and ask them to move old items to the https://ftp.gnu.org/old-gnu/ directory; then they will still be available. In general, however, we recommend leaving all official releases in the main release directory.\r
\r
------------------------------------------------------------------------------\r
Next: FTP Upload Directive File - v1.0, Previous: FTP Upload Standalone Directives, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.8 FTP Upload Directive File - v1.1\r
The v1.1 protocol for uploads lacked the replace directive; instead, file replacements were done automatically and silently (clearly undesirable). This is the only difference between v1.2 and v1.1.\r
\r
Previous: FTP Upload Directive File - v1.1, Up: Automated FTP Uploads   [Contents][Index]\r
\r
11.6.9 FTP Upload Directive File - v1.0\r
Support for v1.0 uploads was discontinued in May 2012; please upgrade to v1.2.\r
\r
In v1.0, the directive file contained one line, excluding the clearsigned data GPG that inserts, which specifies the final destination directory where items (1) and (2) are to be placed.\r
\r
For example, the foo-1.0.tar.gz.directive.asc file might contain the single line:\r
\r
directory: bar/v1\r
This directory line indicates that foo-1.0.tar.gz and foo-1.0.tar.gz.sig are part of package bar. If you were to upload the triplet to /incoming/ftp, and the system can positively authenticate the signatures, then the files foo-1.0.tar.gz and foo-1.0.tar.gz.sig will be placed in the directory gnu/bar/v1 of the ftp.gnu.org site.\r
\r
The directive file can be used to create currently non-existent directory trees, as long as they are under the package directory for your package (in the example above, that is bar).\r
\r
------------------------------------------------------------------------------\r