From 271733ee8eb9a673747bdef320af5ca8e8f18273 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Wed, 2 Jul 2014 02:22:32 +0200 Subject: doc: Convert from DebianDoc SGML to DocBook XML --- doc/method.sgml | 354 -------------------------------------------------------- 1 file changed, 354 deletions(-) delete mode 100644 doc/method.sgml (limited to 'doc/method.sgml') diff --git a/doc/method.sgml b/doc/method.sgml deleted file mode 100644 index 5aa7b52e8..000000000 --- a/doc/method.sgml +++ /dev/null @@ -1,354 +0,0 @@ - - - -APT Method Interface - -Jason Gunthorpe jgg@debian.org -$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $ - - -This document describes the interface that APT uses to the archive -access methods. - - - -Copyright © Jason Gunthorpe, 1998. -

-"APT" and this document are free software; you can redistribute them and/or -modify them under the terms of the GNU General Public License as published -by the Free Software Foundation; either version 2 of the License, or (at your -option) any later version. - -

-For more details, on Debian systems, see the file -/usr/share/common-licenses/GPL for the full license. - - - - -Introduction - - -General - -

-The APT method interface allows APT to acquire archive files (.deb), index -files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It -is a general, extensible system designed to satisfy all of these -requirements: - - -Remote methods that download files from a distant site -Resume of aborted downloads -Progress reporting -If-Modified-Since (IMS) checking for index files -In-Line MD5 generation -No-copy in-filesystem methods -Multi-media methods (like CD's) -Dynamic source selection for failure recovery -User interaction for user/password requests and media swaps -Global configuration - - -Initial releases of APT (0.1.x) used a completely different method -interface that only supported the first 6 items. This new interface -deals with the remainder. - - - - -Terms - -

-Several terms are used through out the document, they have specific -meanings which may not be immediately evident. To clarify they are summarized -here. - - -source -Refers to an item in source list. More specifically it is the broken down -item, that is each source maps to exactly one index file. Archive sources -map to Package files and Source Code sources map to Source files. - -archive file -Refers to a binary package archive (.deb, .rpm, etc). - -source file -Refers to one of the files making up the source code of a package. In -debian it is one of .diff.gz, .dsc. or .tar.gz. - -URI -Universal Resource Identifier (URI) is a super-set of the familiar URL -syntax used by web browsers. It consists of an access specification -followed by a specific location in that access space. The form is -<access>:<location>. Network addresses are given with the form -<access>://[<user>[:<pas>]@]hostname[:port]/<location>. -Some examples: - -file:/var/mirrors/debian/ -ftp://ftp.debian.org/debian -ftp://jgg:MooCow@localhost:21/debian -nfs://bigred/var/mirrors/debian -rsync://debian.midco.net/debian -cdrom:Debian 2.0r1 Disk 1/ - - -method -There is a one to one mapping of URI access specifiers to methods. A method -is a program that knows how to handle a URI access type and operates according -to the specifications in this file. - -method instance -A specific running method. There can be more than one instance of each method -as APT is capable of concurrent method handling. - -message -A series of lines terminated by a blank line sent down one of the -communication lines. The first line should have the form xxx TAG -where xxx are digits forming the status code and TAG is an informational -string - -acquire -The act of bring a URI into the local pathname space. This may simply -be verifying the existence of the URI or actually downloading it from -a remote site. - - - - - -Specification - - -Overview - -

-All methods operate as a sub process of a main controlling parent. 3 FD's -are opened for use by the method allowing two way communication and -emergency error reporting. The FD's correspond to the well known unix FD's, -stdin, stdout and stderr. - -

-Through operation of the method communication is done via http -style plain text. Specifically RFC-822 (like the Package file) fields -are used to describe items and a numeric-like header is used to indicate -what is happening. Each of these distinct communication messages should be -sent quickly and without pause. - -

-In some instances APT may pre-invoke a method to allow things like file -URI's to determine how many files are available locally. - - - - -Message Overview - -

-The first line of each message is called the message header. The first -3 digits (called the Status Code) have the usual meaning found in the -http protocol. 1xx is informational, 2xx is successful and 4xx is failure. -The 6xx series is used to specify things sent to the method. After the -status code is an informational string provided for visual debugging. - - -100 Capabilities - Method capabilities -101 Log - General Logging -102 Status - Inter-URI status reporting (login progress) -200 URI Start - URI is starting acquire -201 URI Done - URI is finished acquire -400 URI Failure - URI has failed to acquire -401 General Failure - Method did not like something sent to it -402 Authorization Required - Method requires authorization - to access the URI. Authorization is User/Pass -403 Media Failure - Method requires a media change -600 URI Acquire - Request a URI be acquired -601 Configuration - Sends the configuration space -602 Authorization Credentials - Response to the 402 message -603 Media Changed - Response to the 403 message - - -Only the 6xx series of status codes is sent TO the method. Furthermore -the method may not emit status codes in the 6xx range. The Codes 402 -and 403 require that the method continue reading all other 6xx codes -until the proper 602/603 code is received. This means the method must be -capable of handling an unlimited number of 600 messages. - -

-The flow of messages starts with the method sending out a -100 Capabilities and APT sending out a 601 Configuration. -After that APT begins sending 600 URI Acquire and the method -sends out 200 URI Start, 201 URI Done or -400 URI Failure. No synchronization is performed, it is expected -that APT will send 600 URI Acquire messages at -any- time and -that the method should queue the messages. This allows methods like http -to pipeline requests to the remote server. It should be noted however -that APT will buffer messages so it is not necessary for the method -to be constantly ready to receive them. - - - - -Header Fields - -

-The following is a short index of the header fields that are supported - - -URIURI being described by the message -FilenameLocation in the filesystem -Last-ModifiedA time stamp in RFC1123 notation for use by IMS checks -IMS-HitThe already existing item is valid -SizeSize of the file in bytes -Resume-PointLocation that transfer was started -MD5-HashComputed MD5 hash for the file -MessageString indicating some displayable message -MediaString indicating the media name required -SiteString indicating the site authorization is required for -UserUsername for authorization -PasswordPassword for authorization -FailOperation failed -DriveDrive the media should be placed in -Config-Item -A string of the form item=value derived from the APT -configuration space. These may include method specific values and general -values not related to the method. It is up to the method to filter out -the ones it wants. -Single-InstanceRequires that only one instance of the method be run - This is a yes/no value. -PipelineThe method is capable of pipelining. -LocalThe method only returns Filename: fields. -Send-ConfigSend configuration to the method. -Needs-CleanupThe process is kept around while the files it returned -are being used. This is primarily intended for CD-ROM and File URIs that need -to unmount filesystems. -VersionVersion string for the method - - -This is a list of which headers each status code can use - - -100 Capabilities -Displays the capabilities of the method. Methods should set the -pipeline bit if their underlying protocol supports pipelining. The -only known method that does support pipelining is http. -Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config, -Needs-Cleanup - -101 Log -A log message may be printed to the screen if debugging is enabled. This -is only for debugging the method. -Fields: Message - -102 Status -Message gives a progress indication for the method. It can be used to show -pre-transfer status for Internet type methods. -Fields: Message - -200 URI Start -Indicates the URI is starting to be transferred. The URI is specified -along with stats about the file itself. -Fields: URI, Size, Last-Modified, Resume-Point - -201 URI Done -Indicates that a URI has completed being transferred. It is possible -to specify a 201 URI Done without a URI Start which would -mean no data was transferred but the file is now available. A Filename -field is specified when the URI is directly available in the local -pathname space. APT will either directly use that file or copy it into -another location. It is possible to return Alt-* fields to indicate that -another possibility for the URI has been found in the local pathname space. -This is done if a decompressed version of a .gz file is found. -Fields: URI, Size, Last-Modified, Filename, MD5-Hash - -400 URI Failure -Indicates a fatal URI failure. The URI is not retrievable from this source. -As with 201 URI Done 200 URI Start is not required to precede -this message -Fields: URI, Message - -401 General Failure -Indicates that some unspecific failure has occurred and the method is unable -to continue. The method should terminate after sending this message. It -is intended to check for invalid configuration options or other severe -conditions. -Fields: Message - -402 Authorization Required -The method requires a Username and Password pair to continue. After sending -this message the method will expect APT to send a 602 Authorization -Credentials message with the required information. It is possible for -a method to send this multiple times. -Fields: Site - -403 Media Failure -A method that deals with multiple media requires that a new media be inserted. -The Media field contains the name of the media to be inserted. -Fields: Media, Drive - -600 URI Acquire -APT is requesting that a new URI be added to the acquire list. Last-Modified -has the time stamp of the currently cache file if applicable. Filename -is the name of the file that the acquired URI should be written to. -Fields: URI, Filename Last-Modified - -601 Configuration -APT is sending the configuration space to the method. A series of -Config-Item fields will be part of this message, each containing an entry -from the configuration space. -Fields: Config-Item. - -602 Authorization Credentials -This is sent in response to a 402 Authorization Required message. -It contains the entered username and password. -Fields: Site, User, Password - -603 Media Changed -This is sent in response to a 403 Media Failure message. It -indicates that the user has changed media and it is safe to proceed. -Fields: Media, Fail - - - - - - -Notes - -

-The methods supplied by the stock apt are: - -cdrom - For Multi-Disc CD-ROMs -copy - (internal) For copying files around the filesystem -file - For local files -gzip - (internal) For decompression -http - For HTTP servers - - -

-The two internal methods, copy and gzip, are used by the acquire code to -parallize and simplify the automatic decompression of package files as well -as copying package files around the file system. Both methods can be seen to -act the same except that one decompresses on the fly. APT uses them by -generating a copy URI that is formed identically to a file URI. The destination -file is send as normal. The method then takes the file specified by the -URI and writes it to the destination file. A typical set of operations may -be: - -http://foo.com/Packages.gz -> /bar/Packages.gz -gzip:/bar/Packages.gz -> /bar/Packages.decomp -rename Packages.decomp to /final/Packages - - -

-The http method implements a fully featured HTTP/1.1 client that supports -deep pipelining and reget. It works best when coupled with an apache 1.3 -server. The file method simply generates failures or success responses with -the filename field set to the proper location. The cdrom method acts the same -except that it checks that the mount point has a valid cdrom in it. It does -this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint. - - - - - -- cgit v1.2.3-70-g09d2