Skip to content

Commit c15a59a

Browse files
JonasAlfredssonJonasAlfredsson
committed
Update documentation
1 parent 2a13ddc commit c15a59a

File tree

3 files changed

+151
-69
lines changed

3 files changed

+151
-69
lines changed

‎README.md

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -153,21 +153,16 @@ COPY conf.d/* /etc/nginx/conf.d/
153153
Here is a collection of links to other resources that provide useful
154154
information.
155155

156-
#### Good to Know
157-
[Document](./docs/good_to_know.md) with a lot of good to know stuff about this
158-
image and the features it provides.
159-
160-
#### Changelog
161-
[Document](./docs/changelog.md) with all the tagged versions of this repository,
162-
as well as bullet points to what has changed between the releases.
163-
164-
#### DockerHub Tags
165-
[Document](./docs/dockerhub_tags.md) with all the tags available from Docker
166-
Hub.
167-
168-
#### Advanced Usage
169-
[Document](./docs/advanced_usage.md) with information about the more advanced
170-
features this image provides.
156+
- [Good to Know](./docs/good_to_know.md)
157+
- A lot of good to know stuff about this image and the features it provides.
158+
- [Changelog](./docs/changelog.md)
159+
- List of all the tagged versions of this repository, as well as bullet points to what has changed between the releases.
160+
- [DockerHub Tags](./docs/dockerhub_tags.md)
161+
- All the tags available from Docker Hub.
162+
- [Advanced Usage](./docs/advanced_usage.md)
163+
- Information about the more advanced features this image provides.
164+
- [Nginx Tips](./docs/nginx_tips.md)
165+
- Some interesting tips on how Nginx can be configured.
171166

172167

173168

‎docs/advanced_usage.md

Lines changed: 0 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -187,57 +187,6 @@ and you may of course take a look at the commands used in the
187187
way of creating your own files.
188188

189189

190-
## Reject Unknown Server Name
191-
When setting up server blocks there exist a setting called `default_server`,
192-
which means that Nginx will use this server block in case it cannot match
193-
the incoming domain name with any of the other `server_name`s in its available
194-
config files. However, a less known fact is that if you do not specify a
195-
`default_server` Nginx will automatically use the [first server block][20] in
196-
its configuration files as the default server.
197-
198-
This might cause confusion as Nginx could now "accidentally" serve a
199-
completely wrong site without the user knowing it. Luckily HTTPS removes some
200-
of this worry, since the browser will most likely throw an
201-
`SSL_ERROR_BAD_CERT_DOMAIN` if the returned certificate is not valid for the
202-
domain that the browser expected to visit. But if the cert is valid for that
203-
domain as well, then there will be problems.
204-
205-
If you want to guard yourself against this, and return an error in the case
206-
that the client tries to connect with an unknown server name, you need to
207-
configure a catch-all block that responds in the default case. This is simple
208-
in the non-SSL case, where you can just return `444` which will terminate the
209-
connection immediately.
210-
211-
```
212-
server {
213-
listen 80 default_server;
214-
server_name _;
215-
return 444;
216-
}
217-
```
218-
219-
> NOTE: The [redirector.conf](../src/nginx_conf.d/redirector.conf) should be
220-
the `default_server` for port 80 in this image.
221-
222-
Unfortunately it is not as simple in the secure HTTPS case, since Nginx would
223-
first need to perform the SSL handshake (which needs a valid certificate)
224-
before it can respond with `444` and drop the connection. To work around this
225-
I found a comment in [this][18] post which mentions that in version `>=1.19.4`
226-
of Nginx you can actually use the [`ssl_reject_handshake`][19] feature to
227-
achieve the same functionality.
228-
229-
```
230-
server {
231-
listen 443 ssl default_server;
232-
ssl_reject_handshake on;
233-
}
234-
```
235-
236-
This will lead to an `SSL_ERROR_UNRECOGNIZED_NAME_ALERT` error in case the
237-
client tries to connect over HTTPS to a server name that is not served by this
238-
instance of Nginx, and the connection will be dropped immediately.
239-
240-
241190

242191

243192

@@ -259,6 +208,3 @@ instance of Nginx, and the connection will be dropped immediately.
259208
[15]: https://derflounder.wordpress.com/2019/06/06/new-tls-security-requirements-for-ios-13-and-macos-catalina-10-15/
260209
[16]: https://superuser.com/questions/738612/openssl-ca-keyusage-extension/1248085#1248085
261210
[17]: https://www.feistyduck.com/library/openssl-cookbook/online/ch-openssl.html
262-
[18]: https://serverfault.com/a/631073
263-
[19]: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake
264-
[20]: https://nginx.org/en/docs/http/request_processing.html

‎docs/nginx_tips.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Nginx Tips
2+
3+
This docuemnt contains some tips on how Nginx can be modified in some different
4+
ways that might be of interest. None of these are required to do, but are more
5+
of nice to know information that I found useful to write down for any potential
6+
future endeavor.
7+
8+
9+
## How Nginx Loads Configs
10+
To understand how Nginx loads any custom configurations we first have to take
11+
a look on the main `nginx.conf` file from the parent image. It has a couple of
12+
standard settings included, but on the last line we can se that it opens the
13+
`/etc/nginx/conf.d/` folder and loads any file that ends with `.conf`.
14+
15+
```conf
16+
user nginx;
17+
worker_processes auto;
18+
19+
error_log /var/log/nginx/error.log notice;
20+
pid /var/run/nginx.pid;
21+
22+
events {
23+
worker_connections 1024;
24+
}
25+
26+
http {
27+
include /etc/nginx/mime.types;
28+
default_type application/octet-stream;
29+
30+
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
31+
'$status $body_bytes_sent "$http_referer" '
32+
'"$http_user_agent" "$http_x_forwarded_for"';
33+
34+
access_log /var/log/nginx/access.log main;
35+
36+
sendfile on;
37+
#tcp_nopush on;
38+
39+
keepalive_timeout 65;
40+
41+
#gzip on;
42+
43+
include /etc/nginx/conf.d/*.conf; # <------------ Extra stuff loaded here
44+
}
45+
```
46+
47+
Files in this folder are being loaded in alphabetical order, so something named
48+
`00-proxy.conf` will be loaded before `10-other.conf`. This i really useful to
49+
know, since it allows you to load common settings used by multiple `server`
50+
blocks that are loaded afterwards.
51+
52+
However, all of these `.conf` file are loaded within the `http` block in Nginx,
53+
so if you want to change anything outside of this block (e.g. `events`) you
54+
will have to add some sort of [`/docker-entrypoint.d/`][7] script to handle it
55+
before Nginx starts, or you can mount your own custom `nginx.conf` on top of
56+
the default.
57+
58+
A small disclaimer on the last part is that a host mounted file
59+
(`-v $(pwd)/nginx.conf:/etc/nginx/nginx.conf`) will [not change][8] inside the
60+
container if it is changed on the host. However, if you host mount a directory,
61+
and change any of the files within it, the changes will be visible inside the
62+
container.
63+
64+
65+
## Reject Unknown Server Name
66+
When setting up server blocks there exist a setting called `default_server`,
67+
which means that Nginx will use this server block in case it cannot match
68+
the incoming domain name with any of the other `server_name`s in its available
69+
config files. However, a less known fact is that if you do not specify a
70+
`default_server` Nginx will automatically use the [first server block][1] in
71+
its configuration files as the default server.
72+
73+
This might cause confusion as Nginx could now "accidentally" serve a
74+
completely wrong site without the user knowing it. Luckily HTTPS removes some
75+
of this worry, since the browser will most likely throw an
76+
`SSL_ERROR_BAD_CERT_DOMAIN` if the returned certificate is not valid for the
77+
domain that the browser expected to visit. But if the cert is valid for that
78+
domain as well, then there will be problems.
79+
80+
If you want to guard yourself against this, and return an error in the case
81+
that the client tries to connect with an unknown server name, you need to
82+
configure a catch-all block that responds in the default case. This is simple
83+
in the non-SSL case, where you can just return `444` which will terminate the
84+
connection immediately.
85+
86+
```
87+
server {
88+
listen 80 default_server;
89+
server_name _;
90+
return 444;
91+
}
92+
```
93+
94+
> NOTE: The [redirector.conf](../src/nginx_conf.d/redirector.conf) should be
95+
the `default_server` for port 80 in this image.
96+
97+
Unfortunately it is not as simple in the secure HTTPS case, since Nginx would
98+
first need to perform the SSL handshake (which needs a valid certificate)
99+
before it can respond with `444` and drop the connection. To work around this
100+
I found a comment in [this][2] post which mentions that in version `>=1.19.4`
101+
of Nginx you can actually use the [`ssl_reject_handshake`][3] feature to
102+
achieve the same functionality.
103+
104+
```
105+
server {
106+
listen 443 ssl default_server;
107+
ssl_reject_handshake on;
108+
}
109+
```
110+
111+
This will lead to an `SSL_ERROR_UNRECOGNIZED_NAME_ALERT` error in case the
112+
client tries to connect over HTTPS to a server name that is not served by this
113+
instance of Nginx, and the connection will be dropped immediately.
114+
115+
116+
## Add Custom Module
117+
Adding a [custom module][4] to Nginx is not enirely trivial, since most guides
118+
I have found require you to re-complie everything with the desired module
119+
included and thus you cannot make use of the official Docker image to build
120+
upon. However, after some research I found that most of these modules are
121+
possible to compile and load as a [dynamic module][5], which enables us to more
122+
or less just add one file and then change one line in the main `nginx.conf`.
123+
124+
A complete example of how to do this is available over at
125+
[AxisCommunications/docker-nginx-ldap][6], where a multi-stage Docker build
126+
can be viewed that add the LDAP module to the official Nginx image with
127+
minimal changes to the original.
128+
129+
130+
131+
132+
133+
134+
[1]: https://nginx.org/en/docs/http/request_processing.html
135+
[2]: https://serverfault.com/a/631073
136+
[3]: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_reject_handshake
137+
[4]: https://www.nginx.com/resources/wiki/modules/
138+
[5]: https://www.nginx.com/blog/compiling-dynamic-modules-nginx-plus/
139+
[6]: https://github.com/AxisCommunications/docker-nginx-ldap
140+
[7]: https://github.com/nginxinc/docker-nginx/tree/master/entrypoint
141+
[8]: hhttps://medium.com/@jonsbun/why-need-to-be-careful-when-mounting-single-files-into-a-docker-container-4f929340834

0 commit comments

Comments
 (0)