From 93c5a267413cb9ab42e03f5cff8d0c893450fdb6 Mon Sep 17 00:00:00 2001 From: Arnout Engelen Date: Sun, 13 Dec 2020 20:56:54 +0100 Subject: [PATCH] nixos-manual: start gradual conversion to markdown Basically copied from the nixpkgs manual infrastructure. Converted 'installation/upgrading' as a test. I guess we should find a way to represent the 'xref linkend' links to 'proper' markdown as well --- nixos/doc/manual/Makefile | 13 +- nixos/doc/manual/installation/upgrading.md | 61 +++++++++ nixos/doc/manual/installation/upgrading.xml | 139 -------------------- nixos/doc/manual/shell.nix | 2 +- 4 files changed, 73 insertions(+), 142 deletions(-) create mode 100644 nixos/doc/manual/installation/upgrading.md delete mode 100644 nixos/doc/manual/installation/upgrading.xml diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile index b86a76005753e..69cb6a0e58e92 100644 --- a/nixos/doc/manual/Makefile +++ b/nixos/doc/manual/Makefile @@ -1,10 +1,12 @@ +MD_TARGETS=$(addsuffix .xml, $(basename $(shell find . -type f -regex '.*\.md$$'))) + .PHONY: all all: manual-combined.xml format .PHONY: debug debug: generated manual-combined.xml -manual-combined.xml: generated *.xml **/*.xml +manual-combined.xml: generated *.xml **/*.xml ${MD_TARGETS} rm -f ./manual-combined.xml nix-shell --pure -Q --packages xmloscopy \ --run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml" @@ -22,9 +24,16 @@ fix-misc-xml: .PHONY: clean clean: - rm -f manual-combined.xml generated + rm -f ${MD_TARGETS} manual-combined.xml generated generated: nix-build ../../release.nix \ --attr manualGeneratedSources.x86_64-linux \ --out-link ./generated + +%.xml: %.md + pandoc $^ -t docbook \ + --top-level-division=chapter \ + --extract-media=media \ + -f markdown+smart \ + > $@ diff --git a/nixos/doc/manual/installation/upgrading.md b/nixos/doc/manual/installation/upgrading.md new file mode 100644 index 0000000000000..4eab6d8eb4d7d --- /dev/null +++ b/nixos/doc/manual/installation/upgrading.md @@ -0,0 +1,61 @@ +# 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-20.09`. 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.\ to 4.20.\ (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`. 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-20.09-small` or `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 . (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 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 20.09 ISO, you will be subscribed to the `nixos-20.09` channel. To see which NixOS channel you're subscribed to, run the following as root: + + # nix-channel --list | grep nixos + nixos https://nixos.org/channels/nixos-unstable + +To switch to a different NixOS channel, do + + # 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 20.09 stable channel: + + # nix-channel --add https://nixos.org/channels/nixos-20.09 nixos + +If you have a server, you may want to use the "small" channel instead: + + # nix-channel --add https://nixos.org/channels/nixos-20.09-small nixos + +And if you want to live on the bleeding edge: + + # 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 + + # 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`: + +```{=docbook} + + = true; + = 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. + +```{=docbook} + + = https://nixos.org/channels/nixos-20.09; + +``` diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml deleted file mode 100644 index 15ba5db9a37be..0000000000000 --- a/nixos/doc/manual/installation/upgrading.xml +++ /dev/null @@ -1,139 +0,0 @@ - - Upgrading NixOS - - 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-20.09. - 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. - 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-20.09-small - or - 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 - . (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 - 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 20.09 ISO, you will be subscribed to the - nixos-20.09 channel. To see which NixOS channel you’re - subscribed to, run the following as root: - -# nix-channel --list | grep nixos -nixos https://nixos.org/channels/nixos-unstable - - To switch to a different NixOS channel, do - -# 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 20.09 stable channel: - -# nix-channel --add https://nixos.org/channels/nixos-20.09 nixos - - If you have a server, you may want to use the “small” channel instead: - -# nix-channel --add https://nixos.org/channels/nixos-20.09-small nixos - - And if you want to live on the bleeding edge: - -# 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 - -# nixos-rebuild switch --upgrade - - which is equivalent to the more verbose nix-channel --update nixos; - nixos-rebuild switch. - - - - 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 - - - - - 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 - - - You can keep a NixOS system up-to-date automatically by adding the following - to configuration.nix: - - = true; - = 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. - - = https://nixos.org/channels/nixos-20.09; - - -
- diff --git a/nixos/doc/manual/shell.nix b/nixos/doc/manual/shell.nix index cc3609d750e03..cb156fa8d468d 100644 --- a/nixos/doc/manual/shell.nix +++ b/nixos/doc/manual/shell.nix @@ -4,5 +4,5 @@ in pkgs.mkShell { name = "nixos-manual"; - buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby ]; + buildInputs = with pkgs; [ xmlformat jing xmloscopy ruby pandoc ]; }