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