<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Chapter 2. Specification</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<link rel="home" href="index.html" title="APT Method Interface"/>
<link rel="up" href="index.html" title="APT Method Interface"/>
<link rel="prev" href="ch1.html" title="Chapter 1. Introduction"/>
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 2. Specification</th>
</tr>
<tr>
<td align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td align="right"> </td>
</tr>
</table>
<hr/>
</div>
<div class="chapter">
<div class="titlepage">
<div>
<div>
<h1 class="title"><a id="ch2"/>Chapter 2. Specification</h1>
</div>
</div>
</div>
<div class="toc">
<p>
<strong>Table of Contents</strong>
</p>
<dl class="toc">
<dt>
<span class="section">
<a href="ch2.html#s2.1">2.1. Overview</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.2">2.2. Message Overview</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.3">2.3. Header Fields</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch2.html#s2.4">2.4. Notes</a>
</span>
</dt>
</dl>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.1"/>2.1. Overview</h2>
</div>
</div>
</div>
<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 correspond to the well known unix FD's, stdin, stdout and
stderr.
</p>
<p>
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.
</p>
<p>
In some instances APT may pre-invoke a method to allow things like file URI's
to determine how many files are available locally.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.2"/>2.2. Message Overview</h2>
</div>
</div>
</div>
<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 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.
</p>
<div class="itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<p>
100 Capabilities - Method capabilities
</p>
</li>
<li class="listitem">
<p>
101 Log - General Logging
</p>
</li>
<li class="listitem">
<p>
102 Status - Inter-URI status reporting (login progress)
</p>
</li>
<li class="listitem">
<p>
200 URI Start - URI is starting acquire
</p>
</li>
<li class="listitem">
<p>
201 URI Done - URI is finished acquire
</p>
</li>
<li class="listitem">
<p>
400 URI Failure - URI has failed to acquire
</p>
</li>
<li class="listitem">
<p>
401 General Failure - Method did not like something sent to it
</p>
</li>
<li class="listitem">
<p>
402 Authorization Required - Method requires authorization to access the URI.
Authorization is User/Pass
</p>
</li>
<li class="listitem">
<p>
403 Media Failure - Method requires a media change
</p>
</li>
<li class="listitem">
<p>
600 URI Acquire - Request a URI be acquired
</p>
</li>
<li class="listitem">
<p>
601 Configuration - Sends the configuration space
</p>
</li>
<li class="listitem">
<p>
602 Authorization Credentials - Response to the 402 message
</p>
</li>
<li class="listitem">
<p>
603 Media Changed - Response to the 403 message
</p>
</li>
</ul>
</div>
<p>
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.
</p>
<p>
The flow of messages starts with the method sending out a <span class="emphasis"><em>100
Capabilities</em></span> and APT sending out a <span class="emphasis"><em>601
Configuration</em></span>. After that APT begins sending <span class="emphasis"><em>600 URI
Acquire</em></span> and the method sends out <span class="emphasis"><em>200 URI Start</em></span>,
<span class="emphasis"><em>201 URI Done</em></span> or <span class="emphasis"><em>400 URI Failure</em></span>. No
synchronization is performed, it is expected that APT will send <span class="emphasis"><em>600
URI Acquire</em></span> 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.
</p>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.3"/>2.3. Header Fields</h2>
</div>
</div>
</div>
<p>
The following is a short index of the header fields that are supported
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">URI</span>
</dt>
<dd>
<p>
URI being described by the message
</p>
</dd>
<dt>
<span class="term">Filename</span>
</dt>
<dd>
<p>
Location in the filesystem
</p>
</dd>
<dt>
<span class="term">Last-Modified</span>
</dt>
<dd>
<p>
A time stamp in RFC1123 notation for use by IMS checks
</p>
</dd>
<dt>
<span class="term">IMS-Hit</span>
</dt>
<dd>
<p>
The already existing item is valid
</p>
</dd>
<dt>
<span class="term">Size</span>
</dt>
<dd>
<p>
Size of the file in bytes
</p>
</dd>
<dt>
<span class="term">Resume-Point</span>
</dt>
<dd>
<p>
Location that transfer was started
</p>
</dd>
<dt>
<span class="term">MD5-Hash</span>
</dt>
<dd>
<p>
Computed MD5 hash for the file
</p>
</dd>
<dt>
<span class="term">Message</span>
</dt>
<dd>
<p>
String indicating some displayable message
</p>
</dd>
<dt>
<span class="term">Media</span>
</dt>
<dd>
<p>
String indicating the media name required
</p>
</dd>
<dt>
<span class="term">Site</span>
</dt>
<dd>
<p>
String indicating the site authorization is required for
</p>
</dd>
<dt>
<span class="term">User</span>
</dt>
<dd>
<p>
Username for authorization
</p>
</dd>
<dt>
<span class="term">Password</span>
</dt>
<dd>
<p>
Password for authorization
</p>
</dd>
<dt>
<span class="term">Fail</span>
</dt>
<dd>
<p>
Operation failed
</p>
</dd>
<dt>
<span class="term">Drive</span>
</dt>
<dd>
<p>
Drive the media should be placed in
</p>
</dd>
<dt>
<span class="term">Config-Item</span>
</dt>
<dd>
<p>
A string of the form
<em class="replaceable"><code>item</code></em>=<em class="replaceable"><code>value</code></em> 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.
</p>
</dd>
<dt>
<span class="term">Single-Instance</span>
</dt>
<dd>
<p>
Requires that only one instance of the method be run This is a yes/no value.
</p>
</dd>
<dt>
<span class="term">Pipeline</span>
</dt>
<dd>
<p>
The method is capable of pipelining.
</p>
</dd>
<dt>
<span class="term">Local</span>
</dt>
<dd>
<p>
The method only returns Filename: fields.
</p>
</dd>
<dt>
<span class="term">Send-Config</span>
</dt>
<dd>
<p>
Send configuration to the method.
</p>
</dd>
<dt>
<span class="term">Needs-Cleanup</span>
</dt>
<dd>
<p>
The 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.
</p>
</dd>
<dt>
<span class="term">Version</span>
</dt>
<dd>
<p>
Version string for the method
</p>
</dd>
</dl>
</div>
<p>
This is a list of which headers each status code can use
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">100 Capabilities</span>
</dt>
<dd>
<p>
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
</p>
</dd>
<dt>
<span class="term">101 Log</span>
</dt>
<dd>
<p>
A log message may be printed to the screen if debugging is enabled. This is
only for debugging the method. Fields: Message
</p>
</dd>
<dt>
<span class="term">102 Status</span>
</dt>
<dd>
<p>
Message gives a progress indication for the method. It can be used to show
pre-transfer status for Internet type methods. Fields: Message
</p>
</dd>
<dt>
<span class="term">200 URI Start</span>
</dt>
<dd>
<p>
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
</p>
</dd>
<dt>
<span class="term">201 URI Done</span>
</dt>
<dd>
<p>
Indicates that a URI has completed being transferred. It is possible to
specify a <span class="emphasis"><em>201 URI Done</em></span> without a <span class="emphasis"><em>URI
Start</em></span> 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
</p>
</dd>
<dt>
<span class="term">400 URI Failure</span>
</dt>
<dd>
<p>
Indicates a fatal URI failure. The URI is not retrievable from this source. As
with <span class="emphasis"><em>201 URI Done</em></span> <span class="emphasis"><em>200 URI Start</em></span> is
not required to precede this message Fields: URI, Message
</p>
</dd>
<dt>
<span class="term">401 General Failure</span>
</dt>
<dd>
<p>
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
</p>
</dd>
<dt>
<span class="term">402 Authorization Required</span>
</dt>
<dd>
<p>
The method requires a Username and Password pair to continue. After sending
this message the method will expect APT to send a <span class="emphasis"><em>602 Authorization
Credentials</em></span> message with the required information. It is possible
for a method to send this multiple times. Fields: Site
</p>
</dd>
<dt>
<span class="term">403 Media Failure</span>
</dt>
<dd>
<p>
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
</p>
</dd>
<dt>
<span class="term">600 URI Acquire</span>
</dt>
<dd>
<p>
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
</p>
</dd>
<dt>
<span class="term">601 Configuration</span>
</dt>
<dd>
<p>
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.
</p>
</dd>
<dt>
<span class="term">602 Authorization Credentials</span>
</dt>
<dd>
<p>
This is sent in response to a <span class="emphasis"><em>402 Authorization Required</em></span>
message. It contains the entered username and password. Fields: Site, User,
Password
</p>
</dd>
<dt>
<span class="term">603 Media Changed</span>
</dt>
<dd>
<p>
This is sent in response to a <span class="emphasis"><em>403 Media Failure</em></span>
message. It indicates that the user has changed media and it is safe
to proceed. Fields: Media, Fail
</p>
</dd>
</dl>
</div>
</div>
<div class="section">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="s2.4"/>2.4. Notes</h2>
</div>
</div>
</div>
<p>
The methods supplied by the stock apt are:
</p>
<div class="orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>
cdrom - For Multi-Disc CD-ROMs
</p>
</li>
<li class="listitem">
<p>
copy - (internal) For copying files around the filesystem
</p>
</li>
<li class="listitem">
<p>
file - For local files
</p>
</li>
<li class="listitem">
<p>
gzip - (internal) For decompression
</p>
</li>
<li class="listitem">
<p>
http - For HTTP servers
</p>
</li>
</ol>
</div>
<p>
The two internal methods, copy and gzip, are used by the acquire code to
parallelize 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:
</p>
<pre class="screen">
http://foo.com/Packages.gz -> /bar/Packages.gz
gzip:/bar/Packages.gz -> /bar/Packages.decomp
rename Packages.decomp to /final/Packages
</pre>
<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.
</p>
</div>
</div>
<div class="navfooter">
<hr/>
<table width="100%" summary="Navigation footer">
<tr>
<td align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<td align="center"> </td>
<td align="right"> </td>
</tr>
<tr>
<td align="left" valign="top">Chapter 1. Introduction </td>
<td align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td align="right" valign="top"> </td>
</tr>
</table>
</div>
</body>
</html>
