doc/method.dbk

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- -*- DocBook -*- -->
   3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   5 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
   6 ]>
   7
   8 <book lang="en">
   9
  10 <title>APT Method Interface</title>
  11
  12 <bookinfo>
  13
  14 <authorgroup>
  15   <author>
  16     <personname>Jason Gunthorpe</personname><email>jgg@debian.org</email>
  17   </author>
  18 </authorgroup>
  19
  20 <releaseinfo>Version &apt-product-version;</releaseinfo>
  21
  22 <abstract>
  23 <para>
  24 This document describes the interface that APT uses to the archive access
  25 methods.
  26 </para>
  27 </abstract>
  28
  29 <copyright><year>1998</year><holder>Jason Gunthorpe</holder></copyright>
  30
  31 <legalnotice>
  32 <title>License Notice</title>
  33 <para>
  34 "APT" and this document are free software; you can redistribute them and/or
  35 modify them under the terms of the GNU General Public License as published by
  36 the Free Software Foundation; either version 2 of the License, or (at your
  37 option) any later version.
  38 </para>
  39 <para>
  40 For more details, on Debian systems, see the file
  41 /usr/share/common-licenses/GPL for the full license.
  42 </para>
  43 </legalnotice>
  44
  45 </bookinfo>
  46
  47 <chapter id="ch1"><title>Introduction</title>
  48
  49 <section id="s1.1"><title>General</title>
  50 <para>
  51 The APT method interface allows APT to acquire archive files (.deb), index
  52 files (Packages, Release, Mirrors) and source files (.tar.gz, .diff). It is a
  53 general, extensible system designed to satisfy all of these requirements:
  54 </para>
  55 <orderedlist numeration="arabic">
  56 <listitem>
  57 <para>
  58 Remote methods that download files from a distant site
  59 </para>
  60 </listitem>
  61 <listitem>
  62 <para>
  63 Resume of aborted downloads
  64 </para>
  65 </listitem>
  66 <listitem>
  67 <para>
  68 Progress reporting
  69 </para>
  70 </listitem>
  71 <listitem>
  72 <para>
  73 If-Modified-Since (IMS) checking for index files
  74 </para>
  75 </listitem>
  76 <listitem>
  77 <para>
  78 In-Line MD5 generation
  79 </para>
  80 </listitem>
  81 <listitem>
  82 <para>
  83 No-copy in-filesystem methods
  84 </para>
  85 </listitem>
  86 <listitem>
  87 <para>
  88 Multi-media methods (like CD's)
  89 </para>
  90 </listitem>
  91 <listitem>
  92 <para>
  93 Dynamic source selection for failure recovery
  94 </para>
  95 </listitem>
  96 <listitem>
  97 <para>
  98 User interaction for user/password requests and media swaps
  99 </para>
 100 </listitem>
 101 <listitem>
 102 <para>
 103 Global configuration
 104 </para>
 105 </listitem>
 106 </orderedlist>
 107 <para>
 108 Initial releases of APT (0.1.x) used a completely different method interface
 109 that only supported the first 6 items. This new interface deals with the
 110 remainder.
 111 </para>
 112 </section>
 113
 114 <section id="s1.2"><title>Terms</title>
 115 <para>
 116 Several terms are used through out the document, they have specific meanings
 117 which may not be immediately evident. To clarify they are summarized here.
 118 </para>
 119 <variablelist>
 120 <varlistentry>
 121 <term>source</term>
 122 <listitem>
 123 <para>
 124 Refers to an item in source list. More specifically it is the broken down
 125 item, that is each source maps to exactly one index file. Archive sources map
 126 to Package files and Source Code sources map to Source files.
 127 </para>
 128 </listitem>
 129 </varlistentry>
 130 <varlistentry>
 131 <term>archive file</term>
 132 <listitem>
 133 <para>
 134 Refers to a binary package archive (.deb, .rpm, etc).
 135 </para>
 136 </listitem>
 137 </varlistentry>
 138 <varlistentry>
 139 <term>source file</term>
 140 <listitem>
 141 <para>
 142 Refers to one of the files making up the source code of a package. In debian
 143 it is one of .diff.gz, .dsc. or .tar.gz.
 144 </para>
 145 </listitem>
 146 </varlistentry>
 147 <varlistentry>
 148 <term>URI</term>
 149 <listitem>
 150 <para>
 151 Universal Resource Identifier (URI) is a super-set of the familiar URL
 152 syntax used by web browsers. It consists of an access specification
 153 followed by a specific location in that access space. The form is
 154 &lt;access&gt;:&lt;location&gt;. Network addresses are given with the form
 155 &lt;access&gt;://[&lt;user&gt;[:&lt;pas&gt;]@]hostname[:port]/&lt;location&gt;.
 156 Some examples:
 157 </para>
 158 <screen>
 159 file:/var/mirrors/debian/
 160 ftp://ftp.debian.org/debian
 161 ftp://jgg:MooCow@localhost:21/debian
 162 nfs://bigred/var/mirrors/debian
 163 rsync://debian.midco.net/debian
 164 cdrom:Debian 2.0r1 Disk 1/
 165 </screen>
 166 </listitem>
 167 </varlistentry>
 168 <varlistentry>
 169 <term>method</term>
 170 <listitem>
 171 <para>
 172 There is a one to one mapping of URI access specifiers to methods. A method is
 173 a program that knows how to handle a URI access type and operates according to
 174 the specifications in this file.
 175 </para>
 176 </listitem>
 177 </varlistentry>
 178 <varlistentry>
 179 <term>method instance</term>
 180 <listitem>
 181 <para>
 182 A specific running method. There can be more than one instance of each method
 183 as APT is capable of concurrent method handling.
 184 </para>
 185 </listitem>
 186 </varlistentry>
 187 <varlistentry>
 188 <term>message</term>
 189 <listitem>
 190 <para>
 191 A series of lines terminated by a blank line sent down one of the communication
 192 lines. The first line should have the form xxx TAG where xxx are digits
 193 forming the status code and TAG is an informational string
 194 </para>
 195 </listitem>
 196 </varlistentry>
 197 <varlistentry>
 198 <term>acquire</term>
 199 <listitem>
 200 <para>
 201 The act of bring a URI into the local pathname space. This may simply be
 202 verifying the existence of the URI or actually downloading it from a remote
 203 site.
 204 </para>
 205 </listitem>
 206 </varlistentry>
 207 </variablelist>
 208 </section>
 209
 210 </chapter>
 211
 212 <chapter id="ch2"><title>Specification</title>
 213
 214 <section id="s2.1"><title>Overview</title>
 215 <para>
 216 All methods operate as a sub process of a main controlling parent. 3 FD's are
 217 opened for use by the method allowing two way communication and emergency error
 218 reporting. The FD's correspond to the well known unix FD's, stdin, stdout and
 219 stderr.
 220 </para>
 221 <para>
 222 Through operation of the method communication is done via http style plain
 223 text. Specifically RFC-822 (like the Package file) fields are used to describe
 224 items and a numeric-like header is used to indicate what is happening. Each of
 225 these distinct communication messages should be sent quickly and without pause.
 226 </para>
 227 <para>
 228 In some instances APT may pre-invoke a method to allow things like file URI's
 229 to determine how many files are available locally.
 230 </para>
 231 </section>
 232
 233 <section id="s2.2"><title>Message Overview</title>
 234 <para>
 235 The first line of each message is called the message header. The first 3
 236 digits (called the Status Code) have the usual meaning found in the http
 237 protocol. 1xx is informational, 2xx is successful and 4xx is failure. The 6xx
 238 series is used to specify things sent to the method. After the status code is
 239 an informational string provided for visual debugging.
 240 </para>
 241 <itemizedlist>
 242 <listitem>
 243 <para>
 244 100 Capabilities - Method capabilities
 245 </para>
 246 </listitem>
 247 <listitem>
 248 <para>
 249 101 Log - General Logging
 250 </para>
 251 </listitem>
 252 <listitem>
 253 <para>
 254 102 Status - Inter-URI status reporting (login progress)
 255 </para>
 256 </listitem>
 257 <listitem>
 258 <para>
 259 200 URI Start - URI is starting acquire
 260 </para>
 261 </listitem>
 262 <listitem>
 263 <para>
 264 201 URI Done - URI is finished acquire
 265 </para>
 266 </listitem>
 267 <listitem>
 268 <para>
 269 400 URI Failure - URI has failed to acquire
 270 </para>
 271 </listitem>
 272 <listitem>
 273 <para>
 274 401 General Failure - Method did not like something sent to it
 275 </para>
 276 </listitem>
 277 <listitem>
 278 <para>
 279 402 Authorization Required - Method requires authorization to access the URI.
 280 Authorization is User/Pass
 281 </para>
 282 </listitem>
 283 <listitem>
 284 <para>
 285 403 Media Failure - Method requires a media change
 286 </para>
 287 </listitem>
 288 <listitem>
 289 <para>
 290 600 URI Acquire - Request a URI be acquired
 291 </para>
 292 </listitem>
 293 <listitem>
 294 <para>
 295 601 Configuration - Sends the configuration space
 296 </para>
 297 </listitem>
 298 <listitem>
 299 <para>
 300 602 Authorization Credentials - Response to the 402 message
 301 </para>
 302 </listitem>
 303 <listitem>
 304 <para>
 305 603 Media Changed - Response to the 403 message
 306 </para>
 307 </listitem>
 308 </itemizedlist>
 309 <para>
 310 Only the 6xx series of status codes is sent TO the method. Furthermore the
 311 method may not emit status codes in the 6xx range. The Codes 402 and 403
 312 require that the method continue reading all other 6xx codes until the proper
 313 602/603 code is received. This means the method must be capable of handling an
 314 unlimited number of 600 messages.
 315 </para>
 316 <para>
 317 The flow of messages starts with the method sending out a <emphasis>100
 318 Capabilities</emphasis> and APT sending out a <emphasis>601
 319 Configuration</emphasis>. After that APT begins sending <emphasis>600 URI
 320 Acquire</emphasis> and the method sends out <emphasis>200 URI Start</emphasis>,
 321 <emphasis>201 URI Done</emphasis> or <emphasis>400 URI Failure</emphasis>. No
 322 synchronization is performed, it is expected that APT will send <emphasis>600
 323 URI Acquire</emphasis> messages at -any- time and that the method should queue
 324 the messages. This allows methods like http to pipeline requests to the remote
 325 server. It should be noted however that APT will buffer messages so it is not
 326 necessary for the method to be constantly ready to receive them.
 327 </para>
 328 </section>
 329
 330 <section id="s2.3"><title>Header Fields</title>
 331 <para>
 332 The following is a short index of the header fields that are supported
 333 </para>
 334 <variablelist>
 335 <varlistentry>
 336 <term>URI</term>
 337 <listitem>
 338 <para>
 339 URI being described by the message
 340 </para>
 341 </listitem>
 342 </varlistentry>
 343 <varlistentry>
 344 <term>Filename</term>
 345 <listitem>
 346 <para>
 347 Location in the filesystem
 348 </para>
 349 </listitem>
 350 </varlistentry>
 351 <varlistentry>
 352 <term>Last-Modified</term>
 353 <listitem>
 354 <para>
 355 A time stamp in RFC1123 notation for use by IMS checks
 356 </para>
 357 </listitem>
 358 </varlistentry>
 359 <varlistentry>
 360 <term>IMS-Hit</term>
 361 <listitem>
 362 <para>
 363 The already existing item is valid
 364 </para>
 365 </listitem>
 366 </varlistentry>
 367 <varlistentry>
 368 <term>Size</term>
 369 <listitem>
 370 <para>
 371 Size of the file in bytes
 372 </para>
 373 </listitem>
 374 </varlistentry>
 375 <varlistentry>
 376 <term>Resume-Point</term>
 377 <listitem>
 378 <para>
 379 Location that transfer was started
 380 </para>
 381 </listitem>
 382 </varlistentry>
 383 <varlistentry>
 384 <term>MD5-Hash</term>
 385 <listitem>
 386 <para>
 387 Computed MD5 hash for the file
 388 </para>
 389 </listitem>
 390 </varlistentry>
 391 <varlistentry>
 392 <term>Message</term>
 393 <listitem>
 394 <para>
 395 String indicating some displayable message
 396 </para>
 397 </listitem>
 398 </varlistentry>
 399 <varlistentry>
 400 <term>Media</term>
 401 <listitem>
 402 <para>
 403 String indicating the media name required
 404 </para>
 405 </listitem>
 406 </varlistentry>
 407 <varlistentry>
 408 <term>Site</term>
 409 <listitem>
 410 <para>
 411 String indicating the site authorization is required for
 412 </para>
 413 </listitem>
 414 </varlistentry>
 415 <varlistentry>
 416 <term>User</term>
 417 <listitem>
 418 <para>
 419 Username for authorization
 420 </para>
 421 </listitem>
 422 </varlistentry>
 423 <varlistentry>
 424 <term>Password</term>
 425 <listitem>
 426 <para>
 427 Password for authorization
 428 </para>
 429 </listitem>
 430 </varlistentry>
 431 <varlistentry>
 432 <term>Fail</term>
 433 <listitem>
 434 <para>
 435 Operation failed
 436 </para>
 437 </listitem>
 438 </varlistentry>
 439 <varlistentry>
 440 <term>Drive</term>
 441 <listitem>
 442 <para>
 443 Drive the media should be placed in
 444 </para>
 445 </listitem>
 446 </varlistentry>
 447 <varlistentry>
 448 <term>Config-Item</term>
 449 <listitem>
 450 <para>
 451 A string of the form
 452 <replaceable>item</replaceable>=<replaceable>value</replaceable> derived from
 453 the APT configuration space. These may include method specific values and
 454 general values not related to the method. It is up to the method to filter out
 455 the ones it wants.
 456 </para>
 457 </listitem>
 458 </varlistentry>
 459 <varlistentry>
 460 <term>Single-Instance</term>
 461 <listitem>
 462 <para>
 463 Requires that only one instance of the method be run This is a yes/no value.
 464 </para>
 465 </listitem>
 466 </varlistentry>
 467 <varlistentry>
 468 <term>Pipeline</term>
 469 <listitem>
 470 <para>
 471 The method is capable of pipelining.
 472 </para>
 473 </listitem>
 474 </varlistentry>
 475 <varlistentry>
 476 <term>Local</term>
 477 <listitem>
 478 <para>
 479 The method only returns Filename: fields.
 480 </para>
 481 </listitem>
 482 </varlistentry>
 483 <varlistentry>
 484 <term>Send-Config</term>
 485 <listitem>
 486 <para>
 487 Send configuration to the method.
 488 </para>
 489 </listitem>
 490 </varlistentry>
 491 <varlistentry>
 492 <term>Needs-Cleanup</term>
 493 <listitem>
 494 <para>
 495 The process is kept around while the files it returned are being used. This is
 496 primarily intended for CD-ROM and File URIs that need to unmount filesystems.
 497 </para>
 498 </listitem>
 499 </varlistentry>
 500 <varlistentry>
 501 <term>Version</term>
 502 <listitem>
 503 <para>
 504 Version string for the method
 505 </para>
 506 </listitem>
 507 </varlistentry>
 508 </variablelist>
 509 <para>
 510 This is a list of which headers each status code can use
 511 </para>
 512 <variablelist>
 513 <varlistentry>
 514 <term>100 Capabilities</term>
 515 <listitem>
 516 <para>
 517 Displays the capabilities of the method. Methods should set the pipeline bit
 518 if their underlying protocol supports pipelining. The only known method that
 519 does support pipelining is http. Fields: Version, Single-Instance, Pre-Scan,
 520 Pipeline, Send-Config, Needs-Cleanup
 521 </para>
 522 </listitem>
 523 </varlistentry>
 524 <varlistentry>
 525 <term>101 Log</term>
 526 <listitem>
 527 <para>
 528 A log message may be printed to the screen if debugging is enabled. This is
 529 only for debugging the method. Fields: Message
 530 </para>
 531 </listitem>
 532 </varlistentry>
 533 <varlistentry>
 534 <term>102 Status</term>
 535 <listitem>
 536 <para>
 537 Message gives a progress indication for the method. It can be used to show
 538 pre-transfer status for Internet type methods. Fields: Message
 539 </para>
 540 </listitem>
 541 </varlistentry>
 542 <varlistentry>
 543 <term>200 URI Start</term>
 544 <listitem>
 545 <para>
 546 Indicates the URI is starting to be transferred. The URI is specified along
 547 with stats about the file itself. Fields: URI, Size, Last-Modified,
 548 Resume-Point
 549 </para>
 550 </listitem>
 551 </varlistentry>
 552 <varlistentry>
 553 <term>201 URI Done</term>
 554 <listitem>
 555 <para>
 556 Indicates that a URI has completed being transferred. It is possible to
 557 specify a <emphasis>201 URI Done</emphasis> without a <emphasis>URI
 558 Start</emphasis> which would mean no data was transferred but the file is now
 559 available. A Filename field is specified when the URI is directly available in
 560 the local pathname space. APT will either directly use that file or copy it
 561 into another location. It is possible to return Alt-* fields to indicate that
 562 another possibility for the URI has been found in the local pathname space.
 563 This is done if a decompressed version of a .gz file is found. Fields: URI,
 564 Size, Last-Modified, Filename, MD5-Hash
 565 </para>
 566 </listitem>
 567 </varlistentry>
 568 <varlistentry>
 569 <term>400 URI Failure</term>
 570 <listitem>
 571 <para>
 572 Indicates a fatal URI failure. The URI is not retrievable from this source. As
 573 with <emphasis>201 URI Done</emphasis> <emphasis>200 URI Start</emphasis> is
 574 not required to precede this message Fields: URI, Message
 575 </para>
 576 </listitem>
 577 </varlistentry>
 578 <varlistentry>
 579 <term>401 General Failure</term>
 580 <listitem>
 581 <para>
 582 Indicates that some unspecific failure has occurred and the method is unable
 583 to  continue. The method should terminate after sending this message. It
 584 is intended to check for invalid configuration options or other severe
 585 conditions. Fields: Message
 586 </para>
 587 </listitem>
 588 </varlistentry>
 589 <varlistentry>
 590 <term>402 Authorization Required</term>
 591 <listitem>
 592 <para>
 593 The method requires a Username and Password pair to continue. After sending
 594 this message the method will expect APT to send a <emphasis>602 Authorization
 595 Credentials</emphasis> message with the required information. It is possible
 596 for a method to send this multiple times. Fields: Site
 597 </para>
 598 </listitem>
 599 </varlistentry>
 600 <varlistentry>
 601 <term>403 Media Failure</term>
 602 <listitem>
 603 <para>
 604 A method that deals with multiple media requires that a new media be
 605 inserted. The Media field contains the name of the media to be
 606 inserted. Fields: Media, Drive
 607 </para>
 608 </listitem>
 609 </varlistentry>
 610 <varlistentry>
 611 <term>600 URI Acquire</term>
 612 <listitem>
 613 <para>
 614 APT is requesting that a new URI be added to the acquire list. Last-Modified
 615 has the time stamp of the currently cache file if applicable. Filename is the
 616 name of the file that the acquired URI should be written to. Fields: URI,
 617 Filename Last-Modified
 618 </para>
 619 </listitem>
 620 </varlistentry>
 621 <varlistentry>
 622 <term>601 Configuration</term>
 623 <listitem>
 624 <para>
 625 APT is sending the configuration space to the method. A series of Config-Item
 626 fields will be part of this message, each containing an entry from the
 627 configuration space. Fields: Config-Item.
 628 </para>
 629 </listitem>
 630 </varlistentry>
 631 <varlistentry>
 632 <term>602 Authorization Credentials</term>
 633 <listitem>
 634 <para>
 635 This is sent in response to a <emphasis>402 Authorization Required</emphasis>
 636 message. It contains the entered username and password. Fields: Site, User,
 637 Password
 638 </para>
 639 </listitem>
 640 </varlistentry>
 641 <varlistentry>
 642 <term>603 Media Changed</term>
 643 <listitem>
 644 <para>
 645 This is sent in response to a <emphasis>403 Media Failure</emphasis>
 646 message. It indicates that the user has changed media and it is safe
 647 to proceed. Fields: Media, Fail
 648 </para>
 649 </listitem>
 650 </varlistentry>
 651 </variablelist>
 652 </section>
 653
 654 <section id="s2.4"><title>Notes</title>
 655 <para>
 656 The methods supplied by the stock apt are:
 657 </para>
 658 <orderedlist numeration="arabic">
 659 <listitem>
 660 <para>
 661 cdrom - For Multi-Disc CD-ROMs
 662 </para>
 663 </listitem>
 664 <listitem>
 665 <para>
 666 copy - (internal) For copying files around the filesystem
 667 </para>
 668 </listitem>
 669 <listitem>
 670 <para>
 671 file - For local files
 672 </para>
 673 </listitem>
 674 <listitem>
 675 <para>
 676 gzip - (internal) For decompression
 677 </para>
 678 </listitem>
 679 <listitem>
 680 <para>
 681 http - For HTTP servers
 682 </para>
 683 </listitem>
 684 </orderedlist>
 685 <para>
 686 The two internal methods, copy and gzip, are used by the acquire code to
 687 parallize and simplify the automatic decompression of package files as well as
 688 copying package files around the file system. Both methods can be seen to act
 689 the same except that one decompresses on the fly. APT uses them by generating
 690 a copy URI that is formed identically to a file URI. The destination file is
 691 send as normal. The method then takes the file specified by the URI and writes
 692 it to the destination file. A typical set of operations may be:
 693 </para>
 694 <screen>
 695 http://foo.com/Packages.gz -&gt; /bar/Packages.gz
 696 gzip:/bar/Packages.gz -&gt; /bar/Packages.decomp
 697 rename Packages.decomp to /final/Packages
 698 </screen>
 699 <para>
 700 The http method implements a fully featured HTTP/1.1 client that supports
 701 deep pipelining and reget. It works best when coupled with an apache 1.3
 702 server. The file method simply generates failures or success responses
 703 with the filename field set to the proper location. The cdrom method acts
 704 the same except that it checks that the mount point has a valid cdrom in
 705 it. It does this by (effectively) computing a md5 hash of 'ls -l' on the
 706 mountpoint.
 707 </para>
 708 </section>
 709
 710 </chapter>
 711
 712 </book>