pyrox.dev
1.Dd January 1, 1980
2.Dt nixos-rebuild 8
3.Os
4.Sh NAME
5.Nm nixos-rebuild
6.Nd reconfigure a NixOS machine
7.
8.
9.
10.Sh SYNOPSIS
11.Nm
12.Bro
13.Cm switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader
14.Brc
15.br
16.Op Fl -upgrade | -upgrade-all
17.Op Fl -install-bootloader
18.Op Fl -no-build-nix
19.Op Fl -fast
20.Op Fl -rollback
21.Op Fl -builders Ar builder-spec
22.br
23.Op Fl -flake Ar flake-uri
24.Op Fl -no-flake
25.Op Fl -override-input Ar input-name flake-uri
26.br
27.Op Fl -profile-name | p Ar name
28.Op Fl -specialisation | c Ar name
29.br
30.Op Fl -build-host Va host
31.Op Fl -target-host Va host
32.Op Fl -use-remote-sudo
33.br
34.Op Fl -show-trace
35.Op Fl I Va NIX_PATH
36.Op Fl -verbose | v
37.Op Fl -impure
38.Op Fl -max-jobs | j Va number
39.Op Fl -keep-failed | K
40.Op Fl -keep-going | k
41.
42.
43.
44.Sh DESCRIPTION
45This command updates the system so that it corresponds to the
46configuration specified in
47.Pa /etc/nixos/configuration.nix
48or
49.Pa /etc/nixos/flake.nix Ns
50\&. Thus, every time you modify the configuration or any other NixOS module, you
51must run
52.Nm
53to make the changes take effect. It builds the new system in
54.Pa /nix/store Ns
55, runs its activation script, and stop and (re)starts any system services if
56needed. Please note that user services need to be started manually as they
57aren't detected by the activation script at the moment.
58.
59.Pp
60This command has one required argument, which specifies the desired
61operation. It must be one of the following:
62.Bl -tag -width indent
63.It Cm switch
64Build and activate the new configuration, and make it the boot default. That
65is, the configuration is added to the GRUB boot menu as the default
66menu entry, so that subsequent reboots will boot the system into the new
67configuration. Previous configurations activated with
68.Ic nixos-rebuild switch
69or
70.Ic nixos-rebuild boot
71remain available in the GRUB menu.
72.Pp
73Note that if you are using specializations, running just
74.Ic nixos-rebuild switch
75will switch you back to the unspecialized, base system \(em in that case, you
76might want to use this instead:
77.Bd -literal -offset indent
78$ nixos-rebuild switch --specialisation your-specialisation-name
79.Ed
80.Pp
81This command will build all specialisations and make them bootable just
82like regular
83.Ic nixos-rebuild switch
84does \(em the only thing different is that it will switch to given
85specialisation instead of the base system; it can be also used to switch from
86the base system into a specialised one, or to switch between specialisations.
87.
88.It Cm boot
89Build the new configuration and make it the boot default (as with
90.Ic nixos-rebuild switch Ns
91), but do not activate it. That is, the system continues to run the previous
92configuration until the next reboot.
93.
94.It Cm test
95Build and activate the new configuration, but do not add it to the GRUB
96boot menu. Thus, if you reboot the system (or if it crashes), you will
97automatically revert to the default configuration (i.e. the
98configuration resulting from the last call to
99.Ic nixos-rebuild switch
100or
101.Ic nixos-rebuild boot Ns
102).
103.Pp
104Note that if you are using specialisations, running just
105.Ic nixos-rebuild test
106will activate the unspecialised, base system \(em in that case, you might want
107to use this instead:
108.Bd -literal -offset indent
109$ nixos-rebuild test --specialisation your-specialisation-name
110.Ed
111.Pp
112This command can be also used to switch from the base system into a
113specialised one, or to switch between specialisations.
114.
115.It Cm build
116Build the new configuration, but neither activate it nor add it to the
117GRUB boot menu. It leaves a symlink named
118.Pa result
119in the current directory, which points to the output of the top-level
120.Dq system
121derivation. This is essentially the same as doing
122.Bd -literal -offset indent
123$ nix-build /path/to/nixpkgs/nixos -A system
124.Ed
125.Pp
126Note that you do not need to be root to run
127.Ic nixos-rebuild build Ns
128\&.
129.
130.It Cm dry-build
131Show what store paths would be built or downloaded by any of the
132operations above, but otherwise do nothing.
133.
134.It Cm dry-activate
135Build the new configuration, but instead of activating it, show what
136changes would be performed by the activation (i.e. by
137.Ic nixos-rebuild test Ns
138). For instance, this command will print which systemd units would be restarted.
139The list of changes is not guaranteed to be complete.
140.
141.It Cm edit
142Opens
143.Pa configuration.nix
144in the default editor.
145.
146.It Cm build-vm
147Build a script that starts a NixOS virtual machine with the desired
148configuration. It leaves a symlink
149.Pa result
150in the current directory that points (under
151.Ql result/bin/run\- Ns Va hostname Ns \-vm Ns
152)
153at the script that starts the VM. Thus, to test a NixOS configuration in
154a virtual machine, you should do the following:
155.Bd -literal -offset indent
156$ nixos-rebuild build-vm
157$ ./result/bin/run-*-vm
158.Ed
159.Pp
160The VM is implemented using the
161.Ql qemu
162package. For best performance, you should load the
163.Ql kvm-intel
164or
165.Ql kvm-amd
166kernel modules to get hardware virtualisation.
167.Pp
168The VM mounts the Nix store of the host through the 9P file system. The
169host Nix store is read-only, so Nix commands that modify the Nix store
170will not work in the VM. This includes commands such as
171.Nm Ns
172; to change the VM’s configuration, you must halt the VM and re-run the commands
173above.
174.Pp
175The VM has its own ext3 root file system, which is automatically created when
176the VM is first started, and is persistent across reboots of the VM. It is
177stored in
178.Ql ./ Ns Va hostname Ns .qcow2 Ns
179\&.
180.\" The entire file system hierarchy of the host is available in
181.\" the VM under
182.\" .Pa /hostfs Ns
183.\" .
184.
185.It Cm build-vm-with-bootloader
186Like
187.Cm build-vm Ns
188, but boots using the regular boot loader of your configuration (e.g. GRUB 1 or
1892), rather than booting directly into the kernel and initial ramdisk of the
190system. This allows you to test whether the boot loader works correctly. \
191However, it does not guarantee that your NixOS configuration will boot
192successfully on the host hardware (i.e., after running
193.Ic nixos-rebuild switch Ns
194), because the hardware and boot loader configuration in the VM are different.
195The boot loader is installed on an automatically generated virtual disk
196containing a
197.Pa /boot
198partition.
199.El
200.
201.
202.
203.Sh OPTIONS
204.Bl -tag -width indent
205.It Fl -upgrade , -upgrade-all
206Update the root user's channel named
207.Ql nixos
208before rebuilding the system.
209.Pp
210In addition to the
211.Ql nixos
212channel, the root user's channels which have a file named
213.Ql .update-on-nixos-rebuild
214in their base directory will also be updated.
215.Pp
216Passing
217.Fl -upgrade-all
218updates all of the root user's channels.
219.
220.It Fl -install-bootloader
221Causes the boot loader to be (re)installed on the device specified by the
222relevant configuration options.
223.
224.It Fl -no-build-nix
225Normally,
226.Nm
227first builds the
228.Ql nixUnstable
229attribute in Nixpkgs, and uses the resulting instance of the Nix package manager
230to build the new system configuration. This is necessary if the NixOS modules
231use features not provided by the currently installed version of Nix. This option
232disables building a new Nix.
233.
234.It Fl -fast
235Equivalent to
236.Fl -no-build-nix Ns
237\&. This option is useful if you call
238.Nm
239frequently (e.g. if you’re hacking on a NixOS module).
240.
241.It Fl -rollback
242Instead of building a new configuration as specified by
243.Pa /etc/nixos/configuration.nix Ns
244, roll back to the previous configuration. (The previous configuration is
245defined as the one before the “current” generation of the Nix profile
246.Pa /nix/var/nix/profiles/system Ns
247\&.)
248.
249.It Fl -builders Ar builder-spec
250Allow ad-hoc remote builders for building the new system. This requires
251the user executing
252.Nm
253(usually root) to be configured as a trusted user in the Nix daemon. This can be
254achieved by using the
255.Va nix.settings.trusted-users
256NixOS option. Examples values for that option are described in the
257.Dq Remote builds
258chapter in the Nix manual, (i.e.
259.Ql --builders \(dqssh://bigbrother x86_64-linux\(dq Ns
260). By specifying an empty string existing builders specified in
261.Pa /etc/nix/machines
262can be ignored:
263.Ql --builders \(dq\(dq
264for example when they are not reachable due to network connectivity.
265.
266.It Fl -profile-name Ar name , Fl p Ar name
267Instead of using the Nix profile
268.Pa /nix/var/nix/profiles/system
269to keep track of the current and previous system configurations, use
270.Pa /nix/var/nix/profiles/system-profiles/ Ns Va name Ns
271\&. When you use GRUB 2, for every system profile created with this flag, NixOS
272will create a submenu named
273.Dq NixOS - Profile Va name
274in GRUB’s boot menu, containing the current and previous configurations of this profile.
275.Pp
276For instance, if you want to test a configuration file named
277.Pa test.nix
278without affecting the default system profile, you would do:
279.Bd -literal -offset indent
280$ nixos-rebuild switch -p test -I nixos-config=./test.nix
281.Ed
282.Pp
283The new configuration will appear in the GRUB 2 submenu
284.Dq NixOS - Profile 'test' Ns
285\&.
286.
287.It Fl -specialisation Ar name , Fl c Ar name
288Activates given specialisation; when not specified, switching and testing
289will activate the base, unspecialised system.
290.
291.It Fl -build-host Ar host
292Instead of building the new configuration locally, use the specified host
293to perform the build. The host needs to be accessible with
294.Ic ssh Ns ,
295and must be able to perform Nix builds. If the option
296.Fl -target-host
297is not set, the build will be copied back to the local machine when done.
298.Pp
299Note that, if
300.Fl -no-build-nix
301is not specified, Nix will be built both locally and remotely. This is because
302the configuration will always be evaluated locally even though the building
303might be performed remotely.
304.Pp
305You can include a remote user name in the host name
306.Ns ( Va user@host Ns
307). You can also set ssh options by defining the
308.Ev NIX_SSHOPTS
309environment variable.
310.
311.It Fl -target-host Ar host
312Specifies the NixOS target host. By setting this to something other than an
313empty string, the system activation will happen on the remote host instead of
314the local machine. The remote host needs to be accessible over
315.Ic ssh Ns ,
316and for the commands
317.Cm switch Ns
318,
319.Cm boot
320and
321.Cm test
322you need root access.
323.Pp
324If
325.Fl -build-host
326is not explicitly specified or empty, building will take place locally.
327.Pp
328You can include a remote user name in the host name
329.Ns ( Va user@host Ns
330). You can also set ssh options by defining the
331.Ev NIX_SSHOPTS
332environment variable.
333.Pp
334Note that
335.Nm
336honors the
337.Va nixpkgs.crossSystem
338setting of the given configuration but disregards the true architecture of the
339target host. Hence the
340.Va nixpkgs.crossSystem
341setting has to match the target platform or else activation will fail.
342.
343.It Fl -use-substitutes
344When set, nixos-rebuild will add
345.Fl -use-substitutes
346to each invocation of nix-copy-closure. This will only affect the behavior of
347nixos-rebuild if
348.Fl -target-host
349or
350.Fl -build-host
351is also set. This is useful when the target-host connection to cache.nixos.org
352is faster than the connection between hosts.
353.
354.It Fl -use-remote-sudo
355When set, nixos-rebuild prefixes remote commands that run on the
356.Fl -build-host
357and
358.Fl -target-host
359systems with
360.Ic sudo Ns
361\&. Setting this option allows deploying as a non-root user.
362.
363.It Fl -flake Va flake-uri Ns Op Va #name
364Build the NixOS system from the specified flake. It defaults to the directory
365containing the target of the symlink
366.Pa /etc/nixos/flake.nix Ns
367, if it exists. The flake must contain an output named
368.Ql nixosConfigurations. Ns Va name Ns
369\&. If
370.Va name
371is omitted, it default to the current host name.
372.
373.It Fl -no-flake
374Do not imply
375.Fl -flake
376if
377.Pa /etc/nixos/flake.nix
378exists. With this option, it is possible to build non-flake NixOS configurations
379even if the current NixOS systems uses flakes.
380.El
381.Pp
382In addition,
383.Nm
384accepts various Nix-related flags, including
385.Fl -max-jobs Ns ,
386.Fl j Ns ,
387.Fl I Ns ,
388.Fl -show-trace Ns ,
389.Fl -keep-failed Ns ,
390.Fl -keep-going Ns ,
391.Fl -impure Ns ,
392.Fl -verbose Ns , and
393.Fl v Ns
394\&. See the Nix manual for details.
395.
396.
397.
398.Sh ENVIRONMENT
399.Bl -tag -width indent
400.It Ev NIXOS_CONFIG
401Path to the main NixOS configuration module. Defaults to
402.Pa /etc/nixos/configuration.nix Ns
403\&.
404.
405.It Ev NIX_PATH
406A colon-separated list of directories used to look up Nix expressions enclosed
407in angle brackets (e.g. <nixpkgs>). Example:
408.Bd -literal -offset indent
409nixpkgs=./my-nixpkgs
410.Ed
411.
412.It Ev NIX_SSHOPTS
413Additional options to be passed to
414.Ic ssh
415on the command line.
416.El
417.
418.
419.
420.Sh FILES
421.Bl -tag -width indent
422.It Pa /etc/nixos/flake.nix
423If this file exists, then
424.Nm
425will use it as if the
426.Fl -flake
427option was given. This file may be a symlink to a
428.Pa flake.nix
429in an actual flake; thus
430.Pa /etc/nixos
431need not be a flake.
432.
433.It Pa /run/current-system
434A symlink to the currently active system configuration in the Nix store.
435.
436.It Pa /nix/var/nix/profiles/system
437The Nix profile that contains the current and previous system
438configurations. Used to generate the GRUB boot menu.
439.El
440.
441.
442.
443.Sh BUGS
444This command should be renamed to something more descriptive.
445.
446.
447.
448.Sh AUTHORS
449.An -nosplit
450.An Eelco Dolstra
451and
452.An the Nixpkgs/NixOS contributors