diff options
Diffstat (limited to 'nixos/doc/manual/installation/changing-config.xml')
-rw-r--r-- | nixos/doc/manual/installation/changing-config.xml | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml new file mode 100644 index 000000000000..aa31742434e4 --- /dev/null +++ b/nixos/doc/manual/installation/changing-config.xml @@ -0,0 +1,90 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + version="5.0" + xml:id="sec-changing-config"> + +<title>Changing the Configuration</title> + +<para>The file <filename>/etc/nixos/configuration.nix</filename> +contains the current configuration of your machine. Whenever you’ve +changed something to that file, you should do + +<screen> +$ nixos-rebuild switch</screen> + +to build the new configuration, make it the default configuration for +booting, and try to realise the configuration in the running system +(e.g., by restarting system services).</para> + +<warning><para>These commands must be executed as root, so you should +either run them from a root shell or by prefixing them with +<literal>sudo -i</literal>.</para></warning> + +<para>You can also do + +<screen> +$ nixos-rebuild test</screen> + +to build the configuration and switch the running system to it, but +without making it the boot default. So if (say) the configuration +locks up your machine, you can just reboot to get back to a working +configuration.</para> + +<para>There is also + +<screen> +$ nixos-rebuild boot</screen> + +to build the configuration and make it the boot default, but not +switch to it now (so it will only take effect after the next +reboot).</para> + +<para>You can make your configuration show up in a different submenu +of the GRUB 2 boot screen by giving it a different <emphasis>profile +name</emphasis>, e.g. + +<screen> +$ nixos-rebuild switch -p test </screen> + +which causes the new configuration (and previous ones created using +<literal>-p test</literal>) to show up in the GRUB submenu “NixOS - +Profile 'test'”. This can be useful to separate test configurations +from “stable” configurations.</para> + +<para>Finally, you can do + +<screen> +$ nixos-rebuild build</screen> + +to build the configuration but nothing more. This is useful to see +whether everything compiles cleanly.</para> + +<para>If you have a machine that supports hardware virtualisation, you +can also test the new configuration in a sandbox by building and +running a QEMU <emphasis>virtual machine</emphasis> that contains the +desired configuration. Just do + +<screen> +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm +</screen> + +The VM does not have any data from your host system, so your existing +user accounts and home directories will not be available. You can +forward ports on the host to the guest. For instance, the following +will forward host port 2222 to guest port 22 (SSH): + +<screen> +$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm +</screen> + +allowing you to log in via SSH (assuming you have set the appropriate +passwords or SSH authorized keys): + +<screen> +$ ssh -p 2222 localhost +</screen> + +</para> + +</chapter> |