Clean up and prepare docs for v3
This commit is contained in:
Léo Colombaro
parent
92a1c5df93
commit
51f5ffab82
40
README.md
40
README.md
|
|
@ -10,9 +10,40 @@ accessible, if needed, even cross-domain.
|
|||
|
||||
## 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 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
|
||||
|
||||
|
|
@ -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
|
||||
expires headers, allow cross domain fonts and protect system files from web
|
||||
access.
|
||||
The `basic.conf` file includes the rules which are recommended to always be
|
||||
defined.
|
||||
|
||||
* **`location/`**
|
||||
|
||||
|
|
@ -71,11 +104,6 @@ This repository has the following structure:
|
|||
|
||||
The main nginx config file.
|
||||
|
||||
### Other resources
|
||||
|
||||
* [Troubleshooting](docs/troubleshooting.md) — Dealing with commonly-encountered errors.
|
||||
* [Hotlink protection](docs/hotlink-protection.md)
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue