2 # This is a template copy it by: ./README.sh | xclip -selection c
3 # to https://openwrt.org/docs/guide-user/services/webserver/nginx#configuration
5 NGINX_UTIL
="/usr/bin/nginx-util"
7 EXAMPLE_COM
="example.com"
10 /* Created by the following bash script that includes the source of some files:
11 * https://github.com/openwrt/packages/net/nginx/files/README.sh
14 eval $
("${NGINX_UTIL}" get_env
)
16 code
() { printf "<file nginx %s>\n%s</file>" "$1" "$(cat "$
(basename $1)")"; }
18 ifConfEcho
() { sed -nE "s/^\s*$1=\s*(\S*)\s*\\\\$/\n$2 \"\1\";/p" ..
/Makefile
;}
26 ===== Configuration =====${MSG}
30 The official Documentation contains a
31 [[https://docs.nginx.com/nginx/admin-guide/|Admin Guide]].
32 Here we will look at some often used configuration parts and how we handle them
34 At different places there are references to the official
35 [[https://docs.nginx.com/nginx/technical-specs/|Technical Specs]]
38 **tl;dr:** The main configuration is a minimal configuration enabling the
39 ''${CONF_DIR}'' directory:
40 * There is a ''${LAN_NAME}.conf'' containing a default server for the LAN, \
41 which includes all ''*.locations''.
42 * We can disable parts of the configuration by renaming them.
43 * If we want to install other servers that are also reachable from the LAN, \
44 we can include the ''${LAN_LISTEN}'' file (or ''${LAN_SSL_LISTEN}'' for \
46 * If Nginx is installed with SSL support, we have a server \
47 in ''_redirect2ssl.conf'' that redirects inexistent URLs to HTTPS, too.
48 * We can create a self-signed certificate and add corresponding directives \
49 to e.g. ''${EXAMPLE_COM}.conf'' by invoking \
50 <code>$(basename ${NGINX_UTIL}) ${ADD_SSL_FCT} ${EXAMPLE_COM}</code>
57 We modify the configuration by creating different configuration files in the
58 ''${CONF_DIR}'' directory.
59 The configuration files use the file extensions ''.locations'' and
60 ''.conf'' (plus ''.crt'' and ''.key'' for Nginx with SSL).
61 We can disable single configuration parts by giving them another extension,
62 e.g., by adding ''.disabled''.
63 For the new configuration to take effect, we must reload it by:
64 <code>service nginx reload</code>
66 For OpenWrt we use a special initial configuration, which is explained below in
67 the section [[#openwrt_s_defaults|OpenWrt’s Defaults]].
68 So, we can make a site available at a specific URL in the **LAN** by creating a
69 ''.locations'' file in the directory ''${CONF_DIR}''.
70 Such a file consists just of some
71 [[https://nginx.org/en/docs/http/ngx_http_core_module.html#location|
73 Under the latter link, you can find also the official documentation for all
74 available directives of the HTTP core of Nginx.
75 Look for //location// in the Context list.
77 The following example provides a simple template, see at the end for
78 different [[#locations_for_apps|Locations for Apps]] and look for
79 [[https://github.com/search?utf8=%E2%9C%93&q=repo%3Aopenwrt%2Fpackages
80 +extension%3Alocations&type=Code&ref=advsearch&l=&l=|
81 other packages using a .locations file]], too:
82 <code nginx ${CONF_DIR}example.locations>
84 access_log off; # default: not logging accesses.
85 # access_log /proc/self/fd/1 openwrt; # use logd (init forwards stdout).
86 # error_log stderr; # default: logging to logd (init forwards stderr).
87 error_log /dev/null; # disable error logging after config file is read.
88 # (state path of a file for access_log/error_log to the file instead.)
91 # location /eg/static { … }
94 All location blocks in all ''.locations'' files must use different URLs,
95 since they are all included in the ''${LAN_NAME}.conf'' that is part of the
96 [[#openwrt_s_defaults|OpenWrt’s Defaults]].
97 We reserve the ''location /'' for making LuCI available under the root URL,
98 e.g. [[http://192.168.1.1/|192.168.1.1/]].
99 All other sites shouldn’t use the root ''location /'' without suffix.
100 We can make other sites available on the root URL of other domain names, e.g.
102 In order to do that, we create a ''.conf'' file for every domain name:
103 see the next section [[#new_server_parts|New Server Parts]].
104 For Nginx with SSL we can also activate SSL there, as described below in the
105 section [[#ssl_server_parts|SSL Server Parts]].
106 We use such server parts also for publishing sites to the internet (WAN)
107 instead of making them available just in the LAN.
109 Via ''.conf'' files we can also add directives to the //http// part of the
110 configuration. The difference to editing the main ''${NGINX_CONF}''
111 file instead is the following: If the package’s ''nginx.conf'' file is updated
112 it will only be installed if the old file has not been changed.
116 ==== New Server Parts ====${MSG}
119 For making the router reachable from the WAN at a registered domain name,
120 it is not enough to give the name server the internet IP address of the router
121 (maybe updated automatically by a
122 [[docs:guide-user:services:ddns:client|DDNS Client]]).
123 We also need to set up virtual hosting for this domain name by creating an
124 appropriate server part in a ''${CONF_DIR}*.conf'' file.
125 All such files are included at the start of Nginx by the default main
126 configuration of OpenWrt ''${NGINX_CONF}'' as depicted in
127 [[#openwrt_s_defaults|OpenWrt’s Defaults]].
129 In the server part, we state the domain as
130 [[https://nginx.org/en/docs/http/ngx_http_core_module.html#server_name|
132 The link points to the same document as for the location blocks in the
133 [[#basic|Basic Configuration]]: the official documentation for all available
134 directives of the HTTP core of Nginx.
135 This time look for //server// in the Context list, too.
136 The server part should also contain similar location blocks as before.
137 We can re-include a ''.locations'' file that is included in the server part for
139 Then the site is reachable under the same path at both domains, e.g., by
140 http://192.168.1.1/ex/am/ple as well as by http://example.com/ex/am/ple.
142 The [[#openwrt_s_defaults|OpenWrt’s Defaults]] include a ''${LAN_NAME}.conf''
143 file containing a server part that listens on the LAN address(es) and acts as
145 For making the domain name accessible in the LAN, too, the corresponding
146 server part must listen **explicitly** on the local IP address(es), cf. the
147 official documentation on
148 [[https://nginx.org/en/docs/http/request_processing.html|request_processing]].
149 We can include the file ''${LAN_LISTEN}'' that contains the listen
150 directives for all LAN addresses on the HTTP port 80 and is automatically
153 The following example is a simple template, see
154 [[https://github.com/search?q=repo%3Aopenwrt%2Fpackages
155 +include+${LAN_LISTEN}+extension%3Aconf&type=Code|
156 such server parts of other packages]], too:
157 <code nginx ${CONF_DIR}${EXAMPLE_COM}.conf>
161 include '${LAN_LISTEN}';
162 server_name ${EXAMPLE_COM};
163 # location / { … } # root location for this server.
164 include '${CONF_DIR}${EXAMPLE_COM}.locations';
170 ==== SSL Server Parts ====${MSG}
173 We can enable HTTPS for a domain if Nginx is installed with SSL support.
174 We need a SSL certificate as well as its key and add them by the directives
175 //ssl_certificate// respective //ssl_certificate_key// to the server part of the
177 The rest of the configuration is similar as described in the previous section
178 [[#new_server_parts|New Server Parts]],
179 we only have to adjust the listen directives by adding the //ssl// parameter,
180 see the official documentation for
181 [[https://nginx.org/en/docs/http/configuring_https_servers.html|
182 configuring HTTPS servers]], too.
183 For making the domain available also in the LAN, we can include the file
184 ''${LAN_SSL_LISTEN}'' that contains the listen directives with ssl
185 parameter for all LAN addresses on the HTTPS port 443 and is automatically
188 The official documentation of the SSL module contains an
189 [[https://nginx.org/en/docs/http/ngx_http_ssl_module.html#example|
191 which includes some optimizations.
192 The following template is extended similarly, see also
193 [[https://github.com/search?q=repo%3Aopenwrt%2Fpackages
194 +include+${LAN_SSL_LISTEN}+extension%3Aconf&type=Code|
195 other packages providing SSL server parts]]:
196 <code nginx ${CONF_DIR}${EXAMPLE_COM}>
200 include '${LAN_SSL_LISTEN}';
201 server_name ${EXAMPLE_COM};
202 ssl_certificate '${CONF_DIR}${EXAMPLE_COM}.crt';
203 ssl_certificate_key '${CONF_DIR}${EXAMPLE_COM}.key';
204 ssl_session_cache ${SSL_SESSION_CACHE_ARG};
205 ssl_session_timeout ${SSL_SESSION_TIMEOUT_ARG};
206 # location / { … } # root location for this server.
207 include '${CONF_DIR}${EXAMPLE_COM}.locations';
211 For creating a certificate (and its key) we can use Let’s Encrypt by installing
212 [[https://github.com/Neilpang/acme.sh|ACME Shell Script]]:
213 <code>opkg update && opkg install acme # and for LuCI: luci-app-acme</code>
215 For the LAN server in the ''${LAN_NAME}.conf'' file, the init script
216 ''/etc/init.d/nginx'' script installs automatically a self-signed certificate.
217 We can use this mechanism also for other sites by issuing, e.g.:
218 <code>$(basename ${NGINX_UTIL}) ${ADD_SSL_FCT} ${EXAMPLE_COM}</code>
219 - It adds SSL directives to the server part of \
220 ''${CONF_DIR}${EXAMPLE_COM}.conf'' like in the example above.
221 - Then, it checks if there is a certificate and key for the given domain name\
222 that is valid for at least 13 months or tries to create a self-signed one.
223 - When cron is activated, it installs a cron job for renewing the self-signed\
224 certificate every year if needed, too. We can activate cron by: \
225 <code>service cron enable && service cron start</code>
227 Beside the ''${LAN_NAME}.conf'' file, the
228 [[#openwrt_s_defaults|OpenWrt’s Defaults]] include also the
229 ''_redirect2ssl.conf'' file containing a server part that redirects all HTTP
230 request for inexistent URIs to HTTPS.
234 ==== OpenWrt’s Defaults ====${MSG}
237 The default main configuration file is:
238 $(code ${NGINX_CONF})
240 We can pretend the main configuration contains also the following presets,
241 since Nginx is configured with them:
242 <code nginx>$(ifConfEcho --pid-path pid)\
243 $(ifConfEcho --lock-path lock_file)\
244 $(ifConfEcho --error-log-path error_log)\
245 $(false && ifConfEcho --http-log-path access_log)\
246 $(ifConfEcho --http-proxy-temp-path proxy_temp_path)\
247 $(ifConfEcho --http-client-body-temp-path client_body_temp_path)\
248 $(ifConfEcho --http-fastcgi-temp-path fastcgi_temp_path)\
251 So, the access log is turned off by default and we can look at the error log
252 by ''logread'', as Nginx’s init file forwards stderr and stdout to the
253 [[docs:guide-user:base-system:log.essentials|logd]].
254 We can set the //error_log// and //access_log// to files where the log
255 messages are forwarded to instead (after the configuration is read).
256 And for redirecting the access log of a //server// or //location// to the logd,
257 too, we insert the following directive in the corresponding block:
259 access_log /proc/self/fd/1 openwrt;
262 At the end, the main configuration pulls in all ''.conf'' files from the
263 directory ''${CONF_DIR}'' into the http block, especially the following
264 server part for the LAN:
265 $(code ${CONF_DIR}${LAN_NAME}.conf)
267 It pulls in all ''.locations'' files from the directory ''${CONF_DIR}''.
268 We can install the location parts of different sites there (see above in the
269 [[#basic|Basic Configuration]]) and re-include them in server parts of other
270 ''${CONF_DIR}*.conf'' files.
271 This is needed especially for making them available to the WAN as described
272 above in the section [[#new_server_parts|New Server Parts]].
273 All ''.locations'' become available on the LAN through the file
274 ''$(basename ${LAN_LISTEN}).default'', which contains one of the following
275 directives for every local IP address:
277 listen IPv4:80 default_server;
278 listen [IPv6]:80 default_server;
280 The ''${LAN_LISTEN}'' file contains the same directives without the
281 parameter ''default_server''.
282 We can include this file in other server parts that should be reachable in the
283 LAN through their //server_name//.
284 Both files ''${LAN_LISTEN}{,.default}'' are (re-)created if Nginx starts
285 through its init for OpenWrt or the LAN interface changes.
287 === Additional Defaults for OpenWrt if Nginx is installed with SSL support ===
289 When Nginx is installed with SSL support, there will be automatically managed
290 files ''$(basename ${LAN_SSL_LISTEN}).default'' and
291 ''$(basename ${LAN_SSL_LISTEN})'' in the directory
292 ''$(dirname ${LAN_SSL_LISTEN})/'' containing the following directives for all
293 IPv4 and IPv6 addresses of the LAN:
295 listen IP:443 ssl; # with respectively without: default_server
297 Both files as well as the ''${LAN_LISTEN}{,.default}'' files are (re-)created
298 if Nginx starts through its init for OpenWrt or the LAN interface changes.
300 For Nginx with SSL there is also the following server part that redirects
301 requests for an inexistent ''server_name'' from HTTP to HTTPS (using an invalid
302 name, more in the official documentation on
303 [[https://nginx.org/en/docs/http/request_processing.html|request_processing]]):
304 $(code ${CONF_DIR}_redirect2ssl.conf)
306 Nginx’s init file for OpenWrt installs automatically a self-signed certificate
307 for the LAN server part if needed and possible:
308 - Everytime Nginx starts, we check if the LAN is set up for SSL.
309 - We add //ssl*// directives (like in the example of the previous section \
310 [[#ssl_server_parts|SSL Server Parts]]) to the configuration file \
311 ''${CONF_DIR}${LAN_NAME}.conf'' if needed and if it looks “normal”, i.e., \
312 it has a ''server_name ${LAN_NAME};'' part.
313 - If there is no corresponding certificate that is valid for more than 13 \
314 months at ''${CONF_DIR}${LAN_NAME}.{crt,key}'', we create a self-signed one.
315 - We activate SSL by including the ssl listen directives from \
316 ''${LAN_SSL_LISTEN}.default'' and it becomes available by the default \
317 redirect from ''listen *:80;'' in ''${CONF_DIR}_redirect2ssl.conf''
318 - If cron is available, i.e., its status is not ''inactive'', we use it \
319 to check the certificate for validity once a year and renew it if there \
320 are only about 13 months of the more than 3 years life time left.
322 The points 2, 3 and 5 can be used for other domains, too:
323 As described in the section [[#new_server_parts|New Server Parts]] above, we
324 create a server part in ''${CONF_DIR}www.example.com.conf'' with
325 a corresponding ''server_name www.example.com;'' directive and call
326 <code>$(basename ${NGINX_UTIL}) ${ADD_SSL_FCT} www.example.com</code>