From dd80ca3ca82976b94244a6d05092da5029fa0107 Mon Sep 17 00:00:00 2001 From: Arch Librarian Date: Mon, 20 Sep 2004 16:51:01 +0000 Subject: Method doc created Author: jgg Date: 1998-10-04 04:49:16 GMT Method doc created --- doc/makefile | 3 +- doc/method.sgml | 324 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 326 insertions(+), 1 deletion(-) create mode 100644 doc/method.sgml diff --git a/doc/makefile b/doc/makefile index e6a2dbefe..5be7c0539 100644 --- a/doc/makefile +++ b/doc/makefile @@ -6,7 +6,8 @@ SUBDIR=doc include ../buildlib/defaults.mak # SGML Documents -SOURCE = dpkg-tech.sgml design.sgml files.sgml guide.sgml cache.sgml +SOURCE = dpkg-tech.sgml design.sgml files.sgml guide.sgml cache.sgml \ + method.sgml include $(DEBIANDOC_H) # Man pages diff --git a/doc/method.sgml b/doc/method.sgml new file mode 100644 index 000000000..756dce87f --- /dev/null +++ b/doc/method.sgml @@ -0,0 +1,324 @@ + + + +APT Method Interface + +Jason Gunthorpe jgg@debian.org +$Id: method.sgml,v 1.1 1998/10/04 04:49:17 jgg 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 GNU/Linux systems, see the file +/usr/doc/copyright/GPL for the full license. + + + + +Introduction + + +General + +

+The APT method interface allows APT to aquire archive files (.deb), index +files (Packages, Revision, 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 + +aquire +The act of bring a URI into the local pathname space. This may simply +be verifiying the existance 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 corrispond to the well known unix FD's, +stdin, stdout and stderr. + +

+The basic startup sequence depends on how the method is invoked. If any +command line arguments are passed then the method should start in +automatic mode. This facility is provided soley to make the methods +easier to test and perhaps use outside of APT. Upon startup the method +will print out a header describing its capabilities and requirements. +After that it either begins processing the command line arugments and +exits when done or waits for commands to be fed to it. + +

+Throught 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 successfull 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 aquire +201 URI Done - URI is finished aquire +400 URI Failure - URI has failed to aquire +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 Aquire - Request a URI be aquired +601 Configuration - Sends the configuration space +602 Authorization Credentials - Response to the 402 message +603 Media Changed - Response to the 403 message +605 Shutdown - Exit + + +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 recieved. 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 Aquire and the method +sends out 200 URI Start, 201 URI Done or +400 URI Failure. No syncronization is performed, it is expected +that APT will send 600 URI Aquire 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 neccessary for the method +to be constantly ready to recieve 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 +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 +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. +Pre-ScanMethod can detect if archives are already available. + This is a yes/no value. +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. +Fields: Version, Single-Interface, Pre-Scan + +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 transfered. 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 transfered. It is possible +to specify a 201 URI Done without a URI Start which would +mean no data was transfered 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. +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 preceed +this message +Fields: URI, Message + +401 General Failure +Indicates that some unspecific failure has occured 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 + +600 URI Aquire +APT is requesting that a new URI be added to the aquire list. Last-Modified +has the time stamp of the currently cache file if applicable. Filename +is the name of the file that the aquired 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 + +605 Shutdown +APT sends this to signal the shutdown of the method. The method should +terminate immidiately. +Fields: None + + + + + + +Examples + + + + + -- cgit v1.2.3