You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

733 lines
18 KiB

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