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