diff options
author | Jörg Thalheim <Mic92@users.noreply.github.com> | 2021-09-07 06:29:19 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-09-07 06:29:19 +0100 |
commit | e622dd1c8422fa378b0ee242b2804afac19b61ec (patch) | |
tree | 84f3f3b434c458ffa77ebb7ca9fb09425fbf77d4 /nixos/doc | |
parent | c7d32059b126e2ba61a9d2422a0baf76fbf7101a (diff) | |
parent | a3480a0e6959f69bdbafe31c4cce2c731a929934 (diff) | |
download | nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar.gz nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar.bz2 nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar.lz nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar.xz nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.tar.zst nixpkgs-e622dd1c8422fa378b0ee242b2804afac19b61ec.zip |
Merge pull request #129154 from bobby285271/pr15
nixos/doc: convert Chapter 1, 3, 4 to CommonMark
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/from_md/installation/changing-config.chapter.xml | 117 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/installation/obtaining.chapter.xml | 48 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/installation/upgrading.chapter.xml | 152 | ||||
-rw-r--r-- | nixos/doc/manual/installation/changing-config.chapter.md | 100 | ||||
-rw-r--r-- | nixos/doc/manual/installation/changing-config.xml | 97 | ||||
-rw-r--r-- | nixos/doc/manual/installation/installation.xml | 6 | ||||
-rw-r--r-- | nixos/doc/manual/installation/obtaining.chapter.md | 26 | ||||
-rw-r--r-- | nixos/doc/manual/installation/obtaining.xml | 54 | ||||
-rw-r--r-- | nixos/doc/manual/installation/upgrading.chapter.md | 118 | ||||
-rw-r--r-- | nixos/doc/manual/installation/upgrading.xml | 139 |
10 files changed, 564 insertions, 293 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> diff --git a/nixos/doc/manual/from_md/installation/obtaining.chapter.xml b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml new file mode 100644 index 00000000000..a922feda253 --- /dev/null +++ b/nixos/doc/manual/from_md/installation/obtaining.chapter.xml @@ -0,0 +1,48 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-obtaining"> + <title>Obtaining NixOS</title> + <para> + NixOS ISO images can be downloaded from the + <link xlink:href="https://nixos.org/nixos/download.html">NixOS + download page</link>. There are a number of installation options. If + you happen to have an optical drive and a spare CD, burning the + image to CD and booting from that is probably the easiest option. + Most people will need to prepare a USB stick to boot from. + <xref linkend="sec-booting-from-usb" /> describes the preferred + method to prepare a USB stick. A number of alternative methods are + presented in the + <link xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS + Wiki</link>. + </para> + <para> + As an alternative to installing NixOS yourself, you can get a + running NixOS system through several other means: + </para> + <itemizedlist> + <listitem> + <para> + Using virtual appliances in Open Virtualization Format (OVF) + that can be imported into VirtualBox. These are available from + the + <link xlink:href="https://nixos.org/nixos/download.html">NixOS + download page</link>. + </para> + </listitem> + <listitem> + <para> + Using AMIs for Amazon’s EC2. To find one for your region and + instance type, please refer to the + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list + of most recent AMIs</link>. + </para> + </listitem> + <listitem> + <para> + Using NixOps, the NixOS-based cloud deployment tool, which + allows you to provision VirtualBox and EC2 NixOS instances from + declarative specifications. Check out the + <link xlink:href="https://nixos.org/nixops">NixOps + homepage</link> for details. + </para> + </listitem> + </itemizedlist> +</chapter> diff --git a/nixos/doc/manual/from_md/installation/upgrading.chapter.xml b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml new file mode 100644 index 00000000000..c0c5a2190fb --- /dev/null +++ b/nixos/doc/manual/from_md/installation/upgrading.chapter.xml @@ -0,0 +1,152 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-upgrading"> + <title>Upgrading NixOS</title> + <para> + The best way to keep your NixOS installation up to date is to use + one of the NixOS <emphasis>channels</emphasis>. A channel is a Nix + mechanism for distributing Nix expressions and associated binaries. + The NixOS channels are updated automatically from NixOS’s Git + repository after certain tests have passed and all packages have + been built. These channels are: + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>Stable channels</emphasis>, such as + <link xlink:href="https://nixos.org/channels/nixos-21.05"><literal>nixos-21.05</literal></link>. + These only get conservative bug fixes and package upgrades. For + instance, a channel update may cause the Linux kernel on your + system to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), + but not from 4.19.x to 4.20.x (a major change that has the + potential to break things). Stable channels are generally + maintained until the next stable branch is created. + </para> + </listitem> + <listitem> + <para> + The <emphasis>unstable channel</emphasis>, + <link xlink:href="https://nixos.org/channels/nixos-unstable"><literal>nixos-unstable</literal></link>. + This corresponds to NixOS’s main development branch, and may + thus see radical changes between channel updates. It’s not + recommended for production systems. + </para> + </listitem> + <listitem> + <para> + <emphasis>Small channels</emphasis>, such as + <link xlink:href="https://nixos.org/channels/nixos-21.05-small"><literal>nixos-21.05-small</literal></link> + or + <link xlink:href="https://nixos.org/channels/nixos-unstable-small"><literal>nixos-unstable-small</literal></link>. + These are identical to the stable and unstable channels + described above, except that they contain fewer binary packages. + This means they get updated faster than the regular channels + (for instance, when a critical security patch is committed to + NixOS’s source tree), but may require more packages to be built + from source than usual. They’re mostly intended for server + environments and as such contain few GUI applications. + </para> + </listitem> + </itemizedlist> + <para> + To see what channels are available, go to + <link xlink:href="https://nixos.org/channels">https://nixos.org/channels</link>. + (Note that the URIs of the various channels redirect to a directory + that contains the channel’s latest version and includes ISO images + and VirtualBox appliances.) Please note that during the release + process, channels that are not yet released will be present here as + well. See the Getting NixOS page + <link xlink:href="https://nixos.org/nixos/download.html">https://nixos.org/nixos/download.html</link> + to find the newest supported stable release. + </para> + <para> + When you first install NixOS, you’re automatically subscribed to the + NixOS channel that corresponds to your installation source. For + instance, if you installed from a 21.05 ISO, you will be subscribed + to the <literal>nixos-21.05</literal> channel. To see which NixOS + channel you’re subscribed to, run the following as root: + </para> + <programlisting> +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +</programlisting> + <para> + To switch to a different NixOS channel, do + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/channel-name nixos +</programlisting> + <para> + (Be sure to include the <literal>nixos</literal> parameter at the + end.) For instance, to use the NixOS 21.05 stable channel: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-21.05 nixos +</programlisting> + <para> + If you have a server, you may want to use the <quote>small</quote> + channel instead: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos +</programlisting> + <para> + And if you want to live on the bleeding edge: + </para> + <programlisting> +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos +</programlisting> + <para> + You can then upgrade NixOS to the latest version in your chosen + channel by running + </para> + <programlisting> +# nixos-rebuild switch --upgrade +</programlisting> + <para> + which is equivalent to the more verbose + <literal>nix-channel --update nixos; nixos-rebuild switch</literal>. + </para> + <note> + <para> + Channels are set per user. This means that running + <literal>nix-channel --add</literal> as a non root user (or + without sudo) will not affect configuration in + <literal>/etc/nixos/configuration.nix</literal> + </para> + </note> + <warning> + <para> + It is generally safe to switch back and forth between channels. + The only exception is that a newer NixOS may also have a newer Nix + version, which may involve an upgrade of Nix’s database schema. + This cannot be undone easily, so in that case you will not be able + to go back to your original channel. + </para> + </warning> + <section xml:id="sec-upgrading-automatic"> + <title>Automatic Upgrades</title> + <para> + You can keep a NixOS system up-to-date automatically by adding the + following to <literal>configuration.nix</literal>: + </para> + <programlisting language="bash"> +system.autoUpgrade.enable = true; +system.autoUpgrade.allowReboot = true; +</programlisting> + <para> + This enables a periodically executed systemd service named + <literal>nixos-upgrade.service</literal>. If the + <literal>allowReboot</literal> option is <literal>false</literal>, + it runs <literal>nixos-rebuild switch --upgrade</literal> to + upgrade NixOS to the latest version in the current channel. (To + see when the service runs, see + <literal>systemctl list-timers</literal>.) If + <literal>allowReboot</literal> is <literal>true</literal>, then + the system will automatically reboot if the new generation + contains a different kernel, initrd or kernel modules. You can + also specify a channel explicitly, e.g. + </para> + <programlisting language="bash"> +system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.05; +</programlisting> + </section> +</chapter> 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 00000000000..8a404f085d7 --- /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](#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 4288806d5eb..00000000000 --- a/nixos/doc/manual/installation/changing-config.xml +++ /dev/null @@ -1,97 +0,0 @@ -<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). - <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. - </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>. - </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> diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index 2901f462dee..cc18a9c6e9f 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -10,8 +10,8 @@ first-time use. </para> </partintro> - <xi:include href="obtaining.xml" /> + <xi:include href="../from_md/installation/obtaining.chapter.xml" /> <xi:include href="installing.xml" /> - <xi:include href="changing-config.xml" /> - <xi:include href="upgrading.xml" /> + <xi:include href="../from_md/installation/changing-config.chapter.xml" /> + <xi:include href="../from_md/installation/upgrading.chapter.xml" /> </part> diff --git a/nixos/doc/manual/installation/obtaining.chapter.md b/nixos/doc/manual/installation/obtaining.chapter.md new file mode 100644 index 00000000000..832ec6146a9 --- /dev/null +++ b/nixos/doc/manual/installation/obtaining.chapter.md @@ -0,0 +1,26 @@ +# Obtaining NixOS {#sec-obtaining} + +NixOS ISO images can be downloaded from the [NixOS download +page](https://nixos.org/nixos/download.html). There are a number of +installation options. If you happen to have an optical drive and a spare +CD, burning the image to CD and booting from that is probably the +easiest option. Most people will need to prepare a USB stick to boot +from. [](#sec-booting-from-usb) describes the preferred method to +prepare a USB stick. A number of alternative methods are presented in +the [NixOS Wiki](https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media). + +As an alternative to installing NixOS yourself, you can get a running +NixOS system through several other means: + +- Using virtual appliances in Open Virtualization Format (OVF) that + can be imported into VirtualBox. These are available from the [NixOS + download page](https://nixos.org/nixos/download.html). + +- Using AMIs for Amazon's EC2. To find one for your region and + instance type, please refer to the [list of most recent + AMIs](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix). + +- Using NixOps, the NixOS-based cloud deployment tool, which allows + you to provision VirtualBox and EC2 NixOS instances from declarative + specifications. Check out the [NixOps + homepage](https://nixos.org/nixops) for details. diff --git a/nixos/doc/manual/installation/obtaining.xml b/nixos/doc/manual/installation/obtaining.xml deleted file mode 100644 index 3b8671782de..00000000000 --- a/nixos/doc/manual/installation/obtaining.xml +++ /dev/null @@ -1,54 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-obtaining"> - <title>Obtaining NixOS</title> - <para> - NixOS ISO images can be downloaded from the - <link -xlink:href="https://nixos.org/nixos/download.html">NixOS download - page</link>. There are a number of installation options. If you happen to - have an optical drive and a spare CD, burning the image to CD and booting - from that is probably the easiest option. Most people will need to prepare a - USB stick to boot from. <xref linkend="sec-booting-from-usb"/> describes the - preferred method to prepare a USB stick. A number of alternative methods are - presented in the - <link -xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS - Wiki</link>. - </para> - <para> - As an alternative to installing NixOS yourself, you can get a running NixOS - system through several other means: - <itemizedlist> - <listitem> - <para> - Using virtual appliances in Open Virtualization Format (OVF) that can be - imported into VirtualBox. These are available from the - <link xlink:href="https://nixos.org/nixos/download.html">NixOS download - page</link>. - </para> - </listitem> - <listitem> - <para> - Using AMIs for Amazon’s EC2. To find one for your region and instance - type, please refer to the - <link - xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list - of most recent AMIs</link>. - </para> - </listitem> - <listitem> - <para> - Using NixOps, the NixOS-based cloud deployment tool, which allows you to - provision VirtualBox and EC2 NixOS instances from declarative - specifications. Check out the - <link - xlink:href="https://nixos.org/nixops">NixOps homepage</link> for - details. - </para> - </listitem> - </itemizedlist> - </para> -</chapter> diff --git a/nixos/doc/manual/installation/upgrading.chapter.md b/nixos/doc/manual/installation/upgrading.chapter.md new file mode 100644 index 00000000000..b7903b9d3cb --- /dev/null +++ b/nixos/doc/manual/installation/upgrading.chapter.md @@ -0,0 +1,118 @@ +# Upgrading NixOS {#sec-upgrading} + +The best way to keep your NixOS installation up to date is to use one of +the NixOS *channels*. A channel is a Nix mechanism for distributing Nix +expressions and associated binaries. The NixOS channels are updated +automatically from NixOS's Git repository after certain tests have +passed and all packages have been built. These channels are: + +- *Stable channels*, such as [`nixos-21.05`](https://nixos.org/channels/nixos-21.05). + These only get conservative bug fixes and package upgrades. For + instance, a channel update may cause the Linux kernel on your system + to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but not + from 4.19.x to 4.20.x (a major change that has the potential to break things). + Stable channels are generally maintained until the next stable + branch is created. + +- The *unstable channel*, [`nixos-unstable`](https://nixos.org/channels/nixos-unstable). + This corresponds to NixOS's main development branch, and may thus see + radical changes between channel updates. It's not recommended for + production systems. + +- *Small channels*, such as [`nixos-21.05-small`](https://nixos.org/channels/nixos-21.05-small) + or [`nixos-unstable-small`](https://nixos.org/channels/nixos-unstable-small). + These are identical to the stable and unstable channels described above, + except that they contain fewer binary packages. This means they get updated + faster than the regular channels (for instance, when a critical security patch + is committed to NixOS's source tree), but may require more packages to be + built from source than usual. They're mostly intended for server environments + and as such contain few GUI applications. + +To see what channels are available, go to <https://nixos.org/channels>. +(Note that the URIs of the various channels redirect to a directory that +contains the channel's latest version and includes ISO images and +VirtualBox appliances.) Please note that during the release process, +channels that are not yet released will be present here as well. See the +Getting NixOS page <https://nixos.org/nixos/download.html> to find the +newest supported stable release. + +When you first install NixOS, you're automatically subscribed to the +NixOS channel that corresponds to your installation source. For +instance, if you installed from a 21.05 ISO, you will be subscribed to +the `nixos-21.05` channel. To see which NixOS channel you're subscribed +to, run the following as root: + +```ShellSession +# nix-channel --list | grep nixos +nixos https://nixos.org/channels/nixos-unstable +``` + +To switch to a different NixOS channel, do + +```ShellSession +# nix-channel --add https://nixos.org/channels/channel-name nixos +``` + +(Be sure to include the `nixos` parameter at the end.) For instance, to +use the NixOS 21.05 stable channel: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-21.05 nixos +``` + +If you have a server, you may want to use the "small" channel instead: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos +``` + +And if you want to live on the bleeding edge: + +```ShellSession +# nix-channel --add https://nixos.org/channels/nixos-unstable nixos +``` + +You can then upgrade NixOS to the latest version in your chosen channel +by running + +```ShellSession +# nixos-rebuild switch --upgrade +``` + +which is equivalent to the more verbose `nix-channel --update nixos; nixos-rebuild switch`. + +::: {.note} +Channels are set per user. This means that running `nix-channel --add` +as a non root user (or without sudo) will not affect +configuration in `/etc/nixos/configuration.nix` +::: + +::: {.warning} +It is generally safe to switch back and forth between channels. The only +exception is that a newer NixOS may also have a newer Nix version, which +may involve an upgrade of Nix's database schema. This cannot be undone +easily, so in that case you will not be able to go back to your original +channel. +::: + +## Automatic Upgrades {#sec-upgrading-automatic} + +You can keep a NixOS system up-to-date automatically by adding the +following to `configuration.nix`: + +```nix +system.autoUpgrade.enable = true; +system.autoUpgrade.allowReboot = true; +``` + +This enables a periodically executed systemd service named +`nixos-upgrade.service`. If the `allowReboot` option is `false`, it runs +`nixos-rebuild switch --upgrade` to upgrade NixOS to the latest version +in the current channel. (To see when the service runs, see `systemctl list-timers`.) +If `allowReboot` is `true`, then the system will automatically reboot if +the new generation contains a different kernel, initrd or kernel +modules. You can also specify a channel explicitly, e.g. + +```nix +system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.05; +``` diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml deleted file mode 100644 index 960d4fa9a43..00000000000 --- a/nixos/doc/manual/installation/upgrading.xml +++ /dev/null @@ -1,139 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - version="5.0" - xml:id="sec-upgrading"> - <title>Upgrading NixOS</title> - <para> - The best way to keep your NixOS installation up to date is to use one of the - NixOS <emphasis>channels</emphasis>. A channel is a Nix mechanism for - distributing Nix expressions and associated binaries. The NixOS channels are - updated automatically from NixOS’s Git repository after certain tests have - passed and all packages have been built. These channels are: - <itemizedlist> - <listitem> - <para> - <emphasis>Stable channels</emphasis>, such as - <literal - xlink:href="https://nixos.org/channels/nixos-21.05">nixos-21.05</literal>. - These only get conservative bug fixes and package upgrades. For instance, - a channel update may cause the Linux kernel on your system to be upgraded - from 4.19.34 to 4.19.38 (a minor bug fix), but not from - 4.19.<replaceable>x</replaceable> to 4.20.<replaceable>x</replaceable> (a - major change that has the potential to break things). Stable channels are - generally maintained until the next stable branch is created. - </para> - <para></para> - </listitem> - <listitem> - <para> - The <emphasis>unstable channel</emphasis>, - <literal - xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>. - This corresponds to NixOS’s main development branch, and may thus see - radical changes between channel updates. It’s not recommended for - production systems. - </para> - </listitem> - <listitem> - <para> - <emphasis>Small channels</emphasis>, such as - <literal - xlink:href="https://nixos.org/channels/nixos-21.05-small">nixos-21.05-small</literal> - or - <literal - xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. - These are identical to the stable and unstable channels described above, - except that they contain fewer binary packages. This means they get - updated faster than the regular channels (for instance, when a critical - security patch is committed to NixOS’s source tree), but may require - more packages to be built from source than usual. They’re mostly - intended for server environments and as such contain few GUI applications. - </para> - </listitem> - </itemizedlist> - To see what channels are available, go to - <link xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the - various channels redirect to a directory that contains the channel’s latest - version and includes ISO images and VirtualBox appliances.) Please note that - during the release process, channels that are not yet released will be - present here as well. See the Getting NixOS page - <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest - supported stable release. - </para> - <para> - When you first install NixOS, you’re automatically subscribed to the NixOS - channel that corresponds to your installation source. For instance, if you - installed from a 21.05 ISO, you will be subscribed to the - <literal>nixos-21.05</literal> channel. To see which NixOS channel you’re - subscribed to, run the following as root: -<screen> -<prompt># </prompt>nix-channel --list | grep nixos -nixos https://nixos.org/channels/nixos-unstable -</screen> - To switch to a different NixOS channel, do -<screen> -<prompt># </prompt>nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos -</screen> - (Be sure to include the <literal>nixos</literal> parameter at the end.) For - instance, to use the NixOS 21.05 stable channel: -<screen> -<prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-21.05 nixos -</screen> - If you have a server, you may want to use the “small” channel instead: -<screen> -<prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos -</screen> - And if you want to live on the bleeding edge: -<screen> -<prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-unstable nixos -</screen> - </para> - <para> - You can then upgrade NixOS to the latest version in your chosen channel by - running -<screen> -<prompt># </prompt>nixos-rebuild switch --upgrade -</screen> - which is equivalent to the more verbose <literal>nix-channel --update nixos; - nixos-rebuild switch</literal>. - </para> - <note> - <para> - Channels are set per user. This means that running <literal> nix-channel - --add</literal> as a non root user (or without sudo) will not affect - configuration in <literal>/etc/nixos/configuration.nix</literal> - </para> - </note> - <warning> - <para> - It is generally safe to switch back and forth between channels. The only - exception is that a newer NixOS may also have a newer Nix version, which may - involve an upgrade of Nix’s database schema. This cannot be undone easily, - so in that case you will not be able to go back to your original channel. - </para> - </warning> - <section xml:id="sec-upgrading-automatic"> - <title>Automatic Upgrades</title> - - <para> - You can keep a NixOS system up-to-date automatically by adding the following - to <filename>configuration.nix</filename>: -<programlisting> -<xref linkend="opt-system.autoUpgrade.enable"/> = true; -<xref linkend="opt-system.autoUpgrade.allowReboot"/> = true; -</programlisting> - This enables a periodically executed systemd service named - <literal>nixos-upgrade.service</literal>. If the <literal>allowReboot</literal> - option is <literal>false</literal>, it runs <command>nixos-rebuild switch - --upgrade</command> to upgrade NixOS to the latest version in the current - channel. (To see when the service runs, see <command>systemctl list-timers</command>.) - If <literal>allowReboot</literal> is <literal>true</literal>, then the - system will automatically reboot if the new generation contains a different - kernel, initrd or kernel modules. - You can also specify a channel explicitly, e.g. -<programlisting> -<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-21.05; -</programlisting> - </para> - </section> -</chapter> |