diff options
| author | Vladimír Čunát <vcunat@gmail.com> | 2019-10-27 10:29:58 +0100 |
|---|---|---|
| committer | Vladimír Čunát <vcunat@gmail.com> | 2019-10-27 10:29:58 +0100 |
| commit | d9c5d584cd027f3a7aa43f8fbc261bb19114f02b (patch) | |
| tree | ff034b35b03a00587f691d9121b23cb5a4bc7d91 /nixos/doc | |
| parent | 4f43e5fe886374ec918da4bf494710cd58c4adf7 (diff) | |
| parent | 2896f00181b6dd11c3075bfc5706f02beec1e9e3 (diff) | |
| download | nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar.gz nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar.bz2 nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar.lz nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar.xz nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.tar.zst nixpkgs-d9c5d584cd027f3a7aa43f8fbc261bb19114f02b.zip | |
Merge branch 'master' into release-docs
It's been a very long time, so I think a merge will be better than a rebase. There was only one simple conflict.
Diffstat (limited to 'nixos/doc')
79 files changed, 3154 insertions, 865 deletions
diff --git a/nixos/doc/manual/Makefile b/nixos/doc/manual/Makefile index b251a1f5e2c..b86a7600575 100644 --- a/nixos/doc/manual/Makefile +++ b/nixos/doc/manual/Makefile @@ -6,13 +6,14 @@ debug: generated manual-combined.xml manual-combined.xml: generated *.xml **/*.xml rm -f ./manual-combined.xml - nix-shell --packages xmloscopy \ + nix-shell --pure -Q --packages xmloscopy \ --run "xmloscopy --docbook5 ./manual.xml ./manual-combined.xml" .PHONY: format format: - find ../../ -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \ - xmlformat --config-file "../xmlformat.conf" -i {} + nix-shell --pure -Q --packages xmlformat \ + --run "find ../../ -iname '*.xml' -type f -print0 | xargs -0 -I{} -n1 \ + xmlformat --config-file '../xmlformat.conf' -i {}" .PHONY: fix-misc-xml fix-misc-xml: @@ -23,7 +24,7 @@ fix-misc-xml: clean: rm -f manual-combined.xml generated -generated: ./options-to-docbook.xsl +generated: nix-build ../../release.nix \ --attr manualGeneratedSources.x86_64-linux \ --out-link ./generated diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml index f078b8c3ba3..526803e429b 100644 --- a/nixos/doc/manual/administration/cleaning-store.xml +++ b/nixos/doc/manual/administration/cleaning-store.xml @@ -11,12 +11,12 @@ Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced packages. This is easy: <screen> -$ nix-collect-garbage +<prompt>$ </prompt>nix-collect-garbage </screen> Alternatively, you can use a systemd unit that does the same in the background: <screen> -# systemctl start nix-gc.service +<prompt># </prompt>systemctl start nix-gc.service </screen> You can tell NixOS in <filename>configuration.nix</filename> to run this unit automatically at certain points in time, for instance, every night at 03:15: @@ -31,11 +31,11 @@ $ nix-collect-garbage configurations. The following command deletes old roots, removing the ability to roll back to them: <screen> -$ nix-collect-garbage -d +<prompt>$ </prompt>nix-collect-garbage -d </screen> You can also do this for specific profiles, e.g. <screen> -$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old +<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old </screen> Note that NixOS system configurations are stored in the profile <filename>/nix/var/nix/profiles/system</filename>. @@ -45,7 +45,7 @@ $ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations o Nix store) is to run Nix’s store optimiser, which seeks out identical files in the store and replaces them with hard links to a single copy. <screen> -$ nix-store --optimise +<prompt>$ </prompt>nix-store --optimise </screen> Since this command needs to read the entire Nix store, it can take quite a while to finish. diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml index 4b977d1d82e..42486f01fe8 100644 --- a/nixos/doc/manual/administration/container-networking.xml +++ b/nixos/doc/manual/administration/container-networking.xml @@ -11,10 +11,10 @@ <literal>10.233.0.0/16</literal>. You can get the container’s IPv4 address as follows: <screen> -# nixos-container show-ip foo +<prompt># </prompt>nixos-container show-ip foo 10.233.4.2 -$ ping -c1 10.233.4.2 +<prompt>$ </prompt>ping -c1 10.233.4.2 64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms </screen> </para> @@ -52,4 +52,8 @@ $ ping -c1 10.233.4.2 networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; </programlisting> </para> + + <para> + You may need to restart your system for the changes to take effect. + </para> </section> diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml index bb8b7f83d9e..16d03cc0d1a 100644 --- a/nixos/doc/manual/administration/control-groups.xml +++ b/nixos/doc/manual/administration/control-groups.xml @@ -16,7 +16,7 @@ <literal>systemd</literal> hierarchy, which is what systemd uses to keep track of the processes belonging to each service or user session: <screen> -$ systemd-cgls +<prompt>$ </prompt>systemd-cgls ├─user │ └─eelco │ └─c1 diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml index 2a98fb12623..d03dbc4d705 100644 --- a/nixos/doc/manual/administration/declarative-containers.xml +++ b/nixos/doc/manual/administration/declarative-containers.xml @@ -15,7 +15,7 @@ containers.database = { config = { config, pkgs, ... }: { <xref linkend="opt-services.postgresql.enable"/> = true; - <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql96; + <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_6; }; }; </programlisting> diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml index fa380477f6c..7ded0c11786 100644 --- a/nixos/doc/manual/administration/imperative-containers.xml +++ b/nixos/doc/manual/administration/imperative-containers.xml @@ -30,6 +30,13 @@ <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; ' </screen> + By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen + as container IP. This behavior can be altered by setting <literal>--host-address</literal> and + <literal>--local-address</literal>: +<screen> +# nixos-container create test --config-file test-container.nix \ + --local-address 10.235.1.2 --host-address 10.235.1.1 +</screen> </para> <para> @@ -73,7 +80,8 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux </para> <para> - To change the configuration of the container, you can edit + There are several ways to change the configuration of the container. First, + on the host, you can edit <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>, and run <screen> @@ -86,7 +94,8 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux <xref linkend="opt-services.httpd.enable"/> = true; <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org"; <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ]; - ' +' + # curl http://$(nixos-container show-ip foo)/ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… </screen> @@ -95,13 +104,11 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux </para> <para> - Note that in previous versions of NixOS (17.09 and earlier) one could also - use all nix-related commands (like <command>nixos-rebuild switch</command>) - from inside the container. However, since the release of Nix 2.0 this is not - supported anymore. Supporting Nix commands inside the container might be - possible again in future versions. See - <link xlink:href="https://github.com/NixOS/nixpkgs/issues/40355">the github - issue</link> for tracking progress on this issue. + Alternatively, you can change the configuration from within the container + itself by running <command>nixos-rebuild switch</command> inside the + container. Note that the container by default does not have a copy of the + NixOS channel, so you should run <command>nix-channel --update</command> + first. </para> <para> diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml index a41936b373d..da4877fcdf0 100644 --- a/nixos/doc/manual/administration/logging.xml +++ b/nixos/doc/manual/administration/logging.xml @@ -11,14 +11,14 @@ The command <literal>journalctl</literal> allows you to see the contents of the journal. For example, <screen> -$ journalctl -b +<prompt>$ </prompt>journalctl -b </screen> shows all journal entries since the last reboot. (The output of <command>journalctl</command> is piped into <command>less</command> by default.) You can use various options and match operators to restrict output to messages of interest. For instance, to get all messages from PostgreSQL: <screen> -$ journalctl -u postgresql.service +<prompt>$ </prompt>journalctl -u postgresql.service -- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. -- ... Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down @@ -29,7 +29,7 @@ Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to Or to get all messages since the last reboot that have at least a “critical” severity level: <screen> -$ journalctl -b -p crit +<prompt>$ </prompt>journalctl -b -p crit Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1) </screen> diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml index 07c6acaa469..fb87810ba46 100644 --- a/nixos/doc/manual/administration/rollback.xml +++ b/nixos/doc/manual/administration/rollback.xml @@ -33,7 +33,7 @@ where <replaceable>N</replaceable> is the number of the NixOS system configuration. To get a list of the available configurations, do: <screen> -$ ls -l /nix/var/nix/profiles/system-*-link +<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link <replaceable>...</replaceable> lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 </screen> diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 786dd5e2390..19bec1f7794 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-running"> <title>Administration</title> - <partintro> + <partintro xml:id="ch-running-intro"> <para> This chapter describes various aspects of managing a running NixOS system, such as how to use the <command>systemd</command> service manager. diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml index 0c2085c8155..1b9c745eb59 100644 --- a/nixos/doc/manual/administration/service-mgmt.xml +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -21,7 +21,7 @@ <command>systemd</command>. Without any arguments, it shows the status of active units: <screen> -$ systemctl +<prompt>$ </prompt>systemctl -.mount loaded active mounted / swapfile.swap loaded active active /swapfile sshd.service loaded active running SSH Daemon @@ -33,7 +33,7 @@ graphical.target loaded active active Graphical Interface You can ask for detailed status information about a unit, for instance, the PostgreSQL database service: <screen> -$ systemctl status postgresql.service +<prompt>$ </prompt>systemctl status postgresql.service postgresql.service - PostgreSQL Server Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service) Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml index a4ca3b651e2..b9d11152d5e 100644 --- a/nixos/doc/manual/administration/store-corruption.xml +++ b/nixos/doc/manual/administration/store-corruption.xml @@ -18,7 +18,7 @@ If the corruption is in a path in the closure of the NixOS system configuration, you can fix it by doing <screen> -# nixos-rebuild switch --repair +<prompt># </prompt>nixos-rebuild switch --repair </screen> This will cause Nix to check every path in the closure, and if its cryptographic hash differs from the hash recorded in Nix’s database, the @@ -28,7 +28,7 @@ <para> You can also scan the entire Nix store for corrupt paths: <screen> -# nix-store --verify --check-contents --repair +<prompt># </prompt>nix-store --verify --check-contents --repair </screen> Any corrupt paths will be redownloaded if they’re available in a binary cache; otherwise, they cannot be repaired. diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml index 1d95cfb22b6..80daf6bdbff 100644 --- a/nixos/doc/manual/administration/user-sessions.xml +++ b/nixos/doc/manual/administration/user-sessions.xml @@ -10,7 +10,7 @@ allows querying and manipulating user sessions. For instance, to list all user sessions: <screen> -$ loginctl +<prompt>$ </prompt>loginctl SESSION UID USER SEAT c1 500 eelco seat0 c3 0 root seat0 @@ -21,7 +21,7 @@ $ loginctl devices attached to the system; usually, there is only one seat.) To get information about a session: <screen> -$ loginctl session-status c3 +<prompt>$ </prompt>loginctl session-status c3 c3 - root (0) Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago Leader: 2536 (login) diff --git a/nixos/doc/manual/configuration/ad-hoc-packages.xml b/nixos/doc/manual/configuration/ad-hoc-packages.xml index 19159d8db5b..c7e882d846f 100644 --- a/nixos/doc/manual/configuration/ad-hoc-packages.xml +++ b/nixos/doc/manual/configuration/ad-hoc-packages.xml @@ -9,7 +9,7 @@ With the command <command>nix-env</command>, you can install and uninstall packages from the command line. For instance, to install Mozilla Thunderbird: <screen> -$ nix-env -iA nixos.thunderbird</screen> +<prompt>$ </prompt>nix-env -iA nixos.thunderbird</screen> If you invoke this as root, the package is installed in the Nix profile <filename>/nix/var/nix/profiles/default</filename> and visible to all users of the system; otherwise, the package ends up in @@ -25,7 +25,7 @@ $ nix-env -iA nixos.thunderbird</screen> Packages come from the NixOS channel. You typically upgrade a package by updating to the latest version of the NixOS channel: <screen> -$ nix-channel --update nixos +<prompt>$ </prompt>nix-channel --update nixos </screen> and then running <literal>nix-env -i</literal> again. Other packages in the profile are <emphasis>not</emphasis> affected; this is the crucial difference @@ -34,21 +34,21 @@ $ nix-channel --update nixos their current versions in the NixOS channel. You can however upgrade all packages for which there is a newer version by doing: <screen> -$ nix-env -u '*' +<prompt>$ </prompt>nix-env -u '*' </screen> </para> <para> A package can be uninstalled using the <option>-e</option> flag: <screen> -$ nix-env -e thunderbird +<prompt>$ </prompt>nix-env -e thunderbird </screen> </para> <para> Finally, you can roll back an undesirable <command>nix-env</command> action: <screen> -$ nix-env --rollback +<prompt>$ </prompt>nix-env --rollback </screen> </para> diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml index 028a9427534..182641055e4 100644 --- a/nixos/doc/manual/configuration/adding-custom-packages.xml +++ b/nixos/doc/manual/configuration/adding-custom-packages.xml @@ -14,8 +14,8 @@ xlink:href="http://nixos.org/nixpkgs/manual">Nixpkgs manual</link>. In short, you clone Nixpkgs: <screen> -$ git clone https://github.com/NixOS/nixpkgs -$ cd nixpkgs +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs +<prompt>$ </prompt>cd nixpkgs </screen> Then you write and test the package as described in the Nixpkgs manual. Finally, you add it to <literal>environment.systemPackages</literal>, e.g. @@ -31,7 +31,7 @@ $ cd nixpkgs <para> The second possibility is to add the package outside of the Nixpkgs tree. For instance, here is how you specify a build of the - <link xlink:href="http://www.gnu.org/software/hello/">GNU Hello</link> + <link xlink:href="https://www.gnu.org/software/hello/">GNU Hello</link> package directly in <filename>configuration.nix</filename>: <programlisting> <xref linkend="opt-environment.systemPackages"/> = @@ -65,8 +65,8 @@ stdenv.mkDerivation rec { </programlisting> This allows testing the package easily: <screen> -$ nix-build my-hello.nix -$ ./result/bin/hello +<prompt>$ </prompt>nix-build my-hello.nix +<prompt>$ </prompt>./result/bin/hello Hello, world! </screen> </para> diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml index 8a1a39c98c1..eadafb94b8f 100644 --- a/nixos/doc/manual/configuration/config-file.xml +++ b/nixos/doc/manual/configuration/config-file.xml @@ -197,11 +197,12 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ]; pkgs.emacs ]; -<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90; +<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_10; </programlisting> The latter option definition changes the default PostgreSQL package used - by NixOS’s PostgreSQL service to 9.0. For more information on packages, - including how to add new ones, see <xref linkend="sec-custom-packages"/>. + by NixOS’s PostgreSQL service to 10.x. For more information on + packages, including how to add new ones, see + <xref linkend="sec-custom-packages"/>. </para> </listitem> </varlistentry> diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index 8d05dcd34b4..5961209bc13 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-configuration"> <title>Configuration</title> - <partintro> + <partintro xml:id="ch-configuration-intro"> <para> This chapter describes how to configure various aspects of a NixOS machine through the configuration file @@ -21,6 +21,9 @@ <xi:include href="xfce.xml" /> <xi:include href="networking.xml" /> <xi:include href="linux-kernel.xml" /> + <xi:include href="matrix.xml" /> <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" /> + <xi:include href="profiles.xml" /> + <xi:include href="kubernetes.xml" /> <!-- Apache; libvirtd virtualisation --> </part> diff --git a/nixos/doc/manual/configuration/customizing-packages.xml b/nixos/doc/manual/configuration/customizing-packages.xml index 03b5bb53197..34e6ab4b24d 100644 --- a/nixos/doc/manual/configuration/customizing-packages.xml +++ b/nixos/doc/manual/configuration/customizing-packages.xml @@ -24,8 +24,8 @@ <para> Apart from high-level options, it’s possible to tweak a package in almost arbitrary ways, such as changing or disabling dependencies of a package. For - instance, the Emacs package in Nixpkgs by default has a dependency on GTK+ 2. - If you want to build it against GTK+ 3, you can specify that as follows: + instance, the Emacs package in Nixpkgs by default has a dependency on GTK 2. + If you want to build it against GTK 3, you can specify that as follows: <programlisting> <xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ]; </programlisting> @@ -33,7 +33,7 @@ function that produces Emacs, with the original arguments amended by the set of arguments specified by you. So here the function argument <varname>gtk</varname> gets the value <literal>pkgs.gtk3</literal>, causing - Emacs to depend on GTK+ 3. (The parentheses are necessary because in Nix, + Emacs to depend on GTK 3. (The parentheses are necessary because in Nix, function application binds more weakly than list construction, so without them, <xref linkend="opt-environment.systemPackages"/> would be a list with two elements.) diff --git a/nixos/doc/manual/configuration/declarative-packages.xml b/nixos/doc/manual/configuration/declarative-packages.xml index be9884fe9dc..5fb3bcb9f8f 100644 --- a/nixos/doc/manual/configuration/declarative-packages.xml +++ b/nixos/doc/manual/configuration/declarative-packages.xml @@ -22,13 +22,18 @@ <para> You can get a list of the available packages as follows: <screen> -$ nix-env -qaP '*' --description +<prompt>$ </prompt>nix-env -qaP '*' --description nixos.firefox firefox-23.0 Mozilla Firefox - the browser, reloaded <replaceable>...</replaceable> </screen> The first column in the output is the <emphasis>attribute name</emphasis>, - such as <literal>nixos.thunderbird</literal>. (The <literal>nixos</literal> - prefix allows distinguishing between different channels that you might have.) + such as <literal>nixos.thunderbird</literal>. + </para> + <para> + Note: the <literal>nixos</literal> prefix tells us that we want to get the + package from the <literal>nixos</literal> channel and works only in CLI tools. + + In declarative configuration use <literal>pkgs</literal> prefix (variable). </para> <para> diff --git a/nixos/doc/manual/configuration/firewall.xml b/nixos/doc/manual/configuration/firewall.xml index b66adcedce6..47a19ac82c0 100644 --- a/nixos/doc/manual/configuration/firewall.xml +++ b/nixos/doc/manual/configuration/firewall.xml @@ -34,13 +34,4 @@ Similarly, UDP port ranges can be opened through <xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>. </para> - - <para> - Also of interest is -<programlisting> -<xref linkend="opt-networking.firewall.allowPing"/> = true; -</programlisting> - to allow the machine to respond to ping requests. (ICMPv6 pings are always - allowed.) - </para> </section> diff --git a/nixos/doc/manual/configuration/ipv6-config.xml b/nixos/doc/manual/configuration/ipv6-config.xml index e9ab7cce4eb..675a5d9a260 100644 --- a/nixos/doc/manual/configuration/ipv6-config.xml +++ b/nixos/doc/manual/configuration/ipv6-config.xml @@ -39,7 +39,7 @@ <xref linkend="opt-networking.defaultGateway6"/> = { address = "fe00::1"; interface = "enp0s3"; -} +}; </programlisting> </para> diff --git a/nixos/doc/manual/configuration/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml new file mode 100644 index 00000000000..54a100e4479 --- /dev/null +++ b/nixos/doc/manual/configuration/kubernetes.xml @@ -0,0 +1,112 @@ +<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-kubernetes"> + <title>Kubernetes</title> + <para> + The NixOS Kubernetes module is a collective term for a handful of individual + submodules implementing the Kubernetes cluster components. + </para> + <para> + There are generally two ways of enabling Kubernetes on NixOS. One way is to + enable and configure cluster components appropriately by hand: +<programlisting> +services.kubernetes = { + apiserver.enable = true; + controllerManager.enable = true; + scheduler.enable = true; + addonManager.enable = true; + proxy.enable = true; + flannel.enable = true; +}; +</programlisting> + Another way is to assign cluster roles ("master" and/or "node") to the host. + This enables apiserver, controllerManager, scheduler, addonManager, + kube-proxy and etcd: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ]; +</programlisting> + While this will enable the kubelet and kube-proxy only: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ]; +</programlisting> + Assigning both the master and node roles is usable if you want a single node + Kubernetes cluster for dev or testing purposes: +<programlisting> +<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ]; +</programlisting> + Note: Assigning either role will also default both + <xref linkend="opt-services.kubernetes.flannel.enable"/> and + <xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up + flannel as CNI and activates automatic PKI bootstrapping. + </para> + <para> + As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports + on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have + been disabled by default. While opening insecure ports is still possible, it + is recommended not to bind these to other interfaces than loopback. To + re-enable the insecure port on the apiserver, see options: + <xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and + <xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/> + </para> + <note> + <para> + As of NixOS 19.03, it is mandatory to configure: + <xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress + must be resolveable and routeable by all cluster nodes. In single node + clusters, this can be set to <literal>localhost</literal>. + </para> + </note> + <para> + Role-based access control (RBAC) authorization mode is enabled by default. + This means that anonymous requests to the apiserver secure port will + expectedly cause a permission denied error. All cluster components must + therefore be configured with x509 certificates for two-way tls communication. + The x509 certificate subject section determines the roles and permissions + granted by the apiserver to perform clusterwide or namespaced operations. See + also: + <link + xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/"> + Using RBAC Authorization</link>. + </para> + <para> + The NixOS kubernetes module provides an option for automatic certificate + bootstrapping and configuration, + <xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping + process involves setting up a certificate authority (CA) daemon (cfssl) on + the kubernetes master node. cfssl generates a CA-cert for the cluster, and + uses the CA-cert for signing subordinate certs issued to each of the cluster + components. Subsequently, the certmgr daemon monitors active certificates and + renews them when needed. For single node Kubernetes clusters, setting + <xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and + no further action is required. For joining extra node machines to an existing + cluster on the other hand, establishing initial trust is mandatory. + </para> + <para> + To add new nodes to the cluster: On any (non-master) cluster node where + <xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper + script <literal>nixos-kubernetes-node-join</literal> is available on PATH. + Given a token on stdin, it will copy the token to the kubernetes secrets + directory and restart the certmgr service. As requested certificates are + issued, the script will restart kubernetes cluster components as needed for + them to pick up new keypairs. + </para> + <note> + <para> + Multi-master (HA) clusters are not supported by the easyCerts module. + </para> + </note> + <para> + In order to interact with an RBAC-enabled cluster as an administrator, one + needs to have cluster-admin privileges. By default, when easyCerts is + enabled, a cluster-admin kubeconfig file is generated and linked into + <literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by + <xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>. + <literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal> + will make kubectl use this kubeconfig to access and authenticate the cluster. + The cluster-admin kubeconfig references an auto-generated keypair owned by + root. Thus, only root on the kubernetes master may obtain cluster-admin + rights by means of this file. + </para> +</chapter> diff --git a/nixos/doc/manual/configuration/matrix.xml b/nixos/doc/manual/configuration/matrix.xml new file mode 100644 index 00000000000..ef8d5cbda88 --- /dev/null +++ b/nixos/doc/manual/configuration/matrix.xml @@ -0,0 +1,203 @@ +<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="module-services-matrix"> + <title>Matrix</title> + <para> + <link xlink:href="https://matrix.org/">Matrix</link> is an open standard for + interoperable, decentralised, real-time communication over IP. It can be used + to power Instant Messaging, VoIP/WebRTC signalling, Internet of Things + communication - or anywhere you need a standard HTTP API for publishing and + subscribing to data whilst tracking the conversation history. + </para> + <para> + This chapter will show you how to set up your own, self-hosted Matrix + homeserver using the Synapse reference homeserver, and how to serve your own + copy of the Riot web client. See the + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> overview page for links to Riot Apps for Android and iOS, + desktop clients, as well as bridges to other networks and other projects + around Matrix. + </para> + <section xml:id="module-services-matrix-synapse"> + <title>Synapse Homeserver</title> + + <para> + <link xlink:href="https://github.com/matrix-org/synapse">Synapse</link> is + the reference homeserver implementation of Matrix from the core development + team at matrix.org. The following configuration example will set up a + synapse server for the <literal>example.org</literal> domain, served from + the host <literal>myhostname.example.org</literal>. For more information, + please refer to the + <link xlink:href="https://github.com/matrix-org/synapse#synapse-installation"> + installation instructions of Synapse </link>. +<programlisting> +let + fqdn = + let + join = hostName: domain: hostName + optionalString (domain != null) ".${domain}"; + in join config.networking.hostName config.networking.domain; +in { + networking = { + hostName = "myhostname"; + domain = "example.org"; + }; + networking.firewall.allowedTCPPorts = [ 80 443 ]; + + services.nginx = { + enable = true; + # only recommendedProxySettings and recommendedGzipSettings are strictly required, + # but the rest make sense as well + recommendedTlsSettings = true; + recommendedOptimisation = true; + recommendedGzipSettings = true; + recommendedProxySettings = true; + + virtualHosts = { + # This host section can be placed on a different host than the rest, + # i.e. to delegate from the host being accessible as ${config.networking.domain} + # to another host actually running the Matrix homeserver. + "${config.networking.domain}" = { + locations."= /.well-known/matrix/server".extraConfig = + let + # use 443 instead of the default 8448 port to unite + # the client-server and server-server port for simplicity + server = { "m.server" = "${fqdn}:443"; }; + in '' + add_header Content-Type application/json; + return 200 '${builtins.toJSON server}'; + ''; + locations."= /.well-known/matrix/client".extraConfig = + let + client = { + "m.homeserver" = { "base_url" = "https://${fqdn}"; }; + "m.identity_server" = { "base_url" = "https://vector.im"; }; + }; + # ACAO required to allow riot-web on any URL to request this json file + in '' + add_header Content-Type application/json; + add_header Access-Control-Allow-Origin *; + return 200 '${builtins.toJSON client}'; + ''; + }; + + # Reverse proxy for Matrix client-server and server-server communication + ${fqdn} = { + enableACME = true; + forceSSL = true; + + # Or do a redirect instead of the 404, or whatever is appropriate for you. + # But do not put a Matrix Web client here! See the Riot Web section below. + locations."/".extraConfig = '' + return 404; + ''; + + # forward all Matrix API calls to the synapse Matrix homeserver + locations."/_matrix" = { + proxyPass = "http://[::1]:8008"; # without a trailing / + }; + }; + }; + }; + services.matrix-synapse = { + enable = true; + server_name = config.networking.domain; + listeners = [ + { + port = 8008; + bind_address = "::1"; + type = "http"; + tls = false; + x_forwarded = true; + resources = [ + { names = [ "client" "federation" ]; compress = false; } + ]; + } + ]; + }; +}; +</programlisting> + </para> + + <para> + If the <code>A</code> and <code>AAAA</code> DNS records on + <literal>example.org</literal> do not point on the same host as the records + for <code>myhostname.example.org</code>, you can easily move the + <code>/.well-known</code> virtualHost section of the code to the host that + is serving <literal>example.org</literal>, while the rest stays on + <literal>myhostname.example.org</literal> with no other changes required. + This pattern also allows to seamlessly move the homeserver from + <literal>myhostname.example.org</literal> to + <literal>myotherhost.example.org</literal> by only changing the + <code>/.well-known</code> redirection target. + </para> + + <para> + If you want to run a server with public registration by anybody, you can + then enable <option>services.matrix-synapse.enable_registration = + true;</option>. Otherwise, or you can generate a registration secret with + <command>pwgen -s 64 1</command> and set it with + <option>services.matrix-synapse.registration_shared_secret</option>. To + create a new user or admin, run the following after you have set the secret + and have rebuilt NixOS: +<screen> +<prompt>$ </prompt>nix run nixpkgs.matrix-synapse +<prompt>$ </prompt>register_new_matrix_user -k <replaceable>your-registration-shared-secret</replaceable> http://localhost:8008 +<prompt>New user localpart: </prompt><replaceable>your-username</replaceable> +<prompt>Password:</prompt> +<prompt>Confirm password:</prompt> +<prompt>Make admin [no]:</prompt> +Success! +</screen> + In the example, this would create a user with the Matrix Identifier + <literal>@your-username:example.org</literal>. Note that the registration + secret ends up in the nix store and therefore is world-readable by any user + on your machine, so it makes sense to only temporarily activate the + <option>registration_shared_secret</option> option until a better solution + for NixOS is in place. + </para> + </section> + <section xml:id="module-services-matrix-riot-web"> + <title>Riot Web Client</title> + + <para> + <link xlink:href="https://github.com/vector-im/riot-web/">Riot Web</link> is + the reference web client for Matrix and developed by the core team at + matrix.org. The following snippet can be optionally added to the code before + to complete the synapse installation with a web client served at + <code>https://riot.myhostname.example.org</code> and + <code>https://riot.example.org</code>. Alternatively, you can use the hosted + copy at <link xlink:href="https://riot.im/app">https://riot.im/app</link>, + or use other web clients or native client applications. Due to the + <literal>/.well-known</literal> urls set up done above, many clients should + fill in the required connection details automatically when you enter your + Matrix Identifier. See + <link xlink:href="https://matrix.org/docs/projects/try-matrix-now.html">Try + Matrix Now!</link> for a list of existing clients and their supported + featureset. +<programlisting> +services.nginx.virtualHosts."riot.${fqdn}" = { + enableACME = true; + forceSSL = true; + serverAliases = [ + "riot.${config.networking.domain}" + ]; + + root = pkgs.riot-web; +}; +</programlisting> + </para> + + <para> + Note that the Riot developers do not recommend running Riot and your Matrix + homeserver on the same fully-qualified domain name for security reasons. In + the example, this means that you should not reuse the + <literal>myhostname.example.org</literal> virtualHost to also serve Riot, + but instead serve it on a different subdomain, like + <literal>riot.example.org</literal> in the example. See the + <link xlink:href="https://github.com/vector-im/riot-web#important-security-note">Riot + Important Security Notes</link> for more information on this subject. + </para> + </section> +</chapter> diff --git a/nixos/doc/manual/configuration/modularity.xml b/nixos/doc/manual/configuration/modularity.xml index 298ffd661f6..7ad0ae80a48 100644 --- a/nixos/doc/manual/configuration/modularity.xml +++ b/nixos/doc/manual/configuration/modularity.xml @@ -106,25 +106,40 @@ The unique option `services.httpd.adminAddr' is defined multiple times, in `/etc configuration option is. The command <option>nixos-option</option> allows you to find out: <screen> -$ nixos-option <xref linkend="opt-services.xserver.enable"/> +<prompt>$ </prompt>nixos-option <xref linkend="opt-services.xserver.enable"/> true -$ nixos-option <xref linkend="opt-boot.kernelModules"/> +<prompt>$ </prompt>nixos-option <xref linkend="opt-boot.kernelModules"/> [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ] </screen> - Interactive exploration of the configuration is possible using - <command -xlink:href="https://github.com/edolstra/nix-repl">nix-repl</command>, - a read-eval-print loop for Nix expressions. It’s not installed by default; - run <literal>nix-env -i nix-repl</literal> to get it. A typical use: + Interactive exploration of the configuration is possible using <command>nix + repl</command>, a read-eval-print loop for Nix expressions. A typical use: <screen> -$ nix-repl '<nixpkgs/nixos>' +<prompt>$ </prompt>nix repl '<nixpkgs/nixos>' -nix-repl> config.<xref linkend="opt-networking.hostName"/> +<prompt>nix-repl> </prompt>config.<xref linkend="opt-networking.hostName"/> "mandark" -nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/> +<prompt>nix-repl> </prompt>map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/> [ "example.org" "example.gov" ] </screen> </para> + + <para> + While abstracting your configuration, you may find it useful to generate + modules using code, instead of writing files. The example below would have + the same effect as importing a file which sets those options. +<programlisting> +{ config, pkgs, ... }: + +let netConfig = { hostName }: { + networking.hostName = hostName; + networking.useDHCP = false; +}; + +in + +{ imports = [ (netConfig "nixos.localdomain") ]; } +</programlisting> + </para> </section> diff --git a/nixos/doc/manual/configuration/profiles.xml b/nixos/doc/manual/configuration/profiles.xml new file mode 100644 index 00000000000..9d08f7f7bed --- /dev/null +++ b/nixos/doc/manual/configuration/profiles.xml @@ -0,0 +1,39 @@ +<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="ch-profiles"> + <title>Profiles</title> + <para> + In some cases, it may be desirable to take advantage of commonly-used, + predefined configurations provided by nixpkgs, but different from those that + come as default. This is a role fulfilled by NixOS's Profiles, which come as + files living in <filename><nixpkgs/nixos/modules/profiles></filename>. + That is to say, expected usage is to add them to the imports list of your + <filename>/etc/configuration.nix</filename> as such: + </para> +<programlisting> + imports = [ + <nixpkgs/nixos/modules/profiles/profile-name.nix> + ]; +</programlisting> + <para> + Even if some of these profiles seem only useful in the context of install + media, many are actually intended to be used in real installs. + </para> + <para> + What follows is a brief explanation on the purpose and use-case for each + profile. Detailing each option configured by each one is out of scope. + </para> + <xi:include href="profiles/all-hardware.xml" /> + <xi:include href="profiles/base.xml" /> + <xi:include href="profiles/clone-config.xml" /> + <xi:include href="profiles/demo.xml" /> + <xi:include href="profiles/docker-container.xml" /> + <xi:include href="profiles/graphical.xml" /> + <xi:include href="profiles/hardened.xml" /> + <xi:include href="profiles/headless.xml" /> + <xi:include href="profiles/installation-device.xml" /> + <xi:include href="profiles/minimal.xml" /> + <xi:include href="profiles/qemu-guest.xml" /> +</chapter> diff --git a/nixos/doc/manual/configuration/profiles/all-hardware.xml b/nixos/doc/manual/configuration/profiles/all-hardware.xml new file mode 100644 index 00000000000..2936f71069d --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/all-hardware.xml @@ -0,0 +1,21 @@ +<section 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-profile-all-hardware"> + <title>All Hardware</title> + + <para> + Enables all hardware supported by NixOS: i.e., all firmware is included, and + all devices from which one may boot are enabled in the initrd. Its primary + use is in the NixOS installation CDs. + </para> + + <para> + The enabled kernel modules include support for SATA and PATA, SCSI + (partially), USB, Firewire (untested), Virtio (QEMU, KVM, etc.), VMware, and + Hyper-V. Additionally, <xref linkend="opt-hardware.enableAllFirmware"/> is + enabled, and the firmware for the ZyDAS ZD1211 chipset is specifically + installed. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/base.xml b/nixos/doc/manual/configuration/profiles/base.xml new file mode 100644 index 00000000000..b75f6ba25b4 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/base.xml @@ -0,0 +1,15 @@ +<section 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-profile-base"> + <title>Base</title> + + <para> + Defines the software packages included in the "minimal" installation CD. It + installs several utilities useful in a simple recovery or install media, such + as a text-mode web browser, and tools for manipulating block devices, + networking, hardware diagnostics, and filesystems (with their respective + kernel modules). + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/clone-config.xml b/nixos/doc/manual/configuration/profiles/clone-config.xml new file mode 100644 index 00000000000..04fa1643d0f --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/clone-config.xml @@ -0,0 +1,21 @@ +<section 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-profile-clone-config"> + <title>Clone Config</title> + + <para> + This profile is used in installer images. It provides an editable + configuration.nix that imports all the modules that were also used when + creating the image in the first place. As a result it allows users to edit + and rebuild the live-system. + </para> + + <para> + On images where the installation media also becomes an installation target, + copying over <literal>configuration.nix</literal> should be disabled by + setting <literal>installer.cloneConfig</literal> to <literal>false</literal>. + For example, this is done in <literal>sd-image-aarch64.nix</literal>. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/demo.xml b/nixos/doc/manual/configuration/profiles/demo.xml new file mode 100644 index 00000000000..395a5ec357c --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/demo.xml @@ -0,0 +1,15 @@ +<section 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-profile-demo"> + <title>Demo</title> + + <para> + This profile just enables a <systemitem class="username">demo</systemitem> + user, with password <literal>demo</literal>, uid <literal>1000</literal>, + <systemitem class="groupname">wheel</systemitem> group and + <link linkend="opt-services.xserver.displayManager.sddm.autoLogin"> autologin + in the SDDM display manager</link>. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/docker-container.xml b/nixos/doc/manual/configuration/profiles/docker-container.xml new file mode 100644 index 00000000000..efa7b8f24c4 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/docker-container.xml @@ -0,0 +1,16 @@ +<section 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-profile-docker-container"> + <title>Docker Container</title> + + <para> + This is the profile from which the Docker images are generated. It prepares a + working system by importing the + <link linkend="sec-profile-minimal">Minimal</link> and + <link linkend="sec-profile-clone-config">Clone Config</link> profiles, and + setting appropriate configuration options that are useful inside a container + context, like <xref linkend="opt-boot.isContainer"/>. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/graphical.xml b/nixos/doc/manual/configuration/profiles/graphical.xml new file mode 100644 index 00000000000..73e3abc59d0 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/graphical.xml @@ -0,0 +1,22 @@ +<section 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-profile-graphical"> + <title>Graphical</title> + + <para> + Defines a NixOS configuration with the Plasma 5 desktop. It's used by the + graphical installation CD. + </para> + + <para> + It sets <xref linkend="opt-services.xserver.enable"/>, + <xref linkend="opt-services.xserver.displayManager.sddm.enable"/>, + <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> ( + <link linkend="opt-services.xserver.desktopManager.plasma5.enableQt4Support"> + without Qt4 Support</link>), and + <xref linkend="opt-services.xserver.libinput.enable"/> to true. It also + includes glxinfo and firefox in the system packages list. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/hardened.xml b/nixos/doc/manual/configuration/profiles/hardened.xml new file mode 100644 index 00000000000..dc83fc837e2 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/hardened.xml @@ -0,0 +1,24 @@ +<section 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-profile-hardened"> + <title>Hardened</title> + + <para> + A profile with most (vanilla) hardening options enabled by default, + potentially at the cost of features and performance. + </para> + + <para> + This includes a hardened kernel, and limiting the system information + available to processes through the <filename>/sys</filename> and + <filename>/proc</filename> filesystems. It also disables the User Namespaces + feature of the kernel, which stops Nix from being able to build anything + (this particular setting can be overriden via + <xref linkend="opt-security.allowUserNamespaces"/>). See the + <literal + xlink:href="https://github.com/nixos/nixpkgs/tree/master/nixos/modules/profiles/hardened.nix"> + profile source</literal> for further detail on which settings are altered. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/headless.xml b/nixos/doc/manual/configuration/profiles/headless.xml new file mode 100644 index 00000000000..1b64497ebf7 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/headless.xml @@ -0,0 +1,19 @@ +<section 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-profile-headless"> + <title>Headless</title> + + <para> + Common configuration for headless machines (e.g., Amazon EC2 instances). + </para> + + <para> + Disables <link linkend="opt-sound.enable">sound</link>, + <link linkend="opt-boot.vesa">vesa</link>, serial consoles, + <link linkend="opt-systemd.enableEmergencyMode">emergency mode</link>, + <link linkend="opt-boot.loader.grub.splashImage">grub splash images</link> + and configures the kernel to reboot automatically on panic. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/installation-device.xml b/nixos/doc/manual/configuration/profiles/installation-device.xml new file mode 100644 index 00000000000..192ae955b68 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/installation-device.xml @@ -0,0 +1,36 @@ +<section 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-profile-installation-device"> + <title>Installation Device</title> + + <para> + Provides a basic configuration for installation devices like CDs. + This enables redistributable firmware, includes the + <link linkend="sec-profile-clone-config">Clone Config profile</link> + and a copy of the Nixpkgs channel, so <command>nixos-install</command> + works out of the box. + </para> + <para> + Documentation for <link linkend="opt-documentation.enable">Nixpkgs</link> + and <link linkend="opt-documentation.nixos.enable">NixOS</link> are + forcefully enabled (to override the + <link linkend="sec-profile-minimal">Minimal profile</link> preference); the + NixOS manual is shown automatically on TTY 8, udisks is disabled. + Autologin is enabled as <literal>nixos</literal> user, while passwordless + login as both <literal>root</literal> and <literal>nixos</literal> is possible. + Passwordless <command>sudo</command> is enabled too. + <link linkend="opt-networking.wireless.enable">wpa_supplicant</link> is + enabled, but configured to not autostart. + </para> + <para> + It is explained how to login, start the ssh server, and if available, + how to start the display manager. + </para> + + <para> + Several settings are tweaked so that the installer has a better chance of + succeeding under low-memory environments. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/minimal.xml b/nixos/doc/manual/configuration/profiles/minimal.xml new file mode 100644 index 00000000000..179f2d0be64 --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/minimal.xml @@ -0,0 +1,17 @@ +<section 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-profile-minimal"> + <title>Minimal</title> + + <para> + This profile defines a small NixOS configuration. It does not contain any + graphical stuff. It's a very short file that enables + <link linkend="opt-environment.noXlibs">noXlibs</link>, sets + <link linkend="opt-i18n.supportedLocales">i18n.supportedLocales</link> to + only support the user-selected locale, + <link linkend="opt-documentation.enable">disables packages' documentation + </link>, and <link linkend="opt-sound.enable">disables sound</link>. + </para> +</section> diff --git a/nixos/doc/manual/configuration/profiles/qemu-guest.xml b/nixos/doc/manual/configuration/profiles/qemu-guest.xml new file mode 100644 index 00000000000..5d055c45d2d --- /dev/null +++ b/nixos/doc/manual/configuration/profiles/qemu-guest.xml @@ -0,0 +1,18 @@ +<section 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-profile-qemu-guest"> + <title>QEMU Guest</title> + + <para> + This profile contains common configuration for virtual machines running under + QEMU (using virtio). + </para> + + <para> + It makes virtio modules available on the initrd, sets the system time from + the hardware clock to work around a bug in qemu-kvm, and + <link linkend="opt-security.rngd.enable">enables rngd</link>. + </para> +</section> diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml index 66c1c6eb3a1..4b1710f3a2b 100644 --- a/nixos/doc/manual/configuration/user-mgmt.xml +++ b/nixos/doc/manual/configuration/user-mgmt.xml @@ -44,7 +44,7 @@ A user ID (uid) is assigned automatically. You can also specify a uid manually by adding <programlisting> - uid = 1000; +uid = 1000; </programlisting> to the user specification. </para> diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml index 999447234ad..247d29d5831 100644 --- a/nixos/doc/manual/configuration/wireless.xml +++ b/nixos/doc/manual/configuration/wireless.xml @@ -19,27 +19,52 @@ NixOS lets you specify networks for wpa_supplicant declaratively: <programlisting> <xref linkend="opt-networking.wireless.networks"/> = { - echelon = { + echelon = { # SSID with no spaces or special characters psk = "abcdefgh"; }; - "free.wifi" = {}; -} + "echelon's AP" = { # SSID with spaces and/or special characters + psk = "ijklmnop"; + }; + echelon = { # Hidden SSID + hidden = true; + psk = "qrstuvwx"; + }; + free.wifi = {}; # Public wireless network +}; </programlisting> Be aware that keys will be written to the nix store in plaintext! When no networks are set, it will default to using a configuration file at <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file - yourself to define wireless networks, WPA keys and so on (see - wpa_supplicant.conf(5)). + yourself to define wireless networks, WPA keys and so on (see <citerefentry> + <refentrytitle>wpa_supplicant.conf</refentrytitle> + <manvolnum>5</manvolnum> </citerefentry>). </para> <para> - If you are using WPA2 the <command>wpa_passphrase</command> tool might be - useful to generate the <literal>wpa_supplicant.conf</literal>. + If you are using WPA2 you can generate pskRaw key using + <command>wpa_passphrase</command>: +<screen> +<prompt>$ </prompt>wpa_passphrase ESSID PSK +network={ + ssid="echelon" + #psk="abcdefgh" + psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435 +} +</screen> +<programlisting> +<xref linkend="opt-networking.wireless.networks"/> = { + echelon = { + pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435"; + }; +} +</programlisting> + or you can use it to directly generate the + <literal>wpa_supplicant.conf</literal>: <screen> -# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen> +<prompt># </prompt>wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen> After you have edited the <literal>wpa_supplicant.conf</literal>, you need to restart the wpa_supplicant service. <screen> -# systemctl restart wpa_supplicant.service</screen> +<prompt># </prompt>systemctl restart wpa_supplicant.service</screen> </para> </section> diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml index 703a1b8b7f0..f6f659b02af 100644 --- a/nixos/doc/manual/configuration/x-windows.xml +++ b/nixos/doc/manual/configuration/x-windows.xml @@ -35,11 +35,11 @@ </para> <para> NixOS’s default <emphasis>display manager</emphasis> (the program that - provides a graphical login prompt and manages the X server) is SLiM. You can - select an alternative one by picking one of the following lines: + provides a graphical login prompt and manages the X server) is LightDM. You + can select an alternative one by picking one of the following lines: <programlisting> <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true; -<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.slim.enable"/> = true; </programlisting> </para> <para> @@ -60,8 +60,41 @@ # systemctl start display-manager.service </screen> </para> + <para> + On 64-bit systems, if you want OpenGL for 32-bit programs such as in Wine, + you should also set the following: +<programlisting> +<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; +</programlisting> + </para> + <simplesect xml:id="sec-x11-auto-login"> + <title>Auto-login</title> + <para> + The x11 login screen can be skipped entirely, automatically logging you into + your window manager and desktop environment when you boot your computer. + </para> + <para> + This is especially helpful if you have disk encryption enabled. Since you + already have to provide a password to decrypt your disk, entering a second + password to login can be redundant. + </para> + <para> + To enable auto-login, you need to define your default window manager and + desktop environment. If you wanted no desktop environment and i3 as your your + window manager, you'd define: +<programlisting> +<xref linkend="opt-services.xserver.desktopManager.default"/> = "none"; +<xref linkend="opt-services.xserver.windowManager.default"/> = "i3"; +</programlisting> + And, finally, to enable auto-login for a user <literal>johndoe</literal>: +<programlisting> +<xref linkend="opt-services.xserver.displayManager.auto.enable"/> = true; +<xref linkend="opt-services.xserver.displayManager.auto.user"/> = "johndoe"; +</programlisting> + </para> + </simplesect> <simplesect xml:id="sec-x11-graphics-cards-nvidia"> - <title>NVIDIA Graphics Cards</title> + <title>Proprietary NVIDIA drivers</title> <para> NVIDIA provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because @@ -71,6 +104,7 @@ </programlisting> Or if you have an older card, you may have to use one of the legacy drivers: <programlisting> +<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy390" ]; <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ]; <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ]; <xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ]; @@ -78,16 +112,9 @@ You may need to reboot after enabling this driver to prevent a clash with other kernel modules. </para> - <para> - On 64-bit systems, if you want full acceleration for 32-bit programs such as - Wine, you should also set the following: -<programlisting> -<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; -</programlisting> - </para> </simplesect> <simplesect xml:id="sec-x11--graphics-cards-amd"> - <title>AMD Graphics Cards</title> + <title>Proprietary AMD drivers</title> <para> AMD provides a proprietary driver for its graphics cards that has better 3D performance than the X.org drivers. It is not enabled by default because @@ -98,13 +125,12 @@ You will need to reboot after enabling this driver to prevent a clash with other kernel modules. </para> + <note> <para> - On 64-bit systems, if you want full acceleration for 32-bit programs such as - Wine, you should also set the following: -<programlisting> -<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true; -</programlisting> + For recent AMD GPUs you most likely want to keep either the defaults + or <literal>"amdgpu"</literal> (both free). </para> + </note> </simplesect> <simplesect xml:id="sec-x11-touchpads"> <title>Touchpads</title> @@ -133,4 +159,140 @@ versions. </para> </simplesect> + <simplesect xml:id="custom-xkb-layouts"> + <title>Custom XKB layouts</title> + <para> + It is possible to install custom + <link xlink:href="https://en.wikipedia.org/wiki/X_keyboard_extension"> + XKB + </link> + keyboard layouts using the option + <option> + <link linkend="opt-services.xserver.extraLayouts"> + services.xserver.extraLayouts + </link> + </option>. + As a first example, we are going to create a layout based on the basic US + layout, with an additional layer to type some greek symbols by pressing the + right-alt key. + </para> + <para> + To do this we are going to create a <literal>us-greek</literal> file + with a <literal>xkb_symbols</literal> section. + </para> +<programlisting> +xkb_symbols "us-greek" +{ + include "us(basic)" // includes the base US keys + include "level3(ralt_switch)" // configures right alt as a third level switch + + key <LatA> { [ a, A, Greek_alpha ] }; + key <LatB> { [ b, B, Greek_beta ] }; + key <LatG> { [ g, G, Greek_gamma ] }; + key <LatD> { [ d, D, Greek_delta ] }; + key <LatZ> { [ z, Z, Greek_zeta ] }; +}; +</programlisting> + <para> + To install the layout, the filepath, a description and the list of + languages must be given: + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.us-greek = { + description = "US layout with alt-gr greek"; + languages = [ "eng" ]; + symbolsFile = /path/to/us-greek; +} +</programlisting> + <note> + <para> + The name should match the one given to the + <literal>xkb_symbols</literal> block. + </para> + </note> + <para> + The layout should now be installed and ready to use: try it by + running <literal>setxkbmap us-greek</literal> and type + <literal><alt>+a</literal>. To change the default the usual + <option> + <link linkend="opt-services.xserver.layout"> + services.xserver.layout + </link> + </option> + option can still be used. + </para> + <para> + A layout can have several other components besides + <literal>xkb_symbols</literal>, for example we will define new + keycodes for some multimedia key and bind these to some symbol. + </para> + <para> + Use the <emphasis>xev</emphasis> utility from + <literal>pkgs.xorg.xev</literal> to find the codes of the keys of + interest, then create a <literal>media-key</literal> file to hold + the keycodes definitions + </para> +<programlisting> +xkb_keycodes "media" +{ + <volUp> = 123; + <volDown> = 456; +} +</programlisting> + <para> + Now use the newly define keycodes in <literal>media-sym</literal>: + </para> +<programlisting> +xkb_symbols "media" +{ + key.type = "ONE_LEVEL"; + key <volUp> { [ XF86AudioLowerVolume ] }; + key <volDown> { [ XF86AudioRaiseVolume ] }; +} +</programlisting> + <para> + As before, to install the layout do + </para> +<programlisting> +<xref linkend="opt-services.xserver.extraLayouts"/>.media = { + description = "Multimedia keys remapping"; + languages = [ "eng" ]; + symbolsFile = /path/to/media-key; + keycodesFile = /path/to/media-sym; +}; +</programlisting> + <note> + <para> + The function <literal>pkgs.writeText <filename> <content> + </literal> can be useful if you prefer to keep the layout definitions + inside the NixOS configuration. + </para> + </note> + <para> + Unfortunately, the Xorg server does not (currently) support setting a + keymap directly but relies instead on XKB rules to select the matching + components (keycodes, types, ...) of a layout. This means that components + other than symbols won't be loaded by default. As a workaround, you + can set the keymap using <literal>setxkbmap</literal> at the start of the + session with: + </para> +<programlisting> +<xref linkend="opt-services.xserver.displayManager.sessionCommands"/> = "setxkbmap -keycodes media"; +</programlisting> + <para> + If you are manually starting the X server, you should set the argument + <literal>-xkbdir /etc/X11/xkb</literal>, otherwise X won't find your layout files. + For example with <command>xinit</command> run + <screen><prompt>$ </prompt>xinit -- -xkbdir /etc/X11/xkb</screen> + </para> + <para> + To learn how to write layouts take a look at the XKB + <link xlink:href="https://www.x.org/releases/current/doc/xorg-docs/input/XKB-Enhancing.html#Defining_New_Layouts"> + documentation + </link>. More example layouts can also be found + <link xlink:href="https://wiki.archlinux.org/index.php/X_KeyBoard_extension#Basic_examples"> + here + </link>. + </para> +</simplesect> </chapter> diff --git a/nixos/doc/manual/configuration/xfce.xml b/nixos/doc/manual/configuration/xfce.xml index 77d5d963279..6ac99c6b2be 100644 --- a/nixos/doc/manual/configuration/xfce.xml +++ b/nixos/doc/manual/configuration/xfce.xml @@ -11,7 +11,7 @@ <link linkend="opt-services.xserver.desktopManager.xfce.enable">xfce.enable</link> = true; <link linkend="opt-services.xserver.desktopManager.default">default</link> = "xfce"; }; - </programlisting> +</programlisting> </para> <para> Optionally, <emphasis>compton</emphasis> can be enabled for nice graphical @@ -24,7 +24,7 @@ <link linkend="opt-services.compton.shadow">shadow</link> = true; <link linkend="opt-services.compton.fadeDelta">fadeDelta</link> = 4; }; - </programlisting> +</programlisting> </para> <para> Some Xfce programs are not installed automatically. To install them manually @@ -37,7 +37,7 @@ To enable <emphasis>Thunar</emphasis> volume support, put <programlisting> <xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true; - </programlisting> +</programlisting> into your <emphasis>configuration.nix</emphasis>. </para> </simplesect> @@ -58,14 +58,14 @@ on start (look at <command>journalctl --user -b</command>). <programlisting> Thunar:2410): GVFS-RemoteVolumeMonitor-WARNING **: remote volume monitor with dbus name org.gtk.Private.UDisks2VolumeMonitor is not supported - </programlisting> +</programlisting> This is caused by some needed GNOME services not running. This is all fixed by enabling "Launch GNOME services on startup" in the Advanced tab of the Session and Startup settings panel. Alternatively, you can run this command to do the same thing. <programlisting> -$ xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true - </programlisting> +<prompt>$ </prompt>xfconf-query -c xfce4-session -p /compat/LaunchGNOME -s true +</programlisting> A log-out and re-log will be needed for this to take effect. </para> </simplesect> diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index faae4f20544..f9de2db1a08 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -5,55 +5,6 @@ with pkgs; let lib = pkgs.lib; - # Remove invisible and internal options. - optionsListVisible = lib.filter (opt: opt.visible && !opt.internal) (lib.optionAttrSetToDocList options); - - # Replace functions by the string <function> - substFunction = x: - if builtins.isAttrs x then lib.mapAttrs (name: substFunction) x - else if builtins.isList x then map substFunction x - else if lib.isFunction x then "<function>" - else x; - - # Generate DocBook documentation for a list of packages. This is - # what `relatedPackages` option of `mkOption` from - # ../../../lib/options.nix influences. - # - # Each element of `relatedPackages` can be either - # - a string: that will be interpreted as an attribute name from `pkgs`, - # - a list: that will be interpreted as an attribute path from `pkgs`, - # - an attrset: that can specify `name`, `path`, `package`, `comment` - # (either of `name`, `path` is required, the rest are optional). - genRelatedPackages = packages: - let - unpack = p: if lib.isString p then { name = p; } - else if lib.isList p then { path = p; } - else p; - describe = args: - let - title = args.title or null; - name = args.name or (lib.concatStringsSep "." args.path); - path = args.path or [ args.name ]; - package = args.package or (lib.attrByPath path (throw "Invalid package attribute path `${toString path}'") pkgs); - in "<listitem>" - + "<para><literal>${lib.optionalString (title != null) "${title} aka "}pkgs.${name} (${package.meta.name})</literal>" - + lib.optionalString (!package.meta.available) " <emphasis>[UNAVAILABLE]</emphasis>" - + ": ${package.meta.description or "???"}.</para>" - + lib.optionalString (args ? comment) "\n<para>${args.comment}</para>" - # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting> - + lib.optionalString (package.meta ? longDescription) "\n<programlisting>${package.meta.longDescription}</programlisting>" - + "</listitem>"; - in "<itemizedlist>${lib.concatStringsSep "\n" (map (p: describe (unpack p)) packages)}</itemizedlist>"; - - optionsListDesc = lib.flip map optionsListVisible (opt: opt // { - # Clean up declaration sites to not refer to the NixOS source tree. - declarations = map stripAnyPrefixes opt.declarations; - } - // lib.optionalAttrs (opt ? example) { example = substFunction opt.example; } - // lib.optionalAttrs (opt ? default) { default = substFunction opt.default; } - // lib.optionalAttrs (opt ? type) { type = substFunction opt.type; } - // lib.optionalAttrs (opt ? relatedPackages && opt.relatedPackages != []) { relatedPackages = genRelatedPackages opt.relatedPackages; }); - # We need to strip references to /nix/store/* from options, # including any `extraSources` if some modules came from elsewhere, # or else the build will fail. @@ -63,37 +14,13 @@ let prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); stripAnyPrefixes = lib.flip (lib.fold lib.removePrefix) prefixesToStrip; - # Custom "less" that pushes up all the things ending in ".enable*" - # and ".package*" - optionLess = a: b: - let - ise = lib.hasPrefix "enable"; - isp = lib.hasPrefix "package"; - cmp = lib.splitByAndCompare ise lib.compare - (lib.splitByAndCompare isp lib.compare lib.compare); - in lib.compareLists cmp a.loc b.loc < 0; - - # Customly sort option list for the man page. - optionsList = lib.sort optionLess optionsListDesc; - - # Convert the list of options into an XML file. - optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList); - - optionsDocBook = runCommand "options-db.xml" {} '' - optionsXML=${optionsXML} - if grep /nixpkgs/nixos/modules $optionsXML; then - echo "The manual appears to depend on the location of Nixpkgs, which is bad" - echo "since this prevents sharing via the NixOS channel. This is typically" - echo "caused by an option default that refers to a relative path (see above" - echo "for hints about the offending path)." - exit 1 - fi - ${buildPackages.libxslt.bin}/bin/xsltproc \ - --stringparam revision '${revision}' \ - -o intermediate.xml ${./options-to-docbook.xsl} $optionsXML - ${buildPackages.libxslt.bin}/bin/xsltproc \ - -o "$out" ${./postprocess-option-descriptions.xsl} intermediate.xml - ''; + optionsDoc = buildPackages.nixosOptionsDoc { + inherit options revision; + transformOptions = opt: opt // { + # Clean up declaration sites to not refer to the NixOS source tree. + declarations = map stripAnyPrefixes opt.declarations; + }; + }; sources = lib.sourceFilesBySuffices ./. [".xml"]; @@ -108,7 +35,7 @@ let generatedSources = runCommand "generated-docbook" {} '' mkdir $out ln -s ${modulesDoc} $out/modules.xml - ln -s ${optionsDocBook} $out/options-db.xml + ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml printf "%s" "${version}" > $out/version ''; @@ -234,22 +161,7 @@ let in rec { inherit generatedSources; - # The NixOS options in JSON format. - optionsJSON = runCommand "options-json" - { meta.description = "List of NixOS options in JSON format"; - } - '' - # Export list of options in different format. - dst=$out/share/doc/nixos - mkdir -p $dst - - cp ${builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON - (builtins.listToAttrs (map (o: { name = o.name; value = removeAttrs o ["name" "visible" "internal"]; }) optionsList)))) - } $dst/options.json - - mkdir -p $out/nix-support - echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products - ''; # */ + inherit (optionsDoc) optionsJSON optionsXML optionsDocBook; # Generate the NixOS manual. manualHTML = runCommand "nixos-manual-html" @@ -265,9 +177,13 @@ in rec { xsltproc \ ${manualXsltprocOptions} \ --stringparam target.database.document "${olinkDB}/olinkdb.xml" \ + --stringparam id.warnings "1" \ --nonet --output $dst/ \ ${docbook_xsl_ns}/xml/xsl/docbook/xhtml/chunktoc.xsl \ - ${manual-combined}/manual-combined.xml + ${manual-combined}/manual-combined.xml \ + |& tee xsltproc.out + grep "^ID recommended on" xsltproc.out &>/dev/null && echo "error: some IDs are missing" && false + rm xsltproc.out mkdir -p $dst/images/callouts cp ${docbook_xsl_ns}/xml/xsl/docbook/images/callouts/*.svg $dst/images/callouts/ @@ -326,6 +242,7 @@ in rec { # Generate manpages. mkdir -p $out/share/man xsltproc --nonet \ + --maxdepth 6000 \ --param man.output.in.separate.dir 1 \ --param man.output.base.dir "'$out/share/man/'" \ --param man.endnotes.are.numbered 0 \ diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml index 23d9ddf88a7..56a596baed0 100644 --- a/nixos/doc/manual/development/building-nixos.xml +++ b/nixos/doc/manual/development/building-nixos.xml @@ -14,14 +14,14 @@ Default CD/DVD configurations are available inside <filename>nixos/modules/installer/cd-dvd</filename>. <screen> -$ git clone https://github.com/NixOS/nixpkgs.git -$ cd nixpkgs/nixos -$ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix</screen> +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs.git +<prompt>$ </prompt>cd nixpkgs/nixos +<prompt>$ </prompt>nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd-dvd/installation-cd-minimal.nix default.nix</screen> </para> <para> Before burning your CD/DVD, you can check the content of the image by mounting anywhere like suggested by the following command: <screen> -# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> +<prompt># </prompt>mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen> </para> </chapter> diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml index b4791b72970..88369fb891b 100644 --- a/nixos/doc/manual/development/building-parts.xml +++ b/nixos/doc/manual/development/building-parts.xml @@ -8,8 +8,8 @@ With the command <command>nix-build</command>, you can build specific parts of your NixOS configuration. This is done as follows: <screen> -$ cd <replaceable>/path/to/nixpkgs/nixos</replaceable> -$ nix-build -A config.<replaceable>option</replaceable></screen> +<prompt>$ </prompt>cd <replaceable>/path/to/nixpkgs/nixos</replaceable> +<prompt>$ </prompt>nix-build -A config.<replaceable>option</replaceable></screen> where <replaceable>option</replaceable> is a NixOS option with type “derivation” (i.e. something that can be built). Attributes of interest include: @@ -28,7 +28,7 @@ $ nix-build -A config.<replaceable>option</replaceable></screen> <para> A shortcut to build this is: <screen> -$ nix-build -A system</screen> +<prompt>$ </prompt>nix-build -A system</screen> </para> </listitem> </varlistentry> @@ -66,9 +66,9 @@ $ nix-build -A system</screen> test whether the kernel and the initial ramdisk boot correctly, by using QEMU’s <option>-kernel</option> and <option>-initrd</option> options: <screen> -$ nix-build -A config.system.build.initialRamdisk -o initrd -$ nix-build -A config.system.build.kernel -o kernel -$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null +<prompt>$ </prompt>nix-build -A config.system.build.initialRamdisk -o initrd +<prompt>$ </prompt>nix-build -A config.system.build.kernel -o kernel +<prompt>$ </prompt>qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null </screen> </para> </listitem> @@ -99,15 +99,15 @@ $ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/ contain dots (e.g. <literal>httpd.service</literal>), you need to put them between quotes, like this: <screen> -$ nix-build -A 'config.systemd.units."httpd.service".unit' +<prompt>$ </prompt>nix-build -A 'config.systemd.units."httpd.service".unit' </screen> You can also test individual units, without rebuilding the whole system, by putting them in <filename>/run/systemd/system</filename>: <screen> -$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ +<prompt>$ </prompt>cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \ /run/systemd/system/tmp-httpd.service -# systemctl daemon-reload -# systemctl start tmp-httpd.service +<prompt># </prompt>systemctl daemon-reload +<prompt># </prompt>systemctl start tmp-httpd.service </screen> Note that the unit must not have the same name as any unit in <filename>/etc/systemd/system</filename> since those take precedence over diff --git a/nixos/doc/manual/development/debugging-nixos-tests.xml b/nixos/doc/manual/development/debugging-nixos-tests.xml deleted file mode 100644 index 30e58e1e355..00000000000 --- a/nixos/doc/manual/development/debugging-nixos-tests.xml +++ /dev/null @@ -1,37 +0,0 @@ -<section 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-debugging-nixos-tests"> - <title>Debugging NixOS tests</title> - - <para> - Tests may fail and infrastructure offers access to inspect machine state. - </para> - - <para> - To prevent test from stopping and cleaning up, insert a sleep command: - </para> - -<programlisting> -$machine->succeed("sleep 84000"); -</programlisting> - - <para> - As soon as machine starts run as root: - </para> - -<programlisting> -nix-shell -p socat --run "socat STDIO,raw,echo=0,escape=0x11 UNIX:/tmp/nix-build-vm-test-run-*.drv-0/vm-state-machine/backdoor" -</programlisting> - - <para> - You may need to find the correct path, replacing <literal>/tmp</literal>, - <literal>*</literal> or <literal>machine</literal>. - </para> - - <para> - Press "enter" to open up console and login as "root". After you're done, - press "ctrl-q" to exit the console. - </para> -</section> diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 03dee6ff09b..43f511b3e96 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-development"> <title>Development</title> - <partintro> + <partintro xml:id="ch-development-intro"> <para> This chapter describes how you can modify and extend NixOS. </para> diff --git a/nixos/doc/manual/development/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml index d068887200a..2695082e386 100644 --- a/nixos/doc/manual/development/nixos-tests.xml +++ b/nixos/doc/manual/development/nixos-tests.xml @@ -16,5 +16,4 @@ xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/test <xi:include href="writing-nixos-tests.xml" /> <xi:include href="running-nixos-tests.xml" /> <xi:include href="running-nixos-tests-interactively.xml" /> - <xi:include href="debugging-nixos-tests.xml" /> </chapter> diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml index e6c9eae11a7..8fcbb627342 100644 --- a/nixos/doc/manual/development/option-types.xml +++ b/nixos/doc/manual/development/option-types.xml @@ -106,7 +106,7 @@ </para> </listitem> </varlistentry> - <varlistentry> + <varlistentry xml:id='types.ints.ux'> <term> <varname>types.ints.{u8, u16, u32}</varname> </term> @@ -131,6 +131,17 @@ </para> </listitem> </varlistentry> + <varlistentry> + <term> + <varname>types.port</varname> + </term> + <listitem> + <para> + A port number. This type is an alias to + <link linkend='types.ints.ux'><varname>types.ints.u16</varname></link>. + </para> + </listitem> + </varlistentry> </variablelist> <para> @@ -337,6 +348,18 @@ </varlistentry> <varlistentry> <term> + <varname>types.oneOf</varname> [ <replaceable>t1</replaceable> <replaceable>t2</replaceable> ... ] + </term> + <listitem> + <para> + Type <replaceable>t1</replaceable> or type <replaceable>t2</replaceable> and so forth, + e.g. <literal>with types; oneOf [ int str bool ]</literal>. Multiple definitions + cannot be merged. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> <varname>types.coercedTo</varname> <replaceable>from</replaceable> <replaceable>f</replaceable> <replaceable>to</replaceable> </term> <listitem> @@ -501,7 +524,7 @@ config.mod.two = { foo = 2; bar = "two"; };</screen> The function to type check the value. Takes a value as parameter and return a boolean. It is possible to extend a type check with the <literal>addCheck</literal> function - (<xref + (<xref linkend='ex-extending-type-check-1' />), or to fully override the check function (<xref linkend='ex-extending-type-check-2' />). @@ -511,7 +534,7 @@ config.mod.two = { foo = 2; bar = "two"; };</screen> <screen> byte = mkOption { description = "An integer between 0 and 255."; - type = addCheck types.int (x: x >= 0 && x <= 255); + type = types.addCheck types.int (x: x >= 0 && x <= 255); };</screen> </example> <example xml:id='ex-extending-type-check-2'> diff --git a/nixos/doc/manual/development/releases.xml b/nixos/doc/manual/development/releases.xml index b8dd9f20c6a..bdaa2676503 100755 --- a/nixos/doc/manual/development/releases.xml +++ b/nixos/doc/manual/development/releases.xml @@ -62,13 +62,6 @@ </listitem> <listitem> <para> - <link xlink:href="https://github.com/NixOS/nixpkgs/settings/branches"> - Let a GitHub nixpkgs admin lock the branch on github for you. (so - developers can’t force push) </link> - </para> - </listitem> - <listitem> - <para> <link xlink:href="https://github.com/NixOS/nixpkgs/compare/bdf161ed8d21...6b63c4616790"> Bump the <literal>system.defaultChannel</literal> attribute in <literal>nixos/modules/misc/version.nix</literal> </link> @@ -107,6 +100,16 @@ </listitem> <listitem> <para> + Remove attributes that we know we will not be able to support, + especially if there is a stable alternative. E.g. Check that our + Linux kernels' + <link xlink:href="https://www.kernel.org/category/releases.html"> + projected end-of-life</link> are after our release projected + end-of-life + </para> + </listitem> + <listitem> + <para> Edit changelog at <literal>nixos/doc/manual/release-notes/rl-1709.xml</literal> (double check desktop versions are noted) @@ -184,6 +187,12 @@ </listitem> <listitem> <para> + Update "Chapter 4. Upgrading NixOS" section of the manual to match + new stable release version. + </para> + </listitem> + <listitem> + <para> Update the <link xlink:href="https://github.com/NixOS/nixos-homepage/commit/2a37975d5a617ecdfca94696242b6f32ffcba9f1"><code>NIXOS_SERIES</code></link> in the @@ -214,6 +223,30 @@ </itemizedlist> </section> </section> + <section xml:id="release-managers"> + <title>Release Management Team</title> + <para> + For each release there are two release managers. After each release the + release manager having managed two releases steps down and the release + management team of the last release appoints a new release manager. + </para> + <para> + This makes sure a release management team always consists of one release + manager who already has managed one release and one release manager being + introduced to their role, making it easier to pass on knowledge and + experience. + </para> + <para> + A release manager's role and responsibilities are: + </para> + <itemizedlist> + <listitem><para>manage the release process</para></listitem> + <listitem><para>start discussions about features and changes for a given release</para></listitem> + <listitem><para>create a roadmap</para></listitem> + <listitem><para>release in cooperation with Eelco Dolstra</para></listitem> + <listitem><para>decide which bug fixes, features, etc... get backported after a release</para></listitem> + </itemizedlist> + </section> <section xml:id="release-schedule"> <title>Release schedule</title> diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.xml b/nixos/doc/manual/development/running-nixos-tests-interactively.xml index b25d3dcb911..e390d62fde2 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.xml +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.xml @@ -9,17 +9,17 @@ The test itself can be run interactively. This is particularly useful when developing or debugging a test: <screen> -$ nix-build nixos/tests/login.nix -A driver -$ ./result/bin/nixos-test-driver +<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver +<prompt>$ </prompt>./result/bin/nixos-test-driver starting VDE switch for network 1 -> +<prompt>></prompt> </screen> You can then take any Perl statement, e.g. <screen> -> startAll -> testScript -> $machine->succeed("touch /tmp/foo") -> print($machine->succeed("pwd"), "\n") # Show stdout of command +<prompt>></prompt> startAll +<prompt>></prompt> testScript +<prompt>></prompt> $machine->succeed("touch /tmp/foo") +<prompt>></prompt> print($machine->succeed("pwd")) # Show stdout of command </screen> The function <command>testScript</command> executes the entire test script and drops you back into the test driver command line upon its completion. @@ -30,8 +30,8 @@ starting VDE switch for network 1 <para> To just start and experiment with the VMs, run: <screen> -$ nix-build nixos/tests/login.nix -A driver -$ ./result/bin/nixos-run-vms +<prompt>$ </prompt>nix-build nixos/tests/login.nix -A driver +<prompt>$ </prompt>./result/bin/nixos-run-vms </screen> The script <command>nixos-run-vms</command> starts the virtual machines defined by test. diff --git a/nixos/doc/manual/development/running-nixos-tests.xml b/nixos/doc/manual/development/running-nixos-tests.xml index eadbe1ea4f2..13ae1ed9369 100644 --- a/nixos/doc/manual/development/running-nixos-tests.xml +++ b/nixos/doc/manual/development/running-nixos-tests.xml @@ -12,12 +12,12 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix">login.nix</filename>, you just do: <screen> -$ nix-build '<nixpkgs/nixos/tests/login.nix>' +<prompt>$ </prompt>nix-build '<nixpkgs/nixos/tests/login.nix>' </screen> or, if you don’t want to rely on <envar>NIX_PATH</envar>: <screen> -$ cd /my/nixpkgs/nixos/tests -$ nix-build login.nix +<prompt>$ </prompt>cd /my/nixpkgs/nixos/tests +<prompt>$ </prompt>nix-build login.nix … running the VM test script machine: QEMU running (pid 8841) @@ -30,7 +30,7 @@ machine: QEMU running (pid 8841) fast, as no disk image needs to be created. Afterwards, you can view a pretty-printed log of the test: <screen> -$ firefox result/log.html +<prompt>$ </prompt>firefox result/log.html </screen> </para> </section> diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml index eec9b56b1c0..b333ccabb42 100644 --- a/nixos/doc/manual/development/sources.xml +++ b/nixos/doc/manual/development/sources.xml @@ -11,19 +11,18 @@ modify NixOS, however, you should check out the latest sources from Git. This is as follows: <screen> -$ git clone https://github.com/NixOS/nixpkgs -$ cd nixpkgs -$ git remote add channels https://github.com/NixOS/nixpkgs-channels -$ git remote update channels +<prompt>$ </prompt>git clone https://github.com/NixOS/nixpkgs +<prompt>$ </prompt>cd nixpkgs +<prompt>$ </prompt>git remote update origin </screen> This will check out the latest Nixpkgs sources to <filename>./nixpkgs</filename> the NixOS sources to <filename>./nixpkgs/nixos</filename>. (The NixOS source tree lives in a - subdirectory of the Nixpkgs repository.) The remote - <literal>channels</literal> refers to a read-only repository that tracks the - Nixpkgs/NixOS channels (see <xref linkend="sec-upgrading"/> for more + subdirectory of the Nixpkgs repository.) The + <literal>nixpkgs</literal> repository has branches that correspond + to each Nixpkgs/NixOS channel (see <xref linkend="sec-upgrading"/> for more information about channels). Thus, the Git branch - <literal>channels/nixos-17.03</literal> will contain the latest built and + <literal>origin/nixos-17.03</literal> will contain the latest built and tested version available in the <literal>nixos-17.03</literal> channel. </para> <para> @@ -32,23 +31,23 @@ $ git remote update channels not have caught up yet and you’ll have to rebuild everything from source. So you may want to create a local branch based on your current NixOS version: <screen> -$ nixos-version +<prompt>$ </prompt>nixos-version 17.09pre104379.6e0b727 (Hummingbird) -$ git checkout -b local 6e0b727 +<prompt>$ </prompt>git checkout -b local 6e0b727 </screen> Or, to base your local branch on the latest version available in a NixOS channel: <screen> -$ git remote update channels -$ git checkout -b local channels/nixos-17.03 +<prompt>$ </prompt>git remote update origin +<prompt>$ </prompt>git checkout -b local origin/nixos-17.03 </screen> (Replace <literal>nixos-17.03</literal> with the name of the channel you want to use.) You can use <command>git merge</command> or <command>git rebase</command> to keep your local branch in sync with the channel, e.g. <screen> -$ git remote update channels -$ git merge channels/nixos-17.03 +<prompt>$ </prompt>git remote update origin +<prompt>$ </prompt>git merge origin/nixos-17.03 </screen> You can use <command>git cherry-pick</command> to copy commits from your local branch to the upstream branch. @@ -58,7 +57,7 @@ $ git merge channels/nixos-17.03 tell <command>nixos-rebuild</command> about them using the <option>-I</option> flag: <screen> -# nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs +<prompt># </prompt>nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs </screen> </para> <para> @@ -67,7 +66,7 @@ $ git merge channels/nixos-17.03 <replaceable>/my/sources</replaceable>/nixpkgs</command>, or change the default by adding a symlink in <filename>~/.nix-defexpr</filename>: <screen> -$ ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs +<prompt>$ </prompt>ln -s <replaceable>/my/sources</replaceable>/nixpkgs ~/.nix-defexpr/nixpkgs </screen> You may want to delete the symlink <filename>~/.nix-defexpr/channels_root</filename> to prevent root’s NixOS diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml index 63f5f3de7f4..902f995fbc1 100644 --- a/nixos/doc/manual/development/testing-installer.xml +++ b/nixos/doc/manual/development/testing-installer.xml @@ -8,15 +8,15 @@ Building, burning, and booting from an installation CD is rather tedious, so here is a quick way to see if the installer works properly: <screen> -# mount -t tmpfs none /mnt -# nixos-generate-config --root /mnt -$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install -# ./result/bin/nixos-install</screen> +<prompt># </prompt>mount -t tmpfs none /mnt +<prompt># </prompt>nixos-generate-config --root /mnt +<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-install +<prompt># </prompt>./result/bin/nixos-install</screen> To start a login shell in the new NixOS installation in <filename>/mnt</filename>: <screen> -$ nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter -# ./result/bin/nixos-enter +<prompt>$ </prompt>nix-build '<nixpkgs/nixos>' -A config.system.build.nixos-enter +<prompt># </prompt>./result/bin/nixos-enter </screen> </para> </chapter> diff --git a/nixos/doc/manual/development/writing-nixos-tests.xml b/nixos/doc/manual/development/writing-nixos-tests.xml index 983f8f9cbe3..6be2d0a4d23 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.xml +++ b/nixos/doc/manual/development/writing-nixos-tests.xml @@ -108,7 +108,7 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualis <programlisting> $machine->start; $machine->waitForUnit("default.target"); -die unless $machine->succeed("uname") =~ /Linux/; +$machine->succeed("uname") =~ /Linux/ or die; </programlisting> The first line is actually unnecessary; machines are implicitly started when you first execute an action on them (such as <literal>waitForUnit</literal> @@ -397,9 +397,9 @@ startAll; </para> <para> <programlisting> - $machine->systemctl("list-jobs --no-pager"); // runs `systemctl list-jobs --no-pager` - $machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager` - </programlisting> +$machine->systemctl("list-jobs --no-pager"); // runs `systemctl list-jobs --no-pager` +$machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager` +</programlisting> </para> </listitem> </varlistentry> @@ -410,10 +410,10 @@ startAll; To test user units declared by <literal>systemd.user.services</literal> the optional <literal>$user</literal> argument can be used: <programlisting> - $machine->start; - $machine->waitForX; - $machine->waitForUnit("xautolock.service", "x-session-user"); - </programlisting> +$machine->start; +$machine->waitForX; +$machine->waitForUnit("xautolock.service", "x-session-user"); +</programlisting> This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>, <literal>waitForUnit</literal>, <literal>startJob</literal> and <literal>stopJob</literal>. diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml index 1a116ec0b65..48193d986ab 100644 --- a/nixos/doc/manual/installation/changing-config.xml +++ b/nixos/doc/manual/installation/changing-config.xml @@ -9,10 +9,18 @@ <link linkend="ch-configuration">changed something</link> in that file, you should do <screen> -# nixos-rebuild switch</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> @@ -23,7 +31,8 @@ <para> You can also do <screen> -# nixos-rebuild test</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. @@ -31,7 +40,8 @@ <para> There is also <screen> -# nixos-rebuild boot</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> @@ -39,7 +49,8 @@ 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> -# nixos-rebuild switch -p test </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 @@ -48,7 +59,8 @@ <para> Finally, you can do <screen> -$ nixos-rebuild build</screen> +<prompt>$ </prompt>nixos-rebuild build +</screen> to build the configuration but nothing more. This is useful to see whether everything compiles cleanly. </para> @@ -58,8 +70,8 @@ $ nixos-rebuild build</screen> <emphasis>virtual machine</emphasis> that contains the desired configuration. Just do <screen> -$ nixos-rebuild build-vm -$ ./result/bin/run-*-vm +<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 @@ -74,12 +86,12 @@ $ ./result/bin/run-*-vm guest. For instance, the following will forward host port 2222 to guest port 22 (SSH): <screen> -$ QEMU_NET_OPTS="hostfwd=tcp::2222-:22" ./result/bin/run-*-vm +<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> -$ ssh -p 2222 localhost +<prompt>$ </prompt>ssh -p 2222 localhost </screen> </para> </chapter> diff --git a/nixos/doc/manual/installation/installation.xml b/nixos/doc/manual/installation/installation.xml index d4276be95d6..2901f462dee 100644 --- a/nixos/doc/manual/installation/installation.xml +++ b/nixos/doc/manual/installation/installation.xml @@ -4,7 +4,7 @@ version="5.0" xml:id="ch-installation"> <title>Installation</title> - <partintro> + <partintro xml:id="ch-installation-intro"> <para> This section describes how to obtain, install, and configure NixOS for first-time use. diff --git a/nixos/doc/manual/installation/installing-from-other-distro.xml b/nixos/doc/manual/installation/installing-from-other-distro.xml index d1e49a2a159..8ed45899fd7 100644 --- a/nixos/doc/manual/installation/installing-from-other-distro.xml +++ b/nixos/doc/manual/installation/installing-from-other-distro.xml @@ -47,8 +47,8 @@ Short version: </para> <screen> -$ curl https://nixos.org/nix/install | sh -$ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> +<prompt>$ </prompt>curl https://nixos.org/nix/install | sh +<prompt>$ </prompt>. $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> <para> More details in the <link @@ -65,14 +65,14 @@ $ . $HOME/.nix-profile/etc/profile.d/nix.sh # …or open a fresh shell</screen> the <literal>nixpkgs</literal> channel by default. </para> <screen> -$ nix-channel --list +<prompt>$ </prompt>nix-channel --list nixpkgs https://nixos.org/channels/nixpkgs-unstable</screen> <para> As that channel gets released without running the NixOS tests, it will be safer to use the <literal>nixos-*</literal> channels instead: </para> <screen> -$ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen> +<prompt>$ </prompt>nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</replaceable> nixpkgs</screen> <para> You may want to throw in a <literal>nix-channel --update</literal> for good measure. @@ -89,7 +89,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</repla NixOS partition. They are installed by default on NixOS, but you don't have NixOS yet.. </para> -<screen>$ nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> +<screen><prompt>$ </prompt>nix-env -iE "_: with import <nixpkgs/nixos> { configuration = {}; }; with config.system.build; [ nixos-generate-config nixos-install nixos-enter manual.manpages ]"</screen> </listitem> <listitem> <note> @@ -116,7 +116,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</repla <para> Generate your NixOS configuration: </para> -<screen>$ sudo `which nixos-generate-config` --root /mnt</screen> +<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /mnt</screen> <para> You'll probably want to edit the configuration files. Refer to the <literal>nixos-generate-config</literal> step in @@ -148,8 +148,8 @@ $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</repla distribution: </para> <screen> -$ sudo groupadd -g 30000 nixbld -$ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> +<prompt>$ </prompt>sudo groupadd -g 30000 nixbld +<prompt>$ </prompt>sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> </listitem> <listitem> <para> @@ -161,7 +161,7 @@ $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> existing systems without the help of a rescue USB drive or similar. </para> </warning> -<screen>$ sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> +<screen><prompt>$ </prompt>sudo PATH="$PATH" NIX_PATH="$NIX_PATH" `which nixos-install` --root /mnt</screen> <para> Again, please refer to the <literal>nixos-install</literal> step in <xref linkend="sec-installation" /> for more information. @@ -175,8 +175,8 @@ $ sudo useradd -u 30000 -g nixbld -G nixbld nixbld</screen> Optionally, you may want to clean up your non-NixOS distribution: </para> <screen> -$ sudo userdel nixbld -$ sudo groupdel nixbld</screen> +<prompt>$ </prompt>sudo userdel nixbld +<prompt>$ </prompt>sudo groupdel nixbld</screen> <para> If you do not wish to keep the Nix package manager installed either, run something like <literal>sudo rm -rv ~/.nix-* /nix</literal> and remove the @@ -193,7 +193,7 @@ $ sudo groupdel nixbld</screen> <para> Generate your NixOS configuration: </para> -<screen>$ sudo `which nixos-generate-config` --root /</screen> +<screen><prompt>$ </prompt>sudo `which nixos-generate-config` --root /</screen> <para> Note that this will place the generated configuration files in <literal>/etc/nixos</literal>. You'll probably want to edit the @@ -212,21 +212,21 @@ $ sudo groupdel nixbld</screen> </para> <programlisting> <link linkend="opt-users.users._name__.initialHashedPassword">users.users.root.initialHashedPassword</link> = ""; - </programlisting> +</programlisting> </listitem> <listitem> <para> Build the NixOS closure and install it in the <literal>system</literal> profile: </para> -<screen>$ nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> +<screen><prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/system -f '<nixpkgs/nixos>' -I nixos-config=/etc/nixos/configuration.nix -iA system</screen> </listitem> <listitem> <para> Change ownership of the <literal>/nix</literal> tree to root (since your Nix install was probably single user): </para> -<screen>$ sudo chown -R 0.0 /nix</screen> +<screen><prompt>$ </prompt>sudo chown -R 0.0 /nix</screen> </listitem> <listitem> <para> @@ -284,16 +284,16 @@ $ sudo groupdel nixbld</screen> Let's create the files: </para> <screen> -$ sudo touch /etc/NIXOS -$ sudo touch /etc/NIXOS_LUSTRATE - </screen> +<prompt>$ </prompt>sudo touch /etc/NIXOS +<prompt>$ </prompt>sudo touch /etc/NIXOS_LUSTRATE +</screen> <para> Let's also make sure the NixOS configuration files are kept once we reboot on NixOS: </para> <screen> -$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE - </screen> +<prompt>$ </prompt>echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE +</screen> </listitem> <listitem> <para> @@ -312,8 +312,9 @@ $ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE </para> </warning> <screen> -$ sudo mv -v /boot /boot.bak && - sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot</screen> +<prompt>$ </prompt>sudo mv -v /boot /boot.bak && +sudo /nix/var/nix/profiles/system/bin/switch-to-configuration boot +</screen> <para> Cross your fingers, reboot, hopefully you should get a NixOS prompt! </para> diff --git a/nixos/doc/manual/installation/installing-usb.xml b/nixos/doc/manual/installation/installing-usb.xml index 0b311189430..83598635acc 100644 --- a/nixos/doc/manual/installation/installing-usb.xml +++ b/nixos/doc/manual/installation/installing-usb.xml @@ -15,16 +15,16 @@ <note> <title>On macOS</title> <para> -<programlisting> -$ diskutil list +<screen> +<prompt>$ </prompt>diskutil list [..] /dev/diskN (external, physical): #: TYPE NAME SIZE IDENTIFIER [..] -$ diskutil unmountDisk diskN +<prompt>$ </prompt>diskutil unmountDisk diskN Unmount of all volumes on diskN was successful -$ sudo dd bs=1m if=nix.iso of=/dev/rdiskN -</programlisting> +<prompt>$ </prompt>sudo dd if=nix.iso of=/dev/rdiskN +</screen> Using the 'raw' <command>rdiskN</command> device instead of <command>diskN</command> completes in minutes instead of hours. After <command>dd</command> completes, a GUI dialog "The disk you inserted was diff --git a/nixos/doc/manual/installation/installing-virtualbox-guest.xml b/nixos/doc/manual/installation/installing-virtualbox-guest.xml index da78b480f5a..5c86eacfbf4 100644 --- a/nixos/doc/manual/installation/installing-virtualbox-guest.xml +++ b/nixos/doc/manual/installation/installing-virtualbox-guest.xml @@ -77,18 +77,22 @@ Shared folders can be given a name and a path in the host system in the VirtualBox settings (Machine / Settings / Shared Folders, then click on the "Add" icon). Add the following to the - <literal>/etc/nixos/configuration.nix</literal> to auto-mount them: + <literal>/etc/nixos/configuration.nix</literal> to auto-mount them. If you do + not add <literal>"nofail"</literal>, the system will no boot properly. The + same goes for disabling <literal>rngd</literal> which is normally used to get + randomness but this does not work in virtual machines. </para> <programlisting> { config, pkgs, ...} : { + security.rngd.enable = false; // otherwise vm will not boot ... fileSystems."/virtualboxshare" = { fsType = "vboxsf"; device = "nameofthesharedfolder"; - options = [ "rw" ]; + options = [ "rw" "nofail" ]; }; } </programlisting> diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml index 2b68def95b7..8ff920eb5a8 100644 --- a/nixos/doc/manual/installation/installing.xml +++ b/nixos/doc/manual/installation/installing.xml @@ -29,13 +29,14 @@ </para> <para> - You are logged-in automatically as <literal>root</literal>. (The - <literal>root</literal> user account has an empty password.) + You are logged-in automatically as <literal>nixos</literal>. + The <literal>nixos</literal> user account has an empty password so you + can use <command>sudo</command> without a password. </para> <para> If you downloaded the graphical ISO image, you can run <command>systemctl - start display-manager</command> to start KDE. If you want to continue on the + start display-manager</command> to start the desktop environment. If you want to continue on the terminal, you can use <command>loadkeys</command> to switch to your preferred keyboard layout. (We even provide neo2 via <command>loadkeys de neo</command>!) @@ -54,7 +55,7 @@ <para> To manually configure the network on the graphical installer, first disable - network-manager with <command>systemctl stop network-manager</command>. + network-manager with <command>systemctl stop NetworkManager</command>. </para> <para> @@ -65,9 +66,9 @@ <para> If you would like to continue the installation from a different machine you - need to activate the SSH daemon via <literal>systemctl start - sshd</literal>. In order to be able to login you also need to set a - password for <literal>root</literal> using <literal>passwd</literal>. + need to activate the SSH daemon via <command>systemctl start + sshd</command>. You then must set a password for either <literal>root</literal> or + <literal>nixos</literal> with <command>passwd</command> to be able to login. </para> </section> </section> @@ -110,15 +111,22 @@ <listitem> <para> Create a <emphasis>GPT</emphasis> partition table. -<screen language="commands"># parted /dev/sda -- mklabel gpt</screen> +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel gpt</screen> </para> </listitem> <listitem> <para> - Add a <emphasis>swap</emphasis> partition. The size required will vary - according to needs, here a 8GiB one is created. The space left in front - (512MiB) will be used by the boot partition. -<screen language="commands"># parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB</screen> + Add the <emphasis>root</emphasis> partition. This will fill the disk + except for the end part, where the swap will live, and the space left in + front (512MiB) which will be used by the boot partition. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Next, add a <emphasis>swap</emphasis> partition. The size required will + vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> <note> <para> The swap partition size rules are no different than for other Linux @@ -129,19 +137,12 @@ </listitem> <listitem> <para> - Next, add the <emphasis>root</emphasis> partition. This will fill the - remainder ending part of the disk. -<screen language="commands"># parted /dev/sda -- mkpart primary 8.5GiB -1MiB</screen> - </para> - </listitem> - <listitem> - <para> Finally, the <emphasis>boot</emphasis> partition. NixOS by default uses the ESP (EFI system partition) as its <emphasis>/boot</emphasis> partition. It uses the initially reserved 512MiB at the start of the disk. -<screen language="commands"># parted /dev/sda -- mkpart ESP fat32 1M 512MiB -# parted /dev/sda -- set 3 boot on</screen> +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 boot on</screen> </para> </listitem> </orderedlist> @@ -172,14 +173,21 @@ <listitem> <para> Create a <emphasis>MBR</emphasis> partition table. -<screen language="commands"># parted /dev/sda -- mklabel msdos</screen> +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mklabel msdos</screen> </para> </listitem> <listitem> <para> - Add a <emphasis>swap</emphasis> partition. The size required will vary - according to needs, here a 8GiB one is created. -<screen language="commands"># parted /dev/sda -- mkpart primary linux-swap 1M 8GiB</screen> + Add the <emphasis>root</emphasis> partition. This will fill the the disk + except for the end part, where the swap will live. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB</screen> + </para> + </listitem> + <listitem> + <para> + Finally, add a <emphasis>swap</emphasis> partition. The size required + will vary according to needs, here a 8GiB one is created. +<screen language="commands"><prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> <note> <para> The swap partition size rules are no different than for other Linux @@ -188,13 +196,6 @@ </note> </para> </listitem> - <listitem> - <para> - Finally, add the <emphasis>root</emphasis> partition. This will fill the - remainder of the disk. -<screen language="commands"># parted /dev/sda -- mkpart primary 8GiB -1s</screen> - </para> - </listitem> </orderedlist> </para> @@ -218,7 +219,7 @@ since this makes the file system configuration independent from device changes. For example: <screen> -# mkfs.ext4 -L nixos /dev/sda1</screen> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1</screen> </para> </listitem> <listitem> @@ -227,7 +228,7 @@ recommended to assign a label to the swap partition: <option>-L <replaceable>label</replaceable></option>. For example: <screen> -# mkswap -L swap /dev/sda2</screen> +<prompt># </prompt>mkswap -L swap /dev/sda2</screen> </para> </listitem> <listitem> @@ -242,7 +243,7 @@ it’s recommended to assign a label to the boot partition: <option>-n <replaceable>label</replaceable></option>. For example: <screen> -# mkfs.fat -F 32 -n boot /dev/sda3</screen> +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3</screen> </para> </listitem> </varlistentry> @@ -273,7 +274,7 @@ Mount the target file system on which NixOS should be installed on <filename>/mnt</filename>, e.g. <screen> -# mount /dev/disk/by-label/nixos /mnt +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt </screen> </para> </listitem> @@ -287,8 +288,8 @@ <para> Mount the boot file system on <filename>/mnt/boot</filename>, e.g. <screen> -# mkdir -p /mnt/boot -# mount /dev/disk/by-label/boot /mnt/boot +<prompt># </prompt>mkdir -p /mnt/boot +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot </screen> </para> </listitem> @@ -303,7 +304,7 @@ the build actions that it may spawn) may need quite a bit of RAM, depending on your configuration. <screen> -# swapon /dev/sda2</screen> +<prompt># </prompt>swapon /dev/sda2</screen> </para> </listitem> <listitem> @@ -325,16 +326,16 @@ The command <command>nixos-generate-config</command> can generate an initial configuration file for you: <screen> -# nixos-generate-config --root /mnt</screen> +<prompt># </prompt>nixos-generate-config --root /mnt</screen> You should then edit <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your needs: <screen> -# nano /mnt/etc/nixos/configuration.nix +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix </screen> If you’re using the graphical ISO image, other editors may be available (such as <command>vim</command>). If you have network access, you can also install other editors — for instance, you can install Emacs by running - <literal>nix-env -i emacs</literal>. + <literal>nix-env -f '<nixpkgs>' -iA emacs</literal>. </para> <variablelist> <varlistentry> @@ -378,6 +379,10 @@ the grub menu. </para> <para> + If you need to configure networking for your machine the configuration + options are described in <xref linkend="sec-networking"/>. + </para> + <para> Another critical option is <option>fileSystems</option>, specifying the file systems that need to be mounted by NixOS. However, you typically don’t need to set it yourself, because @@ -387,7 +392,11 @@ <filename>hardware-configuration.nix</filename> is included from <filename>configuration.nix</filename> and will be overwritten by future invocations of <command>nixos-generate-config</command>; thus, you - generally should not modify it.) + generally should not modify it.) Additionally, you may want to look at + <link xlink:href="https://github.com/NixOS/nixos-hardware">Hardware + configuration for known-hardware</link> at this point or after + installation. + </para> <note> <para> @@ -408,7 +417,7 @@ <para> Do the installation: <screen> -# nixos-install</screen> +<prompt># </prompt>nixos-install</screen> Cross fingers. If this fails due to a temporary problem (such as a network issue while downloading binaries from the NixOS binary cache), you can just re-run <command>nixos-install</command>. Otherwise, fix your @@ -435,7 +444,7 @@ Retype new UNIX password: ***</screen> <para> If everything went well: <screen> -# reboot</screen> +<prompt># </prompt>reboot</screen> </para> </listitem> <listitem> @@ -456,16 +465,16 @@ Retype new UNIX password: ***</screen> You’ll probably want to create some user accounts as well, which can be done with <command>useradd</command>: <screen> -$ useradd -c 'Eelco Dolstra' -m eelco -$ passwd eelco</screen> +<prompt>$ </prompt>useradd -c 'Eelco Dolstra' -m eelco +<prompt>$ </prompt>passwd eelco</screen> </para> <para> You may also want to install some software. For instance, <screen> -$ nix-env -qa \*</screen> +<prompt>$ </prompt>nix-env -qaP \*</screen> shows what packages are available, and <screen> -$ nix-env -i w3m</screen> +<prompt>$ </prompt>nix-env -f '<nixpkgs>' -iA w3m</screen> install the <literal>w3m</literal> browser. </para> </listitem> @@ -485,19 +494,19 @@ $ nix-env -i w3m</screen> <example xml:id="ex-partition-scheme-MBR"> <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (MBR)</title> <screen language="commands"> -# parted /dev/sda -- mklabel msdos -# parted /dev/sda -- mkpart primary linux-swap 1M 8GiB -# parted /dev/sda -- mkpart primary 8GiB -1s</screen> +<prompt># </prompt>parted /dev/sda -- mklabel msdos +<prompt># </prompt>parted /dev/sda -- mkpart primary 1MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100%</screen> </example> <example xml:id="ex-partition-scheme-UEFI"> <title>Example partition schemes for NixOS on <filename>/dev/sda</filename> (UEFI)</title> <screen language="commands"> -# parted /dev/sda -- mklabel gpt -# parted /dev/sda -- mkpart primary linux-swap 512MiB 8.5GiB -# parted /dev/sda -- mkpart primary 8.5GiB -1MiB -# parted /dev/sda -- mkpart ESP fat32 1M 512MiB -# parted /dev/sda -- set 3 boot on</screen> +<prompt># </prompt>parted /dev/sda -- mklabel gpt +<prompt># </prompt>parted /dev/sda -- mkpart primary 512MiB -8GiB +<prompt># </prompt>parted /dev/sda -- mkpart primary linux-swap -8GiB 100% +<prompt># </prompt>parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB +<prompt># </prompt>parted /dev/sda -- set 3 boot on</screen> </example> <example xml:id="ex-install-sequence"> @@ -505,23 +514,23 @@ $ nix-env -i w3m</screen> <para> With a partitioned disk. <screen language="commands"> -# mkfs.ext4 -L nixos /dev/sda1 -# mkswap -L swap /dev/sda2 -# swapon /dev/sda2 -# mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> -# mount /dev/disk/by-label/nixos /mnt -# mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> -# mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> -# nixos-generate-config --root /mnt -# nano /mnt/etc/nixos/configuration.nix -# nixos-install -# reboot</screen> +<prompt># </prompt>mkfs.ext4 -L nixos /dev/sda1 +<prompt># </prompt>mkswap -L swap /dev/sda2 +<prompt># </prompt>swapon /dev/sda2 +<prompt># </prompt>mkfs.fat -F 32 -n boot /dev/sda3 # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/nixos /mnt +<prompt># </prompt>mkdir -p /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>mount /dev/disk/by-label/boot /mnt/boot # <lineannotation>(for UEFI systems only)</lineannotation> +<prompt># </prompt>nixos-generate-config --root /mnt +<prompt># </prompt>nano /mnt/etc/nixos/configuration.nix +<prompt># </prompt>nixos-install +<prompt># </prompt>reboot</screen> </para> </example> <example xml:id='ex-config'> <title>NixOS Configuration</title> -<screen> +<programlisting> { config, pkgs, ... }: { imports = [ # Include the results of the hardware scan. @@ -539,7 +548,7 @@ $ nix-env -i w3m</screen> # Enable the OpenSSH server. services.sshd.enable = true; } - </screen> +</programlisting> </example> </section> <section xml:id="sec-installation-additional-notes"> diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml index 69668b1d4bd..8d3f35b7c26 100644 --- a/nixos/doc/manual/installation/upgrading.xml +++ b/nixos/doc/manual/installation/upgrading.xml @@ -14,11 +14,11 @@ <para> <emphasis>Stable channels</emphasis>, such as <literal - xlink:href="https://nixos.org/channels/nixos-17.03">nixos-17.03</literal>. + xlink:href="https://nixos.org/channels/nixos-19.09">nixos-19.09</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.9.16 to 4.9.17 (a minor bug fix), but not from - 4.9.<replaceable>x</replaceable> to 4.11.<replaceable>x</replaceable> (a + 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> @@ -38,7 +38,7 @@ <para> <emphasis>Small channels</emphasis>, such as <literal - xlink:href="https://nixos.org/channels/nixos-17.03-small">nixos-17.03-small</literal> + xlink:href="https://nixos.org/channels/nixos-19.09-small">nixos-19.09-small</literal> or <literal xlink:href="https://nixos.org/channels/nixos-unstable-small">nixos-unstable-small</literal>. @@ -63,8 +63,8 @@ <para> When you first install NixOS, you’re automatically subscribed to the NixOS channel that corresponds to your installation source. For instance, if you - installed from a 17.03 ISO, you will be subscribed to the - <literal>nixos-17.03</literal> channel. To see which NixOS channel you’re + installed from a 19.09 ISO, you will be subscribed to the + <literal>nixos-19.09</literal> channel. To see which NixOS channel you’re subscribed to, run the following as root: <screen> # nix-channel --list | grep nixos @@ -75,13 +75,13 @@ nixos https://nixos.org/channels/nixos-unstable # 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 17.03 stable channel: + instance, to use the NixOS 19.09 stable channel: <screen> -# nix-channel --add https://nixos.org/channels/nixos-17.03 nixos +# nix-channel --add https://nixos.org/channels/nixos-19.09 nixos </screen> If you have a server, you may want to use the “small” channel instead: <screen> -# nix-channel --add https://nixos.org/channels/nixos-17.03-small nixos +# nix-channel --add https://nixos.org/channels/nixos-19.09-small nixos </screen> And if you want to live on the bleeding edge: <screen> @@ -127,7 +127,7 @@ nixos https://nixos.org/channels/nixos-unstable current channel. (To see when the service runs, see <command>systemctl list-timers</command>.) You can also specify a channel explicitly, e.g. <programlisting> -<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-17.03; +<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-19.09; </programlisting> </para> </section> diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml index 9f30b792510..ddb1408fdcf 100644 --- a/nixos/doc/manual/man-configuration.xml +++ b/nixos/doc/manual/man-configuration.xml @@ -8,8 +8,8 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><filename>configuration.nix</filename> - </refname><refpurpose>NixOS system configuration specification</refpurpose> + <refname><filename>configuration.nix</filename></refname> + <refpurpose>NixOS system configuration specification</refpurpose> </refnamediv> <refsection> <title>Description</title> diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml index 87e4f3dae86..d114261f53b 100644 --- a/nixos/doc/manual/man-nixos-build-vms.xml +++ b/nixos/doc/manual/man-nixos-build-vms.xml @@ -8,8 +8,8 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><command>nixos-build-vms</command> - </refname><refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> + <refname><command>nixos-build-vms</command></refname> + <refpurpose>build a network of virtual machines from a network of NixOS configurations</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -24,8 +24,14 @@ <arg> <option>--help</option> - </arg> - + </arg> + + <arg> + <option>--option</option> + <replaceable>name</replaceable> + <replaceable>value</replaceable> + </arg> + <arg choice="plain"> <replaceable>network.nix</replaceable> </arg> @@ -115,6 +121,18 @@ </para> </listitem> </varlistentry> + <varlistentry> + <term> + <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> + </term> + <listitem> + <para>Set the Nix configuration option + <replaceable>name</replaceable> to <replaceable>value</replaceable>. + This overrides settings in the Nix configuration file (see + <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para> + </listitem> + </varlistentry> </variablelist> </refsection> </refentry> diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml index 42edaa1ae5b..fe560d3efdd 100644 --- a/nixos/doc/manual/man-nixos-enter.xml +++ b/nixos/doc/manual/man-nixos-enter.xml @@ -8,8 +8,8 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><command>nixos-enter</command> - </refname><refpurpose>run a command in a NixOS chroot environment</refpurpose> + <refname><command>nixos-enter</command></refname> + <refpurpose>run a command in a NixOS chroot environment</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> @@ -34,6 +34,12 @@ </arg> <replaceable>shell-command</replaceable> </arg> + + <arg> + <arg choice='plain'> + <option>--silent</option> + </arg> + </arg> <arg> <arg choice='plain'> @@ -102,6 +108,16 @@ </varlistentry> <varlistentry> <term> + <option>--silent</option> + </term> + <listitem> + <para> + Suppresses all output from the activation script of the target system. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> <option>--</option> </term> <listitem> diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml index 1227873f578..9ac3b918ff6 100644 --- a/nixos/doc/manual/man-nixos-generate-config.xml +++ b/nixos/doc/manual/man-nixos-generate-config.xml @@ -8,23 +8,23 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><command>nixos-generate-config</command> - </refname><refpurpose>generate NixOS configuration modules</refpurpose> + <refname><command>nixos-generate-config</command></refname> + <refpurpose>generate NixOS configuration modules</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>nixos-generate-config</command> + <command>nixos-generate-config</command> <arg> <option>--force</option> </arg> - + <arg> <arg choice='plain'> <option>--root</option> </arg> <replaceable>root</replaceable> </arg> - + <arg> <arg choice='plain'> <option>--dir</option> @@ -154,7 +154,7 @@ file systems on <filename>/mnt</filename> and <filename>/mnt/boot</filename>, you would run: <screen> -$ nixos-generate-config --root /mnt +<prompt>$ </prompt>nixos-generate-config --root /mnt </screen> The resulting file <filename>/mnt/etc/nixos/hardware-configuration.nix</filename> might look @@ -167,7 +167,7 @@ $ nixos-generate-config --root /mnt { imports = - [ <nixos/modules/installer/scan/not-detected.nix> + [ <nixos/modules/installer/scan/not-detected.nix> ]; boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ]; @@ -204,7 +204,7 @@ $ nixos-generate-config --root /mnt <para> After installation, if your hardware configuration changes, you can run: <screen> -$ nixos-generate-config +<prompt>$ </prompt>nixos-generate-config </screen> to update <filename>/etc/nixos/hardware-configuration.nix</filename>. Your <filename>/etc/nixos/configuration.nix</filename> will diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml index 25f4f40613a..45bbd5d81ff 100644 --- a/nixos/doc/manual/man-nixos-install.xml +++ b/nixos/doc/manual/man-nixos-install.xml @@ -8,77 +8,77 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><command>nixos-install</command> - </refname><refpurpose>install bootloader and NixOS</refpurpose> + <refname><command>nixos-install</command></refname> + <refpurpose>install bootloader and NixOS</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>nixos-install</command> + <command>nixos-install</command> <arg> <arg choice='plain'> <option>-I</option> </arg> <replaceable>path</replaceable> </arg> - + <arg> <arg choice='plain'> <option>--root</option> </arg> <replaceable>root</replaceable> </arg> - + <arg> <arg choice='plain'> <option>--system</option> </arg> <replaceable>path</replaceable> </arg> - + <arg> <arg choice='plain'> <option>--no-channel-copy</option> </arg> </arg> - + <arg> <arg choice='plain'> <option>--no-root-passwd</option> </arg> </arg> - + <arg> <arg choice='plain'> <option>--no-bootloader</option> </arg> </arg> - + <arg> - <group choice='req'> + <group choice='req'> <arg choice='plain'> <option>--max-jobs</option> </arg> - + <arg choice='plain'> <option>-j</option> </arg> </group> <replaceable>number</replaceable> </arg> - + <arg> <option>--cores</option> <replaceable>number</replaceable> </arg> - + <arg> <option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable> </arg> - + <arg> <arg choice='plain'> <option>--show-trace</option> </arg> </arg> - + <arg> <arg choice='plain'> <option>--help</option> @@ -255,12 +255,12 @@ on an <literal>ext4</literal> file system created in <filename>/dev/sda1</filename>: <screen> -$ mkfs.ext4 /dev/sda1 -$ mount /dev/sda1 /mnt -$ nixos-generate-config --root /mnt -$ # edit /mnt/etc/nixos/configuration.nix -$ nixos-install -$ reboot +<prompt>$ </prompt>mkfs.ext4 /dev/sda1 +<prompt>$ </prompt>mount /dev/sda1 /mnt +<prompt>$ </prompt>nixos-generate-config --root /mnt +<prompt>$ </prompt># edit /mnt/etc/nixos/configuration.nix +<prompt>$ </prompt>nixos-install +<prompt>$ </prompt>reboot </screen> </para> </refsection> diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml index d436cce742a..81e3739b3be 100644 --- a/nixos/doc/manual/man-nixos-option.xml +++ b/nixos/doc/manual/man-nixos-option.xml @@ -8,24 +8,24 @@ <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> <refnamediv> - <refname><command>nixos-option</command> - </refname><refpurpose>inspect a NixOS configuration</refpurpose> + <refname><command>nixos-option</command></refname> + <refpurpose>inspect a NixOS configuration</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> - <command>nixos-option</command> + <command>nixos-option</command> <arg> <option>-I</option> <replaceable>path</replaceable> </arg> - + <arg> <option>--verbose</option> </arg> - + <arg> <option>--xml</option> </arg> - + <arg choice="plain"> <replaceable>option.name</replaceable> </arg> @@ -103,13 +103,13 @@ <title>Examples</title> <para> Investigate option values: -<screen>$ nixos-option boot.loader +<screen><prompt>$ </prompt>nixos-option boot.loader This attribute set contains: generationsDir grub initScript -$ nixos-option boot.loader.grub.enable +<prompt>$ </prompt>nixos-option boot.loader.grub.enable Value: true diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml index 551a65f5e96..c697b7ee047 100644 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -7,41 +7,47 @@ <refmiscinfo class="source">NixOS</refmiscinfo> <!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> --> </refmeta> + <refnamediv> - <refname><command>nixos-rebuild</command> - </refname><refpurpose>reconfigure a NixOS machine</refpurpose> + <refname><command>nixos-rebuild</command></refname> + <refpurpose>reconfigure a NixOS machine</refpurpose> </refnamediv> + <refsynopsisdiv> <cmdsynopsis> - <command>nixos-rebuild</command><group choice='req'> + <command>nixos-rebuild</command><group choice='req'> <arg choice='plain'> <option>switch</option> </arg> - + <arg choice='plain'> <option>boot</option> </arg> - + <arg choice='plain'> <option>test</option> </arg> - + <arg choice='plain'> <option>build</option> </arg> - + <arg choice='plain'> <option>dry-build</option> </arg> - + <arg choice='plain'> <option>dry-activate</option> </arg> - + + <arg choice='plain'> + <option>edit</option> + </arg> + <arg choice='plain'> <option>build-vm</option> </arg> - + <arg choice='plain'> <option>build-vm-with-bootloader</option> </arg> @@ -50,29 +56,34 @@ <arg> <option>--upgrade</option> </arg> - + <arg> <option>--install-bootloader</option> </arg> - + <arg> <option>--no-build-nix</option> </arg> - + <arg> <option>--fast</option> </arg> - + <arg> <option>--rollback</option> </arg> + + <arg> + <option>--builders</option> <replaceable>builder-spec</replaceable> + </arg> + <sbr /> <arg> - <group choice='req'> + <group choice='req'> <arg choice='plain'> <option>--profile-name</option> </arg> - + <arg choice='plain'> <option>-p</option> </arg> @@ -82,10 +93,41 @@ <arg> <option>--show-trace</option> </arg> + <arg> + <option>-I</option> + <replaceable>path</replaceable> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--verbose</option></arg> + <arg choice='plain'><option>-v</option></arg> + </group> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--max-jobs</option></arg> + <arg choice='plain'><option>-j</option></arg> + </group> + <replaceable>number</replaceable> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--keep-failed</option></arg> + <arg choice='plain'><option>-K</option></arg> + </group> + </arg> + <arg> + <group choice='req'> + <arg choice='plain'><option>--keep-going</option></arg> + <arg choice='plain'><option>-k</option></arg> + </group> + </arg> </cmdsynopsis> </refsynopsisdiv> + <refsection> <title>Description</title> + <para> This command updates the system so that it corresponds to the configuration specified in <filename>/etc/nixos/configuration.nix</filename>. Thus, every @@ -93,11 +135,14 @@ NixOS module, you must run <command>nixos-rebuild</command> to make the changes take effect. It builds the new system in <filename>/nix/store</filename>, runs its activation script, and stop and - (re)starts any system services if needed. + (re)starts any system services if needed. Please note that user services need + to be started manually as they aren't detected by the activation script at the moment. </para> + <para> This command has one required argument, which specifies the desired operation. It must be one of the following: + <variablelist> <varlistentry> <term> @@ -114,6 +159,7 @@ </para> </listitem> </varlistentry> + <varlistentry> <term> <option>boot</option> @@ -127,6 +173,7 @@ </para> </listitem> </varlistentry> + <varlistentry> <term> <option>test</option> @@ -141,6 +188,7 @@ </para> </listitem> </varlistentry> + <varlistentry> <term> <option>build</option> @@ -152,13 +200,14 @@ the current directory, which points to the output of the top-level “system” derivation. This is essentially the same as doing <screen> -$ nix-build /path/to/nixpkgs/nixos -A system +<prompt>$ </prompt>nix-build /path/to/nixpkgs/nixos -A system </screen> Note that you do not need to be <literal>root</literal> to run <command>nixos-rebuild build</command>. </para> </listitem> </varlistentry> + <varlistentry> <term> <option>dry-build</option> @@ -170,6 +219,7 @@ $ nix-build /path/to/nixpkgs/nixos -A system </para> </listitem> </varlistentry> + <varlistentry> <term> <option>dry-activate</option> @@ -184,6 +234,18 @@ $ nix-build /path/to/nixpkgs/nixos -A system </para> </listitem> </varlistentry> + + <varlistentry> + <term> + <option>edit</option> + </term> + <listitem> + <para> + Opens <filename>configuration.nix</filename> in the default editor. + </para> + </listitem> + </varlistentry> + <varlistentry> <term> <option>build-vm</option> @@ -197,16 +259,18 @@ $ nix-build /path/to/nixpkgs/nixos -A system at the script that starts the VM. Thus, to test a NixOS configuration in a virtual machine, you should do the following: <screen> -$ nixos-rebuild build-vm -$ ./result/bin/run-*-vm +<prompt>$ </prompt>nixos-rebuild build-vm +<prompt>$ </prompt>./result/bin/run-*-vm </screen> </para> + <para> The VM is implemented using the <literal>qemu</literal> package. For best performance, you should load the <literal>kvm-intel</literal> or <literal>kvm-amd</literal> kernel modules to get hardware virtualisation. </para> + <para> The VM mounts the Nix store of the host through the 9P file system. The host Nix store is read-only, so Nix commands that modify the Nix store @@ -214,6 +278,7 @@ $ ./result/bin/run-*-vm <command>nixos-rebuild</command>; to change the VM’s configuration, you must halt the VM and re-run the commands above. </para> + <para> The VM has its own <literal>ext3</literal> root file system, which is automatically created when the VM is first started, and is persistent @@ -224,6 +289,7 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + <varlistentry> <term> <option>build-vm-with-bootloader</option> @@ -246,11 +312,13 @@ $ ./result/bin/run-*-vm </variablelist> </para> </refsection> + <refsection> <title>Options</title> <para> This command accepts the following options: </para> + <variablelist> <varlistentry> <term> @@ -262,6 +330,7 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--install-bootloader</option> @@ -273,6 +342,7 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--no-build-nix</option> @@ -288,6 +358,7 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--fast</option> @@ -301,6 +372,7 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--rollback</option> @@ -315,6 +387,27 @@ $ ./result/bin/run-*-vm </para> </listitem> </varlistentry> + + <varlistentry> + <term> + <option>--builders</option> <replaceable>builder-spec</replaceable> + </term> + <listitem> + <para> + Allow ad-hoc remote builders for building the new system. This requires + the user executing <command>nixos-rebuild</command> (usually root) to be + configured as a trusted user in the Nix daemon. This can be achieved by + using the <literal>nix.trustedUsers</literal> NixOS option. Examples + values for that option are described in the <literal>Remote builds + chapter</literal> in the Nix manual, (i.e. <command>--builders + "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string + existing builders specified in <filename>/etc/nix/machines</filename> can + be ignored: <command>--builders ""</command> for example when they are + not reachable due to network connectivity. + </para> + </listitem> + </varlistentry> + <varlistentry> <term> <option>--profile-name</option> @@ -338,13 +431,14 @@ $ ./result/bin/run-*-vm <filename>test.nix</filename> without affecting the default system profile, you would do: <screen> -$ nixos-rebuild switch -p test -I nixos-config=./test.nix +<prompt>$ </prompt>nixos-rebuild switch -p test -I nixos-config=./test.nix </screen> The new configuration will appear in the GRUB 2 submenu “NixOS - Profile 'test'”. </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--build-host</option> @@ -370,6 +464,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </para> </listitem> </varlistentry> + <varlistentry> <term> <option>--target-host</option> @@ -382,6 +477,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix be accessible over ssh, and for the commands <option>switch</option>, <option>boot</option> and <option>test</option> you need root access. </para> + <para> If <option>--build-host</option> is not explicitly specified, <option>--build-host</option> will implicitly be set to the same value as @@ -390,6 +486,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix place remotely (and no build artifacts will be copied to the local machine). </para> + <para> You can include a remote user name in the host name (<replaceable>user@host</replaceable>). You can also set ssh options by @@ -398,6 +495,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </listitem> </varlistentry> </variablelist> + <para> In addition, <command>nixos-rebuild</command> accepts various Nix-related flags, including <option>--max-jobs</option> / <option>-j</option>, @@ -406,8 +504,10 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix <option>-v</option>. See the Nix manual for details. </para> </refsection> + <refsection> <title>Environment</title> + <variablelist> <varlistentry> <term> @@ -420,6 +520,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </para> </listitem> </varlistentry> + <varlistentry> <term> <envar>NIX_SSHOPTS</envar> @@ -433,9 +534,12 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </varlistentry> </variablelist> </refsection> + <refsection> <title>Files</title> + <variablelist> + <varlistentry> <term> <filename>/run/current-system</filename> @@ -446,6 +550,7 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </para> </listitem> </varlistentry> + <varlistentry> <term> <filename>/nix/var/nix/profiles/system</filename> @@ -457,8 +562,10 @@ $ nixos-rebuild switch -p test -I nixos-config=./test.nix </para> </listitem> </varlistentry> + </variablelist> </refsection> + <refsection> <title>Bugs</title> <para> diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml index 931c4a5ad02..e9ad8bddcac 100644 --- a/nixos/doc/manual/man-nixos-version.xml +++ b/nixos/doc/manual/man-nixos-version.xml @@ -7,8 +7,8 @@ <refmiscinfo class="source">NixOS</refmiscinfo> </refmeta> <refnamediv> - <refname><command>nixos-version</command> - </refname><refpurpose>show the NixOS version</refpurpose> + <refname><command>nixos-version</command></refname> + <refpurpose>show the NixOS version</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml index 0390dda6468..f5a1dd2d69f 100644 --- a/nixos/doc/manual/man-pages.xml +++ b/nixos/doc/manual/man-pages.xml @@ -6,7 +6,7 @@ <author><personname><firstname>Eelco</firstname><surname>Dolstra</surname></personname> <contrib>Author</contrib> </author> - <copyright><year>2007-2018</year><holder>Eelco Dolstra</holder> + <copyright><year>2007-2019</year><holder>Eelco Dolstra</holder> </copyright> </info> <xi:include href="man-configuration.xml" /> diff --git a/nixos/doc/manual/options-to-docbook.xsl b/nixos/doc/manual/options-to-docbook.xsl deleted file mode 100644 index 72ac89d4ff6..00000000000 --- a/nixos/doc/manual/options-to-docbook.xsl +++ /dev/null @@ -1,236 +0,0 @@ -<?xml version="1.0"?> - -<xsl:stylesheet version="1.0" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:str="http://exslt.org/strings" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:nixos="tag:nixos.org" - xmlns="http://docbook.org/ns/docbook" - extension-element-prefixes="str" - > - - <xsl:output method='xml' encoding="UTF-8" /> - - <xsl:param name="revision" /> - <xsl:param name="program" /> - - - <xsl:template match="/expr/list"> - <appendix xml:id="appendix-configuration-options"> - <title>Configuration Options</title> - <variablelist xml:id="configuration-variable-list"> - <xsl:for-each select="attrs"> - <xsl:variable name="id" select="concat('opt-', str:replace(str:replace(str:replace(str:replace(attr[@name = 'name']/string/@value, '*', '_'), '<', '_'), '>', '_'), '?', '_'))" /> - <varlistentry> - <term xlink:href="#{$id}"> - <xsl:attribute name="xml:id"><xsl:value-of select="$id"/></xsl:attribute> - <option> - <xsl:value-of select="attr[@name = 'name']/string/@value" /> - </option> - </term> - - <listitem> - - <nixos:option-description> - <para> - <xsl:value-of disable-output-escaping="yes" - select="attr[@name = 'description']/string/@value" /> - </para> - </nixos:option-description> - - <xsl:if test="attr[@name = 'type']"> - <para> - <emphasis>Type:</emphasis> - <xsl:text> </xsl:text> - <xsl:value-of select="attr[@name = 'type']/string/@value"/> - <xsl:if test="attr[@name = 'readOnly']/bool/@value = 'true'"> - <xsl:text> </xsl:text> - <emphasis>(read only)</emphasis> - </xsl:if> - </para> - </xsl:if> - - <xsl:if test="attr[@name = 'default']"> - <para> - <emphasis>Default:</emphasis> - <xsl:text> </xsl:text> - <xsl:apply-templates select="attr[@name = 'default']" mode="top" /> - </para> - </xsl:if> - - <xsl:if test="attr[@name = 'example']"> - <para> - <emphasis>Example:</emphasis> - <xsl:text> </xsl:text> - <xsl:choose> - <xsl:when test="attr[@name = 'example']/attrs[attr[@name = '_type' and string[@value = 'literalExample']]]"> - <programlisting><xsl:value-of select="attr[@name = 'example']/attrs/attr[@name = 'text']/string/@value" /></programlisting> - </xsl:when> - <xsl:otherwise> - <xsl:apply-templates select="attr[@name = 'example']" mode="top" /> - </xsl:otherwise> - </xsl:choose> - </para> - </xsl:if> - - <xsl:if test="attr[@name = 'relatedPackages']"> - <para> - <emphasis>Related packages:</emphasis> - <xsl:text> </xsl:text> - <xsl:value-of disable-output-escaping="yes" - select="attr[@name = 'relatedPackages']/string/@value" /> - </para> - </xsl:if> - - <xsl:if test="count(attr[@name = 'declarations']/list/*) != 0"> - <para> - <emphasis>Declared by:</emphasis> - </para> - <xsl:apply-templates select="attr[@name = 'declarations']" /> - </xsl:if> - - <xsl:if test="count(attr[@name = 'definitions']/list/*) != 0"> - <para> - <emphasis>Defined by:</emphasis> - </para> - <xsl:apply-templates select="attr[@name = 'definitions']" /> - </xsl:if> - - </listitem> - - </varlistentry> - - </xsl:for-each> - - </variablelist> - </appendix> - </xsl:template> - - - <xsl:template match="*" mode="top"> - <xsl:choose> - <xsl:when test="string[contains(@value, '
')]"> -<programlisting> -<xsl:text>'' -</xsl:text><xsl:value-of select='str:replace(string/@value, "${", "''${")' /><xsl:text>''</xsl:text></programlisting> - </xsl:when> - <xsl:otherwise> - <literal><xsl:apply-templates /></literal> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - - <xsl:template match="null"> - <xsl:text>null</xsl:text> - </xsl:template> - - - <xsl:template match="string"> - <xsl:choose> - <xsl:when test="(contains(@value, '"') or contains(@value, '\')) and not(contains(@value, '
'))"> - <xsl:text>''</xsl:text><xsl:value-of select='str:replace(@value, "${", "''${")' /><xsl:text>''</xsl:text> - </xsl:when> - <xsl:otherwise> - <xsl:text>"</xsl:text><xsl:value-of select="str:replace(str:replace(str:replace(str:replace(@value, '\', '\\'), '"', '\"'), '
', '\n'), '$', '\$')" /><xsl:text>"</xsl:text> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - - <xsl:template match="int"> - <xsl:value-of select="@value" /> - </xsl:template> - - - <xsl:template match="bool[@value = 'true']"> - <xsl:text>true</xsl:text> - </xsl:template> - - - <xsl:template match="bool[@value = 'false']"> - <xsl:text>false</xsl:text> - </xsl:template> - - - <xsl:template match="list"> - [ - <xsl:for-each select="*"> - <xsl:apply-templates select="." /> - <xsl:text> </xsl:text> - </xsl:for-each> - ] - </xsl:template> - - - <xsl:template match="attrs[attr[@name = '_type' and string[@value = 'literalExample']]]"> - <xsl:value-of select="attr[@name = 'text']/string/@value" /> - </xsl:template> - - - <xsl:template match="attrs"> - { - <xsl:for-each select="attr"> - <xsl:value-of select="@name" /> - <xsl:text> = </xsl:text> - <xsl:apply-templates select="*" /><xsl:text>; </xsl:text> - </xsl:for-each> - } - </xsl:template> - - - <xsl:template match="derivation"> - <replaceable>(build of <xsl:value-of select="attr[@name = 'name']/string/@value" />)</replaceable> - </xsl:template> - - <xsl:template match="attr[@name = 'declarations' or @name = 'definitions']"> - <simplelist> - <xsl:for-each select="list/string"> - <member><filename> - <!-- Hyperlink the filename either to the NixOS Subversion - repository (if it’s a module and we have a revision number), - or to the local filesystem. --> - <xsl:choose> - <xsl:when test="not(starts-with(@value, '/'))"> - <xsl:choose> - <xsl:when test="$revision = 'local'"> - <xsl:attribute name="xlink:href">https://github.com/NixOS/nixpkgs/blob/master/<xsl:value-of select="@value"/></xsl:attribute> - </xsl:when> - <xsl:otherwise> - <xsl:attribute name="xlink:href">https://github.com/NixOS/nixpkgs/blob/<xsl:value-of select="$revision"/>/<xsl:value-of select="@value"/></xsl:attribute> - </xsl:otherwise> - </xsl:choose> - </xsl:when> - <xsl:when test="$revision != 'local' and $program = 'nixops' and contains(@value, '/nix/')"> - <xsl:attribute name="xlink:href">https://github.com/NixOS/nixops/blob/<xsl:value-of select="$revision"/>/nix/<xsl:value-of select="substring-after(@value, '/nix/')"/></xsl:attribute> - </xsl:when> - <xsl:otherwise> - <xsl:attribute name="xlink:href">file://<xsl:value-of select="@value"/></xsl:attribute> - </xsl:otherwise> - </xsl:choose> - <!-- Print the filename and make it user-friendly by replacing the - /nix/store/<hash> prefix by the default location of nixos - sources. --> - <xsl:choose> - <xsl:when test="not(starts-with(@value, '/'))"> - <nixpkgs/<xsl:value-of select="@value"/>> - </xsl:when> - <xsl:when test="contains(@value, 'nixops') and contains(@value, '/nix/')"> - <nixops/<xsl:value-of select="substring-after(@value, '/nix/')"/>> - </xsl:when> - <xsl:otherwise> - <xsl:value-of select="@value" /> - </xsl:otherwise> - </xsl:choose> - </filename></member> - </xsl:for-each> - </simplelist> - </xsl:template> - - - <xsl:template match="function"> - <xsl:text>λ</xsl:text> - </xsl:template> - - -</xsl:stylesheet> diff --git a/nixos/doc/manual/postprocess-option-descriptions.xsl b/nixos/doc/manual/postprocess-option-descriptions.xsl deleted file mode 100644 index 1201c7612c2..00000000000 --- a/nixos/doc/manual/postprocess-option-descriptions.xsl +++ /dev/null @@ -1,115 +0,0 @@ -<?xml version="1.0"?> - -<xsl:stylesheet version="1.0" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:str="http://exslt.org/strings" - xmlns:exsl="http://exslt.org/common" - xmlns:db="http://docbook.org/ns/docbook" - xmlns:nixos="tag:nixos.org" - extension-element-prefixes="str exsl"> - <xsl:output method='xml' encoding="UTF-8" /> - - <xsl:template match="@*|node()"> - <xsl:copy> - <xsl:apply-templates select="@*|node()" /> - </xsl:copy> - </xsl:template> - - <xsl:template name="break-up-description"> - <xsl:param name="input" /> - <xsl:param name="buffer" /> - - <!-- Every time we have two newlines following each other, we want to - break it into </para><para>. --> - <xsl:variable name="parbreak" select="'

'" /> - - <!-- Similar to "(head:tail) = input" in Haskell. --> - <xsl:variable name="head" select="$input[1]" /> - <xsl:variable name="tail" select="$input[position() > 1]" /> - - <xsl:choose> - <xsl:when test="$head/self::text() and contains($head, $parbreak)"> - <!-- If the haystack provided to str:split() directly starts or - ends with $parbreak, it doesn't generate a <token/> for that, - so we are doing this here. --> - <xsl:variable name="splitted-raw"> - <xsl:if test="starts-with($head, $parbreak)"><token /></xsl:if> - <xsl:for-each select="str:split($head, $parbreak)"> - <token><xsl:value-of select="node()" /></token> - </xsl:for-each> - <!-- Something like ends-with($head, $parbreak), but there is - no ends-with() in XSLT, so we need to use substring(). --> - <xsl:if test=" - substring($head, string-length($head) - - string-length($parbreak) + 1) = $parbreak - "><token /></xsl:if> - </xsl:variable> - <xsl:variable name="splitted" - select="exsl:node-set($splitted-raw)/token" /> - <!-- The buffer we had so far didn't contain any text nodes that - contain a $parbreak, so we can put the buffer along with the - first token of $splitted into a para element. --> - <para xmlns="http://docbook.org/ns/docbook"> - <xsl:apply-templates select="exsl:node-set($buffer)" /> - <xsl:apply-templates select="$splitted[1]/node()" /> - </para> - <!-- We have already emitted the first splitted result, so the - last result is going to be set as the new $buffer later - because its contents may not be directly followed up by a - $parbreak. --> - <xsl:for-each select="$splitted[position() > 1 - and position() < last()]"> - <para xmlns="http://docbook.org/ns/docbook"> - <xsl:apply-templates select="node()" /> - </para> - </xsl:for-each> - <xsl:call-template name="break-up-description"> - <xsl:with-param name="input" select="$tail" /> - <xsl:with-param name="buffer" select="$splitted[last()]/node()" /> - </xsl:call-template> - </xsl:when> - <!-- Either non-text node or one without $parbreak, which we just - want to buffer and continue recursing. --> - <xsl:when test="$input"> - <xsl:call-template name="break-up-description"> - <xsl:with-param name="input" select="$tail" /> - <!-- This essentially appends $head to $buffer. --> - <xsl:with-param name="buffer"> - <xsl:if test="$buffer"> - <xsl:for-each select="exsl:node-set($buffer)"> - <xsl:apply-templates select="." /> - </xsl:for-each> - </xsl:if> - <xsl:apply-templates select="$head" /> - </xsl:with-param> - </xsl:call-template> - </xsl:when> - <!-- No more $input, just put the remaining $buffer in a para. --> - <xsl:otherwise> - <para xmlns="http://docbook.org/ns/docbook"> - <xsl:apply-templates select="exsl:node-set($buffer)" /> - </para> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template match="nixos:option-description"> - <xsl:choose> - <!-- - Only process nodes that are comprised of a single <para/> element, - because if that's not the case the description already contains - </para><para> in between and we need no further processing. - --> - <xsl:when test="count(db:para) > 1"> - <xsl:apply-templates select="node()" /> - </xsl:when> - <xsl:otherwise> - <xsl:call-template name="break-up-description"> - <xsl:with-param name="input" - select="exsl:node-set(db:para/node())" /> - </xsl:call-template> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - -</xsl:stylesheet> diff --git a/nixos/doc/manual/release-notes/release-notes.xml b/nixos/doc/manual/release-notes/release-notes.xml index a222bfa29d5..444862c5739 100644 --- a/nixos/doc/manual/release-notes/release-notes.xml +++ b/nixos/doc/manual/release-notes/release-notes.xml @@ -8,6 +8,8 @@ This section lists the release notes for each stable version of NixOS and current unstable revision. </para> + <xi:include href="rl-2003.xml" /> + <xi:include href="rl-1909.xml" /> <xi:include href="rl-1903.xml" /> <xi:include href="rl-1809.xml" /> <xi:include href="rl-1803.xml" /> diff --git a/nixos/doc/manual/release-notes/rl-1412.xml b/nixos/doc/manual/release-notes/rl-1412.xml index 4d93aa644c1..139f61c2a55 100644 --- a/nixos/doc/manual/release-notes/rl-1412.xml +++ b/nixos/doc/manual/release-notes/rl-1412.xml @@ -17,7 +17,7 @@ </listitem> <listitem> <para> - <link xlink:href="http://thread.gmane.org/gmane.linux.distributions.nixos/15165"> + <link xlink:href="https://www.mail-archive.com/nix-dev@lists.science.uu.nl/msg13957.html"> Nix has been updated to 1.8.</link> </para> </listitem> diff --git a/nixos/doc/manual/release-notes/rl-1509.xml b/nixos/doc/manual/release-notes/rl-1509.xml index e500c9d6342..5c4d9970178 100644 --- a/nixos/doc/manual/release-notes/rl-1509.xml +++ b/nixos/doc/manual/release-notes/rl-1509.xml @@ -627,7 +627,7 @@ nix-env -f "<nixpkgs>" -iA haskellPackages.pandoc In case of an infinite loop, use the <command>--show-trace</command> command line argument and read the line just above the error message. <screen> -$ nixos-rebuild build --show-trace +<prompt>$ </prompt>nixos-rebuild build --show-trace … while evaluating the module argument `pkgs' in "/etc/nixos/my-module.nix": infinite recursion encountered diff --git a/nixos/doc/manual/release-notes/rl-1703.xml b/nixos/doc/manual/release-notes/rl-1703.xml index 6ca79e2bc00..14b31b232e9 100644 --- a/nixos/doc/manual/release-notes/rl-1703.xml +++ b/nixos/doc/manual/release-notes/rl-1703.xml @@ -626,17 +626,17 @@ xlink:href="https://nixos.org/nixpkgs/manual/#sec-overlays-install"> overlays</link>. For example, the following code: <programlisting> - let - pkgs = import <nixpkgs> {}; - in - pkgs.overridePackages (self: super: ...) +let + pkgs = import <nixpkgs> {}; +in + pkgs.overridePackages (self: super: ...) </programlisting> should be replaced by: <programlisting> - let - pkgs = import <nixpkgs> {}; - in - import pkgs.path { overlays = [(self: super: ...)]; } +let + pkgs = import <nixpkgs> {}; +in + import pkgs.path { overlays = [(self: super: ...)]; } </programlisting> </para> </listitem> @@ -730,7 +730,7 @@ </listitem> <listitem> <para> - <literal>jre</literal> now defaults to GTK+ UI by default. This improves + <literal>jre</literal> now defaults to GTK UI by default. This improves visual consistency and makes Java follow system font style, improving the situation on HighDPI displays. This has a cost of increased closure size; for server and other headless workloads it's recommended to use diff --git a/nixos/doc/manual/release-notes/rl-1809.xml b/nixos/doc/manual/release-notes/rl-1809.xml index c5521735428..3f10b26223d 100644 --- a/nixos/doc/manual/release-notes/rl-1809.xml +++ b/nixos/doc/manual/release-notes/rl-1809.xml @@ -477,6 +477,48 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull' <itemizedlist> <listitem> <para> + Some licenses that were incorrectly not marked as unfree now are. This is + the case for: + <itemizedlist> + <listitem> + <para> + cc-by-nc-sa-20: Creative Commons Attribution Non Commercial Share Alike + 2.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-25: Creative Commons Attribution Non Commercial Share Alike + 2.5 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-30: Creative Commons Attribution Non Commercial Share Alike + 3.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nc-sa-40: Creative Commons Attribution Non Commercial Share Alike + 4.0 + </para> + </listitem> + <listitem> + <para> + cc-by-nd-30: Creative Commons Attribution-No Derivative Works v3.00 + </para> + </listitem> + <listitem> + <para> + msrla: Microsoft Research License Agreement + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> The deprecated <varname>services.cassandra</varname> module has seen a complete rewrite. (See above.) </para> @@ -595,6 +637,12 @@ $ nix-instantiate -E '(import <nixpkgsunstable> {}).gitFull' anyways for clarity. </para> </listitem> + <listitem> + <para> + Groups <literal>kvm</literal> and <literal>render</literal> are introduced + now, as systemd requires them. + </para> + </listitem> </itemizedlist> </section> diff --git a/nixos/doc/manual/release-notes/rl-1903.xml b/nixos/doc/manual/release-notes/rl-1903.xml index 1f26d4765b9..8ff1681d3b4 100644 --- a/nixos/doc/manual/release-notes/rl-1903.xml +++ b/nixos/doc/manual/release-notes/rl-1903.xml @@ -3,7 +3,7 @@ xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:id="sec-release-19.03"> - <title>Release 19.03 (“Koi”, 2019/03/??)</title> + <title>Release 19.03 (“Koi”, 2019/04/11)</title> <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" @@ -19,7 +19,59 @@ <itemizedlist> <listitem> - <para /> + <para> + End of support is planned for end of October 2019, handing over to 19.09. + </para> + </listitem> + <listitem> + <para> + The default Python 3 interpreter is now CPython 3.7 instead of CPython + 3.6. + </para> + </listitem> + <listitem> + <para> + Added the Pantheon desktop environment. It can be enabled through + <varname>services.xserver.desktopManager.pantheon.enable</varname>. + </para> + <note> + <para> + By default, <varname>services.xserver.desktopManager.pantheon</varname> + enables LightDM as a display manager, as pantheon's screen locking + implementation relies on it. + </para> + <para> + Because of that it is recommended to leave LightDM enabled. If you'd like + to disable it anyway, set + <option>services.xserver.displayManager.lightdm.enable</option> to + <literal>false</literal> and enable your preferred display manager. + </para> + </note> + <para> + Also note that Pantheon's LightDM greeter is not enabled by default, + because it has numerous issues in NixOS and isn't optimal for use here + yet. + </para> + </listitem> + <listitem> + <para> + A major refactoring of the Kubernetes module has been completed. + Refactorings primarily focus on decoupling components and enhancing + security. Two-way TLS and RBAC has been enabled by default for all + components, which slightly changes the way the module is configured. See: + <xref linkend="sec-kubernetes"/> for details. + </para> + </listitem> + <listitem> + <para> + There is now a set of <option>confinement</option> options for + <option>systemd.services</option>, which allows to restrict services + into a <citerefentry> + <refentrytitle>chroot</refentrytitle> + <manvolnum>2</manvolnum> + </citerefentry>ed environment that only contains the store paths from + the runtime closure of the service. + </para> </listitem> </itemizedlist> </section> @@ -37,7 +89,49 @@ <itemizedlist> <listitem> - <para /> + <para> + <literal>./programs/nm-applet.nix</literal> + </para> + </listitem> + <listitem> + <para> + There is a new <varname>security.googleOsLogin</varname> module for using + <link xlink:href="https://cloud.google.com/compute/docs/instances/managing-instance-access">OS + Login</link> to manage SSH access to Google Compute Engine instances, + which supersedes the imperative and broken + <literal>google-accounts-daemon</literal> used in + <literal>nixos/modules/virtualisation/google-compute-config.nix</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>./services/misc/beanstalkd.nix</literal> + </para> + </listitem> + <listitem> + <para> + There is a new <varname>services.cockroachdb</varname> module for running + CockroachDB databases. NixOS now ships with CockroachDB 2.1.x as well, + available on <literal>x86_64-linux</literal> and + <literal>aarch64-linux</literal>. + </para> + </listitem> + </itemizedlist> + + <itemizedlist> + <listitem> + <para> + <literal>./security/duosec.nix</literal> + </para> + </listitem> + <listitem> + <para> + The <link xlink:href="https://duo.com/docs/duounix">PAM module for Duo + Security</link> has been enabled for use. One can configure it using the + <option>security.duosec</option> options along with the corresponding PAM + option in + <option>security.pam.services.<name?>.duoSecurity.enable</option>. + </para> </listitem> </itemizedlist> </section> @@ -101,10 +195,346 @@ </listitem> <listitem> <para> + The <varname>buildPythonPackage</varname> function now sets + <varname>strictDeps = true</varname> to help distinguish between native + and non-native dependencies in order to improve cross-compilation + compatibility. Note however that this may break user expressions. + </para> + </listitem> + <listitem> + <para> + The <varname>buildPythonPackage</varname> function now sets <varname>LANG + = C.UTF-8</varname> to enable Unicode support. The + <varname>glibcLocales</varname> package is no longer needed as a build + input. + </para> + </listitem> + <listitem> + <para> + The Syncthing state and configuration data has been moved from + <varname>services.syncthing.dataDir</varname> to the newly defined + <varname>services.syncthing.configDir</varname>, which default to + <literal>/var/lib/syncthing/.config/syncthing</literal>. This change makes + possible to share synced directories using ACLs without Syncthing + resetting the permission on every start. + </para> + </listitem> + <listitem> + <para> + The <literal>ntp</literal> module now has sane default restrictions. If + you're relying on the previous defaults, which permitted all queries and + commands from all firewall-permitted sources, you can set + <varname>services.ntp.restrictDefault</varname> and + <varname>services.ntp.restrictSource</varname> to <literal>[]</literal>. + </para> + </listitem> + <listitem> + <para> Package <varname>rabbitmq_server</varname> is renamed to <varname>rabbitmq-server</varname>. </para> </listitem> + <listitem> + <para> + The <literal>light</literal> module no longer uses setuid binaries, but + udev rules. As a consequence users of that module have to belong to the + <literal>video</literal> group in order to use the executable (i.e. + <literal>users.users.yourusername.extraGroups = ["video"];</literal>). + </para> + </listitem> + <listitem> + <para> + Buildbot now supports Python 3 and its packages have been moved to + <literal>pythonPackages</literal>. The options + <option>services.buildbot-master.package</option> and + <option>services.buildbot-worker.package</option> can be used to select + the Python 2 or 3 version of the package. + </para> + </listitem> + <listitem> + <para> + Options + <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.userName</literal> + and + <literal>services.znc.confOptions.networks.<replaceable>name</replaceable>.modulePackages</literal> + were removed. They were never used for anything and can therefore safely + be removed. + </para> + </listitem> + <listitem> + <para> + Package <literal>wasm</literal> has been renamed + <literal>proglodyte-wasm</literal>. The package <literal>wasm</literal> + will be pointed to <literal>ocamlPackages.wasm</literal> in 19.09, so make + sure to update your configuration if you want to keep + <literal>proglodyte-wasm</literal> + </para> + </listitem> + <listitem> + <para> + When the <literal>nixpkgs.pkgs</literal> option is set, NixOS will no + longer ignore the <literal>nixpkgs.overlays</literal> option. The old + behavior can be recovered by setting <literal>nixpkgs.overlays = + lib.mkForce [];</literal>. + </para> + </listitem> + <listitem> + <para> + OpenSMTPD has been upgraded to version 6.4.0p1. This release makes + backwards-incompatible changes to the configuration file format. See + <command>man smtpd.conf</command> for more information on the new file + format. + </para> + </listitem> + <listitem> + <para> + The versioned <varname>postgresql</varname> have been renamed to use + underscore number seperators. For example, <varname>postgresql96</varname> + has been renamed to <varname>postgresql_9_6</varname>. + </para> + </listitem> + <listitem> + <para> + Package <literal>consul-ui</literal> and passthrough + <literal>consul.ui</literal> have been removed. The package + <literal>consul</literal> now uses upstream releases that vendor the UI + into the binary. See + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/48714#issuecomment-433454834">#48714</link> + for details. + </para> + </listitem> + <listitem> + <para> + Slurm introduces the new option + <literal>services.slurm.stateSaveLocation</literal>, which is now set to + <literal>/var/spool/slurm</literal> by default (instead of + <literal>/var/spool</literal>). Make sure to move all files to the new + directory or to set the option accordingly. + </para> + <para> + The slurmctld now runs as user <literal>slurm</literal> instead of + <literal>root</literal>. If you want to keep slurmctld running as + <literal>root</literal>, set <literal>services.slurm.user = + root</literal>. + </para> + <para> + The options <literal>services.slurm.nodeName</literal> and + <literal>services.slurm.partitionName</literal> are now sets of strings to + correctly reflect that fact that each of these options can occour more + than once in the configuration. + </para> + </listitem> + <listitem> + <para> + The <literal>solr</literal> package has been upgraded from 4.10.3 to 7.5.0 + and has undergone some major changes. The <literal>services.solr</literal> + module has been updated to reflect these changes. Please review + http://lucene.apache.org/solr/ carefully before upgrading. + </para> + </listitem> + <listitem> + <para> + Package <literal>ckb</literal> is renamed to <literal>ckb-next</literal>, + and options <literal>hardware.ckb.*</literal> are renamed to + <literal>hardware.ckb-next.*</literal>. + </para> + </listitem> + <listitem> + <para> + The option + <literal>services.xserver.displayManager.job.logToFile</literal> which was + previously set to <literal>true</literal> when using the display managers + <literal>lightdm</literal>, <literal>sddm</literal> or + <literal>xpra</literal> has been reset to the default value + (<literal>false</literal>). + </para> + </listitem> + <listitem> + <para> + Network interface indiscriminate NixOS firewall options + (<literal>networking.firewall.allow*</literal>) are now preserved when + also setting interface specific rules such as + <literal>networking.firewall.interfaces.en0.allow*</literal>. These rules + continue to use the pseudo device "default" + (<literal>networking.firewall.interfaces.default.*</literal>), and + assigning to this pseudo device will override the + (<literal>networking.firewall.allow*</literal>) options. + </para> + </listitem> + <listitem> + <para> + The <literal>nscd</literal> service now disables all caching of + <literal>passwd</literal> and <literal>group</literal> databases by + default. This was interferring with the correct functioning of the + <literal>libnss_systemd.so</literal> module which is used by + <literal>systemd</literal> to manage uids and usernames in the presence of + <literal>DynamicUser=</literal> in systemd services. This was already the + default behaviour in presence of <literal>services.sssd.enable = + true</literal> because nscd caching would interfere with + <literal>sssd</literal> in unpredictable ways as well. Because we're using + nscd not for caching, but for convincing glibc to find NSS modules in the + nix store instead of an absolute path, we have decided to disable caching + globally now, as it's usually not the behaviour the user wants and can + lead to surprising behaviour. Furthermore, negative caching of host + lookups is also disabled now by default. This should fix the issue of dns + lookups failing in the presence of an unreliable network. + </para> + <para> + If the old behaviour is desired, this can be restored by setting the + <literal>services.nscd.config</literal> option with the desired caching + parameters. +<programlisting> + services.nscd.config = + '' + server-user nscd + threads 1 + paranoia no + debug-level 0 + + enable-cache passwd yes + positive-time-to-live passwd 600 + negative-time-to-live passwd 20 + suggested-size passwd 211 + check-files passwd yes + persistent passwd no + shared passwd yes + + enable-cache group yes + positive-time-to-live group 3600 + negative-time-to-live group 60 + suggested-size group 211 + check-files group yes + persistent group no + shared group yes + + enable-cache hosts yes + positive-time-to-live hosts 600 + negative-time-to-live hosts 5 + suggested-size hosts 211 + check-files hosts yes + persistent hosts no + shared hosts yes + ''; + </programlisting> + See + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/50316">#50316</link> + for details. + </para> + </listitem> + <listitem> + <para> + GitLab Shell previously used the nix store paths for the + <literal>gitlab-shell</literal> command in its + <literal>authorized_keys</literal> file, which might stop working after + garbage collection. To circumvent that, we regenerated that file on each + startup. As <literal>gitlab-shell</literal> has now been changed to use + <literal>/var/run/current-system/sw/bin/gitlab-shell</literal>, this is + not necessary anymore, but there might be leftover lines with a nix store + path. Regenerate the <literal>authorized_keys</literal> file via + <command>sudo -u git -H gitlab-rake gitlab:shell:setup</command> in that + case. + </para> + </listitem> + <listitem> + <para> + The <literal>pam_unix</literal> account module is now loaded with its + control field set to <literal>required</literal> instead of + <literal>sufficient</literal>, so that later PAM account modules that + might do more extensive checks are being executed. Previously, the whole + account module verification was exited prematurely in case a nss module + provided the account name to <literal>pam_unix</literal>. The LDAP and + SSSD NixOS modules already add their NSS modules when enabled. In case + your setup breaks due to some later PAM account module previosuly + shadowed, or failing NSS lookups, please file a bug. You can get back the + old behaviour by manually setting <literal> +<![CDATA[security.pam.services.<name?>.text]]> + </literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>pam_unix</literal> password module is now loaded with its + control field set to <literal>sufficient</literal> instead of + <literal>required</literal>, so that password managed only by later PAM + password modules are being executed. Previously, for example, changing an + LDAP account's password through PAM was not possible: the whole password + module verification was exited prematurely by <literal>pam_unix</literal>, + preventing <literal>pam_ldap</literal> to manage the password as it + should. + </para> + </listitem> + <listitem> + <para> + <literal>fish</literal> has been upgraded to 3.0. It comes with a number + of improvements and backwards incompatible changes. See the + <literal>fish</literal> + <link xlink:href="https://github.com/fish-shell/fish-shell/releases/tag/3.0.0">release + notes</link> for more information. + </para> + </listitem> + <listitem> + <para> + The ibus-table input method has had a change in config format, which + causes all previous settings to be lost. See + <link xlink:href="https://github.com/mike-fabian/ibus-table/commit/f9195f877c5212fef0dfa446acb328c45ba5852b">this + commit message</link> for details. + </para> + </listitem> + <listitem> + <para> + NixOS module system type <literal>types.optionSet</literal> and + <literal>lib.mkOption</literal> argument <literal>options</literal> are + deprecated. Use <literal>types.submodule</literal> instead. + (<link xlink:href="https://github.com/NixOS/nixpkgs/pull/54637">#54637</link>) + </para> + </listitem> + <listitem> + <para> + <literal>matrix-synapse</literal> has been updated to version 0.99. It + will <link xlink:href="https://github.com/matrix-org/synapse/pull/4509">no + longer generate a self-signed certificate on first launch</link> and will + be + <link xlink:href="https://matrix.org/blog/2019/02/05/synapse-0-99-0/">the + last version to accept self-signed certificates</link>. As such, it is now + recommended to use a proper certificate verified by a root CA (for example + Let's Encrypt). The new <link linkend="module-services-matrix">manual + chapter on Matrix</link> contains a working example of using nginx as a + reverse proxy in front of <literal>matrix-synapse</literal>, using Let's + Encrypt certificates. + </para> + </listitem> + <listitem> + <para> + <literal>mailutils</literal> now works by default when + <literal>sendmail</literal> is not in a setuid wrapper. As a consequence, + the <literal>sendmailPath</literal> argument, having lost its main use, + has been removed. + </para> + </listitem> + <listitem> + <para> + <literal>graylog</literal> has been upgraded from version 2.* to 3.*. Some + setups making use of extraConfig (especially those exposing Graylog via + reverse proxies) need to be updated as upstream removed/replaced some + settings. See + <link xlink:href="http://docs.graylog.org/en/3.0/pages/upgrade/graylog-3.0.html#simplified-http-interface-configuration">Upgrading + Graylog</link> for details. + </para> + </listitem> + <listitem> + <para> + The option <literal>users.ldap.bind.password</literal> was renamed to <literal>users.ldap.bind.passwordFile</literal>, + and needs to be readable by the <literal>nslcd</literal> user. + Same applies to the new <literal>users.ldap.daemon.rootpwmodpwFile</literal> option. + </para> + </listitem> + <listitem> + <para> + <literal>nodejs-6_x</literal> is end-of-life. + <literal>nodejs-6_x</literal>, <literal>nodejs-slim-6_x</literal> and + <literal>nodePackages_6_x</literal> are removed. + </para> + </listitem> </itemizedlist> </section> @@ -117,7 +547,221 @@ <itemizedlist> <listitem> - <para /> + <para> + The <option>services.matomo</option> module gained the option + <option>services.matomo.package</option> which determines the used Matomo + version. + </para> + <para> + The Matomo module now also comes with the systemd service + <literal>matomo-archive-processing.service</literal> and a timer that + automatically triggers archive processing every hour. This means that you + can safely + <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour"> + disable browser triggers for Matomo archiving </link> at + <literal>Administration > System > General Settings</literal>. + </para> + <para> + Additionally, you can enable to + <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs"> + delete old visitor logs </link> at <literal>Administration > System > + Privacy</literal>, but make sure that you run <literal>systemctl start + matomo-archive-processing.service</literal> at least once without errors + if you have already collected data before, so that the reports get + archived before the source data gets deleted. + </para> + </listitem> + <listitem> + <para> + <literal>composableDerivation</literal> along with supporting library + functions has been removed. + </para> + </listitem> + <listitem> + <para> + The deprecated <literal>truecrypt</literal> package has been removed and + <literal>truecrypt</literal> attribute is now an alias for + <literal>veracrypt</literal>. VeraCrypt is backward-compatible with + TrueCrypt volumes. Note that <literal>cryptsetup</literal> also supports + loading TrueCrypt volumes. + </para> + </listitem> + <listitem> + <para> + The Kubernetes DNS addons, kube-dns, has been replaced with CoreDNS. This + change is made in accordance with Kubernetes making CoreDNS the official + default starting from + <link xlink:href="https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG-1.11.md#sig-cluster-lifecycle">Kubernetes + v1.11</link>. Please beware that upgrading DNS-addon on existing clusters + might induce minor downtime while the DNS-addon terminates and + re-initializes. Also note that the DNS-service now runs with 2 pod + replicas by default. The desired number of replicas can be configured + using: <option>services.kubernetes.addons.dns.replicas</option>. + </para> + </listitem> + <listitem> + <para> + The quassel-webserver package and module was removed from nixpkgs due to + the lack of maintainers. + </para> + </listitem> + <listitem> + <para> + The manual gained a <link linkend="module-services-matrix"> new chapter on + self-hosting <literal>matrix-synapse</literal> and + <literal>riot-web</literal> </link>, the most prevalent server and client + implementations for the + <link xlink:href="https://matrix.org/">Matrix</link> federated + communication network. + </para> + </listitem> + <listitem> + <para> + The astah-community package was removed from nixpkgs due to it being + discontinued and the downloads not being available anymore. + </para> + </listitem> + <listitem> + <para> + The httpd service now saves log files with a .log file extension by + default for easier integration with the logrotate service. + </para> + </listitem> + <listitem> + <para> + The owncloud server packages and httpd subservice module were removed from + nixpkgs due to the lack of maintainers. + </para> + </listitem> + <listitem> + <para> + It is possible now to uze ZRAM devices as general purpose ephemeral block + devices, not only as swap. Using more than 1 device as ZRAM swap is no + longer recommended, but is still possible by setting + <literal>zramSwap.swapDevices</literal> explicitly. + </para> + <para> + ZRAM algorithm can be changed now. + </para> + <para> + Changes to ZRAM algorithm are applied during <literal>nixos-rebuild + switch</literal>, so make sure you have enough swap space on disk to + survive ZRAM device rebuild. Alternatively, use <literal>nixos-rebuild + boot; reboot</literal>. + </para> + </listitem> + <listitem> + <para> + Flat volumes are now disabled by default in + <literal>hardware.pulseaudio</literal>. This has been done to prevent + applications, which are unaware of this feature, setting their volumes to + 100% on startup causing harm to your audio hardware and potentially your + ears. + </para> + <note> + <para> + With this change application specific volumes are relative to the master + volume which can be adjusted independently, whereas before they were + absolute; meaning that in effect, it scaled the device-volume with the + volume of the loudest application. + </para> + </note> + </listitem> + <listitem> + <para> + The + <link xlink:href="https://github.com/DanielAdolfsson/ndppd"><literal>ndppd</literal></link> + module now supports <link linkend="opt-services.ndppd.enable">all config + options</link> provided by the current upstream version as service + options. Additionally the <literal>ndppd</literal> package doesn't contain + the systemd unit configuration from upstream anymore, the unit is + completely configured by the NixOS module now. + </para> + </listitem> + <listitem> + <para> + New installs of NixOS will default to the Redmine 4.x series unless + otherwise specified in <literal>services.redmine.package</literal> while + existing installs of NixOS will default to the Redmine 3.x series. + </para> + </listitem> + <listitem> + <para> + The <link linkend="opt-services.grafana.enable">Grafana module</link> now + supports declarative + <link xlink:href="http://docs.grafana.org/administration/provisioning/">datasource + and dashboard</link> provisioning. + </para> + </listitem> + <listitem> + <para> + The use of insecure ports on kubernetes has been deprecated. Thus options: + <varname>services.kubernetes.apiserver.port</varname> and + <varname>services.kubernetes.controllerManager.port</varname> has been + renamed to <varname>.insecurePort</varname>, and default of both options + has changed to 0 (disabled). + </para> + </listitem> + <listitem> + <para> + Note that the default value of + <varname>services.kubernetes.apiserver.bindAddress</varname> has changed + from 127.0.0.1 to 0.0.0.0, allowing the apiserver to be accessible from + outside the master node itself. If the apiserver insecurePort is enabled, + it is strongly recommended to only bind on the loopback interface. See: + <varname>services.kubernetes.apiserver.insecurebindAddress</varname>. + </para> + </listitem> + <listitem> + <para> + The option + <varname>services.kubernetes.apiserver.allowPrivileged</varname> and + <varname>services.kubernetes.kubelet.allowPrivileged</varname> now + defaults to false. Disallowing privileged containers on the cluster. + </para> + </listitem> + <listitem> + <para> + The kubernetes module does no longer add the kubernetes package to + <varname>environment.systemPackages</varname> implicitly. + </para> + </listitem> + <listitem> + <para> + The <literal>intel</literal> driver has been removed from the default list + of <link linkend="opt-services.xserver.videoDrivers">X.org video + drivers</link>. The <literal>modesetting</literal> driver should take over + automatically, it is better maintained upstream and has less problems with + advanced X11 features. This can lead to a change in the output names used + by <literal>xrandr</literal>. Some performance regressions on some GPU + models might happen. Some OpenCL and VA-API applications might also break + (Beignet seems to provide OpenCL support with + <literal>modesetting</literal> driver, too). Kernel mode setting API does + not support backlight control, so <literal>xbacklight</literal> tool will + not work; backlight level can be controlled directly via + <literal>/sys/</literal> or with <literal>brightnessctl</literal>. Users + who need this functionality more than multi-output XRandR are advised to + add `intel` to `videoDrivers` and report an issue (or provide additional + details in an existing one) + </para> + </listitem> + <listitem> + <para> + Openmpi has been updated to version 4.0.0, which removes some deprecated + MPI-1 symbols. This may break some older applications that still rely on + those symbols. An upgrade guide can be found + <link xlink:href="https://www.open-mpi.org/faq/?category=mpi-removed">here</link>. + </para> + <para> + The nginx package now relies on OpenSSL 1.1 and supports TLS 1.3 by + default. You can set the protocols used by the nginx service using + <xref linkend="opt-services.nginx.sslProtocols"/>. + </para> + </listitem> + <listitem> + <para> + A new subcommand <command>nixos-rebuild edit</command> was added. + </para> </listitem> </itemizedlist> </section> diff --git a/nixos/doc/manual/release-notes/rl-1909.xml b/nixos/doc/manual/release-notes/rl-1909.xml new file mode 100644 index 00000000000..8bd353a3430 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-1909.xml @@ -0,0 +1,902 @@ +<section 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-release-19.09"> + <title>Release 19.09 (“Loris”, 2019/10/09)</title> + + <section 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-release-19.09-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + End of support is planned for end of April 2020, handing over to 20.03. + </para> + </listitem> + <listitem> + <para> + Nix has been updated to 2.3; see its + <link xlink:href="https://nixos.org/nix/manual/#ssec-relnotes-2.3">release + notes</link>. + </para> + </listitem> + <listitem> + <para>Core version changes:</para> + <para>systemd: 239 -> 243</para> + <para>gcc: 7 -> 8</para> + <para>glibc: 2.27 (unchanged)</para> + <para>linux: 4.19 LTS (unchanged)</para> + <para>openssl: 1.0 -> 1.1</para> + </listitem> + <listitem> + <para>Desktop version changes:</para> + <para>plasma5: 5.14 -> 5.16</para> + <para>gnome3: 3.30 -> 3.32</para> + </listitem> + <listitem> + <para> + PHP now defaults to PHP 7.3, updated from 7.2. + </para> + </listitem> + <listitem> + <para> + PHP 7.1 is no longer supported due to upstream not supporting this version for the entire lifecycle of the 19.09 release. + </para> + </listitem> + <listitem> + <para> + The binfmt module is now easier to use. Additional systems can + be added through <option>boot.binfmt.emulatedSystems</option>. + For instance, <literal>boot.binfmt.emulatedSystems = [ + "wasm32-wasi" "x86_64-windows" "aarch64-linux" ];</literal> will + set up binfmt interpreters for each of those listed systems. + </para> + </listitem> + <listitem> + <para> + The installer now uses a less privileged <literal>nixos</literal> user whereas before we logged in as root. + To gain root privileges use <literal>sudo -i</literal> without a password. + </para> + </listitem> + <listitem> + <para> + We've updated to Xfce 4.14, which brings a new module <option>services.xserver.desktopManager.xfce4-14</option>. + If you'd like to upgrade, please switch from the <option>services.xserver.desktopManager.xfce</option> module as it + will be deprecated in a future release. They're incompatibilities with the current Xfce module; it doesn't support + <option>thunarPlugins</option> and it isn't recommended to use <option>services.xserver.desktopManager.xfce</option> + and <option>services.xserver.desktopManager.xfce4-14</option> simultaneously or to downgrade from Xfce 4.14 after upgrading. + </para> + </listitem> + <listitem> + <para> + The GNOME 3 desktop manager module sports an interface to enable/disable core services, applications, and optional GNOME packages + like games. + <itemizedlist> + <para>This can be achieved with the following options which the desktop manager default enables, excluding <literal>games</literal>.</para> + <listitem><para><xref linkend="opt-services.gnome3.core-os-services.enable"/></para></listitem> + <listitem><para><xref linkend="opt-services.gnome3.core-shell.enable"/></para></listitem> + <listitem><para><xref linkend="opt-services.gnome3.core-utilities.enable"/></para></listitem> + <listitem><para><xref linkend="opt-services.gnome3.games.enable"/></para></listitem> + </itemizedlist> + With these options we hope to give users finer grained control over their systems. Prior to this change you'd either have to manually + disable options or use <option>environment.gnome3.excludePackages</option> which only excluded the optional applications. + <option>environment.gnome3.excludePackages</option> is now unguarded, it can exclude any package installed with <option>environment.systemPackages</option> + in the GNOME 3 module. + </para> + </listitem> + <listitem> + <para> + Orthogonal to the previous changes to the GNOME 3 desktop manager module, we've updated all default services and applications + to match as close as possible to a default reference GNOME 3 experience. + </para> + + <bridgehead>The following changes were enacted in <option>services.gnome3.core-utilities.enable</option></bridgehead> + + <itemizedlist> + <title>Applications removed from defaults:</title> + <listitem><para><literal>accerciser</literal></para></listitem> + <listitem><para><literal>dconf-editor</literal></para></listitem> + <listitem><para><literal>evolution</literal></para></listitem> + <listitem><para><literal>gnome-documents</literal></para></listitem> + <listitem><para><literal>gnome-nettool</literal></para></listitem> + <listitem><para><literal>gnome-power-manager</literal></para></listitem> + <listitem><para><literal>gnome-todo</literal></para></listitem> + <listitem><para><literal>gnome-tweaks</literal></para></listitem> + <listitem><para><literal>gnome-usage</literal></para></listitem> + <listitem><para><literal>gucharmap</literal></para></listitem> + <listitem><para><literal>nautilus-sendto</literal></para></listitem> + <listitem><para><literal>vinagre</literal></para></listitem> + </itemizedlist> + <itemizedlist> + <title>Applications added to defaults:</title> + <listitem><para><literal>cheese</literal></para></listitem> + <listitem><para><literal>geary</literal></para></listitem> + </itemizedlist> + + <bridgehead>The following changes were enacted in <option>services.gnome3.core-shell.enable</option></bridgehead> + + <itemizedlist> + <title>Applications added to defaults:</title> + <listitem><para><literal>gnome-color-manager</literal></para></listitem> + <listitem><para><literal>orca</literal></para></listitem> + </itemizedlist> + <itemizedlist> + <title>Services enabled:</title> + <listitem><para><option>services.avahi.enable</option></para></listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </section> + + <section 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-release-19.09-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>./programs/dwm-status.nix</literal> + </para> + </listitem> + <listitem> + <para> + The new <varname>hardware.printers</varname> module allows to declaratively configure CUPS printers + via the <varname>ensurePrinters</varname> and + <varname>ensureDefaultPrinter</varname> options. + <varname>ensurePrinters</varname> will never delete existing printers, + but will make sure that the given printers are configured as declared. + </para> + </listitem> + <listitem> + <para> + There is a new <xref linkend="opt-services.system-config-printer.enable"/> and <xref linkend="opt-programs.system-config-printer.enable"/> module + for the program of the same name. If you previously had <literal>system-config-printer</literal> enabled through some other + means you should migrate to using one of these modules. + </para> + <itemizedlist> + <para>If you're a user of the following desktopManager modules no action is needed:</para> + <listitem> + <para><option>services.xserver.desktopManager.plasma5</option></para> + </listitem> + <listitem> + <para><option>services.xserver.desktopManager.gnome3</option></para> + </listitem> + <listitem> + <para><option>services.xserver.desktopManager.pantheon</option></para> + </listitem> + <listitem> + <para><option>services.xserver.desktopManager.mate</option></para> + <para> + Note Mate uses <literal>programs.system-config-printer</literal> as it doesn't + use it as a service, but its graphical interface directly. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + <xref linkend="opt-services.blueman.enable"/> has been added. + If you previously had blueman installed via <option>environment.systemPackages</option> please + migrate to using the NixOS module, as this would result in an insufficiently configured blueman. + </para> + </listitem> + </itemizedlist> + + </section> + + <section 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-release-19.09-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + Buildbot no longer supports Python 2, as support was dropped upstream in + version 2.0.0. Configurations may need to be modified to make them + compatible with Python 3. + </para> + </listitem> + <listitem> + <para> + PostgreSQL now uses + <filename class="directory">/run/postgresql</filename> as its socket + directory instead of <filename class="directory">/tmp</filename>. So + if you run an application like eg. Nextcloud, where you need to use + the Unix socket path as the database host name, you need to change it + accordingly. + </para> + </listitem> + <listitem> + <para> + PostgreSQL 9.4 is scheduled EOL during the 19.09 life cycle and has been removed. + </para> + </listitem> + <listitem> + <para> + The options <option>services.prometheus.alertmanager.user</option> and + <option>services.prometheus.alertmanager.group</option> have been removed + because the alertmanager service is now using systemd's <link + xlink:href="http://0pointer.net/blog/dynamic-users-with-systemd.html"> + DynamicUser mechanism</link> which obviates these options. + </para> + </listitem> + <listitem> + <para> + The NetworkManager systemd unit was renamed back from network-manager.service to + NetworkManager.service for better compatibility with other applications expecting this name. + The same applies to ModemManager where modem-manager.service is now called ModemManager.service again. + </para> + </listitem> + <listitem> + <para> + The <option>services.nzbget.configFile</option> and <option>services.nzbget.openFirewall</option> + options were removed as they are managed internally by the nzbget. The + <option>services.nzbget.dataDir</option> option hadn't actually been used by + the module for some time and so was removed as cleanup. + </para> + </listitem> + <listitem> + <para> + The <option>services.mysql.pidDir</option> option was removed, as it was only used by the wordpress + apache-httpd service to wait for mysql to have started up. + This can be accomplished by either describing a dependency on mysql.service (preferred) + or waiting for the (hardcoded) <filename>/run/mysqld/mysql.sock</filename> file to appear. + </para> + </listitem> + <listitem> + <para> + The <option>services.emby.enable</option> module has been removed, see + <option>services.jellyfin.enable</option> instead for a free software fork of Emby. + + See the Jellyfin documentation: + <link xlink:href="https://jellyfin.readthedocs.io/en/latest/administrator-docs/migrate-from-emby/"> + Migrating from Emby to Jellyfin + </link> + </para> + </listitem> + <listitem> + <para> + IPv6 Privacy Extensions are now enabled by default for undeclared + interfaces. The previous behaviour was quite misleading — even though + the default value for + <option>networking.interfaces.*.preferTempAddress</option> was + <literal>true</literal>, undeclared interfaces would not prefer temporary + addresses. Now, interfaces not mentioned in the config will prefer + temporary addresses. EUI64 addresses can still be set as preferred by + explicitly setting the option to <literal>false</literal> for the + interface in question. + </para> + </listitem> + <listitem> + <para> + Since Bittorrent Sync was superseded by Resilio Sync in 2016, the + <literal>bittorrentSync</literal>, <literal>bittorrentSync14</literal>, + and <literal>bittorrentSync16</literal> packages have been removed in + favor of <literal>resilio-sync</literal>. + </para> + <para> + The corresponding module, <option>services.btsync</option> has been + replaced by the <option>services.resilio</option> module. + </para> + </listitem> + <listitem> + <para> + The httpd service no longer attempts to start the postgresql service. If you have come to depend + on this behaviour then you can preserve the behavior with the following configuration: + <literal>systemd.services.httpd.after = [ "postgresql.service" ];</literal> + </para> + <para> + The option <option>services.httpd.extraSubservices</option> has been + marked as deprecated. You may still use this feature, but it will be + removed in a future release of NixOS. You are encouraged to convert any + httpd subservices you may have written to a full NixOS module. + </para> + <para> + Most of the httpd subservices packaged with NixOS have been replaced with + full NixOS modules including LimeSurvey, WordPress, and Zabbix. These + modules can be enabled using the <option>services.limesurvey.enable</option>, + <option>services.mediawiki.enable</option>, <option>services.wordpress.enable</option>, + and <option>services.zabbixWeb.enable</option> options. + </para> + </listitem> + <listitem> + <para> + The option <option>systemd.network.networks.<name>.routes.*.routeConfig.GatewayOnlink</option> + was renamed to <option>systemd.network.networks.<name>.routes.*.routeConfig.GatewayOnLink</option> + (capital <literal>L</literal>). This follows + <link xlink:href="https://github.com/systemd/systemd/commit/9cb8c5593443d24c19e40bfd4fc06d672f8c554c"> + upstreams renaming + </link> of the setting. + </para> + </listitem> + <listitem> + <para> + As of this release the NixOps feature <literal>autoLuks</literal> is deprecated. It no longer works + with our systemd version without manual intervention. + </para> + <para> + Whenever the usage of the module is detected the evaluation will fail with a message + explaining why and how to deal with the situation. + </para> + <para> + A new knob named <literal>nixops.enableDeprecatedAutoLuks</literal> + has been introduced to disable the eval failure and to acknowledge the notice was received and read. + If you plan on using the feature please note that it might break with subsequent updates. + </para> + <para> + Make sure you set the <literal>_netdev</literal> option for each of the file systems referring to block + devices provided by the autoLuks module. Not doing this might render the system in a + state where it doesn't boot anymore. + </para> + <para> + If you are actively using the <literal>autoLuks</literal> module please let us know in + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/62211">issue #62211</link>. + </para> + </listitem> + <listitem> + <para> + The setopt declarations will be evaluated at the end of <literal>/etc/zshrc</literal>, so any code in <xref linkend="opt-programs.zsh.interactiveShellInit" />, + <xref linkend="opt-programs.zsh.loginShellInit" /> and <xref linkend="opt-programs.zsh.promptInit" /> may break if it relies on those options being set. + </para> + </listitem> + <listitem> + <para> + The <literal>prometheus-nginx-exporter</literal> package now uses the offical exporter provided by NGINX Inc. + Its metrics are differently structured and are incompatible to the old ones. For information about the metrics, + have a look at the <link xlink:href="https://github.com/nginxinc/nginx-prometheus-exporter">official repo</link>. + </para> + </listitem> + <listitem> + <para> + The <literal>shibboleth-sp</literal> package has been updated to version 3. + It is largely backward compatible, for further information refer to the + <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/ReleaseNotes">release notes</link> + and <link xlink:href="https://wiki.shibboleth.net/confluence/display/SP3/UpgradingFromV2">upgrade guide</link>. + </para> + <para> + Nodejs 8 is scheduled EOL under the lifetime of 19.09 and has been dropped. + </para> + </listitem> + <listitem> + <para> + By default, prometheus exporters are now run with <literal>DynamicUser</literal> enabled. + Exporters that need a real user, now run under a seperate user and group which follow the pattern <literal><exporter-name>-exporter</literal>, instead of the previous default <literal>nobody</literal> and <literal>nogroup</literal>. + Only some exporters are affected by the latter, namely the exporters <literal>dovecot</literal>, <literal>node</literal>, <literal>postfix</literal> and <literal>varnish</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>ibus-qt</literal> package is not installed by default anymore when <xref linkend="opt-i18n.inputMethod.enabled" /> is set to <literal>ibus</literal>. + If IBus support in Qt 4.x applications is required, add the <literal>ibus-qt</literal> package to your <xref linkend="opt-environment.systemPackages" /> manually. + </para> + </listitem> + <listitem> + <para> + The CUPS Printing service now uses socket-based activation by + default, only starting when needed. The previous behavior can + be restored by setting + <option>services.cups.startWhenNeeded</option> to + <literal>false</literal>. + </para> + </listitem> + <listitem> + <para> + The <option>services.systemhealth</option> module has been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <option>services.mantisbt</option> module has been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + Squid 3 has been removed and the <option>squid</option> derivation now refers to Squid 4. + </para> + </listitem> + <listitem> + <para> + The <option>services.pdns-recursor.extraConfig</option> option has been replaced by + <option>services.pdns-recursor.settings</option>. The new option allows setting extra + configuration while being better type-checked and mergeable. + </para> + </listitem> + <listitem> + <para> + No service depends on <literal>keys.target</literal> anymore which is a systemd + target that indicates if all <link xlink:href="https://nixos.org/nixops/manual/#idm140737322342384">NixOps keys</link> were successfully uploaded. + Instead, <literal><key-name>-key.service</literal> should be used to define + a dependency of a key in a service. The full issue behind the <literal>keys.target</literal> + dependency is described at <link xlink:href="https://github.com/NixOS/nixpkgs/issues/67265">NixOS/nixpkgs#67265</link>. + </para> + <para> + The following services are affected by this: + <itemizedlist> + <listitem><para><link linkend="opt-services.dovecot2.enable"><literal>services.dovecot2</literal></link></para></listitem> + <listitem><para><link linkend="opt-services.nsd.enable"><literal>services.nsd</literal></link></para></listitem> + <listitem><para><link linkend="opt-services.softether.enable"><literal>services.softether</literal></link></para></listitem> + <listitem><para><link linkend="opt-services.strongswan.enable"><literal>services.strongswan</literal></link></para></listitem> + <listitem><para><link linkend="opt-services.strongswan-swanctl.enable"><literal>services.strongswan-swanctl</literal></link></para></listitem> + <listitem><para><link linkend="opt-services.httpd.enable"><literal>services.httpd</literal></link></para></listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The <option>security.acme.directory</option> option has been replaced by a read-only <option>security.acme.certs.<cert>.directory</option> option for each certificate you define. This will be + a subdirectory of <literal>/var/lib/acme</literal>. You can use this read-only option to figure out where the certificates are stored for a specific certificate. For example, + the <option>services.nginx.virtualhosts.<name>.enableACME</option> option will use this directory option to find the certs for the virtual host. + </para> + <para> + <option>security.acme.preDelay</option> and <option>security.acme.activationDelay</option> options have been removed. To execute a service before certificates + are provisioned or renewed add a <literal>RequiredBy=acme-${cert}.service</literal> to any service. + </para> + <para> + Furthermore, the acme module will not automatically add a dependency on <literal>lighttpd.service</literal> anymore. If you are using certficates provided by letsencrypt + for lighttpd, then you should depend on the certificate service <literal>acme-${cert}.service></literal> manually. + </para> + <para> + For nginx, the dependencies are still automatically managed when <option>services.nginx.virtualhosts.<name>.enableACME</option> is enabled just like before. What changed is that nginx now directly depends on the specific certificates that it needs, + instead of depending on the catch-all <literal>acme-certificates.target</literal>. This target unit was also removed from the codebase. + This will mean nginx will no longer depend on certificates it isn't explicitly managing and fixes a bug with certificate renewal + ordering racing with nginx restarting which could lead to nginx getting in a broken state as described at + <link xlink:href="https://github.com/NixOS/nixpkgs/issues/60180">NixOS/nixpkgs#60180</link>. + </para> + </listitem> + <listitem> + <para> + The old deprecated <literal>emacs</literal> package sets have been dropped. + What used to be called <literal>emacsPackagesNg</literal> is now simply called <literal>emacsPackages</literal>. + </para> + </listitem> + <listitem> + <para> + <option>services.xserver.desktopManager.xterm</option> is now disabled by default if <literal>stateVersion</literal> is 19.09 or higher. + Previously the xterm desktopManager was enabled when xserver was enabled, but it isn't useful for all people so it didn't make sense to + have any desktopManager enabled default. + </para> + </listitem> + <listitem> + <para> + The WeeChat plugin <literal>pkgs.weechatScripts.weechat-xmpp</literal> has been removed as it doesn't receive + any updates from upstream and depends on outdated Python2-based modules. + </para> + </listitem> + <listitem> + <para> + Old unsupported versions (<literal>logstash5</literal>, + <literal>kibana5</literal>, + <literal>filebeat5</literal>, + <literal>heartbeat5</literal>, + <literal>metricbeat5</literal>, + <literal>packetbeat5</literal>) of the ELK-stack and Elastic beats have been removed. + </para> + </listitem> + <listitem> + <para> + For NixOS 19.03, both Prometheus 1 and 2 were available to allow for + a seamless transition from version 1 to 2 with existing setups. + Because Prometheus 1 is no longer developed, it was removed. + Prometheus 2 is now configured with <literal>services.prometheus</literal>. + </para> + </listitem> + <listitem> + <para> + Citrix Receiver (<literal>citrix_receiver</literal>) has been dropped in favor of Citrix Workspace + (<literal>citrix_workspace</literal>). + </para> + </listitem> + <listitem> + <para> + The <literal>services.gitlab</literal> module has had its literal secret options (<option>services.gitlab.smtp.password</option>, + <option>services.gitlab.databasePassword</option>, + <option>services.gitlab.initialRootPassword</option>, + <option>services.gitlab.secrets.secret</option>, + <option>services.gitlab.secrets.db</option>, + <option>services.gitlab.secrets.otp</option> and + <option>services.gitlab.secrets.jws</option>) replaced by file-based versions (<option>services.gitlab.smtp.passwordFile</option>, + <option>services.gitlab.databasePasswordFile</option>, + <option>services.gitlab.initialRootPasswordFile</option>, + <option>services.gitlab.secrets.secretFile</option>, + <option>services.gitlab.secrets.dbFile</option>, + <option>services.gitlab.secrets.otpFile</option> and + <option>services.gitlab.secrets.jwsFile</option>). This was done so that secrets aren't stored + in the world-readable nix store, but means that for each option you'll have to create a file with + the same exact string, add "File" to the end of the option name, and change the definition to a + string pointing to the corresponding file; e.g. <literal>services.gitlab.databasePassword = "supersecurepassword"</literal> + becomes <literal>services.gitlab.databasePasswordFile = "/path/to/secret_file"</literal> where the + file <literal>secret_file</literal> contains the string <literal>supersecurepassword</literal>. + </para> + <para> + The state path (<option>services.gitlab.statePath</option>) now has the following restriction: + no parent directory can be owned by any other user than <literal>root</literal> or the user + specified in <option>services.gitlab.user</option>; i.e. if <option>services.gitlab.statePath</option> + is set to <literal>/var/lib/gitlab/state</literal>, <literal>gitlab</literal> and all parent directories + must be owned by either <literal>root</literal> or the user specified in <option>services.gitlab.user</option>. + </para> + </listitem> + <listitem> + <para> + The <option>networking.useDHCP</option> option is unsupported in combination with + <option>networking.useNetworkd</option> in anticipation of defaulting to it by default. + It has to be set to <literal>false</literal> and enabled per + interface with <option>networking.interfaces.<name>.useDHCP = true;</option> + </para> + </listitem> + <listitem> + <para> + The Twitter client <literal>corebird</literal> has been dropped as <link xlink:href="https://www.patreon.com/posts/corebirds-future-18921328">it is discontinued and does not work against the new Twitter API</link>. + Please use the fork <literal>cawbird</literal> instead which has been adapted to the API changes and is still maintained. + </para> + </listitem> + <listitem> + <para> + The <literal>nodejs-11_x</literal> package has been removed as it's EOLed by upstream. + </para> + </listitem> + <listitem> + <para> + Because of the systemd upgrade, + <application>systemd-timesyncd</application> will no longer work if + <option>system.stateVersion</option> is not set correctly. When + upgrading from NixOS 19.03, please make sure that + <option>system.stateVersion</option> is set to + <literal>"19.03"</literal>, or lower if the installation dates back to an + earlier version of NixOS. + </para> + </listitem> + <listitem> + <para> + Due to the short lifetime of non-LTS kernel releases package attributes like <literal>linux_5_1</literal>, + <literal>linux_5_2</literal> and <literal>linux_5_3</literal> have been removed to discourage dependence + on specific non-LTS kernel versions in stable NixOS releases. + + Going forward, versioned attributes like <literal>linux_4_9</literal> will exist for LTS versions only. + Please use <literal>linux_latest</literal> or <literal>linux_testing</literal> if you depend on non-LTS + releases. Keep in mind that <literal>linux_latest</literal> and <literal>linux_testing</literal> will + change versions under the hood during the lifetime of a stable release and might include breaking changes. + </para> + </listitem> + <listitem> + <para> + Because of the systemd upgrade, + some network interfaces might change their name. For details see + <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.net-naming-scheme.html#History"> + upstream docs</link> or <link xlink:href="https://github.com/NixOS/nixpkgs/issues/71086"> + our ticket</link>. + </para> + </listitem> + </itemizedlist> + </section> + + <section 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-release-19.09-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para> + The <option>documentation</option> module gained an option named + <option>documentation.nixos.includeAllModules</option> which makes the + generated <citerefentry> + <refentrytitle>configuration.nix</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> manual page include all options + from all NixOS modules included in a given + <literal>configuration.nix</literal> configuration file. Currently, it is + set to <literal>false</literal> by default as enabling it frequently + prevents evaluation. But the plan is to eventually have it set to + <literal>true</literal> by default. Please set it to + <literal>true</literal> now in your <literal>configuration.nix</literal> + and fix all the bugs it uncovers. + </para> + </listitem> + <listitem> + <para> + The <literal>vlc</literal> package gained support for Chromecast + streaming, enabled by default. TCP port 8010 must be open for it to work, + so something like <literal>networking.firewall.allowedTCPPorts = [ 8010 + ];</literal> may be required in your configuration. Also consider enabling + <link xlink:href="https://nixos.wiki/wiki/Accelerated_Video_Playback"> + Accelerated Video Playback</link> for better transcoding performance. + </para> + </listitem> + <listitem> + <para> + The following changes apply if the <literal>stateVersion</literal> is + changed to 19.09 or higher. For <literal>stateVersion = "19.03"</literal> + or lower the old behavior is preserved. + </para> + <itemizedlist> + <listitem> + <para> + <literal>solr.package</literal> defaults to + <literal>pkgs.solr_8</literal>. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <literal>hunspellDicts.fr-any</literal> dictionary now ships with <literal>fr_FR.{aff,dic}</literal> + which is linked to <literal>fr-toutesvariantes.{aff,dic}</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>mysql</literal> service now runs as <literal>mysql</literal> + user. Previously, systemd did execute it as root, and mysql dropped privileges + itself. + This includes <literal>ExecStartPre=</literal> and + <literal>ExecStartPost=</literal> phases. + To accomplish that, runtime and data directory setup was delegated to + RuntimeDirectory and tmpfiles. + </para> + </listitem> + <listitem> + <para> + With the upgrade to systemd version 242 the <literal>systemd-timesyncd</literal> + service is no longer using <literal>DynamicUser=yes</literal>. In order for the + upgrade to work we rely on an activation script to move the state from the old + to the new directory. The older directory (prior <literal>19.09</literal>) was + <literal>/var/lib/private/systemd/timesync</literal>. + </para> + <para> + As long as the <literal>system.config.stateVersion</literal> is below + <literal>19.09</literal> the state folder will migrated to its proper location + (<literal>/var/lib/systemd/timesync</literal>), if required. + </para> + </listitem> + <listitem> + <para> + The package <literal>avahi</literal> is now built to look up service + definitions from <literal>/etc/avahi/services</literal> instead of its + output directory in the nix store. Accordingly the module + <option>avahi</option> now supports custom service definitions via + <option>services.avahi.extraServiceFiles</option>, which are then placed + in the aforementioned directory. See <citerefentry> + <refentrytitle>avahi.service</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> for more information on custom service definitions. + </para> + </listitem> + <listitem> + <para> + Since version 0.1.19, <literal>cargo-vendor</literal> honors package + includes that are specified in the <filename>Cargo.toml</filename> + file of Rust crates. <literal>rustPlatform.buildRustPackage</literal> uses + <literal>cargo-vendor</literal> to collect and build dependent crates. + Since this change in <literal>cargo-vendor</literal> changes the set of + vendored files for most Rust packages, the hash that use used to verify + the dependencies, <literal>cargoSha256</literal>, also changes. + </para> + <para> + The <literal>cargoSha256</literal> hashes of all in-tree derivations that + use <literal>buildRustPackage</literal> have been updated to reflect this + change. However, third-party derivations that use + <literal>buildRustPackage</literal> may have to be updated as well. + </para> + </listitem> + <listitem> + <para> + The <literal>consul</literal> package was upgraded past version <literal>1.5</literal>, + so its deprecated legacy UI is no longer available. + </para> + </listitem> + <listitem> + <para> + The default resample-method for PulseAudio has been changed from the upstream default <literal>speex-float-1</literal> + to <literal>speex-float-5</literal>. Be aware that low-powered ARM-based and MIPS-based boards will struggle with this + so you'll need to set <option>hardware.pulseaudio.daemon.config.resample-method</option> back to <literal>speex-float-1</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>phabricator</literal> package and associated <literal>httpd.extraSubservice</literal>, as well as the + <literal>phd</literal> service have been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>mercurial</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>trac</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs because it was unmaintained. + </para> + </listitem> + <listitem> + <para> + The <literal>foswiki</literal> package and associated <literal>httpd.extraSubservice</literal> have been removed + from nixpkgs due to lack of maintainer. + </para> + </listitem> + <listitem> + <para> + The <literal>tomcat-connector</literal> <literal>httpd.extraSubservice</literal> has been removed from nixpkgs. + </para> + </listitem> + <listitem> + <para> + It's now possible to change configuration in + <link linkend="opt-services.nextcloud.enable">services.nextcloud</link> after the initial deploy + since all config parameters are persisted in an additional config file generated by the module. + Previously core configuration like database parameters were set using their imperative + installer after creating <literal>/var/lib/nextcloud</literal>. + </para> + </listitem> + <listitem> + <para> + There exists now <literal>lib.forEach</literal>, which is like <literal>map</literal>, but with + arguments flipped. When mapping function body spans many lines (or has nested + <literal>map</literal>s), it is often hard to follow which list is modified. + </para> + <para> + Previous solution to this problem was either to use <literal>lib.flip map</literal> + idiom or extract that anonymous mapping function to a named one. Both can still be used + but <literal>lib.forEach</literal> is preferred over <literal>lib.flip map</literal>. + </para> + <para> + The <literal>/etc/sysctl.d/nixos.conf</literal> file containing all the options set via + <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link> was moved to + <literal>/etc/sysctl.d/60-nixos.conf</literal>, as + <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + recommends prefixing all filenames in <literal>/etc/sysctl.d</literal> with a + two-digit number and a dash to simplify the ordering of the files. + </para> + </listitem> + <listitem> + <para> + We now install the sysctl snippets shipped with systemd. + <itemizedlist> + <para>This enables:</para> + <listitem> + <para>Loose reverse path filtering</para> + </listitem> + <listitem> + <para>Source route filtering</para> + </listitem> + <listitem> + <para> + <literal>fq_codel</literal> as a packet scheduler (this helps to fight bufferbloat) + </para> + </listitem> + </itemizedlist> + This also configures the kernel to pass core dumps to <literal>systemd-coredump</literal>, + and restricts the SysRq key combinations to the sync command only. + These sysctl snippets can be found in <literal>/etc/sysctl.d/50-*.conf</literal>, + and overridden via <link linkend="opt-boot.kernel.sysctl">boot.kernel.sysctl</link> + (which will place the parameters in <literal>/etc/sysctl.d/60-nixos.conf</literal>). + </para> + </listitem> + <listitem> + <para> + Core dumps are now processed by <literal>systemd-coredump</literal> + by default. <literal>systemd-coredump</literal> behaviour can + still be modified via + <option>systemd.coredump.extraConfig</option>. To stick to the + old behaviour (having the kernel dump to a file called + <literal>core</literal> in the working directory), without piping + it through <literal>systemd-coredump</literal>, set + <option>systemd.coredump.enable</option> to + <literal>false</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>systemd.packages</literal> option now also supports generators and + shutdown scripts. Old <literal>systemd.generator-packages</literal> option has + been removed. + </para> + </listitem> + <listitem> + <para> + The <literal>rmilter</literal> package was removed with associated module and options due deprecation by upstream developer. + Use <literal>rspamd</literal> in proxy mode instead. + </para> + </listitem> + <listitem> + <para> + systemd cgroup accounting via the + <link linkend="opt-systemd.enableCgroupAccounting">systemd.enableCgroupAccounting</link> + option is now enabled by default. It now also enables the more recent Block IO and IP accounting + features. + </para> + </listitem> + <listitem> + <para> + We no longer enable custom font rendering settings with <option>fonts.fontconfig.penultimate.enable</option> by default. + The defaults from fontconfig are sufficient. + </para> + </listitem> + <listitem> + <para> + The <literal>crashplan</literal> package and the + <literal>crashplan</literal> service have been removed from nixpkgs due to + crashplan shutting down the service, while the <literal>crashplansb</literal> + package and <literal>crashplan-small-business</literal> service have been + removed from nixpkgs due to lack of maintainer. + </para> + <para> + The <link linkend="opt-services.redis.enable">redis module</link> was hardcoded to use the <literal>redis</literal> user, + <filename class="directory">/run/redis</filename> as runtime directory and + <filename class="directory">/var/lib/redis</filename> as state directory. + Note that the NixOS module for Redis now disables kernel support for Transparent Huge Pages (THP), + because this features causes major performance problems for Redis, + e.g. (https://redis.io/topics/latency). + </para> + </listitem> + <listitem> + <para> + Using <option>fonts.enableDefaultFonts</option> adds a default emoji font <literal>noto-fonts-emoji</literal>. + <itemizedlist> + <para>Users of the following options will have this enabled by default:</para> + <listitem> + <para><option>services.xserver.enable</option></para> + </listitem> + <listitem> + <para><option>programs.sway.enable</option></para> + </listitem> + <listitem> + <para><option>programs.way-cooler.enable</option></para> + </listitem> + <listitem> + <para><option>services.xrdp.enable</option></para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + The <literal>altcoins</literal> categorization of packages has + been removed. You now access these packages at the top level, + ie. <literal>nix-shell -p dogecoin</literal> instead of + <literal>nix-shell -p altcoins.dogecoin</literal>, etc. + </para> + </listitem> + <listitem> + <para> + Ceph has been upgraded to v14.2.1. + See the <link xlink:href="https://ceph.com/releases/v14-2-0-nautilus-released/">release notes</link> for details. + The mgr dashboard as well as osds backed by loop-devices is no longer explicitly supported by the package and module. + Note: There's been some issues with python-cherrypy, which is used by the dashboard + and prometheus mgr modules (and possibly others), hence 0000-dont-check-cherrypy-version.patch. + </para> + </listitem> + <listitem> + <para> + <literal>pkgs.weechat</literal> is now compiled against <literal>pkgs.python3</literal>. + Weechat also recommends <link xlink:href="https://weechat.org/scripts/python3/">to use Python3 + in their docs.</link> + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/release-notes/rl-2003.xml b/nixos/doc/manual/release-notes/rl-2003.xml new file mode 100644 index 00000000000..f001a18b1c1 --- /dev/null +++ b/nixos/doc/manual/release-notes/rl-2003.xml @@ -0,0 +1,152 @@ +<section 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-release-20.03"> + <title>Release 20.03 (“Markhor”, 2020.03/??)</title> + + <section 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-release-20.03-highlights"> + <title>Highlights</title> + + <para> + In addition to numerous new and upgraded packages, this release has the + following highlights: + </para> + + <itemizedlist> + <listitem> + <para> + Support is planned until the end of October 2020, handing over to 20.09. + </para> + </listitem> + <listitem> + <para> + Postgresql for NixOS service now defaults to v11. + </para> + </listitem> + <listitem> + <para> + The graphical installer image starts the graphical session automatically. + Before you'd be greeted by a tty and asked to enter <command>systemctl start display-manager</command>. + It is now possible to disable the display-manager from running by selecting the <literal>Disable display-manager</literal> + quirk in the boot menu. + </para> + </listitem> + <listitem> + <para> + By default zfs pools will now be trimmed on a weekly basis. + Trimming is only done on supported devices (i.e. NVME or SSDs) + and should improve throughput and lifetime of these devices. + It is controlled by the <varname>services.zfs.trim.enable</varname> varname. + The zfs scrub service (<varname>services.zfs.autoScrub.enable</varname>) + and the zfs autosnapshot service (<varname>services.zfs.autoSnapshot.enable</varname>) + are now only enabled if zfs is set in <varname>config.boot.initrd.supportedFilesystems</varname> or + <varname>config.boot.supportedFilesystems</varname>. These lists will automatically contain + zfs as soon as any zfs mountpoint is configured in <varname>fileSystems</varname>. + </para> + </listitem> + </itemizedlist> + </section> + + <section 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-release-20.03-new-services"> + <title>New Services</title> + + <para> + The following new services were added since the last release: + </para> + + <itemizedlist> + <listitem> + <para /> + </listitem> + </itemizedlist> + + </section> + + <section 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-release-20.03-incompatibilities"> + <title>Backward Incompatibilities</title> + + <para> + When upgrading from a previous release, please be aware of the following + incompatible changes: + </para> + + <itemizedlist> + <listitem> + <para> + GnuPG is now built without support for a graphical passphrase entry + by default. Please enable the <literal>gpg-agent</literal> user service + via the NixOS option <literal>programs.gnupg.agent.enable</literal>. + Note that upstream recommends using <literal>gpg-agent</literal> and + will spawn a <literal>gpg-agent</literal> on the first invocation of + GnuPG anyway. + </para> + </listitem> + <listitem> + <para> + The <literal>dynamicHosts</literal> option has been removed from the + <link linkend="opt-networking.networkmanager.enable">networkd</link> + module. Allowing (multiple) regular users to override host entries + affecting the whole system opens up a huge attack vector. + There seem to be very rare cases where this might be useful. + Consider setting system-wide host entries using + <link linkend="opt-networking.hosts">networking.hosts</link>, provide + them via the DNS server in your network, or use + <link linkend="opt-environment.etc">environment.etc</link> + to add a file into <literal>/etc/NetworkManager/dnsmasq.d</literal> + reconfiguring <literal>hostsdir</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>99-main.network</literal> file was removed. Maching all + network interfaces caused many breakages, see + <link xlink:href="https://github.com/NixOS/nixpkgs/pull/18962">#18962</link> + and <link xlink:href="https://github.com/NixOS/nixpkgs/pull/71106">#71106</link>. + </para> + <para> + We already don't support the global <link linkend="opt-networking.useDHCP">networking.useDHCP</link>, + <link linkend="opt-networking.defaultGateway">networking.defaultGateway</link> and + <link linkend="opt-networking.defaultGateway6">networking.defaultGateway6</link> options + if <link linkend="opt-networking.useNetworkd">networking.useNetworkd</link> is enabled, + but direct users to configure the per-device + <link linkend="opt-networking.interfaces">networking.interfaces.<name>.…</link> options. + </para> + </listitem> + </itemizedlist> + </section> + + <section 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-release-20.03-notable-changes"> + <title>Other Notable Changes</title> + + <itemizedlist> + <listitem> + <para>SD images are now compressed by default using <literal>bzip2</literal>.</para> + </listitem> + <listitem> + <para> + OpenSSH has been upgraded from 7.9 to 8.1, improving security and adding features + but with potential incompatibilities. Consult the + <link xlink:href="https://www.openssh.com/txt/release-8.1"> + release announcement</link> for more information. + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/xmlformat.conf b/nixos/doc/xmlformat.conf index 4a565c8465b..c3f39c7fd81 100644 --- a/nixos/doc/xmlformat.conf +++ b/nixos/doc/xmlformat.conf @@ -37,7 +37,6 @@ para abstract entry-break 1 exit-break 1 normalize yes - wrap-length 79 title format block |