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-bootloader</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-bootloader</option></term>
216 <listitem>
217 <para>Causes the boot loader to be (re)installed on the
218 device specified by the relevant configuration options.
219 </para>
220 </listitem>
221 </varlistentry>
222
223 <varlistentry>
224 <term><option>--no-build-nix</option></term>
225 <listitem>
226 <para>Normally, <command>nixos-rebuild</command> first builds
227 the <varname>nixUnstable</varname> attribute in Nixpkgs, and
228 uses the resulting instance of the Nix package manager to build
229 the new system configuration. This is necessary if the NixOS
230 modules use features not provided by the currently installed
231 version of Nix. This option disables building a new Nix.</para>
232 </listitem>
233 </varlistentry>
234
235 <varlistentry>
236 <term><option>--fast</option></term>
237 <listitem>
238 <para>Equivalent to <option>--no-build-nix</option>
239 <option>--show-trace</option>. This option is useful if you
240 call <command>nixos-rebuild</command> frequently (e.g. if you’re
241 hacking on a NixOS module).</para>
242 </listitem>
243 </varlistentry>
244
245 <varlistentry>
246 <term><option>--rollback</option></term>
247 <listitem>
248 <para>Instead of building a new configuration as specified by
249 <filename>/etc/nixos/configuration.nix</filename>, roll back to
250 the previous configuration. (The previous configuration is
251 defined as the one before the “current” generation of the
252 Nix profile <filename>/nix/var/nix/profiles/system</filename>.)</para>
253 </listitem>
254 </varlistentry>
255
256 <varlistentry>
257 <term><option>--profile-name</option></term>
258 <term><option>-p</option></term>
259 <listitem>
260 <para>Instead of using the Nix profile
261 <filename>/nix/var/nix/profiles/system</filename> to keep track
262 of the current and previous system configurations, use
263 <filename>/nix/var/nix/profiles/system-profiles/<replaceable>name</replaceable></filename>.
264 When you use GRUB 2, for every system profile created with this
265 flag, NixOS will create a submenu named “NixOS - Profile
266 '<replaceable>name</replaceable>'” in GRUB’s boot menu,
267 containing the current and previous configurations of this
268 profile.</para>
269
270 <para>For instance, if you want to test a configuration file
271 named <filename>test.nix</filename> without affecting the
272 default system profile, you would do:
273
274<screen>
275$ nixos-rebuild switch -p test -I nixos-config=./test.nix
276</screen>
277
278 The new configuration will appear in the GRUB 2 submenu “NixOS - Profile
279 'test'”.</para>
280 </listitem>
281 </varlistentry>
282
283 <varlistentry>
284 <term><option>--build-host</option></term>
285 <listitem>
286 <para>Instead of building the new configuration locally, use the
287 specified host to perform the build. The host needs to be accessible
288 with ssh, and must be able to perform Nix builds. If the option
289 <option>--target-host</option> is not set, the build will be copied back
290 to the local machine when done.</para>
291
292 <para>Note that, if <option>--no-build-nix</option> is not specified,
293 Nix will be built both locally and remotely. This is because the
294 configuration will always be evaluated locally even though the building
295 might be performed remotely.</para>
296
297 <para>You can include a remote user name in
298 the host name (<replaceable>user@host</replaceable>). You can also set
299 ssh options by defining the <envar>NIX_SSHOPTS</envar> environment
300 variable.</para>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry>
305 <term><option>--target-host</option></term>
306 <listitem>
307 <para>Specifies the NixOS target host. By setting this to something other
308 than <replaceable>localhost</replaceable>, the system activation will
309 happen on the remote host instead of the local machine. The remote host
310 needs to be accessible over ssh, and for the commands
311 <option>switch</option>, <option>boot</option> and <option>test</option>
312 you need root access.</para>
313
314 <para>If <option>--build-host</option> is not explicitly
315 specified, <option>--build-host</option> will implicitly be set to the
316 same value as <option>--target-host</option>. So, if you only specify
317 <option>--target-host</option> both building and activation will take
318 place remotely (and no build artifacts will be copied to the local
319 machine).</para>
320
321 <para>You can include a remote user name in
322 the host name (<replaceable>user@host</replaceable>). You can also set
323 ssh options by defining the <envar>NIX_SSHOPTS</envar> environment
324 variable.</para>
325 </listitem>
326 </varlistentry>
327
328</variablelist>
329
330<para>In addition, <command>nixos-rebuild</command> accepts various
331Nix-related flags, including <option>--max-jobs</option> /
332<option>-j</option>, <option>--show-trace</option>,
333<option>--keep-failed</option>, <option>--keep-going</option> and
334<option>--verbose</option> / <option>-v</option>. See
335the Nix manual for details.</para>
336
337</refsection>
338
339
340<refsection><title>Environment</title>
341
342<variablelist>
343
344 <varlistentry>
345 <term><envar>NIXOS_CONFIG</envar></term>
346 <listitem>
347 <para>Path to the main NixOS configuration module. Defaults to
348 <filename>/etc/nixos/configuration.nix</filename>.</para>
349 </listitem>
350 </varlistentry>
351
352 <varlistentry><term><envar>NIX_SSHOPTS</envar></term>
353
354 <listitem><para>Additional options to be passed to
355 <command>ssh</command> on the command line.</para></listitem>
356
357 </varlistentry>
358
359</variablelist>
360
361</refsection>
362
363
364<refsection><title>Files</title>
365
366<variablelist>
367
368 <varlistentry>
369 <term><filename>/run/current-system</filename></term>
370 <listitem>
371 <para>A symlink to the currently active system configuration in
372 the Nix store.</para>
373 </listitem>
374 </varlistentry>
375
376 <varlistentry>
377 <term><filename>/nix/var/nix/profiles/system</filename></term>
378 <listitem>
379 <para>The Nix profile that contains the current and previous
380 system configurations. Used to generate the GRUB boot
381 menu.</para>
382 </listitem>
383 </varlistentry>
384
385</variablelist>
386
387</refsection>
388
389
390<refsection><title>Bugs</title>
391
392<para>This command should be renamed to something more
393descriptive.</para>
394
395</refsection>
396
397
398
399</refentry>