mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-27 16:11:58 +00:00
0eaf29433e
Spaces inside <refname> cause stray double underscore in generated manual pages. Fixes #70468
576 lines
17 KiB
XML
576 lines
17 KiB
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>
|
||
</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>
|