gaja-group
/
server-configs-nginx
mirror of https://github.com/h5bp/server-configs-nginx
2
0
Fork 0
Code Issues Releases Wiki Activity

Clean up and prepare docs for v3

This commit is contained in:
Léo Colombaro 2019-02-12 12:25:30 +01:00
parent 92a1c5df93
commit 51f5ffab82
No known key found for this signature in database
GPG Key ID: 687B480A6D4F735F
5 changed files with 34 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@ -10,9 +10,40 @@ accessible, if needed, even cross-domain.
## Getting Started ## Getting Started
Using the Nginx server configs repo directly has a few required steps to be able to work.
* [Nginx Beginners Guide](https://nginx.org/en/docs/beginners_guide.html) * [Nginx Beginners Guide](https://nginx.org/en/docs/beginners_guide.html)
* [Nginx Request Processing](https://nginx.org/en/docs/http/request_processing.html) * [Nginx Request Processing](https://nginx.org/en/docs/http/request_processing.html)
* [How Nginx works](docs/getting-started.md) — Understanding nginx, and how it differs from other webservers.
### Check `nginx.conf` settings
The first thing to check is that the `nginx.conf` file contains appropriate values for
your specific install.
Most specific variables are:
* `user`
* `error_log`
* `pid`
* `access_log`
### Nginx test and restart
* To verify Nginx config
```shell
$ nginx -t
```
* To verify Nginx config with a custom file
```shell
$ nginx -t -c nginx.conf
```
* To reload Nginx and apply new config
```shell
$ nginx reload
```
### Basic structure ### Basic structure
@ -56,6 +87,8 @@ This repository has the following structure:
This file loads a small subset of the rules provided by this repository to add This file loads a small subset of the rules provided by this repository to add
expires headers, allow cross domain fonts and protect system files from web expires headers, allow cross domain fonts and protect system files from web
access. access.
The `basic.conf` file includes the rules which are recommended to always be
defined.
* **`location/`** * **`location/`**
@ -71,11 +104,6 @@ This repository has the following structure:
The main nginx config file. The main nginx config file.
### Other resources
* [Troubleshooting](docs/troubleshooting.md) — Dealing with commonly-encountered errors.
* [Hotlink protection](docs/hotlink-protection.md)
## Usage ## Usage

76
docs/getting-started.md
View File

@ -1,76 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
# Getting started
Using the Nginx server configs repo directly has a few required steps to be able to work.
## Check `nginx.conf` settings
The first thing to check is that the `nginx.conf` file contains appropriate values for
your specific install. The web user varies with distribution, in most cases compare to
the config file originally present, and use the same user:
// /etc/nginx-original/nginx.conf
user www-data www-data;
Apply to the runtime config file:
// /etc/nginx/nginx.conf
#user www www;
user www-data www-data;
## Configure logs and pid file
The location of logs also varies from system to system. To account for this the `nginx.conf`
file uses a relative path for logs:
// /etc/nginx/nginx.conf
error_log logs/error.log warn;
There are two options to configure this appropriately, change the path to point at the folder
where logs should be stored:
// /etc/nginx/nginx.conf
error_log /var/log/nginx/error.log warn;
Or, setup a symlink to point at the right place:
cd /etc/nginx
ln -s /var/log/nginx logs
The location of the pid file should also be checked and corrected if necessary.
Check your config before trying to start nginx:
nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
If you see:
nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: [emerg] open() "/usr/share/nginx/log/access.log" failed (2: No such file or directory)
nginx: configuration file /etc/nginx/nginx.conf test failed
Or similar, there is still a problem to resolve before continuing.
## Verify config and restart nginx
Verify the config and restart nginx to apply the changes.
To verify nginx config (Tests default nginx config file)
nginx -t
**OR**
To verify a particular nginx config file
nginx -t -c nginx.conf
This will test the nginx config file and throws error if any. Otherwise test is successful and you can restart nginx.
Finally reload nginx to apply the changes.
nginx reload

57
docs/hotlink-protection.md
View File

@ -1,57 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
# Hotlink Protection
Depending on how sensitive assets are, nginx offers a few options for protecting
assets.
## valid_referers
the simplest way to protect assets from hotlinking is to use
[valid_referers](https://nginx.org/en/docs/http/ngx_http_referer_module.html).
It's easy to use, this would be included in a relevant location block:
valid_referers none blocked example.com *.example.com;
if ($invalid_referer) {
return 403;
}
## secure_link
The [secure_link module](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html)
provides a flexible, more robust means of protecting assets from being hotlinked or
downloaded outside from outside the web itself.
It is more involved to setup and use but, for example, permits time limited and
IP-restricted (or restricted on any other parameter desired) links to assets.
Example nginx config:
secure_link $arg_md5,$arg_expires;
secure_link_md5 "$secure_link_expires$uri$remote_addr secret";
if ($secure_link = "") {
# No get args, or invalid hash
return 403;
}
if ($secure_link = "0") {
# valid hash, but the link is now expired
return 410;
}
if ($secure_link = "1") {
# valid hash, and link is still fresh
...
}
This requires implementing server-side logic to generate links of the form:
https://example.com/protected/url.ext?md5=hash&expires=timestamp
where:
hash = md5({timestamp}/protected/url.ext{clientip} secret)
"secret" should be application-specific and needs to match in the nginx config,
and the function used to generate these secure urls

224
docs/troubleshooting.md
View File

@ -1,224 +0,0 @@
[Nginx Server Configs homepage](https://github.com/h5bp/server-configs-nginx)
# Troubleshooting
## types_hash errors
Depending on the server architecture, it's possible to get the following error:
> could not build the types_hash, you should increase either
> types_hash_max_size: 1024 or types_hash_bucket_size: 32
Nginx uses [hash tables](https://nginx.org/en/docs/hash.html) to speed up certain
tasks, usually the default value is sufficient but depending on the actual server
config this error might be encountered. The solution is to do exactly what the
error message suggests, by adding to nginx.conf the following:
# add this to the http context
types_hash_max_size: 1024;
## OR add this to the http context, don't need both
# types_hash_bucket_size: 32
## Only some rules are being applied
Nginx only uses one location block when processing a request.
A direct concequence of this is that if, either directly or via include
statemtents, directives are defined like so:
# Make sure js files are served with a long expire
location ~* \.js$ {
add_header "section" "long expire"; # for illustration only
add_header Cache-Control "max-age=31536000";
}
# Oh, and kill etags for js files
location ~* \.js$ {
add_header "section" "no etags"; # for illustration only
etag off;
}
_the section headers are only to demonstrate which location blocks applied to a
particular request_.
Only ONE of these location blocks will be used:
$ curl -I "http://nginx.h5bp.dev/js/main.js"
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Oct 2014 09:58:47 GMT
Content-Type: application/javascript; charset=utf-8
Content-Length: 1
Last-Modified: Tue, 29 Oct 2013 15:17:17 GMT
Connection: keep-alive
ETag: "526fd17d-1"
Cache-Control: max-age=31536000
section: long expire
Accept-Ranges: bytes
The way to achieve the desired effect is to consolidate all rules into one
location block:
location ~* \.js$ {
# Make sure js files are served with a long expire
add_header "section" "long expire"; # for illustration only
add_header Cache-Control "max-age=31536000";
add_header "section" "no etags"; # for illustration only
etag off;
}
Which would then yield:
$ curl -I "http://nginx.h5bp.dev/js/main.js"
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Oct 2014 10:00:22 GMT
Content-Type: application/javascript; charset=utf-8
Content-Length: 1
Last-Modified: Tue, 29 Oct 2013 15:17:17 GMT
Connection: keep-alive
Cache-Control: max-age=31536000
section: long expire
section: no etags
Accept-Ranges: bytes
## Cannot dynamically serve <file extension> requests
It might be expected that a request for a file that does not exist
will always reach the backend application - but this is not necessarily
the case.
Using php as an example, here is a simple example config:
server {
listen 80;
server_name example.com;
root /var/www/example.com;
location / {
try_files $uri $uri/ /index.php;
}
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
With the above config, a request for `/css/main.css`, assuming the file exists,
would be served directly by nginx whereas a request for `/application/user.css`
would be processed by php.
It is tempting to add h5bp's basic ruleset by simply appending it in
the server context:
server {
listen 80;
server_name example.com;
root /var/www/example.com;
location / {
try_files $uri $uri/ /index.php;
}
location ~ [^/]\.php(/|$) {
fastcgi_split_path_info ^(.+?\.php)(/.*)$;
if (!-f $document_root$fastcgi_script_name) {
return 404;
}
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
}
# ADDED
include h5bp/basic.conf;
}
The result in this case would be `/css/main.css`, assuming the file exists,
is served with headers defined by h5bp's basic ruleset whereas `/application/user.css`
will be a 404. The reason for this is that H5bp's basic ruleset includes, for example:
location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc)$ {
expires 1M;
access_log off;
}
Which will _also_ capture any dynamic requests matching that url pattern and not
hand the request to the php application in the event of an error.
There are 3 basic strategies to resolve this:
## Define error_page in each location block
Modifying (all) location blocks as follows:
location ~* \.(?:jpg|jpeg|gif|png|ico|cur|gz|svg|svgz|mp4|ogg|ogv|webm|htc)$ {
error_page 404 = /index.php;
expires 1M;
access_log off;
}
Will make Nginx pass requests for files that don't exist to the application.
## Use prefix routing
Prefix routing is always preferred - if there is a common path for static files
this can be used to reduce the scope of any included rules:
server {
listen 80;
server_name example.com;
root /var/www/example.com;
location / {
try_files $uri $uri/ /index.php;
}
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
# ADDED. Apply only to the css, js and images folder
location ~ ^/(css|images|js)/ {
include h5bp/basic.conf;
}
}
## Change to use a 404 front-controller
Instead of using try_files alone, change the server config such that the
application is the 404 page:
server {
listen 80;
server_name example.com;
root /var/www/example.com;
try_files $uri $uri/ @app;
error_page 404 = @app;
location @app {
include fastcgi_params;
fastcgi_pass 127.0.0.1:9000;
fastcgi_param SCRIPT_FILENAME $document_root/index.php;
fastcgi_param SCRIPT_NAME $document_root/index.php;
fastcgi_param DOCUMENT_URI /index.php;
fastcgi_index index.php;
}
# ADDED.
include h5bp/basic.conf;
}
_with this kind of setup it's necessary to explicitly define the php filename_.
In this way after nginx has tried to serve a (none existant) static file, it
will pass the request to the php application successfully.

7
h5bp/README.md
View File

@ -1,7 +0,0 @@
Component-config files
----------------------
Each of these files is intended to be included in a server block. Not all of
the files here are used - they are available to be included as required. The
`basic.conf` file includes the rules which are recommended to always be
defined.