modules/websites/vhost-options.nix

   1 { config, lib, name, ... }:
   2 let
   3   inherit (lib) literalExample mkOption nameValuePair types;
   4 in
   5 {
   6   options = {
   7
   8     hostName = mkOption {
   9       type = types.str;
  10       default = name;
  11       description = "Canonical hostname for the server.";
  12     };
  13
  14     serverAliases = mkOption {
  15       type = types.listOf types.str;
  16       default = [];
  17       example = ["www.example.org" "www.example.org:8080" "example.org"];
  18       description = ''
  19         Additional names of virtual hosts served by this virtual host configuration.
  20       '';
  21     };
  22
  23     listen = mkOption {
  24       type = with types; listOf (submodule ({
  25         options = {
  26           port = mkOption {
  27             type = types.port;
  28             description = "Port to listen on";
  29           };
  30           ip = mkOption {
  31             type = types.str;
  32             default = "*";
  33             description = "IP to listen on. 0.0.0.0 for IPv4 only, * for all.";
  34           };
  35           ssl = mkOption {
  36             type = types.bool;
  37             default = false;
  38             description = "Whether to enable SSL (https) support.";
  39           };
  40         };
  41       }));
  42       default = [];
  43       example = [
  44         { ip = "195.154.1.1"; port = 443; ssl = true;}
  45         { ip = "192.154.1.1"; port = 80; }
  46         { ip = "*"; port = 8080; }
  47       ];
  48       description = ''
  49         Listen addresses and ports for this virtual host.
  50         <note><para>
  51           This option overrides <literal>addSSL</literal>, <literal>forceSSL</literal> and <literal>onlySSL</literal>.
  52         </para></note>
  53       '';
  54     };
  55
  56     enableSSL = mkOption {
  57       type = types.bool;
  58       visible = false;
  59       default = false;
  60     };
  61
  62     addSSL = mkOption {
  63       type = types.bool;
  64       default = false;
  65       description = ''
  66         Whether to enable HTTPS in addition to plain HTTP. This will set defaults for
  67         <literal>listen</literal> to listen on all interfaces on the respective default
  68         ports (80, 443).
  69       '';
  70     };
  71
  72     onlySSL = mkOption {
  73       type = types.bool;
  74       default = false;
  75       description = ''
  76         Whether to enable HTTPS and reject plain HTTP connections. This will set
  77         defaults for <literal>listen</literal> to listen on all interfaces on port 443.
  78       '';
  79     };
  80
  81     forceSSL = mkOption {
  82       type = types.bool;
  83       default = false;
  84       description = ''
  85         Whether to add a separate nginx server block that permanently redirects (301)
  86         all plain HTTP traffic to HTTPS. This will set defaults for
  87         <literal>listen</literal> to listen on all interfaces on the respective default
  88         ports (80, 443), where the non-SSL listens are used for the redirect vhosts.
  89       '';
  90     };
  91
  92     enableACME = mkOption {
  93       type = types.bool;
  94       default = false;
  95       description = ''
  96         Whether to ask Let's Encrypt to sign a certificate for this vhost.
  97         Alternately, you can use an existing certificate through <option>useACMEHost</option>.
  98       '';
  99     };
 100
 101     useACMEHost = mkOption {
 102       type = types.nullOr types.str;
 103       default = null;
 104       description = ''
 105         A host of an existing Let's Encrypt certificate to use.
 106         This is useful if you have many subdomains and want to avoid hitting the
 107         <link xlink:href="https://letsencrypt.org/docs/rate-limits/">rate limit</link>.
 108         Alternately, you can generate a certificate through <option>enableACME</option>.
 109         <emphasis>Note that this option does not create any certificates, nor it does add subdomains to existing ones – you will need to create them manually using  <xref linkend="opt-security.acme.certs"/>.</emphasis>
 110       '';
 111     };
 112
 113     acmeRoot = mkOption {
 114       type = types.str;
 115       default = "/var/lib/acme/acme-challenges";
 116       description = "Directory for the acme challenge which is PUBLIC, don't put certs or keys in here";
 117     };
 118
 119     sslServerCert = mkOption {
 120       type = types.path;
 121       example = "/var/host.cert";
 122       description = "Path to server SSL certificate.";
 123     };
 124
 125     sslServerKey = mkOption {
 126       type = types.path;
 127       example = "/var/host.key";
 128       description = "Path to server SSL certificate key.";
 129     };
 130
 131     sslServerChain = mkOption {
 132       type = types.nullOr types.path;
 133       default = null;
 134       example = "/var/ca.pem";
 135       description = "Path to server SSL chain file.";
 136     };
 137
 138     http2 = mkOption {
 139       type = types.bool;
 140       default = false;
 141       description = ''
 142         Whether to enable HTTP 2. HTTP/2 is supported in all multi-processing modules that come with httpd. <emphasis>However, if you use the prefork mpm, there will
 143         be severe restrictions.</emphasis> Refer to <link xlink:href="https://httpd.apache.org/docs/2.4/howto/http2.html#mpm-config"/> for details.
 144       '';
 145     };
 146
 147     adminAddr = mkOption {
 148       type = types.nullOr types.str;
 149       default = null;
 150       example = "admin@example.org";
 151       description = "E-mail address of the server administrator.";
 152     };
 153
 154     documentRoot = mkOption {
 155       type = types.nullOr types.path;
 156       default = null;
 157       example = "/data/webserver/docs";
 158       description = ''
 159         The path of Apache's document root directory.  If left undefined,
 160         an empty directory in the Nix store will be used as root.
 161       '';
 162     };
 163
 164     servedDirs = mkOption {
 165       type = types.listOf types.attrs;
 166       default = [];
 167       example = [
 168         { urlPath = "/nix";
 169           dir = "/home/eelco/Dev/nix-homepage";
 170         }
 171       ];
 172       description = ''
 173         This option provides a simple way to serve static directories.
 174       '';
 175     };
 176
 177     servedFiles = mkOption {
 178       type = types.listOf types.attrs;
 179       default = [];
 180       example = [
 181         { urlPath = "/foo/bar.png";
 182           file = "/home/eelco/some-file.png";
 183         }
 184       ];
 185       description = ''
 186         This option provides a simple way to serve individual, static files.
 187
 188         <note><para>
 189           This option has been deprecated and will be removed in a future
 190           version of NixOS. You can achieve the same result by making use of
 191           the <literal>locations.&lt;name&gt;.alias</literal> option.
 192         </para></note>
 193       '';
 194     };
 195
 196     extraConfig = mkOption {
 197       type = types.lines;
 198       default = "";
 199       example = ''
 200         <Directory /home>
 201           Options FollowSymlinks
 202           AllowOverride All
 203         </Directory>
 204       '';
 205       description = ''
 206         These lines go to httpd.conf verbatim. They will go after
 207         directories and directory aliases defined by default.
 208       '';
 209     };
 210
 211     enableUserDir = mkOption {
 212       type = types.bool;
 213       default = false;
 214       description = ''
 215         Whether to enable serving <filename>~/public_html</filename> as
 216         <literal>/~<replaceable>username</replaceable></literal>.
 217       '';
 218     };
 219
 220     globalRedirect = mkOption {
 221       type = types.nullOr types.str;
 222       default = null;
 223       example = http://newserver.example.org/;
 224       description = ''
 225         If set, all requests for this host are redirected permanently to
 226         the given URL.
 227       '';
 228     };
 229
 230     logFormat = mkOption {
 231       type = types.str;
 232       default = "common";
 233       example = "combined";
 234       description = ''
 235         Log format for Apache's log files. Possible values are: combined, common, referer, agent.
 236       '';
 237     };
 238
 239     robotsEntries = mkOption {
 240       type = types.lines;
 241       default = "";
 242       example = "Disallow: /foo/";
 243       description = ''
 244         Specification of pages to be ignored by web crawlers. See <link
 245         xlink:href='http://www.robotstxt.org/'/> for details.
 246       '';
 247     };
 248
 249     locations = mkOption {
 250       type = with types; attrsOf (submodule (import ./location-options.nix));
 251       default = {};
 252       example = literalExample ''
 253         {
 254           "/" = {
 255             proxyPass = "http://localhost:3000";
 256           };
 257           "/foo/bar.png" = {
 258             alias = "/home/eelco/some-file.png";
 259           };
 260         };
 261       '';
 262       description = ''
 263         Declarative location config. See <link
 264         xlink:href="https://httpd.apache.org/docs/2.4/mod/core.html#location"/> for details.
 265       '';
 266     };
 267
 268   };
 269
 270   config = {
 271
 272     locations = builtins.listToAttrs (map (elem: nameValuePair elem.urlPath { alias = elem.file; }) config.servedFiles);
 273
 274   };
 275 }