From 60cb23001a1e8e4102ce905810c5641a7eb3a237 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Mon, 5 Feb 2018 19:41:54 +0100
Subject: Add a "nixos-enter" command

This factors out the functionality in nixos-install for running a
command inside a NixOS installation (nixos-install --chroot).
---
 nixos/doc/manual/man-nixos-enter.xml | 119 +++++++++++++++++++++++++++++++++++
 nixos/doc/manual/man-pages.xml       |   3 +-
 2 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100644 nixos/doc/manual/man-nixos-enter.xml

(limited to 'nixos/doc/manual')

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>
diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml
index e945e0e6263..80a8458fbfe 100644
--- a/nixos/doc/manual/man-pages.xml
+++ b/nixos/doc/manual/man-pages.xml
@@ -15,7 +15,7 @@
     </author>
 
     <copyright>
-      <year>2007-2015</year>
+      <year>2007-2018</year>
       <holder>Eelco Dolstra</holder>
     </copyright>
 
@@ -25,6 +25,7 @@
   <xi:include href="man-nixos-build-vms.xml" />
   <xi:include href="man-nixos-generate-config.xml" />
   <xi:include href="man-nixos-install.xml" />
+  <xi:include href="man-nixos-enter.xml" />
   <xi:include href="man-nixos-option.xml" />
   <xi:include href="man-nixos-rebuild.xml" />
   <xi:include href="man-nixos-version.xml" />
-- 
cgit 1.4.1