Merge pull request #129154 from bobby285271/pr15

nixos/doc: convert Chapter 1, 3, 4 to CommonMark
This commit is contained in:
Jörg Thalheim 2021-09-07 06:29:19 +01:00 committed by GitHub
commit e622dd1c84
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 564 additions and 293 deletions

View file

@ -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 youve
<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>

View file

@ -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 Amazons 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>

View file

@ -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 NixOSs 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 NixOSs main development branch, and may
thus see radical changes between channel updates. Its 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
NixOSs source tree), but may require more packages to be built
from source than usual. Theyre 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 channels 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, youre 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 youre 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 Nixs 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>

View file

@ -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
```

View file

@ -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 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).
<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>

View file

@ -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>

View file

@ -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.

View file

@ -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 Amazons 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>

View file

@ -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;
```

View file

@ -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 NixOSs 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 NixOSs main development branch, and may thus see
radical changes between channel updates. Its 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 NixOSs source tree), but may require
more packages to be built from source than usual. Theyre 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 channels 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, youre 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 youre
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 Nixs 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>