- use automake defined pkgdata dir for lua script dir instead of hardcoded
[apt.git] / doc / method.sgml
1 <!-- -*- mode: sgml; mode: fold -*- -->
2 <!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">
3 <book>
4 <title>APT Method Interface </title>
5
6 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
7 <version>$Id: method.sgml,v 1.10 2003/02/12 15:05:46 doogie Exp $</version>
8
9 <abstract>
10 This document describes the interface that APT uses to the archive
11 access methods.
12 </abstract>
13
14 <copyright>
15 Copyright &copy; Jason Gunthorpe, 1998.
16 <p>
17 "APT" and this document are free software; you can redistribute them and/or
18 modify them under the terms of the GNU General Public License as published
19 by the Free Software Foundation; either version 2 of the License, or (at your
20 option) any later version.
21
22 <p>
23 For more details, on Debian GNU/Linux systems, see the file
24 /usr/share/common-licenses/GPL for the full license.
25 </copyright>
26
27 <toc sect>
28
29 <chapt>Introduction
30 <!-- General                                                           {{{ -->
31 <!-- ===================================================================== -->
32 <sect>General
33
34 <p>
35 The APT method interface allows APT to acquire archive files (.deb), index
36 files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It
37 is a general, extensible system designed to satisfy all of these
38 requirements:
39
40 <enumlist>
41 <item>Remote methods that download files from a distant site
42 <item>Resume of aborted downloads
43 <item>Progress reporting
44 <item>If-Modified-Since (IMS) checking for index files
45 <item>In-Line MD5 generation
46 <item>No-copy in-filesystem methods
47 <item>Multi-media methods (like CD's)
48 <item>Dynamic source selection for failure recovery
49 <item>User interaction for user/password requests and media swaps
50 <item>Global configuration
51 </enumlist>
52
53 Initial releases of APT (0.1.x) used a completely different method
54 interface that only supported the first 6 items. This new interface
55 deals with the remainder.
56 </sect>
57                                                                   <!-- }}} -->
58 <!-- Terms                                                             {{{ -->
59 <!-- ===================================================================== -->
60 <sect>Terms
61
62 <p>
63 Several terms are used through out the document, they have specific
64 meanings which may not be immediately evident. To clarify they are summarized
65 here.
66
67 <taglist>
68 <tag>source<item>
69 Refers to an item in source list. More specifically it is the broken down
70 item, that is each source maps to exactly one index file. Archive sources
71 map to Package files and Source Code sources map to Source files.
72
73 <tag>archive file<item>
74 Refers to a binary package archive (.deb, .rpm, etc). 
75
76 <tag>source file<item>
77 Refers to one of the files making up the source code of a package. In
78 debian it is one of .diff.gz, .dsc. or .tar.gz.
79
80 <tag>URI<item>
81 Universal Resource Identifier (URI) is a super-set of the familiar URL
82 syntax used by web browsers. It consists of an access specification
83 followed by a specific location in that access space. The form is
84 &lt;access&gt;:&lt;location&gt;. Network addresses are given with the form 
85 &lt;access&gt;://[&lt;user&gt;[:&lt;pas&gt;]@]hostname[:port]/&lt;location&gt;. 
86 Some examples:
87 <example>
88 file:/var/mirrors/debian/
89 ftp://ftp.debian.org/debian
90 ftp://jgg:MooCow@localhost:21/debian
91 nfs://bigred/var/mirrors/debian
92 rsync://debian.midco.net/debian
93 cdrom:Debian 2.0r1 Disk 1/
94 </example>
95
96 <tag>method<item>
97 There is a one to one mapping of URI access specifiers to methods. A method
98 is a program that knows how to handle a URI access type and operates according
99 to the specifications in this file.
100
101 <tag>method instance<item>
102 A specific running method. There can be more than one instance of each method
103 as APT is capable of concurrent method handling.
104
105 <tag>message<item>
106 A series of lines terminated by a blank line sent down one of the
107 communication lines. The first line should have the form xxx TAG
108 where xxx are digits forming the status code and TAG is an informational
109 string
110
111 <tag>acquire<item>
112 The act of bring a URI into the local pathname space. This may simply
113 be verifying the existence of the URI or actually downloading it from
114 a remote site.
115
116 </taglist>
117
118 </sect>
119                                                                   <!-- }}} -->
120 <chapt>Specification
121 <!-- Overview                                                          {{{ -->
122 <!-- ===================================================================== -->
123 <sect>Overview
124
125 <p>
126 All methods operate as a sub process of a main controlling parent. 3 FD's
127 are opened for use by the method allowing two way communication and
128 emergency error reporting. The FD's correspond to the well known unix FD's, 
129 stdin, stdout and stderr.
130
131 <p>
132 Through operation of the method communication is done via http 
133 style plain text. Specifically RFC-822 (like the Package file) fields
134 are used to describe items and a numeric-like header is used to indicate
135 what is happening. Each of these distinct communication messages should be
136 sent quickly and without pause.
137
138 <p> 
139 In some instances APT may pre-invoke a method to allow things like file
140 URI's to determine how many files are available locally.
141 </sect>
142                                                                   <!-- }}} -->
143 <!-- Message Overview                                                  {{{ -->
144 <!-- ===================================================================== -->
145 <sect>Message Overview
146
147 <p>
148 The first line of each message is called the message header. The first
149 3 digits (called the Status Code) have the usual meaning found in the 
150 http protocol. 1xx is informational, 2xx is successful and 4xx is failure. 
151 The 6xx series is used to specify things sent to the method. After the 
152 status code is an informational string provided for visual debugging.
153
154 <list>
155 <item>100 Capabilities - Method capabilities
156 <item>101 Log - General Logging
157 <item>102 Status - Inter-URI status reporting (login progress)
158 <item>200 URI Start - URI is starting acquire
159 <item>201 URI Done - URI is finished acquire
160 <item>400 URI Failure - URI has failed to acquire
161 <item>401 General Failure - Method did not like something sent to it
162 <item>402 Authorization Required - Method requires authorization
163         to access the URI. Authorization is User/Pass
164 <item>403 Media Failure - Method requires a media change        
165 <item>600 URI Acquire - Request a URI be acquired
166 <item>601 Configuration - Sends the configuration space
167 <item>602 Authorization Credentials - Response to the 402 message
168 <item>603 Media Changed - Response to the 403 message
169 </list>
170
171 Only the 6xx series of status codes is sent TO the method. Furthermore
172 the method may not emit status codes in the 6xx range. The Codes 402
173 and 403 require that the method continue reading all other 6xx codes
174 until the proper 602/603 code is received. This means the method must be
175 capable of handling an unlimited number of 600 messages.
176
177 <p>
178 The flow of messages starts with the method sending out a 
179 <em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
180 After that APT begins sending <em>600 URI Acquire</> and the method
181 sends out <em>200 URI Start</>, <em>201 URI Done</> or 
182 <em>400 URI Failure</>. No synchronization is performed, it is expected
183 that APT will send <em>600 URI Acquire</> messages at -any- time and
184 that the method should queue the messages. This allows methods like http
185 to pipeline requests to the remote server. It should be noted however
186 that APT will buffer messages so it is not necessary for the method
187 to be constantly ready to receive them.
188 </sect>
189                                                                   <!-- }}} -->
190 <!-- Header Fields                                                     {{{ -->
191 <!-- ===================================================================== -->
192 <sect>Header Fields
193
194 <p> 
195 The following is a short index of the header fields that are supported
196
197 <taglist>
198 <tag>URI<item>URI being described by the message
199 <tag>Filename<item>Location in the filesystem
200 <tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks
201 <tag>IMS-Hit<item>The already existing item is valid
202 <tag>Size<item>Size of the file in bytes
203 <tag>Resume-Point<item>Location that transfer was started
204 <tag>MD5-Hash<item>Computed MD5 hash for the file
205 <tag>Message<item>String indicating some displayable message
206 <tag>Media<item>String indicating the media name required
207 <tag>Site<item>String indicating the site authorization is required for
208 <tag>User<item>Username for authorization
209 <tag>Password<item>Password for authorization
210 <tag>Fail<item>Operation failed
211 <tag>Drive<item>Drive the media should be placed in
212 <tag>Config-Item<item>
213 A string of the form <var>item</>=<var>value</> derived from the APT 
214 configuration space. These may include method specific values and general
215 values not related to the method. It is up to the method to filter out
216 the ones it wants.
217 <tag>Single-Instance<item>Requires that only one instance of the method be run
218                           This is a yes/no value.
219 <tag>Pipeline<item>The method is capable of pipelining.
220 <tag>Local<item>The method only returns Filename: fields.
221 <tag>Send-Config<item>Send configuration to the method.
222 <tag>Needs-Cleanup<item>The process is kept around while the files it returned
223 are being used. This is primarily intended for CDROM and File URIs that need
224 to unmount filesystems.
225 <tag>Version<item>Version string for the method
226 </taglist>
227
228 This is a list of which headers each status code can use
229
230 <taglist>
231 <tag>100 Capabilities<item>
232 Displays the capabilities of the method. Methods should set the
233 pipeline bit if their underlying protocol supports pipelining. The
234 only known method that does support pipelining is http.
235 Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config, 
236 Needs-Cleanup
237
238 <tag>101 Log<item>
239 A log message may be printed to the screen if debugging is enabled. This
240 is only for debugging the method.
241 Fields: Message
242
243 <tag>102 Status<item>
244 Message gives a progress indication for the method. It can be used to show
245 pre-transfer status for Internet type methods.
246 Fields: Message
247
248 <tag>200 URI Start<item>
249 Indicates the URI is starting to be transfered. The URI is specified
250 along with stats about the file itself.
251 Fields: URI, Size, Last-Modified, Resume-Point
252
253 <tag>201 URI Done<item>
254 Indicates that a URI has completed being transfered. It is possible
255 to specify a <em>201 URI Done</> without a <em>URI Start</> which would
256 mean no data was transfered but the file is now available. A Filename
257 field is specified when the URI is directly available in the local 
258 pathname space. APT will either directly use that file or copy it into 
259 another location. It is possible to return Alt-* fields to indicate that
260 another possibility for the URI has been found in the local pathname space.
261 This is done if a decompressed version of a .gz file is found.
262 Fields: URI, Size, Last-Modified, Filename, MD5-Hash
263
264 <tag>400 URI Failure<item>
265 Indicates a fatal URI failure. The URI is not retrievable from this source.
266 As with <em>201 URI Done</> <em>200 URI Start</> is not required to precede
267 this message
268 Fields: URI, Message
269
270 <tag>401 General Failure<item>
271 Indicates that some unspecific failure has occurred and the method is unable
272 to continue. The method should terminate after sending this message. It 
273 is intended to check for invalid configuration options or other severe
274 conditions.
275 Fields: Message
276
277 <tag>402 Authorization Required<item>
278 The method requires a Username and Password pair to continue. After sending
279 this message the method will expect APT to send a <em>602 Authorization 
280 Credentials</> message with the required information. It is possible for
281 a method to send this multiple times.
282 Fields: Site
283
284 <tag>403 Media Failure<item>
285 A method that deals with multiple media requires that a new media be inserted.
286 The Media field contains the name of the media to be inserted.
287 Fields: Media, Drive
288
289 <tag>600 URI Acquire<item>
290 APT is requesting that a new URI be added to the acquire list. Last-Modified
291 has the time stamp of the currently cache file if applicable. Filename
292 is the name of the file that the acquired URI should be written to.
293 Fields: URI, Filename Last-Modified
294
295 <tag>601 Configuration<item>
296 APT is sending the configuration space to the method. A series of
297 Config-Item fields will be part of this message, each containing an entry
298 from the configuration space.
299 Fields: Config-Item.
300
301 <tag>602 Authorization Credentials<item>
302 This is sent in response to a <em>402 Authorization Required</> message. 
303 It contains the entered username and password.
304 Fields: Site, User, Password
305
306 <tag>603 Media Changed<item>
307 This is sent in response to a <em>403 Media Failure</> message. It
308 indicates that the user has changed media and it is safe to proceed.
309 Fields: Media, Fail
310 </taglist>
311
312 </sect>
313                                                                   <!-- }}} -->
314 <!-- Method Notes                                                      {{{ -->
315 <!-- ===================================================================== -->
316 <sect>Notes
317
318 <p>
319 The methods supplied by the stock apt are:
320 <enumlist>
321 <item>cdrom - For Multi-Disc CDROMs
322 <item>copy - (internal) For copying files around the filesystem
323 <item>file - For local files
324 <item>gzip - (internal) For decompression
325 <item>http - For HTTP servers
326 </enumlist>
327
328 <p>
329 The two internal methods, copy and gzip, are used by the acquire code to
330 parallize and simplify the automatic decompression of package files as well 
331 as copying package files around the file system. Both methods can be seen to 
332 act the same except that one decompresses on the fly. APT uses them by
333 generating a copy URI that is formed identically to a file URI. The destination
334 file is send as normal. The method then takes the file specified by the 
335 URI and writes it to the destination file. A typical set of operations may
336 be:
337 <example>
338 http://foo.com/Packages.gz -> /bar/Packages.gz
339 gzip:/bar/Packages.gz -> /bar/Packages.decomp
340 rename Packages.decomp to /final/Packages
341 </example>
342
343 <p>
344 The http method implements a fully featured HTTP/1.1 client that supports
345 deep pipelining and reget. It works best when coupled with an apache 1.3
346 server. The file method simply generates failures or success responses with
347 the filename field set to the proper location. The cdrom method acts the same
348 except that it checks that the mount point has a valid cdrom in it. It does 
349 this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint.
350
351 </sect>
352                                                                   <!-- }}} -->
353
354 </book>