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
11 <refnamediv>
12 <refname><command>nixos-rebuild</command></refname>
13 <refpurpose>reconfigure a NixOS machine</refpurpose>
14 </refnamediv>
15
16 <refsynopsisdiv>
17 <cmdsynopsis>
18 <command>nixos-rebuild</command><group choice='req'>
19 <arg choice='plain'>
20 <option>switch</option>
21 </arg>
22
23 <arg choice='plain'>
24 <option>boot</option>
25 </arg>
26
27 <arg choice='plain'>
28 <option>test</option>
29 </arg>
30
31 <arg choice='plain'>
32 <option>build</option>
33 </arg>
34
35 <arg choice='plain'>
36 <option>dry-build</option>
37 </arg>
38
39 <arg choice='plain'>
40 <option>dry-activate</option>
41 </arg>
42
43 <arg choice='plain'>
44 <option>edit</option>
45 </arg>
46
47 <arg choice='plain'>
48 <option>build-vm</option>
49 </arg>
50
51 <arg choice='plain'>
52 <option>build-vm-with-bootloader</option>
53 </arg>
54 </group>
55 <sbr />
56
57 <arg>
58 <group choice='req'>
59 <arg choice='plain'>
60 <option>--upgrade</option>
61 </arg>
62 <arg choice='plain'>
63 <option>--upgrade-all</option>
64 </arg>
65 </group>
66 </arg>
67
68 <arg>
69 <option>--install-bootloader</option>
70 </arg>
71
72 <arg>
73 <option>--no-build-nix</option>
74 </arg>
75
76 <arg>
77 <option>--fast</option>
78 </arg>
79
80 <arg>
81 <option>--rollback</option>
82 </arg>
83
84 <arg>
85 <option>--builders</option> <replaceable>builder-spec</replaceable>
86 </arg>
87
88 <sbr/>
89
90 <arg>
91 <option>--flake</option> <replaceable>flake-uri</replaceable>
92 </arg>
93
94 <arg>
95 <option>--override-input</option> <replaceable>input-name</replaceable> <replaceable>flake-uri</replaceable>
96 </arg>
97
98 <sbr />
99
100 <arg>
101 <group choice='req'>
102 <arg choice='plain'>
103 <option>--profile-name</option>
104 </arg>
105
106 <arg choice='plain'>
107 <option>-p</option>
108 </arg>
109 </group> <replaceable>name</replaceable>
110 </arg>
111
112 <sbr />
113
114 <arg>
115 <option>--build-host</option> <replaceable>host</replaceable>
116 </arg>
117
118 <arg>
119 <option>--target-host</option> <replaceable>host</replaceable>
120 </arg>
121
122 <arg>
123 <option>--use-remote-sudo</option>
124 </arg>
125
126 <sbr />
127
128 <arg>
129 <option>--show-trace</option>
130 </arg>
131 <arg>
132 <option>-I</option>
133 <replaceable>path</replaceable>
134 </arg>
135 <arg>
136 <group choice='req'>
137 <arg choice='plain'><option>--verbose</option></arg>
138 <arg choice='plain'><option>-v</option></arg>
139 </group>
140 </arg>
141 <arg>
142 <group choice='req'>
143 <arg choice='plain'><option>--impure</option></arg>
144 </group>
145 </arg>
146 <arg>
147 <group choice='req'>
148 <arg choice='plain'><option>--max-jobs</option></arg>
149 <arg choice='plain'><option>-j</option></arg>
150 </group>
151 <replaceable>number</replaceable>
152 </arg>
153 <arg>
154 <group choice='req'>
155 <arg choice='plain'><option>--keep-failed</option></arg>
156 <arg choice='plain'><option>-K</option></arg>
157 </group>
158 </arg>
159 <arg>
160 <group choice='req'>
161 <arg choice='plain'><option>--keep-going</option></arg>
162 <arg choice='plain'><option>-k</option></arg>
163 </group>
164 </arg>
165 </cmdsynopsis>
166 </refsynopsisdiv>
167
168 <refsection>
169 <title>Description</title>
170
171 <para>
172 This command updates the system so that it corresponds to the
173 configuration specified in
174 <filename>/etc/nixos/configuration.nix</filename> or
175 <filename>/etc/nixos/flake.nix</filename>. Thus, every time you
176 modify the configuration or any other NixOS module, you must run
177 <command>nixos-rebuild</command> to make the changes take
178 effect. It builds the new system in
179 <filename>/nix/store</filename>, runs its activation script, and
180 stop and (re)starts any system services if needed. Please note that
181 user services need to be started manually as they aren't detected
182 by the activation script at the moment.
183 </para>
184
185 <para>
186 This command has one required argument, which specifies the desired
187 operation. It must be one of the following:
188
189 <variablelist>
190 <varlistentry>
191 <term>
192 <option>switch</option>
193 </term>
194 <listitem>
195 <para>
196 Build and activate the new configuration, and make it the boot default.
197 That is, the configuration is added to the GRUB boot menu as the default
198 menu entry, so that subsequent reboots will boot the system into the new
199 configuration. Previous configurations activated with
200 <command>nixos-rebuild switch</command> or <command>nixos-rebuild
201 boot</command> remain available in the GRUB menu.
202 </para>
203 </listitem>
204 </varlistentry>
205
206 <varlistentry>
207 <term>
208 <option>boot</option>
209 </term>
210 <listitem>
211 <para>
212 Build the new configuration and make it the boot default (as with
213 <command>nixos-rebuild switch</command>), but do not activate it. That
214 is, the system continues to run the previous configuration until the
215 next reboot.
216 </para>
217 </listitem>
218 </varlistentry>
219
220 <varlistentry>
221 <term>
222 <option>test</option>
223 </term>
224 <listitem>
225 <para>
226 Build and activate the new configuration, but do not add it to the GRUB
227 boot menu. Thus, if you reboot the system (or if it crashes), you will
228 automatically revert to the default configuration (i.e. the
229 configuration resulting from the last call to <command>nixos-rebuild
230 switch</command> or <command>nixos-rebuild boot</command>).
231 </para>
232 </listitem>
233 </varlistentry>
234
235 <varlistentry>
236 <term>
237 <option>build</option>
238 </term>
239 <listitem>
240 <para>
241 Build the new configuration, but neither activate it nor add it to the
242 GRUB boot menu. It leaves a symlink named <filename>result</filename> in
243 the current directory, which points to the output of the top-level
244 “system” derivation. This is essentially the same as doing
245<screen>
246<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system
247</screen>
248 Note that you do not need to be <literal>root</literal> to run
249 <command>nixos-rebuild build</command>.
250 </para>
251 </listitem>
252 </varlistentry>
253
254 <varlistentry>
255 <term>
256 <option>dry-build</option>
257 </term>
258 <listitem>
259 <para>
260 Show what store paths would be built or downloaded by any of the
261 operations above, but otherwise do nothing.
262 </para>
263 </listitem>
264 </varlistentry>
265
266 <varlistentry>
267 <term>
268 <option>dry-activate</option>
269 </term>
270 <listitem>
271 <para>
272 Build the new configuration, but instead of activating it, show what
273 changes would be performed by the activation (i.e. by
274 <command>nixos-rebuild test</command>). For instance, this command will
275 print which systemd units would be restarted. The list of changes is not
276 guaranteed to be complete.
277 </para>
278 </listitem>
279 </varlistentry>
280
281 <varlistentry>
282 <term>
283 <option>edit</option>
284 </term>
285 <listitem>
286 <para>
287 Opens <filename>configuration.nix</filename> in the default editor.
288 </para>
289 </listitem>
290 </varlistentry>
291
292 <varlistentry>
293 <term>
294 <option>build-vm</option>
295 </term>
296 <listitem>
297 <para>
298 Build a script that starts a NixOS virtual machine with the desired
299 configuration. It leaves a symlink <filename>result</filename> in the
300 current directory that points (under
301 <filename>result/bin/run-<replaceable>hostname</replaceable>-vm</filename>)
302 at the script that starts the VM. Thus, to test a NixOS configuration in
303 a virtual machine, you should do the following:
304<screen>
305<prompt>$ </prompt>nixos-rebuild build-vm
306<prompt>$ </prompt>./result/bin/run-*-vm
307</screen>
308 </para>
309
310 <para>
311 The VM is implemented using the <literal>qemu</literal> package. For
312 best performance, you should load the <literal>kvm-intel</literal> or
313 <literal>kvm-amd</literal> kernel modules to get hardware
314 virtualisation.
315 </para>
316
317 <para>
318 The VM mounts the Nix store of the host through the 9P file system. The
319 host Nix store is read-only, so Nix commands that modify the Nix store
320 will not work in the VM. This includes commands such as
321 <command>nixos-rebuild</command>; to change the VM’s configuration,
322 you must halt the VM and re-run the commands above.
323 </para>
324
325 <para>
326 The VM has its own <literal>ext3</literal> root file system, which is
327 automatically created when the VM is first started, and is persistent
328 across reboots of the VM. It is stored in
329 <literal>./<replaceable>hostname</replaceable>.qcow2</literal>.
330<!-- The entire file system hierarchy of the host is available in
331 the VM under <filename>/hostfs</filename>.-->
332 </para>
333 </listitem>
334 </varlistentry>
335
336 <varlistentry>
337 <term>
338 <option>build-vm-with-bootloader</option>
339 </term>
340 <listitem>
341 <para>
342 Like <option>build-vm</option>, but boots using the regular boot loader
343 of your configuration (e.g., GRUB 1 or 2), rather than booting directly
344 into the kernel and initial ramdisk of the system. This allows you to
345 test whether the boot loader works correctly. However, it does not
346 guarantee that your NixOS configuration will boot successfully on the
347 host hardware (i.e., after running <command>nixos-rebuild
348 switch</command>), because the hardware and boot loader configuration in
349 the VM are different. The boot loader is installed on an automatically
350 generated virtual disk containing a <filename>/boot</filename>
351 partition.
352 </para>
353 </listitem>
354 </varlistentry>
355 </variablelist>
356 </para>
357 </refsection>
358
359 <refsection>
360 <title>Options</title>
361 <para>
362 This command accepts the following options:
363 </para>
364
365 <variablelist>
366 <varlistentry>
367 <term>
368 <option>--upgrade</option>
369 </term>
370 <term>
371 <option>--upgrade-all</option>
372 </term>
373 <listitem>
374 <para>
375 Update the root user's channel named <literal>nixos</literal>
376 before rebuilding the system.
377 </para>
378 <para>
379 In addition to the <literal>nixos</literal> channel, the root
380 user's channels which have a file named
381 <literal>.update-on-nixos-rebuild</literal> in their base
382 directory will also be updated.
383 </para>
384 <para>
385 Passing <option>--upgrade-all</option> updates all of the root
386 user's channels.
387 </para>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry>
392 <term>
393 <option>--install-bootloader</option>
394 </term>
395 <listitem>
396 <para>
397 Causes the boot loader to be (re)installed on the device specified by the
398 relevant configuration options.
399 </para>
400 </listitem>
401 </varlistentry>
402
403 <varlistentry>
404 <term>
405 <option>--no-build-nix</option>
406 </term>
407 <listitem>
408 <para>
409 Normally, <command>nixos-rebuild</command> first builds the
410 <varname>nixUnstable</varname> attribute in Nixpkgs, and uses the
411 resulting instance of the Nix package manager to build the new system
412 configuration. This is necessary if the NixOS modules use features not
413 provided by the currently installed version of Nix. This option disables
414 building a new Nix.
415 </para>
416 </listitem>
417 </varlistentry>
418
419 <varlistentry>
420 <term>
421 <option>--fast</option>
422 </term>
423 <listitem>
424 <para>
425 Equivalent to <option>--no-build-nix</option>. This option is
426 useful if you call <command>nixos-rebuild</command> frequently
427 (e.g. if you’re hacking on a NixOS module).
428 </para>
429 </listitem>
430 </varlistentry>
431
432 <varlistentry>
433 <term>
434 <option>--rollback</option>
435 </term>
436 <listitem>
437 <para>
438 Instead of building a new configuration as specified by
439 <filename>/etc/nixos/configuration.nix</filename>, roll back to the
440 previous configuration. (The previous configuration is defined as the one
441 before the “current” generation of the Nix profile
442 <filename>/nix/var/nix/profiles/system</filename>.)
443 </para>
444 </listitem>
445 </varlistentry>
446
447 <varlistentry>
448 <term>
449 <option>--builders</option> <replaceable>builder-spec</replaceable>
450 </term>
451 <listitem>
452 <para>
453 Allow ad-hoc remote builders for building the new system. This requires
454 the user executing <command>nixos-rebuild</command> (usually root) to be
455 configured as a trusted user in the Nix daemon. This can be achieved by
456 using the <literal>nix.trustedUsers</literal> NixOS option. Examples
457 values for that option are described in the <literal>Remote builds
458 chapter</literal> in the Nix manual, (i.e. <command>--builders
459 "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string
460 existing builders specified in <filename>/etc/nix/machines</filename> can
461 be ignored: <command>--builders ""</command> for example when they are
462 not reachable due to network connectivity.
463 </para>
464 </listitem>
465 </varlistentry>
466
467 <varlistentry>
468 <term>
469 <option>--profile-name</option>
470 </term>
471 <term>
472 <option>-p</option>
473 </term>
474 <listitem>
475 <para>
476 Instead of using the Nix profile
477 <filename>/nix/var/nix/profiles/system</filename> to keep track of the
478 current and previous system configurations, use
479 <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
480 When you use GRUB 2, for every system profile created with this flag,
481 NixOS will create a submenu named “NixOS - Profile
482 '<replaceable>name</replaceable>'” in GRUB’s boot menu, containing
483 the current and previous configurations of this profile.
484 </para>
485 <para>
486 For instance, if you want to test a configuration file named
487 <filename>test.nix</filename> without affecting the default system
488 profile, you would do:
489<screen>
490<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix
491</screen>
492 The new configuration will appear in the GRUB 2 submenu “NixOS -
493 Profile 'test'”.
494 </para>
495 </listitem>
496 </varlistentry>
497
498 <varlistentry>
499 <term>
500 <option>--build-host</option>
501 </term>
502 <listitem>
503 <para>
504 Instead of building the new configuration locally, use the specified host
505 to perform the build. The host needs to be accessible with ssh, and must
506 be able to perform Nix builds. If the option
507 <option>--target-host</option> is not set, the build will be copied back
508 to the local machine when done.
509 </para>
510 <para>
511 Note that, if <option>--no-build-nix</option> is not specified, Nix will
512 be built both locally and remotely. This is because the configuration
513 will always be evaluated locally even though the building might be
514 performed remotely.
515 </para>
516 <para>
517 You can include a remote user name in the host name
518 (<replaceable>user@host</replaceable>). You can also set ssh options by
519 defining the <envar>NIX_SSHOPTS</envar> environment variable.
520 </para>
521 </listitem>
522 </varlistentry>
523
524 <varlistentry>
525 <term>
526 <option>--target-host</option>
527 </term>
528 <listitem>
529 <para>
530 Specifies the NixOS target host. By setting this to something other than
531 <replaceable>localhost</replaceable>, the system activation will happen
532 on the remote host instead of the local machine. The remote host needs to
533 be accessible over ssh, and for the commands <option>switch</option>,
534 <option>boot</option> and <option>test</option> you need root access.
535 </para>
536
537 <para>
538 If <option>--build-host</option> is not explicitly specified,
539 <option>--build-host</option> will implicitly be set to the same value as
540 <option>--target-host</option>. So, if you only specify
541 <option>--target-host</option> both building and activation will take
542 place remotely (and no build artifacts will be copied to the local
543 machine).
544 </para>
545
546 <para>
547 You can include a remote user name in the host name
548 (<replaceable>user@host</replaceable>). You can also set ssh options by
549 defining the <envar>NIX_SSHOPTS</envar> environment variable.
550 </para>
551 </listitem>
552 </varlistentry>
553
554 <varlistentry>
555 <term>
556 <option>--use-substitutes</option>
557 </term>
558 <listitem>
559 <para>
560 When set, nixos-rebuild will add <option>--use-substitutes</option>
561 to each invocation of nix-copy-closure. This will only affect the
562 behavior of nixos-rebuild if <option>--target-host</option> or
563 <option>--build-host</option> is also set. This is useful when
564 the target-host connection to cache.nixos.org is faster than the
565 connection between hosts.
566 </para>
567 </listitem>
568 </varlistentry>
569
570 <varlistentry>
571 <term>
572 <option>--use-remote-sudo</option>
573 </term>
574 <listitem>
575 <para>
576 When set, nixos-rebuild prefixes remote commands that run on
577 the <option>--build-host</option> and <option>--target-host</option>
578 systems with <command>sudo</command>. Setting this option allows
579 deploying as a non-root user.
580 </para>
581 </listitem>
582 </varlistentry>
583
584 <varlistentry>
585 <term>
586 <option>--flake</option> <replaceable>flake-uri</replaceable><optional>#<replaceable>name</replaceable></optional>
587 </term>
588 <listitem>
589 <para>
590 Build the NixOS system from the specified flake. It defaults to
591 the directory containing the target of the symlink
592 <filename>/etc/nixos/flake.nix</filename>, if it exists. The
593 flake must contain an output named
594 <literal>nixosConfigurations.<replaceable>name</replaceable></literal>. If
595 <replaceable>name</replaceable> is omitted, it default to the
596 current host name.
597 </para>
598 </listitem>
599 </varlistentry>
600
601 </variablelist>
602
603 <para>
604 In addition, <command>nixos-rebuild</command> accepts various Nix-related
605 flags, including <option>--max-jobs</option> / <option>-j</option>,
606 <option>--show-trace</option>, <option>--keep-failed</option>,
607 <option>--keep-going</option>, <option>--impure</option>, and <option>--verbose</option> /
608 <option>-v</option>. See the Nix manual for details.
609 </para>
610 </refsection>
611
612 <refsection>
613 <title>Environment</title>
614
615 <variablelist>
616 <varlistentry>
617 <term>
618 <envar>NIXOS_CONFIG</envar>
619 </term>
620 <listitem>
621 <para>
622 Path to the main NixOS configuration module. Defaults to
623 <filename>/etc/nixos/configuration.nix</filename>.
624 </para>
625 </listitem>
626 </varlistentry>
627
628 <varlistentry>
629 <term>
630 <envar>NIX_SSHOPTS</envar>
631 </term>
632 <listitem>
633 <para>
634 Additional options to be passed to <command>ssh</command> on the command
635 line.
636 </para>
637 </listitem>
638 </varlistentry>
639 </variablelist>
640 </refsection>
641
642 <refsection>
643 <title>Files</title>
644
645 <variablelist>
646
647 <varlistentry>
648 <term>
649 <filename>/etc/nixos/flake.nix</filename>
650 </term>
651 <listitem>
652 <para>
653 If this file exists, then <command>nixos-rebuild</command> will
654 use it as if the <option>--flake</option> option was given. This
655 file may be a symlink to a <filename>flake.nix</filename> in an
656 actual flake; thus <filename>/etc/nixos</filename> need not be a
657 flake.
658 </para>
659 </listitem>
660 </varlistentry>
661
662 <varlistentry>
663 <term>
664 <filename>/run/current-system</filename>
665 </term>
666 <listitem>
667 <para>
668 A symlink to the currently active system configuration in the Nix store.
669 </para>
670 </listitem>
671 </varlistentry>
672
673 <varlistentry>
674 <term>
675 <filename>/nix/var/nix/profiles/system</filename>
676 </term>
677 <listitem>
678 <para>
679 The Nix profile that contains the current and previous system
680 configurations. Used to generate the GRUB boot menu.
681 </para>
682 </listitem>
683 </varlistentry>
684
685 </variablelist>
686 </refsection>
687
688 <refsection>
689 <title>Bugs</title>
690 <para>
691 This command should be renamed to something more descriptive.
692 </para>
693 </refsection>
694</refentry>