pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 version="5.0"
4 xml:id="sec-changing-config">
5
6<title>Changing the Configuration</title>
7
8<para>The file <filename>/etc/nixos/configuration.nix</filename>
9contains the current configuration of your machine. Whenever you’ve
10<link linkend="ch-configuration">changed something</link> in that file, you should do
11
12<screen>
13# nixos-rebuild switch</screen>
14
15to build the new configuration, make it the default configuration for
16booting, and try to realise the configuration in the running system
17(e.g., by restarting system services).</para>
18
19<warning><para>These commands must be executed as root, so you should
20either run them from a root shell or by prefixing them with
21<literal>sudo -i</literal>.</para></warning>
22
23<para>You can also do
24
25<screen>
26# nixos-rebuild test</screen>
27
28to build the configuration and switch the running system to it, but
29without making it the boot default. So if (say) the configuration
30locks up your machine, you can just reboot to get back to a working
31configuration.</para>
32
33<para>There is also
34
35<screen>
36# nixos-rebuild boot</screen>
37
38to build the configuration and make it the boot default, but not
39switch to it now (so it will only take effect after the next
40reboot).</para>
41
42<para>You can make your configuration show up in a different submenu
43of the GRUB 2 boot screen by giving it a different <emphasis>profile
44name</emphasis>, e.g.
45
46<screen>
47# nixos-rebuild switch -p test </screen>
48
49which causes the new configuration (and previous ones created using
50<literal>-p test</literal>) to show up in the GRUB submenu “NixOS -
51Profile 'test'”. This can be useful to separate test configurations
52from “stable” configurations.</para>
53
54<para>Finally, you can do
55
56<screen>
57$ nixos-rebuild build</screen>
58
59to build the configuration but nothing more. This is useful to see
60whether everything compiles cleanly.</para>
61
62<para>If you have a machine that supports hardware virtualisation, you
63can also test the new configuration in a sandbox by building and
64running a QEMU <emphasis>virtual machine</emphasis> that contains the
65desired configuration. Just do
66
67<screen>
68$ nixos-rebuild build-vm
69$ ./result/bin/run-*-vm
70</screen>
71
72The VM does not have any data from your host system, so your existing
73user accounts and home directories will not be available. You can
74forward ports on the host to the guest. For instance, the following
75will forward host port 2222 to guest port 22 (SSH):
76
77<screen>
78$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm
79</screen>
80
81allowing you to log in via SSH (assuming you have set the appropriate
82passwords or SSH authorized keys):
83
84<screen>
85$ ssh -p 2222 localhost
86</screen>
87
88</para>
89
90</chapter>