From a0663e3709d1b3d2db97572ec33f3c33a40bcc2a Mon Sep 17 00:00:00 2001
From: Joachim Fasting <joachifm@fastmail.fm>
Date: Thu, 17 Mar 2016 14:14:46 +0100
Subject: [PATCH] dnscrypt-proxy service: documentation fixes

- fix `enable` option description
  using `mkEnableOption longDescription` is incorrect; override
  `description` instead
- additional details for proper usage of the service, including
  an example of the recommended configuration
- clarify `localAddress` option description
- clarify `localPort` option description
- clarify `customResolver` option description
---
 .../services/networking/dnscrypt-proxy.nix    | 62 ++++++++++++-------
 1 file changed, 41 insertions(+), 21 deletions(-)

diff --git a/nixos/modules/services/networking/dnscrypt-proxy.nix b/nixos/modules/services/networking/dnscrypt-proxy.nix
index 9bb28838878..d9ca430161e 100644
--- a/nixos/modules/services/networking/dnscrypt-proxy.nix
+++ b/nixos/modules/services/networking/dnscrypt-proxy.nix
@@ -27,25 +27,46 @@ in
 {
   options = {
     services.dnscrypt-proxy = {
-      enable = mkEnableOption ''
-        Enable dnscrypt-proxy. The proxy relays regular DNS queries to a
-        DNSCrypt enabled upstream resolver. The traffic between the
-        client and the upstream resolver is encrypted and authenticated,
-        which may mitigate the risk of MITM attacks and third-party
+      enable = mkEnableOption "dnscrypt-proxy" // { description = ''
+        Whether to enable the DNSCrypt client proxy. The proxy relays
+        DNS queries to a DNSCrypt enabled upstream resolver. The traffic
+        between the client and the upstream resolver is encrypted and
+        authenticated, mitigating the risk of MITM attacks and third-party
         snooping (assuming the upstream is trustworthy).
-      '';
+
+        Enabling this option does not alter the system nameserver; to relay
+        local queries, prepend <literal>127.0.0.1</literal> to
+        <option>networking.nameservers</option>.
+
+        The recommended configuration is to run DNSCrypt proxy as a forwarder
+        for a caching DNS client, as in
+        <programlisting>
+        {
+          services.dnscrypt-proxy.enable = true;
+          services.dnscrypt-proxy.localPort = 43;
+          services.dnsmasq.enable = true;
+          services.dnsmasq.servers = [ "127.0.0.1#43" ];
+          services.dnsmasq.resolveLocalQueries = true; # this is the default
+        }
+        </programlisting>
+     ''; };
       localAddress = mkOption {
         default = "127.0.0.1";
         type = types.string;
         description = ''
-          Listen for DNS queries on this address.
+          Listen for DNS queries to relay on this address. The only reason to
+          change this from its default value is to proxy queries on behalf
+          of other machines (typically on the local network).
         '';
       };
       localPort = mkOption {
         default = 53;
         type = types.int;
         description = ''
-          Listen on this port.
+          Listen for DNS queries to relay on this port. The default value
+          assumes that the DNSCrypt proxy should relay DNS queries directly.
+          When running as a forwarder for another DNS client, set this option
+          to a different value; otherwise leave the default.
         '';
       };
       resolverName = mkOption {
@@ -53,7 +74,7 @@ in
         type = types.nullOr types.string;
         description = ''
           The name of the upstream DNSCrypt resolver to use. See
-          <literal>${resolverListFile}</literal> for alternative resolvers
+          <filename>${resolverListFile}</filename> for alternative resolvers
           (e.g., if you are concerned about logging and/or server
           location).
         '';
@@ -61,9 +82,8 @@ in
       customResolver = mkOption {
         default = null;
         description = ''
-          Use a resolver not listed in the upstream list (e.g.,
-          a private DNSCrypt provider). For advanced users only.
-          If specified, this option takes precedence.
+          Use an unlisted resolver (e.g., a private DNSCrypt provider). For
+          advanced users only. If specified, this option takes precedence.
         '';
         type = types.nullOr (types.submodule ({ ... }: { options = {
           address = mkOption {
@@ -80,20 +100,20 @@ in
             type = types.str;
             description = "Provider fully qualified domain name";
             example = "2.dnscrypt-cert.opendns.com";
-         };
-         key = mkOption {
-           type = types.str;
-           description = "Provider public key";
-           example = "B735:1140:206F:225D:3E2B:D822:D7FD:691E:A1C3:3CC8:D666:8D0C:BE04:BFAB:CA43:FB79";
-         }; }; }));
+          };
+          key = mkOption {
+            type = types.str;
+            description = "Provider public key";
+            example = "B735:1140:206F:225D:3E2B:D822:D7FD:691E:A1C3:3CC8:D666:8D0C:BE04:BFAB:CA43:FB79";
+          };
+        }; }));
       };
       tcpOnly = mkOption {
         default = false;
         type = types.bool;
         description = ''
-          Force sending encrypted DNS queries to the upstream resolver
-          over TCP instead of UDP (on port 443). Enabling this option may
-          help circumvent filtering, but should not be used otherwise.
+          Force sending encrypted DNS queries to the upstream resolver over
+          TCP instead of UDP (on port 443). Use only if the UDP port is blocked.
         '';
       };
     };