pyrox.dev
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, ... }:
7
8with 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 { options = {
31 addr = mkOption { type = str; description = "IP address."; };
32 port = mkOption { type = int; description = "Port number."; default = 80; };
33 ssl = mkOption { type = bool; description = "Enable SSL."; default = false; };
34 extraParameters = mkOption { type = listOf str; description = "Extra parameters of this listen directive."; default = []; example = [ "reuseport" "deferred" ]; };
35 }; });
36 default = [];
37 example = [
38 { addr = "195.154.1.1"; port = 443; ssl = true;}
39 { addr = "192.154.1.1"; port = 80; }
40 ];
41 description = ''
42 Listen addresses and ports for this virtual host.
43 IPv6 addresses must be enclosed in square brackets.
44 Note: this option overrides <literal>addSSL</literal>
45 and <literal>onlySSL</literal>.
46 '';
47 };
48
49 enableACME = mkOption {
50 type = types.bool;
51 default = false;
52 description = ''
53 Whether to ask Let's Encrypt to sign a certificate for this vhost.
54 Alternately, you can use an existing certificate through <option>useACMEHost</option>.
55 '';
56 };
57
58 useACMEHost = mkOption {
59 type = types.nullOr types.str;
60 default = null;
61 description = ''
62 A host of an existing Let's Encrypt certificate to use.
63 This is useful if you have many subdomains and want to avoid hitting the
64 <link xlink:href="https://letsencrypt.org/docs/rate-limits/">rate limit</link>.
65 Alternately, you can generate a certificate through <option>enableACME</option>.
66 <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>
67 '';
68 };
69
70 acmeRoot = mkOption {
71 type = types.str;
72 default = "/var/lib/acme/acme-challenge";
73 description = "Directory for the acme challenge which is PUBLIC, don't put certs or keys in here";
74 };
75
76 acmeFallbackHost = mkOption {
77 type = types.nullOr types.str;
78 default = null;
79 description = ''
80 Host which to proxy requests to if acme challenge is not found. Useful
81 if you want multiple hosts to be able to verify the same domain name.
82 '';
83 };
84
85 addSSL = mkOption {
86 type = types.bool;
87 default = false;
88 description = ''
89 Whether to enable HTTPS in addition to plain HTTP. This will set defaults for
90 <literal>listen</literal> to listen on all interfaces on the respective default
91 ports (80, 443).
92 '';
93 };
94
95 onlySSL = mkOption {
96 type = types.bool;
97 default = false;
98 description = ''
99 Whether to enable HTTPS and reject plain HTTP connections. This will set
100 defaults for <literal>listen</literal> to listen on all interfaces on port 443.
101 '';
102 };
103
104 enableSSL = mkOption {
105 type = types.bool;
106 visible = false;
107 default = false;
108 };
109
110 forceSSL = mkOption {
111 type = types.bool;
112 default = false;
113 description = ''
114 Whether to add a separate nginx server block that permanently redirects (301)
115 all plain HTTP traffic to HTTPS. This will set defaults for
116 <literal>listen</literal> to listen on all interfaces on the respective default
117 ports (80, 443), where the non-SSL listens are used for the redirect vhosts.
118 '';
119 };
120
121 sslCertificate = mkOption {
122 type = types.path;
123 example = "/var/host.cert";
124 description = "Path to server SSL certificate.";
125 };
126
127 sslCertificateKey = mkOption {
128 type = types.path;
129 example = "/var/host.key";
130 description = "Path to server SSL certificate key.";
131 };
132
133 sslTrustedCertificate = mkOption {
134 type = types.nullOr types.path;
135 default = null;
136 example = "/var/root.cert";
137 description = "Path to root SSL certificate for stapling and client certificates.";
138 };
139
140 http2 = mkOption {
141 type = types.bool;
142 default = true;
143 description = ''
144 Whether to enable HTTP 2.
145 Note that (as of writing) due to nginx's implementation, to disable
146 HTTP 2 you have to disable it on all vhosts that use a given
147 IP address / port.
148 If there is one server block configured to enable http2,then it is
149 enabled for all server blocks on this IP.
150 See https://stackoverflow.com/a/39466948/263061.
151 '';
152 };
153
154 http3 = mkOption {
155 type = types.bool;
156 default = false;
157 description = ''
158 Whether to enable HTTP 3.
159 This requires using <literal>pkgs.nginxQuic</literal> package
160 which can be achived by setting <literal>services.nginx.package = pkgs.nginxQuic;</literal>.
161 Note that HTTP 3 support is experimental and
162 *not* yet recommended for production.
163 Read more at https://quic.nginx.org/
164 '';
165 };
166
167 root = mkOption {
168 type = types.nullOr types.path;
169 default = null;
170 example = "/data/webserver/docs";
171 description = ''
172 The path of the web root directory.
173 '';
174 };
175
176 default = mkOption {
177 type = types.bool;
178 default = false;
179 description = ''
180 Makes this vhost the default.
181 '';
182 };
183
184 extraConfig = mkOption {
185 type = types.lines;
186 default = "";
187 description = ''
188 These lines go to the end of the vhost verbatim.
189 '';
190 };
191
192 globalRedirect = mkOption {
193 type = types.nullOr types.str;
194 default = null;
195 example = "newserver.example.org";
196 description = ''
197 If set, all requests for this host are redirected permanently to
198 the given hostname.
199 '';
200 };
201
202 basicAuth = mkOption {
203 type = types.attrsOf types.str;
204 default = {};
205 example = literalExample ''
206 {
207 user = "password";
208 };
209 '';
210 description = ''
211 Basic Auth protection for a vhost.
212
213 WARNING: This is implemented to store the password in plain text in the
214 Nix store.
215 '';
216 };
217
218 basicAuthFile = mkOption {
219 type = types.nullOr types.path;
220 default = null;
221 description = ''
222 Basic Auth password file for a vhost.
223 Can be created via: <command>htpasswd -c <filename> <username></command>.
224
225 WARNING: The generate file contains the users' passwords in a
226 non-cryptographically-securely hashed way.
227 '';
228 };
229
230 locations = mkOption {
231 type = types.attrsOf (types.submodule (import ./location-options.nix {
232 inherit lib;
233 }));
234 default = {};
235 example = literalExample ''
236 {
237 "/" = {
238 proxyPass = "http://localhost:3000";
239 };
240 };
241 '';
242 description = "Declarative location config";
243 };
244 };
245}