mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-12-02 03:43:06 +00:00
* Added a manpage for nixos-rebuild.
svn path=/nixos/trunk/; revision=18855
This commit is contained in:
Eelco Dolstra
parent
ed6d8c6881
commit
e0d69c92a8
307
doc/manual/man-nixos-rebuild.xml
Normal file
307
doc/manual/man-nixos-rebuild.xml
Normal file
@ -0,0 +1,307 @@
|
||||
<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>
|
||||
</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>
|
||||
|
||||
</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>
|
||||
@ -24,5 +24,6 @@
|
||||
</info>
|
||||
|
||||
<xi:include href="man-configuration.xml" />
|
||||
<xi:include href="man-nixos-rebuild.xml" />
|
||||
|
||||
</reference>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user