NixOS · Mar 22, 2019
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml
@@ -200,8 +200,9 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
 <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 10.x. 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/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml
@@ -4,15 +4,13 @@
          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.
+  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:
+  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;
@@ -33,95 +31,82 @@ services.kubernetes = {
 <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:
+  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.
+  <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"/>
+  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>.
+   <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
+  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>.
+  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>
+  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.
+  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.
+  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
@@ -5,31 +5,34 @@
          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.
+  <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.
+  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</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>
+   installation instructions of Synapse </link>.
+<programlisting>
     let
       fqdn =
         let
@@ -116,28 +119,29 @@
     };
    </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.
+   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:
-
-   <programlisting>
+   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:
+<programlisting>
     $ nix run nixpkgs.matrix-synapse
     $ register_new_matrix_user -k &lt;your-registration-shared-secret&gt; http://localhost:8008
     New user localpart: &lt;your-username&gt;
@@ -147,31 +151,32 @@
     Success!
    </programlisting>
    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.
+   <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>
+  <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;
@@ -183,15 +188,16 @@
      };
    </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.
+   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>