[back]
[Abstract]
[Copyright Notice]
[Contents]
APT Method Interface - Chapter 2
Specification
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.
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.
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 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 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 Acquire 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 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.
The following is a short index of the header fields that are supported
- URI
- URI being described by the message
- Filename
- Location in the filesystem
- Last-Modified
- A time stamp in RFC1123 notation for use by IMS checks
- IMS-Hit
- The already existing item is valid
- Size
- Size of the file in bytes
- Resume-Point
- Location that transfer was started
- MD5-Hash
- Computed MD5 hash for the file
- Message
- String indicating some displayable message
- Media
- String indicating the media name required
- Site
- String indicating the site authorization is required for
- User
- Username for authorization
- Password
- Password for authorization
- Fail
- Operation failed
- Drive
- Drive 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-Instance
- Requires that only one instance of the method be run
This is a yes/no value.
- Pipeline
- The method is capable of pipelining.
- Local
- The method only returns Filename: feilds.
- Send-Config
- Send configuration to the method.
- Version
- Version 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 pipeling. The
only known method that does support pipelining is http.
Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config
- 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. It is possible to return Alt-* feilds 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 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, 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
The methods supplied by the stock apt are:
- cdrom - For Multi-Disc CDROMs
- 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.
[back]
[Abstract]
[Copyright Notice]
[Contents]
APT Method Interface
$Id: method.sgml,v 1.6 1998/12/14 04:00:34 jgg Exp $
Jason Gunthorpe jgg@debian.org