rename chroot to sandbox (fixes #656, close #682)

- rename options but leav old names as lower-priority aliases,
  also "-dirs" -> "-paths" to get closer to the meaning
- update docs to reflect the new names (old aliases are not documented),
  including a new file with release notes
- tests need an update after corresponding changes to nixpkgs
- __noChroot is left as it is (after discussion on the PR)
This commit is contained in:
Vladimír Čunát 2015-09-29 18:21:10 +02:00
parent aaf8a1c16b
commit b39622a487
4 changed files with 62 additions and 29 deletions

View file

@ -224,16 +224,16 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
</varlistentry> </varlistentry>
<varlistentry><term><literal>build-use-chroot</literal></term> <varlistentry><term><literal>build-use-sandbox</literal></term>
<listitem><para>If set to <literal>true</literal>, builds will be <listitem><para>If set to <literal>true</literal>, builds will be
performed in a <emphasis>chroot environment</emphasis>, i.e., performed in a <emphasis>sandboxed environment</emphasis>, i.e.,
theyre isolated from the normal file system hierarchy and will theyre isolated from the normal file system hierarchy and will
only see their dependencies in the Nix store, the temporary build only see their dependencies in the Nix store, the temporary build
directory, private versions of <filename>/proc</filename>, directory, private versions of <filename>/proc</filename>,
<filename>/dev</filename>, <filename>/dev/shm</filename> and <filename>/dev</filename>, <filename>/dev/shm</filename> and
<filename>/dev/pts</filename>, and the paths configured with the <filename>/dev/pts</filename> (on Linux), and the paths configured with the
<link linkend='conf-build-chroot-dirs'><literal>build-chroot-dirs</literal> <link linkend='conf-build-sandbox-paths'><literal>build-sandbox-paths</literal>
option</link>. This is useful to prevent undeclared dependencies option</link>. This is useful to prevent undeclared dependencies
on files in directories such as <filename>/usr/bin</filename>. In on files in directories such as <filename>/usr/bin</filename>. In
addition, on Linux, builds run in private PID, mount, network, IPC addition, on Linux, builds run in private PID, mount, network, IPC
@ -241,8 +241,8 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
system (except that fixed-output derivations do not run in private system (except that fixed-output derivations do not run in private
network namespace to ensure they can access the network).</para> network namespace to ensure they can access the network).</para>
<para>Currently, chroots only work on Linux and Mac OS X. The use <para>Currently, sandboxing only work on Linux and Mac OS X. The use
of a chroot requires that Nix is run as root (so you should use of a sandbox requires that Nix is run as root (so you should use
the <link linkend='conf-build-users-group'>“build users” the <link linkend='conf-build-users-group'>“build users”
feature</link> to perform the actual builds under different users feature</link> to perform the actual builds under different users
than root).</para> than root).</para>
@ -250,7 +250,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
<para>If this option is set to <literal>relaxed</literal>, then <para>If this option is set to <literal>relaxed</literal>, then
fixed-output derivations and derivations that have the fixed-output derivations and derivations that have the
<varname>__noChroot</varname> attribute set to <varname>__noChroot</varname> attribute set to
<literal>true</literal> do not run in chroots.</para> <literal>true</literal> do not run in sandboxes.</para>
<para>The default is <literal>false</literal>.</para> <para>The default is <literal>false</literal>.</para>
@ -259,17 +259,16 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
</varlistentry> </varlistentry>
<varlistentry xml:id="conf-build-chroot-dirs"><term><literal>build-chroot-dirs</literal></term> <varlistentry xml:id="conf-build-sandbox-paths">
<term><literal>build-sandbox-paths</literal></term>
<listitem><para>A list of paths bind-mounted into Nix chroot <listitem><para>A list of paths bind-mounted into Nix sandbox
environments. Contrary to what the name suggests, the specified environments. You can use the syntax
paths do not have to be directories; you can bind-mount other
types of files as well. You can use the syntax
<literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal> <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal>
to mount a path in a different location in the chroot; for to mount a path in a different location in the sandbox; for
instance, <literal>/bin=/nix-bin</literal> will mount the path instance, <literal>/bin=/nix-bin</literal> will mount the path
<literal>/nix-bin</literal> as <literal>/bin</literal> inside the <literal>/nix-bin</literal> as <literal>/bin</literal> inside the
chroot.</para> sandbox.</para>
<para>Depending on how Nix was built, the default value for this option <para>Depending on how Nix was built, the default value for this option
may be empty or provide <filename>/bin/sh</filename> as a may be empty or provide <filename>/bin/sh</filename> as a
@ -278,10 +277,11 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
</varlistentry> </varlistentry>
<varlistentry xml:id="conf-build-extra-chroot-dirs"><term><literal>build-extra-chroot-dirs</literal></term> <varlistentry xml:id="conf-build-extra-sandbox-paths">
<term><literal>build-extra-sandbox-paths</literal></term>
<listitem><para>A list of additional paths appended to <listitem><para>A list of additional paths appended to
<option>build-chroot-dirs</option>. Useful if you want to extend <option>build-sandbox-paths</option>. Useful if you want to extend
its default value.</para></listitem> its default value.</para></listitem>
</varlistentry> </varlistentry>
@ -593,19 +593,21 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
between different versions of the same system to be hard-coded into nix. between different versions of the same system to be hard-coded into nix.
</para> </para>
<para>The hook is passed the derivation path and, if chroots are enabled, <para>The hook is passed the derivation path and, if sandboxes are enabled,
the chroot directory. It can then modify the chroot and send a series of the sandbox directory. It can then modify the sandbox and send a series of
commands to modify various settings to stdout. The currently recognized commands to modify various settings to stdout. The currently recognized
commands are:</para> commands are:</para>
<variablelist> <variablelist>
<varlistentry xml:id="extra-chroot-dirs"><term><literal>extra-chroot-dirs</literal></term> <varlistentry xml:id="extra-sandbox-paths">
<term><literal>extra-sandbox-paths</literal></term>
<listitem> <listitem>
<para>Pass a list of files and directories to be included in the <para>Pass a list of files and directories to be included in the
chroot for this build. One entry per line, terminated by an empty sandbox for this build. One entry per line, terminated by an empty
line. Entries have the same format as build-chroot-dirs.</para> line. Entries have the same format as
<literal>build-sandbox-paths</literal>.</para>
</listitem> </listitem>

View file

@ -12,6 +12,7 @@
</partintro> </partintro>
--> -->
<xi:include href="rl-1.11.xml" />
<xi:include href="rl-1.10.xml" /> <xi:include href="rl-1.10.xml" />
<xi:include href="rl-1.9.xml" /> <xi:include href="rl-1.9.xml" />
<xi:include href="rl-1.8.xml" /> <xi:include href="rl-1.8.xml" />

View file

@ -0,0 +1,23 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ssec-relnotes-1.11">
<title>Release 1.11 (TODO: date, 2015)</title>
<para>TODO: This is primarily a bug fix release. It also has a number of new
features:</para>
<itemizedlist>
<listitem>
<para>All "chroot"-containing strings got renamed to "sandbox".
In particular, some nix options got renamed, but the old names
are still accepted as lower-priority aliases.
</para>
</listitem>
</itemizedlist>
<para>This release has contributions from TODO.</para>
</section>

View file

@ -1842,12 +1842,14 @@ void DerivationGoal::startBuilder()
work properly. Purity checking for fixed-output derivations work properly. Purity checking for fixed-output derivations
is somewhat pointless anyway. */ is somewhat pointless anyway. */
{ {
string x = settings.get("build-use-chroot", string("false")); string x = settings.get("build-use-sandbox",
/* deprecated alias */
settings.get("build-use-chroot", string("false")));
if (x != "true" && x != "false" && x != "relaxed") if (x != "true" && x != "false" && x != "relaxed")
throw Error("option build-use-chroot must be set to one of true, false or relaxed"); throw Error("option build-use-sandbox must be set to one of true, false or relaxed");
if (x == "true") { if (x == "true") {
if (get(drv->env, "__noChroot") == "1") if (get(drv->env, "__noChroot") == "1")
throw Error(format("derivation %1% has __noChroot set, but that's not allowed when build-use-chroot is true") % drvPath); throw Error(format("derivation %1% has __noChroot set, but that's not allowed when build-use-sandbox is true") % drvPath);
useChroot = true; useChroot = true;
} }
else if (x == "false") else if (x == "false")
@ -1866,8 +1868,13 @@ void DerivationGoal::startBuilder()
/* Allow a user-configurable set of directories from the /* Allow a user-configurable set of directories from the
host file system. */ host file system. */
PathSet dirs = tokenizeString<StringSet>(settings.get("build-chroot-dirs", defaultChrootDirs)); PathSet dirs = tokenizeString<StringSet>(
PathSet dirs2 = tokenizeString<StringSet>(settings.get("build-extra-chroot-dirs", string(""))); settings.get("build-sandbox-paths",
/* deprecated alias with lower priority */
settings.get("build-chroot-dirs", defaultChrootDirs)));
PathSet dirs2 = tokenizeString<StringSet>(
settings.get("build-extra-chroot-dirs",
settings.get("build-extra-sandbox-paths", string(""))));
dirs.insert(dirs2.begin(), dirs2.end()); dirs.insert(dirs2.begin(), dirs2.end());
for (auto & i : dirs) { for (auto & i : dirs) {
@ -2010,7 +2017,7 @@ void DerivationGoal::startBuilder()
/* We don't really have any parent prep work to do (yet?) /* We don't really have any parent prep work to do (yet?)
All work happens in the child, instead. */ All work happens in the child, instead. */
#else #else
throw Error("chroot builds are not supported on this platform"); throw Error("sandboxing builds is not supported on this platform");
#endif #endif
} }
@ -2059,7 +2066,7 @@ void DerivationGoal::startBuilder()
auto line = std::string{lines, lastPos, nlPos}; auto line = std::string{lines, lastPos, nlPos};
lastPos = nlPos + 1; lastPos = nlPos + 1;
if (state == stBegin) { if (state == stBegin) {
if (line == "extra-chroot-dirs") { if (line == "extra-sandbox-paths" || line == "extra-chroot-dirs") {
state = stExtraChrootDirs; state = stExtraChrootDirs;
} else { } else {
throw Error(format("unknown pre-build hook command %1%") throw Error(format("unknown pre-build hook command %1%")
@ -2607,7 +2614,7 @@ void DerivationGoal::registerOutputs()
replaceValidPath(path, actualPath); replaceValidPath(path, actualPath);
else else
if (buildMode != bmCheck && rename(actualPath.c_str(), path.c_str()) == -1) if (buildMode != bmCheck && rename(actualPath.c_str(), path.c_str()) == -1)
throw SysError(format("moving build output %1% from the chroot to the Nix store") % path); throw SysError(format("moving build output %1% from the sandbox to the Nix store") % path);
} }
if (buildMode != bmCheck) actualPath = path; if (buildMode != bmCheck) actualPath = path;
} else { } else {