doc/method.sgml

   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>
   7 <version>$Id: method.sgml,v 1.3 1998/10/08 04:55:06 jgg 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/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>
  35 The APT method interface allows APT to acquire archive files (.deb), index
  36 files (Packages, Revision, 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 verifiying 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 corrispond to the well known unix FD's,
 129 stdin, stdout and stderr.
 130
 131 <p>
 132 The basic startup sequence depends on how the method is invoked. If any
 133 command line arguments are passed then the method should start in
 134 automatic mode. This facility is provided soley to make the methods
 135 easier to test and perhaps use outside of APT. Upon startup the method
 136 will print out a header describing its capabilities and requirements.
 137 After that it either begins processing the command line arugments and
 138 exits when done or waits for commands to be fed to it.
 139
 140 <p>
 141 Throught operation of the method communication is done via http
 142 style plain text. Specifically RFC-822 (like the Package file) fields
 143 are used to describe items and a numeric-like header is used to indicate
 144 what is happening. Each of these distinct communication messages should be
 145 sent quickly and without pause.
 146
 147 <p>
 148 In some instances APT may pre-invoke a method to allow things like file
 149 URI's to determine how many files are available locally.
 150 </sect>
 151                                                                   <!-- }}} -->
 152 <!-- Message Overview                                                  {{{ -->
 153 <!-- ===================================================================== -->
 154 <sect>Message Overview
 155
 156 <p>
 157 The first line of each message is called the message header. The first
 158 3 digits (called the Status Code) have the usual meaning found in the
 159 http protocol. 1xx is informational, 2xx is successfull and 4xx is failure.
 160 The 6xx series is used to specify things sent to the method. After the
 161 status code is an informational string provided for visual debugging.
 162
 163 <list>
 164 <item>100 Capabilities - Method capabilities
 165 <item>101 Log - General Logging
 166 <item>102 Status - Inter-URI status reporting (login progress)
 167 <item>200 URI Start - URI is starting acquire
 168 <item>201 URI Done - URI is finished acquire
 169 <item>400 URI Failure - URI has failed to acquire
 170 <item>401 General Failure - Method did not like something sent to it
 171 <item>402 Authorization Required - Method requires authorization
 172         to access the URI. Authorization is User/Pass
 173 <item>403 Media Failure - Method requires a media change
 174 <item>600 URI Acquire - Request a URI be acquired
 175 <item>601 Configuration - Sends the configuration space
 176 <item>602 Authorization Credentials - Response to the 402 message
 177 <item>603 Media Changed - Response to the 403 message
 178 <item>605 Shutdown - Exit
 179 </list>
 180
 181 Only the 6xx series of status codes is sent TO the method. Furthermore
 182 the method may not emit status codes in the 6xx range. The Codes 402
 183 and 403 require that the method continue reading all other 6xx codes
 184 until the proper 602/603 code is recieved. This means the method must be
 185 capable of handling an unlimited number of 600 messages.
 186
 187 <p>
 188 The flow of messages starts with the method sending out a
 189 <em>100 Capabilities</> and APT sending out a <em>601 Configuration</>.
 190 After that APT begins sending <em>600 URI Acquire</> and the method
 191 sends out <em>200 URI Start</>, <em>201 URI Done</> or
 192 <em>400 URI Failure</>. No syncronization is performed, it is expected
 193 that APT will send <em>600 URI Acquire</> messages at -any- time and
 194 that the method should queue the messages. This allows methods like http
 195 to pipeline requests to the remote server. It should be noted however
 196 that APT will buffer messages so it is not neccessary for the method
 197 to be constantly ready to recieve them.
 198 </sect>
 199                                                                   <!-- }}} -->
 200 <!-- Header Fields                                                     {{{ -->
 201 <!-- ===================================================================== -->
 202 <sect>Header Fields
 203
 204 <p>
 205 The following is a short index of the header fields that are supported
 206
 207 <taglist>
 208 <tag>URI<item>URI being described by the message
 209 <tag>Filename<item>Location in the filesystem
 210 <tag>Last-Modified<item>A time stamp in RFC1123 notation for use by IMS checks
 211 <tag>Size<item>Size of the file in bytes
 212 <tag>Resume-Point<item>Location that transfer was started
 213 <tag>MD5-Hash<item>Computed MD5 hash for the file
 214 <tag>Message<item>String indicating some displayable message
 215 <tag>Media<item>String indicating the media name required
 216 <tag>Site<item>String indicating the site authorization is required for
 217 <tag>User<item>Username for authorization
 218 <tag>Password<item>Password for authorization
 219 <tag>Config-Item<item>
 220 A string of the form <var>item</>=<var>value</> derived from the APT
 221 configuration space. These may include method specific values and general
 222 values not related to the method. It is up to the method to filter out
 223 the ones it wants.
 224 <tag>Single-Instance<item>Requires that only one instance of the method be run
 225                           This is a yes/no value.
 226 <tag>Pre-Scan<item>Method can detect if archives are already available.
 227                    This is a yes/no value.
 228 <tag>Version<item>Version string for the method
 229 </taglist>
 230
 231 This is a list of which headers each status code can use
 232
 233 <taglist>
 234 <tag>100 Capabilities<item>
 235 Displays the capabilities of the method.
 236 Fields: Version, Single-Instance, Pre-Scan
 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.
 260 Fields: URI, Size, Last-Modified, Filename, MD5-Hash
 261
 262 <tag>400 URI Failure<item>
 263 Indicates a fatal URI failure. The URI is not retrievable from this source.
 264 As with <em>201 URI Done</> <em>200 URI Start</> is not required to preceed
 265 this message
 266 Fields: URI, Message
 267
 268 <tag>401 General Failure<item>
 269 Indicates that some unspecific failure has occured and the method is unable
 270 to continue. The method should terminate after sending this message. It
 271 is intended to check for invalid configuration options or other severe
 272 conditions.
 273 Fields: Message
 274
 275 <tag>402 Authorization Required<item>
 276 The method requires a Username and Password pair to continue. After sending
 277 this message the method will expect APT to send a <em>602 Authorization
 278 Credentials</> message with the required information. It is possible for
 279 a method to send this multiple times.
 280 Fields: Site
 281
 282 <tag>403 Media Failure<item>
 283 A method that deals with multiple media requires that a new media be inserted.
 284 The Media field contains the name of the media to be inserted.
 285 Fields: Media
 286
 287 <tag>600 URI Acquire<item>
 288 APT is requesting that a new URI be added to the acquire list. Last-Modified
 289 has the time stamp of the currently cache file if applicable. Filename
 290 is the name of the file that the acquired URI should be written to.
 291 Fields: URI, Filename Last-Modified
 292
 293 <tag>601 Configuration<item>
 294 APT is sending the configuration space to the method. A series of
 295 Config-Item fields will be part of this message, each containing an entry
 296 from the configuration space.
 297 Fields: Config-Item.
 298
 299 <tag>602 Authorization Credentials<item>
 300 This is sent in response to a <em>402 Authorization Required</> message.
 301 It contains the entered username and password.
 302 Fields: Site, User, Password
 303
 304 <tag>603 Media Changed<item>
 305 This is sent in response to a <em>403 Media Failure</> message. It
 306 indicates that the user has changed media and it is safe to proceed.
 307 Fields: Media
 308
 309 <tag>605 Shutdown<item>
 310 APT sends this to signal the shutdown of the method. The method should
 311 terminate immidiately.
 312 Fields: None
 313 </taglist>
 314
 315 </sect>
 316                                                                   <!-- }}} -->
 317 <!-- Examples                                                          {{{ -->
 318 <!-- ===================================================================== -->
 319 <sect>Examples
 320
 321 </sect>
 322                                                                   <!-- }}} -->
 323
 324 </book>