diff options
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.xml | 117 |
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 = "test"; +</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="hostfwd=tcp::2222-:22" ./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> |