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