nixos/modules/services/web-servers/nginx/location-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 { lib, config }:
   7
   8 with lib;
   9
  10 {
  11   options = {
  12     basicAuth = mkOption {
  13       type = types.attrsOf types.str;
  14       default = {};
  15       example = literalExpression ''
  16         {
  17           user = "password";
  18         };
  19       '';
  20       description = ''
  21         Basic Auth protection for a vhost.
  22
  23         WARNING: This is implemented to store the password in plain text in the
  24         Nix store.
  25       '';
  26     };
  27
  28     basicAuthFile = mkOption {
  29       type = types.nullOr types.path;
  30       default = null;
  31       description = ''
  32         Basic Auth password file for a vhost.
  33         Can be created via: {command}`htpasswd -c <filename> <username>`.
  34
  35         WARNING: The generate file contains the users' passwords in a
  36         non-cryptographically-securely hashed way.
  37       '';
  38     };
  39
  40     proxyPass = mkOption {
  41       type = types.nullOr types.str;
  42       default = null;
  43       example = "http://www.example.org/";
  44       description = ''
  45         Adds proxy_pass directive and sets recommended proxy headers if
  46         recommendedProxySettings is enabled.
  47       '';
  48     };
  49
  50     proxyWebsockets = mkOption {
  51       type = types.bool;
  52       default = false;
  53       example = true;
  54       description = ''
  55         Whether to support proxying websocket connections with HTTP/1.1.
  56       '';
  57     };
  58
  59     index = mkOption {
  60       type = types.nullOr types.str;
  61       default = null;
  62       example = "index.php index.html";
  63       description = ''
  64         Adds index directive.
  65       '';
  66     };
  67
  68     tryFiles = mkOption {
  69       type = types.nullOr types.str;
  70       default = null;
  71       example = "$uri =404";
  72       description = ''
  73         Adds try_files directive.
  74       '';
  75     };
  76
  77     root = mkOption {
  78       type = types.nullOr types.path;
  79       default = null;
  80       example = "/your/root/directory";
  81       description = ''
  82         Root directory for requests.
  83       '';
  84     };
  85
  86     alias = mkOption {
  87       type = types.nullOr types.path;
  88       default = null;
  89       example = "/your/alias/directory";
  90       description = ''
  91         Alias directory for requests.
  92       '';
  93     };
  94
  95     return = mkOption {
  96       type = with types; nullOr (oneOf [ str int ]);
  97       default = null;
  98       example = "301 http://example.com$request_uri";
  99       description = ''
 100         Adds a return directive, for e.g. redirections.
 101       '';
 102     };
 103
 104     fastcgiParams = mkOption {
 105       type = types.attrsOf (types.either types.str types.path);
 106       default = {};
 107       description = ''
 108         FastCGI parameters to override.  Unlike in the Nginx
 109         configuration file, overriding only some default parameters
 110         won't unset the default values for other parameters.
 111       '';
 112     };
 113
 114     extraConfig = mkOption {
 115       type = types.lines;
 116       default = "";
 117       description = ''
 118         These lines go to the end of the location verbatim.
 119       '';
 120     };
 121
 122     priority = mkOption {
 123       type = types.int;
 124       default = 1000;
 125       description = ''
 126         Order of this location block in relation to the others in the vhost.
 127         The semantics are the same as with `lib.mkOrder`. Smaller values have
 128         a greater priority.
 129       '';
 130     };
 131
 132     recommendedProxySettings = mkOption {
 133       type = types.bool;
 134       default = config.services.nginx.recommendedProxySettings;
 135       defaultText = literalExpression "config.services.nginx.recommendedProxySettings";
 136       description = ''
 137         Enable recommended proxy settings.
 138       '';
 139     };
 140   };
 141 }