On Wed, 08 Nov 2017 18:20:59 -0700 Sean Whitton <spwhit...@spwhitton.name> wrote: > Hello Ian, > > On Wed, Nov 08 2017, Ian Jackson wrote: > > > Sean Whitton writes ("Bug#880920: Document Rules-Requires-Root > >field"): > >> I wonder if we should just make Policy the new home of the spec that > >> Niels and Guillem have already written? > > > > I certainly would rather not block incorporation of this new spec into > > Debian's official document set, on the task of reformatting it into > > docbook. > > > > So yes it should probably go into the policy package (since there is > > no better home for it). > > Given that we are now rST I think we should not just dump the spec into > the policy package, but hold out on a patch to the manual itself, since > writing such a thing is not very hard at all. > > -- > Sean Whitton
Hi, Here is an initial draft for how I think it could look. Review welcome. Thanks, ~Niels
>From 337d56b25eadd4dd0d80f30019e9b837dbf01210 Mon Sep 17 00:00:00 2001 From: Niels Thykier <ni...@thykier.net> Date: Fri, 29 Dec 2017 11:28:08 +0000 Subject: [PATCH] Initial draft for Rules-Requires-Root Signed-off-by: Niels Thykier <ni...@thykier.net> --- policy/ch-controlfields.rst | 90 +++++++++++++++++++++++++++++++++++++++++++++ policy/ch-source.rst | 46 ++++++++++++++++++++++- 2 files changed, 135 insertions(+), 1 deletion(-) diff --git a/policy/ch-controlfields.rst b/policy/ch-controlfields.rst index 0771346..5310813 100644 --- a/policy/ch-controlfields.rst +++ b/policy/ch-controlfields.rst @@ -129,6 +129,8 @@ package) are: - :ref:`Testsuite <s-f-Testsuite>` +- :ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>` + The fields in the binary package paragraphs are: - :ref:`Package <s-f-Package>` (mandatory) @@ -1020,6 +1022,94 @@ This field is automatically added to Debian source control files field may also be used in source package control files (``debian/control``) if needed in other situations. +.. _s-f-Rules-Requires-Root: + +``Rules-Requires-Root`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Simple field that defines if the source package requires access to +root (or fakeroot) during selected targets in the :ref:`Main building +script: debian/rules <s-debianrules>`. + +The field can consist of exactly one of either of the following: + + - ``no``: Declares that neither root nor fakeroot is required. + Package builders (e.g. dpkg-buildpackage) may choose to invoke any + target in ``debian/rules`` with an unprivileged user. + + - ``binary-targets`` (default): Declares that the package will need + the root (or fakeroot) when either of the ``binary``, + ``binary-arch`` or ``binary-indep`` targets are called. This is + how every tool behaved before this field was defined. + + - A space separated list of keywords described below. These must + always contain a forward slash, which sets them apart from the + other values. When this list is provided, the builder must provide + a `gain root command` (as defined in :ref:`debian/rules - Gain root + api for Rules-Requires-Root <s-debianrules-gainrootapi>`) *or* + pretend that the value was set to ``binary-targets`` and both + parties must degrade accordingly (see below). + +Please note that any tool (partiularly older versions of them) may be +unaware of this field and behave like the field was set to +``binary-targets``. The package build must gracefully cope with this +and produce the same semantical result regardless. The value of this +field must not degrade if a builder tool invokes the package build + +This field intentionally does not enable a package to request a true +root over fakeroot. + +**Definition of the keywords**: + +The keywords have the format ``<namespace>/<case>``, where: + + * ``<namespace>`` must consist entirely of printable ASCII characters + except for any whitespace and the forward slash (``/``). It must + consist of at least 2 characters. + + * ``/`` (between ``<namespace>`` and ``<case>``) is a single ASCII + forward slash. + + * ``<case>`` must consist entirely of printable ASCII characters + except for any whitespace. It must consist of at least 2 + characters. + +These keywords define where the package build script (or the tools +called from it) will need access to root or fakeroot. If ``debian/rules`` +directly needs to invoke a tool as root or under fakeroot, then it must +use the keyword ``dpkg/target-subcommand``. + +Furthermore, each tool or package may claim its own namespace named +after it and create keywords based on that namespace. The tool may +use the `gain root command` to perform a given action as root or under +fakeroot if (but only if) a package lists of said keyword in the +``Rules-Requires-Root`` field. + +All tools must ignore keywords with namespaces they do not know or +own. A tool may choose warn or abort with an error if it finds +unknown keywords in namespaces it provides or owns (but it is not +required to this for all keywords in the namespace). + + +**Provided keywords**: + +The following incomplete list of keywords are defined: + + * ``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. + +The policy is not intended to contain a complete list of these +keywords. Please consult the documentation of the tool or package in +question for which keywords it defines and when they are needed. + .. _s5.7: User-defined fields diff --git a/policy/ch-source.rst b/policy/ch-source.rst index 37c4442..d5816c1 100644 --- a/policy/ch-source.rst +++ b/policy/ch-source.rst @@ -346,7 +346,9 @@ The targets are as follows: architecture-dependent or not), it must still exist and must always succeed. - The ``binary`` targets must be invoked as root. [#]_ + The ``binary`` targets may be invoked as root depending on the + value of the :ref:`Rules-Requires-Root <s-f-Rules-Requires-Root>` + field. [#]_ ``clean`` (required) This must undo any effects that the ``build`` and ``binary`` targets may have had, except that it should leave alone any output files @@ -536,6 +538,48 @@ order to make it work for your package. # Code to run the package test suite. endif + +.. _s-debianrules-gainrootapi: + +``debian/rules`` - Gain root api for ``Rules-Requires-Root`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Depending on the value of the :ref:`Rules-Requires-Root +<s-f-Rules-Requires-Root>` field, the package builder +(e.g. dpkg-buildpackage) may run the ``debian/rules`` target as an +unprivileged user and provide a `gain root command`. + +The `gain root command` is passed to the build script via the +``DPKG_GAIN_ROOT_CMD`` environment variable. It is space separated +list with the first word being the command (which should available be +in PATH) and additional words being arguments. The `gain root +command` may not be used via a shell and accordingly it must not rely +on shell features. + +The `gain root command` must not prompt or require human interaction +(as the build script itself must not require interaction). +Furthermore, it must be possible to preprend the command to an +existing command without having to alter or quote the command being +invoked. + +The following are examples of valid defitions root commands (in the sh +syntax) provided the tools are available and properly configured:: + + # Command "sudo", with arguments "-nE" and "--" + export DPKG_GAIN_ROOT_CMD='sudo -nE --' + # Command "fakeroot" with the single argument "--" + export DPKG_GAIN_ROOT_CMD='fakeroot --' + +Examples of valid use of the `gain root command`:: + + # sh-syntax (assumes set -e semantics for error handling) + $DPKG_GAIN_ROOT_CMD some-cmd --which-requires-root + + # perl + my @cmd = ('some-cmd', '--which-requires-root'); + unshift(@cmd, split(' ', $ENV{DPKG_GAIN_ROOT_CMD})) if $ENV{DPKG_GAIN_ROOT_CMD}; + system(@cmd) == or die("@cmd failed"); + .. _s-substvars: Variable substitutions: ``debian/substvars`` -- 2.15.1