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>