nixpkgs/doc/manual/man-nixos-rebuild.xml

<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-rebuild</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-rebuild</command></refname>
  <refpurpose>reconfigure a NixOS machine</refpurpose>
</refnamediv>

<refsynopsisdiv>
  <cmdsynopsis>
    <command>nixos-rebuild</command>
    <group choice='req'>
      <arg choice='plain'><option>switch</option></arg>
      <arg choice='plain'><option>boot</option></arg>
      <arg choice='plain'><option>test</option></arg>
      <arg choice='plain'><option>build</option></arg>
      <arg choice='plain'><option>dry-run</option></arg>
      <arg choice='plain'><option>build-vm</option></arg>
      <arg choice='plain'><option>build-vm-with-bootloader</option></arg>
      <arg choice='plain'><option>pull</option></arg>
    </group>
    <sbr />
    <arg><option>--install-grub</option></arg>
    <arg><option>--no-pull</option></arg>
    <arg><option>--no-build-nix</option></arg>
    <arg><option>--fast</option></arg>
    <arg><option>--rollback</option></arg>
    <sbr />
    <arg><option>--show-trace</option></arg>
  </cmdsynopsis>
</refsynopsisdiv>


<refsection><title>Description</title>

<para>This command updates the system so that it corresponds to the
configuration specified in
<filename>/etc/nixos/configuration.nix</filename>.  Thus, every time
you modify <filename>/etc/nixos/configuration.nix</filename> or any
NixOS module, you must run <command>nixos-rebuild</command> to make
the changes take effect.  It builds the new system in
<filename>/nix/store</filename>, runs its activation script, and stop
and (re)starts any system services if needed.</para>

<para>This command has one required argument, which specifies the
desired operation.  It must be one of the following:

<variablelist>

  <varlistentry>
    <term><option>switch</option></term>
    <listitem>
      <para>Build and activate the new configuration, and make it the
      boot default.  That is, the configuration is added to the GRUB
      boot menu as the default meny entry, so that subsequent reboots
      will boot the system into the new configuration.  Previous
      configurations activated with <command>nixos-rebuild
      switch</command> or <command>nixos-rebuild boot</command> remain
      available in the GRUB menu.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>boot</option></term>
    <listitem>
      <para>Build the new configuration and make it the boot default
      (as with <command>nixos-rebuild switch</command>), but do not
      activate it.  That is, the system continues to run the previous
      configuration until the next reboot.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>test</option></term>
    <listitem>
      <para>Build and activate the new configuration, but do not add
      it to the GRUB boot menu.  Thus, if you reboot the system (or if
      it crashes), you will automatically revert to the default
      configuration (i.e. the configuration resulting from the last
      call to <command>nixos-rebuild switch</command> or
      <command>nixos-rebuild boot</command>).</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>build</option></term>
    <listitem>
      <para>Build the new configuration, but neither activate it nor
      add it to the GRUB boot menu.  It leaves a symlink named
      <filename>result</filename> in the current directory, which
      points to the output of the top-level “system” derivation.  This
      is essentially the same as doing
<screen>
$ nix-build /etc/nixos/nixos -A system
</screen>
      Note that you do not need to be <literal>root</literal> to run
      <command>nixos-rebuild build</command>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>dry-run</option></term>
    <listitem>
      <para>Simply show what store paths would be built or downloaded
      by any of the operations above.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>build-vm</option></term>
    <listitem>
      <para>Build a script that starts a NixOS virtual machine with
      the desired configuration.  It leaves a symlink
      <filename>result</filename> in the current directory that points
      (under
      <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
      at the script that starts the VM.  Thus, to test a NixOS
      configuration in a virtual machine, you should do the following:
<screen>
$ nixos-rebuild build-vm
$ ./result/bin/run-*-vm
</screen></para>

      <para>The VM is implemented using the
      <literal>qemu-kvm</literal> package.  For best performance, you
      should load the <literal>kvm-intel</literal> or
      <literal>kvm-amd</literal> kernel modules.</para>

      <para>The VM mounts the Nix store of the host through the CIFS
      filesystem.  (<literal>qemu-kvm</literal> automatically starts a
      Samba daemon for this purpose.)  The host Nix store is
      read-only, so Nix commands that modify the Nix store will not
      work in the VM.  This includes commands such as
      <command>nixos-rebuild</command>; to change the VM’s
      configuration, you must halt the VM and re-run the commands
      above.
      </para>

      <para>The VM has its own <literal>ext3</literal> root
      filesystem, which is automatically created when the VM is first
      started, and is persistent across reboots of the VM.  It is
      stored in <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
      The entire filesystem hierarchy of the host is available in the
      VM under <filename>/hostfs</filename>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>build-vm-with-bootloader</option></term>
    <listitem>
      <para>Like <option>build-vm</option>, but boots using the
      regular boot loader of your configuration (e.g., GRUB 1 or 2),
      rather than booting directly into the kernel and initial ramdisk
      of the system.  This allows you to test whether the boot loader
      works correctly.  However, it does not guarantee that your NixOS
      configuration will boot successfully on the host hardware (i.e.,
      after running <command>nixos-rebuild switch</command>), because
      the hardware and boot loader configuration in the VM are
      different.  The boot loader is installed on an automatically
      generated virtual disk containing a <filename>/boot</filename>
      partition, which is mounted read-only in the VM.</para>
    </listitem>
  </varlistentry>
  
  <varlistentry>
    <term><option>pull</option></term>
    <listitem>
      <para>This operation merely fetches the latest manifest in the
      Nixpkgs channel to speed up subsequent
      <command>nix-env</command> operations.  This is useful if you
      are not using <command>nix-channel</command> but still want to
      use pre-built binary packages.  It doesn’t reconfigure the
      system at all.</para>
    </listitem>
  </varlistentry>

</variablelist>

</para>


</refsection>


<refsection><title>Options</title>

<para>This command accepts the following options:</para>

<variablelist>

  <varlistentry>
    <term><option>--install-grub</option></term>
    <listitem>
      <para>Causes the GRUB boot loader to be (re)installed on the
      device specified by the
      <varname>boot.loader.grub.device</varname> configuration
      option.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--no-pull</option></term>
    <listitem>
      <para>Normally, <command>nixos-rebuild</command> calls
      <command>nix-pull</command> to obtain the set of available
      pre-built binaries in the Nixpkgs channel.  This option causes
      the call to <command>nix-pull</command> to be skipped.  Note
      that the result of previous invocations of
      <command>nix-pull</command> may still be available in
      <filename>/nix/var/nix/manifests</filename>, so to disable the
      use of pre-built binaries, you should clear that directory in
      addition to using <option>--no-pull</option>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--no-build-nix</option></term>
    <listitem>
      <para>Normally, <command>nixos-rebuild</command> first builds
      the <varname>nixUnstable</varname> attribute in Nixpkgs, and
      uses the resulting instance of the Nix package manager to build
      the new system configuration.  This is necessary if the NixOS
      modules use features not provided by the currently installed
      version of Nix.  This option disables building a new Nix.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--fast</option></term>
    <listitem>
      <para>Equivalent to <option>--no-pull</option>
      <option>--no-build-nix</option> <option>--show-trace</option>.
      This option is useful if you call
      <command>nixos-rebuild</command> frequently (e.g. if you’re
      hacking on a NixOS module).</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><option>--rollback</option></term>
    <listitem>
      <para>Instead of building a new configuration as specified by
      <filename>/etc/nixos/configuration.nix</filename>, roll back to
      the previous configuration.  (The previous configuration is
      defined as the one before the “current” generation of the
      profile <filename>/nix/var/nix/profiles/system</filename>.)</para>
    </listitem>
  </varlistentry>

</variablelist>

<para>In addition, <command>nixos-rebuild</command> accepts various
Nix-related flags, including <option>--max-jobs</option> /
<option>-j</option>, <option>--show-trace</option>,
<option>--keep-failed</option>, <option>--keep-going</option> and
<option>--verbose</option> / <option>-v</option>.  See
the Nix manual for details.</para>

</refsection>


<refsection><title>Environment</title>

<variablelist>

  <varlistentry>
    <term><envar>NIXOS</envar></term>
    <listitem>
      <para>Path to the NixOS source tree.  Defaults to
      <filename>/etc/nixos/nixos</filename>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><envar>NIXPKGS</envar></term>
    <listitem>
      <para>Path to the Nixpkgs source tree.  Defaults to
      <filename>/etc/nixos/nixpkgs</filename>.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><envar>NIXOS_CONFIG</envar></term>
    <listitem>
      <para>Path to the main NixOS configuration module.  Defaults to
      <filename>/etc/nixos/configuration.nix</filename>.</para>
    </listitem>
  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Files</title>

<variablelist>

  <varlistentry>
    <term><filename>/var/run/current-system</filename></term>
    <listitem>
      <para>A symlink to the currently active system configuration in
      the Nix store.</para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><filename>/nix/var/nix/profiles/system</filename></term>
    <listitem>
      <para>The Nix profile that contains the current and previous
      system configurations.  Used to generate the GRUB boot
      menu.</para>
    </listitem>
  </varlistentry>

</variablelist>

</refsection>


<refsection><title>Bugs</title>

<para>This command should be renamed to something more
descriptive.</para>

</refsection>



</refentry>