summary refs log tree commit diff
path: root/nixos/doc/manual/man-nixos-rebuild.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/man-nixos-rebuild.xml')
-rw-r--r--nixos/doc/manual/man-nixos-rebuild.xml690
1 files changed, 690 insertions, 0 deletions
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
new file mode 100644
index 00000000000..ab2a5d83a08
--- /dev/null
+++ b/nixos/doc/manual/man-nixos-rebuild.xml
@@ -0,0 +1,690 @@
+<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>
+      <group choice='req'>
+        <arg choice='plain'>
+          <option>--upgrade</option>
+        </arg>
+        <arg choice='plain'>
+          <option>--upgrade-all</option>
+        </arg>
+      </group>
+    </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>
+    <option>--flake</option> <replaceable>flake-uri</replaceable>
+   </arg>
+
+   <arg>
+    <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</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>--build-host</option> <replaceable>host</replaceable>
+   </arg>
+
+   <arg>
+    <option>--target-host</option> <replaceable>host</replaceable>
+   </arg>
+
+   <arg>
+    <option>--use-remote-sudo</option>
+   </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>--impure</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> or
+   <filename>/etc/nixos/flake.nix</filename>. Thus, every time you
+   modify the configuration or any other 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.
+      </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>
+    <term>
+     <option>--upgrade-all</option>
+    </term>
+    <listitem>
+      <para>
+        Update the root user's channel named <literal>nixos</literal>
+        before rebuilding the system.
+      </para>
+      <para>
+        In addition to the <literal>nixos</literal> channel, the root
+        user's channels which have a file named
+        <literal>.update-on-nixos-rebuild</literal> in their base
+        directory will also be updated.
+      </para>
+      <para>
+        Passing <option>--upgrade-all</option> updates all of the root
+        user's channels.
+     </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>. 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.settings.trusted-users</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, building
+      will take place locally.
+     </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-substitutes</option>
+    </term>
+    <listitem>
+     <para>
+       When set, nixos-rebuild will add <option>--use-substitutes</option>
+       to each invocation of nix-copy-closure. This will only affect the
+       behavior of nixos-rebuild if <option>--target-host</option> or
+       <option>--build-host</option> is also set. This is useful when
+       the target-host connection to cache.nixos.org is faster than the
+       connection between hosts.
+     </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>
+
+   <varlistentry>
+    <term>
+     <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional>
+    </term>
+    <listitem>
+     <para>
+      Build the NixOS system from the specified flake. It defaults to
+      the directory containing the target of the symlink
+      <filename>/etc/nixos/flake.nix</filename>, if it exists. The
+      flake must contain an output named
+      <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If
+      <replaceable>name</replaceable> is omitted, it default to the
+      current host name.
+     </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>, <option>--impure</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>/etc/nixos/flake.nix</filename>
+    </term>
+    <listitem>
+     <para>
+      If this file exists, then <command>nixos-rebuild</command> will
+      use it as if the <option>--flake</option> option was given. This
+      file may be a symlink to a <filename>flake.nix</filename> in an
+      actual flake; thus <filename>/etc/nixos</filename> need not be a
+      flake.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <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>