1 files changed, 90 insertions, 0 deletions
diff --git a/nixpkgs/nixos/doc/manual/installation/changing-config.xml b/nixpkgs/nixos/doc/manual/installation/changing-config.xml
new file mode 100644
index 000000000000..b77d71389a9d
--- /dev/null
+++ b/nixpkgs/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
+  <link linkend="ch-configuration">changed something</link> in that file, you
+  should do
+<screen>
+<prompt># </prompt>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>
+<prompt># </prompt>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>
+<prompt># </prompt>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>
+<prompt># </prompt>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>
+<prompt>$ </prompt>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>
+<prompt>$ </prompt>nixos-rebuild build-vm
+<prompt>$ </prompt>./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 unless you have set
+  <literal>mutableUsers = false</literal>. Another way is to temporarily add
+  the following to your configuration:
+<screen>
+<link linkend="opt-users.users._name__.initialHashedPassword">users.users.your-user.initialHashedPassword</link> = "test";
+</screen>
+  <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you have
+  started the virtual machine at least once without the right users, otherwise
+  the changes will not get picked up. 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>
+<prompt>$ </prompt>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>
+<prompt>$ </prompt>ssh -p 2222 localhost
+</screen>
+ </para>
+</chapter>