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