doc/external-installation-planner-protocol.txt

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