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.

external-installation-planner-protocol.md 13 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301
  1. # APT External Installation Planner Protocol (EIPP) - version 0.1
  2. This document describes the communication protocol between APT and
  3. external installation planner. The protocol is called APT EIPP, for "APT
  4. External Installation Planner Protocol".
  5. ## Terminology
  6. In the following we use the term **architecture qualified package name**
  7. (or *arch-qualified package names* for short) to refer to package
  8. identifiers of the form "package:arch" where "package" is a package name
  9. and "arch" a dpkg architecture.
  10. ## Components
  11. - **APT**: we know this one.
  12. - APT is equipped with its own **internal planner** for the order of
  13. package installation (and removal) which is identified by the string
  14. `internal`.
  15. - **External planner**: an *external* software component able to plan an
  16. installation on behalf of APT.
  17. At each interaction with APT, a single planner is in use. When there is
  18. a total of 2 or more planners, internals or externals, the user can
  19. choose which one to use.
  20. Each planner is identified by an unique string, the **planner name**.
  21. Planner names must be formed using only alphanumeric ASCII characters,
  22. dashes, and underscores; planner names must start with a lowercase ASCII
  23. letter. The special name `internal` denotes APT's internal planner, is
  24. reserved, and cannot be used by external planners.
  25. ## Installation
  26. Each external planner is installed as a file under Dir::Bin::Planners
  27. (see below), which defaults to `/usr/lib/apt/planners`. We will assume
  28. in the remainder of this section that such a default value is in effect.
  29. The naming scheme is `/usr/lib/apt/planners/NAME`, where `NAME` is the
  30. name of the external planner.
  31. Each file under `/usr/lib/apt/planners` corresponding to an external
  32. planner must be executable.
  33. No non-planner files must be installed under `/usr/lib/apt/planners`, so
  34. that an index of available external planners can be obtained by listing
  35. the content of that directory.
  36. ## Configuration
  37. Several APT options can be used to affect installation planing in APT.
  38. An overview of them is given below. Please refer to proper APT
  39. configuration documentation for more, and more up to date, information.
  40. - **APT::Planner**: the name of the planner to be used for dependency
  41. solving. Defaults to `internal`
  42. - **Dir::Bin::Planners**: absolute path of the directory where to look
  43. for external solvers. Defaults to `/usr/lib/apt/planners`.
  44. ## Protocol
  45. When configured to use an external planner, APT will resort to it to
  46. decide in which order packages should be installed, configured and
  47. removed.
  48. The interaction happens **in batch**: APT will invoke the external
  49. planner passing the current status of (half-)installed packages and of
  50. packages which should be installed, as well as a request denoting the
  51. packages to install, reinstall, remove and purge. The external planner
  52. will compute a valid plan of when and how to call the low-level package
  53. manager (like dpkg) with each package to satisfy the request.
  54. External planners are invoked by executing them. Communications happens
  55. via the file descriptors: **stdin** (standard input) and **stdout**
  56. (standard output). stderr is not used by the EIPP protocol. Planners can
  57. therefore use stderr to dump debugging information that could be
  58. inspected separately.
  59. After invocation, the protocol passes through a sequence of phases:
  60. 1. APT invokes the external planner
  61. 2. APT send to the planner an installation planner **scenario**
  62. 3. The planner calculates the order. During this phase the planner may
  63. send, repeatedly, **progress** information to APT.
  64. 4. The planner sends back to APT an **answer**, i.e. either a *solution*
  65. or an *error* report.
  66. 5. The external planner exits
  67. ### Scenario
  68. A scenario is a text file encoded in a format very similar to the "Deb
  69. 822" format (AKA "the format used by Debian `Packages` files"). A
  70. scenario consists of two distinct parts: a **request** and a **package
  71. universe**, occurring in that order. The request consists of a single
  72. Deb 822 stanza, while the package universe consists of several such
  73. stanzas. All stanzas occurring in a scenario are separated by an empty
  74. line.
  75. #### Request
  76. Within an installation planner scenario, a request represents the action
  77. on packages requested by the user explicitly as well as potentially
  78. additions calculated by a dependency resolver which the user has
  79. accepted.
  80. An installation planner is not allowed to suggest the modification of
  81. package states (e.g. removing additional packages) even if it can't
  82. calculate a solution otherwise – the planner must error out in such
  83. a case. An exception is made for scenarios which contain packages which
  84. aren't completely installed (like half-installed or trigger-awaiting):
  85. Solvers are free to move these packages to a fully installed state (but
  86. are still forbidden to remove them).
  87. A request is a single Deb 822 stanza opened by a mandatory Request field
  88. and followed by a mixture of action, preference, and global
  89. configuration fields.
  90. The value of the **Request:** field is a string describing the EIPP
  91. protocol which will be used to communicate and especially which answers
  92. APT will understand. At present, the string must be `EIPP 0.1`. Request
  93. fields are mainly used to identify the beginning of a request stanza;
  94. their actual values are otherwise not used by the EIPP protocol.
  95. The following **configuration fields** are supported in request stanzas:
  96. - **Architecture:** (mandatory) The name of the *native* architecture on
  97. the user machine (see also: `dpkg --print-architecture`)
  98. - **Architectures:** (optional, defaults to the native architecture) A
  99. space separated list of *all* architectures known to APT (this is
  100. roughly equivalent to the union of `dpkg --print-architecture` and
  101. `dpkg --print-foreign-architectures`)
  102. The following **action fields** are supported in request stanzas:
  103. - **Install:** (optional, defaults to the empty string) A space
  104. separated list of arch-qualified package names, with *no version
  105. attached*, to install. This field denotes a list of packages that the
  106. user wants to install, usually via an APT `install` request.
  107. - **Remove:** (optional, defaults to the empty string) Same syntax of
  108. Install. This field denotes a list of packages that the user wants to
  109. remove, usually via APT `remove` or `purge` requests.
  110. - **ReInstall:** (optional, defaults to the empty string) Same syntax of
  111. Install. This field denotes a list of packages which are installed,
  112. but should be reinstalled again e.g. because files shipped by that
  113. package were removed or corrupted accidentally, usually requested via
  114. an APT `install` request with the `--reinstall` flag.
  115. The following **preference fields** are supported in request stanzas:
  116. - **Planner:** (optional, defaults to the empty string) a purely
  117. informational string specifying to which planner this request was send
  118. initially.
  119. - **Immediate-Configuration:** (option, unset by default) A boolean
  120. value defining if the planner should try to configure all packages as
  121. quickly as possible (true) or shouldn't perform any kind of immediate
  122. configuration at all (false). If not explicitly set with this field
  123. the planner is free to pick either mode or implementing e.g. a mode
  124. which configures only packages immediately if they are flagged as
  125. `Essential` (or are dependencies of packages marked as `Essential`).
  126. - **Allow-Temporary-Remove-of-Essentials** (optional, defaults to `no`).
  127. A boolean value allowing the planner (if set to yes) to temporarily
  128. remove an essential package. Associated with the APT::Force-LoopBreak
  129. configuration option its main use is highlighting that planners who do
  130. temporary removes must take special care in terms of essentials. Legit
  131. uses of this option by users is very uncommon, traditionally
  132. a situation in which it is needed indicates a packaging error.
  133. #### Package universe
  134. A package universe is a list of Deb 822 stanzas, one per package, called
  135. **package stanzas**. Each package stanzas starts with a Package
  136. field. The following fields are supported in package stanzas:
  137. - The fields Package, Version, Architecture (all mandatory) and
  138. Multi-Arch, Pre-Depends, Depends, Conflicts, Breaks, Essential
  139. (optional) as they are contained in the dpkg database (see the manpage
  140. `dpkg-query (1)`).
  141. - **Status:** (optional, defaults to `uninstalled`). Allowed values are
  142. the "package status" names as listed in `dpkg-query (1)` and visible
  143. e.g. in the dpkg database as the second value in the space separated
  144. list of values in the Status field there. In other words: Neither
  145. desired action nor error flags are present in this field in EIPP!
  146. - **APT-ID:** (mandatory). Unique package identifier, according to APT.
  147. ### Answer
  148. An answer from the external planner to APT is either a *solution* or an
  149. *error*.
  150. The following invariant on **exit codes** must hold true. When the
  151. external planner is *able to find a solution*, it will write the
  152. solution to standard output and then exit with an exit code of 0. When
  153. the external planner is *unable to find a solution* (and is aware of
  154. that), it will write an error to standard output and then exit with an
  155. exit code of 0. An exit code other than 0 will be interpreted as
  156. a planner crash with no meaningful error about dependency resolution to
  157. convey to the user.
  158. #### Solution
  159. A solution is a list of Deb 822 stanzas. Each of them could be an:
  160. - unpack stanza to cause the extraction of a package to the disk
  161. - configure stanza to cause an unpacked package to be configured and
  162. therefore the installation to be completed
  163. - remove stanza to cause the removal of a package from the system
  164. An **unpack stanza** starts with an Unpack field and supports the
  165. following fields:
  166. - **Unpack:** (mandatory). The value is a package identifier,
  167. referencing one of the package stanzas of the package universe via its
  168. APT-ID field.
  169. - All fields supported by package stanzas.
  170. **Configure** and **Remove stanzas** require and support the same
  171. fields with the exception of the Unpack field which is replaced in
  172. these instances with the Configure or Remove field respectively.
  173. The order of the stanzas is significant (unlike in the EDSP protocol),
  174. with the first stanza being the first performed action. If multiple
  175. stanzas of the same type appear in direct succession the order in such
  176. a set isn't significant through.
  177. The solution needs to be valid (it is not allowed to configure a package
  178. before it was unpacked, dependency relations must be satisfied, …), but
  179. they don't need to be complete: A planner can and should expect that any
  180. package which wasn't explicitly configured will be configured at the end
  181. automatically. That also means through that a planner is not allowed to
  182. produce a solution in which a package remains unconfigured. Also,
  183. packages which are requested to be removed will be automatically removed
  184. at the end if not marked for removal explicitly earlier.
  185. In terms of expressivity, all stanzas can carry one single field each, as
  186. APT-IDs are enough to pinpoint packages to be installed/removed.
  187. Nonetheless, for protocol readability, it is recommended that planners
  188. either add unconditionally the fields Package, Version, and Architecture
  189. to all install/remove stanzas or, alternatively, that they support
  190. a `--verbose` command line flag that explicitly enables the output of
  191. those fields in solutions.
  192. #### Error
  193. An error is a single Deb 822 stanza, starting the field Error. The
  194. following fields are supported in error stanzas:
  195. - **Error:** (mandatory). The value of this field is ignored, although
  196. it should be a unique error identifier, such as a UUID.
  197. - **Message:** (mandatory). The value of this field is a text string,
  198. meant to be read by humans, that explains the cause of the planner
  199. error. Message fields might be multi-line, like the Description field
  200. in the dpkg database. The first line conveys a short message, which
  201. can be explained in more details using subsequent lines.
  202. ### Progress
  203. During dependency solving, an external planner may send progress
  204. information to APT using **progress stanzas**. A progress stanza starts
  205. with the Progress field and might contain the following fields:
  206. - **Progress:** (mandatory). The value of this field is a date and time
  207. timestamp from the UTC timezone, in RFC 2822 format (see 'date -uR' as
  208. an example). The timestamp provides a time annotation for the
  209. progress report.
  210. - **Percentage:** (optional). An integer from 0 to 100, representing the
  211. completion of the installation planning process, as declared by the
  212. planner.
  213. - **Message:** (optional). A textual message, meant to be read by the
  214. APT user, telling what is going on within the installation planner
  215. (e.g. the current phase of planning, as declared by the planner).
  216. # Future extensions
  217. Potential future extensions to this protocol are to be discussed on
  218. deity@lists.debian.org.