From 51f5ffab8265e2cf64ef88916254dee3944ffb54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9o=20Colombaro?= Date: Tue, 12 Feb 2019 12:25:30 +0100 Subject: [PATCH] Clean up and prepare docs for v3 --- README.md | 40 ++++++- docs/getting-started.md | 76 ------------- docs/hotlink-protection.md | 57 ---------- docs/troubleshooting.md | 224 ------------------------------------- h5bp/README.md | 7 -- 5 files changed, 34 insertions(+), 370 deletions(-) delete mode 100644 docs/getting-started.md delete mode 100644 docs/hotlink-protection.md delete mode 100644 docs/troubleshooting.md delete mode 100644 h5bp/README.md diff --git a/README.md b/README.md index 80cd668..9d28b70 100644 --- a/README.md +++ b/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 diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index c568a73..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -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 diff --git a/docs/hotlink-protection.md b/docs/hotlink-protection.md deleted file mode 100644 index 915a276..0000000 --- a/docs/hotlink-protection.md +++ /dev/null @@ -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 diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md deleted file mode 100644 index d4b182e..0000000 --- a/docs/troubleshooting.md +++ /dev/null @@ -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 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. diff --git a/h5bp/README.md b/h5bp/README.md deleted file mode 100644 index f32e966..0000000 --- a/h5bp/README.md +++ /dev/null @@ -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.