nixos/doc/manual/man-nixos-enter.xml

   1 <refentry xmlns="http://docbook.org/ns/docbook"
   2           xmlns:xlink="http://www.w3.org/1999/xlink"
   3           xmlns:xi="http://www.w3.org/2001/XInclude">
   4  <refmeta>
   5   <refentrytitle><command>nixos-enter</command>
   6   </refentrytitle><manvolnum>8</manvolnum>
   7   <refmiscinfo class="source">NixOS</refmiscinfo>
   8 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
   9  </refmeta>
  10  <refnamediv>
  11   <refname><command>nixos-enter</command></refname>
  12   <refpurpose>run a command in a NixOS chroot environment</refpurpose>
  13  </refnamediv>
  14  <refsynopsisdiv>
  15   <cmdsynopsis>
  16    <command>nixos-enter</command>
  17    <arg>
  18     <arg choice='plain'>
  19      <option>--root</option>
  20     </arg>
  21      <replaceable>root</replaceable>
  22    </arg>
  23
  24    <arg>
  25     <arg choice='plain'>
  26      <option>--system</option>
  27     </arg>
  28      <replaceable>system</replaceable>
  29    </arg>
  30
  31    <arg>
  32     <arg choice='plain'>
  33      <option>-c</option>
  34     </arg>
  35      <replaceable>shell-command</replaceable>
  36    </arg>
  37
  38    <arg>
  39     <arg choice='plain'>
  40      <option>--silent</option>
  41     </arg>
  42    </arg>
  43
  44    <arg>
  45     <arg choice='plain'>
  46      <option>--help</option>
  47     </arg>
  48    </arg>
  49
  50    <arg>
  51     <arg choice='plain'>
  52      <option>--</option>
  53     </arg>
  54      <replaceable>arguments</replaceable>
  55    </arg>
  56   </cmdsynopsis>
  57  </refsynopsisdiv>
  58  <refsection>
  59   <title>Description</title>
  60   <para>
  61    This command runs a command in a NixOS chroot environment, that is, in a
  62    filesystem hierarchy previously prepared using
  63    <command>nixos-install</command>.
  64   </para>
  65  </refsection>
  66  <refsection>
  67   <title>Options</title>
  68   <para>
  69    This command accepts the following options:
  70   </para>
  71   <variablelist>
  72    <varlistentry>
  73     <term>
  74      <option>--root</option>
  75     </term>
  76     <listitem>
  77      <para>
  78       The path to the NixOS system you want to enter. It defaults to
  79       <filename>/mnt</filename>.
  80      </para>
  81     </listitem>
  82    </varlistentry>
  83    <varlistentry>
  84     <term>
  85      <option>--system</option>
  86     </term>
  87     <listitem>
  88      <para>
  89       The NixOS system configuration to use. It defaults to
  90       <filename>/nix/var/nix/profiles/system</filename>. You can enter a
  91       previous NixOS configuration by specifying a path such as
  92       <filename>/nix/var/nix/profiles/system-106-link</filename>.
  93      </para>
  94     </listitem>
  95    </varlistentry>
  96    <varlistentry>
  97     <term>
  98      <option>--command</option>
  99     </term>
 100     <term>
 101      <option>-c</option>
 102     </term>
 103     <listitem>
 104      <para>
 105       The bash command to execute.
 106      </para>
 107     </listitem>
 108    </varlistentry>
 109    <varlistentry>
 110     <term>
 111      <option>--silent</option>
 112     </term>
 113     <listitem>
 114      <para>
 115        Suppresses all output from the activation script of the target system.
 116      </para>
 117     </listitem>
 118    </varlistentry>
 119    <varlistentry>
 120     <term>
 121      <option>--</option>
 122     </term>
 123     <listitem>
 124      <para>
 125       Interpret the remaining arguments as the program name and arguments to be
 126       invoked. The program is not executed in a shell.
 127      </para>
 128     </listitem>
 129    </varlistentry>
 130   </variablelist>
 131  </refsection>
 132  <refsection>
 133   <title>Examples</title>
 134   <para>
 135    Start an interactive shell in the NixOS installation in
 136    <filename>/mnt</filename>:
 137   </para>
 138 <screen>
 139 <prompt># </prompt>nixos-enter --root /mnt
 140 </screen>
 141   <para>
 142    Run a shell command:
 143   </para>
 144 <screen>
 145 <prompt># </prompt>nixos-enter -c 'ls -l /; cat /proc/mounts'
 146 </screen>
 147   <para>
 148    Run a non-shell command:
 149   </para>
 150 <screen>
 151 # nixos-enter -- cat /proc/mounts
 152 </screen>
 153  </refsection>
 154 </refentry>