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