Merge pull request #39878 from knedlsepp/fix-ncurses-darwin-extensions

ncurses: Fix shared library extension on darwin

.editorconfig

@@ -13,8 +13,8 @@ charset = utf-8
 
 # see https://nixos.org/nixpkgs/manual/#chap-conventions
 
-# Match nix/ruby files, set indent to spaces with width of two
+# Match nix/ruby/docbook files, set indent to spaces with width of two
-[*.{nix,rb}]
+[*.{nix,rb,xml}]
 indent_style = space
 indent_size = 2
 
@@ -26,7 +26,3 @@ indent_size = 4
 # Match diffs, avoid to trim trailing whitespace
 [*.{diff,patch}]
 trim_trailing_whitespace = false
-
-# https://github.com/NixOS/nixpkgs/pull/39336#discussion_r183387754
-[.version]
-insert_final_newline = false

.github/CODEOWNERS

@@ -14,6 +14,7 @@
 /lib                        @edolstra @nbp
 /lib/systems                @nbp @ericson2314
 /lib/generators.nix         @edolstra @nbp @Profpatsch
+/lib/debug.nix              @edolstra @nbp @Profpatsch
 
 # Nixpkgs Internals
 /default.nix                          @nbp

doc/Makefile

@@ -64,7 +64,7 @@ manual-full.xml: ${MD_TARGETS} .version *.xml
 
 .version:
 	nix-instantiate --eval \
-		-E '(import ../lib).nixpkgsVersion' > .version
+		-E '(import ../lib).version' > .version
 
 %.section.xml: %.section.md
 	pandoc $^ -w docbook+smart \

doc/cross-compilation.xml

@@ -75,7 +75,7 @@
             An example of such a tool is LLVM.
           </para>
           <para>
-            Although the existance of a "target platfom" is arguably a historical mistake, it is a common one: examples of tools that suffer from it are GCC, Binutils, GHC and Autoconf.
+            Although the existence of a "target platfom" is arguably a historical mistake, it is a common one: examples of tools that suffer from it are GCC, Binutils, GHC and Autoconf.
             Nixpkgs tries to avoid sharing in the mistake where possible.
             Still, because the concept of a target platform is so ingrained, it is best to support it as is.
           </para>

doc/default.nix

@@ -30,7 +30,7 @@ pkgs.stdenv.mkDerivation {
   ];
 
   postPatch = ''
-    echo ${lib.nixpkgsVersion} > .version
+    echo ${lib.version} > .version
   '';
 
   installPhase = ''

doc/functions.xml

@@ -294,6 +294,22 @@ merge:"diff3"
 
 </section>
 
+<section xml:id="sec-debug">
+  <title>Debugging Nix Expressions</title>
+
+  <para>Nix is a unityped, dynamic language, this means every value can
+  potentially appear anywhere. Since it is also non-strict, evaluation order
+  and what ultimately is evaluated might surprise you. Therefore it is important
+  to be able to debug nix expressions.</para>
+
+
+  <para>In the <literal>lib/debug.nix</literal> file you will find a number of
+  functions that help (pretty-)printing values while evaluation is runnnig. You
+  can even specify how deep these values should be printed recursively, and
+  transform them on the fly. Please consult the docstrings in
+  <literal>lib/debug.nix</literal> for usage information.</para>
+</section>
+
 
 <section xml:id="sec-fhs-environments">
   <title>buildFHSUserEnv</title>

lib/debug.nix

@@ -1,34 +1,67 @@
+/* Collection of functions useful for debugging
+   broken nix expressions.
+
+   * `trace`-like functions take two values, print
+     the first to stderr and return the second.
+   * `traceVal`-like functions take one argument
+     which both printed and returned.
+   * `traceSeq`-like functions fully evaluate their
+     traced value before printing (not just to “weak
+     head normal form” like trace does by default).
+   * Functions that end in `-Fn` take an additional
+     function as their first argument, which is applied
+     to the traced value before it is printed.
+*/
 { lib }:
-
 let
-
+  inherit (builtins) trace isAttrs isList isInt
-inherit (builtins) trace attrNamesToStr isAttrs isList isInt
+          head substring attrNames;
-        isString isBool head substring attrNames;
+  inherit (lib) id elem isFunction;
-
-inherit (lib) all id mapAttrsFlatten elem isFunction;
-
 in
 
 rec {
 
-  inherit (builtins) addErrorContext;
+  # -- TRACING --
 
-  addErrorContextToAttrs = lib.mapAttrs (a: v: lib.addErrorContext "while evaluating ${a}" v);
+  /* Trace msg, but only if pred is true.
 
-  traceIf = p: msg: x: if p then trace msg x else x;
+     Example:
+       traceIf true "hello" 3
+       trace: hello
+       => 3
+  */
+  traceIf = pred: msg: x: if pred then trace msg x else x;
 
-  traceVal = x: trace x x;
+  /* Trace the value and also return it.
-  traceXMLVal = x: trace (builtins.toXML x) x;
-  traceXMLValMarked = str: x: trace (str + builtins.toXML x) x;
 
-  # strict trace functions (traced structure is fully evaluated and printed)
+     Example:
+       traceValFn (v: "mystring ${v}") "foo"
+       trace: mystring foo
+       => "foo"
+  */
+  traceValFn = f: x: trace (f x) x;
+  traceVal = traceValFn id;
 
-  /* `builtins.trace`, but the value is `builtins.deepSeq`ed first. */
+  /* `builtins.trace`, but the value is `builtins.deepSeq`ed first.
+
+     Example:
+       trace { a.b.c = 3; } null
+       trace: { a = <CODE>; }
+       => null
+       traceSeq { a.b.c = 3; } null
+       trace: { a = { b = { c = 3; }; }; }
+       => null
+  */
   traceSeq = x: y: trace (builtins.deepSeq x x) y;
 
-  /* Like `traceSeq`, but only down to depth n.
+  /* Like `traceSeq`, but only evaluate down to depth n.
-   * This is very useful because lots of `traceSeq` usages
+     This is very useful because lots of `traceSeq` usages
-   * lead to an infinite recursion.
+     lead to an infinite recursion.
+
+     Example:
+       traceSeqN 2 { a.b.c = 3; } null
+       trace: { a = { b = {…}; }; }
+       => null
    */
   traceSeqN = depth: x: y: with lib;
     let snip = v: if      isList  v then noQuotes "[…]" v
@@ -43,39 +76,16 @@ rec {
     in trace (generators.toPretty { allowPrettyValues = true; }
                (modify depth snip x)) y;
 
-  /* `traceSeq`, but the same value is traced and returned */
+  /* A combination of `traceVal` and `traceSeq` */
-  traceValSeq = v: traceVal (builtins.deepSeq v v);
+  traceValSeqFn = f: v: traceVal f (builtins.deepSeq v v);
-  /* `traceValSeq` but with fixed depth */
+  traceValSeq = traceValSeqFn id;
-  traceValSeqN = depth: v: traceSeqN depth v v;
+
+  /* A combination of `traceVal` and `traceSeqN`. */
+  traceValSeqNFn = f: depth: v: traceSeqN depth (f v) v;
+  traceValSeqN = traceValSeqNFn id;
 
 
-  # this can help debug your code as well - designed to not produce thousands of lines
+  # -- TESTING --
-  traceShowVal = x: trace (showVal x) x;
-  traceShowValMarked = str: x: trace (str + showVal x) x;
-  attrNamesToStr = a: lib.concatStringsSep "; " (map (x: "${x}=") (attrNames a));
-  showVal = x:
-      if isAttrs x then
-          if x ? outPath then "x is a derivation, name ${if x ? name then x.name else "<no name>"}, { ${attrNamesToStr x} }"
-          else "x is attr set { ${attrNamesToStr x} }"
-      else if isFunction x then "x is a function"
-      else if x == [] then "x is an empty list"
-      else if isList x then "x is a list, first element is: ${showVal (head x)}"
-      else if x == true then "x is boolean true"
-      else if x == false then "x is boolean false"
-      else if x == null then "x is null"
-      else if isInt x then "x is an integer `${toString x}'"
-      else if isString x then "x is a string `${substring 0 50 x}...'"
-      else "x is probably a path `${substring 0 50 (toString x)}...'";
-
-  # trace the arguments passed to function and its result
-  # maybe rewrite these functions in a traceCallXml like style. Then one function is enough
-  traceCall  = n: f: a: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a));
-  traceCall2 = n: f: a: b: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a) (t "arg 2" b));
-  traceCall3 = n: f: a: b: c: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a) (t "arg 2" b) (t "arg 3" c));
-
-  # FIXME: rename this?
-  traceValIfNot = c: x:
-    if c x then true else trace (showVal x) false;
 
   /* Evaluate a set of tests.  A test is an attribute set {expr,
      expected}, denoting an expression and its expected result.  The
@@ -99,9 +109,68 @@ rec {
   # usage: { testX = allTrue [ true ]; }
   testAllTrue = expr: { inherit expr; expected = map (x: true) expr; };
 
-  strict = v:
+
-    trace "Warning: strict is deprecated and will be removed in the next release"
+  # -- DEPRECATED --
-      (builtins.seq v v);
+
+  traceShowVal = x: trace (showVal x) x;
+  traceShowValMarked = str: x: trace (str + showVal x) x;
+
+  attrNamesToStr = a:
+    trace ( "Warning: `attrNamesToStr` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please use more specific concatenation "
+          + "for your uses (`lib.concat(Map)StringsSep`)." )
+    (lib.concatStringsSep "; " (map (x: "${x}=") (attrNames a)));
+
+  showVal = with lib;
+    trace ( "Warning: `showVal` is deprecated "
+          + "and will be removed in the next release, "
+          + "please use `traceSeqN`" )
+    (let
+      modify = v:
+        let pr = f: { __pretty = f; val = v; };
+        in   if isDerivation v then pr
+          (drv: "<δ:${drv.name}:${concatStringsSep ","
+                                 (attrNames drv)}>")
+        else if [] ==   v then pr (const "[]")
+        else if isList  v then pr (l: "[ ${go (head l)}, … ]")
+        else if isAttrs v then pr
+          (a: "{ ${ concatStringsSep ", " (attrNames a)} }")
+        else v;
+      go = x: generators.toPretty
+        { allowPrettyValues = true; }
+        (modify x);
+    in go);
+
+  traceXMLVal = x:
+    trace ( "Warning: `traceXMLVal` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please use `traceValFn builtins.toXML`." )
+    (trace (builtins.toXML x) x);
+  traceXMLValMarked = str: x:
+    trace ( "Warning: `traceXMLValMarked` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please use `traceValFn (x: str + builtins.toXML x)`." )
+    (trace (str + builtins.toXML x) x);
+
+  # trace the arguments passed to function and its result
+  # maybe rewrite these functions in a traceCallXml like style. Then one function is enough
+  traceCall  = n: f: a: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a));
+  traceCall2 = n: f: a: b: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a) (t "arg 2" b));
+  traceCall3 = n: f: a: b: c: let t = n2: x: traceShowValMarked "${n} ${n2}:" x; in t "result" (f (t "arg 1" a) (t "arg 2" b) (t "arg 3" c));
+
+  traceValIfNot = c: x:
+    trace ( "Warning: `traceValIfNot` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please use `if/then/else` and `traceValSeq 1`.")
+    (if c x then true else traceSeq (showVal x) false);
+
+
+  addErrorContextToAttrs = attrs:
+    trace ( "Warning: `addErrorContextToAttrs` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please use `builtins.addErrorContext` directly." )
+    (lib.mapAttrs (a: v: lib.addErrorContext "while evaluating ${a}" v) attrs);
 
   # example: (traceCallXml "myfun" id 3) will output something like
   # calling myfun arg 1: 3 result: 3
@@ -109,17 +178,20 @@ rec {
   # note: if result doesn't evaluate you'll get no trace at all (FIXME)
   #       args should be printed in any case
   traceCallXml = a:
-    if !isInt a then
+    trace ( "Warning: `traceCallXml` is deprecated "
+          + "and will be removed in the next release. "
+          + "Please complain if you use the function regularly." )
+    (if !isInt a then
       traceCallXml 1 "calling ${a}\n"
     else
       let nr = a;
       in (str: expr:
           if isFunction expr then
             (arg:
-              traceCallXml (builtins.add 1 nr) "${str}\n arg ${builtins.toString nr} is \n ${builtins.toXML (strict arg)}" (expr arg)
+              traceCallXml (builtins.add 1 nr) "${str}\n arg ${builtins.toString nr} is \n ${builtins.toXML (builtins.seq arg arg)}" (expr arg)
             )
           else
-            let r = strict expr;
+            let r = builtins.seq expr expr;
             in trace "${str}\n result:\n${builtins.toXML r}" r
-      );
+      ));
 }

lib/default.nix

@@ -58,7 +58,7 @@ let
       replaceStrings seq stringLength sub substring tail;
     inherit (trivial) id const concat or and boolToString mergeAttrs
       flip mapNullable inNixShell min max importJSON warn info
-      nixpkgsVersion mod compare splitByAndCompare
+      nixpkgsVersion version mod compare splitByAndCompare
       functionArgs setFunctionArgs isFunction;
 
     inherit (fixedPoints) fix fix' extends composeExtensions
@@ -115,11 +115,12 @@ let
       unknownModule mkOption;
     inherit (types) isType setType defaultTypeMerge defaultFunctor
       isOptionType mkOptionType;
-    inherit (debug) addErrorContextToAttrs traceIf traceVal
+    inherit (debug) addErrorContextToAttrs traceIf traceVal traceValFn
       traceXMLVal traceXMLValMarked traceSeq traceSeqN traceValSeq
-      traceValSeqN traceShowVal traceShowValMarked
+      traceValSeqFn traceValSeqN traceValSeqNFn traceShowVal
-      showVal traceCall traceCall2 traceCall3 traceValIfNot runTests
+      traceShowValMarked showVal traceCall traceCall2 traceCall3
-      testAllTrue strict traceCallXml attrNamesToStr;
+      traceValIfNot runTests testAllTrue traceCallXml
+      attrNamesToStr;
     inherit (misc) maybeEnv defaultMergeArg defaultMerge foldArgs
       defaultOverridableDelayableArgs composedArgsAndFun
       maybeAttrNullable maybeAttr ifEnable checkFlag getValue

lib/generators.nix

@@ -143,18 +143,13 @@ rec {
        (This means fn is type Val -> String.) */
     allowPrettyValues ? false
   }@args: v: with builtins;
-    if      isInt      v then toString v
+    let     isPath   = v: typeOf v == "path";
+    in if   isInt      v then toString v
     else if isString   v then ''"${libStr.escape [''"''] v}"''
     else if true  ==   v then "true"
     else if false ==   v then "false"
     else if null  ==   v then "null"
-    else if isFunction v then
+    else if isPath     v then toString v
-      let fna = lib.functionArgs v;
-          showFnas = concatStringsSep "," (libAttr.mapAttrsToList
-                       (name: hasDefVal: if hasDefVal then "(${name})" else name)
-                       fna);
-      in if fna == {}    then "<λ>"
-                         else "<λ:{${showFnas}}>"
     else if isList     v then "[ "
         + libStr.concatMapStringsSep " " (toPretty args) v
       + " ]"
@@ -163,12 +158,21 @@ rec {
       if attrNames v == [ "__pretty" "val" ] && allowPrettyValues
          then v.__pretty v.val
       # TODO: there is probably a better representation?
-      else if v ? type && v.type == "derivation" then "<δ>"
+      else if v ? type && v.type == "derivation" then
+        "<δ:${v.name}>"
+        # "<δ:${concatStringsSep "," (builtins.attrNames v)}>"
       else "{ "
           + libStr.concatStringsSep " " (libAttr.mapAttrsToList
               (name: value:
                 "${toPretty args name} = ${toPretty args value};") v)
         + " }"
-    else abort "generators.toPretty: should never happen (v = ${v})";
+    else if isFunction v then
+      let fna = lib.functionArgs v;
+          showFnas = concatStringsSep "," (libAttr.mapAttrsToList
+                       (name: hasDefVal: if hasDefVal then "(${name})" else name)
+                       fna);
+      in if fna == {}    then "<λ>"
+                         else "<λ:{${showFnas}}>"
+    else abort "toPretty: should never happen (v = ${v})";
 
 }

lib/modules.nix

@@ -159,7 +159,7 @@ rec {
       context = name: ''while evaluating the module argument `${name}' in "${key}":'';
       extraArgs = builtins.listToAttrs (map (name: {
         inherit name;
-        value = addErrorContext (context name)
+        value = builtins.addErrorContext (context name)
           (args.${name} or config._module.args.${name});
       }) requiredArgs);
 
@@ -309,7 +309,7 @@ rec {
           res.mergedValue;
 
     in opt //
-      { value = addErrorContext "while evaluating the option `${showOption loc}':" value;
+      { value = builtins.addErrorContext "while evaluating the option `${showOption loc}':" value;
         definitions = map (def: def.value) res.defsFinal;
         files = map (def: def.file) res.defsFinal;
         inherit (res) isDefined;

lib/systems/doubles.nix

@@ -26,7 +26,7 @@ in rec {
 
   none = [];
 
-  arm     = filterDoubles predicates.isArm;
+  arm     = filterDoubles predicates.isAarch32;
   aarch64 = filterDoubles predicates.isAarch64;
   x86     = filterDoubles predicates.isx86;
   i686    = filterDoubles predicates.isi686;

lib/systems/examples.nix

@@ -88,16 +88,36 @@ rec {
   #
 
   iphone64 = {
-    config = "aarch64-apple-darwin14";
+    config = "aarch64-apple-ios";
-    arch = "arm64";
+    # config = "aarch64-apple-darwin14";
-    libc = "libSystem";
+    sdkVer = "10.2";
+    useiOSPrebuilt = true;
     platform = {};
   };
 
   iphone32 = {
-    config = "arm-apple-darwin10";
+    config = "armv7-apple-ios";
-    arch = "armv7-a";
+    # config = "arm-apple-darwin10";
-    libc = "libSystem";
+    sdkVer = "10.2";
+    useiOSPrebuilt = true;
+    platform = {};
+  };
+
+  iphone64-simulator = {
+    config = "x86_64-apple-ios";
+    # config = "x86_64-apple-darwin14";
+    sdkVer = "10.2";
+    useiOSPrebuilt = true;
+    isiPhoneSimulator = true;
+    platform = {};
+  };
+
+  iphone32-simulator = {
+    config = "i686-apple-ios";
+    # config = "i386-apple-darwin11";
+    sdkVer = "10.2";
+    useiOSPrebuilt = true;
+    isiPhoneSimulator = true;
     platform = {};
   };
 

lib/systems/for-meta.nix

@@ -7,7 +7,7 @@ in rec {
   all     = [ {} ]; # `{}` matches anything
   none    = [];
 
-  arm     = [ patterns.isArm ];
+  arm     = [ patterns.isAarch32 ];
   aarch64 = [ patterns.isAarch64 ];
   x86     = [ patterns.isx86 ];
   i686    = [ patterns.isi686 ];

lib/systems/inspect.nix

@@ -9,8 +9,8 @@ rec {
     isx86_64       = { cpu = cpuTypes.x86_64; };
     isPowerPC      = { cpu = cpuTypes.powerpc; };
     isx86          = { cpu = { family = "x86"; }; };
-    isArm          = { cpu = { family = "arm"; }; };
+    isAarch32      = { cpu = { family = "arm"; bits = 32; }; };
-    isAarch64      = { cpu = { family = "aarch64"; }; };
+    isAarch64      = { cpu = { family = "arm"; bits = 64; }; };
     isMips         = { cpu = { family = "mips"; }; };
     isRiscV        = { cpu = { family = "riscv"; }; };
     isWasm         = { cpu = { family = "wasm"; }; };
@@ -41,6 +41,9 @@ rec {
 
     isEfi          = map (family: { cpu.family = family; })
                        [ "x86" "arm" "aarch64" ];
+
+    # Deprecated after 18.03
+    isArm = isAarch32;
   };
 
   matchAnyAttrs = patterns:

lib/systems/parse.nix

@@ -72,7 +72,7 @@ rec {
     armv6l   = { bits = 32; significantByte = littleEndian; family = "arm"; };
     armv7a   = { bits = 32; significantByte = littleEndian; family = "arm"; };
     armv7l   = { bits = 32; significantByte = littleEndian; family = "arm"; };
-    aarch64  = { bits = 64; significantByte = littleEndian; family = "aarch64"; };
+    aarch64  = { bits = 64; significantByte = littleEndian; family = "arm"; };
     i686     = { bits = 32; significantByte = littleEndian; family = "x86"; };
     x86_64   = { bits = 64; significantByte = littleEndian; family = "x86"; };
     mips     = { bits = 32; significantByte = bigEndian;    family = "mips"; };

lib/tests/misc.nix

@@ -317,7 +317,8 @@ runTests {
     expr = mapAttrs (const (generators.toPretty {})) rec {
       int = 42;
       bool = true;
-      string = "fnord";
+      string = ''fno"rd'';
+      path = /. + "/foo"; # toPath returns a string
       null_ = null;
       function = x: x;
       functionArgs = { arg ? 4, foo }: arg;
@@ -328,13 +329,14 @@ runTests {
     expected = rec {
       int = "42";
       bool = "true";
-      string = "\"fnord\"";
+      string = ''"fno\"rd"'';
+      path = "/foo";
       null_ = "null";
       function = "<λ>";
       functionArgs = "<λ:{(arg),foo}>";
       list = "[ 3 4 ${function} [ false ] ]";
       attrs = "{ \"foo\" = null; \"foo bar\" = \"baz\"; }";
-      drv = "<δ>";
+      drv = "<δ:test>";
     };
   };
 

lib/trivial.nix

@@ -58,11 +58,14 @@ rec {
 
   inherit (lib.strings) fileContents;
 
+  release = fileContents ../.version;
+  versionSuffix = let suffixFile = ../.version-suffix; in
+    if pathExists suffixFile then fileContents suffixFile else "pre-git";
+
   # Return the Nixpkgs version number.
-  nixpkgsVersion =
+  version = release + versionSuffix;
-    let suffixFile = ../.version-suffix; in
+
-    fileContents ../.version
+  nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
-    + (if pathExists suffixFile then fileContents suffixFile else "pre-git");
 
   # Whether we're being called by nix-shell.
   inNixShell = builtins.getEnv "IN_NIX_SHELL" != "";

maintainers/maintainer-list.nix

@@ -1241,7 +1241,7 @@
     name = "Mabry Cervin";
   };
   eqyiel = {
-    email = "r@rkm.id.au";
+    email = "ruben@maher.fyi";
     github = "eqyiel";
     name = "Ruben Maher";
   };
@@ -1726,6 +1726,11 @@
     github = "jbedo";
     name = "Justin Bedő";
   };
+  jbgi = {
+    email = "jb@giraudeau.info";
+    github = "jbgi";
+    name = "Jean-Baptiste Giraudeau";
+  };
   jcumming = {
     email = "jack@mudshark.org";
     name = "Jack Cummings";
@@ -1755,6 +1760,11 @@
     github = "tftio";
     name = "James Felix Black";
   };
+  jflanglois = {
+    email = "yourstruly@julienlanglois.me";
+    github = "jflanglois";
+    name = "Julien Langlois";
+  };
   jfrankenau = {
     email = "johannes@frankenau.net";
     github = "jfrankenau";
@@ -2521,6 +2531,11 @@
     github = "fstamour";
     name = "Francis St-Amour";
   };
+  mrkkrp = {
+    email = "markkarpov92@gmail.com";
+    github = "mrkkrp";
+    name = "Mark Karpov";
+  };
   mrVanDalo = {
     email = "contact@ingolf-wagner.de";
     github = "mrVanDalo";
@@ -4039,7 +4054,7 @@
   xeji = {
     email = "xeji@cat3.de";
     github = "xeji";
-    name = "xeji";
+    name = "Uli Baum";
   };
   xnaveira = {
     email = "xnaveira@gmail.com";

nixos/doc/manual/Makefile

@@ -0,0 +1,8 @@
+debug:
+	nix-shell --packages xmloscopy \
+		--run 'xmloscopy --docbook5 ./manual.xml ./manual-combined.xml'
+
+generated: ./options-to-docbook.xsl
+	nix-build ../../release.nix \
+		--attr manualGeneratedSources.x86_64-linux \
+		--out-link ./generated

nixos/doc/manual/administration/cleaning-store.xml

@@ -29,8 +29,8 @@ this unit automatically at certain points in time, for instance, every
 night at 03:15:
 
 <programlisting>
-nix.gc.automatic = true;
+<xref linkend="opt-nix.gc.automatic"/> = true;
-nix.gc.dates = "03:15";
+<xref linkend="opt-nix.gc.dates"/> = "03:15";
 </programlisting>
 
 </para>

nixos/doc/manual/administration/container-networking.xml

@@ -39,9 +39,9 @@ IP address. This can be accomplished using the following configuration
 on the host:
 
 <programlisting>
-networking.nat.enable = true;
+<xref linkend="opt-networking.nat.enable"/> = true;
-networking.nat.internalInterfaces = ["ve-+"];
+<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"];
-networking.nat.externalInterface = "eth0";
+<xref linkend="opt-networking.nat.externalInterface"/> = "eth0";
 </programlisting>
 where <literal>eth0</literal> should be replaced with the desired
 external interface. Note that <literal>ve-+</literal> is a wildcard

nixos/doc/manual/administration/control-groups.xml

@@ -47,7 +47,7 @@ would get 1/1001 of the cgroup’s CPU time.)  You can limit a service’s
 CPU share in <filename>configuration.nix</filename>:
 
 <programlisting>
-systemd.services.httpd.serviceConfig.CPUShares = 512;
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512;
 </programlisting>
 
 By default, every cgroup has 1024 CPU shares, so this will halve the
@@ -61,7 +61,7 @@ available memory.  Per-cgroup memory limits can be specified in
 <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap):
 
 <programlisting>
-systemd.services.httpd.serviceConfig.MemoryLimit = "512M";
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M";
 </programlisting>
 
 </para>

nixos/doc/manual/administration/declarative-containers.xml

@@ -15,8 +15,8 @@ following specifies that there shall be a container named
 containers.database =
   { config =
       { config, pkgs, ... }:
-      { services.postgresql.enable = true;
+      { <xref linkend="opt-services.postgresql.enable"/> = true;
-        services.postgresql.package = pkgs.postgresql96;
+      <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql96;
       };
   };
 </programlisting>
@@ -33,11 +33,11 @@ ports. However, they cannot change the network configuration. You can
 give a container its own network as follows:
 
 <programlisting>
-containers.database =
+containers.database = {
-  { privateNetwork = true;
+  <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true;
-    hostAddress = "192.168.100.10";
+  <link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10";
-    localAddress = "192.168.100.11";
+  <link linkend="opt-containers._name_.localAddress">localAddress</link> = "192.168.100.11";
-  };
+};
 </programlisting>
 
 This gives the container a private virtual Ethernet interface with IP

nixos/doc/manual/administration/imperative-containers.xml

@@ -30,8 +30,8 @@ line. For instance, to create a container that has
 
 <screen>
 # nixos-container create foo --config '
-  services.openssh.enable = true;
+  <xref linkend="opt-services.openssh.enable"/> = true;
-  users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
+  <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"];
 '
 </screen>
 
@@ -100,9 +100,9 @@ specify a new configuration on the command line:
 
 <screen>
 # nixos-container update foo --config '
-  services.httpd.enable = true;
+  <xref linkend="opt-services.httpd.enable"/> = true;
-  services.httpd.adminAddr = "foo@example.org";
+  <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org";
-  networking.firewall.allowedTCPPorts = [ 80 ];
+  <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ];
 '
 
 # curl http://$(nixos-container show-ip foo)/

nixos/doc/manual/configuration/abstractions.xml

@@ -11,7 +11,7 @@ to abstract.  Take, for instance, this Apache HTTP Server configuration:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     [ { hostName = "example.org";
         documentRoot = "/webroot";
         adminAddr = "alice@example.org";
@@ -43,7 +43,7 @@ let
     };
 in
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     [ exampleOrgCommon
       (exampleOrgCommon // {
         enableSSL = true;
@@ -66,7 +66,7 @@ allowed.  Thus, you also could have written:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let exampleOrgCommon = <replaceable>...</replaceable>; in
     [ exampleOrgCommon
       (exampleOrgCommon // { <replaceable>...</replaceable> })
@@ -86,7 +86,7 @@ the host name.  This can be done as follows:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = name:
         { hostName = name;
@@ -113,7 +113,7 @@ element in a list:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = <replaceable>...</replaceable>;
     in map makeVirtualHost
@@ -132,7 +132,7 @@ function that takes a <emphasis>set</emphasis> as its argument, like this:
 
 <programlisting>
 {
-  services.httpd.virtualHosts =
+  <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
       makeVirtualHost = { name, root }:
         { hostName = name;

nixos/doc/manual/configuration/ad-hoc-network-config.xml

@@ -6,14 +6,14 @@
 
 <title>Ad-Hoc Configuration</title>
 
-<para>You can use <option>networking.localCommands</option> to specify
+<para>You can use <xref linkend="opt-networking.localCommands"/> to specify
 shell commands to be run at the end of
 <literal>network-setup.service</literal>.  This is useful for doing
 network configuration not covered by the existing NixOS modules.  For
 instance, to statically configure an IPv6 address:
 
 <programlisting>
-networking.localCommands =
+<xref linkend="opt-networking.localCommands"/> =
   ''
     ip -6 addr add 2001:610:685:1::1/64 dev eth0
   '';

nixos/doc/manual/configuration/adding-custom-packages.xml

@@ -24,7 +24,7 @@ manual.  Finally, you add it to
 <literal>environment.systemPackages</literal>, e.g.
 
 <programlisting>
-environment.systemPackages = [ pkgs.my-package ];
+<xref linkend="opt-environment.systemPackages"/> = [ pkgs.my-package ];
 </programlisting>
 
 and you run <command>nixos-rebuild</command>, specifying your own
@@ -41,7 +41,7 @@ Nixpkgs tree.  For instance, here is how you specify a build of the
 package directly in <filename>configuration.nix</filename>:
 
 <programlisting>
-environment.systemPackages =
+<xref linkend="opt-environment.systemPackages"/> =
   let
     my-hello = with pkgs; stdenv.mkDerivation rec {
       name = "hello-2.8";
@@ -57,7 +57,7 @@ environment.systemPackages =
 Of course, you can also move the definition of
 <literal>my-hello</literal> into a separate Nix expression, e.g.
 <programlisting>
-environment.systemPackages = [ (import ./my-hello.nix) ];
+<xref linkend="opt-environment.systemPackages"/> = [ (import ./my-hello.nix) ];
 </programlisting>
 where <filename>my-hello.nix</filename> contains:
 <programlisting>

nixos/doc/manual/configuration/config-file.xml

@@ -28,9 +28,9 @@ form <literal><replaceable>name</replaceable> =
 <programlisting>
 { config, pkgs, ... }:
 
-{ services.httpd.enable = true;
+{ <xref linkend="opt-services.httpd.enable"/> = true;
-  services.httpd.adminAddr = "alice@example.org";
+  <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
-  services.httpd.documentRoot = "/webroot";
+  <xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
 }
 </programlisting>
 
@@ -40,7 +40,7 @@ the document root.</para>
 
 <para>Sets can be nested, and in fact dots in option names are
 shorthand for defining a set containing another set.  For instance,
-<option>services.httpd.enable</option> defines a set named
+<xref linkend="opt-services.httpd.enable"/> defines a set named
 <varname>services</varname> that contains a set named
 <varname>httpd</varname>, which in turn contains an option definition
 named <varname>enable</varname> with value <literal>true</literal>.
@@ -89,7 +89,7 @@ The option value `services.httpd.enable' in `/etc/nixos/configuration.nix' is no
       <para>Strings are enclosed in double quotes, e.g.
 
 <programlisting>
-networking.hostName = "dexter";
+<xref linkend="opt-networking.hostName"/> = "dexter";
 </programlisting>
 
       Special characters can be escaped by prefixing them with a
@@ -99,7 +99,7 @@ networking.hostName = "dexter";
       single quotes</emphasis>, e.g.
 
 <programlisting>
-networking.extraHosts =
+<xref linkend="opt-networking.extraHosts"/> =
   ''
     127.0.0.2 other-localhost
     10.0.0.1 server
@@ -125,8 +125,8 @@ networking.extraHosts =
       <literal>false</literal>, e.g.
 
 <programlisting>
-networking.firewall.enable = true;
+<xref linkend="opt-networking.firewall.enable"/> = true;
-networking.firewall.allowPing = false;
+<xref linkend="opt-networking.firewall.allowPing"/> = false;
 </programlisting>
       </para>
     </listitem>
@@ -138,7 +138,7 @@ networking.firewall.allowPing = false;
       <para>For example,
 
 <programlisting>
-boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 60;
 </programlisting>
 
       (Note that here the attribute name
@@ -158,7 +158,7 @@ boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 60;
       enclosed in braces, as in the option definition
 
 <programlisting>
-fileSystems."/boot" =
+<xref linkend="opt-fileSystems"/>."/boot" =
   { device = "/dev/sda1";
     fsType = "ext4";
     options = [ "rw" "data=ordered" "relatime" ];
@@ -175,7 +175,7 @@ fileSystems."/boot" =
       elements are separated by whitespace, like this:
 
 <programlisting>
-boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
 </programlisting>
 
       List elements can be any other type, e.g. sets:
@@ -195,12 +195,12 @@ swapDevices = [ { device = "/dev/disk/by-label/swap"; } ];
       the function argument <varname>pkgs</varname>.  Typical uses:
 
 <programlisting>
-environment.systemPackages =
+<xref linkend="opt-environment.systemPackages"/> =
   [ pkgs.thunderbird
     pkgs.emacs
   ];
 
-postgresql.package = pkgs.postgresql90;
+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql90;
 </programlisting>
 
       The latter option definition changes the default PostgreSQL

nixos/doc/manual/configuration/configuration.xml

@@ -25,9 +25,8 @@ effect after you run <command>nixos-rebuild</command>.</para>
 <xi:include href="networking.xml" />
 <xi:include href="linux-kernel.xml" />
 
-<xi:include href="modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
+<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
 
 <!-- Apache; libvirtd virtualisation -->
 
 </part>
-

nixos/doc/manual/configuration/customizing-packages.xml

@@ -28,7 +28,7 @@ has a dependency on GTK+ 2.  If you want to build it against GTK+ 3,
 you can specify that as follows:
 
 <programlisting>
-environment.systemPackages = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
+<xref linkend="opt-environment.systemPackages"/> = [ (pkgs.emacs.override { gtk = pkgs.gtk3; }) ];
 </programlisting>
 
 The function <varname>override</varname> performs the call to the Nix
@@ -38,7 +38,7 @@ the set of arguments specified by you.  So here the function argument
 causing Emacs to depend on GTK+ 3.  (The parentheses are necessary
 because in Nix, function application binds more weakly than list
 construction, so without them,
-<literal>environment.systemPackages</literal> would be a list with two
+<xref linkend="opt-environment.systemPackages"/> would be a list with two
 elements.)</para>
 
 <para>Even greater customisation is possible using the function
@@ -51,7 +51,7 @@ For instance, if you want to override the source code of Emacs, you
 can say:
 
 <programlisting>
-environment.systemPackages = [
+<xref linkend="opt-environment.systemPackages"/> = [
   (pkgs.emacs.overrideAttrs (oldAttrs: {
     name = "emacs-25.0-pre";
     src = /path/to/my/emacs/tree;

nixos/doc/manual/configuration/declarative-packages.xml

@@ -8,12 +8,12 @@
 
 <para>With declarative package management, you specify which packages
 you want on your system by setting the option
-<option>environment.systemPackages</option>.  For instance, adding the
+<xref linkend="opt-environment.systemPackages"/>.  For instance, adding the
 following line to <filename>configuration.nix</filename> enables the
 Mozilla Thunderbird email application:
 
 <programlisting>
-environment.systemPackages = [ pkgs.thunderbird ];
+<xref linkend="opt-environment.systemPackages"/> = [ pkgs.thunderbird ];
 </programlisting>
 
 The effect of this specification is that the Thunderbird package from
@@ -34,7 +34,7 @@ name</emphasis>, such as
 different channels that you might have.)</para>
 
 <para>To “uninstall” a package, simply remove it from
-<option>environment.systemPackages</option> and run
+<xref linkend="opt-environment.systemPackages"/> and run
 <command>nixos-rebuild switch</command>.</para>
 
 <xi:include href="customizing-packages.xml" />

nixos/doc/manual/configuration/file-systems.xml

@@ -13,21 +13,21 @@ device <filename>/dev/disk/by-label/data</filename> onto the mount
 point <filename>/data</filename>:
 
 <programlisting>
-fileSystems."/data" =
+<xref linkend="opt-fileSystems"/>."/data" =
   { device = "/dev/disk/by-label/data";
     fsType = "ext4";
   };
 </programlisting>
 
 Mount points are created automatically if they don’t already exist.
-For <option>device</option>, it’s best to use the topology-independent
+For <option><link linkend="opt-fileSystems._name__.device">device</link></option>, it’s best to use the topology-independent
 device aliases in <filename>/dev/disk/by-label</filename> and
 <filename>/dev/disk/by-uuid</filename>, as these don’t change if the
 topology changes (e.g. if a disk is moved to another IDE
 controller).</para>
 
 <para>You can usually omit the file system type
-(<option>fsType</option>), since <command>mount</command> can usually
+(<option><link linkend="opt-fileSystems._name__.fsType">fsType</link></option>), since <command>mount</command> can usually
 detect the type and load the necessary kernel module automatically.
 However, if the file system is needed at early boot (in the initial
 ramdisk) and is not <literal>ext2</literal>, <literal>ext3</literal>
@@ -38,7 +38,7 @@ available.</para>
 <note><para>System startup will fail if any of the filesystems fails to mount,
 dropping you to the emergency shell.
 You can make a mount asynchronous and non-critical by adding
-<literal>options = [ "nofail" ];</literal>.
+<literal><link linkend="opt-fileSystems._name__.options">options</link> = [ "nofail" ];</literal>.
 </para></note>
 
 <xi:include href="luks-file-systems.xml" />

nixos/doc/manual/configuration/firewall.xml

@@ -12,37 +12,37 @@ both IPv4 and IPv6 traffic. It is enabled by default. It can be
 disabled as follows:
 
 <programlisting>
-networking.firewall.enable = false;
+<xref linkend="opt-networking.firewall.enable"/> = false;
 </programlisting>
 
 If the firewall is enabled, you can open specific TCP ports to the
 outside world:
 
 <programlisting>
-networking.firewall.allowedTCPPorts = [ 80 443 ];
+<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];
 </programlisting>
 
 Note that TCP port 22 (ssh) is opened automatically if the SSH daemon
-is enabled (<option>services.openssh.enable = true</option>). UDP
+is enabled (<option><xref linkend="opt-services.openssh.enable"/> = true</option>). UDP
 ports can be opened through
-<option>networking.firewall.allowedUDPPorts</option>.</para>
+<xref linkend="opt-networking.firewall.allowedUDPPorts"/>.</para>
 
 <para>To open ranges of TCP ports:
 
 <programlisting>
-networking.firewall.allowedTCPPortRanges = [
+<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [
   { from = 4000; to = 4007; }
   { from = 8000; to = 8010; }
 ];
 </programlisting>
 
 Similarly, UDP port ranges can be opened through
-<option>networking.firewall.allowedUDPPortRanges</option>.</para>
+<xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.</para>
 
 <para>Also of interest is
 
 <programlisting>
-networking.firewall.allowPing = true;
+<xref linkend="opt-networking.firewall.allowPing"/> = true;
 </programlisting>
 
 to allow the machine to respond to ping requests.  (ICMPv6 pings are

nixos/doc/manual/configuration/ipv4-config.xml

@@ -12,15 +12,18 @@ interfaces.  However, you can configure an interface manually as
 follows:
 
 <programlisting>
-networking.interfaces.eth0.ipv4.addresses = [ { address = "192.168.1.2"; prefixLength = 24; } ];
+<link linkend="opt-networking.interfaces._name__.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ {
+  address = "192.168.1.2";
+  prefixLength = 24;
+} ];
 </programlisting>
 
 Typically you’ll also want to set a default gateway and set of name
 servers:
 
 <programlisting>
-networking.defaultGateway = "192.168.1.1";
+<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
-networking.nameservers = [ "8.8.8.8" ];
+<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
 </programlisting>
 
 </para>
@@ -31,10 +34,10 @@ service
 The default gateway and name server configuration is performed by
 <literal>network-setup.service</literal>.</para></note>
 
-<para>The host name is set using <option>networking.hostName</option>:
+<para>The host name is set using <xref linkend="opt-networking.hostName"/>:
 
 <programlisting>
-networking.hostName = "cartman";
+<xref linkend="opt-networking.hostName"/> = "cartman";
 </programlisting>
 
 The default host name is <literal>nixos</literal>.  Set it to the

nixos/doc/manual/configuration/ipv6-config.xml

@@ -11,14 +11,14 @@ is used to automatically assign IPv6 addresses to all interfaces.  You
 can disable IPv6 support globally by setting:
 
 <programlisting>
-networking.enableIPv6 = false;
+<xref linkend="opt-networking.enableIPv6"/> = false;
 </programlisting></para>
 
 <para>You can disable IPv6 on a single interface using a normal sysctl (in this
 example, we use interface <varname>eth0</varname>):
 
 <programlisting>
-boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;
 </programlisting>
 </para>
 
@@ -26,14 +26,17 @@ boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
 DHCPv6. You can configure an interface manually:
 
 <programlisting>
-networking.interfaces.eth0.ipv6.addresses = [ { address = "fe00:aa:bb:cc::2"; prefixLength = 64; } ];
+<link linkend="opt-networking.interfaces._name__.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ {
+  address = "fe00:aa:bb:cc::2";
+  prefixLength = 64;
+} ];
 </programlisting>
 </para>
 
 <para>For configuring a gateway, optionally with explicitly specified interface:
 
 <programlisting>
-networking.defaultGateway6 = {
+<xref linkend="opt-networking.defaultGateway6"/> = {
   address = "fe00::1";
   interface = "enp0s3";
 }

nixos/doc/manual/configuration/linux-kernel.xml

@@ -10,7 +10,7 @@
 the option <option>boot.kernelPackages</option>.  For instance, this
 selects the Linux 3.10 kernel:
 <programlisting>
-boot.kernelPackages = pkgs.linuxPackages_3_10;
+<xref linkend="opt-boot.kernelPackages"/> = pkgs.linuxPackages_3_10;
 </programlisting>
 Note that this not only replaces the kernel, but also packages that
 are specific to the kernel version, such as the NVIDIA video drivers.
@@ -45,23 +45,23 @@ is typically <literal>y</literal>, <literal>n</literal> or
 
 <para>Kernel modules for hardware devices are generally loaded
 automatically by <command>udev</command>.  You can force a module to
-be loaded via <option>boot.kernelModules</option>, e.g.
+be loaded via <xref linkend="opt-boot.kernelModules"/>, e.g.
 <programlisting>
-boot.kernelModules = [ "fuse" "kvm-intel" "coretemp" ];
+<xref linkend="opt-boot.kernelModules"/> = [ "fuse" "kvm-intel" "coretemp" ];
 </programlisting>
 If the module is required early during the boot (e.g. to mount the
 root file system), you can use
-<option>boot.initrd.extraKernelModules</option>:
+<xref linkend="opt-boot.initrd.extraKernelModules"/>:
 <programlisting>
-boot.initrd.extraKernelModules = [ "cifs" ];
+<xref linkend="opt-boot.initrd.extraKernelModules"/> = [ "cifs" ];
 </programlisting>
 This causes the specified modules and their dependencies to be added
 to the initial ramdisk.</para>
 
 <para>Kernel runtime parameters can be set through
-<option>boot.kernel.sysctl</option>, e.g.
+<xref linkend="opt-boot.kernel.sysctl"/>, e.g.
 <programlisting>
-boot.kernel.sysctl."net.ipv4.tcp_keepalive_time" = 120;
+<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv4.tcp_keepalive_time" = 120;
 </programlisting>
 sets the kernel’s TCP keepalive time to 120 seconds.  To see the
 available parameters, run <command>sysctl -a</command>.</para>

nixos/doc/manual/configuration/luks-file-systems.xml

@@ -33,13 +33,13 @@ as <filename>/</filename>, add the following to
 <filename>configuration.nix</filename>:
 
 <programlisting>
-boot.initrd.luks.devices.crypted.device = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
+<link linkend="opt-boot.initrd.luks.devices._name__.device">boot.initrd.luks.devices.crypted.device</link> = "/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d";
-fileSystems."/".device = "/dev/mapper/crypted";
+<xref linkend="opt-fileSystems"/>."/".device = "/dev/mapper/crypted";
 </programlisting>
 
 Should grub be used as bootloader, and <filename>/boot</filename> is located
 on an encrypted partition, it is necessary to add the following grub option:
-<programlisting>boot.loader.grub.enableCryptodisk = true;</programlisting>
+<programlisting><xref linkend="opt-boot.loader.grub.enableCryptodisk"/> = true;</programlisting>
 
 </para>
 

nixos/doc/manual/configuration/modularity.xml

@@ -22,8 +22,8 @@ use other modules by including them from
 { config, pkgs, ... }:
 
 { imports = [ ./vpn.nix ./kde.nix ];
-  services.httpd.enable = true;
+  <xref linkend="opt-services.httpd.enable"/> = true;
-  environment.systemPackages = [ pkgs.emacs ];
+  <xref linkend="opt-environment.systemPackages"/> = [ pkgs.emacs ];
   <replaceable>...</replaceable>
 }
 </programlisting>
@@ -35,25 +35,25 @@ latter might look like this:
 <programlisting>
 { config, pkgs, ... }:
 
-{ services.xserver.enable = true;
+{ <xref linkend="opt-services.xserver.enable"/> = true;
-  services.xserver.displayManager.sddm.enable = true;
+  <xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
-  services.xserver.desktopManager.plasma5.enable = true;
+  <xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
 }
 </programlisting>
 
 Note that both <filename>configuration.nix</filename> and
 <filename>kde.nix</filename> define the option
-<option>environment.systemPackages</option>.  When multiple modules
+<xref linkend="opt-environment.systemPackages"/>.  When multiple modules
 define an option, NixOS will try to <emphasis>merge</emphasis> the
 definitions.  In the case of
-<option>environment.systemPackages</option>, that’s easy: the lists of
+<xref linkend="opt-environment.systemPackages"/>, that’s easy: the lists of
 packages can simply be concatenated.  The value in
 <filename>configuration.nix</filename> is merged last, so for
 list-type options, it will appear at the end of the merged list. If
 you want it to appear first, you can use <varname>mkBefore</varname>:
 
 <programlisting>
-boot.kernelModules = mkBefore [ "kvm-intel" ];
+<xref linkend="opt-boot.kernelModules"/> = mkBefore [ "kvm-intel" ];
 </programlisting>
 
 This causes the <literal>kvm-intel</literal> kernel module to be
@@ -61,7 +61,7 @@ loaded before any other kernel modules.</para>
 
 <para>For other types of options, a merge may not be possible. For
 instance, if two modules define
-<option>services.httpd.adminAddr</option>,
+<xref linkend="opt-services.httpd.adminAddr"/>,
 <command>nixos-rebuild</command> will give an error:
 
 <screen>
@@ -72,7 +72,7 @@ When that happens, it’s possible to force one definition take
 precedence over the others:
 
 <programlisting>
-services.httpd.adminAddr = pkgs.lib.mkForce "bob@example.org";
+<xref linkend="opt-services.httpd.adminAddr"/> = pkgs.lib.mkForce "bob@example.org";
 </programlisting>
 
 </para>
@@ -89,15 +89,15 @@ wondering how it’s possible that the (indirect)
 is a “lazy” language — it only computes values when they are needed.
 This works as long as no individual configuration value depends on
 itself.</para></footnote>.  For example, here is a module that adds
-some packages to <option>environment.systemPackages</option> only if
+some packages to <xref linkend="opt-environment.systemPackages"/> only if
-<option>services.xserver.enable</option> is set to
+<xref linkend="opt-services.xserver.enable"/> is set to
 <literal>true</literal> somewhere else:
 
 <programlisting>
 { config, pkgs, ... }:
 
-{ environment.systemPackages =
+{ <xref linkend="opt-environment.systemPackages"/> =
-    if config.services.xserver.enable then
+    if config.<xref linkend="opt-services.xserver.enable"/> then
       [ pkgs.firefox
         pkgs.thunderbird
       ]
@@ -113,10 +113,10 @@ value of a configuration option is.  The command
 <option>nixos-option</option> allows you to find out:
 
 <screen>
-$ nixos-option services.xserver.enable
+$ nixos-option <xref linkend="opt-services.xserver.enable"/>
 true
 
-$ nixos-option boot.kernelModules
+$ nixos-option <xref linkend="opt-boot.kernelModules"/>
 [ "tun" "ipv6" "loop" <replaceable>...</replaceable> ]
 </screen>
 
@@ -130,10 +130,10 @@ typical use:
 <screen>
 $ nix-repl '&lt;nixpkgs/nixos>'
 
-nix-repl> config.networking.hostName
+nix-repl> config.<xref linkend="opt-networking.hostName"/>
 "mandark"
 
-nix-repl> map (x: x.hostName) config.services.httpd.virtualHosts
+nix-repl> map (x: x.hostName) config.<xref linkend="opt-services.httpd.virtualHosts"/>
 [ "example.org" "example.gov" ]
 </screen>
 

nixos/doc/manual/configuration/network-manager.xml

@@ -10,7 +10,7 @@
 use NetworkManager. You can enable NetworkManager by setting:
 
 <programlisting>
-networking.networkmanager.enable = true;
+<xref linkend="opt-networking.networkmanager.enable"/> = true;
 </programlisting>
 
 some desktop managers (e.g., GNOME) enable NetworkManager
@@ -20,7 +20,7 @@ automatically for you.</para>
 belong to the <code>networkmanager</code> group:
 
 <programlisting>
-users.extraUsers.youruser.extraGroups = [ "networkmanager" ];
+<link linkend="opt-users.users._name__.extraGroups">users.extraUsers.youruser.extraGroups</link> = [ "networkmanager" ];
 </programlisting>
 </para>
 

nixos/doc/manual/configuration/ssh.xml

@@ -10,12 +10,12 @@
 setting:
 
 <programlisting>
-services.openssh.enable = true;
+<xref linkend="opt-services.openssh.enable"/> = true;
 </programlisting>
 
 By default, root logins using a password are disallowed.  They can be
 disabled entirely by setting
-<literal>services.openssh.permitRootLogin</literal> to
+<xref linkend="opt-services.openssh.permitRootLogin"/> to
 <literal>"no"</literal>.</para>
 
 <para>You can declaratively specify authorised RSA/DSA public keys for
@@ -23,7 +23,7 @@ a user as follows:
 
 <!-- FIXME: this might not work if the user is unmanaged. -->
 <programlisting>
-users.extraUsers.alice.openssh.authorizedKeys.keys =
+<link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.extraUsers.alice.openssh.authorizedKeys.keys</link> =
   [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
 </programlisting>
 

nixos/doc/manual/configuration/summary.xml

@@ -53,7 +53,7 @@ manual</link> for the rest.</para>
       </row>
       <row>
         <entry><literal>{ x = 1; y = 2; }</literal></entry>
-        <entry>An set with attributes names <literal>x</literal> and <literal>y</literal></entry>
+        <entry>A set with attributes named <literal>x</literal> and <literal>y</literal></entry>
       </row>
       <row>
         <entry><literal>{ foo.bar = 1; }</literal></entry>

nixos/doc/manual/configuration/user-mgmt.xml

@@ -12,13 +12,13 @@ management.  In the declarative style, users are specified in
 states that a user account named <literal>alice</literal> shall exist:
 
 <programlisting>
-users.users.alice =
+<xref linkend="opt-users.users"/>.alice = {
-  { isNormalUser = true;
+  <link linkend="opt-users.users._name__.isNormalUser">isNormalUser</link> = true;
-    home = "/home/alice";
+  <link linkend="opt-users.users._name__.home">home</link> = "/home/alice";
-    description = "Alice Foobar";
+  <link linkend="opt-users.users._name__.description">description</link> = "Alice Foobar";
-    extraGroups = [ "wheel" "networkmanager" ];
+  <link linkend="opt-users.users._name__.extraGroups">extraGroups</link> = [ "wheel" "networkmanager" ];
-    openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
+  <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">openssh.authorizedKeys.keys</link> = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
-  };
+};
 </programlisting>
 
 Note that <literal>alice</literal> is a member of the
@@ -32,13 +32,13 @@ a password. However, you can use the <command>passwd</command> program
 to set a password, which is retained across invocations of
 <command>nixos-rebuild</command>.</para>
 
-<para>If you set users.mutableUsers to false, then the contents of /etc/passwd
+<para>If you set <xref linkend="opt-users.mutableUsers"/> to false, then the contents of
-and /etc/group will be congruent to your NixOS configuration. For instance,
+<literal>/etc/passwd</literal> and <literal>/etc/group</literal> will be congruent to
-if you remove a user from users.users and run nixos-rebuild, the user
+your NixOS configuration. For instance, if you remove a user from <xref linkend="opt-users.users"/>
-account will cease to exist. Also, imperative commands for managing users
+and run nixos-rebuild, the user account will cease to exist. Also, imperative commands for managing users
 and groups, such as useradd, are no longer available. Passwords may still be
-assigned by setting the user's <literal>hashedPassword</literal> option. A
+assigned by setting the user's <link linkend="opt-users.users._name__.hashedPassword">hashedPassword</link>
-hashed password can be generated using <command>mkpasswd -m sha-512</command>
+option. A hashed password can be generated using <command>mkpasswd -m sha-512</command>
 after installing the <literal>mkpasswd</literal> package.</para>
 
 <para>A user ID (uid) is assigned automatically.  You can also specify
@@ -54,7 +54,7 @@ to the user specification.</para>
 group named <literal>students</literal> shall exist:
 
 <programlisting>
-users.groups.students.gid = 1000;
+<xref linkend="opt-users.groups"/>.students.gid = 1000;
 </programlisting>
 
 As with users, the group ID (gid) is optional and will be assigned

nixos/doc/manual/configuration/wireless.xml

@@ -15,12 +15,12 @@ section on wireless networks.</para>
 NixOS will start wpa_supplicant for you if you enable this setting:
 
 <programlisting>
-networking.wireless.enable = true;
+<xref linkend="opt-networking.wireless.enable"/> = true;
 </programlisting>
 
 NixOS lets you specify networks for wpa_supplicant declaratively:
 <programlisting>
-networking.wireless.networks = {
+<xref linkend="opt-networking.wireless.networks"/> = {
   echelon = {
     psk = "abcdefgh";
   };

nixos/doc/manual/configuration/x-windows.xml

@@ -9,14 +9,14 @@
 <para>The X Window System (X11) provides the basis of NixOS’ graphical
 user interface.  It can be enabled as follows:
 <programlisting>
-services.xserver.enable = true;
+<xref linkend="opt-services.xserver.enable"/> = true;
 </programlisting>
 The X server will automatically detect and use the appropriate video
 driver from a set of X.org drivers (such as <literal>vesa</literal>
 and <literal>intel</literal>).  You can also specify a driver
 manually, e.g.
 <programlisting>
-services.xserver.videoDrivers = [ "r128" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "r128" ];
 </programlisting>
 to enable X.org’s <literal>xf86-video-r128</literal> driver.</para>
 
@@ -25,13 +25,13 @@ Otherwise, you can only log into a plain undecorated
 <command>xterm</command> window.  Thus you should pick one or more of
 the following lines:
 <programlisting>
-services.xserver.desktopManager.plasma5.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.plasma5.enable"/> = true;
-services.xserver.desktopManager.xfce.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
-services.xserver.desktopManager.gnome3.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.gnome3.enable"/> = true;
-services.xserver.windowManager.xmonad.enable = true;
+<xref linkend="opt-services.xserver.windowManager.xmonad.enable"/> = true;
-services.xserver.windowManager.twm.enable = true;
+<xref linkend="opt-services.xserver.windowManager.twm.enable"/> = true;
-services.xserver.windowManager.icewm.enable = true;
+<xref linkend="opt-services.xserver.windowManager.icewm.enable"/> = true;
-services.xserver.windowManager.i3.enable = true;
+<xref linkend="opt-services.xserver.windowManager.i3.enable"/> = true;
 </programlisting>
 </para>
 
@@ -40,22 +40,22 @@ 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:
 <programlisting>
-services.xserver.displayManager.sddm.enable = true;
+<xref linkend="opt-services.xserver.displayManager.sddm.enable"/> = true;
-services.xserver.displayManager.lightdm.enable = true;
+<xref linkend="opt-services.xserver.displayManager.lightdm.enable"/> = true;
 </programlisting>
 </para>
 
 <para>You can set the keyboard layout (and optionally the layout variant):
 <programlisting>
-services.xserver.layout = "de";
+<xref linkend="opt-services.xserver.layout"/> = "de";
-services.xserver.xkbVariant = "neo";
+<xref linkend="opt-services.xserver.xkbVariant"/> = "neo";
 </programlisting>
 </para>
 
 <para>The X server is started automatically at boot time.  If you
 don’t want this to happen, you can set:
 <programlisting>
-services.xserver.autorun = false;
+<xref linkend="opt-services.xserver.autorun"/> = false;
 </programlisting>
 The X server can then be started manually:
 <screen>
@@ -70,13 +70,13 @@ The X server can then be started manually:
 has better 3D performance than the X.org drivers.  It is not enabled
 by default because it’s not free software.  You can enable it as follows:
 <programlisting>
-services.xserver.videoDrivers = [ "nvidia" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidia" ];
 </programlisting>
 Or if you have an older card, you may have to use one of the legacy drivers:
 <programlisting>
-services.xserver.videoDrivers = [ "nvidiaLegacy340" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy340" ];
-services.xserver.videoDrivers = [ "nvidiaLegacy304" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy304" ];
-services.xserver.videoDrivers = [ "nvidiaLegacy173" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "nvidiaLegacy173" ];
 </programlisting>
 You may need to reboot after enabling this driver to prevent a clash
 with other kernel modules.</para>
@@ -84,7 +84,7 @@ 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>
-hardware.opengl.driSupport32Bit = true;
+<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
 </programlisting>
 </para>
 
@@ -96,7 +96,7 @@ hardware.opengl.driSupport32Bit = true;
 has better 3D performance than the X.org drivers.  It is not enabled
 by default because it’s not free software.  You can enable it as follows:
 <programlisting>
-services.xserver.videoDrivers = [ "ati_unfree" ];
+<xref linkend="opt-services.xserver.videoDrivers"/> = [ "ati_unfree" ];
 </programlisting>
 You will need to reboot after enabling this driver to prevent a clash
 with other kernel modules.</para>
@@ -104,7 +104,7 @@ 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>
-hardware.opengl.driSupport32Bit = true;
+<xref linkend="opt-hardware.opengl.driSupport32Bit"/> = true;
 </programlisting>
 </para>
 
@@ -115,12 +115,12 @@ hardware.opengl.driSupport32Bit = true;
 <para>Support for Synaptics touchpads (found in many laptops such as
 the Dell Latitude series) can be enabled as follows:
 <programlisting>
-services.xserver.libinput.enable = true;
+<xref linkend="opt-services.xserver.libinput.enable"/> = true;
 </programlisting>
 The driver has many options (see <xref linkend="ch-options"/>).  For
 instance, the following disables tap-to-click behavior:
 <programlisting>
-services.xserver.libinput.tapping = false;
+<xref linkend="opt-services.xserver.libinput.tapping"/> = false;
 </programlisting>
 Note: the use of <literal>services.xserver.synaptics</literal> is deprecated since NixOS 17.09.
 </para>

nixos/doc/manual/configuration/xfce.xml

@@ -9,9 +9,9 @@
     <para>
         To enable the Xfce Desktop Environment, set
         <programlisting>
-services.xserver.desktopManager = {
+<link linkend="opt-services.xserver.desktopManager.default">services.xserver.desktopManager</link> = {
-    xfce.enable = true;
+  <link linkend="opt-services.xserver.desktopManager.xfce.enable">xfce.enable</link> = true;
-    default = "xfce";
+  <link linkend="opt-services.xserver.desktopManager.default">default</link> = "xfce";
 };
         </programlisting>
     </para>
@@ -20,12 +20,12 @@ services.xserver.desktopManager = {
         Optionally, <emphasis>compton</emphasis>
         can be enabled for nice graphical effects, some example settings:
         <programlisting>
-services.compton = {
+<link linkend="opt-services.compton.enable">services.compton</link> = {
-  enable          = true;
+  <link linkend="opt-services.compton.enable">enable</link>          = true;
-  fade            = true;
+  <link linkend="opt-services.compton.fade">fade</link>            = true;
-  inactiveOpacity = "0.9";
+  <link linkend="opt-services.compton.inactiveOpacity">inactiveOpacity</link> = "0.9";
-  shadow          = true;
+  <link linkend="opt-services.compton.shadow">shadow</link>          = true;
-  fadeDelta       = 4;
+  <link linkend="opt-services.compton.fadeDelta">fadeDelta</link>       = 4;
 };
         </programlisting>
     </para>
@@ -33,7 +33,7 @@ services.compton = {
     <para>
         Some Xfce programs are not installed automatically.
         To install them manually (system wide), put them into your
-        <literal>environment.systemPackages</literal>.
+        <xref linkend="opt-environment.systemPackages"/>.
     </para>
 
     <simplesect>
@@ -44,7 +44,7 @@ services.compton = {
             <emphasis>Thunar</emphasis>
             volume support, put
             <programlisting>
-services.xserver.desktopManager.xfce.enable = true;
+<xref linkend="opt-services.xserver.desktopManager.xfce.enable"/> = true;
             </programlisting>
             into your <emphasis>configuration.nix</emphasis>.
         </para>

nixos/doc/manual/default.nix

@@ -102,13 +102,18 @@ let
     </section>
   '';
 
+  generatedSources = runCommand "generated-docbook" {} ''
+    mkdir $out
+    ln -s ${modulesDoc} $out/modules.xml
+    ln -s ${optionsDocBook} $out/options-db.xml
+    printf "%s" "${version}" > $out/version
+  '';
+
   copySources =
     ''
       cp -prd $sources/* . # */
+      ln -s ${generatedSources} ./generated
       chmod -R u+w .
-      ln -s ${modulesDoc} configuration/modules.xml
-      ln -s ${optionsDocBook} options-db.xml
-      printf "%s" "${version}" > version
     '';
 
   toc = builtins.toFile "toc.xml"
@@ -224,6 +229,7 @@ let
     '';
 
 in rec {
+  inherit generatedSources;
 
   # The NixOS options in JSON format.
   optionsJSON = runCommand "options-json"

nixos/doc/manual/development/importing-modules.xml

@@ -0,0 +1,59 @@
+<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-importing-modules">
+
+<title>Importing Modules</title>
+
+<para>
+  Sometimes NixOS modules need to be used in configuration but exist
+  outside of Nixpkgs. These modules can be imported:
+</para>
+
+<programlisting>
+{ config, lib, pkgs, ... }:
+
+{
+  imports =
+    [ # Use a locally-available module definition in
+      # ./example-module/default.nix
+        ./example-module
+    ];
+
+  services.exampleModule.enable = true;
+}
+</programlisting>
+
+<para>
+  The environment variable <literal>NIXOS_EXTRA_MODULE_PATH</literal> is
+  an absolute path to a NixOS module that is included alongside the
+  Nixpkgs NixOS modules. Like any NixOS module, this module can import
+  additional modules:
+</para>
+
+<programlisting>
+# ./module-list/default.nix
+[
+  ./example-module1
+  ./example-module2
+]
+</programlisting>
+
+<programlisting>
+# ./extra-module/default.nix
+{ imports = import ./module-list.nix; }
+</programlisting>
+
+<programlisting>
+# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module
+{ config, lib, pkgs, ... }:
+
+{
+  # No `imports` needed
+
+  services.exampleModule1.enable = true;
+}
+</programlisting>
+
+</section>

nixos/doc/manual/development/writing-documentation.xml

@@ -18,13 +18,25 @@
 <para>
   The DocBook sources of the <xref linkend="book-nixos-manual"/> are in the
   <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual"><filename>nixos/doc/manual</filename></link>
-  subdirectory of the Nixpkgs repository. If you make modifications to
+  subdirectory of the Nixpkgs repository.
-  the manual, it's important to build it before committing. You can do
-  that as follows:
-
-  <screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
 </para>
 
+<para>
+  You can quickly validate your edits with <command>make</command>:
+</para>
+
+<screen>
+  $ cd /path/to/nixpkgs/nixos/doc/manual
+  $ make
+</screen>
+
+<para>
+  Once you are done making modifications to the manual, it's important
+  to build it before committing. You can do that as follows:
+</para>
+
+<screen>nix-build nixos/release.nix -A manual.x86_64-linux</screen>
+
 <para>
   When this command successfully finishes, it will tell you where the
   manual got generated. The HTML will be accessible through the

nixos/doc/manual/development/writing-modules.xml

@@ -180,6 +180,7 @@ in {
 <xi:include href="option-def.xml" />
 <xi:include href="assertions.xml" />
 <xi:include href="meta-attributes.xml" />
+<xi:include href="importing-modules.xml" />
 <xi:include href="replace-modules.xml" />
 
 </chapter>

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

@@ -75,7 +75,7 @@ have set <literal>mutableUsers = false</literal>.  Another way is to
 temporarily add the following to your configuration:
 
 <screen>
-users.extraUsers.your-user.initialPassword = "test"  
+<link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.your-user.initialHashedPassword</link> = "test";
 </screen>
 
 <emphasis>Important:</emphasis> delete the $hostname.qcow2 file if you

nixos/doc/manual/installation/installing-from-other-distro.xml

@@ -111,7 +111,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-<replaceable>version</repla
                 <literal>configuration.nix</literal>:</para>
 
             <programlisting>
-boot.loader.grub.extraEntries = ''
+<xref linkend="opt-boot.loader.grub.extraEntries"/> = ''
   menuentry "Ubuntu" {
     search --set=ubuntu --fs-uuid 3cc3e652-0c1f-4800-8451-033754f68e6e
     configfile "($ubuntu)/boot/grub/grub.cfg"
@@ -183,7 +183,9 @@ $ sudo groupdel nixbld</screen>
                 account with <literal>sudo passwd -l root</literal> if you use
                 <literal>sudo</literal>)</para>
 
-            <programlisting>users.extraUsers.root.initialHashedPassword = "";</programlisting>
+              <programlisting>
+<link linkend="opt-users.users._name__.initialHashedPassword">users.extraUsers.root.initialHashedPassword</link> = "";
+              </programlisting>
         </listitem>
 
         <listitem>
@@ -243,13 +245,15 @@ $ sudo groupdel nixbld</screen>
 
             <screen>
 $ sudo touch /etc/NIXOS
-$ sudo touch /etc/NIXOS_LUSTRATE</screen>
+$ 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>
+$ echo etc/nixos | sudo tee -a /etc/NIXOS_LUSTRATE
+            </screen>
         </listitem>
 
         <listitem>

nixos/doc/manual/installation/installing-virtualbox-guest.xml

@@ -42,7 +42,7 @@
 </para>
 
 <programlisting>
-boot.loader.grub.device = "/dev/sda";
+<xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";
 </programlisting>
 
 <para>
@@ -51,7 +51,7 @@ boot.loader.grub.device = "/dev/sda";
 </para>
 
 <programlisting>
-boot.initrd.checkJournalingFS = false;
+<xref linkend="opt-boot.initrd.checkJournalingFS"/> = false;
 </programlisting>
 
 <para>

nixos/doc/manual/installation/installing.xml

@@ -204,25 +204,28 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
 
       <varlistentry><term>BIOS systems</term>
         <listitem><para>You <emphasis>must</emphasis> set the option
-    <option>boot.loader.grub.device</option> to specify on which disk
+            <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk
             the GRUB boot loader is to be installed.  Without it, NixOS cannot
             boot.</para></listitem></varlistentry>
 
       <varlistentry><term>UEFI systems</term>
         <listitem><para>You <emphasis>must</emphasis> set the option
-      <option>boot.loader.systemd-boot.enable</option> to <literal>true</literal>.
+            <xref linkend="opt-boot.loader.systemd-boot.enable"/> to <literal>true</literal>.
             <command>nixos-generate-config</command> should do this automatically for new
             configurations when booted in
             UEFI mode.</para>
           <para>You may want to look at the options starting with
-      <option>boot.loader.efi</option> and <option>boot.loader.systemd-boot</option>
+            <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> and
-      as well.</para></listitem></varlistentry>
+            <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option> as well.
+          </para>
+        </listitem>
+      </varlistentry>
 
     </variablelist>
 
     <para>If there are other operating systems running on the machine before
     installing NixOS, the
-    <option>boot.loader.grub.useOSProber</option> option can be set to
+    <xref linkend="opt-boot.loader.grub.useOSProber"/> option can be set to
     <literal>true</literal> to automatically add them to the grub menu.</para>
 
     <para>Another critical option is <option>fileSystems</option>,
@@ -264,15 +267,15 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
     <para>As the last step, <command>nixos-install</command> will ask
     you to set the password for the <literal>root</literal> user, e.g.
 
-<screen>
+    <screen>
 setting root password...
 Enter new UNIX password: ***
 Retype new UNIX password: ***
-</screen>
+    </screen>
 
     <note>
       <para>
-        To prevent the password prompt, set <code>users.mutableUsers = false;</code> in
+        To prevent the password prompt, set <code><xref linkend="opt-users.mutableUsers"/> = false;</code> in
         <filename>configuration.nix</filename>, which allows unattended installation
         necessary in automation.
       </para>
@@ -285,8 +288,8 @@ Retype new UNIX password: ***
   <listitem>
     <para>If everything went well:
 
-<screen>
+      <screen>
-# reboot</screen>
+        # reboot</screen>
 
   </para></listitem>
 
@@ -372,26 +375,25 @@ drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"
 </example>
 
 <example xml:id='ex-config'><title>NixOS Configuration</title>
-<screen>
+  <screen>
-{ config, pkgs, ... }:
+{ config, pkgs, ... }: {
-
+  imports = [
-{
+    # Include the results of the hardware scan.
-  imports =
-    [ # Include the results of the hardware scan.
     ./hardware-configuration.nix
   ];
 
-  boot.loader.grub.device = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
+  <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
-  boot.loader.systemd-boot.enable = true; # <lineannotation>(for UEFI systems only)</lineannotation>
+  <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation>
 
   # Note: setting fileSystems is generally not
   # necessary, since nixos-generate-config figures them out
   # automatically in hardware-configuration.nix.
-  #fileSystems."/".device = "/dev/disk/by-label/nixos";
+  #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos";
 
   # Enable the OpenSSH server.
   services.sshd.enable = true;
-}</screen>
+}
+  </screen>
 </example>
 
 <xi:include href="installing-usb.xml" />

nixos/doc/manual/installation/upgrading.xml

@@ -119,7 +119,7 @@ able to go back to your original channel.</para></warning>
 the following to <filename>configuration.nix</filename>:
 
 <programlisting>
-system.autoUpgrade.enable = true;
+<xref linkend="opt-system.autoUpgrade.enable"/> = true;
 </programlisting>
 
 This enables a periodically executed systemd service named
@@ -130,7 +130,7 @@ runs, see <command>systemctl list-timers</command>.)  You can also
 specify a channel explicitly, e.g.
 
 <programlisting>
-system.autoUpgrade.channel = https://nixos.org/channels/nixos-17.03;
+<xref linkend="opt-system.autoUpgrade.channel"/> = https://nixos.org/channels/nixos-17.03;
 </programlisting>
 
 </para>

nixos/doc/manual/man-configuration.xml

@@ -31,7 +31,8 @@ therein.</para>
 <para>You can use the following options in
 <filename>configuration.nix</filename>.</para>
 
-<xi:include href="options-db.xml" />
+<xi:include href="./generated/options-db.xml"
+            xpointer="configuration-variable-list" />
 
 </refsection>
 

nixos/doc/manual/man-nixos-install.xml

@@ -57,9 +57,6 @@
     <arg>
       <arg choice='plain'><option>--show-trace</option></arg>
     </arg>
-    <arg>
-      <arg choice='plain'><option>--chroot</option></arg>
-    </arg>
     <arg>
       <arg choice='plain'><option>--help</option></arg>
     </arg>
@@ -177,14 +174,6 @@ it.</para>
     </listitem>
   </varlistentry>
 
-  <varlistentry>
-    <term><option>--chroot</option></term>
-    <listitem>
-      <para>Chroot into given installation. Any additional arguments passed are going to be executed inside the chroot.
-      </para>
-    </listitem>
-  </varlistentry>
-
   <varlistentry>
     <term><option>--help</option></term>
     <listitem>

nixos/doc/manual/manual.xml

@@ -6,7 +6,7 @@
 
   <info>
     <title>NixOS Manual</title>
-    <subtitle>Version <xi:include href="version" parse="text" /></subtitle>
+    <subtitle>Version <xi:include href="./generated/version" parse="text" /></subtitle>
   </info>
 
   <preface>
@@ -39,7 +39,8 @@
 
   <appendix xml:id="ch-options">
     <title>Configuration Options</title>
-    <xi:include href="options-db.xml" />
+    <xi:include href="./generated/options-db.xml"
+                xpointer="configuration-variable-list" />
   </appendix>
 
   <xi:include href="release-notes/release-notes.xml" />

nixos/doc/manual/options-to-docbook.xsl

@@ -15,9 +15,9 @@
 
 
   <xsl:template match="/expr/list">
-
+    <appendix>
-      <variablelist>
+      <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, '*', '_'), '&lt;', '_'), '>', '_'), '?', '_'))" />
           <varlistentry>
@@ -100,7 +100,7 @@
         </xsl:for-each>
 
       </variablelist>
-
+    </appendix>
   </xsl:template>
 
 

nixos/doc/manual/release-notes/rl-1809.xml

@@ -20,10 +20,21 @@ has the following highlights: </para>
 <itemizedlist>
   <listitem>
     <para>
-      TODO
+      User channels are now in the default <literal>NIX_PATH</literal>,
+      allowing users to use their personal <command>nix-channel</command>
+      defined channels in <command>nix-build</command> and
+      <command>nix-shell</command> commands, as well as in imports like
+      <code>import &lt;mychannel&gt;</code>.
     </para>
+    <para>For example</para>
+    <programlisting>
+$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgsunstable
+$ nix-channel --update
+$ nix-build '&lt;nixpkgsunstable&gt;' -A gitFull
+$ nix run -f '&lt;nixpkgsunstable&gt;' gitFull
+$ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
+</programlisting>
   </listitem>
-
 </itemizedlist>
 
 </section>
@@ -56,6 +67,11 @@ has the following highlights: </para>
 following incompatible changes:</para>
 
 <itemizedlist>
+  <listitem>
+    <para>
+      <literal>lib.strict</literal> is removed. Use <literal>builtins.seq</literal> instead.
+    </para>
+  </listitem>
   <listitem>
     <para>
       The <literal>clementine</literal> package points now to the free derivation.
@@ -63,6 +79,15 @@ following incompatible changes:</para>
       points to the package which is bundled with the unfree <literal>libspotify</literal> package.
     </para>
   </listitem>
+  <listitem>
+    <para>
+      The <literal>netcat</literal> package is now taken directly from OpenBSD's
+      <literal>libressl</literal>, instead of relying on Debian's fork. The new
+      version should be very close to the old version, but there are some minor
+      differences. Importantly, flags like -b, -q, -C, and -Z are no longer
+      accepted by the nc command.
+    </para>
+  </listitem>
 </itemizedlist>
 
 </section>
@@ -77,6 +102,51 @@ following incompatible changes:</para>
 <itemizedlist>
   <listitem>
     <para>
+      <literal>lib.attrNamesToStr</literal> has been deprecated. Use
+      more specific concatenation (<literal>lib.concat(Map)StringsSep</literal>)
+      instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.addErrorContextToAttrs</literal> has been deprecated. Use
+      <literal>builtins.addErrorContext</literal> directly.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.showVal</literal> has been deprecated. Use
+      <literal>lib.traceSeqN</literal> instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.traceXMLVal</literal> has been deprecated. Use
+      <literal>lib.traceValFn builtins.toXml</literal> instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.traceXMLValMarked</literal> has been deprecated. Use
+      <literal>lib.traceValFn (x: str + builtins.toXML x)</literal> instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.traceValIfNot</literal> has been deprecated. Use
+      <literal>if/then/else</literal> and <literal>lib.traceValSeq</literal>
+      instead.
+    </para>
+  </listitem>
+  <listitem>
+    <para>
+      <literal>lib.traceCallXml</literal> has been deprecated. Please complain
+      if you use the function regularly.
+    </para>
+    <para>
+      The attribute <literal>lib.nixpkgsVersion</literal> has been deprecated in favor of
+      <literal>lib.version</literal>. Please refer to the discussion in
+      <link xlink:href="https://github.com/NixOS/nixpkgs/pull/39416#discussion_r183845745">NixOS/nixpkgs#39416</link> for further reference.
     </para>
   </listitem>
 </itemizedlist>

nixos/lib/qemu-flags.nix

@@ -9,7 +9,7 @@
     ];
 
   qemuSerialDevice = if pkgs.stdenv.isi686 || pkgs.stdenv.isx86_64 then "ttyS0"
-        else if pkgs.stdenv.isArm || pkgs.stdenv.isAarch64 then "ttyAMA0"
+        else if pkgs.stdenv.isAarch32 || pkgs.stdenv.isAarch64 then "ttyAMA0"
         else throw "Unknown QEMU serial device for system '${pkgs.stdenv.system}'";
 
   qemuBinary = qemuPkg: {

nixos/lib/test-driver/Machine.pm

@@ -33,9 +33,20 @@ sub new {
         $startCommand =
             "qemu-kvm -m 384 " .
             "-net nic,model=virtio \$QEMU_OPTS ";
-        my $iface = $args->{hdaInterface} || "virtio";
+
-        $startCommand .= "-drive file=" . Cwd::abs_path($args->{hda}) . ",if=$iface,werror=report "
+        if (defined $args->{hda}) {
-            if defined $args->{hda};
+            if ($args->{hdaInterface} eq "scsi") {
+                $startCommand .= "-drive id=hda,file="
+                               . Cwd::abs_path($args->{hda})
+                               . ",werror=report,if=none "
+                               . "-device scsi-hd,drive=hda ";
+            } else {
+                $startCommand .= "-drive file=" . Cwd::abs_path($args->{hda})
+                               . ",if=" . $args->{hdaInterface}
+                               . ",werror=report ";
+            }
+        }
+
         $startCommand .= "-cdrom $args->{cdrom} "
             if defined $args->{cdrom};
         $startCommand .= "-device piix3-usb-uhci -drive id=usbdisk,file=$args->{usb},if=none,readonly -device usb-storage,drive=usbdisk "

nixos/maintainers/scripts/ec2/create-amis.sh

@@ -6,7 +6,7 @@
 set -e
 set -o pipefail
 
-version=$(nix-instantiate --eval --strict '<nixpkgs>' -A lib.nixpkgsVersion | sed s/'"'//g)
+version=$(nix-instantiate --eval --strict '<nixpkgs>' -A lib.version | sed s/'"'//g)
 major=${version:0:5}
 echo "NixOS version is $version ($major)"
 

nixos/modules/config/gnu.nix

@@ -26,11 +26,11 @@ with lib;
         nano zile
         texinfo # for the stand-alone Info reader
       ]
-      ++ stdenv.lib.optional (!stdenv.isArm) grub2;
+      ++ stdenv.lib.optional (!stdenv.isAarch32) grub2;
 
 
     # GNU GRUB, where available.
-    boot.loader.grub.enable = !pkgs.stdenv.isArm;
+    boot.loader.grub.enable = !pkgs.stdenv.isAarch32;
     boot.loader.grub.version = 2;
 
     # GNU lsh.

nixos/modules/i18n/input-method/default.xml

@@ -32,8 +32,8 @@
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "ibus";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "ibus";
-  ibus.engines = with pkgs.ibus-engines; [ anthy hangul mozc ];
+  <link linkend="opt-i18n.inputMethod.ibus.engines">ibus.engines</link> = with pkgs.ibus-engines; [ anthy hangul mozc ];
 };
 </programlisting>
 
@@ -79,8 +79,8 @@ ibus.engines = with pkgs.ibus-engines; [ table table-others ];
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "fcitx";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "fcitx";
-  fcitx.engines = with pkgs.fcitx-engines; [ mozc hangul m17n ];
+  <link linkend="opt-i18n.inputMethod.fcitx.engines">fcitx.engines</link> = with pkgs.fcitx-engines; [ mozc hangul m17n ];
 };
 </programlisting>
 
@@ -119,7 +119,7 @@ i18n.inputMethod = {
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "nabi";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "nabi";
 };
 </programlisting>
 </section>
@@ -132,11 +132,11 @@ i18n.inputMethod = {
 
 <programlisting>
 i18n.inputMethod = {
-  enabled = "uim";
+  <link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "uim";
 };
 </programlisting>
 
-<para>Note: The <literal>i18n.inputMethod.uim.toolbar</literal> option can be 
+<para>Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be
   used to choose uim toolbar.</para>
 
 </section>

nixos/modules/installer/cd-dvd/iso-image.nix

@@ -73,7 +73,8 @@ let
     APPEND ${toString config.boot.loader.grub.memtest86.params}
   '';
 
-  isolinuxCfg = baseIsolinuxCfg + (optionalString config.boot.loader.grub.memtest86.enable isolinuxMemtest86Entry);
+  isolinuxCfg = concatStringsSep "\n"
+    ([ baseIsolinuxCfg ] ++ optional config.boot.loader.grub.memtest86.enable isolinuxMemtest86Entry);
 
   # The EFI boot image.
   efiDir = pkgs.runCommand "efi-directory" {} ''

nixos/modules/installer/tools/nixos-generate-config.pl

@@ -577,8 +577,8 @@ $bootLoaderConfig
   # Set your time zone.
   # time.timeZone = "Europe/Amsterdam";
 
-  # List packages installed in system profile. To search by name, run:
+  # List packages installed in system profile. To search, run:
-  # \$ nix-env -qaP | grep wget
+  # \$ nix search wget
   # environment.systemPackages = with pkgs; [
   #   wget vim
   # ];

nixos/modules/misc/ids.nix

@@ -138,7 +138,6 @@
       ngircd = 112;
       btsync = 113;
       minecraft = 114;
-      #monetdb = 115; # unused (not packaged), removed 2016-09-19
       vault = 115;
       rippled = 116;
       murmur = 117;
@@ -306,6 +305,7 @@
       monero = 287;
       ceph = 288;
       duplicati = 289;
+      monetdb = 290;
 
       # When adding a uid, make sure it doesn't match an existing gid. And don't use uids above 399!
 
@@ -424,7 +424,6 @@
       #ngircd = 112; # unused
       btsync = 113;
       #minecraft = 114; # unused
-      #monetdb = 115; # unused (not packaged), removed 2016-09-19
       vault = 115;
       #ripped = 116; # unused
       #murmur = 117; # unused
@@ -580,6 +579,7 @@
       monero = 287;
       ceph = 288;
       duplicati = 289;
+      monetdb = 290;
 
       # When adding a gid, make sure it doesn't match an existing
       # uid. Users and groups with the same name should have equal

nixos/modules/misc/nixpkgs.nix

@@ -33,7 +33,11 @@ let
   configType = mkOptionType {
     name = "nixpkgs-config";
     description = "nixpkgs config";
-    check = traceValIfNot isConfig;
+    check = x:
+      let traceXIfNot = c:
+            if c x then true
+            else lib.traceSeqN 1 x false;
+      in traceXIfNot isConfig;
     merge = args: fold (def: mergeConfig def.value) {};
   };
 

nixos/modules/misc/version.nix

@@ -5,8 +5,6 @@ with lib;
 let
   cfg = config.system.nixos;
 
-  releaseFile  = "${toString pkgs.path}/.version";
-  suffixFile   = "${toString pkgs.path}/.version-suffix";
   revisionFile = "${toString pkgs.path}/.git-revision";
   gitRepo      = "${toString pkgs.path}/.git";
   gitCommitId  = lib.substring 0 7 (commitIdFromGitRepo gitRepo);
@@ -25,14 +23,14 @@ in
     nixos.release = mkOption {
       readOnly = true;
       type = types.str;
-      default = fileContents releaseFile;
+      default = trivial.release;
       description = "The NixOS release (e.g. <literal>16.03</literal>).";
     };
 
     nixos.versionSuffix = mkOption {
       internal = true;
       type = types.str;
-      default = if pathExists suffixFile then fileContents suffixFile else "pre-git";
+      default = trivial.versionSuffix;
       description = "The NixOS version suffix (e.g. <literal>1160.f2d4ee1</literal>).";
     };
 

nixos/modules/module-list.nix

@@ -199,6 +199,7 @@
   ./services/databases/hbase.nix
   ./services/databases/influxdb.nix
   ./services/databases/memcached.nix
+  ./services/databases/monetdb.nix
   ./services/databases/mongodb.nix
   ./services/databases/mysql.nix
   ./services/databases/neo4j.nix
@@ -250,6 +251,7 @@
   ./services/hardware/illum.nix
   ./services/hardware/interception-tools.nix
   ./services/hardware/irqbalance.nix
+  ./services/hardware/lcd.nix
   ./services/hardware/nvidia-optimus.nix
   ./services/hardware/pcscd.nix
   ./services/hardware/pommed.nix
@@ -327,7 +329,7 @@
   ./services/misc/geoip-updater.nix
   ./services/misc/gitea.nix
   #./services/misc/gitit.nix
-  #./services/misc/gitlab.nix
+  ./services/misc/gitlab.nix
   ./services/misc/gitolite.nix
   ./services/misc/gitweb.nix
   ./services/misc/gogs.nix
@@ -650,6 +652,7 @@
   ./services/web-servers/apache-httpd/default.nix
   ./services/web-servers/caddy.nix
   ./services/web-servers/fcgiwrap.nix
+  ./services/web-servers/hitch/default.nix
   ./services/web-servers/jboss/default.nix
   ./services/web-servers/lighttpd/cgit.nix
   ./services/web-servers/lighttpd/collectd.nix

nixos/modules/programs/digitalbitbox/doc.xml

@@ -15,9 +15,9 @@
     installed by setting <literal>programs.digitalbitbox</literal>
     to <literal>true</literal> in a manner similar to
 
-    <programlisting>
+<programlisting>
-      programs.digitalbitbox.enable = true;
+<xref linkend="opt-programs.digitalbitbox.enable"/> = true;
-    </programlisting>
+</programlisting>
 
     and bundles the <literal>digitalbitbox</literal> package (see <xref
       linkend="sec-digitalbitbox-package" />), which contains the
@@ -46,11 +46,11 @@
       <literal>digitalbitbox</literal> package which could be installed
       as follows:
 
-      <programlisting>
+<programlisting>
-        environment.systemPackages = [
+<xref linkend="opt-environment.systemPackages"/> = [
   pkgs.digitalbitbox
-        ];
+];
-      </programlisting>
+</programlisting>
     </para>
   </section>
 
@@ -62,9 +62,9 @@
       The digitalbitbox hardware package enables the udev rules for
       Digital Bitbox devices and may be installed as follows:
 
-      <programlisting>
+<programlisting>
-        hardware.digitalbitbox.enable = true;
+<xref linkend="opt-hardware.digitalbitbox.enable"/> = true;
-      </programlisting>
+</programlisting>
     </para>
 
     <para>
@@ -72,14 +72,14 @@
       the <literal>udevRule51</literal> and <literal>udevRule52</literal>
       attributes by means of overriding as follows:
 
-      <programlisting>
+<programlisting>
-        programs.digitalbitbox = {
+programs.digitalbitbox = {
-          enable = true;
+  <link linkend="opt-programs.digitalbitbox.enable">enable</link> = true;
-          package = pkgs.digitalbitbox.override {
+  <link linkend="opt-programs.digitalbitbox.package">package</link> = pkgs.digitalbitbox.override {
     udevRule51 = "something else";
   };
-        };
+};
-      </programlisting>
+</programlisting>
     </para>
   </section>
 </chapter>

nixos/modules/programs/plotinus.xml

@@ -17,7 +17,7 @@
 <para>To enable Plotinus, add the following to your <filename>configuration.nix</filename>:
 
 <programlisting>
-programs.plotinus.enable = true;
+<xref linkend="opt-programs.plotinus.enable"/> = true;
 </programlisting>
 
 </para>

nixos/modules/security/acme.xml

@@ -48,9 +48,9 @@ http {
 <filename>configuration.nix</filename>:
 
 <programlisting>
-security.acme.certs."foo.example.com" = {
+<xref linkend="opt-security.acme.certs"/>."foo.example.com" = {
-  webroot = "/var/www/challenges";
+  <link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges";
-  email = "foo@example.com";
+  <link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com";
 };
 </programlisting>
 </para>
@@ -58,17 +58,17 @@ security.acme.certs."foo.example.com" = {
 <para>The private key <filename>key.pem</filename> and certificate
 <filename>fullchain.pem</filename> will be put into
 <filename>/var/lib/acme/foo.example.com</filename>. The target directory can
-be configured with the option <literal>security.acme.directory</literal>.
+be configured with the option <xref linkend="opt-security.acme.directory"/>.
 </para>
 
 <para>Refer to <xref linkend="ch-options" /> for all available configuration
-options for the <literal>security.acme</literal> module.</para>
+options for the <link linkend="opt-security.acme.certs">security.acme</link> module.</para>
 
 </section>
 
 <section><title>Using ACME certificates in Nginx</title>
 <para>NixOS supports fetching ACME certificates for you by setting
-<literal>enableACME = true;</literal> in a virtualHost config. We
+  <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;</literal> in a virtualHost config. We
 first create self-signed placeholder certificates in place of the
 real ACME certs. The placeholder certs are overwritten when the ACME
 certs arrive. For <literal>foo.example.com</literal> the config would
@@ -77,13 +77,13 @@ look like.
 
 <programlisting>
 services.nginx = {
-  enable = true;
+  <link linkend="opt-services.nginx.enable">enable = true;</link>
-  virtualHosts = {
+  <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {
     "foo.example.com" = {
-      forceSSL = true;
+      <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
-      enableACME = true;
+      <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
       locations."/" = {
-        root = "/var/www";
+        <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.root">root</link> = "/var/www";
       };
     };
   };

nixos/modules/security/hidepid.xml

@@ -8,9 +8,9 @@
 
   <para>
     Setting
-    <programlisting>
+<programlisting>
-      security.hideProcessInformation = true;
+<xref linkend="opt-security.hideProcessInformation"/> = true;
-    </programlisting>
+</programlisting>
     ensures that access to process information is restricted to the
     owning user.  This implies, among other things, that command-line
     arguments remain private.  Unless your deployment relies on unprivileged
@@ -25,9 +25,9 @@
 
   <para>
     To allow a service <replaceable>foo</replaceable> to run without process information hiding, set
-    <programlisting>
+<programlisting>
-      systemd.services.<replaceable>foo</replaceable>.serviceConfig.SupplementaryGroups = [ "proc" ];
+<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.<replaceable>foo</replaceable>.serviceConfig</link>.SupplementaryGroups = [ "proc" ];
-    </programlisting>
+</programlisting>
   </para>
 
 </chapter>

nixos/modules/services/audio/alsa.nix

@@ -54,6 +54,11 @@ in
           description = ''
             Whether to enable volume and capture control with keyboard media keys.
 
+            You want to leave this disabled if you run a desktop environment
+            like KDE, Gnome, Xfce, etc, as those handle such things themselves.
+            You might want to enable this if you run a minimalistic desktop
+            environment or work from bare linux ttys/framebuffers.
+
             Enabling this will turn on <option>services.actkbd</option>.
           '';
         };

nixos/modules/services/continuous-integration/buildkite-agent.nix

@@ -17,7 +17,7 @@ let
 
   hooksDir = let
     mkHookEntry = name: value: ''
-      cat > $out/${name} <<EOF
+      cat > $out/${name} <<'EOF'
       #! ${pkgs.runtimeShell}
       set -e
       ${value}

nixos/modules/services/databases/foundationdb.xml

@@ -16,8 +16,8 @@
 
 <para>FoundationDB (or "FDB") is a distributed, open source, high performance,
 transactional key-value store. It can store petabytes of data and deliver
-exceptional performance while maintaining consistency and ACID semantics over a
+exceptional performance while maintaining consistency and ACID semantics
-large cluster.</para>
+(serializable transactions) over a large cluster.</para>
 
 <section><title>Configuring and basic setup</title>
 
@@ -101,7 +101,7 @@ FoundationDB worker processes that should be started on the machine.</para>
 
 <para>FoundationDB worker processes typically require 4GB of RAM per-process at
 minimum for good performance, so this option is set to 1 by default since the
-maximum aount of RAM is unknown. You're advised to abide by this restriction,
+maximum amount of RAM is unknown. You're advised to abide by this restriction,
 so pick a number of processes so that each has 4GB or more.</para>
 
 <para>A similar option exists in order to scale backup agent processes,
@@ -129,7 +129,8 @@ client applications will use to find and join coordinators. Note that this file
 <emphasis>can not</emphasis> be managed by NixOS so easily: FoundationDB is
 designed so that it will rewrite the file at runtime for all clients and nodes
 when cluster coordinators change, with clients transparently handling this
-without intervention.</para>
+without intervention. It is fundamentally a mutable file, and you should not
+try to manage it in any way in NixOS.</para>
 
 <para>When dealing with a cluster, there are two main things you want to
 do:</para>

nixos/modules/services/databases/monetdb.nix

@@ -0,0 +1,100 @@
+{ config, lib, pkgs, ... }:
+
+with lib;
+
+let
+  cfg = config.services.monetdb;
+
+in {
+  meta.maintainers = with maintainers; [ StillerHarpo primeos ];
+
+  ###### interface
+  options = {
+    services.monetdb = {
+
+      enable = mkEnableOption "the MonetDB database server";
+
+      package = mkOption {
+        type = types.package;
+        default = pkgs.monetdb;
+        defaultText = "pkgs.monetdb";
+        description = "MonetDB package to use.";
+      };
+
+      user = mkOption {
+        type = types.str;
+        default = "monetdb";
+        description = "User account under which MonetDB runs.";
+      };
+
+      group = mkOption {
+        type = types.str;
+        default = "monetdb";
+        description = "Group under which MonetDB runs.";
+      };
+
+      dataDir = mkOption {
+        type = types.path;
+        default = "/var/lib/monetdb";
+        description = "Data directory for the dbfarm.";
+      };
+
+      port = mkOption {
+        type = types.ints.u16;
+        default = 50000;
+        description = "Port to listen on.";
+      };
+
+      listenAddress = mkOption {
+        type = types.str;
+        default = "127.0.0.1";
+        example = "0.0.0.0";
+        description = "Address to listen on.";
+      };
+    };
+  };
+
+  ###### implementation
+  config = mkIf cfg.enable {
+
+    users.users.monetdb = mkIf (cfg.user == "monetdb") {
+      uid = config.ids.uids.monetdb;
+      group = cfg.group;
+      description = "MonetDB user";
+      home = cfg.dataDir;
+      createHome = true;
+    };
+
+    users.groups.monetdb = mkIf (cfg.group == "monetdb") {
+      gid = config.ids.gids.monetdb;
+      members = [ cfg.user ];
+    };
+
+    environment.systemPackages = [ cfg.package ];
+
+    systemd.services.monetdb = {
+      description = "MonetDB database server";
+      wantedBy = [ "multi-user.target" ];
+      after = [ "network.target" ];
+      path = [ cfg.package ];
+      unitConfig.RequiresMountsFor = "${cfg.dataDir}";
+      serviceConfig = {
+        User = cfg.user;
+        Group = cfg.group;
+        ExecStart = "${cfg.package}/bin/monetdbd start -n ${cfg.dataDir}";
+        ExecStop = "${cfg.package}/bin/monetdbd stop ${cfg.dataDir}";
+      };
+      preStart = ''
+        if [ ! -e ${cfg.dataDir}/.merovingian_properties ]; then
+          # Create the dbfarm (as cfg.user)
+          ${cfg.package}/bin/monetdbd create ${cfg.dataDir}
+        fi
+
+        # Update the properties
+        ${cfg.package}/bin/monetdbd set port=${toString cfg.port} ${cfg.dataDir}
+        ${cfg.package}/bin/monetdbd set listenaddr=${cfg.listenAddress} ${cfg.dataDir}
+      '';
+    };
+
+  };
+}

nixos/modules/services/databases/postgresql.xml

@@ -23,15 +23,15 @@
 <filename>configuration.nix</filename>:
 
 <programlisting>
-services.postgresql.enable = true;
+<xref linkend="opt-services.postgresql.enable"/> = true;
-services.postgresql.package = pkgs.postgresql94;
+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql94;
 </programlisting>
 
 Note that you are required to specify the desired version of
 PostgreSQL (e.g. <literal>pkgs.postgresql94</literal>). Since
 upgrading your PostgreSQL version requires a database dump and reload
 (see below), NixOS cannot provide a default value for
-<option>services.postgresql.package</option> such as the most recent
+<xref linkend="opt-services.postgresql.package"/> such as the most recent
 release of PostgreSQL.</para>
 
 <!--
@@ -49,10 +49,10 @@ alice=>
 
 <para>By default, PostgreSQL stores its databases in
 <filename>/var/db/postgresql</filename>. You can override this using
-<option>services.postgresql.dataDir</option>, e.g.
+<xref linkend="opt-services.postgresql.dataDir"/>, e.g.
 
 <programlisting>
-services.postgresql.dataDir = "/data/postgresql";
+<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
 </programlisting>
 
 </para>
@@ -69,7 +69,7 @@ services.postgresql.dataDir = "/data/postgresql";
 
 <section><title>Options</title>
 
-<para>FIXME: auto-generated list of module options.</para>
+  <para>A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.</para>
 
 </section>
 

nixos/modules/services/editors/emacs.xml

@@ -404,10 +404,10 @@ in [...]
       user service for Emacs daemon, add the following to your
       <filename>configuration.nix</filename>:
 
-      <programlisting><![CDATA[
+<programlisting>
-services.emacs.enable = true;
+<xref linkend="opt-services.emacs.enable"/> = true;
-services.emacs.package = import /home/cassou/.emacs.d { pkgs = pkgs; };
+<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };
-]]></programlisting>
+</programlisting>
     </para>
 
     <para>
@@ -462,7 +462,7 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
     <!--<title><command>emacsclient</command> as the Default Editor</title>-->
 
     <para>
-      If <varname>services.emacs.defaultEditor</varname> is
+      If <xref linkend="opt-services.emacs.defaultEditor"/> is
       <literal>true</literal>, the <varname>EDITOR</varname> variable
       will be set to a wrapper script which launches
       <command>emacsclient</command>.
@@ -497,10 +497,10 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
       Emacs daemon is not wanted for all users, it is possible to
       install the service but not globally enable it:
 
-      <programlisting><![CDATA[
+<programlisting>
-services.emacs.enable = false;
+<xref linkend="opt-services.emacs.enable"/> = false;
-services.emacs.install = true;
+<xref linkend="opt-services.emacs.install"/> = true;
-]]></programlisting>
+</programlisting>
     </para>
 
     <para>
@@ -582,7 +582,7 @@ services.emacs.install = true;
     <para>
       To install the DocBook 5.0 schemas, either add
       <varname>pkgs.docbook5</varname> to
-      <varname>environment.systemPackages</varname> (<link
+      <xref linkend="opt-environment.systemPackages"/> (<link
       linkend="sec-declarative-package-mgmt">NixOS</link>), or run
       <literal>nix-env -i pkgs.docbook5</literal>
       (<link linkend="sec-ad-hoc-packages">Nix</link>).

nixos/modules/services/editors/infinoted.nix

@@ -129,7 +129,7 @@ in {
         serviceConfig = {
           Type = "simple";
           Restart = "always";
-          ExecStart = "${cfg.package}/bin/infinoted-0.6 --config-file=/var/lib/infinoted/infinoted.conf";
+          ExecStart = "${cfg.package}/bin/infinoted-${versions.majorMinor cfg.package.version} --config-file=/var/lib/infinoted/infinoted.conf";
           User = cfg.user;
           Group = cfg.group;
           PermissionsStartOnly = true;

nixos/modules/services/hardware/lcd.nix

@@ -0,0 +1,172 @@
+{ config, lib, pkgs, ... }:
+
+let
+  cfg = config.services.hardware.lcd;
+  pkg = lib.getBin pkgs.lcdproc;
+
+  serverCfg = pkgs.writeText "lcdd.conf" ''
+    [server]
+    DriverPath=${pkg}/lib/lcdproc/
+    ReportToSyslog=false
+    Bind=${cfg.serverHost}
+    Port=${toString cfg.serverPort}
+    ${cfg.server.extraConfig}
+  '';
+
+  clientCfg = pkgs.writeText "lcdproc.conf" ''
+    [lcdproc]
+    Server=${cfg.serverHost}
+    Port=${toString cfg.serverPort}
+    ReportToSyslog=false
+    ${cfg.client.extraConfig}
+  '';
+
+  serviceCfg = {
+    DynamicUser = true;
+    Restart = "on-failure";
+    Slice = "lcd.slice";
+  };
+
+in with lib; {
+
+  meta.maintainers = with maintainers; [ peterhoeg ];
+
+  options = with types; {
+    services.hardware.lcd = {
+      serverHost = mkOption {
+        type = str;
+        default = "localhost";
+        description = "Host on which LCDd is listening.";
+      };
+
+      serverPort = mkOption {
+        type = int;
+        default = 13666;
+        description = "Port on which LCDd is listening.";
+      };
+
+      server = {
+        enable = mkOption {
+          type = bool;
+          default = false;
+          description = "Enable the LCD panel server (LCDd)";
+        };
+
+        openPorts = mkOption {
+          type = bool;
+          default = false;
+          description = "Open the ports in the firewall";
+        };
+
+        usbPermissions = mkOption {
+          type = bool;
+          default = false;
+          description = ''
+            Set group-write permissions on a USB device.
+            </para>
+            <para>
+            A USB connected LCD panel will most likely require having its
+            permissions modified for lcdd to write to it. Enabling this option
+            sets group-write permissions on the device identified by
+            <option>services.hardware.lcd.usbVid</option> and
+            <option>services.hardware.lcd.usbPid</option>. In order to find the
+            values, you can run the <command>lsusb</command> command. Example
+            output:
+            </para>
+            <para>
+            <literal>
+            Bus 005 Device 002: ID 0403:c630 Future Technology Devices International, Ltd lcd2usb interface
+            </literal>
+            </para>
+            <para>
+            In this case the vendor id is 0403 and the product id is c630.
+          '';
+        };
+
+        usbVid = mkOption {
+          type = str;
+          default = "";
+          description = "The vendor ID of the USB device to claim.";
+        };
+
+        usbPid = mkOption {
+          type = str;
+          default = "";
+          description = "The product ID of the USB device to claim.";
+        };
+
+        usbGroup = mkOption {
+          type = str;
+          default = "dialout";
+          description = "The group to use for settings permissions. This group must exist or you will have to create it.";
+        };
+
+        extraConfig = mkOption {
+          type = lines;
+          default = "";
+          description = "Additional configuration added verbatim to the server config.";
+        };
+      };
+
+      client = {
+        enable = mkOption {
+          type = bool;
+          default = false;
+          description = "Enable the LCD panel client (LCDproc)";
+        };
+
+        extraConfig = mkOption {
+          type = lines;
+          default = "";
+          description = "Additional configuration added verbatim to the client config.";
+        };
+
+        restartForever = mkOption {
+          type = bool;
+          default = true;
+          description = "Try restarting the client forever.";
+        };
+      };
+    };
+  };
+
+  config = mkIf (cfg.server.enable || cfg.client.enable) {
+    networking.firewall.allowedTCPPorts = mkIf (cfg.server.enable && cfg.server.openPorts) [ cfg.serverPort ];
+
+    services.udev.extraRules = mkIf (cfg.server.enable && cfg.server.usbPermissions) ''
+      ACTION=="add", SUBSYSTEMS=="usb", ATTRS{idVendor}=="${cfg.server.usbVid}", ATTRS{idProduct}=="${cfg.server.usbPid}", MODE="660", GROUP="${cfg.server.usbGroup}"
+    '';
+
+    systemd.services = {
+      lcdd = mkIf cfg.server.enable {
+        description = "LCDproc - server";
+        wantedBy = [ "lcd.target" ];
+        serviceConfig = serviceCfg // {
+          ExecStart = "${pkg}/bin/LCDd -f -c ${serverCfg}";
+          SupplementaryGroups = cfg.server.usbGroup;
+        };
+      };
+
+      lcdproc = mkIf cfg.client.enable {
+        description = "LCDproc - client";
+        after = [ "lcdd.service" ];
+        wantedBy = [ "lcd.target" ];
+        serviceConfig = serviceCfg // {
+          ExecStart = "${pkg}/bin/lcdproc -f -c ${clientCfg}";
+          # If the server is being restarted at the same time, the client will
+          # fail as it cannot connect, so space it out a bit.
+          RestartSec = "5";
+          # Allow restarting for eternity
+          StartLimitIntervalSec = lib.mkIf cfg.client.restartForever "0";
+          StartLimitBurst = lib.mkIf cfg.client.restartForever "0";
+        };
+      };
+    };
+
+    systemd.targets.lcd = {
+      description = "LCD client/server";
+      after = [ "lcdd.service" "lcdproc.service" ];
+      wantedBy = [ "multi-user.target" ];
+    };
+  };
+}

nixos/modules/services/misc/gitlab.nix

@@ -8,9 +8,6 @@ let
   cfg = config.services.gitlab;
 
   ruby = cfg.packages.gitlab.ruby;
-  bundler = pkgs.bundler;
-
-  gemHome = "${cfg.packages.gitlab.rubyEnv}/${ruby.gemPath}";
 
   gitlabSocket = "${cfg.statePath}/tmp/sockets/gitlab.socket";
   gitalySocket = "${cfg.statePath}/tmp/sockets/gitaly.socket";
@@ -137,8 +134,6 @@ let
 
   gitlabEnv = {
     HOME = "${cfg.statePath}/home";
-    GEM_HOME = gemHome;
-    BUNDLE_GEMFILE = "${cfg.packages.gitlab}/share/gitlab/Gemfile";
     UNICORN_PATH = "${cfg.statePath}/";
     GITLAB_PATH = "${cfg.packages.gitlab}/share/gitlab/";
     GITLAB_STATE_PATH = "${cfg.statePath}";
@@ -158,19 +153,17 @@ let
 
   gitlab-rake = pkgs.stdenv.mkDerivation rec {
     name = "gitlab-rake";
-    buildInputs = [ cfg.packages.gitlab cfg.packages.gitlab.rubyEnv pkgs.makeWrapper ];
+    buildInputs = [ pkgs.makeWrapper ];
-    phases = "installPhase fixupPhase";
+    dontBuild = true;
-    buildPhase = "";
+    unpackPhase = ":";
     installPhase = ''
       mkdir -p $out/bin
-      makeWrapper ${cfg.packages.gitlab.rubyEnv}/bin/bundle $out/bin/gitlab-bundle \
+      makeWrapper ${cfg.packages.gitlab.rubyEnv}/bin/rake $out/bin/gitlab-rake \
           ${concatStrings (mapAttrsToList (name: value: "--set ${name} '${value}' ") gitlabEnv)} \
           --set GITLAB_CONFIG_PATH '${cfg.statePath}/config' \
           --set PATH '${lib.makeBinPath [ pkgs.nodejs pkgs.gzip pkgs.git pkgs.gnutar config.services.postgresql.package ]}:$PATH' \
           --set RAKEOPT '-f ${cfg.packages.gitlab}/share/gitlab/Rakefile' \
           --run 'cd ${cfg.packages.gitlab}/share/gitlab'
-      makeWrapper $out/bin/gitlab-bundle $out/bin/gitlab-rake \
-          --add-flags "exec rake"
      '';
   };
 
@@ -482,10 +475,10 @@ in {
         Type = "simple";
         User = cfg.user;
         Group = cfg.group;
-        TimeoutSec = "300";
+        TimeoutSec = "infinity";
         Restart = "on-failure";
         WorkingDirectory = "${cfg.packages.gitlab}/share/gitlab";
-        ExecStart="${cfg.packages.gitlab.rubyEnv}/bin/bundle exec \"sidekiq -C \"${cfg.packages.gitlab}/share/gitlab/config/sidekiq_queues.yml\" -e production -P ${cfg.statePath}/tmp/sidekiq.pid\"";
+        ExecStart="${cfg.packages.gitlab.rubyEnv}/bin/sidekiq -C \"${cfg.packages.gitlab}/share/gitlab/config/sidekiq_queues.yml\" -e production -P ${cfg.statePath}/tmp/sidekiq.pid";
       };
     };
 
@@ -493,11 +486,9 @@ in {
       after = [ "network.target" "gitlab.service" ];
       wantedBy = [ "multi-user.target" ];
       environment.HOME = gitlabEnv.HOME;
-      environment.GEM_HOME = "${cfg.packages.gitaly.rubyEnv}/${ruby.gemPath}";
       environment.GITLAB_SHELL_CONFIG_PATH = gitlabEnv.GITLAB_SHELL_CONFIG_PATH;
-      path = with pkgs; [ gitAndTools.git cfg.packages.gitaly.rubyEnv ruby ];
+      path = with pkgs; [ gitAndTools.git cfg.packages.gitaly.rubyEnv cfg.packages.gitaly.rubyEnv.wrappedRuby ];
       serviceConfig = {
-        #PermissionsStartOnly = true; # preStart must be run as root
         Type = "simple";
         User = cfg.user;
         Group = cfg.group;
@@ -529,7 +520,7 @@ in {
         Type = "simple";
         User = cfg.user;
         Group = cfg.group;
-        TimeoutSec = "300";
+        TimeoutSec = "infinity";
         Restart = "on-failure";
         WorkingDirectory = gitlabEnv.HOME;
         ExecStart =
@@ -658,10 +649,10 @@ in {
         Type = "simple";
         User = cfg.user;
         Group = cfg.group;
-        TimeoutSec = "300";
+        TimeoutSec = "infinity";
         Restart = "on-failure";
         WorkingDirectory = "${cfg.packages.gitlab}/share/gitlab";
-        ExecStart = "${cfg.packages.gitlab.rubyEnv}/bin/bundle exec \"unicorn -c ${cfg.statePath}/config/unicorn.rb -E production\"";
+        ExecStart = "${cfg.packages.gitlab.rubyEnv}/bin/unicorn -c ${cfg.statePath}/config/unicorn.rb -E production";
       };
 
     };

nixos/modules/services/misc/gitlab.xml

@@ -18,19 +18,18 @@ webserver to proxy HTTP requests to the socket.</para>
     frontend proxy:
 
 <programlisting>
-    services.nginx = {
+<link linkend="opt-services.nginx.enable">services.nginx</link> = {
-      enable = true;
+  <link linkend="opt-services.nginx.enable">enable</link> = true;
-      recommendedGzipSettings = true;
+  <link linkend="opt-services.nginx.recommendedGzipSettings">recommendedGzipSettings</link> = true;
-      recommendedOptimisation = true;
+  <link linkend="opt-services.nginx.recommendedOptimisation">recommendedOptimisation</link> = true;
-      recommendedProxySettings = true;
+  <link linkend="opt-services.nginx.recommendedProxySettings">recommendedProxySettings</link> = true;
-      recommendedTlsSettings = true;
+  <link linkend="opt-services.nginx.recommendedTlsSettings">recommendedTlsSettings</link> = true;
-      virtualHosts."git.example.com" = {
+  <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link>."git.example.com" = {
-        enableACME = true;
+    <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;
-        forceSSL = true;
+    <link linkend="opt-services.nginx.virtualHosts._name_.forceSSL">forceSSL</link> = true;
-        locations."/".proxyPass = "http://unix:/run/gitlab/gitlab-workhorse.socket";
+    <link linkend="opt-services.nginx.virtualHosts._name_.locations._name_.proxyPass">locations."/".proxyPass</link> = "http://unix:/run/gitlab/gitlab-workhorse.socket";
   };
-    };
+};
-'';
 </programlisting>
 </para>
 
@@ -49,24 +48,24 @@ all data like the repositories and uploads will be stored.</para>
 
 <programlisting>
 services.gitlab = {
-  enable = true;
+  <link linkend="opt-services.gitlab.enable">enable</link> = true;
-  databasePassword = "eXaMpl3";
+  <link linkend="opt-services.gitlab.databasePassword">databasePassword</link> = "eXaMpl3";
-  initialRootPassword = "UseNixOS!";
+  <link linkend="opt-services.gitlab.initialRootPassword">initialRootPassword</link> = "UseNixOS!";
-  https = true;
+  <link linkend="opt-services.gitlab.https">https</link> = true;
-  host = "git.example.com";
+  <link linkend="opt-services.gitlab.host">host</link> = "git.example.com";
-  port = 443;
+  <link linkend="opt-services.gitlab.port">port</link> = 443;
-  user = "git";
+  <link linkend="opt-services.gitlab.user">user</link> = "git";
-  group = "git";
+  <link linkend="opt-services.gitlab.group">group</link> = "git";
   smtp = {
-    enable = true;
+    <link linkend="opt-services.gitlab.smtp.enable">enable</link> = true;
-    address = "localhost";
+    <link linkend="opt-services.gitlab.smtp.address">address</link> = "localhost";
-    port = 25;
+    <link linkend="opt-services.gitlab.smtp.port">port</link> = 25;
   };
   secrets = {
-    db = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
+    <link linkend="opt-services.gitlab.secrets.db">db</link> = "uPgq1gtwwHiatiuE0YHqbGa5lEIXH7fMsvuTNgdzJi8P0Dg12gibTzBQbq5LT7PNzcc3BP9P1snHVnduqtGF43PgrQtU7XL93ts6gqe9CBNhjtaqUwutQUDkygP5NrV6";
-    secret = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
+    <link linkend="opt-services.gitlab.secrets.secret">secret</link> = "devzJ0Tz0POiDBlrpWmcsjjrLaltyiAdS8TtgT9YNBOoUcDsfppiY3IXZjMVtKgXrFImIennFGOpPN8IkP8ATXpRgDD5rxVnKuTTwYQaci2NtaV1XxOQGjdIE50VGsR3";
-    otp = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
+    <link linkend="opt-services.gitlab.secrets.otp">otp</link> = "e1GATJVuS2sUh7jxiPzZPre4qtzGGaS22FR50Xs1TerRVdgI3CBVUi5XYtQ38W4xFeS4mDqi5cQjExE838iViSzCdcG19XSL6qNsfokQP9JugwiftmhmCadtsnHErBMI";
-    jws = ''
+    <link linkend="opt-services.gitlab.secrets.jws">jws</link> = ''
       -----BEGIN RSA PRIVATE KEY-----
       MIIEpAIBAAKCAQEArrtx4oHKwXoqUbMNqnHgAklnnuDon3XG5LJB35yPsXKv/8GK
       ke92wkI+s1Xkvsp8tg9BIY/7c6YK4SR07EWL+dB5qwctsWR2Q8z+/BKmTx9D99pm
@@ -96,7 +95,7 @@ services.gitlab = {
       -----END RSA PRIVATE KEY-----
     '';
   };
-  extraConfig = {
+  <link linkend="opt-services.gitlab.extraConfig">extraConfig</link> = {
     gitlab = {
       email_from = "gitlab-no-reply@example.com";
       email_display_name = "Example GitLab";
@@ -116,7 +115,7 @@ secret from <literal>config/secrets.yml</literal> located in your Gitlab state
 folder.</para>
 
 <para>Refer to <xref linkend="ch-options" /> for all available configuration
-options for the <literal>services.gitlab</literal> module.</para>
+options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.</para>
 
 </section>
 

nixos/modules/services/misc/home-assistant.nix

@@ -5,7 +5,10 @@ with lib;
 let
   cfg = config.services.home-assistant;
 
-  configFile = pkgs.writeText "configuration.yaml" (builtins.toJSON cfg.config);
+  # cfg.config != null can be assumed here
+  configFile = pkgs.writeText "configuration.json"
+    (builtins.toJSON (if cfg.applyDefaultConfig then
+    (lib.recursiveUpdate defaultConfig cfg.config) else cfg.config));
 
   availableComponents = pkgs.home-assistant.availableComponents;
 
@@ -38,6 +41,12 @@ let
     then (cfg.package.override { inherit extraComponents; })
     else cfg.package;
 
+  # If you are changing this, please update the description in applyDefaultConfig
+  defaultConfig = {
+    homeassistant.time_zone = config.time.timeZone;
+    http.server_port = (toString cfg.port);
+  };
+
 in {
   meta.maintainers = with maintainers; [ dotlambda ];
 
@@ -50,6 +59,26 @@ in {
       description = "The config directory, where your <filename>configuration.yaml</filename> is located.";
     };
 
+    port = mkOption {
+      default = 8123;
+      type = types.int;
+      description = "The port on which to listen.";
+    };
+
+    applyDefaultConfig = mkOption {
+      default = true;
+      type = types.bool;
+      description = ''
+        Setting this option enables a few configuration options for HA based on NixOS configuration (such as time zone) to avoid having to manually specify configuration we already have.
+        </para>
+        <para>
+        Currently one side effect of enabling this is that the <literal>http</literal> component will be enabled.
+        </para>
+        <para>
+        This only takes effect if <literal>config != null</literal> in order to ensure that a manually managed <filename>configuration.yaml</filename> is not overwritten.
+      '';
+    };
+
     config = mkOption {
       default = null;
       type = with types; nullOr attrs;
@@ -106,19 +135,20 @@ in {
       description = "Home Assistant";
       after = [ "network.target" ];
       preStart = lib.optionalString (cfg.config != null) ''
-        rm -f ${cfg.configDir}/configuration.yaml
+        config=${cfg.configDir}/configuration.yaml
-        ln -s ${configFile} ${cfg.configDir}/configuration.yaml
+        rm -f $config
+        ${pkgs.remarshal}/bin/json2yaml -i ${configFile} -o $config
+        chmod 444 $config
       '';
       serviceConfig = {
-        ExecStart = ''
+        ExecStart = "${package}/bin/hass --config '${cfg.configDir}'";
-          ${package}/bin/hass --config "${cfg.configDir}"
-        '';
         User = "hass";
         Group = "hass";
         Restart = "on-failure";
         ProtectSystem = "strict";
         ReadWritePaths = "${cfg.configDir}";
         PrivateTmp = true;
+        RemoveIPC = true;
       };
       path = [
         "/run/wrappers" # needed for ping

nixos/modules/services/misc/logkeys.nix

@@ -7,6 +7,13 @@ let
 in {
   options.services.logkeys = {
     enable = mkEnableOption "logkeys service";
+
+    device = mkOption {
+      description = "Use the given device as keyboard input event device instead of /dev/input/eventX default.";
+      default = null;
+      type = types.nullOr types.string;
+      example = "/dev/input/event15";
+    };
   };
 
   config = mkIf cfg.enable {
@@ -14,7 +21,7 @@ in {
       description = "LogKeys Keylogger Daemon";
       wantedBy = [ "multi-user.target" ];
       serviceConfig = {
-        ExecStart = "${pkgs.logkeys}/bin/logkeys -s";
+        ExecStart = "${pkgs.logkeys}/bin/logkeys -s${lib.optionalString (cfg.device != null) " -d ${cfg.device}"}";
         ExecStop = "${pkgs.logkeys}/bin/logkeys -k";
         Type = "forking";
       };

nixos/modules/services/misc/nix-daemon.nix

@@ -342,7 +342,9 @@ in
       nixPath = mkOption {
         type = types.listOf types.str;
         default =
-          [ "nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs"
+          [
+            "$HOME/.nix-defexpr/channels"
+            "nixpkgs=/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs"
             "nixos-config=/etc/nixos/configuration.nix"
             "/nix/var/nix/profiles/per-user/root/channels"
           ];

nixos/modules/services/misc/taskserver/doc.xml

@@ -55,7 +55,7 @@
       Because Taskserver by default only provides scripts to setup users
       imperatively, the <command>nixos-taskserver</command> tool is used for
       addition and deletion of organisations along with users and groups defined
-      by <option>services.taskserver.organisations</option> and as well for
+      by <xref linkend="opt-services.taskserver.organisations"/> and as well for
       imperative set up.
     </para>
 
@@ -99,10 +99,10 @@
       For example, let's say you have the following configuration:
 <screen>
 {
-  services.taskserver.enable = true;
+  <xref linkend="opt-services.taskserver.enable"/> = true;
-  services.taskserver.fqdn = "server";
+  <xref linkend="opt-services.taskserver.fqdn"/> = "server";
-  services.taskserver.listenHost = "::";
+  <xref linkend="opt-services.taskserver.listenHost"/> = "::";
-  services.taskserver.organisations.my-company.users = [ "alice" ];
+  <link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
 }
 </screen>
       This creates an organisation called <literal>my-company</literal> with the
@@ -136,7 +136,7 @@ $ ssh server nixos-taskserver user export my-company alice | sh
 
     <para>
       If you set any options within
-      <option>service.taskserver.pki.manual.*</option>,
+      <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
       <command>nixos-taskserver</command> won't issue certificates, but you can
       still use it for adding or removing user accounts.
     </para>

nixos/modules/services/monitoring/prometheus/exporters/nginx.nix

@@ -9,21 +9,37 @@ in
   port = 9113;
   extraOpts = {
     scrapeUri = mkOption {
-      type = types.string;
+      type = types.str;
       default = "http://localhost/nginx_status";
       description = ''
         Address to access the nginx status page.
         Can be enabled with services.nginx.statusPage = true.
       '';
     };
+    telemetryEndpoint = mkOption {
+      type = types.str;
+      default = "/metrics";
+      description = ''
+        Path under which to expose metrics.
+      '';
+    };
+    insecure = mkOption {
+      type = types.bool;
+      default = true;
+      description = ''
+        Ignore server certificate if using https.
+      '';
+    };
   };
   serviceOpts = {
     serviceConfig = {
       DynamicUser = true;
       ExecStart = ''
         ${pkgs.prometheus-nginx-exporter}/bin/nginx_exporter \
-          -nginx.scrape_uri '${cfg.scrapeUri}' \
+          --nginx.scrape_uri '${cfg.scrapeUri}' \
-          -telemetry.address ${cfg.listenAddress}:${toString cfg.port} \
+          --telemetry.address ${cfg.listenAddress}:${toString cfg.port} \
+          --telemetry.endpoint ${cfg.telemetryEndpoint} \
+          --insecure ${cfg.insecure} \
           ${concatStringsSep " \\\n  " cfg.extraFlags}
       '';
     };

nixos/modules/services/monitoring/prometheus/exporters/varnish.nix

@@ -7,14 +7,80 @@ let
 in
 {
   port = 9131;
+  extraOpts = {
+    noExit = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Do not exit server on Varnish scrape errors.
+      '';
+    };
+    withGoMetrics = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Export go runtime and http handler metrics.
+      '';
+    };
+    verbose = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable verbose logging.
+      '';
+    };
+    raw = mkOption {
+      type = types.bool;
+      default = false;
+      description = ''
+        Enable raw stdout logging without timestamps.
+      '';
+    };
+    varnishStatPath = mkOption {
+      type = types.str;
+      default = "varnishstat";
+      description = ''
+        Path to varnishstat.
+      '';
+    };
+    instance = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        varnishstat -n value.
+      '';
+    };
+    healthPath = mkOption {
+      type = types.nullOr types.str;
+      default = null;
+      description = ''
+        Path under which to expose healthcheck. Disabled unless configured.
+      '';
+    };
+    telemetryPath = mkOption {
+      type = types.str;
+      default = "/metrics";
+      description = ''
+        Path under which to expose metrics.
+      '';
+    };
+  };
   serviceOpts = {
     path = [ pkgs.varnish ];
     serviceConfig = {
       DynamicUser = true;
       ExecStart = ''
         ${pkgs.prometheus-varnish-exporter}/bin/prometheus_varnish_exporter \
-          -web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
+          --web.listen-address ${cfg.listenAddress}:${toString cfg.port} \
-          ${concatStringsSep " \\\n  " cfg.extraFlags}
+          --web.telemetry-path ${cfg.telemetryPath} \
+          --varnishstat-path ${cfg.varnishStatPath} \
+          ${concatStringsSep " \\\n  " (cfg.extraFlags
+            ++ optional (cfg.healthPath != null) "--web.health-path ${cfg.healthPath}"
+            ++ optional (cfg.instance != null) "-n ${cfg.instance}"
+            ++ optional cfg.noExit "--no-exit"
+            ++ optional cfg.withGoMetrics "--with-go-metrics"
+            ++ optional cfg.verbose "--verbose"
+            ++ optional cfg.raw "--raw")}
       '';
     };
   };

nixos/modules/services/networking/dante.nix

@@ -6,6 +6,7 @@ let
   confFile = pkgs.writeText "dante-sockd.conf" ''
     user.privileged: root
     user.unprivileged: dante
+    logoutput: syslog
 
     ${cfg.config}
   '';
@@ -21,11 +22,10 @@ in
       enable = mkEnableOption "Dante SOCKS proxy";
 
       config = mkOption {
-        default     = null;
+        type        = types.lines;
-        type        = types.nullOr types.str;
         description = ''
-          Contents of Dante's configuration file
+          Contents of Dante's configuration file.
-          NOTE: user.privileged/user.unprivileged are set by the service
+          NOTE: user.privileged, user.unprivileged and logoutput are set by the service.
         '';
       };
     };
@@ -33,7 +33,7 @@ in
 
   config = mkIf cfg.enable {
     assertions = [
-      { assertion   = cfg.config != null;
+      { assertion   = cfg.config != "";
         message     = "please provide Dante configuration file contents";
       }
     ];
@@ -54,7 +54,8 @@ in
         Type        = "simple";
         ExecStart   = "${pkgs.dante}/bin/sockd -f ${confFile}";
         ExecReload  = "${pkgs.coreutils}/bin/kill -HUP $MAINPID";
-        Restart     = "always";
+        # Can crash sometimes; see https://github.com/NixOS/nixpkgs/pull/39005#issuecomment-381828708
+        Restart     = "on-failure";
       };
     };
   };

nixos/modules/services/networking/dnscrypt-proxy.xml

@@ -19,7 +19,7 @@
   <para>
     To enable the client proxy, set
     <programlisting>
-      services.dnscrypt-proxy.enable = true;
+<xref linkend="opt-services.dnscrypt-proxy.enable"/> = true;
     </programlisting>
   </para>
 
@@ -38,17 +38,17 @@
     DNS client, change the default proxy listening port to a
     non-standard value and point the other client to it:
     <programlisting>
-      services.dnscrypt-proxy.localPort = 43;
+<xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43;
     </programlisting>
   </para>
 
   <sect2><title>dnsmasq</title>
   <para>
     <programlisting>
-      {
+{
-        services.dnsmasq.enable = true;
+  <xref linkend="opt-services.dnsmasq.enable"/> = true;
-        services.dnsmasq.servers = [ "127.0.0.1#43" ];
+  <xref linkend="opt-services.dnsmasq.servers"/> = [ "127.0.0.1#43" ];
-      }
+}
     </programlisting>
   </para>
   </sect2>
@@ -56,10 +56,10 @@
   <sect2><title>unbound</title>
   <para>
     <programlisting>
-      {
+{
-        services.unbound.enable = true;
+  <xref linkend="opt-services.unbound.enable"/> = true;
-        services.unbound.forwardAddresses = [ "127.0.0.1@43" ];
+  <xref linkend="opt-services.unbound.forwardAddresses"/> = [ "127.0.0.1@43" ];
-      }
+}
     </programlisting>
   </para>
   </sect2>

nixos/modules/services/networking/unifi.nix

@@ -4,22 +4,22 @@ let
   cfg = config.services.unifi;
   stateDir = "/var/lib/unifi";
   cmd = ''
-    @${pkgs.jre}/bin/java java \
+    @${cfg.jrePackage}/bin/java java \
         ${optionalString (cfg.initialJavaHeapSize != null) "-Xms${(toString cfg.initialJavaHeapSize)}m"} \
         ${optionalString (cfg.maximumJavaHeapSize != null) "-Xmx${(toString cfg.maximumJavaHeapSize)}m"} \
         -jar ${stateDir}/lib/ace.jar
   '';
   mountPoints = [
     {
-      what = "${pkgs.unifi}/dl";
+      what = "${cfg.unifiPackage}/dl";
       where = "${stateDir}/dl";
     }
     {
-      what = "${pkgs.unifi}/lib";
+      what = "${cfg.unifiPackage}/lib";
       where = "${stateDir}/lib";
     }
     {
-      what = "${pkgs.mongodb}/bin";
+      what = "${cfg.mongodbPackage}/bin";
       where = "${stateDir}/bin";
     }
     {
@@ -41,6 +41,33 @@ in
       '';
     };
 
+    services.unifi.jrePackage = mkOption {
+      type = types.package;
+      default = pkgs.jre8;
+      defaultText = "pkgs.jre8";
+      description = ''
+        The JRE package to use. Check the release notes to ensure it is supported.
+      '';
+    };
+
+    services.unifi.unifiPackage = mkOption {
+      type = types.package;
+      default = pkgs.unifiLTS;
+      defaultText = "pkgs.unifiLTS";
+      description = ''
+        The unifi package to use.
+      '';
+    };
+
+    services.unifi.mongodbPackage = mkOption {
+      type = types.package;
+      default = pkgs.mongodb;
+      defaultText = "pkgs.mongodb";
+      description = ''
+        The mongodb package to use.
+      '';
+    };
+
     services.unifi.dataDir = mkOption {
       type = types.str;
       default = "${stateDir}/data";
@@ -137,7 +164,7 @@ in
         rm -rf "${stateDir}/webapps"
         mkdir -p "${stateDir}/webapps"
         chown unifi "${stateDir}/webapps"
-        ln -s "${pkgs.unifi}/webapps/ROOT" "${stateDir}/webapps/ROOT"
+        ln -s "${cfg.unifiPackage}/webapps/ROOT" "${stateDir}/webapps/ROOT"
       '';
 
       postStop = ''

nixos/modules/services/printing/cupsd.nix

@@ -83,6 +83,8 @@ let
 
     WebInterface ${if cfg.webInterface then "Yes" else "No"}
 
+    LogLevel ${cfg.logLevel}
+
     ${cfg.extraConf}
   '';
 
@@ -165,6 +167,15 @@ in
         '';
       };
 
+      logLevel = mkOption {
+        type = types.str;
+        default = "info";
+        example = "debug";
+        description = ''
+          Specifies the cupsd logging verbosity.
+        '';
+      };
+
       extraFilesConf = mkOption {
         type = types.lines;
         default = "";
@@ -180,7 +191,7 @@ in
         example =
           ''
             BrowsePoll cups.example.com
-            LogLevel debug
+            MaxCopies 42
           '';
         description = ''
           Extra contents of the configuration file of the CUPS daemon
@@ -345,8 +356,6 @@ in
 
     services.printing.extraConf =
       ''
-        LogLevel info
-
         DefaultAuthType Basic
 
         <Location />

nixos/modules/services/security/oauth2_proxy.nix

@@ -6,70 +6,81 @@ with lib;
 let
   cfg = config.services.oauth2_proxy;
 
-  # Use like:
-  #   repeatedArgs (arg: "--arg=${arg}") args
-  repeatedArgs = concatMapStringsSep " ";
-
   # oauth2_proxy provides many options that are only relevant if you are using
   # a certain provider. This set maps from provider name to a function that
   # takes the configuration and returns a string that can be inserted into the
   # command-line to launch oauth2_proxy.
   providerSpecificOptions = {
-    azure = cfg: ''
+    azure = cfg: {
-      --azure-tenant=${cfg.azure.tenant} \
+      azure.tenant = cfg.azure.tenant;
-      --resource=${cfg.azure.resource} \
+      resource = cfg.azure.resource;
-    '';
+    };
 
-    github = cfg: ''
+    github = cfg: { github = {
-      ${optionalString (!isNull cfg.github.org) "--github-org=${cfg.github.org}"} \
+      inherit (cfg.github) org team;
-      ${optionalString (!isNull cfg.github.team) "--github-org=${cfg.github.team}"} \
+    }; };
-    '';
 
-    google = cfg: ''
+    google = cfg: { google = with cfg.google; optionalAttrs (groups != []) {
-      --google-admin-email=${cfg.google.adminEmail} \
+      admin-email = adminEmail;
-      --google-service-account=${cfg.google.serviceAccountJSON} \
+      service-account = serviceAccountJSON;
-      ${repeatedArgs (group: "--google-group=${group}") cfg.google.groups} \
+      group = groups;
-    '';
+    }; };
   };
 
   authenticatedEmailsFile = pkgs.writeText "authenticated-emails" cfg.email.addresses;
 
-  getProviderOptions = cfg: provider: providerSpecificOptions.${provider} or (_: "") cfg;
+  getProviderOptions = cfg: provider: providerSpecificOptions.${provider} or (_: {}) cfg;
 
-  mkCommandLine = cfg: ''
+  allConfig = with cfg; {
-    --provider='${cfg.provider}' \
+    inherit (cfg) provider scope upstream;
-    ${optionalString (!isNull cfg.email.addresses) "--authenticated-emails-file='${authenticatedEmailsFile}'"} \
+    approval-prompt = approvalPrompt;
-    --approval-prompt='${cfg.approvalPrompt}' \
+    basic-auth-password = basicAuthPassword;
-    ${optionalString (cfg.passBasicAuth && !isNull cfg.basicAuthPassword) "--basic-auth-password='${cfg.basicAuthPassword}'"} \
+    client-id = clientID;
-    --client-id='${cfg.clientID}' \
+    client-secret = clientSecret;
-    --client-secret='${cfg.clientSecret}' \
+    custom-templates-dir = customTemplatesDir;
-    ${optionalString (!isNull cfg.cookie.domain) "--cookie-domain='${cfg.cookie.domain}'"} \
+    email-domain = email.domains;
-    --cookie-expire='${cfg.cookie.expire}' \
+    http-address = httpAddress;
-    --cookie-httponly=${boolToString cfg.cookie.httpOnly} \
+    login-url = loginURL;
-    --cookie-name='${cfg.cookie.name}' \
+    pass-access-token = passAccessToken;
-    --cookie-secret='${cfg.cookie.secret}' \
+    pass-basic-auth = passBasicAuth;
-    --cookie-secure=${boolToString cfg.cookie.secure} \
+    pass-host-header = passHostHeader;
-    ${optionalString (!isNull cfg.cookie.refresh) "--cookie-refresh='${cfg.cookie.refresh}'"} \
+    proxy-prefix = proxyPrefix;
-    ${optionalString (!isNull cfg.customTemplatesDir) "--custom-templates-dir='${cfg.customTemplatesDir}'"} \
+    profile-url = profileURL;
-    ${repeatedArgs (x: "--email-domain='${x}'") cfg.email.domains} \
+    redeem-url = redeemURL;
-    --http-address='${cfg.httpAddress}' \
+    redirect-url = redirectURL;
-    ${optionalString (!isNull cfg.htpasswd.file) "--htpasswd-file='${cfg.htpasswd.file}' --display-htpasswd-form=${boolToString cfg.htpasswd.displayForm}"} \
+    request-logging = requestLogging;
-    ${optionalString (!isNull cfg.loginURL) "--login-url='${cfg.loginURL}'"} \
+    skip-auth-regex = skipAuthRegexes;
-    --pass-access-token=${boolToString cfg.passAccessToken} \
+    signature-key = signatureKey;
-    --pass-basic-auth=${boolToString cfg.passBasicAuth} \
+    validate-url = validateURL;
-    --pass-host-header=${boolToString cfg.passHostHeader} \
+    htpasswd-file = htpasswd.file;
-    --proxy-prefix='${cfg.proxyPrefix}' \
+    cookie = {
-    ${optionalString (!isNull cfg.profileURL) "--profile-url='${cfg.profileURL}'"} \
+      inherit (cookie) domain secure expire name secret refresh;
-    ${optionalString (!isNull cfg.redeemURL) "--redeem-url='${cfg.redeemURL}'"} \
+      httponly = cookie.httpOnly;
-    ${optionalString (!isNull cfg.redirectURL) "--redirect-url='${cfg.redirectURL}'"} \
+    };
-    --request-logging=${boolToString cfg.requestLogging} \
+    set-xauthrequest = setXauthrequest;
-    ${optionalString (!isNull cfg.scope) "--scope='${cfg.scope}'"} \
+  } // lib.optionalAttrs (!isNull cfg.email.addresses) {
-    ${repeatedArgs (x: "--skip-auth-regex='${x}'") cfg.skipAuthRegexes} \
+    authenticated-emails-file = authenticatedEmailsFile;
-    ${optionalString (!isNull cfg.signatureKey) "--signature-key='${cfg.signatureKey}'"} \
+  } // lib.optionalAttrs (cfg.passBasicAuth) {
-    --upstream='${cfg.upstream}' \
+    basic-auth-password = cfg.basicAuthPassword;
-    ${optionalString (!isNull cfg.validateURL) "--validate-url='${cfg.validateURL}'"} \
+  } // lib.optionalAttrs (!isNull cfg.htpasswd.file) {
-    ${optionalString cfg.tls.enable "--tls-cert='${cfg.tls.certificate}' --tls-key='${cfg.tls.key}' --https-address='${cfg.tls.httpsAddress}'"} \
+    display-htpasswd-file = cfg.htpasswd.displayForm;
-  '' + getProviderOptions cfg cfg.provider;
+  } // lib.optionalAttrs tls.enable {
+    tls-cert = tls.certificate;
+    tls-key = tls.key;
+    https-address = tls.httpsAddress;
+  } // (getProviderOptions cfg cfg.provider) // cfg.extraConfig;
+
+  mapConfig = key: attr:
+  if (!isNull attr && attr != []) then (
+    if (builtins.typeOf attr) == "set" then concatStringsSep " "
+      (mapAttrsToList (name: value: mapConfig (key + "-" + name) value) attr) else
+    if (builtins.typeOf attr) == "list" then concatMapStringsSep " " (mapConfig key) attr else
+    if (builtins.typeOf attr) == "bool" then "--${key}=${boolToString attr}" else
+    if (builtins.typeOf attr) == "string" then "--${key}='${attr}'" else
+    "--${key}=${toString attr}")
+    else "";
+
+  configString = concatStringsSep " " (mapAttrsToList mapConfig allConfig);
 in
 {
   options.services.oauth2_proxy = {
@@ -110,7 +121,7 @@ in
     };
 
     clientID = mkOption {
-      type = types.str;
+      type = types.nullOr types.str;
       description = ''
         The OAuth Client ID.
       '';
@@ -118,7 +129,7 @@ in
     };
 
     clientSecret = mkOption {
-      type = types.str;
+      type = types.nullOr types.str;
       description = ''
         The OAuth Client Secret.
       '';
@@ -272,7 +283,8 @@ in
     ####################################################
     # UPSTREAM Configuration
     upstream = mkOption {
-      type = types.commas;
+      type = with types; coercedTo string (x: [x]) (listOf string);
+      default = [];
       description = ''
         The http url(s) of the upstream endpoint or <literal>file://</literal>
         paths for static files. Routing is based on the path.
@@ -365,7 +377,7 @@ in
       };
 
       secret = mkOption {
-        type = types.str;
+        type = types.nullOr types.str;
         description = ''
           The seed string for secure cookies.
         '';
@@ -494,10 +506,43 @@ in
       '';
     };
 
+    setXauthrequest = mkOption {
+      type = types.nullOr types.bool;
+      default = false;
+      description = ''
+        Set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode). Setting this to 'null' means using the upstream default (false).
+      '';
+    };
+
+    extraConfig = mkOption {
+      default = {};
+      description = ''
+        Extra config to pass to oauth2_proxy.
+      '';
+    };
+
+    keyFile = mkOption {
+      type = types.nullOr types.string;
+      default = null;
+      description = ''
+        oauth2_proxy allows passing sensitive configuration via environment variables.
+        Make a file that contains lines like
+        OAUTH2_PROXY_CLIENT_SECRET=asdfasdfasdf.apps.googleuserscontent.com
+        and specify the path here.
+      '';
+      example = "/run/keys/oauth2_proxy";
+    };
+
   };
 
   config = mkIf cfg.enable {
 
+    services.oauth2_proxy = mkIf (!isNull cfg.keyFile) {
+      clientID = mkDefault null;
+      clientSecret = mkDefault null;
+      cookie.secret = mkDefault null;
+    };
+
     users.extraUsers.oauth2_proxy = {
       description = "OAuth2 Proxy";
     };
@@ -511,7 +556,8 @@ in
       serviceConfig = {
         User = "oauth2_proxy";
         Restart = "always";
-        ExecStart = "${cfg.package.bin}/bin/oauth2_proxy ${mkCommandLine cfg}";
+        ExecStart = "${cfg.package.bin}/bin/oauth2_proxy ${configString}";
+        EnvironmentFile = mkIf (cfg.keyFile != null) cfg.keyFile;
       };
     };
 

nixos/modules/services/torrent/deluge.nix

@@ -11,10 +11,7 @@ in {
   options = {
     services = {
       deluge = {
-        enable = mkOption {
+        enable = mkEnableOption "Deluge daemon";
-          default = false;
-          description = "Start the Deluge daemon";
-        };
 
         openFilesLimit = mkOption {
           default = openFilesLimit;
@@ -25,14 +22,7 @@ in {
         };
       };
 
-      deluge.web = {
+      deluge.web.enable = mkEnableOption "Deluge Web daemon";
-        enable = mkOption {
-          default = false;
-          description = ''
-            Start Deluge Web daemon.
-          '';
-        };
-      };
     };
   };
 

nixos/modules/services/web-apps/youtrack.nix

@@ -0,0 +1,177 @@
+{ config, lib, pkgs, options, ... }:
+
+with lib;
+
+let
+  cfg = config.services.youtrack;
+
+  extraAttr = concatStringsSep " " (mapAttrsToList (k: v: "-D${k}=${v}") (stdParams // cfg.extraParams));
+  mergeAttrList = lib.foldl' lib.mergeAttrs {};
+
+  stdParams = mergeAttrList [
+    (optionalAttrs (cfg.baseUrl != null) {
+      "jetbrains.youtrack.baseUrl" = cfg.baseUrl;
+    })
+    {
+    "java.aws.headless" = "true";
+    "jetbrains.youtrack.disableBrowser" = "true";
+    }
+  ];
+in
+{
+  options.services.youtrack = {
+
+    enable = mkEnableOption "YouTrack service";
+
+    address = mkOption {
+      description = ''
+        The interface youtrack will listen on.
+      '';
+      default = "127.0.0.1";
+      type = types.string;
+    };
+
+    baseUrl = mkOption {
+      description = ''
+        Base URL for youtrack. Will be auto-detected and stored in database.
+      '';
+      type = types.nullOr types.string;
+      default = null;
+    };
+
+    extraParams = mkOption {
+      default = {};
+      description = ''
+        Extra parameters to pass to youtrack. See 
+        https://www.jetbrains.com/help/youtrack/standalone/YouTrack-Java-Start-Parameters.html
+        for more information.
+      '';
+      example = {
+        "jetbrains.youtrack.overrideRootPassword" = "tortuga";
+      };
+      type = types.attrsOf types.string;
+    };
+
+    package = mkOption {
+      description = ''
+        Package to use.
+      '';
+      type = types.package;
+      default = pkgs.youtrack;
+      defaultText = "pkgs.youtrack";
+    };
+
+    port = mkOption {
+      description = ''
+        The port youtrack will listen on.
+      '';
+      default = 8080;
+      type = types.int;
+    };
+
+    statePath = mkOption {
+      description = ''
+        Where to keep the youtrack database.
+      '';
+      type = types.string;
+      default = "/var/lib/youtrack";
+    };
+
+    virtualHost = mkOption {
+      description = ''
+        Name of the nginx virtual host to use and setup.
+        If null, do not setup anything.
+      '';
+      default = null;
+      type = types.nullOr types.string;
+    };
+
+    jvmOpts = mkOption {
+      description = ''
+        Extra options to pass to the JVM.
+        See https://www.jetbrains.com/help/youtrack/standalone/Configure-JVM-Options.html
+        for more information.
+      '';
+      type = types.string;
+      example = "-XX:MetaspaceSize=250m";
+      default = "";
+    };
+
+    maxMemory = mkOption {
+      description = ''
+        Maximum Java heap size
+      '';
+      type = types.string;
+      default = "1g";
+    };
+
+    maxMetaspaceSize = mkOption {
+      description = ''
+        Maximum java Metaspace memory.
+      '';
+      type = types.string;
+      default = "350m";
+    };
+  };
+
+  config = mkIf cfg.enable {
+
+    systemd.services.youtrack = {
+      environment.HOME = cfg.statePath;
+      environment.YOUTRACK_JVM_OPTS = "-Xmx${cfg.maxMemory} -XX:MaxMetaspaceSize=${cfg.maxMetaspaceSize} ${cfg.jvmOpts} ${extraAttr}";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        Type = "simple";
+        User = "youtrack";
+        Group = "youtrack";
+        ExecStart = ''${cfg.package}/bin/youtrack ${cfg.address}:${toString cfg.port}'';
+      };
+    };
+
+    users.users.youtrack = {
+      description = "Youtrack service user";
+      isSystemUser = true;
+      home = cfg.statePath;
+      createHome = true;
+      group = "youtrack";
+    };
+
+    users.groups.youtrack = {};
+
+    services.nginx = mkIf (cfg.virtualHost != null) {
+      upstreams.youtrack.servers."${cfg.address}:${toString cfg.port}" = {};
+      virtualHosts.${cfg.virtualHost}.locations = {
+        "/" = {
+          proxyPass = "http://youtrack";
+          extraConfig = ''
+            client_max_body_size 10m;
+            proxy_http_version 1.1;
+            proxy_set_header X-Forwarded-Host $http_host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+          '';
+        };
+
+        "/api/eventSourceBus" = {
+          proxyPass = "http://youtrack";
+          extraConfig = ''
+            proxy_cache off;
+            proxy_buffering off;
+            proxy_read_timeout 86400s;
+            proxy_send_timeout 86400s;
+            proxy_set_header Connection "";
+            chunked_transfer_encoding off;
+            client_max_body_size 10m;
+            proxy_http_version 1.1;
+            proxy_set_header X-Forwarded-Host $http_host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+          '';
+        };
+
+      };
+    };
+
+  };
+}

nixos/modules/services/web-servers/caddy.nix

@@ -25,8 +25,8 @@ in {
     };
 
     ca = mkOption {
-      default = "https://acme-v01.api.letsencrypt.org/directory";
+      default = "https://acme-v02.api.letsencrypt.org/directory";
-      example = "https://acme-staging.api.letsencrypt.org/directory";
+      example = "https://acme-staging-v02.api.letsencrypt.org/directory";
       type = types.string;
       description = "Certificate authority ACME server. The default (Let's Encrypt production server) should be fine for most people.";
     };

nixos/modules/services/web-servers/hitch/default.nix

@@ -0,0 +1,108 @@
+{ config, lib, pkgs, ...}:
+let
+  cfg = config.services.hitch;
+  ocspDir = lib.optionalString cfg.ocsp-stapling.enabled "/var/cache/hitch/ocsp";
+  hitchConfig = with lib; pkgs.writeText "hitch.conf" (concatStringsSep "\n" [
+    ("backend = \"${cfg.backend}\"")
+    (concatMapStrings (s: "frontend = \"${s}\"\n") cfg.frontend)
+    (concatMapStrings (s: "pem-file = \"${s}\"\n") cfg.pem-files)
+    ("ciphers = \"${cfg.ciphers}\"")
+    ("ocsp-dir = \"${ocspDir}\"")
+    "user = \"${cfg.user}\""
+    "group = \"${cfg.group}\""
+    cfg.extraConfig
+  ]);
+in
+with lib;
+{
+  options = {
+    services.hitch = {
+      enable = mkEnableOption "Hitch Server";
+
+      backend = mkOption {
+        type = types.str;
+        description = ''
+          The host and port Hitch connects to when receiving
+          a connection in the form [HOST]:PORT
+        '';
+      };
+
+      ciphers = mkOption {
+        type = types.str;
+        default = "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
+        description = "The list of ciphers to use";
+      };
+
+      frontend = mkOption {
+        type = types.either types.str (types.listOf types.str);
+        default = "[127.0.0.1]:443";
+        description = ''
+          The port and interface of the listen endpoint in the
++         form [HOST]:PORT[+CERT].
+        '';
+        apply = toList;
+      };
+
+      pem-files = mkOption {
+        type = types.listOf types.path;
+        default = [];
+        description = "PEM files to use";
+      };
+
+      ocsp-stapling = {
+        enabled = mkOption {
+          type = types.bool;
+          default = true;
+          description = "Whether to enable OCSP Stapling";
+        };
+      };
+
+      user = mkOption {
+        type = types.str;
+        default = "hitch";
+        description = "The user to run as";
+      };
+
+      group = mkOption {
+        type = types.str;
+        default = "hitch";
+        description = "The group to run as";
+      };
+
+      extraConfig = mkOption {
+        type = types.lines;
+        default = "";
+        description = "Additional configuration lines";
+      };
+    };
+
+  };
+
+  config = mkIf cfg.enable {
+
+    systemd.services.hitch = {
+      description = "Hitch";
+      wantedBy = [ "multi-user.target" ];
+      after = [ "network.target" ];
+      preStart = ''
+        ${pkgs.hitch}/sbin/hitch -t --config ${hitchConfig}
+      '' + (optionalString cfg.ocsp-stapling.enabled ''
+        mkdir -p ${ocspDir}
+        chown -R hitch:hitch ${ocspDir}
+      '');
+      serviceConfig = {
+        Type = "forking";
+        ExecStart = "${pkgs.hitch}/sbin/hitch --daemon --config ${hitchConfig}";
+        ExecReload = "${pkgs.coreutils}/bin/kill -HUP $MAINPID";
+        Restart = "always";
+        RestartSec = "5s";
+        LimitNOFILE = 131072;
+      };
+    };
+
+    environment.systemPackages = [ pkgs.hitch ];
+
+    users.extraUsers.hitch.group = "hitch";
+    users.extraGroups.hitch = {};
+  };
+}

nixos/modules/services/web-servers/nginx/default.nix

@@ -218,7 +218,10 @@ let
             ssl_certificate_key ${vhost.sslCertificateKey};
           ''}
 
-          ${optionalString (vhost.basicAuth != {}) (mkBasicAuth vhostName vhost.basicAuth)}
+          ${optionalString (vhost.basicAuthFile != null || vhost.basicAuth != {}) ''
+            auth_basic secured;
+            auth_basic_user_file ${if vhost.basicAuthFile != null then vhost.basicAuthFile else mkHtpasswd vhostName vhost.basicAuth};
+          ''}
 
           ${mkLocations vhost.locations}
 
@@ -248,16 +251,11 @@ let
       ${optionalString (config.proxyPass != null && cfg.recommendedProxySettings) "include ${recommendedProxyConfig};"}
     }
   '') locations);
-  mkBasicAuth = vhostName: authDef: let
+  mkHtpasswd = vhostName: authDef: pkgs.writeText "${vhostName}.htpasswd" (
-    htpasswdFile = pkgs.writeText "${vhostName}.htpasswd" (
     concatStringsSep "\n" (mapAttrsToList (user: password: ''
       ${user}:{PLAIN}${password}
     '') authDef)
   );
-  in ''
-    auth_basic secured;
-    auth_basic_user_file ${htpasswdFile};
-  '';
 in
 
 {