nixos/modules/services/web-servers/nginx/vhost-options.nix

   1 # This file defines the options that can be used both for the Nginx
   2 # main server configuration, and for the virtual hosts.  (The latter
   3 # has additional options that affect the web server as a whole, like
   4 # the user/group to run under.)
   5
   6 { config, lib, ... }:
   7
   8 with lib;
   9 {
  10   options = {
  11     serverName = mkOption {
  12       type = types.nullOr types.str;
  13       default = null;
  14       description = ''
  15         Name of this virtual host. Defaults to attribute name in virtualHosts.
  16       '';
  17       example = "example.org";
  18     };
  19
  20     serverAliases = mkOption {
  21       type = types.listOf types.str;
  22       default = [];
  23       example = [ "www.example.org" "example.org" ];
  24       description = ''
  25         Additional names of virtual hosts served by this virtual host configuration.
  26       '';
  27     };
  28
  29     listen = mkOption {
  30       type = with types; listOf (submodule {
  31         options = {
  32           addr = mkOption {
  33             type = str;
  34             description = "Listen address.";
  35           };
  36           port = mkOption {
  37             type = types.nullOr port;
  38             description = ''
  39               Port number to listen on.
  40               If unset and the listen address is not a socket then nginx defaults to 80.
  41             '';
  42             default = null;
  43           };
  44           ssl = mkOption {
  45             type = bool;
  46             description = "Enable SSL.";
  47             default = false;
  48           };
  49           proxyProtocol = mkOption {
  50             type = bool;
  51             description = "Enable PROXY protocol.";
  52             default = false;
  53           };
  54           extraParameters = mkOption {
  55             type = listOf str;
  56             description = "Extra parameters of this listen directive.";
  57             default = [ ];
  58             example = [ "backlog=1024" "deferred" ];
  59           };
  60         };
  61       });
  62       default = [];
  63       example = [
  64         { addr = "195.154.1.1"; port = 443; ssl = true; }
  65         { addr = "192.154.1.1"; port = 80; }
  66         { addr = "unix:/var/run/nginx.sock"; }
  67       ];
  68       description = ''
  69         Listen addresses and ports for this virtual host.
  70         IPv6 addresses must be enclosed in square brackets.
  71         Note: this option overrides `addSSL`
  72         and `onlySSL`.
  73
  74         If you only want to set the addresses manually and not
  75         the ports, take a look at `listenAddresses`.
  76       '';
  77     };
  78
  79     listenAddresses = mkOption {
  80       type = with types; listOf str;
  81
  82       description = ''
  83         Listen addresses for this virtual host.
  84         Compared to `listen` this only sets the addresses
  85         and the ports are chosen automatically.
  86
  87         Note: This option overrides `enableIPv6`
  88       '';
  89       default = [];
  90       example = [ "127.0.0.1" "[::1]" ];
  91     };
  92
  93     enableACME = mkOption {
  94       type = types.bool;
  95       default = false;
  96       description = ''
  97         Whether to ask Let's Encrypt to sign a certificate for this vhost.
  98         Alternately, you can use an existing certificate through {option}`useACMEHost`.
  99       '';
 100     };
 101
 102     useACMEHost = mkOption {
 103       type = types.nullOr types.str;
 104       default = null;
 105       description = ''
 106         A host of an existing Let's Encrypt certificate to use.
 107         This is useful if you have many subdomains and want to avoid hitting the
 108         [rate limit](https://letsencrypt.org/docs/rate-limits).
 109         Alternately, you can generate a certificate through {option}`enableACME`.
 110         *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 [](#opt-security.acme.certs).*
 111       '';
 112     };
 113
 114     acmeRoot = mkOption {
 115       type = types.nullOr types.str;
 116       default = "/var/lib/acme/acme-challenge";
 117       description = ''
 118         Directory for the ACME challenge, which is **public**. Don't put certs or keys in here.
 119         Set to null to inherit from config.security.acme.
 120       '';
 121     };
 122
 123     acmeFallbackHost = mkOption {
 124       type = types.nullOr types.str;
 125       default = null;
 126       description = ''
 127         Host which to proxy requests to if ACME challenge is not found. Useful
 128         if you want multiple hosts to be able to verify the same domain name.
 129
 130         With this option, you could request certificates for the present domain
 131         with an ACME client that is running on another host, which you would
 132         specify here.
 133       '';
 134     };
 135
 136     addSSL = mkOption {
 137       type = types.bool;
 138       default = false;
 139       description = ''
 140         Whether to enable HTTPS in addition to plain HTTP. This will set defaults for
 141         `listen` to listen on all interfaces on the respective default
 142         ports (80, 443).
 143       '';
 144     };
 145
 146     onlySSL = mkOption {
 147       type = types.bool;
 148       default = false;
 149       description = ''
 150         Whether to enable HTTPS and reject plain HTTP connections. This will set
 151         defaults for `listen` to listen on all interfaces on port 443.
 152       '';
 153     };
 154
 155     enableSSL = mkOption {
 156       type = types.bool;
 157       visible = false;
 158       default = false;
 159     };
 160
 161     forceSSL = mkOption {
 162       type = types.bool;
 163       default = false;
 164       description = ''
 165         Whether to add a separate nginx server block that redirects (defaults
 166         to 301, configurable with `redirectCode`) all plain HTTP traffic to
 167         HTTPS. This will set defaults for `listen` to listen on all interfaces
 168         on the respective default ports (80, 443), where the non-SSL listens
 169         are used for the redirect vhosts.
 170       '';
 171     };
 172
 173     rejectSSL = mkOption {
 174       type = types.bool;
 175       default = false;
 176       description = ''
 177         Whether to listen for and reject all HTTPS connections to this vhost. Useful in
 178         [default](#opt-services.nginx.virtualHosts._name_.default)
 179         server blocks to avoid serving the certificate for another vhost. Uses the
 180         `ssl_reject_handshake` directive available in nginx versions
 181         1.19.4 and above.
 182       '';
 183     };
 184
 185     kTLS = mkOption {
 186       type = types.bool;
 187       default = false;
 188       description = ''
 189         Whether to enable kTLS support.
 190         Implementing TLS in the kernel (kTLS) improves performance by significantly
 191         reducing the need for copying operations between user space and the kernel.
 192         Required Nginx version 1.21.4 or later.
 193       '';
 194     };
 195
 196     sslCertificate = mkOption {
 197       type = types.path;
 198       example = "/var/host.cert";
 199       description = "Path to server SSL certificate.";
 200     };
 201
 202     sslCertificateKey = mkOption {
 203       type = types.path;
 204       example = "/var/host.key";
 205       description = "Path to server SSL certificate key.";
 206     };
 207
 208     sslTrustedCertificate = mkOption {
 209       type = types.nullOr types.path;
 210       default = null;
 211       example = literalExpression ''"''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt"'';
 212       description = "Path to root SSL certificate for stapling and client certificates.";
 213     };
 214
 215     http2 = mkOption {
 216       type = types.bool;
 217       default = true;
 218       description = ''
 219         Whether to enable the HTTP/2 protocol.
 220         Note that (as of writing) due to nginx's implementation, to disable
 221         HTTP/2 you have to disable it on all vhosts that use a given
 222         IP address / port.
 223         If there is one server block configured to enable http2, then it is
 224         enabled for all server blocks on this IP.
 225         See https://stackoverflow.com/a/39466948/263061.
 226       '';
 227     };
 228
 229     http3 = mkOption {
 230       type = types.bool;
 231       default = true;
 232       description = ''
 233         Whether to enable the HTTP/3 protocol.
 234         This requires using `pkgs.nginxQuic` package
 235         which can be achieved by setting `services.nginx.package = pkgs.nginxQuic;`
 236         and activate the QUIC transport protocol
 237         `services.nginx.virtualHosts.<name>.quic = true;`.
 238         Note that HTTP/3 support is experimental and *not* yet recommended for production.
 239         Read more at https://quic.nginx.org/
 240         HTTP/3 availability must be manually advertised, preferably in each location block.
 241       '';
 242     };
 243
 244     http3_hq = mkOption {
 245       type = types.bool;
 246       default = false;
 247       description = ''
 248         Whether to enable the HTTP/0.9 protocol negotiation used in QUIC interoperability tests.
 249         This requires using `pkgs.nginxQuic` package
 250         which can be achieved by setting `services.nginx.package = pkgs.nginxQuic;`
 251         and activate the QUIC transport protocol
 252         `services.nginx.virtualHosts.<name>.quic = true;`.
 253         Note that special application protocol support is experimental and *not* yet recommended for production.
 254         Read more at https://quic.nginx.org/
 255       '';
 256     };
 257
 258     quic = mkOption {
 259       type = types.bool;
 260       default = false;
 261       description = ''
 262         Whether to enable the QUIC transport protocol.
 263         This requires using `pkgs.nginxQuic` package
 264         which can be achieved by setting `services.nginx.package = pkgs.nginxQuic;`.
 265         Note that QUIC support is experimental and
 266         *not* yet recommended for production.
 267         Read more at https://quic.nginx.org/
 268       '';
 269     };
 270
 271     reuseport = mkOption {
 272       type = types.bool;
 273       default = false;
 274       description = ''
 275         Create an individual listening socket .
 276         It is required to specify only once on one of the hosts.
 277       '';
 278     };
 279
 280     root = mkOption {
 281       type = types.nullOr types.path;
 282       default = null;
 283       example = "/data/webserver/docs";
 284       description = ''
 285         The path of the web root directory.
 286       '';
 287     };
 288
 289     default = mkOption {
 290       type = types.bool;
 291       default = false;
 292       description = ''
 293         Makes this vhost the default.
 294       '';
 295     };
 296
 297     extraConfig = mkOption {
 298       type = types.lines;
 299       default = "";
 300       description = ''
 301         These lines go to the end of the vhost verbatim.
 302       '';
 303     };
 304
 305     globalRedirect = mkOption {
 306       type = types.nullOr types.str;
 307       default = null;
 308       example = "newserver.example.org";
 309       description = ''
 310         If set, all requests for this host are redirected (defaults to 301,
 311         configurable with `redirectCode`) to the given hostname.
 312       '';
 313     };
 314
 315     redirectCode = mkOption {
 316       type = types.ints.between 300 399;
 317       default = 301;
 318       example = 308;
 319       description = ''
 320         HTTP status used by `globalRedirect` and `forceSSL`. Possible usecases
 321         include temporary (302, 307) redirects, keeping the request method and
 322         body (307, 308), or explicitly resetting the method to GET (303).
 323         See <https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections>.
 324       '';
 325     };
 326
 327     basicAuth = mkOption {
 328       type = types.attrsOf types.str;
 329       default = {};
 330       example = literalExpression ''
 331         {
 332           user = "password";
 333         };
 334       '';
 335       description = ''
 336         Basic Auth protection for a vhost.
 337
 338         WARNING: This is implemented to store the password in plain text in the
 339         Nix store.
 340       '';
 341     };
 342
 343     basicAuthFile = mkOption {
 344       type = types.nullOr types.path;
 345       default = null;
 346       description = ''
 347         Basic Auth password file for a vhost.
 348         Can be created via: {command}`htpasswd -c <filename> <username>`.
 349
 350         WARNING: The generate file contains the users' passwords in a
 351         non-cryptographically-securely hashed way.
 352       '';
 353     };
 354
 355     locations = mkOption {
 356       type = types.attrsOf (types.submodule (import ./location-options.nix {
 357         inherit lib config;
 358       }));
 359       default = {};
 360       example = literalExpression ''
 361         {
 362           "/" = {
 363             proxyPass = "http://localhost:3000";
 364           };
 365         };
 366       '';
 367       description = "Declarative location config";
 368     };
 369   };
 370 }