doc/spec/rootless-builds.txt

   1 Supporting rootless builds
   2 ==========================
   3
   4 Status: recommendation, stable
   5 Version: 1.0
   6
   7 Background
   8 ----------
   9
  10 Traditionally, Debian packages have required (fake)root privileges for some
  11 of the "debian/rules" targets. This has required also a split between build
  12 and binary targets; making the builds slower, due to the increased amount
  13 of invocations of "debian/rules" and the overhead of using fakeroot(1) or
  14 equivalent fake environments, or less secure due to the increased dangers
  15 of running under real root via sudo or equivalent.
  16
  17 On this document when talking about "(fake)root" privileges, it will refer
  18 to any mechanism, supported by the dpkg-buildpackage "-r/--root-command"
  19 option, that can provide either a real or faked root user environment.
  20
  21 Specification
  22 -------------
  23
  24 We add a new field to the "Source" stanza of debian/control:
  25
  26   Rules-Requires-Root: no | binary-targets | <implementations-keywords>
  27
  28 The case sensitive values are defined as:
  29
  30  * If "no", then "debian/rules binary" will not require root at all (not even
  31    fakeroot). This is the default in dpkg-build-api level >= 1.
  32    - If the "no" keyword is used, it MUST be the only keyword in that field
  33      and MUST appear exactly once.
  34
  35  * If "binary-targets", then "debian/rules binary" (etc.) must always be run
  36    under (fake)root. This is the status quo, default in dpkg-build-api level 0.
  37
  38  * <implementations-keywords> will be a space separated list of keywords which
  39    define when root is required.
  40
  41    - Keywords consists of <namespace>/<cases>. The "namespace" part cannot
  42      contain "/" or whitespace. The "cases" part cannot contain whitespace.
  43      Furthermore, both parts MUST consist entirely of printable ASCII
  44      characters.
  45
  46    - Each tool/package will define a namespace named after itself and provide
  47      a number of cases where (fake)root is required.
  48      (See also "Implementation provided keywords".)
  49
  50    - When "Rules-Requires-Root" is set to <implementations-keywords>, the
  51      builder (i.e. whatever is executing debian/rules) will expose an
  52      interface that is used to run a command under (fake)root via the
  53      "Gain Root API". If the builder cannot provide such a command, it
  54      MUST behave like "Rules-Requires-Root" was set to "binary-targets",
  55      i.e. run "debian/rules binary" under (fake)root.
  56
  57 When the builder supports this specification, it MUST notify this fact to
  58 the rules file via the "DEB_RULES_REQUIRES_ROOT" environment variable, with
  59 the value it has obtained from the Rules-Requires-Root field or some builder
  60 specific override mechanism, which will denote the level of support the
  61 builder has chosen to commit to take effect during the build. When set,
  62 it MUST be a valid value for the Rules-Requires-Root field. If unset,
  63 the build system SHOULD assume that the builder does not recognize the
  64 Rules-Requires-Root field at all.
  65
  66 It is always permissible for a builder to ignore this field and fall back to
  67 running the binary targets under (fake)root. This is to ensure backwards
  68 compatibility when builds are performed by legacy builders or older versions
  69 of the tooling.
  70
  71 Tools called from the rules file MUST cope gracefully with being called under
  72 (fake)root even when Rules-Requires-Root is set to a value that implies they
  73 should not be (e.g. "no"). However, they MUST NOT attempt to run processes
  74 under (fake)root when run as a regular user when Rules-Requires-Root does
  75 not list any keywords they respond to.
  76
  77 Tools MUST gracefully ignore valid unknown keywords outside their namespace.
  78 They MAY warn about unknown keywords inside their namespace.
  79
  80 The value of this field MUST NOT change the content of the package in any
  81 way. Notably, packages that are bit-for-bit reproducible MUST still provide
  82 bit-for-bit identical results even when the field is ignored.
  83
  84 Implementation provided keywords
  85 --------------------------------
  86
  87 Keywords provided by various implementations:
  88
  89  * dpkg/target-subcommand: When the package needs to run a given command
  90    under (fake)root within the "debian/rules" files directly, this MUST be
  91    declared via this keyword.
  92
  93  * dpkg/target/<target-name>: When a specific "debian/rules" unofficial
  94    target (none of the root-requiring "binary-indep", "binary-arch", "binary",
  95    "clean", nor the non-root-requiring "build-indep", "build-arch", "build")
  96    needs to be run under (fake)root, this MUST be declared via this dynamic
  97    keyword, where <target-name> is the name of the "debian/rules" target.
  98
  99  * debhelper/upstream-make-install: The dh_auto_install command will run
 100    the "install" target from the upstream's Makefile under (fake)root (for
 101    the "makefile" build system or one derived from it).
 102
 103 Gain Root API
 104 -------------
 105
 106 The builder will provide a command to promote a given command to (fake)root
 107 by exposing it in the environment variable "DEB_GAIN_ROOT_CMD". Tools that
 108 need this promotion will then use it like the following:
 109
 110     $DEB_GAIN_ROOT_CMD cmd-that-needs-root ...
 111
 112 This command is subject to the same requirements as the "gain-root-command"
 113 that dpkg-buildpackage accepts via its "-r/--root-command" option, which
 114 means that it can contain space-separated parameters. If dpkg-buildpackage is
 115 called with "-r/--root-command", then dpkg-buildpackage shall use that value
 116 as the value for "DEB_GAIN_ROOT_CMD". The command SHOULD preserve all the
 117 environment variables, unmodified.
 118
 119 The variable SHOULD only be provided when there is a need for it. Notably
 120 when "Rules-Requires-Root" is either "no" or "binary-targets" the variable
 121 SHOULD NOT be defined.
 122
 123 (The "DEB_GAIN_ROOT_CMD" variable used to be named "DPKG_GAIN_ROOT_CMD"
 124 starting with dpkg 1.19.0 and before dpkg 1.19.1 when this specification
 125 got released as stable. The old name MUST not be used.)
 126
 127 Common cases
 128 ------------
 129
 130  * Upstream installation insists on "sudo make install"-like behavior.
 131    => Use dpkg/target-subcommand or debhelper/upstream-make-install.
 132
 133  * Files shipped in the package must be owned by another user than root.
 134    => Not covered; use "binary-targets" for now until dpkg+debhelper
 135       provides the required interface.
 136
 137 Prototyping/preparation
 138 =======================
 139
 140 dpkg side
 141 ---------
 142
 143 dpkg-deb --build provides the --root-owner-group option so that dh_builddeb
 144 or direct calls can control the owner/group file values w/o requiring
 145 (fake)root.
 146
 147 dpkg-buildpackage must export DEB_GAIN_ROOT_CMD when necessary (for
 148 prototyping, doing this unconditionally would be fine).
 149
 150
 151 debhelper side
 152 --------------
 153
 154 When the field is present:
 155
 156  * dh_testroot will behave as usual when Rules-Requires-Root is not present
 157    or set to "binary-targets".
 158
 159  * dh_testroot will be a no-op when Rules-Requires-Root is set to "no".
 160
 161  * Otherwise, dh_testroot will either verify that it is run under (fake)root
 162    (as usual) OR assert that DEB_GAIN_ROOT_CMD is defined.
 163
 164  * debhelper build systems will be patched to check for the
 165    "debhelper/upstream-make-install" keyword and use the "Gain Root API"
 166    accordingly.
 167
 168  * All other (src:)debhelper commands will skip their calls to chown
 169    (currently they just reset them to "0:0" anyway).
 170
 171 With the above, a default "dh $@" will no longer require (fake)root when
 172 built (and Rules-Requires-Root is "no").
 173
 174 Prototyping:
 175
 176  * During prototyping, dh_builddeb can wrap the dpkg-deb --build call with
 177    fakeroot (when not already root).