From b85403368f4a27416961a443bf39fd41871c55c9 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sun, 4 Jul 2021 00:09:43 +0800 Subject: [PATCH] nixos: nixos/doc/manual/installation/changing-config.xml to CommonMark --- .../installation/changing-config.chapter.xml | 117 ++++++++++++++++++ .../installation/changing-config.chapter.md | 100 +++++++++++++++ .../manual/installation/changing-config.xml | 97 --------------- .../doc/manual/installation/installation.xml | 2 +- 4 files changed, 218 insertions(+), 98 deletions(-) create mode 100644 nixos/doc/manual/from_md/installation/changing-config.chapter.xml create mode 100644 nixos/doc/manual/installation/changing-config.chapter.md delete mode 100644 nixos/doc/manual/installation/changing-config.xml 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 000000000000..c88fc6bbdafb --- /dev/null +++ b/nixos/doc/manual/from_md/installation/changing-config.chapter.xml @@ -0,0 +1,117 @@ + + Changing the Configuration + + The file /etc/nixos/configuration.nix contains + the current configuration of your machine. Whenever you’ve + changed something in that + file, you should do + + +# nixos-rebuild switch + + + 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). + + + + This command doesn't start/stop + user + services automatically. nixos-rebuild + only runs a daemon-reload for each user with + running user services. + + + + + These commands must be executed as root, so you should either run + them from a root shell or by prefixing them with + sudo -i. + + + + You can also do + + +# nixos-rebuild test + + + 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. + + + There is also + + +# nixos-rebuild boot + + + 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). + + + You can make your configuration show up in a different submenu of + the GRUB 2 boot screen by giving it a different profile + name, e.g. + + +# nixos-rebuild switch -p test + + + which causes the new configuration (and previous ones created using + -p test) to show up in the GRUB submenu + NixOS - Profile 'test'. This can be useful to + separate test configurations from stable + configurations. + + + Finally, you can do + + +$ nixos-rebuild build + + + to build the configuration but nothing more. This is useful to see + whether everything compiles cleanly. + + + 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 virtual machine that contains the + desired configuration. Just do + + +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm + + + 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 mutableUsers = false. Another + way is to temporarily add the following to your configuration: + + +users.users.your-user.initialHashedPassword = "test"; + + + Important: 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): + + +$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm + + + allowing you to log in via SSH (assuming you have set the + appropriate passwords or SSH authorized keys): + + +$ ssh -p 2222 localhost + + diff --git a/nixos/doc/manual/installation/changing-config.chapter.md b/nixos/doc/manual/installation/changing-config.chapter.md new file mode 100644 index 000000000000..4ed6859ce246 --- /dev/null +++ b/nixos/doc/manual/installation/changing-config.chapter.md @@ -0,0 +1,100 @@ +# Changing the Configuration {#sec-changing-config} + +The file `/etc/nixos/configuration.nix` contains the current +configuration of your machine. Whenever you've [changed +something](#ch-configuration) in that file, you should do + +```ShellSession +# nixos-rebuild switch +``` + +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} +This command doesn\'t start/stop [user services](options.html#opt-systemd.user.services) +automatically. `nixos-rebuild` only runs a `daemon-reload` for each user with running +user services. +::: + +::: {.warning} +These commands must be executed as root, so you should either run them +from a root shell or by prefixing them with `sudo -i`. +::: + +You can also do + +```ShellSession +# nixos-rebuild test +``` + +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. + +There is also + +```ShellSession +# nixos-rebuild boot +``` + +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). + +You can make your configuration show up in a different submenu of the +GRUB 2 boot screen by giving it a different *profile name*, e.g. + +```ShellSession +# nixos-rebuild switch -p test +``` + +which causes the new configuration (and previous ones created using +`-p test`) to show up in the GRUB submenu "NixOS - Profile \'test\'". +This can be useful to separate test configurations from "stable" +configurations. + +Finally, you can do + +```ShellSession +$ nixos-rebuild build +``` + +to build the configuration but nothing more. This is useful to see +whether everything compiles cleanly. + +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 *virtual machine* that contains the desired configuration. Just do + +```ShellSession +$ nixos-rebuild build-vm +$ ./result/bin/run-*-vm +``` + +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 `mutableUsers = false`. Another way is to temporarily add the +following to your configuration: + +```nix +users.users.your-user.initialHashedPassword = "test"; +``` + +*Important:* 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): + +```ShellSession +$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm +``` + +allowing you to log in via SSH (assuming you have set the appropriate +passwords or SSH authorized keys): + +```ShellSession +$ ssh -p 2222 localhost +``` diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml deleted file mode 100644 index 4288806d5eb2..000000000000 --- a/nixos/doc/manual/installation/changing-config.xml +++ /dev/null @@ -1,97 +0,0 @@ - - Changing the Configuration - - The file /etc/nixos/configuration.nix contains the - current configuration of your machine. Whenever you’ve - changed something in that file, you - should do - -# nixos-rebuild switch - - 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). - - - This command doesn't start/stop user - services automatically. nixos-rebuild only runs a - daemon-reload for each user with running user services. - - - - - - These commands must be executed as root, so you should either run them from - a root shell or by prefixing them with sudo -i. - - - - You can also do - -# nixos-rebuild test - - 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. - - - There is also - -# nixos-rebuild boot - - 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). - - - You can make your configuration show up in a different submenu of the GRUB 2 - boot screen by giving it a different profile name, e.g. - -# nixos-rebuild switch -p test - - which causes the new configuration (and previous ones created using - -p test) to show up in the GRUB submenu “NixOS - Profile - 'test'”. This can be useful to separate test configurations from - “stable” configurations. - - - Finally, you can do - -$ nixos-rebuild build - - to build the configuration but nothing more. This is useful to see whether - everything compiles cleanly. - - - 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 - virtual machine that contains the desired configuration. - Just do - -$ nixos-rebuild build-vm -$ ./result/bin/run-*-vm - - 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 - mutableUsers = false. Another way is to temporarily add - the following to your configuration: - -users.users.your-user.initialHashedPassword = "test"; - - Important: 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): - -$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm - - allowing you to log in via SSH (assuming you have set the appropriate - passwords or SSH authorized keys): - -$ ssh -p 2222 localhost - - - diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index 98dbc6d74fdc..65564e8b1e30 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -12,6 +12,6 @@ - +