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