commit e622dd1c8422fa378b0ee242b2804afac19b61ec · pyrox.dev/nixpkgs

+117

nixos/doc/manual/from_md/installation/changing-config.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-changing-config">

     

       2
       2
       +
         <title>Changing the Configuration</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           The file <literal>/etc/nixos/configuration.nix</literal> contains

     

       5
       5
       +
           the current configuration of your machine. Whenever you’ve

     

       6
       6
       +
           <link linkend="ch-configuration">changed something</link> in that

     

       7
       7
       +
           file, you should do

     

       8
       8
       +
         </para>

     

       9
       9
       +
         <programlisting>

     

       10
       10
       +
       # nixos-rebuild switch

     

       11
       11
       +
       </programlisting>

     

       12
       12
       +
         <para>

     

       13
       13
       +
           to build the new configuration, make it the default configuration

     

       14
       14
       +
           for booting, and try to realise the configuration in the running

     

       15
       15
       +
           system (e.g., by restarting system services).

     

       16
       16
       +
         </para>

     

       17
       17
       +
         <warning>

     

       18
       18
       +
           <para>

     

       19
       19
       +
             This command doesn't start/stop

     

       20
       20
       +
             <link linkend="opt-systemd.user.services">user services</link>

     

       21
       21
       +
             automatically. <literal>nixos-rebuild</literal> only runs a

     

       22
       22
       +
             <literal>daemon-reload</literal> for each user with running user

     

       23
       23
       +
             services.

     

       24
       24
       +
           </para>

     

       25
       25
       +
         </warning>

     

       26
       26
       +
         <warning>

     

       27
       27
       +
           <para>

     

       28
       28
       +
             These commands must be executed as root, so you should either run

     

       29
       29
       +
             them from a root shell or by prefixing them with

     

       30
       30
       +
             <literal>sudo -i</literal>.

     

       31
       31
       +
           </para>

     

       32
       32
       +
         </warning>

     

       33
       33
       +
         <para>

     

       34
       34
       +
           You can also do

     

       35
       35
       +
         </para>

     

       36
       36
       +
         <programlisting>

     

       37
       37
       +
       # nixos-rebuild test

     

       38
       38
       +
       </programlisting>

     

       39
       39
       +
         <para>

     

       40
       40
       +
           to build the configuration and switch the running system to it, but

     

       41
       41
       +
           without making it the boot default. So if (say) the configuration

     

       42
       42
       +
           locks up your machine, you can just reboot to get back to a working

     

       43
       43
       +
           configuration.

     

       44
       44
       +
         </para>

     

       45
       45
       +
         <para>

     

       46
       46
       +
           There is also

     

       47
       47
       +
         </para>

     

       48
       48
       +
         <programlisting>

     

       49
       49
       +
       # nixos-rebuild boot

     

       50
       50
       +
       </programlisting>

     

       51
       51
       +
         <para>

     

       52
       52
       +
           to build the configuration and make it the boot default, but not

     

       53
       53
       +
           switch to it now (so it will only take effect after the next

     

       54
       54
       +
           reboot).

     

       55
       55
       +
         </para>

     

       56
       56
       +
         <para>

     

       57
       57
       +
           You can make your configuration show up in a different submenu of

     

       58
       58
       +
           the GRUB 2 boot screen by giving it a different <emphasis>profile

     

       59
       59
       +
           name</emphasis>, e.g.

     

       60
       60
       +
         </para>

     

       61
       61
       +
         <programlisting>

     

       62
       62
       +
       # nixos-rebuild switch -p test

     

       63
       63
       +
       </programlisting>

     

       64
       64
       +
         <para>

     

       65
       65
       +
           which causes the new configuration (and previous ones created using

     

       66
       66
       +
           <literal>-p test</literal>) to show up in the GRUB submenu

     

       67
       67
       +
           <quote>NixOS - Profile 'test'</quote>. This can be useful to

     

       68
       68
       +
           separate test configurations from <quote>stable</quote>

     

       69
       69
       +
           configurations.

     

       70
       70
       +
         </para>

     

       71
       71
       +
         <para>

     

       72
       72
       +
           Finally, you can do

     

       73
       73
       +
         </para>

     

       74
       74
       +
         <programlisting>

     

       75
       75
       +
       $ nixos-rebuild build

     

       76
       76
       +
       </programlisting>

     

       77
       77
       +
         <para>

     

       78
       78
       +
           to build the configuration but nothing more. This is useful to see

     

       79
       79
       +
           whether everything compiles cleanly.

     

       80
       80
       +
         </para>

     

       81
       81
       +
         <para>

     

       82
       82
       +
           If you have a machine that supports hardware virtualisation, you can

     

       83
       83
       +
           also test the new configuration in a sandbox by building and running

     

       84
       84
       +
           a QEMU <emphasis>virtual machine</emphasis> that contains the

     

       85
       85
       +
           desired configuration. Just do

     

       86
       86
       +
         </para>

     

       87
       87
       +
         <programlisting>

     

       88
       88
       +
       $ nixos-rebuild build-vm

     

       89
       89
       +
       $ ./result/bin/run-*-vm

     

       90
       90
       +
       </programlisting>

     

       91
       91
       +
         <para>

     

       92
       92
       +
           The VM does not have any data from your host system, so your

     

       93
       93
       +
           existing user accounts and home directories will not be available

     

       94
       94
       +
           unless you have set <literal>mutableUsers = false</literal>. Another

     

       95
       95
       +
           way is to temporarily add the following to your configuration:

     

       96
       96
       +
         </para>

     

       97
       97
       +
         <programlisting language="bash">

     

       98
       98
       +
       users.users.your-user.initialHashedPassword = &quot;test&quot;;

     

       99
       99
       +
       </programlisting>

     

       100
       100
       +
         <para>

     

       101
       101
       +
           <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if

     

       102
       102
       +
           you have started the virtual machine at least once without the right

     

       103
       103
       +
           users, otherwise the changes will not get picked up. You can forward

     

       104
       104
       +
           ports on the host to the guest. For instance, the following will

     

       105
       105
       +
           forward host port 2222 to guest port 22 (SSH):

     

       106
       106
       +
         </para>

     

       107
       107
       +
         <programlisting>

     

       108
       108
       +
       $ QEMU_NET_OPTS=&quot;hostfwd=tcp::2222-:22&quot; ./result/bin/run-*-vm

     

       109
       109
       +
       </programlisting>

     

       110
       110
       +
         <para>

     

       111
       111
       +
           allowing you to log in via SSH (assuming you have set the

     

       112
       112
       +
           appropriate passwords or SSH authorized keys):

     

       113
       113
       +
         </para>

     

       114
       114
       +
         <programlisting>

     

       115
       115
       +
       $ ssh -p 2222 localhost

     

       116
       116
       +
       </programlisting>

     

       117
       117
       +
       </chapter>

+48

nixos/doc/manual/from_md/installation/obtaining.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-obtaining">

     

       2
       2
       +
         <title>Obtaining NixOS</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           NixOS ISO images can be downloaded from the

     

       5
       5
       +
           <link xlink:href="https://nixos.org/nixos/download.html">NixOS

     

       6
       6
       +
           download page</link>. There are a number of installation options. If

     

       7
       7
       +
           you happen to have an optical drive and a spare CD, burning the

     

       8
       8
       +
           image to CD and booting from that is probably the easiest option.

     

       9
       9
       +
           Most people will need to prepare a USB stick to boot from.

     

       10
       10
       +
           <xref linkend="sec-booting-from-usb" /> describes the preferred

     

       11
       11
       +
           method to prepare a USB stick. A number of alternative methods are

     

       12
       12
       +
           presented in the

     

       13
       13
       +
           <link xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS

     

       14
       14
       +
           Wiki</link>.

     

       15
       15
       +
         </para>

     

       16
       16
       +
         <para>

     

       17
       17
       +
           As an alternative to installing NixOS yourself, you can get a

     

       18
       18
       +
           running NixOS system through several other means:

     

       19
       19
       +
         </para>

     

       20
       20
       +
         <itemizedlist>

     

       21
       21
       +
           <listitem>

     

       22
       22
       +
             <para>

     

       23
       23
       +
               Using virtual appliances in Open Virtualization Format (OVF)

     

       24
       24
       +
               that can be imported into VirtualBox. These are available from

     

       25
       25
       +
               the

     

       26
       26
       +
               <link xlink:href="https://nixos.org/nixos/download.html">NixOS

     

       27
       27
       +
               download page</link>.

     

       28
       28
       +
             </para>

     

       29
       29
       +
           </listitem>

     

       30
       30
       +
           <listitem>

     

       31
       31
       +
             <para>

     

       32
       32
       +
               Using AMIs for Amazon’s EC2. To find one for your region and

     

       33
       33
       +
               instance type, please refer to the

     

       34
       34
       +
               <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list

     

       35
       35
       +
               of most recent AMIs</link>.

     

       36
       36
       +
             </para>

     

       37
       37
       +
           </listitem>

     

       38
       38
       +
           <listitem>

     

       39
       39
       +
             <para>

     

       40
       40
       +
               Using NixOps, the NixOS-based cloud deployment tool, which

     

       41
       41
       +
               allows you to provision VirtualBox and EC2 NixOS instances from

     

       42
       42
       +
               declarative specifications. Check out the

     

       43
       43
       +
               <link xlink:href="https://nixos.org/nixops">NixOps

     

       44
       44
       +
               homepage</link> for details.

     

       45
       45
       +
             </para>

     

       46
       46
       +
           </listitem>

     

       47
       47
       +
         </itemizedlist>

     

       48
       48
       +
       </chapter>

+152

nixos/doc/manual/from_md/installation/upgrading.chapter.xml

···

       1
       1
       +
       <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-upgrading">

     

       2
       2
       +
         <title>Upgrading NixOS</title>

     

       3
       3
       +
         <para>

     

       4
       4
       +
           The best way to keep your NixOS installation up to date is to use

     

       5
       5
       +
           one of the NixOS <emphasis>channels</emphasis>. A channel is a Nix

     

       6
       6
       +
           mechanism for distributing Nix expressions and associated binaries.

     

       7
       7
       +
           The NixOS channels are updated automatically from NixOS’s Git

     

       8
       8
       +
           repository after certain tests have passed and all packages have

     

       9
       9
       +
           been built. These channels are:

     

       10
       10
       +
         </para>

     

       11
       11
       +
         <itemizedlist>

     

       12
       12
       +
           <listitem>

     

       13
       13
       +
             <para>

     

       14
       14
       +
               <emphasis>Stable channels</emphasis>, such as

     

       15
       15
       +
               <link xlink:href="https://nixos.org/channels/nixos-21.05"><literal>nixos-21.05</literal></link>.

     

       16
       16
       +
               These only get conservative bug fixes and package upgrades. For

     

       17
       17
       +
               instance, a channel update may cause the Linux kernel on your

     

       18
       18
       +
               system to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix),

     

       19
       19
       +
               but not from 4.19.x to 4.20.x (a major change that has the

     

       20
       20
       +
               potential to break things). Stable channels are generally

     

       21
       21
       +
               maintained until the next stable branch is created.

     

       22
       22
       +
             </para>

     

       23
       23
       +
           </listitem>

     

       24
       24
       +
           <listitem>

     

       25
       25
       +
             <para>

     

       26
       26
       +
               The <emphasis>unstable channel</emphasis>,

     

       27
       27
       +
               <link xlink:href="https://nixos.org/channels/nixos-unstable"><literal>nixos-unstable</literal></link>.

     

       28
       28
       +
               This corresponds to NixOS’s main development branch, and may

     

       29
       29
       +
               thus see radical changes between channel updates. It’s not

     

       30
       30
       +
               recommended for production systems.

     

       31
       31
       +
             </para>

     

       32
       32
       +
           </listitem>

     

       33
       33
       +
           <listitem>

     

       34
       34
       +
             <para>

     

       35
       35
       +
               <emphasis>Small channels</emphasis>, such as

     

       36
       36
       +
               <link xlink:href="https://nixos.org/channels/nixos-21.05-small"><literal>nixos-21.05-small</literal></link>

     

       37
       37
       +
               or

     

       38
       38
       +
               <link xlink:href="https://nixos.org/channels/nixos-unstable-small"><literal>nixos-unstable-small</literal></link>.

     

       39
       39
       +
               These are identical to the stable and unstable channels

     

       40
       40
       +
               described above, except that they contain fewer binary packages.

     

       41
       41
       +
               This means they get updated faster than the regular channels

     

       42
       42
       +
               (for instance, when a critical security patch is committed to

     

       43
       43
       +
               NixOS’s source tree), but may require more packages to be built

     

       44
       44
       +
               from source than usual. They’re mostly intended for server

     

       45
       45
       +
               environments and as such contain few GUI applications.

     

       46
       46
       +
             </para>

     

       47
       47
       +
           </listitem>

     

       48
       48
       +
         </itemizedlist>

     

       49
       49
       +
         <para>

     

       50
       50
       +
           To see what channels are available, go to

     

       51
       51
       +
           <link xlink:href="https://nixos.org/channels">https://nixos.org/channels</link>.

     

       52
       52
       +
           (Note that the URIs of the various channels redirect to a directory

     

       53
       53
       +
           that contains the channel’s latest version and includes ISO images

     

       54
       54
       +
           and VirtualBox appliances.) Please note that during the release

     

       55
       55
       +
           process, channels that are not yet released will be present here as

     

       56
       56
       +
           well. See the Getting NixOS page

     

       57
       57
       +
           <link xlink:href="https://nixos.org/nixos/download.html">https://nixos.org/nixos/download.html</link>

     

       58
       58
       +
           to find the newest supported stable release.

     

       59
       59
       +
         </para>

     

       60
       60
       +
         <para>

     

       61
       61
       +
           When you first install NixOS, you’re automatically subscribed to the

     

       62
       62
       +
           NixOS channel that corresponds to your installation source. For

     

       63
       63
       +
           instance, if you installed from a 21.05 ISO, you will be subscribed

     

       64
       64
       +
           to the <literal>nixos-21.05</literal> channel. To see which NixOS

     

       65
       65
       +
           channel you’re subscribed to, run the following as root:

     

       66
       66
       +
         </para>

     

       67
       67
       +
         <programlisting>

     

       68
       68
       +
       # nix-channel --list | grep nixos

     

       69
       69
       +
       nixos https://nixos.org/channels/nixos-unstable

     

       70
       70
       +
       </programlisting>

     

       71
       71
       +
         <para>

     

       72
       72
       +
           To switch to a different NixOS channel, do

     

       73
       73
       +
         </para>

     

       74
       74
       +
         <programlisting>

     

       75
       75
       +
       # nix-channel --add https://nixos.org/channels/channel-name nixos

     

       76
       76
       +
       </programlisting>

     

       77
       77
       +
         <para>

     

       78
       78
       +
           (Be sure to include the <literal>nixos</literal> parameter at the

     

       79
       79
       +
           end.) For instance, to use the NixOS 21.05 stable channel:

     

       80
       80
       +
         </para>

     

       81
       81
       +
         <programlisting>

     

       82
       82
       +
       # nix-channel --add https://nixos.org/channels/nixos-21.05 nixos

     

       83
       83
       +
       </programlisting>

     

       84
       84
       +
         <para>

     

       85
       85
       +
           If you have a server, you may want to use the <quote>small</quote>

     

       86
       86
       +
           channel instead:

     

       87
       87
       +
         </para>

     

       88
       88
       +
         <programlisting>

     

       89
       89
       +
       # nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos

     

       90
       90
       +
       </programlisting>

     

       91
       91
       +
         <para>

     

       92
       92
       +
           And if you want to live on the bleeding edge:

     

       93
       93
       +
         </para>

     

       94
       94
       +
         <programlisting>

     

       95
       95
       +
       # nix-channel --add https://nixos.org/channels/nixos-unstable nixos

     

       96
       96
       +
       </programlisting>

     

       97
       97
       +
         <para>

     

       98
       98
       +
           You can then upgrade NixOS to the latest version in your chosen

     

       99
       99
       +
           channel by running

     

       100
       100
       +
         </para>

     

       101
       101
       +
         <programlisting>

     

       102
       102
       +
       # nixos-rebuild switch --upgrade

     

       103
       103
       +
       </programlisting>

     

       104
       104
       +
         <para>

     

       105
       105
       +
           which is equivalent to the more verbose

     

       106
       106
       +
           <literal>nix-channel --update nixos; nixos-rebuild switch</literal>.

     

       107
       107
       +
         </para>

     

       108
       108
       +
         <note>

     

       109
       109
       +
           <para>

     

       110
       110
       +
             Channels are set per user. This means that running

     

       111
       111
       +
             <literal>nix-channel --add</literal> as a non root user (or

     

       112
       112
       +
             without sudo) will not affect configuration in

     

       113
       113
       +
             <literal>/etc/nixos/configuration.nix</literal>

     

       114
       114
       +
           </para>

     

       115
       115
       +
         </note>

     

       116
       116
       +
         <warning>

     

       117
       117
       +
           <para>

     

       118
       118
       +
             It is generally safe to switch back and forth between channels.

     

       119
       119
       +
             The only exception is that a newer NixOS may also have a newer Nix

     

       120
       120
       +
             version, which may involve an upgrade of Nix’s database schema.

     

       121
       121
       +
             This cannot be undone easily, so in that case you will not be able

     

       122
       122
       +
             to go back to your original channel.

     

       123
       123
       +
           </para>

     

       124
       124
       +
         </warning>

     

       125
       125
       +
         <section xml:id="sec-upgrading-automatic">

     

       126
       126
       +
           <title>Automatic Upgrades</title>

     

       127
       127
       +
           <para>

     

       128
       128
       +
             You can keep a NixOS system up-to-date automatically by adding the

     

       129
       129
       +
             following to <literal>configuration.nix</literal>:

     

       130
       130
       +
           </para>

     

       131
       131
       +
           <programlisting language="bash">

     

       132
       132
       +
       system.autoUpgrade.enable = true;

     

       133
       133
       +
       system.autoUpgrade.allowReboot = true;

     

       134
       134
       +
       </programlisting>

     

       135
       135
       +
           <para>

     

       136
       136
       +
             This enables a periodically executed systemd service named

     

       137
       137
       +
             <literal>nixos-upgrade.service</literal>. If the

     

       138
       138
       +
             <literal>allowReboot</literal> option is <literal>false</literal>,

     

       139
       139
       +
             it runs <literal>nixos-rebuild switch --upgrade</literal> to

     

       140
       140
       +
             upgrade NixOS to the latest version in the current channel. (To

     

       141
       141
       +
             see when the service runs, see

     

       142
       142
       +
             <literal>systemctl list-timers</literal>.) If

     

       143
       143
       +
             <literal>allowReboot</literal> is <literal>true</literal>, then

     

       144
       144
       +
             the system will automatically reboot if the new generation

     

       145
       145
       +
             contains a different kernel, initrd or kernel modules. You can

     

       146
       146
       +
             also specify a channel explicitly, e.g.

     

       147
       147
       +
           </para>

     

       148
       148
       +
           <programlisting language="bash">

     

       149
       149
       +
       system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.05;

     

       150
       150
       +
       </programlisting>

     

       151
       151
       +
         </section>

     

       152
       152
       +
       </chapter>

+100

nixos/doc/manual/installation/changing-config.chapter.md

···

       1
       1
       +
       # Changing the Configuration {#sec-changing-config}

     

       2
       2
       +
       

     

       3
       3
       +
       The file `/etc/nixos/configuration.nix` contains the current

     

       4
       4
       +
       configuration of your machine. Whenever you've [changed

     

       5
       5
       +
       something](#ch-configuration) in that file, you should do

     

       6
       6
       +
       

     

       7
       7
       +
       ```ShellSession

     

       8
       8
       +
       # nixos-rebuild switch

     

       9
       9
       +
       ```

     

       10
       10
       +
       

     

       11
       11
       +
       to build the new configuration, make it the default configuration for

     

       12
       12
       +
       booting, and try to realise the configuration in the running system

     

       13
       13
       +
       (e.g., by restarting system services).

     

       14
       14
       +
       

     

       15
       15
       +
       ::: {.warning}

     

       16
       16
       +
       This command doesn\'t start/stop [user services](#opt-systemd.user.services)

     

       17
       17
       +
       automatically. `nixos-rebuild` only runs a `daemon-reload` for each user with running

     

       18
       18
       +
       user services.

     

       19
       19
       +
       :::

     

       20
       20
       +
       

     

       21
       21
       +
       ::: {.warning}

     

       22
       22
       +
       These commands must be executed as root, so you should either run them

     

       23
       23
       +
       from a root shell or by prefixing them with `sudo -i`.

     

       24
       24
       +
       :::

     

       25
       25
       +
       

     

       26
       26
       +
       You can also do

     

       27
       27
       +
       

     

       28
       28
       +
       ```ShellSession

     

       29
       29
       +
       # nixos-rebuild test

     

       30
       30
       +
       ```

     

       31
       31
       +
       

     

       32
       32
       +
       to build the configuration and switch the running system to it, but

     

       33
       33
       +
       without making it the boot default. So if (say) the configuration locks

     

       34
       34
       +
       up your machine, you can just reboot to get back to a working

     

       35
       35
       +
       configuration.

     

       36
       36
       +
       

     

       37
       37
       +
       There is also

     

       38
       38
       +
       

     

       39
       39
       +
       ```ShellSession

     

       40
       40
       +
       # nixos-rebuild boot

     

       41
       41
       +
       ```

     

       42
       42
       +
       

     

       43
       43
       +
       to build the configuration and make it the boot default, but not switch

     

       44
       44
       +
       to it now (so it will only take effect after the next reboot).

     

       45
       45
       +
       

     

       46
       46
       +
       You can make your configuration show up in a different submenu of the

     

       47
       47
       +
       GRUB 2 boot screen by giving it a different *profile name*, e.g.

     

       48
       48
       +
       

     

       49
       49
       +
       ```ShellSession

     

       50
       50
       +
       # nixos-rebuild switch -p test

     

       51
       51
       +
       ```

     

       52
       52
       +
       

     

       53
       53
       +
       which causes the new configuration (and previous ones created using

     

       54
       54
       +
       `-p test`) to show up in the GRUB submenu "NixOS - Profile \'test\'".

     

       55
       55
       +
       This can be useful to separate test configurations from "stable"

     

       56
       56
       +
       configurations.

     

       57
       57
       +
       

     

       58
       58
       +
       Finally, you can do

     

       59
       59
       +
       

     

       60
       60
       +
       ```ShellSession

     

       61
       61
       +
       $ nixos-rebuild build

     

       62
       62
       +
       ```

     

       63
       63
       +
       

     

       64
       64
       +
       to build the configuration but nothing more. This is useful to see

     

       65
       65
       +
       whether everything compiles cleanly.

     

       66
       66
       +
       

     

       67
       67
       +
       If you have a machine that supports hardware virtualisation, you can

     

       68
       68
       +
       also test the new configuration in a sandbox by building and running a

     

       69
       69
       +
       QEMU *virtual machine* that contains the desired configuration. Just do

     

       70
       70
       +
       

     

       71
       71
       +
       ```ShellSession

     

       72
       72
       +
       $ nixos-rebuild build-vm

     

       73
       73
       +
       $ ./result/bin/run-*-vm

     

       74
       74
       +
       ```

     

       75
       75
       +
       

     

       76
       76
       +
       The VM does not have any data from your host system, so your existing

     

       77
       77
       +
       user accounts and home directories will not be available unless you have

     

       78
       78
       +
       set `mutableUsers = false`. Another way is to temporarily add the

     

       79
       79
       +
       following to your configuration:

     

       80
       80
       +
       

     

       81
       81
       +
       ```nix

     

       82
       82
       +
       users.users.your-user.initialHashedPassword = "test";

     

       83
       83
       +
       ```

     

       84
       84
       +
       

     

       85
       85
       +
       *Important:* delete the \$hostname.qcow2 file if you have started the

     

       86
       86
       +
       virtual machine at least once without the right users, otherwise the

     

       87
       87
       +
       changes will not get picked up. You can forward ports on the host to the

     

       88
       88
       +
       guest. For instance, the following will forward host port 2222 to guest

     

       89
       89
       +
       port 22 (SSH):

     

       90
       90
       +
       

     

       91
       91
       +
       ```ShellSession

     

       92
       92
       +
       $ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

     

       93
       93
       +
       ```

     

       94
       94
       +
       

     

       95
       95
       +
       allowing you to log in via SSH (assuming you have set the appropriate

     

       96
       96
       +
       passwords or SSH authorized keys):

     

       97
       97
       +
       

     

       98
       98
       +
       ```ShellSession

     

       99
       99
       +
       $ ssh -p 2222 localhost

     

       100
       100
       +
       ```

-97

nixos/doc/manual/installation/changing-config.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                version="5.0"

     

       4
       4
       -
                xml:id="sec-changing-config">

     

       5
       5
       -
        <title>Changing the Configuration</title>

     

       6
       6
       -
        <para>

     

       7
       7
       -
         The file <filename>/etc/nixos/configuration.nix</filename> contains the

     

       8
       8
       -
         current configuration of your machine. Whenever you’ve

     

       9
       9
       -
         <link linkend="ch-configuration">changed something</link> in that file, you

     

       10
       10
       -
         should do

     

       11
       11
       -
       <screen>

     

       12
       12
       -
       <prompt># </prompt>nixos-rebuild switch

     

       13
       13
       -
       </screen>

     

       14
       14
       -
         to build the new configuration, make it the default configuration for

     

       15
       15
       -
         booting, and try to realise the configuration in the running system (e.g., by

     

       16
       16
       -
         restarting system services).

     

       17
       17
       -
         <warning>

     

       18
       18
       -
          <para>

     

       19
       19
       -
           This command doesn't start/stop <link linkend="opt-systemd.user.services">user

     

       20
       20
       -
           services</link> automatically. <command>nixos-rebuild</command> only runs a

     

       21
       21
       -
           <literal>daemon-reload</literal> for each user with running user services.

     

       22
       22
       -
          </para>

     

       23
       23
       -
         </warning>

     

       24
       24
       -
        </para>

     

       25
       25
       -
        <warning>

     

       26
       26
       -
         <para>

     

       27
       27
       -
          These commands must be executed as root, so you should either run them from

     

       28
       28
       -
          a root shell or by prefixing them with <literal>sudo -i</literal>.

     

       29
       29
       -
         </para>

     

       30
       30
       -
        </warning>

     

       31
       31
       -
        <para>

     

       32
       32
       -
         You can also do

     

       33
       33
       -
       <screen>

     

       34
       34
       -
       <prompt># </prompt>nixos-rebuild test

     

       35
       35
       -
       </screen>

     

       36
       36
       -
         to build the configuration and switch the running system to it, but without

     

       37
       37
       -
         making it the boot default. So if (say) the configuration locks up your

     

       38
       38
       -
         machine, you can just reboot to get back to a working configuration.

     

       39
       39
       -
        </para>

     

       40
       40
       -
        <para>

     

       41
       41
       -
         There is also

     

       42
       42
       -
       <screen>

     

       43
       43
       -
       <prompt># </prompt>nixos-rebuild boot

     

       44
       44
       -
       </screen>

     

       45
       45
       -
         to build the configuration and make it the boot default, but not switch to it

     

       46
       46
       -
         now (so it will only take effect after the next reboot).

     

       47
       47
       -
        </para>

     

       48
       48
       -
        <para>

     

       49
       49
       -
         You can make your configuration show up in a different submenu of the GRUB 2

     

       50
       50
       -
         boot screen by giving it a different <emphasis>profile name</emphasis>, e.g.

     

       51
       51
       -
       <screen>

     

       52
       52
       -
       <prompt># </prompt>nixos-rebuild switch -p test

     

       53
       53
       -
       </screen>

     

       54
       54
       -
         which causes the new configuration (and previous ones created using

     

       55
       55
       -
         <literal>-p test</literal>) to show up in the GRUB submenu “NixOS - Profile

     

       56
       56
       -
         'test'”. This can be useful to separate test configurations from

     

       57
       57
       -
         “stable” configurations.

     

       58
       58
       -
        </para>

     

       59
       59
       -
        <para>

     

       60
       60
       -
         Finally, you can do

     

       61
       61
       -
       <screen>

     

       62
       62
       -
       <prompt>$ </prompt>nixos-rebuild build

     

       63
       63
       -
       </screen>

     

       64
       64
       -
         to build the configuration but nothing more. This is useful to see whether

     

       65
       65
       -
         everything compiles cleanly.

     

       66
       66
       -
        </para>

     

       67
       67
       -
        <para>

     

       68
       68
       -
         If you have a machine that supports hardware virtualisation, you can also

     

       69
       69
       -
         test the new configuration in a sandbox by building and running a QEMU

     

       70
       70
       -
         <emphasis>virtual machine</emphasis> that contains the desired configuration.

     

       71
       71
       -
         Just do

     

       72
       72
       -
       <screen>

     

       73
       73
       -
       <prompt>$ </prompt>nixos-rebuild build-vm

     

       74
       74
       -
       <prompt>$ </prompt>./result/bin/run-*-vm

     

       75
       75
       -
       </screen>

     

       76
       76
       -
         The VM does not have any data from your host system, so your existing user

     

       77
       77
       -
         accounts and home directories will not be available unless you have set

     

       78
       78
       -
         <literal>mutableUsers = false</literal>. Another way is to temporarily add

     

       79
       79
       -
         the following to your configuration:

     

       80
       80
       -
       <screen>

     

       81
       81
       -
       <link linkend="opt-users.users._name_.initialHashedPassword">users.users.your-user.initialHashedPassword</link> = "test";

     

       82
       82
       -
       </screen>

     

       83
       83
       -
         <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you have

     

       84
       84
       -
         started the virtual machine at least once without the right users, otherwise

     

       85
       85
       -
         the changes will not get picked up. You can forward ports on the host to the

     

       86
       86
       -
         guest. For instance, the following will forward host port 2222 to guest port

     

       87
       87
       -
         22 (SSH):

     

       88
       88
       -
       <screen>

     

       89
       89
       -
       <prompt>$ </prompt>QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm

     

       90
       90
       -
       </screen>

     

       91
       91
       -
         allowing you to log in via SSH (assuming you have set the appropriate

     

       92
       92
       -
         passwords or SSH authorized keys):

     

       93
       93
       -
       <screen>

     

       94
       94
       -
       <prompt>$ </prompt>ssh -p 2222 localhost

     

       95
       95
       -
       </screen>

     

       96
       96
       -
        </para>

     

       97
       97
       -
       </chapter>

+3 -3

nixos/doc/manual/installation/installation.xml

···

       10
       10
        
          first-time use.

     

       11
       11
        
         </para>

     

       12
       12
        
        </partintro>

     

       13
       13
       -
        <xi:include href="obtaining.xml" />

     

       13
       13
       +
        <xi:include href="../from_md/installation/obtaining.chapter.xml" />

     

       14
       14
        
        <xi:include href="installing.xml" />

     

       15
       15
       -
        <xi:include href="changing-config.xml" />

     

       16
       16
       -
        <xi:include href="upgrading.xml" />

     

       15
       15
       +
        <xi:include href="../from_md/installation/changing-config.chapter.xml" />

     

       16
       16
       +
        <xi:include href="../from_md/installation/upgrading.chapter.xml" />

     

       17
       17
        
       </part>

+26

nixos/doc/manual/installation/obtaining.chapter.md

···

       1
       1
       +
       # Obtaining NixOS {#sec-obtaining}

     

       2
       2
       +
       

     

       3
       3
       +
       NixOS ISO images can be downloaded from the [NixOS download

     

       4
       4
       +
       page](https://nixos.org/nixos/download.html). There are a number of

     

       5
       5
       +
       installation options. If you happen to have an optical drive and a spare

     

       6
       6
       +
       CD, burning the image to CD and booting from that is probably the

     

       7
       7
       +
       easiest option. Most people will need to prepare a USB stick to boot

     

       8
       8
       +
       from. [](#sec-booting-from-usb) describes the preferred method to

     

       9
       9
       +
       prepare a USB stick. A number of alternative methods are presented in

     

       10
       10
       +
       the [NixOS Wiki](https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media).

     

       11
       11
       +
       

     

       12
       12
       +
       As an alternative to installing NixOS yourself, you can get a running

     

       13
       13
       +
       NixOS system through several other means:

     

       14
       14
       +
       

     

       15
       15
       +
       -   Using virtual appliances in Open Virtualization Format (OVF) that

     

       16
       16
       +
           can be imported into VirtualBox. These are available from the [NixOS

     

       17
       17
       +
           download page](https://nixos.org/nixos/download.html).

     

       18
       18
       +
       

     

       19
       19
       +
       -   Using AMIs for Amazon's EC2. To find one for your region and

     

       20
       20
       +
           instance type, please refer to the [list of most recent

     

       21
       21
       +
           AMIs](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix).

     

       22
       22
       +
       

     

       23
       23
       +
       -   Using NixOps, the NixOS-based cloud deployment tool, which allows

     

       24
       24
       +
           you to provision VirtualBox and EC2 NixOS instances from declarative

     

       25
       25
       +
           specifications. Check out the [NixOps

     

       26
       26
       +
           homepage](https://nixos.org/nixops) for details.

-54

nixos/doc/manual/installation/obtaining.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                xmlns:xi="http://www.w3.org/2001/XInclude"

     

       4
       4
       -
                version="5.0"

     

       5
       5
       -
                xml:id="sec-obtaining">

     

       6
       6
       -
        <title>Obtaining NixOS</title>

     

       7
       7
       -
        <para>

     

       8
       8
       -
         NixOS ISO images can be downloaded from the

     

       9
       9
       -
         <link

     

       10
       10
       -
       xlink:href="https://nixos.org/nixos/download.html">NixOS download

     

       11
       11
       -
         page</link>. There are a number of installation options. If you happen to

     

       12
       12
       -
         have an optical drive and a spare CD, burning the image to CD and booting

     

       13
       13
       -
         from that is probably the easiest option. Most people will need to prepare a

     

       14
       14
       -
         USB stick to boot from. <xref linkend="sec-booting-from-usb"/> describes the

     

       15
       15
       -
         preferred method to prepare a USB stick. A number of alternative methods are

     

       16
       16
       -
         presented in the

     

       17
       17
       -
         <link

     

       18
       18
       -
       xlink:href="https://nixos.wiki/wiki/NixOS_Installation_Guide#Making_the_installation_media">NixOS

     

       19
       19
       -
         Wiki</link>.

     

       20
       20
       -
        </para>

     

       21
       21
       -
        <para>

     

       22
       22
       -
         As an alternative to installing NixOS yourself, you can get a running NixOS

     

       23
       23
       -
         system through several other means:

     

       24
       24
       -
         <itemizedlist>

     

       25
       25
       -
          <listitem>

     

       26
       26
       -
           <para>

     

       27
       27
       -
            Using virtual appliances in Open Virtualization Format (OVF) that can be

     

       28
       28
       -
            imported into VirtualBox. These are available from the

     

       29
       29
       -
            <link xlink:href="https://nixos.org/nixos/download.html">NixOS download

     

       30
       30
       -
            page</link>.

     

       31
       31
       -
           </para>

     

       32
       32
       -
          </listitem>

     

       33
       33
       -
          <listitem>

     

       34
       34
       -
           <para>

     

       35
       35
       -
            Using AMIs for Amazon’s EC2. To find one for your region and instance

     

       36
       36
       -
            type, please refer to the

     

       37
       37
       -
            <link

     

       38
       38
       -
           xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/ec2-amis.nix">list

     

       39
       39
       -
            of most recent AMIs</link>.

     

       40
       40
       -
           </para>

     

       41
       41
       -
          </listitem>

     

       42
       42
       -
          <listitem>

     

       43
       43
       -
           <para>

     

       44
       44
       -
            Using NixOps, the NixOS-based cloud deployment tool, which allows you to

     

       45
       45
       -
            provision VirtualBox and EC2 NixOS instances from declarative

     

       46
       46
       -
            specifications. Check out the

     

       47
       47
       -
            <link

     

       48
       48
       -
           xlink:href="https://nixos.org/nixops">NixOps homepage</link> for

     

       49
       49
       -
            details.

     

       50
       50
       -
           </para>

     

       51
       51
       -
          </listitem>

     

       52
       52
       -
         </itemizedlist>

     

       53
       53
       -
        </para>

     

       54
       54
       -
       </chapter>

+118

nixos/doc/manual/installation/upgrading.chapter.md

···

       1
       1
       +
       # Upgrading NixOS {#sec-upgrading}

     

       2
       2
       +
       

     

       3
       3
       +
       The best way to keep your NixOS installation up to date is to use one of

     

       4
       4
       +
       the NixOS *channels*. A channel is a Nix mechanism for distributing Nix

     

       5
       5
       +
       expressions and associated binaries. The NixOS channels are updated

     

       6
       6
       +
       automatically from NixOS's Git repository after certain tests have

     

       7
       7
       +
       passed and all packages have been built. These channels are:

     

       8
       8
       +
       

     

       9
       9
       +
       -   *Stable channels*, such as [`nixos-21.05`](https://nixos.org/channels/nixos-21.05).

     

       10
       10
       +
           These only get conservative bug fixes and package upgrades. For

     

       11
       11
       +
           instance, a channel update may cause the Linux kernel on your system

     

       12
       12
       +
           to be upgraded from 4.19.34 to 4.19.38 (a minor bug fix), but not

     

       13
       13
       +
           from 4.19.x to 4.20.x (a major change that has the potential to break things).

     

       14
       14
       +
           Stable channels are generally maintained until the next stable

     

       15
       15
       +
           branch is created.

     

       16
       16
       +
       

     

       17
       17
       +
       -   The *unstable channel*, [`nixos-unstable`](https://nixos.org/channels/nixos-unstable).

     

       18
       18
       +
           This corresponds to NixOS's main development branch, and may thus see

     

       19
       19
       +
           radical changes between channel updates. It's not recommended for

     

       20
       20
       +
           production systems.

     

       21
       21
       +
       

     

       22
       22
       +
       -   *Small channels*, such as [`nixos-21.05-small`](https://nixos.org/channels/nixos-21.05-small)

     

       23
       23
       +
           or [`nixos-unstable-small`](https://nixos.org/channels/nixos-unstable-small).

     

       24
       24
       +
           These are identical to the stable and unstable channels described above,

     

       25
       25
       +
           except that they contain fewer binary packages. This means they get updated

     

       26
       26
       +
           faster than the regular channels (for instance, when a critical security patch

     

       27
       27
       +
           is committed to NixOS's source tree), but may require more packages to be

     

       28
       28
       +
           built from source than usual. They're mostly intended for server environments

     

       29
       29
       +
           and as such contain few GUI applications.

     

       30
       30
       +
       

     

       31
       31
       +
       To see what channels are available, go to <https://nixos.org/channels>.

     

       32
       32
       +
       (Note that the URIs of the various channels redirect to a directory that

     

       33
       33
       +
       contains the channel's latest version and includes ISO images and

     

       34
       34
       +
       VirtualBox appliances.) Please note that during the release process,

     

       35
       35
       +
       channels that are not yet released will be present here as well. See the

     

       36
       36
       +
       Getting NixOS page <https://nixos.org/nixos/download.html> to find the

     

       37
       37
       +
       newest supported stable release.

     

       38
       38
       +
       

     

       39
       39
       +
       When you first install NixOS, you're automatically subscribed to the

     

       40
       40
       +
       NixOS channel that corresponds to your installation source. For

     

       41
       41
       +
       instance, if you installed from a 21.05 ISO, you will be subscribed to

     

       42
       42
       +
       the `nixos-21.05` channel. To see which NixOS channel you're subscribed

     

       43
       43
       +
       to, run the following as root:

     

       44
       44
       +
       

     

       45
       45
       +
       ```ShellSession

     

       46
       46
       +
       # nix-channel --list | grep nixos

     

       47
       47
       +
       nixos https://nixos.org/channels/nixos-unstable

     

       48
       48
       +
       ```

     

       49
       49
       +
       

     

       50
       50
       +
       To switch to a different NixOS channel, do

     

       51
       51
       +
       

     

       52
       52
       +
       ```ShellSession

     

       53
       53
       +
       # nix-channel --add https://nixos.org/channels/channel-name nixos

     

       54
       54
       +
       ```

     

       55
       55
       +
       

     

       56
       56
       +
       (Be sure to include the `nixos` parameter at the end.) For instance, to

     

       57
       57
       +
       use the NixOS 21.05 stable channel:

     

       58
       58
       +
       

     

       59
       59
       +
       ```ShellSession

     

       60
       60
       +
       # nix-channel --add https://nixos.org/channels/nixos-21.05 nixos

     

       61
       61
       +
       ```

     

       62
       62
       +
       

     

       63
       63
       +
       If you have a server, you may want to use the "small" channel instead:

     

       64
       64
       +
       

     

       65
       65
       +
       ```ShellSession

     

       66
       66
       +
       # nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos

     

       67
       67
       +
       ```

     

       68
       68
       +
       

     

       69
       69
       +
       And if you want to live on the bleeding edge:

     

       70
       70
       +
       

     

       71
       71
       +
       ```ShellSession

     

       72
       72
       +
       # nix-channel --add https://nixos.org/channels/nixos-unstable nixos

     

       73
       73
       +
       ```

     

       74
       74
       +
       

     

       75
       75
       +
       You can then upgrade NixOS to the latest version in your chosen channel

     

       76
       76
       +
       by running

     

       77
       77
       +
       

     

       78
       78
       +
       ```ShellSession

     

       79
       79
       +
       # nixos-rebuild switch --upgrade

     

       80
       80
       +
       ```

     

       81
       81
       +
       

     

       82
       82
       +
       which is equivalent to the more verbose `nix-channel --update nixos; nixos-rebuild switch`.

     

       83
       83
       +
       

     

       84
       84
       +
       ::: {.note}

     

       85
       85
       +
       Channels are set per user. This means that running `nix-channel --add`

     

       86
       86
       +
       as a non root user (or without sudo) will not affect

     

       87
       87
       +
       configuration in `/etc/nixos/configuration.nix`

     

       88
       88
       +
       :::

     

       89
       89
       +
       

     

       90
       90
       +
       ::: {.warning}

     

       91
       91
       +
       It is generally safe to switch back and forth between channels. The only

     

       92
       92
       +
       exception is that a newer NixOS may also have a newer Nix version, which

     

       93
       93
       +
       may involve an upgrade of Nix's database schema. This cannot be undone

     

       94
       94
       +
       easily, so in that case you will not be able to go back to your original

     

       95
       95
       +
       channel.

     

       96
       96
       +
       :::

     

       97
       97
       +
       

     

       98
       98
       +
       ## Automatic Upgrades {#sec-upgrading-automatic}

     

       99
       99
       +
       

     

       100
       100
       +
       You can keep a NixOS system up-to-date automatically by adding the

     

       101
       101
       +
       following to `configuration.nix`:

     

       102
       102
       +
       

     

       103
       103
       +
       ```nix

     

       104
       104
       +
       system.autoUpgrade.enable = true;

     

       105
       105
       +
       system.autoUpgrade.allowReboot = true;

     

       106
       106
       +
       ```

     

       107
       107
       +
       

     

       108
       108
       +
       This enables a periodically executed systemd service named

     

       109
       109
       +
       `nixos-upgrade.service`. If the `allowReboot` option is `false`, it runs

     

       110
       110
       +
       `nixos-rebuild switch --upgrade` to upgrade NixOS to the latest version

     

       111
       111
       +
       in the current channel. (To see when the service runs, see `systemctl list-timers`.)

     

       112
       112
       +
       If `allowReboot` is `true`, then the system will automatically reboot if

     

       113
       113
       +
       the new generation contains a different kernel, initrd or kernel

     

       114
       114
       +
       modules. You can also specify a channel explicitly, e.g.

     

       115
       115
       +
       

     

       116
       116
       +
       ```nix

     

       117
       117
       +
       system.autoUpgrade.channel = https://nixos.org/channels/nixos-21.05;

     

       118
       118
       +
       ```

-139

nixos/doc/manual/installation/upgrading.xml

···

       1
       1
       -
       <chapter xmlns="http://docbook.org/ns/docbook"

     

       2
       2
       -
                xmlns:xlink="http://www.w3.org/1999/xlink"

     

       3
       3
       -
                version="5.0"

     

       4
       4
       -
                xml:id="sec-upgrading">

     

       5
       5
       -
        <title>Upgrading NixOS</title>

     

       6
       6
       -
        <para>

     

       7
       7
       -
         The best way to keep your NixOS installation up to date is to use one of the

     

       8
       8
       -
         NixOS <emphasis>channels</emphasis>. A channel is a Nix mechanism for

     

       9
       9
       -
         distributing Nix expressions and associated binaries. The NixOS channels are

     

       10
       10
       -
         updated automatically from NixOS’s Git repository after certain tests have

     

       11
       11
       -
         passed and all packages have been built. These channels are:

     

       12
       12
       -
         <itemizedlist>

     

       13
       13
       -
          <listitem>

     

       14
       14
       -
           <para>

     

       15
       15
       -
            <emphasis>Stable channels</emphasis>, such as

     

       16
       16
       -
            <literal

     

       17
       17
       -
           xlink:href="https://nixos.org/channels/nixos-21.05">nixos-21.05</literal>.

     

       18
       18
       -
            These only get conservative bug fixes and package upgrades. For instance,

     

       19
       19
       -
            a channel update may cause the Linux kernel on your system to be upgraded

     

       20
       20
       -
            from 4.19.34 to 4.19.38 (a minor bug fix), but not from

     

       21
       21
       -
            4.19.<replaceable>x</replaceable> to 4.20.<replaceable>x</replaceable> (a

     

       22
       22
       -
            major change that has the potential to break things). Stable channels are

     

       23
       23
       -
            generally maintained until the next stable branch is created.

     

       24
       24
       -
           </para>

     

       25
       25
       -
           <para></para>

     

       26
       26
       -
          </listitem>

     

       27
       27
       -
          <listitem>

     

       28
       28
       -
           <para>

     

       29
       29
       -
            The <emphasis>unstable channel</emphasis>,

     

       30
       30
       -
            <literal

     

       31
       31
       -
           xlink:href="https://nixos.org/channels/nixos-unstable">nixos-unstable</literal>.

     

       32
       32
       -
            This corresponds to NixOS’s main development branch, and may thus see

     

       33
       33
       -
            radical changes between channel updates. It’s not recommended for

     

       34
       34
       -
            production systems.

     

       35
       35
       -
           </para>

     

       36
       36
       -
          </listitem>

     

       37
       37
       -
          <listitem>

     

       38
       38
       -
           <para>

     

       39
       39
       -
            <emphasis>Small channels</emphasis>, such as

     

       40
       40
       -
            <literal

     

       41
       41
       -
           xlink:href="https://nixos.org/channels/nixos-21.05-small">nixos-21.05-small</literal>

     

       42
       42
       -
            or

     

       43
       43
       -
            <literal

     

       44
       44
       -
           xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>.

     

       45
       45
       -
            These are identical to the stable and unstable channels described above,

     

       46
       46
       -
            except that they contain fewer binary packages. This means they get

     

       47
       47
       -
            updated faster than the regular channels (for instance, when a critical

     

       48
       48
       -
            security patch is committed to NixOS’s source tree), but may require

     

       49
       49
       -
            more packages to be built from source than usual. They’re mostly

     

       50
       50
       -
            intended for server environments and as such contain few GUI applications.

     

       51
       51
       -
           </para>

     

       52
       52
       -
          </listitem>

     

       53
       53
       -
         </itemizedlist>

     

       54
       54
       -
         To see what channels are available, go to

     

       55
       55
       -
         <link xlink:href="https://nixos.org/channels"/>. (Note that the URIs of the

     

       56
       56
       -
         various channels redirect to a directory that contains the channel’s latest

     

       57
       57
       -
         version and includes ISO images and VirtualBox appliances.) Please note that

     

       58
       58
       -
         during the release process, channels that are not yet released will be

     

       59
       59
       -
         present here as well. See the Getting NixOS page

     

       60
       60
       -
         <link xlink:href="https://nixos.org/nixos/download.html"/> to find the newest

     

       61
       61
       -
         supported stable release.

     

       62
       62
       -
        </para>

     

       63
       63
       -
        <para>

     

       64
       64
       -
         When you first install NixOS, you’re automatically subscribed to the NixOS

     

       65
       65
       -
         channel that corresponds to your installation source. For instance, if you

     

       66
       66
       -
         installed from a 21.05 ISO, you will be subscribed to the

     

       67
       67
       -
         <literal>nixos-21.05</literal> channel. To see which NixOS channel you’re

     

       68
       68
       -
         subscribed to, run the following as root:

     

       69
       69
       -
       <screen>

     

       70
       70
       -
       <prompt># </prompt>nix-channel --list | grep nixos

     

       71
       71
       -
       nixos https://nixos.org/channels/nixos-unstable

     

       72
       72
       -
       </screen>

     

       73
       73
       -
         To switch to a different NixOS channel, do

     

       74
       74
       -
       <screen>

     

       75
       75
       -
       <prompt># </prompt>nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos

     

       76
       76
       -
       </screen>

     

       77
       77
       -
         (Be sure to include the <literal>nixos</literal> parameter at the end.) For

     

       78
       78
       -
         instance, to use the NixOS 21.05 stable channel:

     

       79
       79
       -
       <screen>

     

       80
       80
       -
       <prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-21.05 nixos

     

       81
       81
       -
       </screen>

     

       82
       82
       -
         If you have a server, you may want to use the “small” channel instead:

     

       83
       83
       -
       <screen>

     

       84
       84
       -
       <prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-21.05-small nixos

     

       85
       85
       -
       </screen>

     

       86
       86
       -
         And if you want to live on the bleeding edge:

     

       87
       87
       -
       <screen>

     

       88
       88
       -
       <prompt># </prompt>nix-channel --add https://nixos.org/channels/nixos-unstable nixos

     

       89
       89
       -
       </screen>

     

       90
       90
       -
        </para>

     

       91
       91
       -
        <para>

     

       92
       92
       -
         You can then upgrade NixOS to the latest version in your chosen channel by

     

       93
       93
       -
         running

     

       94
       94
       -
       <screen>

     

       95
       95
       -
       <prompt># </prompt>nixos-rebuild switch --upgrade

     

       96
       96
       -
       </screen>

     

       97
       97
       -
         which is equivalent to the more verbose <literal>nix-channel --update nixos;

     

       98
       98
       -
         nixos-rebuild switch</literal>.

     

       99
       99
       -
        </para>

     

       100
       100
       -
        <note>

     

       101
       101
       -
         <para>

     

       102
       102
       -
          Channels are set per user. This means that running <literal> nix-channel

     

       103
       103
       -
          --add</literal> as a non root user (or without sudo) will not affect

     

       104
       104
       -
          configuration in <literal>/etc/nixos/configuration.nix</literal>

     

       105
       105
       -
         </para>

     

       106
       106
       -
        </note>

     

       107
       107
       -
        <warning>

     

       108
       108
       -
         <para>

     

       109
       109
       -
          It is generally safe to switch back and forth between channels. The only

     

       110
       110
       -
          exception is that a newer NixOS may also have a newer Nix version, which may

     

       111
       111
       -
          involve an upgrade of Nix’s database schema. This cannot be undone easily,

     

       112
       112
       -
          so in that case you will not be able to go back to your original channel.

     

       113
       113
       -
         </para>

     

       114
       114
       -
        </warning>

     

       115
       115
       -
        <section xml:id="sec-upgrading-automatic">

     

       116
       116
       -
         <title>Automatic Upgrades</title>

     

       117
       117
       -
       

     

       118
       118
       -
         <para>

     

       119
       119
       -
          You can keep a NixOS system up-to-date automatically by adding the following

     

       120
       120
       -
          to <filename>configuration.nix</filename>:

     

       121
       121
       -
       <programlisting>

     

       122
       122
       -
       <xref linkend="opt-system.autoUpgrade.enable"/> = true;

     

       123
       123
       -
       <xref linkend="opt-system.autoUpgrade.allowReboot"/> = true;

     

       124
       124
       -
       </programlisting>

     

       125
       125
       -
          This enables a periodically executed systemd service named

     

       126
       126
       -
          <literal>nixos-upgrade.service</literal>. If the <literal>allowReboot</literal>

     

       127
       127
       -
          option is <literal>false</literal>, it runs <command>nixos-rebuild switch

     

       128
       128
       -
          --upgrade</command> to upgrade NixOS to the latest version in the current

     

       129
       129
       -
          channel. (To see when the service runs, see <command>systemctl list-timers</command>.)

     

       130
       130
       -
          If <literal>allowReboot</literal> is <literal>true</literal>, then the

     

       131
       131
       -
          system will automatically reboot if the new generation contains a different

     

       132
       132
       -
          kernel, initrd or kernel modules.

     

       133
       133
       -
          You can also specify a channel explicitly, e.g.

     

       134
       134
       -
       <programlisting>

     

       135
       135
       -
       <xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-21.05;

     

       136
       136
       -
       </programlisting>

     

       137
       137
       -
         </para>

     

       138
       138
       -
        </section>

     

       139
       139
       -
       </chapter>