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