]>
Commit | Line | Data |
---|---|---|
dd80ca3c AL |
1 | <!doctype debiandoc system> |
2 | <!-- -*- mode: sgml; mode: fold -*- --> | |
3 | <book> | |
4 | <title>APT Method Interface </title> | |
5 | ||
6 | <author>Jason Gunthorpe <email>jgg@debian.org</email></author> | |
42c90c42 | 7 | <version>$Id: method.sgml,v 1.6 1998/12/14 04:00:34 jgg Exp $</version> |
dd80ca3c AL |
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 © 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/doc/copyright/GPL for the full license. | |
25 | </copyright> | |
26 | ||
27 | <toc sect> | |
28 | ||
29 | <chapt>Introduction | |
30 | <!-- General {{{ --> | |
31 | <!-- ===================================================================== --> | |
32 | <sect>General | |
33 | ||
34 | <p> | |
7e798dd7 | 35 | The APT method interface allows APT to acquire archive files (.deb), index |
42c90c42 | 36 | files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It |
dd80ca3c AL |
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 | <access>:<location>. Network addresses are given with the form | |
9977fc5b | 85 | <access>://[<user>[:<pas>]@]hostname[:port]/<location>. |
dd80ca3c AL |
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 | ||
7e798dd7 | 111 | <tag>acquire<item> |
dd80ca3c | 112 | The act of bring a URI into the local pathname space. This may simply |
7e798dd7 | 113 | be verifiying the existence of the URI or actually downloading it from |
dd80ca3c AL |
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 corrispond to the well known unix FD's, | |
129 | stdin, stdout and stderr. | |
130 | ||
dd80ca3c AL |
131 | <p> |
132 | Throught 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 successfull 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) | |
7e798dd7 AL |
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 | |
dd80ca3c AL |
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 | |
7e798dd7 | 165 | <item>600 URI Acquire - Request a URI be acquired |
dd80ca3c AL |
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 | |
dd80ca3c AL |
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 recieved. 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</>. | |
7e798dd7 | 180 | After that APT begins sending <em>600 URI Acquire</> and the method |
dd80ca3c AL |
181 | sends out <em>200 URI Start</>, <em>201 URI Done</> or |
182 | <em>400 URI Failure</>. No syncronization is performed, it is expected | |
7e798dd7 | 183 | that APT will send <em>600 URI Acquire</> messages at -any- time and |
dd80ca3c AL |
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 neccessary for the method | |
187 | to be constantly ready to recieve 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 | |
93bf083d | 201 | <tag>IMS-Hit<item>The already existing item is valid |
dd80ca3c AL |
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 | |
542ec555 AL |
210 | <tag>Fail<item>Operation failed |
211 | <tag>Drive<item>Drive the media should be placed in | |
dd80ca3c AL |
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. | |
93bf083d | 219 | <tag>Pipeline<item>The method is capable of pipelining. |
542ec555 | 220 | <tag>Local<item>The method only returns Filename: feilds. |
93bf083d | 221 | <tag>Send-Config<item>Send configuration to the method. |
dd80ca3c AL |
222 | <tag>Version<item>Version string for the method |
223 | </taglist> | |
224 | ||
225 | This is a list of which headers each status code can use | |
226 | ||
227 | <taglist> | |
228 | <tag>100 Capabilities<item> | |
93bf083d AL |
229 | Displays the capabilities of the method. Methods should set the |
230 | pipeline bit if their underlying protocol supports pipeling. The | |
231 | only known method that does support pipelining is http. | |
232 | Fields: Version, Single-Instance, Pre-Scan, Pipeline, Send-Config | |
dd80ca3c AL |
233 | |
234 | <tag>101 Log<item> | |
235 | A log message may be printed to the screen if debugging is enabled. This | |
236 | is only for debugging the method. | |
237 | Fields: Message | |
238 | ||
239 | <tag>102 Status<item> | |
240 | Message gives a progress indication for the method. It can be used to show | |
241 | pre-transfer status for internet type methods. | |
242 | Fields: Message | |
243 | ||
244 | <tag>200 URI Start<item> | |
245 | Indicates the URI is starting to be transfered. The URI is specified | |
246 | along with stats about the file itself. | |
247 | Fields: URI, Size, Last-Modified, Resume-Point | |
248 | ||
249 | <tag>201 URI Done<item> | |
250 | Indicates that a URI has completed being transfered. It is possible | |
251 | to specify a <em>201 URI Done</> without a <em>URI Start</> which would | |
252 | mean no data was transfered but the file is now available. A Filename | |
253 | field is specified when the URI is directly available in the local | |
254 | pathname space. APT will either directly use that file or copy it into | |
93bf083d AL |
255 | another location. It is possible to return Alt-* feilds to indicate that |
256 | another possibility for the URI has been found in the local pathname space. | |
257 | This is done if a decompressed version of a .gz file is found. | |
dd80ca3c AL |
258 | Fields: URI, Size, Last-Modified, Filename, MD5-Hash |
259 | ||
260 | <tag>400 URI Failure<item> | |
261 | Indicates a fatal URI failure. The URI is not retrievable from this source. | |
262 | As with <em>201 URI Done</> <em>200 URI Start</> is not required to preceed | |
263 | this message | |
264 | Fields: URI, Message | |
265 | ||
266 | <tag>401 General Failure<item> | |
267 | Indicates that some unspecific failure has occured and the method is unable | |
268 | to continue. The method should terminate after sending this message. It | |
269 | is intended to check for invalid configuration options or other severe | |
270 | conditions. | |
271 | Fields: Message | |
272 | ||
273 | <tag>402 Authorization Required<item> | |
274 | The method requires a Username and Password pair to continue. After sending | |
275 | this message the method will expect APT to send a <em>602 Authorization | |
276 | Credentials</> message with the required information. It is possible for | |
277 | a method to send this multiple times. | |
278 | Fields: Site | |
279 | ||
280 | <tag>403 Media Failure<item> | |
281 | A method that deals with multiple media requires that a new media be inserted. | |
282 | The Media field contains the name of the media to be inserted. | |
542ec555 | 283 | Fields: Media, Drive |
dd80ca3c | 284 | |
7e798dd7 AL |
285 | <tag>600 URI Acquire<item> |
286 | APT is requesting that a new URI be added to the acquire list. Last-Modified | |
dd80ca3c | 287 | has the time stamp of the currently cache file if applicable. Filename |
7e798dd7 | 288 | is the name of the file that the acquired URI should be written to. |
dd80ca3c AL |
289 | Fields: URI, Filename Last-Modified |
290 | ||
291 | <tag>601 Configuration<item> | |
292 | APT is sending the configuration space to the method. A series of | |
293 | Config-Item fields will be part of this message, each containing an entry | |
294 | from the configuration space. | |
295 | Fields: Config-Item. | |
296 | ||
297 | <tag>602 Authorization Credentials<item> | |
298 | This is sent in response to a <em>402 Authorization Required</> message. | |
299 | It contains the entered username and password. | |
300 | Fields: Site, User, Password | |
301 | ||
302 | <tag>603 Media Changed<item> | |
303 | This is sent in response to a <em>403 Media Failure</> message. It | |
304 | indicates that the user has changed media and it is safe to proceed. | |
542ec555 | 305 | Fields: Media, Fail |
dd80ca3c AL |
306 | </taglist> |
307 | ||
308 | </sect> | |
309 | <!-- }}} --> | |
42c90c42 | 310 | <!-- Method Notes {{{ --> |
dd80ca3c | 311 | <!-- ===================================================================== --> |
42c90c42 AL |
312 | <sect>Notes |
313 | ||
314 | <p> | |
315 | The methods supplied by the stock apt are: | |
316 | <enumlist> | |
317 | <item>cdrom - For Multi-Disc CDROMs | |
318 | <item>copy - (internal) For copying files around the filesystem | |
319 | <item>file - For local files | |
320 | <item>gzip - (internal) For decompression | |
321 | <item>http - For HTTP servers | |
322 | </enumlist> | |
323 | ||
324 | <p> | |
325 | The two internal methods, copy and gzip, are used by the acquire code to | |
326 | parallize and simplify the automatic decompression of package files as well | |
327 | as copying package files around the file system. Both methods can be seen to | |
328 | act the same except that one decompresses on the fly. APT uses them by | |
329 | generating a copy URI that is formed identically to a file URI. The destination | |
330 | file is send as normal. The method then takes the file specified by the | |
331 | URI and writes it to the destination file. A typical set of operations may | |
332 | be: | |
333 | <example> | |
334 | http://foo.com/Packages.gz -> /bar/Packages.gz | |
335 | gzip:/bar/Packages.gz -> /bar/Packages.decomp | |
336 | rename Packages.decomp to /final/Packages | |
337 | </example> | |
338 | ||
339 | <p> | |
340 | The http method implements a fully featured HTTP/1.1 client that supports | |
341 | deep pipelining and reget. It works best when coupled with an apache 1.3 | |
342 | server. The file method simply generates failures or success responses with | |
343 | the filename field set to the proper location. The cdrom method acts the same | |
344 | except that it checks that the mount point has a valid cdrom in it. It does | |
345 | this by (effectively) computing a md5 hash of 'ls -l' on the mountpoint. | |
dd80ca3c AL |
346 | |
347 | </sect> | |
348 | <!-- }}} --> | |
349 | ||
350 | </book> |