Add a "nixos-enter" command

This factors out the functionality in nixos-install for running a
command inside a NixOS installation (nixos-install --chroot).

1 files changed, 119 insertions, 0 deletions

diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml
new file mode 100644
index 00000000000..a2fbe07961d
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-enter.xml
@@ -0,0 +1,119 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+<refmeta>
+  <refentrytitle><command>nixos-enter</command></refentrytitle>
+  <manvolnum>8</manvolnum>
+  <refmiscinfo class="source">NixOS</refmiscinfo>
+  <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
+</refmeta>
+
+<refnamediv>
+  <refname><command>nixos-enter</command></refname>
+  <refpurpose>run a command in a NixOS chroot environment</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nixos-enter</command>
+    <arg>
+      <arg choice='plain'><option>--root</option></arg>
+      <replaceable>root</replaceable>
+    </arg>
+    <arg>
+      <arg choice='plain'><option>--system</option></arg>
+      <replaceable>system</replaceable>
+    </arg>
+    <arg>
+      <arg choice='plain'><option>-c</option></arg>
+      <replaceable>shell-command</replaceable>
+    </arg>
+    <arg>
+      <arg choice='plain'><option>--help</option></arg>
+    </arg>
+    <arg>
+      <arg choice='plain'><option>--</option></arg>
+      <replaceable>arguments</replaceable>
+    </arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>This command runs a command in a NixOS chroot environment, that
+is, in a filesystem hierarchy previously prepared using
+<command>nixos-install</command>.</para>
+
+</refsection>
+
+<refsection><title>Options</title>
+
+<para>This command accepts the following options:</para>
+
+<variablelist>
+
+  <varlistentry>
+    <term><option>--root</option></term>
+    <listitem>
+      <para>The path to the NixOS system you want to enter. It defaults to <filename>/mnt</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--system</option></term>
+    <listitem>
+      <para>The NixOS system configuration to use. It defaults to
+      <filename>/nix/var/nix/profiles/system</filename>. You can enter
+      a previous NixOS configuration by specifying a path such as
+      <filename>/nix/var/nix/profiles/system-106-link</filename>.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--command</option></term>
+    <term><option>-c</option></term>
+    <listitem>
+      <para>The bash command to execute.</para>
+    </listitem>
+  </varlistentry>
+
+  <varlistentry>
+    <term><option>--</option></term>
+
+    <listitem><para>Interpret the remaining arguments as the program
+    name and arguments to be invoked. The program is not executed in a
+    shell.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>Start an interactive shell in the NixOS installation in
+<filename>/mnt</filename>:</para>
+
+<screen>
+# nixos-enter /mnt
+</screen>
+
+<para>Run a shell command:</para>
+
+<screen>
+# nixos-enter -c 'ls -l /; cat /proc/mounts'
+</screen>
+
+<para>Run a non-shell command:</para>
+
+<screen>
+# nixos-enter -- cat /proc/mounts
+</screen>
+
+</refsection>
+
+</refentry>