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 <refmeta>
5 <refentrytitle><command>nixos-rebuild</command>
6 </refentrytitle><manvolnum>8</manvolnum>
7 <refmiscinfo class="source">NixOS</refmiscinfo>
8<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
9 </refmeta>
10 <refnamediv>
11 <refname><command>nixos-rebuild</command>
12 </refname><refpurpose>reconfigure a NixOS machine</refpurpose>
13 </refnamediv>
14 <refsynopsisdiv>
15 <cmdsynopsis>
16 <command>nixos-rebuild</command><group choice='req'>
17 <arg choice='plain'>
18 <option>switch</option>
19 </arg>
20
21 <arg choice='plain'>
22 <option>boot</option>
23 </arg>
24
25 <arg choice='plain'>
26 <option>test</option>
27 </arg>
28
29 <arg choice='plain'>
30 <option>build</option>
31 </arg>
32
33 <arg choice='plain'>
34 <option>dry-build</option>
35 </arg>
36
37 <arg choice='plain'>
38 <option>dry-activate</option>
39 </arg>
40
41 <arg choice='plain'>
42 <option>build-vm</option>
43 </arg>
44
45 <arg choice='plain'>
46 <option>build-vm-with-bootloader</option>
47 </arg>
48 </group>
49 <sbr />
50 <arg>
51 <option>--upgrade</option>
52 </arg>
53
54 <arg>
55 <option>--install-bootloader</option>
56 </arg>
57
58 <arg>
59 <option>--no-build-nix</option>
60 </arg>
61
62 <arg>
63 <option>--fast</option>
64 </arg>
65
66 <arg>
67 <option>--rollback</option>
68 </arg>
69 <sbr />
70 <arg>
71 <group choice='req'>
72 <arg choice='plain'>
73 <option>--profile-name</option>
74 </arg>
75
76 <arg choice='plain'>
77 <option>-p</option>
78 </arg>
79 </group> <replaceable>name</replaceable>
80 </arg>
81 <sbr />
82 <arg>
83 <option>--show-trace</option>
84 </arg>
85 </cmdsynopsis>
86 </refsynopsisdiv>
87 <refsection>
88 <title>Description</title>
89 <para>
90 This command updates the system so that it corresponds to the configuration
91 specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every
92 time you modify <filename>/etc/nixos/configuration.nix</filename> or any
93 NixOS module, you must run <command>nixos-rebuild</command> to make the
94 changes take effect. It builds the new system in
95 <filename>/nix/store</filename>, runs its activation script, and stop and
96 (re)starts any system services if needed.
97 </para>
98 <para>
99 This command has one required argument, which specifies the desired
100 operation. It must be one of the following:
101 <variablelist>
102 <varlistentry>
103 <term>
104 <option>switch</option>
105 </term>
106 <listitem>
107 <para>
108 Build and activate the new configuration, and make it the boot default.
109 That is, the configuration is added to the GRUB boot menu as the default
110 menu entry, so that subsequent reboots will boot the system into the new
111 configuration. Previous configurations activated with
112 <command>nixos-rebuild switch</command> or <command>nixos-rebuild
113 boot</command> remain available in the GRUB menu.
114 </para>
115 </listitem>
116 </varlistentry>
117 <varlistentry>
118 <term>
119 <option>boot</option>
120 </term>
121 <listitem>
122 <para>
123 Build the new configuration and make it the boot default (as with
124 <command>nixos-rebuild switch</command>), but do not activate it. That
125 is, the system continues to run the previous configuration until the
126 next reboot.
127 </para>
128 </listitem>
129 </varlistentry>
130 <varlistentry>
131 <term>
132 <option>test</option>
133 </term>
134 <listitem>
135 <para>
136 Build and activate the new configuration, but do not add it to the GRUB
137 boot menu. Thus, if you reboot the system (or if it crashes), you will
138 automatically revert to the default configuration (i.e. the
139 configuration resulting from the last call to <command>nixos-rebuild
140 switch</command> or <command>nixos-rebuild boot</command>).
141 </para>
142 </listitem>
143 </varlistentry>
144 <varlistentry>
145 <term>
146 <option>build</option>
147 </term>
148 <listitem>
149 <para>
150 Build the new configuration, but neither activate it nor add it to the
151 GRUB boot menu. It leaves a symlink named <filename>result</filename> in
152 the current directory, which points to the output of the top-level
153 “system” derivation. This is essentially the same as doing
154<screen>
155$ nix-build /path/to/nixpkgs/nixos -A system
156</screen>
157 Note that you do not need to be <literal>root</literal> to run
158 <command>nixos-rebuild build</command>.
159 </para>
160 </listitem>
161 </varlistentry>
162 <varlistentry>
163 <term>
164 <option>dry-build</option>
165 </term>
166 <listitem>
167 <para>
168 Show what store paths would be built or downloaded by any of the
169 operations above, but otherwise do nothing.
170 </para>
171 </listitem>
172 </varlistentry>
173 <varlistentry>
174 <term>
175 <option>dry-activate</option>
176 </term>
177 <listitem>
178 <para>
179 Build the new configuration, but instead of activating it, show what
180 changes would be performed by the activation (i.e. by
181 <command>nixos-rebuild test</command>). For instance, this command will
182 print which systemd units would be restarted. The list of changes is not
183 guaranteed to be complete.
184 </para>
185 </listitem>
186 </varlistentry>
187 <varlistentry>
188 <term>
189 <option>build-vm</option>
190 </term>
191 <listitem>
192 <para>
193 Build a script that starts a NixOS virtual machine with the desired
194 configuration. It leaves a symlink <filename>result</filename> in the
195 current directory that points (under
196 <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
197 at the script that starts the VM. Thus, to test a NixOS configuration in
198 a virtual machine, you should do the following:
199<screen>
200$ nixos-rebuild build-vm
201$ ./result/bin/run-*-vm
202</screen>
203 </para>
204 <para>
205 The VM is implemented using the <literal>qemu</literal> package. For
206 best performance, you should load the <literal>kvm-intel</literal> or
207 <literal>kvm-amd</literal> kernel modules to get hardware
208 virtualisation.
209 </para>
210 <para>
211 The VM mounts the Nix store of the host through the 9P file system. The
212 host Nix store is read-only, so Nix commands that modify the Nix store
213 will not work in the VM. This includes commands such as
214 <command>nixos-rebuild</command>; to change the VM’s configuration,
215 you must halt the VM and re-run the commands above.
216 </para>
217 <para>
218 The VM has its own <literal>ext3</literal> root file system, which is
219 automatically created when the VM is first started, and is persistent
220 across reboots of the VM. It is stored in
221 <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
222<!-- The entire file system hierarchy of the host is available in
223 the VM under <filename>/hostfs</filename>.-->
224 </para>
225 </listitem>
226 </varlistentry>
227 <varlistentry>
228 <term>
229 <option>build-vm-with-bootloader</option>
230 </term>
231 <listitem>
232 <para>
233 Like <option>build-vm</option>, but boots using the regular boot loader
234 of your configuration (e.g., GRUB 1 or 2), rather than booting directly
235 into the kernel and initial ramdisk of the system. This allows you to
236 test whether the boot loader works correctly. However, it does not
237 guarantee that your NixOS configuration will boot successfully on the
238 host hardware (i.e., after running <command>nixos-rebuild
239 switch</command>), because the hardware and boot loader configuration in
240 the VM are different. The boot loader is installed on an automatically
241 generated virtual disk containing a <filename>/boot</filename>
242 partition, which is mounted read-only in the VM.
243 </para>
244 </listitem>
245 </varlistentry>
246 </variablelist>
247 </para>
248 </refsection>
249 <refsection>
250 <title>Options</title>
251 <para>
252 This command accepts the following options:
253 </para>
254 <variablelist>
255 <varlistentry>
256 <term>
257 <option>--upgrade</option>
258 </term>
259 <listitem>
260 <para>
261 Fetch the latest version of NixOS from the NixOS channel.
262 </para>
263 </listitem>
264 </varlistentry>
265 <varlistentry>
266 <term>
267 <option>--install-bootloader</option>
268 </term>
269 <listitem>
270 <para>
271 Causes the boot loader to be (re)installed on the device specified by the
272 relevant configuration options.
273 </para>
274 </listitem>
275 </varlistentry>
276 <varlistentry>
277 <term>
278 <option>--no-build-nix</option>
279 </term>
280 <listitem>
281 <para>
282 Normally, <command>nixos-rebuild</command> first builds the
283 <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the
284 resulting instance of the Nix package manager to build the new system
285 configuration. This is necessary if the NixOS modules use features not
286 provided by the currently installed version of Nix. This option disables
287 building a new Nix.
288 </para>
289 </listitem>
290 </varlistentry>
291 <varlistentry>
292 <term>
293 <option>--fast</option>
294 </term>
295 <listitem>
296 <para>
297 Equivalent to <option>--no-build-nix</option>
298 <option>--show-trace</option>. This option is useful if you call
299 <command>nixos-rebuild</command> frequently (e.g. if you’re hacking on
300 a NixOS module).
301 </para>
302 </listitem>
303 </varlistentry>
304 <varlistentry>
305 <term>
306 <option>--rollback</option>
307 </term>
308 <listitem>
309 <para>
310 Instead of building a new configuration as specified by
311 <filename>/etc/nixos/configuration.nix</filename>, roll back to the
312 previous configuration. (The previous configuration is defined as the one
313 before the “current” generation of the Nix profile
314 <filename>/nix/var/nix/profiles/system</filename>.)
315 </para>
316 </listitem>
317 </varlistentry>
318 <varlistentry>
319 <term>
320 <option>--profile-name</option>
321 </term>
322 <term>
323 <option>-p</option>
324 </term>
325 <listitem>
326 <para>
327 Instead of using the Nix profile
328 <filename>/nix/var/nix/profiles/system</filename> to keep track of the
329 current and previous system configurations, use
330 <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
331 When you use GRUB 2, for every system profile created with this flag,
332 NixOS will create a submenu named “NixOS - Profile
333 '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
334 the current and previous configurations of this profile.
335 </para>
336 <para>
337 For instance, if you want to test a configuration file named
338 <filename>test.nix</filename> without affecting the default system
339 profile, you would do:
340<screen>
341$ nixos-rebuild switch -p test -I nixos-config=./test.nix
342</screen>
343 The new configuration will appear in the GRUB 2 submenu “NixOS -
344 Profile 'test'”.
345 </para>
346 </listitem>
347 </varlistentry>
348 <varlistentry>
349 <term>
350 <option>--build-host</option>
351 </term>
352 <listitem>
353 <para>
354 Instead of building the new configuration locally, use the specified host
355 to perform the build. The host needs to be accessible with ssh, and must
356 be able to perform Nix builds. If the option
357 <option>--target-host</option> is not set, the build will be copied back
358 to the local machine when done.
359 </para>
360 <para>
361 Note that, if <option>--no-build-nix</option> is not specified, Nix will
362 be built both locally and remotely. This is because the configuration
363 will always be evaluated locally even though the building might be
364 performed remotely.
365 </para>
366 <para>
367 You can include a remote user name in the host name
368 (<replaceable>user@host</replaceable>). You can also set ssh options by
369 defining the <envar>NIX_SSHOPTS</envar> environment variable.
370 </para>
371 </listitem>
372 </varlistentry>
373 <varlistentry>
374 <term>
375 <option>--target-host</option>
376 </term>
377 <listitem>
378 <para>
379 Specifies the NixOS target host. By setting this to something other than
380 <replaceable>localhost</replaceable>, the system activation will happen
381 on the remote host instead of the local machine. The remote host needs to
382 be accessible over ssh, and for the commands <option>switch</option>,
383 <option>boot</option> and <option>test</option> you need root access.
384 </para>
385 <para>
386 If <option>--build-host</option> is not explicitly specified,
387 <option>--build-host</option> will implicitly be set to the same value as
388 <option>--target-host</option>. So, if you only specify
389 <option>--target-host</option> both building and activation will take
390 place remotely (and no build artifacts will be copied to the local
391 machine).
392 </para>
393 <para>
394 You can include a remote user name in the host name
395 (<replaceable>user@host</replaceable>). You can also set ssh options by
396 defining the <envar>NIX_SSHOPTS</envar> environment variable.
397 </para>
398 </listitem>
399 </varlistentry>
400 </variablelist>
401 <para>
402 In addition, <command>nixos-rebuild</command> accepts various Nix-related
403 flags, including <option>--max-jobs</option> / <option>-j</option>,
404 <option>--show-trace</option>, <option>--keep-failed</option>,
405 <option>--keep-going</option> and <option>--verbose</option> /
406 <option>-v</option>. See the Nix manual for details.
407 </para>
408 </refsection>
409 <refsection>
410 <title>Environment</title>
411 <variablelist>
412 <varlistentry>
413 <term>
414 <envar>NIXOS_CONFIG</envar>
415 </term>
416 <listitem>
417 <para>
418 Path to the main NixOS configuration module. Defaults to
419 <filename>/etc/nixos/configuration.nix</filename>.
420 </para>
421 </listitem>
422 </varlistentry>
423 <varlistentry>
424 <term>
425 <envar>NIX_SSHOPTS</envar>
426 </term>
427 <listitem>
428 <para>
429 Additional options to be passed to <command>ssh</command> on the command
430 line.
431 </para>
432 </listitem>
433 </varlistentry>
434 </variablelist>
435 </refsection>
436 <refsection>
437 <title>Files</title>
438 <variablelist>
439 <varlistentry>
440 <term>
441 <filename>/run/current-system</filename>
442 </term>
443 <listitem>
444 <para>
445 A symlink to the currently active system configuration in the Nix store.
446 </para>
447 </listitem>
448 </varlistentry>
449 <varlistentry>
450 <term>
451 <filename>/nix/var/nix/profiles/system</filename>
452 </term>
453 <listitem>
454 <para>
455 The Nix profile that contains the current and previous system
456 configurations. Used to generate the GRUB boot menu.
457 </para>
458 </listitem>
459 </varlistentry>
460 </variablelist>
461 </refsection>
462 <refsection>
463 <title>Bugs</title>
464 <para>
465 This command should be renamed to something more descriptive.
466 </para>
467 </refsection>
468</refentry>