Revert "nixos/doc: re-format"

This reverts commit ea6e8775bd. The new
format is not an improvement.
This commit is contained in:
Eelco Dolstra
2019-09-19 19:17:30 +02:00
parent db3d31b903
commit b0ccd6dd16
124 changed files with 5709 additions and 1940 deletions
@@ -4,20 +4,28 @@
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 youve <link linkend="ch-configuration">changed something</link> in that file, you should do
The file <filename>/etc/nixos/configuration.nix</filename> contains the
current configuration of your machine. Whenever youve
<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).
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).
<warning>
<para>
This command doesn't start/stop <link linkend="opt-systemd.user.services">user services</link> automatically. <command>nixos-rebuild</command> only runs a <literal>daemon-reload</literal> for each user with running user services.
This command doesn't start/stop <link linkend="opt-systemd.user.services">user
services</link> automatically. <command>nixos-rebuild</command> only runs a
<literal>daemon-reload</literal> for each user with running user services.
</para>
</warning>
</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>.
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>
@@ -25,44 +33,63 @@
<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.
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).
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.
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.
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.
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
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:
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):
<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):
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>