pyrox.dev
1<refentry xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude">
4
5<refmeta>
6 <refentrytitle><command>nixos-rebuild</command></refentrytitle>
7 <manvolnum>8</manvolnum>
8 <refmiscinfo class="source">NixOS</refmiscinfo>
9 <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
10</refmeta>
11
12<refnamediv>
13 <refname><command>nixos-rebuild</command></refname>
14 <refpurpose>reconfigure a NixOS machine</refpurpose>
15</refnamediv>
16
17<refsynopsisdiv>
18 <cmdsynopsis>
19 <command>nixos-rebuild</command>
20 <group choice='req'>
21 <arg choice='plain'><option>switch</option></arg>
22 <arg choice='plain'><option>boot</option></arg>
23 <arg choice='plain'><option>test</option></arg>
24 <arg choice='plain'><option>build</option></arg>
25 <arg choice='plain'><option>dry-build</option></arg>
26 <arg choice='plain'><option>dry-activate</option></arg>
27 <arg choice='plain'><option>build-vm</option></arg>
28 <arg choice='plain'><option>build-vm-with-bootloader</option></arg>
29 </group>
30 <sbr />
31 <arg><option>--upgrade</option></arg>
32 <arg><option>--install-grub</option></arg>
33 <arg><option>--no-build-nix</option></arg>
34 <arg><option>--fast</option></arg>
35 <arg><option>--rollback</option></arg>
36 <sbr />
37 <arg>
38 <group choice='req'>
39 <arg choice='plain'><option>--profile-name</option></arg>
40 <arg choice='plain'><option>-p</option></arg>
41 </group>
42 <replaceable>name</replaceable>
43 </arg>
44 <sbr />
45 <arg><option>--show-trace</option></arg>
46 </cmdsynopsis>
47</refsynopsisdiv>
48
49
50<refsection><title>Description</title>
51
52<para>This command updates the system so that it corresponds to the
53configuration specified in
54<filename>/etc/nixos/configuration.nix</filename>. Thus, every time
55you modify <filename>/etc/nixos/configuration.nix</filename> or any
56NixOS module, you must run <command>nixos-rebuild</command> to make
57the changes take effect. It builds the new system in
58<filename>/nix/store</filename>, runs its activation script, and stop
59and (re)starts any system services if needed.</para>
60
61<para>This command has one required argument, which specifies the
62desired operation. It must be one of the following:
63
64<variablelist>
65
66 <varlistentry>
67 <term><option>switch</option></term>
68 <listitem>
69 <para>Build and activate the new configuration, and make it the
70 boot default. That is, the configuration is added to the GRUB
71 boot menu as the default meny entry, so that subsequent reboots
72 will boot the system into the new configuration. Previous
73 configurations activated with <command>nixos-rebuild
74 switch</command> or <command>nixos-rebuild boot</command> remain
75 available in the GRUB menu.</para>
76 </listitem>
77 </varlistentry>
78
79 <varlistentry>
80 <term><option>boot</option></term>
81 <listitem>
82 <para>Build the new configuration and make it the boot default
83 (as with <command>nixos-rebuild switch</command>), but do not
84 activate it. That is, the system continues to run the previous
85 configuration until the next reboot.</para>
86 </listitem>
87 </varlistentry>
88
89 <varlistentry>
90 <term><option>test</option></term>
91 <listitem>
92 <para>Build and activate the new configuration, but do not add
93 it to the GRUB boot menu. Thus, if you reboot the system (or if
94 it crashes), you will automatically revert to the default
95 configuration (i.e. the configuration resulting from the last
96 call to <command>nixos-rebuild switch</command> or
97 <command>nixos-rebuild boot</command>).</para>
98 </listitem>
99 </varlistentry>
100
101 <varlistentry>
102 <term><option>build</option></term>
103 <listitem>
104 <para>Build the new configuration, but neither activate it nor
105 add it to the GRUB boot menu. It leaves a symlink named
106 <filename>result</filename> in the current directory, which
107 points to the output of the top-level “system” derivation. This
108 is essentially the same as doing
109<screen>
110$ nix-build /path/to/nixpkgs/nixos -A system
111</screen>
112 Note that you do not need to be <literal>root</literal> to run
113 <command>nixos-rebuild build</command>.</para>
114 </listitem>
115 </varlistentry>
116
117 <varlistentry>
118 <term><option>dry-build</option></term>
119 <listitem>
120 <para>Show what store paths would be built or downloaded by any
121 of the operations above, but otherwise do nothing.</para>
122 </listitem>
123 </varlistentry>
124
125 <varlistentry>
126 <term><option>dry-activate</option></term>
127 <listitem>
128 <para>Build the new configuration, but instead of activating it,
129 show what changes would be performed by the activation (i.e. by
130 <command>nixos-rebuild test</command>). For
131 instance, this command will print which systemd units would be
132 restarted. The list of changes is not guaranteed to be
133 complete.</para>
134 </listitem>
135 </varlistentry>
136
137 <varlistentry>
138 <term><option>build-vm</option></term>
139 <listitem>
140 <para>Build a script that starts a NixOS virtual machine with
141 the desired configuration. It leaves a symlink
142 <filename>result</filename> in the current directory that points
143 (under
144 <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
145 at the script that starts the VM. Thus, to test a NixOS
146 configuration in a virtual machine, you should do the following:
147<screen>
148$ nixos-rebuild build-vm
149$ ./result/bin/run-*-vm
150</screen></para>
151
152 <para>The VM is implemented using the <literal>qemu</literal>
153 package. For best performance, you should load the
154 <literal>kvm-intel</literal> or <literal>kvm-amd</literal>
155 kernel modules to get hardware virtualisation.</para>
156
157 <para>The VM mounts the Nix store of the host through the 9P
158 file system. The host Nix store is read-only, so Nix commands
159 that modify the Nix store will not work in the VM. This
160 includes commands such as <command>nixos-rebuild</command>; to
161 change the VM’s configuration, you must halt the VM and re-run
162 the commands above.
163 </para>
164
165 <para>The VM has its own <literal>ext3</literal> root file
166 system, which is automatically created when the VM is first
167 started, and is persistent across reboots of the VM. It is
168 stored in
169 <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
170 <!-- The entire file system hierarchy of the host is available in
171 the VM under <filename>/hostfs</filename>.--></para>
172 </listitem>
173 </varlistentry>
174
175 <varlistentry>
176 <term><option>build-vm-with-bootloader</option></term>
177 <listitem>
178 <para>Like <option>build-vm</option>, but boots using the
179 regular boot loader of your configuration (e.g., GRUB 1 or 2),
180 rather than booting directly into the kernel and initial ramdisk
181 of the system. This allows you to test whether the boot loader
182 works correctly. However, it does not guarantee that your NixOS
183 configuration will boot successfully on the host hardware (i.e.,
184 after running <command>nixos-rebuild switch</command>), because
185 the hardware and boot loader configuration in the VM are
186 different. The boot loader is installed on an automatically
187 generated virtual disk containing a <filename>/boot</filename>
188 partition, which is mounted read-only in the VM.</para>
189 </listitem>
190 </varlistentry>
191
192</variablelist>
193
194</para>
195
196
197</refsection>
198
199
200<refsection><title>Options</title>
201
202<para>This command accepts the following options:</para>
203
204<variablelist>
205
206 <varlistentry>
207 <term><option>--upgrade</option></term>
208 <listitem>
209 <para>Fetch the latest version of NixOS from the NixOS
210 channel.</para>
211 </listitem>
212 </varlistentry>
213
214 <varlistentry>
215 <term><option>--install-grub</option></term>
216 <listitem>
217 <para>Causes the GRUB boot loader to be (re)installed on the
218 device specified by the
219 <varname>boot.loader.grub.device</varname> configuration
220 option.</para>
221 </listitem>
222 </varlistentry>
223
224 <varlistentry>
225 <term><option>--no-build-nix</option></term>
226 <listitem>
227 <para>Normally, <command>nixos-rebuild</command> first builds
228 the <varname>nixUnstable</varname> attribute in Nixpkgs, and
229 uses the resulting instance of the Nix package manager to build
230 the new system configuration. This is necessary if the NixOS
231 modules use features not provided by the currently installed
232 version of Nix. This option disables building a new Nix.</para>
233 </listitem>
234 </varlistentry>
235
236 <varlistentry>
237 <term><option>--fast</option></term>
238 <listitem>
239 <para>Equivalent to <option>--no-build-nix</option>
240 <option>--show-trace</option>. This option is useful if you
241 call <command>nixos-rebuild</command> frequently (e.g. if you’re
242 hacking on a NixOS module).</para>
243 </listitem>
244 </varlistentry>
245
246 <varlistentry>
247 <term><option>--rollback</option></term>
248 <listitem>
249 <para>Instead of building a new configuration as specified by
250 <filename>/etc/nixos/configuration.nix</filename>, roll back to
251 the previous configuration. (The previous configuration is
252 defined as the one before the “current” generation of the
253 Nix profile <filename>/nix/var/nix/profiles/system</filename>.)</para>
254 </listitem>
255 </varlistentry>
256
257 <varlistentry>
258 <term><option>--profile-name</option></term>
259 <term><option>-p</option></term>
260 <listitem>
261 <para>Instead of using the Nix profile
262 <filename>/nix/var/nix/profiles/system</filename> to keep track
263 of the current and previous system configurations, use
264 <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
265 When you use GRUB 2, for every system profile created with this
266 flag, NixOS will create a submenu named “NixOS - Profile
267 '<replaceable>name</replaceable>'” in GRUB’s boot menu,
268 containing the current and previous configurations of this
269 profile.</para>
270
271 <para>For instance, if you want to test a configuration file
272 named <filename>test.nix</filename> without affecting the
273 default system profile, you would do:
274
275<screen>
276$ nixos-rebuild switch -p test -I nixos-config=./test.nix
277</screen>
278
279 The new configuration will appear in the GRUB 2 submenu “NixOS - Profile
280 'test'”.</para>
281 </listitem>
282 </varlistentry>
283
284</variablelist>
285
286<para>In addition, <command>nixos-rebuild</command> accepts various
287Nix-related flags, including <option>--max-jobs</option> /
288<option>-j</option>, <option>--show-trace</option>,
289<option>--keep-failed</option>, <option>--keep-going</option> and
290<option>--verbose</option> / <option>-v</option>. See
291the Nix manual for details.</para>
292
293</refsection>
294
295
296<refsection><title>Environment</title>
297
298<variablelist>
299
300 <varlistentry>
301 <term><envar>NIXOS_CONFIG</envar></term>
302 <listitem>
303 <para>Path to the main NixOS configuration module. Defaults to
304 <filename>/etc/nixos/configuration.nix</filename>.</para>
305 </listitem>
306 </varlistentry>
307
308</variablelist>
309
310</refsection>
311
312
313<refsection><title>Files</title>
314
315<variablelist>
316
317 <varlistentry>
318 <term><filename>/run/current-system</filename></term>
319 <listitem>
320 <para>A symlink to the currently active system configuration in
321 the Nix store.</para>
322 </listitem>
323 </varlistentry>
324
325 <varlistentry>
326 <term><filename>/nix/var/nix/profiles/system</filename></term>
327 <listitem>
328 <para>The Nix profile that contains the current and previous
329 system configurations. Used to generate the GRUB boot
330 menu.</para>
331 </listitem>
332 </varlistentry>
333
334</variablelist>
335
336</refsection>
337
338
339<refsection><title>Bugs</title>
340
341<para>This command should be renamed to something more
342descriptive.</para>
343
344</refsection>
345
346
347
348</refentry>