summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/installation/changing-config.chapter.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/installation/changing-config.chapter.xml')
-rw-r--r--nixos/doc/manual/from_md/installation/changing-config.chapter.xml117
1 files changed, 117 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/installation/changing-config.chapter.xml b/nixos/doc/manual/from_md/installation/changing-config.chapter.xml
new file mode 100644
index 00000000000..86f0b15b41c
--- /dev/null
+++ b/nixos/doc/manual/from_md/installation/changing-config.chapter.xml
@@ -0,0 +1,117 @@
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-changing-config">
+  <title>Changing the Configuration</title>
+  <para>
+    The file <literal>/etc/nixos/configuration.nix</literal> contains
+    the current configuration of your machine. Whenever you’ve
+    <link linkend="ch-configuration">changed something</link> in that
+    file, you should do
+  </para>
+  <programlisting>
+# nixos-rebuild switch
+</programlisting>
+  <para>
+    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>
+      This command doesn't start/stop
+      <link linkend="opt-systemd.user.services">user services</link>
+      automatically. <literal>nixos-rebuild</literal> only runs a
+      <literal>daemon-reload</literal> for each user with running user
+      services.
+    </para>
+  </warning>
+  <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
+  </para>
+  <programlisting>
+# nixos-rebuild test
+</programlisting>
+  <para>
+    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
+  </para>
+  <programlisting>
+# nixos-rebuild boot
+</programlisting>
+  <para>
+    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.
+  </para>
+  <programlisting>
+# nixos-rebuild switch -p test
+</programlisting>
+  <para>
+    which causes the new configuration (and previous ones created using
+    <literal>-p test</literal>) to show up in the GRUB submenu
+    <quote>NixOS - Profile 'test'</quote>. This can be useful to
+    separate test configurations from <quote>stable</quote>
+    configurations.
+  </para>
+  <para>
+    Finally, you can do
+  </para>
+  <programlisting>
+$ nixos-rebuild build
+</programlisting>
+  <para>
+    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
+  </para>
+  <programlisting>
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+</programlisting>
+  <para>
+    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:
+  </para>
+  <programlisting language="bash">
+users.users.your-user.initialHashedPassword = &quot;test&quot;;
+</programlisting>
+  <para>
+    <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):
+  </para>
+  <programlisting>
+$ QEMU_NET_OPTS=&quot;hostfwd=tcp::2222-:22&quot; ./result/bin/run-*-vm
+</programlisting>
+  <para>
+    allowing you to log in via SSH (assuming you have set the
+    appropriate passwords or SSH authorized keys):
+  </para>
+  <programlisting>
+$ ssh -p 2222 localhost
+</programlisting>
+</chapter>