path: root/nixos/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-build</option>
   </arg>

   <arg choice='plain'>
    <option>dry-activate</option>
   </arg>

   <arg choice='plain'>
    <option>edit</option>
   </arg>

   <arg choice='plain'>
    <option>build-vm</option>
   </arg>

   <arg choice='plain'>
    <option>build-vm-with-bootloader</option>
   </arg>
    </group>
   <sbr />
   <arg>
    <option>--upgrade</option>
   </arg>

   <arg>
    <option>--install-bootloader</option>
   </arg>

   <arg>
    <option>--no-build-nix</option>
   </arg>

   <arg>
    <option>--fast</option>
   </arg>

   <arg>
    <option>--rollback</option>
   </arg>

   <arg>
    <option>--builders</option> <replaceable>builder-spec</replaceable>
   </arg>

   <sbr />
   <arg>
    <group choice='req'>
    <arg choice='plain'>
     <option>--profile-name</option>
    </arg>

    <arg choice='plain'>
     <option>-p</option>
    </arg>
     </group> <replaceable>name</replaceable>
   </arg>
   <sbr />
   <arg>
    <option>--show-trace</option>
   </arg>
   <arg>
    <option>-I</option>
    <replaceable>path</replaceable>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--verbose</option></arg>
     <arg choice='plain'><option>-v</option></arg>
    </group>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--max-jobs</option></arg>
     <arg choice='plain'><option>-j</option></arg>
    </group>
    <replaceable>number</replaceable>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--keep-failed</option></arg>
     <arg choice='plain'><option>-K</option></arg>
    </group>
   </arg>
   <arg>
    <group choice='req'>
     <arg choice='plain'><option>--keep-going</option></arg>
     <arg choice='plain'><option>-k</option></arg>
    </group>
   </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. Please note that user services need
   to be started manually as they aren't detected by the activation script at the moment.
  </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
       menu 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>
<prompt>$ </prompt>nix-build /path/to/nixpkgs/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-build</option>
     </term>
     <listitem>
      <para>
       Show what store paths would be built or downloaded by any of the
       operations above, but otherwise do nothing.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <option>dry-activate</option>
     </term>
     <listitem>
      <para>
       Build the new configuration, but instead of activating it, show what
       changes would be performed by the activation (i.e. by
       <command>nixos-rebuild test</command>). For instance, this command will
       print which systemd units would be restarted. The list of changes is not
       guaranteed to be complete.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>
      <option>edit</option>
     </term>
     <listitem>
      <para>
       Opens <filename>configuration.nix</filename> in the default editor.
      </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>
<prompt>$ </prompt>nixos-rebuild build-vm
<prompt>$ </prompt>./result/bin/run-*-vm
</screen>
      </para>

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

      <para>
       The VM mounts the Nix store of the host through the 9P file system. 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 file system, 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 file system 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>
   </variablelist>
  </para>
 </refsection>

 <refsection>
  <title>Options</title>
  <para>
   This command accepts the following options:
  </para>

  <variablelist>
   <varlistentry>
    <term>
     <option>--upgrade</option>
    </term>
    <listitem>
     <para>
      Fetch the latest version of NixOS from the NixOS channel.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--install-bootloader</option>
    </term>
    <listitem>
     <para>
      Causes the boot loader to be (re)installed on the device specified by the
      relevant configuration options.
     </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-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 Nix profile
      <filename>/nix/var/nix/profiles/system</filename>.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--builders</option> <replaceable>builder-spec</replaceable>
    </term>
    <listitem>
     <para>
      Allow ad-hoc remote builders for building the new system. This requires
      the user executing <command>nixos-rebuild</command> (usually root) to be
      configured as a trusted user in the Nix daemon. This can be achieved by
      using the <literal>nix.trustedUsers</literal> NixOS option. Examples
      values for that option are described in the <literal>Remote builds
      chapter</literal> in the Nix manual, (i.e. <command>--builders
      "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
      existing builders specified in <filename>/etc/nix/machines</filename> can
      be ignored: <command>--builders ""</command> for example when they are
      not reachable due to network connectivity.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--profile-name</option>
    </term>
    <term>
     <option>-p</option>
    </term>
    <listitem>
     <para>
      Instead of using the Nix profile
      <filename>/nix/var/nix/profiles/system</filename> to keep track of the
      current and previous system configurations, use
      <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
      When you use GRUB 2, for every system profile created with this flag,
      NixOS will create a submenu named “NixOS - Profile
      '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
      the current and previous configurations of this profile.
     </para>
     <para>
      For instance, if you want to test a configuration file named
      <filename>test.nix</filename> without affecting the default system
      profile, you would do:
<screen>
<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix
</screen>
      The new configuration will appear in the GRUB 2 submenu “NixOS -
      Profile 'test'”.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--build-host</option>
    </term>
    <listitem>
     <para>
      Instead of building the new configuration locally, use the specified host
      to perform the build. The host needs to be accessible with ssh, and must
      be able to perform Nix builds. If the option
      <option>--target-host</option> is not set, the build will be copied back
      to the local machine when done.
     </para>
     <para>
      Note that, if <option>--no-build-nix</option> is not specified, Nix will
      be built both locally and remotely. This is because the configuration
      will always be evaluated locally even though the building might be
      performed remotely.
     </para>
     <para>
      You can include a remote user name in the host name
      (<replaceable>user@host</replaceable>). You can also set ssh options by
      defining the <envar>NIX_SSHOPTS</envar> environment variable.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--target-host</option>
    </term>
    <listitem>
     <para>
      Specifies the NixOS target host. By setting this to something other than
      <replaceable>localhost</replaceable>, the system activation will happen
      on the remote host instead of the local machine. The remote host needs to
      be accessible over ssh, and for the commands <option>switch</option>,
      <option>boot</option> and <option>test</option> you need root access.
     </para>

     <para>
      If <option>--build-host</option> is not explicitly specified,
      <option>--build-host</option> will implicitly be set to the same value as
      <option>--target-host</option>. So, if you only specify
      <option>--target-host</option> both building and activation will take
      place remotely (and no build artifacts will be copied to the local
      machine).
     </para>

     <para>
      You can include a remote user name in the host name
      (<replaceable>user@host</replaceable>). You can also set ssh options by
      defining the <envar>NIX_SSHOPTS</envar> environment variable.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <option>--use-remote-sudo</option>
    </term>
    <listitem>
     <para>
      When set, nixos-rebuild prefixes remote commands that run on
      the <option>--build-host</option> and <option>--target-host</option>
      systems with <command>sudo</command>. Setting this option allows
      deploying as a non-root user.
     </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_CONFIG</envar>
    </term>
    <listitem>
     <para>
      Path to the main NixOS configuration module. Defaults to
      <filename>/etc/nixos/configuration.nix</filename>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <envar>NIX_SSHOPTS</envar>
    </term>
    <listitem>
     <para>
      Additional options to be passed to <command>ssh</command> on the command
      line.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsection>

 <refsection>
  <title>Files</title>

  <variablelist>

   <varlistentry>
    <term>
     <filename>/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>