[dpkg] 127/192: doc: Add new rootless builds experimental draft specification

Tue Oct 17 11:04:09 UTC 2017

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch pu/reproducible_builds
in repository dpkg.

commit 11fce7c00e04a5b045ba733d574a304515f1321e
Author: Niels Thykier <niels at thykier.net>
Date:   Sat Sep 16 15:54:18 2017 +0200

    doc: Add new rootless builds experimental draft specification
    
    [guillem at debian.org:
     - Mark the spec as an experimental draft.
     - Add new Background section.
     - Rename Package-Creation-Requires-Root to Rules-Requires-Root.
     - Rename dpkg/rules-requires-root to dpkg/target-subcommand.
     - Add new dpkg/target/<target-name> keyword.
     - Use dpkg-deb --build instead of dpkg --build.
     - Fix DPKG_GAIN_ROOT_CMD invocation, and denote it as the one to use
       instead of the alternative wrapper command.
     - Rearrange sections and reflow text. ]
    
    Signed-off-by: Guillem Jover <guillem at debian.org>
---
 Makefile.am             |   1 +
 debian/changelog        |   3 +
 debian/dpkg-dev.docs    |   1 +
 doc/rootless-builds.txt | 161 ++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 166 insertions(+)

diff --git a/Makefile.am b/Makefile.am
index c7d8f4e..5a77902 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -41,6 +41,7 @@ EXTRA_DIST = \
 	doc/coding-style.txt \
 	doc/frontend.txt \
 	doc/lcov-inject.pl \
+	doc/rootless-builds.txt \
 	doc/triggers.txt \
 	debian/changelog \
 	debian/compat \
diff --git a/debian/changelog b/debian/changelog
index c996a1c..196e239 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -91,6 +91,9 @@ dpkg (1.19.0) UNRELEASED; urgency=medium
     - Clarify that sanitize options should not be used for production builds.
     - Remove recommendation to use Pre-Depends for trigger directives from
       deb-triggers(5). Closes: #864882
+    - Add new rootless build experimental draft specification.
+      Initial proposal by Niels Thykier <niels at thykier.net>, wording fixes
+      and spec clarifications by Guillem Jover <guillem at debian.org>.
   * Code internals:
     - Switch perl code to use -> operator for function variables.
     - Switch perl code from split() with /\s+/ to ' '.
diff --git a/debian/dpkg-dev.docs b/debian/dpkg-dev.docs
index f432402..c141789 100644
--- a/debian/dpkg-dev.docs
+++ b/debian/dpkg-dev.docs
@@ -4,4 +4,5 @@ debian/usertags
 doc/README.api
 doc/README.feature-removal-schedule
 doc/frontend.txt
+doc/rootless-builds.txt
 doc/triggers.txt
diff --git a/doc/rootless-builds.txt b/doc/rootless-builds.txt
new file mode 100644
index 0000000..98e3877
--- /dev/null
+++ b/doc/rootless-builds.txt
@@ -0,0 +1,161 @@
+Supporting rootless builds
+==========================
+
+Status: draft, experimental
+
+Background
+----------
+
+Traditionally, Debian packages have required (fake)root privileges for some
+of the "debian/rules" targets. This has required also a split between build
+and binary targets; making the builds slower, due to the increased amount
+of invocations of "debian/rules" and the overhead of using fakeroot(1) or
+equivalent fake environments, or less secure due to the increased dangers
+of running under real root via sudo or equivalent.
+
+On this document when talking about "(fake)root" privileges, it will refer
+to any mechanism, supported by the dpkg-buildpackage "-r/--root-command"
+option, that can provide either a real or faked root user environment.
+
+Specification
+-------------
+
+We add a new field to the "Source" stanza of debian/control:
+
+  Rules-Requires-Root: no | binary-targets | <implementations-keywords>
+
+The values are defined as:
+
+ * If "no", then "debian/rules binary" will not require root at all (not even
+   fakeroot).
+   - If the "no" keyword is used, it MUST be the only keyword in that field
+     and MUST appear exactly once.
+
+ * If "binary-targets", then "debian/rules binary" (etc.) must always be run
+   under (fake)root. This is the default/status quo.
+
+ * <implementations-keywords> will be a space separated list of keywords which
+   define when root is required.
+
+   - Keywords consists of <namespace>/<cases>. The "namespace" part cannot
+     contain "/" or whitespace. The "cases" part cannot contain whitespace.
+     Furthermore, both parts MUST consist entirely of printable ASCII
+     characters.
+
+   - Each tool/package will define a namespace named after itself and provide
+     a number of cases where (fake)root is required.
+     (See also "Implementation provided keywords".)
+
+   - When "Rules-Requires-Root" is set to <implementations-keywords>, the
+     builder will expose an interface that is used to run a command under
+     (fake)root via the "Gain Root API". If the builder cannot provide such
+     a command, it MUST behave like "Rules-Requires-Root" was set to
+     "binary-targets", i.e. run "debian/rules binary" under (fake)root.
+
+It is always permissible for a builder to ignore this field and fall back to
+running the binary targets under (fake)root. This is to ensure backwards
+compatibility when builds are performed by legacy builders or older versions
+of the tooling.
+
+Tools called from the rules file MUST cope gracefully with being called under
+(fake)root even when Rules-Requires-Root is set to a value that implies they
+should not be (e.g. "no"). However, they MUST NOT attempt to run processes
+under (fake)root when run as a regular user when Rules-Requires-Root does
+not list any keywords they respond to.
+
+Tools MUST gracefully ignore valid unknown keywords outside their namespace.
+They MAY warn about unknown keywords inside their namespace.
+
+The value of this field MUST NOT change the content of the package in any
+way. Notably, packages that are bit-for-bit reproducible MUST still provide
+bit-for-bit identical results even when the field is ignored.
+
+Implementation provided keywords
+--------------------------------
+
+Keywords provided by various implementations:
+
+ * dpkg/target-subcommand: When the package needs to run a given command
+   under (fake)root within the "debian/rules" files directly, this MUST be
+   declared via this keyword.
+
+ * dpkg/target/<target-name>: When a specific "debian/rules" unofficial
+   target (none of the root-requiring "binary-indep", "binary-arch", "binary",
+   "clean", nor the non-root-requiring "build-indep", "build-arch", "build")
+   needs to be run under (fake)root, this MUST be declared via this dynamic
+   keyword, where <target-name> is the name of the "debian/rules" target.
+
+ * debhelper/upstream-make-install: The dh_auto_install command will run
+   the "install" target from the upstream's Makefile under (fake)root (for
+   the "makefile" build system or one derived from it).
+
+Gain Root API
+-------------
+
+The builder will provide a command to promote a given command to (fake)root
+by exposing it in the environment variable "DPKG_GAIN_ROOT_CMD". Tools that
+need this promotion will then use it like the following:
+
+    $DPKG_GAIN_ROOT_CMD cmd-that-needs-root ...
+
+This command is subject to the same requirements as the "gain-root-command"
+that dpkg-buildpackage accepts via its "-r/--root-command" option, which
+means that it can contain space-separated parameters. If dpkg-buildpackage is
+called with "-r/--root-command", then dpkg-buildpackage shall use that value
+as the value for DPKG_GAIN_ROOT_CMD.
+
+The variable SHOULD only be provided when there is a need for it. Notably
+when "Rules-Requires-Root" is either "no" or "binary-targets" the variable
+SHOULD NOT be defined.
+
+Common cases
+------------
+
+ * Upstream installation insists on "sudo make install"-like behaviour.
+   => Use dpkg/target-subcommand or debhelper/upstream-make-install.
+
+ * Files shipped in the package must be owned by another user than root.
+   => Not covered; use "binary-targets" for now until dpkg+debhelper
+      provides the required interface.
+
+Prototyping/preparation
+=======================
+
+dpkg side
+---------
+
+dpkg-deb --build must either default to resetting all owner/group values to
+0:0 when not run under (fake)root OR provide an interface so dh_builddeb can
+provide the owner/group value to dpkg-deb --build.
+
+dpkg-buildpackage must export DPKG_GAIN_ROOT_CMD (for starters, doing this
+unconditionally would be fine).
+
+
+debhelper side
+--------------
+
+When the field is present:
+
+ * dh_testroot will behave as usual when Rules-Requires-Root is not present
+   or set to "binary-targets".
+
+ * dh_testroot will be a no-op when Rules-Requires-Root is set to "no".
+
+ * Otherwise, dh_testroot will either verify that it is run under (fake)root
+   (as usual) OR assert that DPKG_GAIN_ROOT_CMD is defined.
+
+ * debhelper build systems will be patched to check for the
+   "debhelper/upstream-make-install" keyword and use the "Gain Root API"
+   accordingly.
+
+ * All other (src:)debhelper commands will skip their calls to chown
+   (currently they just reset them to "0:0" anyway).
+
+With the above, a default "dh $@" will no longer require (fake)root when
+built (and Rules-Requires-Root is "no").
+
+Prototyping:
+
+ * During prototyping, dh_builddeb can wrap the dpkg-deb --build call with
+   fakeroot (when not already root).

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/reproducible/dpkg.git

