Merge pull request #73113 from aanderse/httpd-vhost

nixos/httpd: support overridable virtual hosts

3 files changed, 68 insertions, 97 deletions

diff --git a/nixos/doc/manual/configuration/abstractions.xml b/nixos/doc/manual/configuration/abstractions.xml
index 5bf0635cc1a..df9ff2615e1 100644
--- a/nixos/doc/manual/configuration/abstractions.xml
+++ b/nixos/doc/manual/configuration/abstractions.xml
@@ -11,50 +11,46 @@
 <programlisting>
 {
   <xref linkend="opt-services.httpd.virtualHosts"/> =
-    [ { hostName = "example.org";
-        documentRoot = "/webroot";
+    { "blog.example.org" = {
+        documentRoot = "/webroot/blog.example.org";
         adminAddr = "alice@example.org";
-        enableUserDir = true;
-      }
-      { hostName = "example.org";
-        documentRoot = "/webroot";
+        forceSSL = true;
+        enableACME = true;
+        enablePHP = true;
+      };
+      "wiki.example.org" = {
+        documentRoot = "/webroot/wiki.example.org";
         adminAddr = "alice@example.org";
-        enableUserDir = true;
-        enableSSL = true;
-        sslServerCert = "/root/ssl-example-org.crt";
-        sslServerKey = "/root/ssl-example-org.key";
-      }
-    ];
+        forceSSL = true;
+        enableACME = true;
+        enablePHP = true;
+      };
+    };
 }
 </programlisting>
   It defines two virtual hosts with nearly identical configuration; the only
-  difference is that the second one has SSL enabled. To prevent this
+  difference is the document root directories. To prevent this
   duplication, we can use a <literal>let</literal>:
 <programlisting>
 let
-  exampleOrgCommon =
-    { hostName = "example.org";
-      documentRoot = "/webroot";
-      adminAddr = "alice@example.org";
-      enableUserDir = true;
+  commonConfig =
+    { adminAddr = "alice@example.org";
+      forceSSL = true;
+      enableACME = true;
     };
 in
 {
   <xref linkend="opt-services.httpd.virtualHosts"/> =
-    [ exampleOrgCommon
-      (exampleOrgCommon // {
-        enableSSL = true;
-        sslServerCert = "/root/ssl-example-org.crt";
-        sslServerKey = "/root/ssl-example-org.key";
-      })
-    ];
+    { "blog.example.org" = (commonConfig // { documentRoot = "/webroot/blog.example.org"; });
+      "wiki.example.org" = (commonConfig // { documentRoot = "/webroot/wiki.example.com"; });
+    };
 }
 </programlisting>
-  The <literal>let exampleOrgCommon = <replaceable>...</replaceable></literal>
-  defines a variable named <literal>exampleOrgCommon</literal>. The
+  The <literal>let commonConfig = <replaceable>...</replaceable></literal>
+  defines a variable named <literal>commonConfig</literal>. The
   <literal>//</literal> operator merges two attribute sets, so the
   configuration of the second virtual host is the set
-  <literal>exampleOrgCommon</literal> extended with the SSL options.
+  <literal>commonConfig</literal> extended with the document root option.
  </para>
 
  <para>
@@ -63,13 +59,13 @@ in
 <programlisting>
 {
   <xref linkend="opt-services.httpd.virtualHosts"/> =
-    let exampleOrgCommon = <replaceable>...</replaceable>; in
-    [ exampleOrgCommon
-      (exampleOrgCommon // { <replaceable>...</replaceable> })
-    ];
+    let commonConfig = <replaceable>...</replaceable>; in
+    { "blog.example.org" = (commonConfig // { <replaceable>...</replaceable> })
+      "wiki.example.org" = (commonConfig // { <replaceable>...</replaceable> })
+    };
 }
 </programlisting>
-  but not <literal>{ let exampleOrgCommon = <replaceable>...</replaceable>; in
+  but not <literal>{ let commonConfig = <replaceable>...</replaceable>; in
   <replaceable>...</replaceable>; }</literal> since attributes (as opposed to
   attribute values) are not expressions.
  </para>
@@ -77,80 +73,29 @@ in
  <para>
   <emphasis>Functions</emphasis> provide another method of abstraction. For
   instance, suppose that we want to generate lots of different virtual hosts,
-  all with identical configuration except for the host name. This can be done
+  all with identical configuration except for the document root. This can be done
   as follows:
 <programlisting>
 {
   <xref linkend="opt-services.httpd.virtualHosts"/> =
     let
-      makeVirtualHost = name:
-        { hostName = name;
-          documentRoot = "/webroot";
+      makeVirtualHost = webroot:
+        { documentRoot = webroot;
           adminAddr = "alice@example.org";
+          forceSSL = true;
+          enableACME = true;
         };
     in
-      [ (makeVirtualHost "example.org")
-        (makeVirtualHost "example.com")
-        (makeVirtualHost "example.gov")
-        (makeVirtualHost "example.nl")
-      ];
+      { "example.org" = (makeVirtualHost "/webroot/example.org");
+        "example.com" = (makeVirtualHost "/webroot/example.com");
+        "example.gov" = (makeVirtualHost "/webroot/example.gov");
+        "example.nl" = (makeVirtualHost "/webroot/example.nl");
+      };
 }
 </programlisting>
   Here, <varname>makeVirtualHost</varname> is a function that takes a single
-  argument <literal>name</literal> and returns the configuration for a virtual
+  argument <literal>webroot</literal> and returns the configuration for a virtual
   host. That function is then called for several names to produce the list of
   virtual host configurations.
  </para>
-
- <para>
-  We can further improve on this by using the function <varname>map</varname>,
-  which applies another function to every element in a list:
-<programlisting>
-{
-  <xref linkend="opt-services.httpd.virtualHosts"/> =
-    let
-      makeVirtualHost = <replaceable>...</replaceable>;
-    in map makeVirtualHost
-      [ "example.org" "example.com" "example.gov" "example.nl" ];
-}
-</programlisting>
-  (The function <literal>map</literal> is called a <emphasis>higher-order
-  function</emphasis> because it takes another function as an argument.)
- </para>
-
- <para>
-  What if you need more than one argument, for instance, if we want to use a
-  different <literal>documentRoot</literal> for each virtual host? Then we can
-  make <varname>makeVirtualHost</varname> a function that takes a
-  <emphasis>set</emphasis> as its argument, like this:
-<programlisting>
-{
-  <xref linkend="opt-services.httpd.virtualHosts"/> =
-    let
-      makeVirtualHost = { name, root }:
-        { hostName = name;
-          documentRoot = root;
-          adminAddr = "alice@example.org";
-        };
-    in map makeVirtualHost
-      [ { name = "example.org"; root = "/sites/example.org"; }
-        { name = "example.com"; root = "/sites/example.com"; }
-        { name = "example.gov"; root = "/sites/example.gov"; }
-        { name = "example.nl"; root = "/sites/example.nl"; }
-      ];
-}
-</programlisting>
-  But in this case (where every root is a subdirectory of
-  <filename>/sites</filename> named after the virtual host), it would have been
-  shorter to define <varname>makeVirtualHost</varname> as
-<programlisting>
-makeVirtualHost = name:
-  { hostName = name;
-    documentRoot = "/sites/${name}";
-    adminAddr = "alice@example.org";
-  };
-</programlisting>
-  Here, the construct <literal>${<replaceable>...</replaceable>}</literal>
-  allows the result of an expression to be spliced into a string.
- </para>
 </section>
diff --git a/nixos/doc/manual/configuration/config-file.xml b/nixos/doc/manual/configuration/config-file.xml
index eadafb94b8f..7ccb5b3664e 100644
--- a/nixos/doc/manual/configuration/config-file.xml
+++ b/nixos/doc/manual/configuration/config-file.xml
@@ -27,7 +27,7 @@
 
 { <xref linkend="opt-services.httpd.enable"/> = true;
   <xref linkend="opt-services.httpd.adminAddr"/> = "alice@example.org";
-  <xref linkend="opt-services.httpd.documentRoot"/> = "/webroot";
+  <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.localhost.documentRoot</link> = "/webroot";
 }
 </programlisting>
   defines a configuration with three option definitions that together enable
@@ -50,7 +50,11 @@
     httpd = {
       enable = true;
       adminAddr = "alice@example.org";
-      documentRoot = "/webroot";
+      virtualHosts = {
+        localhost = {
+          documentRoot = "/webroot";
+        };
+      };
     };
   };
 }
diff --git a/nixos/doc/manual/release-notes/rl-2003.xml b/nixos/doc/manual/release-notes/rl-2003.xml
index d54d2cd87ae..1c1c8908064 100644
--- a/nixos/doc/manual/release-notes/rl-2003.xml
+++ b/nixos/doc/manual/release-notes/rl-2003.xml
@@ -327,6 +327,28 @@ services.xserver.displayManager.defaultSession = "xfce+icewm";
      module.
     </para>
    </listitem>
+   <listitem>
+    <para>
+      The httpd module no longer provides options to support serving web content without defining a virtual host. As a
+      result of this the <link linkend="opt-services.httpd.logPerVirtualHost">services.httpd.logPerVirtualHost</link>
+      option now defaults to <literal>true</literal> instead of <literal>false</literal>. Please update your
+      configuration to make use of <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts</link>.
+    </para>
+    <para>
+      The <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;</link>
+      option has changed type from a list of submodules to an attribute set of submodules, better matching
+      <link linkend="opt-services.nginx.virtualHosts">services.nginx.virtualHosts.&lt;name&gt;</link>.
+    </para>
+    <para>
+      This change comes with the addition of the following options which mimic the functionality of their <literal>nginx</literal> counterparts:
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.addSSL</link>,
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.forceSSL</link>,
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.onlySSL</link>,
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.enableACME</link>,
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.acmeRoot</link>, and
+      <link linkend="opt-services.httpd.virtualHosts">services.httpd.virtualHosts.&lt;name&gt;.useACMEHost</link>.
+    </para>
+   </listitem>
   </itemizedlist>
  </section>