* imported changes from apt--main

[apt.git] / doc / method.sgml

diff --git a/doc/method.sgml b/doc/method.sgml
index 023bac40ebdc09b08f6af304e257c8ef9f631de5..d71ef02ea57418126d75ba13ae4e95cfed3c6926 100644 (file)
--- a/doc/method.sgml
+++ b/doc/method.sgml
@@ -1,10 +1,10 @@
-<!doctype debiandoc system>

 <!-- -*- mode: sgml; mode: fold -*- -->
 <!-- -*- mode: sgml; mode: fold -*- -->

+<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">

 <book>
 <title>APT Method Interface </title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
 <book>
 <title>APT Method Interface </title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>

-<version>$Id: method.sgml,v 1.3 1998/10/08 04:55:06 jgg Exp $</version>
+<version>$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $</version>

 
 <abstract>
 This document describes the interface that APT uses to the archive
 
 <abstract>
 This document describes the interface that APT uses to the archive


@@ -21,7 +21,7 @@ option) any later version.
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file
 
 <p>
 For more details, on Debian GNU/Linux systems, see the file

-/usr/doc/copyright/GPL for the full license.
+/usr/share/common-licenses/GPL for the full license.

 </copyright>
 
 <toc sect>
 </copyright>
 
 <toc sect>


@@ -33,7 +33,7 @@ For more details, on Debian GNU/Linux systems, see the file
 
 <p>
 The APT method interface allows APT to acquire archive files (.deb), index
 
 <p>
 The APT method interface allows APT to acquire archive files (.deb), index

-files (Packages, Revision, Mirrors) and source files (.tar.gz, .diff). It
+files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It

 is a general, extensible system designed to satisfy all of these
 requirements:
 
 is a general, extensible system designed to satisfy all of these
 requirements:
 


@@ -110,7 +110,7 @@ string
 
 <tag>acquire<item>
 The act of bring a URI into the local pathname space. This may simply
 
 <tag>acquire<item>
 The act of bring a URI into the local pathname space. This may simply

-be verifiying the existence of the URI or actually downloading it from
+be verifying the existence of the URI or actually downloading it from

 a remote site.
 
 </taglist>
 a remote site.
 
 </taglist>


@@ -125,20 +125,11 @@ a remote site.
 <p>
 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
 <p>
 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, 
+emergency error reporting. The FD's correspond to the well known unix FD's, 

 stdin, stdout and stderr.
 
 <p>
 stdin, stdout and stderr.
 
 <p>

-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.
-
-<p>
-Throught operation of the method communication is done via http 
+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
 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


@@ -156,7 +147,7 @@ URI's to determine how many files are available locally.
 <p>
 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 
 <p>
 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. 
+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.
 
 The 6xx series is used to specify things sent to the method. After the 
 status code is an informational string provided for visual debugging.
 


@@ -175,13 +166,12 @@ status code is an informational string provided for visual debugging.
 <item>601 Configuration - Sends the configuration space
 <item>602 Authorization Credentials - Response to the 402 message
 <item>603 Media Changed - Response to the 403 message
 <item>601 Configuration - Sends the configuration space
 <item>602 Authorization Credentials - Response to the 402 message
 <item>603 Media Changed - Response to the 403 message

-<item>605 Shutdown - Exit

 </list>
 
 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
 </list>
 
 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
+until the proper 602/603 code is received. This means the method must be

 capable of handling an unlimited number of 600 messages.
 
 <p>
 capable of handling an unlimited number of 600 messages.
 
 <p>


@@ -189,12 +179,12 @@ The flow of messages starts with the method sending out a
 <em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
 After that APT begins sending <em>600 URI Acquire</> and the method
 sends out <em>200 URI Start</>, <em>201 URI Done</> or 
 <em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
 After that APT begins sending <em>600 URI Acquire</> and the method
 sends out <em>200 URI Start</>, <em>201 URI Done</> or 

-<em>400 URI Failure</>. No syncronization is performed, it is expected
+<em>400 URI Failure</>. No synchronization is performed, it is expected

 that APT will send <em>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 send <em>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 neccessary for the method
-to be constantly ready to recieve them.
+that APT will buffer messages so it is not necessary for the method
+to be constantly ready to receive them.

 </sect>
                                                                   <!-- }}} -->
 <!-- Header Fields                                                    {{{ -->
 </sect>
                                                                   <!-- }}} -->
 <!-- Header Fields                                                    {{{ -->


@@ -208,6 +198,7 @@ The following is a short index of the header fields that are supported
 <tag>URI<item>URI being described by the message
 <tag>Filename<item>Location in the filesystem
 <tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks
 <tag>URI<item>URI being described by the message
 <tag>Filename<item>Location in the filesystem
 <tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks

+<tag>IMS-Hit<item>The already existing item is valid

 <tag>Size<item>Size of the file in bytes
 <tag>Resume-Point<item>Location that transfer was started
 <tag>MD5-Hash<item>Computed MD5 hash for the file
 <tag>Size<item>Size of the file in bytes
 <tag>Resume-Point<item>Location that transfer was started
 <tag>MD5-Hash<item>Computed MD5 hash for the file


@@ -216,6 +207,8 @@ The following is a short index of the header fields that are supported
 <tag>Site<item>String indicating the site authorization is required for
 <tag>User<item>Username for authorization
 <tag>Password<item>Password for authorization
 <tag>Site<item>String indicating the site authorization is required for
 <tag>User<item>Username for authorization
 <tag>Password<item>Password for authorization

+<tag>Fail<item>Operation failed
+<tag>Drive<item>Drive the media should be placed in

 <tag>Config-Item<item>
 A string of the form <var>item</>=<var>value</> derived from the APT 
 configuration space. These may include method specific values and general
 <tag>Config-Item<item>
 A string of the form <var>item</>=<var>value</> derived from the APT 
 configuration space. These may include method specific values and general


@@ -223,8 +216,12 @@ values not related to the method. It is up to the method to filter out
 the ones it wants.
 <tag>Single-Instance<item>Requires that only one instance of the method be run
                           This is a yes/no value.
 the ones it wants.
 <tag>Single-Instance<item>Requires that only one instance of the method be run
                           This is a yes/no value.

-<tag>Pre-Scan<item>Method can detect if archives are already available.
-                   This is a yes/no value.
+<tag>Pipeline<item>The method is capable of pipelining.
+<tag>Local<item>The method only returns Filename: fields.
+<tag>Send-Config<item>Send configuration to the method.
+<tag>Needs-Cleanup<item>The process is kept around while the files it returned
+are being used. This is primarily intended for CDROM and File URIs that need
+to unmount filesystems.

 <tag>Version<item>Version string for the method
 </taglist>
 
 <tag>Version<item>Version string for the method
 </taglist>
 


@@ -232,8 +229,11 @@ This is a list of which headers each status code can use
 
 <taglist>
 <tag>100 Capabilities<item>
 
 <taglist>
 <tag>100 Capabilities<item>

-Displays the capabilities of the method. 
-Fields: Version, Single-Instance, Pre-Scan
+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

 
 <tag>101 Log<item>
 A log message may be printed to the screen if debugging is enabled. This
 
 <tag>101 Log<item>
 A log message may be printed to the screen if debugging is enabled. This


@@ -242,7 +242,7 @@ Fields: Message
 
 <tag>102 Status<item>
 Message gives a progress indication for the method. It can be used to show
 
 <tag>102 Status<item>
 Message gives a progress indication for the method. It can be used to show

-pre-transfer status for internet type methods.
+pre-transfer status for Internet type methods.

 Fields: Message
 
 <tag>200 URI Start<item>
 Fields: Message
 
 <tag>200 URI Start<item>


@@ -256,17 +256,19 @@ to specify a <em>201 URI Done</> without a <em>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 
 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.
+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
 
 <tag>400 URI Failure<item>
 Indicates a fatal URI failure. The URI is not retrievable from this source.
 Fields: URI, Size, Last-Modified, Filename, MD5-Hash
 
 <tag>400 URI Failure<item>
 Indicates a fatal URI failure. The URI is not retrievable from this source.

-As with <em>201 URI Done</> <em>200 URI Start</> is not required to preceed
+As with <em>201 URI Done</> <em>200 URI Start</> is not required to precede

 this message
 Fields: URI, Message
 
 <tag>401 General Failure<item>
 this message
 Fields: URI, Message
 
 <tag>401 General Failure<item>

-Indicates that some unspecific failure has occured and the method is unable
+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.
 to continue. The method should terminate after sending this message. It 
 is intended to check for invalid configuration options or other severe
 conditions.


@@ -282,7 +284,7 @@ Fields: Site
 <tag>403 Media Failure<item>
 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.
 <tag>403 Media Failure<item>
 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
+Fields: Media, Drive

 
 <tag>600 URI Acquire<item>
 APT is requesting that a new URI be added to the acquire list. Last-Modified
 
 <tag>600 URI Acquire<item>
 APT is requesting that a new URI be added to the acquire list. Last-Modified


@@ -304,19 +306,47 @@ Fields: Site, User, Password
 <tag>603 Media Changed<item>
 This is sent in response to a <em>403 Media Failure</> message. It
 indicates that the user has changed media and it is safe to proceed.
 <tag>603 Media Changed<item>
 This is sent in response to a <em>403 Media Failure</> message. It
 indicates that the user has changed media and it is safe to proceed.

-Fields: Media
-
-<tag>605 Shutdown<item>
-APT sends this to signal the shutdown of the method. The method should
-terminate immidiately.
-Fields: None
+Fields: Media, Fail

 </taglist>
 
 </sect>
                                                                   <!-- }}} -->
 </taglist>
 
 </sect>
                                                                   <!-- }}} -->

-<!-- Examples                                                         {{{ -->
+<!-- Method Notes                                                     {{{ -->

 <!-- ===================================================================== -->
 <!-- ===================================================================== -->

-<sect>Examples
+<sect>Notes
+
+<p>
+The methods supplied by the stock apt are:
+<enumlist>
+<item>cdrom - For Multi-Disc CDROMs
+<item>copy - (internal) For copying files around the filesystem
+<item>file - For local files
+<item>gzip - (internal) For decompression
+<item>http - For HTTP servers
+</enumlist>
+
+<p>
+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:
+<example>
+http://foo.com/Packages.gz -> /bar/Packages.gz
+gzip:/bar/Packages.gz -> /bar/Packages.decomp
+rename Packages.decomp to /final/Packages
+</example>
+
+<p>
+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.

 
 </sect>
                                                                   <!-- }}} -->
 
 </sect>
                                                                   <!-- }}} -->