diff --git a/docs/security/ssl/create-a-self-signed-tls-certificate.md b/docs/security/ssl/create-a-self-signed-tls-certificate.md index f8b298a9615..87c8bb4502d 100644 --- a/docs/security/ssl/create-a-self-signed-tls-certificate.md +++ b/docs/security/ssl/create-a-self-signed-tls-certificate.md @@ -2,11 +2,11 @@ author: name: Linode email: docs@linode.com -description: 'This guide will show you a brief command to create a self-signed TLS certificate with OpenSSL.' +description: 'This guide shows how to create a self-signed TLS certificate with OpenSSL.' keywords: ["ssl", "tls", "https", "certificate", "self"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['security/ssl/create-a-self-signed-certificate-on-centos-and-fedora/','security/ssl/create-a-self-signed-certificate-on-debian-and-ubuntu/','security/ssl/how-to-make-a-selfsigned-ssl-certificate/'] -modified: 2018-01-09 +modified: 2018-01-23 modified_by: name: Linode published: 2018-01-09 @@ -15,10 +15,13 @@ title: 'Create a Self-Signed TLS Certificate' ![Create a Self-Signed Certificate title graphic](/docs/assets/create-a-self-signed-tls-certificate-title-graphic.jpg "Create a Self-Signed Certificate title graphic") -Self-signed TLS certificates are suitable for personal use or applications used internally within an organization. If you intend to use your SSL certificate on a website served by Apache or NGINX, see our guides for doing that (Apache, [NGINX](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/x)) once you’ve completed the process outlined here. +## What is a Self-Signed TLS Certificate? +Self-signed TLS certificates are suitable for personal use or for applications that are used internally within an organization. If you intend to use your SSL certificate on a website, see our guide on enabling TLS for [NGINX](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/) once you’ve completed the process outlined in this guide. -1. Change users to the `root` user and change directories to where you want to create the certificate and key pair. That location will vary depending on your end use. Here we'll use `/root/certs`. +## Create the Certificate + +1. Change to the `root` user and change to the directory in which you want to create the certificate and key pair. That location will vary depending on your needs. Here we'll use `/root/certs`: su - root mkdir /root/certs && cd /root/certs @@ -27,7 +30,19 @@ Self-signed TLS certificates are suitable for personal use or applications used openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out MyCertificate.crt -keyout MyKey.key - After entering the command, you will be prompted to add identifying information for your website or organization to the certificate. Since a self-signed cert won't be used publicly, this information isn't necessary. However, if this certificate were being created to be passed on to a certificate authority for signing, the information would need to be as accurate as possible. + You will be prompted to add identifying information about your website or organization to the certificate. Since a self-signed certificate won't be used publicly, this information isn't necessary. If this certificate will be passed on to a certificate authority for signing, the information needs to be as accurate as possible. + + The following is a breakdown of the OpenSSL options used in this command. There are many other options available, but these will create a basic certificate which will be good for a year. For more information, see `man openssl` in your terminal. + + * `-newkey rsa:4096`: Create a 4096 bit RSA key for use with the certificate. `RSA 2048` is the default on more recent versions of OpenSSL but to be sure of the key size, you should specify it during creation. + + * `-x509`: Create a self-signed certificate. + + * `-sha256`: Generate the certificate request using 265-bit SHA (Secure Hash Algorithm). + + * `-days`: Determines the length of time in days that the certificate is being issued for. For a self-signed certificate, this value can be increased as necessary. + + * `-nodes`: Create a certificate that does not require a passphrase. If this option is excluded, you will be required to enter the passphrase in the console each time the application using it is restarted. Here is an example of the output: @@ -54,18 +69,6 @@ Common Name (e.g. server FQDN or YOUR name) []:hostname.example.com Email Address []:admin@example.com {{< /output >}} - Here's a breakdown of the OpenSSL options used in that command. There are many others available, but these will create you something basic which will be good for a year. For more info, see `man openssl` in your terminal. - - * `-newkey rsa:4096` tells OpenSSL to create a 4096 bit RSA key for use with the certificate. RSA 2048 is the default on more recent versions of OpenSSL but to be sure of the key size, you should specify it during creation. - - * `-x509` tells OpenSSL to create a self-signed certificate. - - * `-sha256` generate the certificate request using 265-bit SHA (Secure Hash Algorithm). - - * `-days` determines the length of time in days that the certificate is being issued for. For a self-signed certificate, this value can be increased as necessary. - - * `-nodes` instructs OpenSSL to create a certificate that does not require a passphrase. If this option is excluded, you will be required to enter the passphrase in the console each time the application using it is restarted. - 3. Restrict the key's permissions so that only `root` can access it: chmod 400 /root/certs/MyKey.key diff --git a/docs/security/ssl/obtain-a-commercially-signed-tls-certificate.md b/docs/security/ssl/obtain-a-commercially-signed-tls-certificate.md index d2c7274589d..9c12a4bb6d6 100644 --- a/docs/security/ssl/obtain-a-commercially-signed-tls-certificate.md +++ b/docs/security/ssl/obtain-a-commercially-signed-tls-certificate.md @@ -2,30 +2,34 @@ author: name: Linode email: docs@linode.com -description: 'This guide will show you a brief command to create a self-signed TLS certificate with OpenSSL.' +description: 'This guide shows how to create a commercially-signed TLS certificate with OpenSSL.' keywords: ["ssl", "tls", "https", "certificate", "commercial"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['security/ssl/create-a-self-signed-certificate-on-centos-and-fedora/','security/ssl/create-a-self-signed-certificate-on-debian-and-ubuntu/','security/ssl/obtain-a-commercially-signed-ssl-certificate-on-centos-and-fedora/','security/ssl/obtain-a-commercially-signed-ssl-certificate-on-debian-and-ubuntu/','security/ssl/obtaining-a-commercially-signed-ssl-certificate/'] -modified: 2017-12-20 +modified: 2018-01-23 modified_by: name: Linode published: 2017-12-20 title: 'Obtain a Commercially Signed TLS Certificate' --- +## What is a Commercially Signed TLS Certificate? + If you intend to host a publicly accessible website which will use HTTPS, then you will want to install a commercially signed TLS certificate so people visiting your site don't get warnings in their browser about an unsafe connection. -There are currently two primary ways to do this: The easiest method is to sign your certificate using [Let's Encrypt](https://letsencrypt.org/). The [CertBot](https://certbot.eff.org/) tool makes obtaining and renewing certificates through Let's Encrypt extremely simple. However, this isn't a viable option for everyone. +The easiest method is to sign your certificate using [Let's Encrypt](https://letsencrypt.org/). The [CertBot](https://certbot.eff.org/) tool makes obtaining and renewing certificates through Let's Encrypt extremely simple. However, this isn't a viable option for everyone. + +If you need [Domain Validation](https://en.wikipedia.org/wiki/Domain-validated_certificate) or [Extended Validation certificates](https://en.wikipedia.org/wiki/Extended_Validation_Certificate), you must create a Certificate Signing Request (CSR) for submission to a Certificate Authority (CA) such as Thawte or Verisign. This is the method for obtaining a signed TLS certificate that this guide focuses on. -If you need [Domain Validation](https://en.wikipedia.org/wiki/Domain-validated_certificate) or [Extended Validation certificates](https://en.wikipedia.org/wiki/Extended_Validation_Certificate), you must create a certificate signing request for submission to a certificate authority such as Thawte or Verisign. This is the second method for obtaining a signed TLS certificate, and the one which this guide focuses on. Some CAs allow you to create a CSR directly through their web interface after you register an account with them. That's certainly a usability advantage over manually creating the CSR on your server or local computer as this guide instructs. +Some CAs allow you to create a CSR directly through their web interface after you register an account with them. That's certainly a usability advantage over manually creating the CSR on your server or local computer as this guide instructs. -Research certificate authorities thoroughly before deciding on a company which will be used for things such as protecting customers' personal information via HTTPS, cryptographically signing emails, or granting access to internal platforms. +Research certificate authorities thoroughly before deciding on the company which will be used for things such as protecting customers' personal information via HTTPS, cryptographically signing emails, or granting access to internal platforms. -If you intend to use your SSL certificate on a website served by Apache or NGINX, see our guides for doing that (Apache, [NGINX](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections)) once you’ve completed the process outlined here. +If you intend to use your SSL certificate on a website, see our guide on [Enabling TLS for HTTPS on NGINX](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections) once you’ve completed the process in this guide. ## Create a Certificate Signing Request (CSR) -1. Change users to the `root` user and move to a directory where you want to create the certificate information: +1. Change to the `root` user and move to the directory in which you want to create the certificate information: su - root mkdir /root/certs/ && cd /root/certs/ @@ -34,9 +38,19 @@ If you intend to use your SSL certificate on a website served by Apache or NGINX openssl req -new -newkey rsa:4096 -days 365 -nodes -keyout example.com.key -out example.com.csr - After entering the command, you will be prompted to add identifying information for your website or organization to the certificate. Since this certificate is being created to be passed on to a certificate authority for signing, the information needs to be accurate. + You will be prompted to add identifying information for your website or organization to the certificate. Since this certificate is being created to be passed on to a certificate authority for signing, the information needs to be accurate. + + The following is a breakdown of the OpenSSL options used in this command. There are many other options available, but these will create a basic certificate which will be good for a year. For more information, see `man openssl` in your terminal. + + * `-newkey rsa:4096`: Creates a 4096 bit RSA key for use with the certificate. `RSA 2048` is the default on more recent versions of OpenSSL but to be sure of the key size, you should specify it during creation. + + * `-sha256`: Generates the certificate request using 265-bit SHA (Secure Hash Algorithm). + + * `-days`: Determines the length of time in days that the certificate is being issued for. For a commercial certificate, this value should be no higher than `730` (2 years). - Here is an example of the output. You may safely leave the `extra attributes` blank, just press *Enter* to bypass each one. + * `-nodes`: Creates a certificate that does not require a passphrase. If this option is excluded, you will be required to enter the passphrase in the console each time the application using it is restarted. + + Here is an example of the output. You may safely leave the `extra attributes` blank, just press **Enter** to bypass each one: {{< output >}} root@localhost:~# openssl req -new -newkey rsa:4096 -days 365 -nodes -keyout example.com.key -out example.com.csr @@ -66,37 +80,25 @@ A challenge password []: An optional company name []: {{< /output >}} - Here's a breakdown of the OpenSSL options used in that command. There are many others available, but these will create you something basic which will be good for a year. For more info, see `man openssl` in your terminal. - - * `-newkey rsa:4096` tells OpenSSL to create a 4096 bit RSA key for use with the certificate. RSA 2048 is the default on more recent versions of OpenSSL but to be sure of the key size, you should specify it during creation. - - * `-sha256` generate the certificate request using 265-bit SHA (Secure Hash Algorithm). - - * `-days` determines the length of time in days that the certificate is being issued for. For a commercial certificate, this value should be no higher than 730 (2 years). - - * `-nodes` instructs OpenSSL to create a certificate that does not require a passphrase. If this option is excluded, you will be required to enter the passphrase in the console each time the application using it is restarted. - - -## Regarding Your Certificate Authority's Root Certificate +## Your Certificate Authority's Root Certificate Most modern Linux distributions come with common root CA certificates installed as part of the `ca-certificates` package, located under `/etc/ssl/certs/ca-certificates.crt`. -Alternatively, or if your `ca-certificates` bundle does not already include your CA's root cert, you could download the certificate directly from the certificate authority's website. Once you have the certificate, you'll then need to add it manually by moving the file to the source directory and updating the bundle. +Alternatively, or if your `ca-certificates` bundle does not already include your CA's root cert, download the certificate directly from the certificate authority's website. Once you have the certificate, add it manually by moving the file to the source directory and updating the bundle. -CentOS +**CentOS** cp rootCert-example.crt /etc/pki/ca-trust/source/anchors/ update-ca-trust -Debian or Ubuntu +**Debian or Ubuntu** cp rootCert-example.crt /usr/local/share/ca-certificates/ update-ca-certificates - ## Submit Your CSR to Your Certificate Authority -This is when you must submit the certificate signing request to the CA for it to sign. How you do this will differ among certificate authorities and some CAs have videos or written instructions to guide you through the process, but the process usually involves the following steps: +Submit the certificate signing request to the CA. The exact steps differ among certificate authorities, and some CAs have videos or written instructions to guide you through the process. It usually involves the following steps: 1. Log in to your account with the CA. @@ -104,40 +106,16 @@ This is when you must submit the certificate signing request to the CA for it to 3. After a few days, the signed certificate will be available for you to download and install into your server. - ## Prepare a Chained SSL Certificate -Many CAs will issue certificates from an intermediate authority, which must be combined with the root certificate. If you receive several files from your CA ending with `.crt` (collectively referred to as a "chained SSL certificate"), they must be linked into one file, in a specific order, to ensure full compatibility with most browsers. The example below uses a chained SSL certificate that was signed by Comodo. +Many CAs will issue certificates from an intermediate authority, that certificate must be combined with the root certificate. + +If you receive several files from your CA ending with `.crt` (collectively referred to as a *chained SSL certificate*), they must be linked into one file, in a specific order, to ensure full compatibility with most browsers. The example below uses a chained SSL certificate that was signed by Comodo. To combine the individual certificates: cat example.com.crt COMODORSADomainValidationSecureServerCA.crt COMODORSAAddTrustCA.crt AddTrustExternalCARoot.crt > www.mydomain.com.crt -The contents of the resulting file will appear similar to the following: - - -----BEGIN CERTIFICATE----- - MIIFSzCCBDOgAwIBAgIQVjCXC0bF9U8FypJOnL9cuDANBgkqhkiG9w0BAQsFADCB - ................................................................ - ncHG3hwHHwhiEz6ukC2mqxA+D3KILiywgHgWcumnpeCEUQgDzy0Fz2Ip/kR/1Fkv - DCQzME2NkT1ZdW8fdz+Y - -----END CERTIFICATE----- - -----BEGIN CERTIFICATE----- - MIIGCDCCA/CgAwIBAgIQKy5u6tl1NmwUim7bo3yMBzANBgkqhkiG9w0BAQwFADCB - ................................................................ - j4rBYKEMrltDR5FL1ZoXX/nUh8HCjLfn4g8wGTeGrODcQgPmlKidrv0PJFGUzpII - -----END CERTIFICATE----- - -----BEGIN CERTIFICATE----- - ZFRydXN0IEV4dGVybmFsIFRUUCBOZXR3b3JrMSIwIAYDVQQDExlBZGRUcnVzdCBF - ................................................................ - Uspzgb8c8+a4bmYRBbMelC1/kZWSWfFMzqORcUx8Rww7Cxn2obFshj5cqsQugsv5 - -----END CERTIFICATE----- - -----BEGIN CERTIFICATE----- - MIIENjCCAx6gAwIBAgIBATANBgkqhkiG9w0BAQUFADBvMQswCQYDVQQGEwJTRTEU - ................................................................ - 6wwCURQtjr0W4MHfRnXnJK3s9EK0hZNwEGe6nQY1ShjTK3rMUUKhemPR5ruhxSvC - -----END CERTIFICATE----- - - Use this table to better visualize the command entered to prepare the chained certificate: | **Certificate Type:** | **Issued to:** | **Issued by:** | @@ -146,3 +124,29 @@ Use this table to better visualize the command entered to prepare the chained ce | Intermediate Certificate 1 | Comodo LLC | COMODORSA DomainValidation SecureServerCA | | Intermediate Certificate 2 | COMODORSA DomainValidation SecureServerCA | COMODORSA AddTrustCA | | Root certificate | COMODORSA AddTrustCA | AddTrust ExternalCARoot | + +The contents of the resulting file will appear similar to the following: + +{{< file "example.com.crt" >}} +-----BEGIN CERTIFICATE----- +MIIFSzCCBDOgAwIBAgIQVjCXC0bF9U8FypJOnL9cuDANBgkqhkiG9w0BAQsFADCB +................................................................ +ncHG3hwHHwhiEz6ukC2mqxA+D3KILiywgHgWcumnpeCEUQgDzy0Fz2Ip/kR/1Fkv +DCQzME2NkT1ZdW8fdz+Y +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +MIIGCDCCA/CgAwIBAgIQKy5u6tl1NmwUim7bo3yMBzANBgkqhkiG9w0BAQwFADCB +................................................................ +j4rBYKEMrltDR5FL1ZoXX/nUh8HCjLfn4g8wGTeGrODcQgPmlKidrv0PJFGUzpII +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +ZFRydXN0IEV4dGVybmFsIFRUUCBOZXR3b3JrMSIwIAYDVQQDExlBZGRUcnVzdCBF +................................................................ +Uspzgb8c8+a4bmYRBbMelC1/kZWSWfFMzqORcUx8Rww7Cxn2obFshj5cqsQugsv5 +-----END CERTIFICATE----- +-----BEGIN CERTIFICATE----- +MIIENjCCAx6gAwIBAgIBATANBgkqhkiG9w0BAQUFADBvMQswCQYDVQQGEwJTRTEU +................................................................ +6wwCURQtjr0W4MHfRnXnJK3s9EK0hZNwEGe6nQY1ShjTK3rMUUKhemPR5ruhxSvC +-----END CERTIFICATE----- +{{< /file >}} diff --git a/docs/tools-reference/tools/manipulate-lists-with-sort-and-uniq.md b/docs/tools-reference/tools/manipulate-lists-with-sort-and-uniq.md index 20e2ffdd677..774720f8b41 100644 --- a/docs/tools-reference/tools/manipulate-lists-with-sort-and-uniq.md +++ b/docs/tools-reference/tools/manipulate-lists-with-sort-and-uniq.md @@ -6,20 +6,20 @@ description: Use the sort and uniq Linux utilities to manage and order keywords: ["linux", "common commands", "sort", "uniq", "shell", "bash"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['linux-tools/common-commands/sort-uniq/'] -modified: 2018-01-16 +modified: 2018-01-23 modified_by: name: Linode published: 2010-11-29 -title: Manipulate Lists with sort and uniq +title: 'Manipulate Lists with sort and uniq' --- -The Linux utilities `sort` and `uniq` are useful for ordering and manipulating data in text files and as part of shell scripting. The `sort` command takes a list of items and sorts them alphabetically and numerically. The `uniq` command takes a list of items and removes adjacent duplicate lines. Though narrow in their focus, both of these tools are useful in a number of different command line operations. +![Manipulate Lists with sort and uniq](/docs/assets/manipulate_lists_with_sort_and_uniq_smg.png "Manipulate Lists with sort and uniq") -![Title graphic](/docs/assets/manipulate_lists_with_sort_and_uniq_smg.png) +## What are sort and uniq? -## Usage +The Linux utilities `sort` and `uniq` are useful for ordering and manipulating data in text files and as part of shell scripting. The `sort` command takes a list of items and sorts them alphabetically and numerically. The `uniq` command takes a list of items and removes adjacent duplicate lines. Though narrow in their focus, both of these tools are useful in a number of different command line operations. -### sort +## How to Use sort The `sort` command accepts input from a text file or standard output, sorts the input by line, and outputs the result. Sorted text is sent to standard output and printed on the terminal unless redirected. `sort` commands take the following format: @@ -37,13 +37,13 @@ In the default configuration, this `sort` prints the output on the terminal. To Here, the sorted output is written to the `~/retired-roster.txt` file. -### uniq +## How to Use uniq The `uniq` command takes input and removes repeated lines. Because `uniq` only removes identical adjacent lines, it is often used in conjunction with `sort` to remove non-adjacent duplicate lines. sort ~/roster.txt | uniq -## Examples +## Sort and Uniq Examples The examples in this section will use the following text file as an input: @@ -146,7 +146,7 @@ Aaron Smith The pseudo-random order is determined by using a cryptographic hash of the contents of lines, which produces a fast shuffle. Identical lines are always printed adjacently to each other. -If you would prefer `sort` can scramble a list using the system's random number generator `/dev/random` or psudo-random number generator `/dev/urandom`. Consider the output of the following commands: +If you prefer, `sort` can scramble a list using the system's random number generator `/dev/random` or pseudo-random number generator `/dev/urandom`. Consider the output of the following commands: {{< output >}} $ sort -R names-list.txt --random-source=/dev/random diff --git a/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections.md b/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections.md index 0c33520b48e..2ae30100b8e 100644 --- a/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections.md +++ b/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections.md @@ -6,33 +6,34 @@ description: 'Install a TLS certificate into NGINX for HTTPS access.' keywords: ["ssl", "tls", "nginx", "https", "certificate"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['web-servers/nginx/configuration/ssl/','security/ssl/ssl-certificates-with-nginx/','security/ssl/how-to-provide-encrypted-access-to-resources-using-ssl-certificated-on-nginx/','security/ssl/provide-encrypted-resource-access-using-ssl-certificates-on-nginx/'] -modified: 2018-01-09 +modified: 2018-01-23 modified_by: name: Linode published: 2018-01-09 title: 'Getting Started with NGINX - Part 3: Enable TLS for HTTPS Connections' --- -![HTTPS Configuration on NGINX](/docs/assets/nginx-ssl/Enable_SSL_nginx.jpg) +A single NGINX installation can host multiple websites. Any number of them can use the same TLS certificate and key, or a certificate/key pair exclusively their own. -A single NGINX installation can host multiple websites. Any number of them can use the same TLS certificate and key, or a cert/key pair exclusively their own. +## What is TLS? -Transport Layer Security (TLS) is the successor to Secure Socket Layer (SSL), and provides stronger HTTPS access to web servers from browsers and other devices. This guide outlines several scenarios for how to add a TLS certificate to your site's NGINX configuration. +Transport Layer Security (TLS) is the successor to Secure Socket Layer (SSL), and provides stronger HTTPS access to web servers from browsers and other devices. -## Before You Begin +This guide outlines several scenarios for how to add a TLS certificate to your site's NGINX configuration. -- This guide is Part 3 of our *Getting Started with NGINX* series and you will need a working NGINX setup with your site accessible via HTTP. If do not already have that, then complete at least [Part 1: Basic Installation and Setup](/docs/web-servers/nginx/nginx-installation-and-basic-setup/) before going further. +## Before You Begin -- You will need root access to the system, or a user account with `sudo` privileges. +* This guide is Part 3 of our *Getting Started with NGINX* series and you will need a working NGINX setup with your site accessible via HTTP. If do not already have that, complete at least [Part 1: Basic Installation and Setup](/docs/web-servers/nginx/nginx-installation-and-basic-setup/) before going further. -- You will need a TLS certificate and key for your site. The certificate can be self-signed if this is a private or internal site, or if you are simply experimenting. You can alternatively use a commercial certificate chain if that's what your site requires. If you don't already have a certificate and server key, see our guides for creating a [self-signed certificate](/docs/security/ssl/create-a-self-signed-tls-certificate) or a [certificate signing request](/docs/security/ssl/obtain-a-commercially-signed-tls-certificate). +* You will need root access to the system, or a user account with `sudo` privileges. -- If you compiled NGINX from source code, ensure that it was compiled with `--with-http_ssl_module`. Verify in the output of `nginx -V`. +* You will need a TLS certificate and key for your site. The certificate can be self-signed if this is a private or internal site, or if you are simply experimenting. Alternatively, use a commercial certificate chain if your site requires. If you don't already have a certificate and server key, see our guides for creating a [self-signed certificate](/docs/security/ssl/create-a-self-signed-tls-certificate) or a [certificate signing request](/docs/security/ssl/obtain-a-commercially-signed-tls-certificate). +* If you compiled NGINX from source code, ensure that it was compiled with `--with-http_ssl_module`. Verify in the output of `nginx -V`. -## Credentials Storage Location +## TLS Credentials Storage Location -There is no official or unanimously preferred place to store your site's TLS certificate and key. The certificate is sent to each device that connects to the server, so it's not a private file. The key, however, is. +There is no official or unanimously preferred place to store your site's TLS certificate (`.crt`) and key (`.key`). The certificate is sent to each device that connects to the server, so it's not a private file. The key, however, is private. Wherever you decide to store your certificate/key pair, you want them to remain untouched by system updates and secured against other system users. As an example, we'll store them in `/root/certs/` but **whatever location you decide, you should back up that folder**. @@ -46,12 +47,11 @@ Wherever you decide to store your certificate/key pair, you want them to remain chmod 400 /root/certs/example.com/example.com.key +## Configure the http Block for HTTPS -## Configure Your http Block - -Directives you want NGINX to apply to all sites on your server should go into the `http` block of `nginx.conf`, including SSL/TLS directives. The directives below assume one website, or all sites on the server, using the same certificate and key. +If there are directives that you want NGINX to apply to all sites on your server, add them to the `http` block of `nginx.conf`. Include SSL/TLS directives. The directives below assume one website, or all sites on the server, use the same certificate and key. -If you have multiple sites with their own HTTPS credentials, and/or are using a setup with both HTTP and HTTPS sites, you'll want to move the `ssl_certificate` and `ssl_certificate_key` directives into the `server` block for the appropriate site (`.pem` format can also be used). +If you have multiple sites with their own HTTPS credentials, or are using a setup with both HTTP and HTTPS sites, move the `ssl_certificate` and `ssl_certificate_key` directives into the `server` block for the appropriate site (`.pem` format can also be used). {{< file-excerpt "/etc/nginx/nginx.conf" nginx >}} http { @@ -61,19 +61,14 @@ http { ssl_protocols TLSv1.1 TLSv1.2; {{< /file-excerpt >}} - -## Configure a Single Site +## Configure a Single HTTPS Site Scenario: You have a certificate issued for one domain, and a single website you'd like NGINX to serve over HTTPS. -With only one site to work with, simply use the `http` block configuration [above](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/#configure-your-http-block). In this scenario, you do not need to add `ssl_*` directives to the site's configuration file. However, you do need to tell NGINX that the site should be listening on port 443 for HTTPS connections instead of port 80. See the [SSL module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) section of the NGINX docs for more information. +With only one site to work with, simply use the `http` block configuration [in the previous section](#configure-your-http-block). In this scenario, you do not need to add `ssl_*` directives to the site's configuration file. However, you do need to tell NGINX that the site should be listening on port `443` for HTTPS connections instead of port `80`. See the [SSL module](https://nginx.org/en/docs/http/ngx_http_ssl_module.html) section of the NGINX docs for more information. 1. As an example, below is a basic site configuration which works with the `http` block given above: - {{< note >}} -This `server` block makes your site available over IPv4 and IPv6 but *only* over HTTPS-you will have no HTTP access. You will also need to type `https://` into the browser to access your site. This is only a starting step, you likely wouldn't want to use this configuration without HSTS or redirecting HTTP requests to port 443. We'll get to those in part 4 of this series. -{{< /note >}} - {{< file-excerpt "/etc/nginx/conf.d/example.com.conf" nginx >}} server { listen 443 ssl default_server; @@ -82,20 +77,23 @@ server { root /var/www/example.com; {{< /file-excerpt >}} + This is only a starting step. This `server` block makes your site available over IPv4 and IPv6 but only over HTTPS. You will not have HTTP access. + + You will also need to include `https://` to access your site, and you likely wouldn't want to use this configuration without HSTS or without redirecting HTTP requests to port `443`. We'll get to those in [Part 4](/docs/web-servers/nginx/tls-deployment-best-practices-for-nginx/) of this series. + 2. Reload your configuration after making changes to NGINX's config files: nginx -s reload -3. Go to your site's address or Linode's IP in a web browser-making sure you use `https://` in the URL. Your site should load over HTTPS. If you're using a self-signed certificate, the browser will warn of an insecure connection but you'll be able to bypass that and still connect. - +3. From a web browser, go to your site's domain or IP address `https://example.com`. Your site should load over HTTPS. If you're using a self-signed certificate, the browser will warn that the connection is insecure. Bypass the warning and connect anyway. -## Configure Multiple Sites with a Single Certificate +## Configure Multiple Sites with a Single SSL Certificate -Scenario: You have a certificate that is valid for multiple domains, such as a wildcard certificate or a certificate using *SubjectAltName*. +**Scenario:** You have a certificate that is valid for multiple domains, such as a wildcard certificate or a certificate using *SubjectAltName*. -In this scenario, the directives in the `http` block given [above](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/#configure-your-http-block) stay the same. You'll need two separate configuration files in `/etc/nginx/conf.d/`, one for each site the credentials will protect. In them it is necessary to specify the IP address for each site with the `listen` directive. You do not want to use `default_server` if you have two different websites with different IPs. +In this scenario, the directives in the `http` block given in the [Configure Your HTTP Block](#configure-your-http-block) section stay the same. You'll need two separate configuration files in `/etc/nginx/conf.d/`, one for each site the credentials will protect. In them it is necessary to specify the IP address for each site with the `listen` directive. You do not want to use `default_server` if you have two different websites with different IPs. -1. The sites `example1.com`, `example2.com` are served using the same certificate and key we placed into `/root/certs/example.com/` [earlier](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/#credentials-storage-location). +1. The sites `example1.com`, `example2.com` are served using the same certificate and key we placed into `/root/certs/example.com/` [earlier](#credentials-storage-location). {{< file-excerpt "/etc/nginx/conf.d/example1.com.conf" nginx >}} server { @@ -121,25 +119,23 @@ server { 3. Both sites should now be accessible by HTTPS. If you use your browser to inspect the certificate properties, you'll see the one cert is serving both sites. +## Configure Multiple Sites with Different SSL Certificates -## Configure Multiple Sites with Different Certificates - -Scenario: You have two (or more) completely independent websites you want to serve with two (or more) different TLS certificate/key pairs. +**Scenario:** You have two (or more) completely independent websites you want to serve with a matching number of different TLS certificate/key pairs. 1. Make sure your certificate storage is organized well. Below is an example: /root/certs - ├── example1.com + ├── example1.com/ │   ├── example1.com.crt │   └── example1.com.key - └── example2.com + └── example2.com/ ├── example2.com.crt └── example2.com.key -2. Configure the `http` block of your `nginx.conf` as shown [above](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections/#configure-your-http-block), but **without the certificate and key locations**. Those will instead go in the individual site's `server` block since the locations are different for each site. The result should be: +2. Configure the `http` block of your `nginx.conf` as shown [above](#configure-your-http-block), but **without the certificate and key locations**. Those will go in the individual site's `server` block since the locations are different for each site. The result should be: {{< file-excerpt "/etc/nginx/nginx.conf" nginx >}} - http { ssl_ciphers EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; @@ -180,7 +176,8 @@ server { 5. Both sites should be accessible over HTTPS, but using your browser to inspect the certificates will show that site `example1.com` is using `example1.com.crt`, and `example2.com` is using `example2.com.crt`. - ## Part 4: TLS Best Practices For NGINX -Now that you've got NGINX serving your site over HTTPS, do not simply use the above configurations as-is. It only gets HTTPS working on your server and is inherently insecure without further configuration. To harden your server's handling of TLS connections, move on to part 4 of this series: [TLS Deployment Best Practices for NGINX](/docs/web-servers/nginx/tls-deployment-best-practices-for-nginx/). +Now that you've got NGINX serving your site over HTTPS, do not simply use the above configurations as-is. It only gets HTTPS working on your server and is inherently insecure without further configuration. + +To harden your server's handling of TLS connections, continue to Part 4 of this series: [TLS Deployment Best Practices for NGINX](/docs/web-servers/nginx/tls-deployment-best-practices-for-nginx/). diff --git a/docs/web-servers/nginx/nginx-installation-and-basic-setup.md b/docs/web-servers/nginx/nginx-installation-and-basic-setup.md index 0e0592e0dac..ab20ac09eca 100644 --- a/docs/web-servers/nginx/nginx-installation-and-basic-setup.md +++ b/docs/web-servers/nginx/nginx-installation-and-basic-setup.md @@ -2,45 +2,42 @@ author: name: Linode email: docs@linode.com -description: 'Assessing, installing, and configuring NGINX.' -keywords: ["nginx", "web server", "configure nginx"] +description: 'An in-depth look at the NGINX web server. Includes assessment, installation, and configuration best practices.' +keywords: ["nginx", "web server", "configure nginx", "optimize nginx"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['web-servers/nginx/configuration/ssl/','security/ssl/ssl-certificates-with-nginx/index.cfm/','web-servers/nginx/install-nginx-web-server-on-debian-8/','web-servers/nginx/how-to-install-nginx-on-debian-7-wheezy/'] -modified: 2018-01-09 +modified: 2018-01-25 modified_by: name: Linode published: 2018-01-09 title: 'Getting Started with NGINX - Part 1: Installation and Basic Setup' --- -This guide is the first of a four-part series. Parts one and two will walk you through installing NGINX Open Source from the NGINX repositories and making some configuration changes to increase performance and security. Parts three and four set up NGIX to serve your site over HTTPS and harden the TLS connection. +This guide is the first of a four-part series. Parts One and Two will walk you through installing NGINX Open Source from the NGINX repositories and making some configuration changes to increase performance and security. Parts Three and Four set up NGIX to serve your site over HTTPS and harden the TLS connection. ## Before You Begin -- You will need root access to the system, or a user account with `sudo` privileges. - -- Set your system's [hostname](/docs/getting-started/#setting-the-hostname). - -- Update your system. - +* You will need root access to the system, or a user account with `sudo` privileges. +* Set your system's [hostname](/docs/getting-started/#setting-the-hostname). +* Update your system. ## Install NGINX ### Stable vs. Mainline -The first decision you'll have to make about your installation is whether you want the *stable* or *mainline* version of NGINX Open Source. Stable is recommended, and will be what this series uses. More on NGINX versions [here](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/#stable_vs_mainline). +The first decision to make about your installation is whether you want the *Stable* or *Mainline* version of NGINX Open Source. Stable is recommended, and will be what this series of guides uses. More on NGINX versions [here](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/#stable_vs_mainline). -### Binary vs. Compiling +### Install NGINX from Binary or Compile from Source? -There are three primary ways to install NGINX Open Source. +There are three primary ways to install NGINX Open Source: -- A pre-built binary from your Linux distribution's repositories. This is the easiest installation method because you simply use your package manager to install the `nginx` package. However, for distributions which provide binaries (as opposed to build scripts), you'll be running an older version of NGINX than the current stable or mainline release. Patches can also be slower to land in distro repositories from upstream. +* **A pre-built binary from your Linux distribution's repositories.** This is the easiest installation method because you use your package manager to install the `nginx` package. However, for distributions which provide binaries (as opposed to build scripts), you'll be running an older version of NGINX than the current stable or mainline release. Patches can also be slower to land in distro repositories from upstream. -- A pre-built binary from NGINX Inc.'s repository. Still an easy installation process, requiring only to add the repository to your system and then install as normal. Has the benefit of the most vanilla, upstream configuration by default, with quicker updates and newer releases than a Linux distribution's repository. Compile-time options often differ from those of the NGINX binary in distribution repositories, and you can use `nginx -V` to see the compile options your binary was built with. **This is the installation method used in this series.** +* **A pre-built binary from NGINX Inc.'s repository.** This is the installation method used in this series. Still an easy installation process, and only requires that you add the repository to your system and then install as normal. Has the benefit of the most vanilla, upstream configuration by default, with quicker updates and newer releases than a Linux distribution's repository. Compile-time options often differ from those of the NGINX binary in distribution repositories, and you can use `nginx -V` to see the compile options your binary was built with. -- Compiling from source. This is the most complicated method of installation but still not difficult when following [NGINX's documentation](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/). Source code is updated frequently with patches and maintained at the newest stable or mainline releases, and building can be easily automated. This is the most customizable installation method because you can include or omit any compiling options and flags you choose. For example, one common reason people compile their own NGINX build is so they can use the server with a newer version of OpenSSL than what their Linux distribution provides. +* **Compiling from source.** This is the most complicated method of installation but still not difficult when following [NGINX's documentation](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/). Source code is updated frequently with patches and maintained at the newest stable or mainline releases, and building can be easily automated. This is the most customizable installation method because you can include or omit any compiling options and flags you choose. For example, one common reason people compile their own NGINX build is so they can use the server with a newer version of OpenSSL than what their Linux distribution provides. -### Installation Instructions +### How to Install NGINX This guide will use the official NGINX instructions for installing pre-built binaries on Ubuntu from the NGINX repository. See the [NGINX admin guide](https://www.nginx.com/resources/admin-guide/installing-nginx-open-source/) if you would like to use another distribution or installation method. @@ -51,7 +48,7 @@ This guide will use the official NGINX instructions for installing pre-built bin 2. Open `/etc/apt/sources.list` in a text editor and add the following two lines. Replace **codename** with the codename of your Ubuntu version (for example **xenial** for Ubuntu 16.04). - {{< file-excerpt "/etc/apt/sources.list" conf >}} + {{< file-excerpt "/etc/apt/sources.list" conf >}} deb http://nginx.org/packages/mainline/ubuntu/ codename nginx deb-src http://nginx.org/packages/mainline/ubuntu/ codename nginx {{< /file-excerpt >}} @@ -79,34 +76,33 @@ Server: nginx/1.11.9 As use of NGINX the product has grown, the company has worked to distance itself from configurations and terminology that were used in the past when trying to ease adoption for people already familiar with Apache. -If you have used Apache, you'll know that multiple sites (called *virtual hosts* in Apache terminology) are stored at `/etc/apache/sites-available/`, which symlink to files in `/etc/apache/sites-enabled/`. However, many guides and blog posts on NGINX recommend this same configuration. As you could expect, this has led to some confusion, and the assumption that NGINX regularly uses the `../sites-available/` and `../sites-enabled/` directories, and the `www-data` user. It does not. +If you have used Apache, you'll know that multiple sites (called *Virtual Hosts* in Apache terminology) are stored at `/etc/apache/sites-available/`, which symlink to files in `/etc/apache/sites-enabled/`. However, many guides and blog posts on NGINX recommend this same configuration. As you could expect, this has led to some confusion, and the assumption that NGINX regularly uses the `../sites-available/` and `../sites-enabled/` directories, and the `www-data` user. It does not. -Sure, it can. The NGINX packages in Debian and Ubuntu repositories have changed their configurations to this for quite a while now, so serving sites whose configuration files are stored in `/sites-available/` and symlinked to `/sites-enabled/` is certainly a working setup. However it is entirely unnecessary, and the Debian Linux family is the only one which does it. NGINX is NGINX, so use it as NGINX. Don't force Apache configurations onto a web server that isn't Apache. +Sure, it can. The NGINX packages in Debian and Ubuntu repositories have changed their configurations to this for quite a while now, so serving sites whose configuration files are stored in `/sites-available/` and symlinked to `/sites-enabled/` is certainly a working setup. However it is unnecessary, and the Debian Linux family is the only one which uses it. There is no need to force Apache configurations onto NGINX. Instead, multiple site configuration files should be stored in `/etc/nginx/conf.d/` as `example.com.conf`, or `example.com.disabled`. Do not add `server { }` blocks directly to `/etc/nginx/nginx.conf` either, even if your configuration is relatively simple. The NGINX process also runs as the username `ngnix` in the `nginx` group, so keep that in mind when adjusting permissions for website directories. For more information, see *[Creating NGNIX Plus Configuration Files](https://www.nginx.com/resources/admin-guide/configuration-files/)* . -Last, [as the NGINX docs point out](https://www.nginx.com/resources/wiki/start/topics/examples/server_blocks/), the term *virtual host* is an Apache term, even though it's used by Debian and Ubuntu `nginx.conf` file supplied from the repos, and some of NGINX's old documentation. A *server block* is the NGINX equivalent, so that is the phrase you'll see in this series on NGINX. - +Finally, [as the NGINX docs point out](https://www.nginx.com/resources/wiki/start/topics/examples/server_blocks/), the term *Virtual Host* is an Apache term, even though it's used by Debian and Ubuntu `nginx.conf` file supplied from the repos, and some of NGINX's old documentation. A *Server Block* is the NGINX equivalent, so that is the phrase you'll see in this series on NGINX. -## Configure for General Best Practices +## NGINX Configuration Best Practices -There is an endless amount of customizations you can do to NGINX to fit it better to your needs. Many of those will be exclusive to your use case though; what works great for one person may not work at all for another. +There are an endless number of customizations you can do to NGINX to fit it better to your needs. Many of those will be exclusive to your use case though; what works great for one person may not work at all for another. -This series will provide configurations that are general enough to be useful in just about any production scenario, but which you can build on for your own specialized setup. Everything in the section below is considered a best practice and none are reliant on each other. They're not essential to the function of your site or server, but they can have ugly consequences if disregarded. +This series will provide configurations that are general enough to be useful in just about any production scenario, but which you can build on for your own specialized setup. Everything in the section below is considered a best practice and none are reliant on each other. They're not essential to the function of your site or server, but they can have unintended consequences if disregarded. Two quick points: -- Before going further, first preserve the default `nginx.conf` file so you can restore the default configuration if your files become unusable: +* Before going further, first preserve the default `nginx.conf` file so you can restore the default configuration if your files become unusable: cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup-original -- After implementing each of the changes below, reload your configuration: +* After implementing each of the changes below, reload your configuration: nginx -s reload -### Use Multiple Worker Processes +### Configure nginx.conf for Multiple Worker Processes -Add or edit the following line in `/etc/nginx/nginx.conf`. Set this value to `auto`, or the number of CPU cores available to your Linode. +Add or edit the following line in `/etc/nginx/nginx.conf`. Set this value to `auto`, or to the number of CPU cores available to your Linode. {{< file-excerpt "/etc/nginx/nginx.conf" conf >}} worker_processes auto; @@ -114,18 +110,17 @@ worker_processes auto; For more information, see the sections on worker processes in [the NGINX docs](https://nginx.org/en/docs/ngx_core_module.html#worker_processes) and [this NGINX blog post](https://www.nginx.com/blog/tuning-nginx/). - ### Disable Server Tokens -NGINX's version number is visible by default with any connection made to the server, whether a successful 201 connection by cURL, or a 404 returned to a browser. Disabling server tokens makes it more difficult to determine NGINX's version, and therefore more difficult to implement version-specific attacks. +NGINX's version number is visible by default with any connection made to the server, whether by a successful 201 connection by cURL, or a 404 returned to a browser. Disabling server tokens makes it more difficult to determine NGINX's version, and therefore more difficult for an attacker to execute version-specific attacks. Server tokens enabled: -![NGNINX server tokens enabled](/docs/assets/nginx-basics/nginx-server-tokens-enabled.jpg) +![NGNINX server tokens enabled](/docs/assets/nginx-basics/nginx-server-tokens-enabled.jpg "NGNINX server tokens enabled") Server tokens disabled: -![NGINX server tokens disabled](/docs/assets/nginx-basics/404_Not_Found_Server_Tokens_Off.jpg) +![NGINX server tokens disabled](/docs/assets/nginx-basics/404_Not_Found_Server_Tokens_Off.jpg "NGINX server tokens disabled") Add the following line to the `http { }` block of `/etc/nginx/nginx.conf`: @@ -137,8 +132,7 @@ server_tokens off; Where NGNIX sets its root directory will differ depending on how you installed it. At the time of this writing, NGINX supplied from NGINX Inc.'s repository uses `/usr/share/nginx/`. -The NGINX docs warn that relying on the default location can result in the loss of site data when upgrading NGINX. You should use `/var/www/`, `/srv/`, or some other location that won't be touched by package or system updates. For more explanation, see *[Using the default document root]( -https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#using-the-default-document-root)* and *[Not using standard document root locations](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#not-using-standard-document-root-locations)*. +The NGINX docs warn that relying on the default location can result in the loss of site data when upgrading NGINX. You should use `/var/www/`, `/srv/`, or some other location that won't be touched by package or system updates. For more explanation, see [Using the default document root](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#using-the-default-document-root) and [Not using standard document root locations](https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/#not-using-standard-document-root-locations). This series will use `/var/www/example.com/` in its examples; in each instance, replace `example.com` with the IP address or domain name of your Linode. @@ -158,7 +152,7 @@ server { ### Serve Over IPv4 and IPv6 -Default NGINX configurations listen on port 80 and on all IPv4 addresses. Unless you intend your site to be inaccessible over IPv6 (or are unable to provide it for some reason), you should tell NGINX to also listen for incoming IPv6 traffic. +Default NGINX configurations listen on port `80` and on all IPv4 addresses. Unless you intend your site to be inaccessible over IPv6 (or are unable to provide it for some reason), you should tell NGINX to also listen for incoming IPv6 traffic. Add a second `listen` directive for IPv6 as shown below: @@ -168,27 +162,25 @@ server { listen [::]:80; {{< /file-excerpt >}} -If your site uses TLS, add the following line: +If your site uses [TLS](/docs/web-servers/nginx/enable-tls-on-nginx-for-https-connections), add the following line: {{< file-excerpt "/etc/nginx/conf.d/example.com.conf" nginx >}} listen [::]:443 ssl; {{< /file-excerpt >}} - {{< note >}} You can also specify your Linode's public IP addresses for NGINX to listen on. The line would then be, for example, `listen 203.0.113.4:80;`. {{< /note >}} +### Why NGINX has Compression Disabled -### About Compression - -You do not want to universally enable gzip compression because, depending on your site's content and whether you set session cookies, you risk vulnerability to [CRIME](https://en.wikipedia.org/wiki/CRIME) and [BREACH](http://www.breachattack.com/) exploits. +You do not want to universally enable gzip compression because, depending on your site's content and whether you set session cookies, you risk vulnerability to the [CRIME](https://en.wikipedia.org/wiki/CRIME) and [BREACH](http://www.breachattack.com/) exploits. -Compression has been disabled by default in NGINX [for years now](http://mailman.nginx.org/pipermail/nginx/2012-September/035600.html), so is not vulnerable to CRIME out of the box. Modern browsers have also taken steps against these exploits, but web servers can still be configured irresponsibly. +Compression has been disabled by default in NGINX [for years now](http://mailman.nginx.org/pipermail/nginx/2012-September/035600.html), so it's not vulnerable to CRIME out of the box. Modern browsers have also taken steps against these exploits, but web servers can still be configured irresponsibly. -On the other hand, if you leave gzip compression totally disabled, you rule out those vulnerabilities and use less CPU cycles, but at the expense of decreasing your site's performance. +On the other hand, if you leave gzip compression totally disabled, you rule out those vulnerabilities and use fewer CPU cycles, but at the expense of decreasing your site's performance. -There are various server-side mitigations possible and TLS 1.3 will further contribute to that, but for now, and unless you know what you're doing, the best solution is to compress only static site content such as images and HTML and CSS. +There are various server-side mitigations possible and the release of TLS 1.3 further contributes to that. For now, and unless you know what you're doing, the best solution is to compress only static site content such as images and HTML and CSS. Enable static asset compression by setting `gzip on` in a `server` block. It is also possible to enable compression for all sites served by NGINX by putting this directive within a `http` block. However, it's safer to use it only inside `server` blocks for individual sites and content types: @@ -199,11 +191,9 @@ server { } {{< /file-excerpt >}} -{{< note >}} -You can view all available mime types with `cat /etc/nginx/mime.types`. -{{< /note >}} +To view all available mime types, use `cat /etc/nginx/mime.types`. -Below is an example where NGINX is serving multiple websites, some using SSl/TLS and some not. The `gzip` directive is added to the HTTP site's `server { }` block, which ensures it remains disabled for the HTTPS site. +Below is an example in which NGINX is serving multiple websites, some using SSL/TLS and some are not. The `gzip` directive is added to the HTTP site's `server { }` block, which ensures it remains disabled for the HTTPS site: {{< file "/etc/nginx/conf.d/example1.com.conf" nginx >}} server { @@ -222,18 +212,20 @@ server { } {{< /file >}} -There are various other options available to NGINX's gzip module. See the [NGINX docs](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) for more info, and if if you prefer to compile you NGINX build, you can include the *[ngx_http_gzip_static_module](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)* which would further suit compression of static content. - +There are various other options available to NGINX's gzip module. See the [NGINX docs](https://nginx.org/en/docs/http/ngx_http_gzip_module.html) for more information, and if if you prefer to compile your NGINX build, you can include the [*ngx_http_gzip_static_module*](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html) which would further suit compression of static content. ## Configuration Recap To summarize where we are thus far: -- The *stable* version of NGINX Open Source was installed from the *nginx.org* repository. +* The *stable* version of NGINX Open Source was installed from the *nginx.org* repository. -- We have one basic website accessible, whose root directory is located at `/var/www/example.com/` and configuration file is located at `/etc/nginx/conf.d/example.com.conf`. +* One basic website is accessible: - {{< file "/etc/nginx/conf.d/example.com.conf" nginx >}} + * The root directory is located at `/var/www/example.com/` + * The configuration file is located at `/etc/nginx/conf.d/example.com.conf` + + {{< file "/etc/nginx/conf.d/example.com.conf" nginx >}} server { listen 80 default_server; listen [::]:80 default_server; @@ -247,7 +239,9 @@ server { } {{< /file >}} -- Changes we want NGINX to apply universally were added to the `html` block of `/etc/nginx/nginx.conf`. Our addition is put at the bottom of the block so we know what was added compared to what's provided by default. `nginx.conf` now looks like below. Note that `nginx.conf` does not contain any `server` blocks. +* Changes we want NGINX to apply universally are in the `html` block of `/etc/nginx/nginx.conf`. Our addition is put at the bottom of the block so we know what was added compared to what's provided by default. + + `nginx.conf` now looks like the following example. Note that `nginx.conf` does not contain any `server` blocks: {{< file "/etc/nginx/nginx.conf" nginx >}} user nginx; @@ -285,7 +279,6 @@ http { } {{< /file >}} - ## Part 2: (Slightly More) Advanced Configurations -By now you should have a basic NGINX installation and a some foundational settings to get you started. For slightly more advanced configurations, yet still applicable to anyone hosting a site on a Linode, see part 2 of this series: [(Slightly more) Advanced Configurations](/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx/) +By now you should have a basic NGINX installation and a some foundational settings to get you started. For slightly more advanced configurations, yet still applicable to anyone hosting a site on a Linode, see Part 2 of this series: [(Slightly more) Advanced Configurations for NGINX](/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx/) diff --git a/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx.md b/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx.md index cfb161fd1b9..020152e5d1e 100644 --- a/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx.md +++ b/docs/web-servers/nginx/slightly-more-advanced-configurations-for-nginx.md @@ -2,11 +2,11 @@ author: name: Linode email: docs@linode.com -description: 'Configure and optimize NGINX.' -keywords: ["nginx", "web server"] +description: 'Configure and optimize NGINX to best suit your web server needs. Host multiple sites, configure caching, disable content sniffing, and more.' +keywords: ["nginx", "web server", "nginx configuration", "multiple sites", "configure caching"] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' aliases: ['web-servers/nginx/configure-nginx-for-optimized-performance/','web-servers/nginx/how-to-configure-nginx/'] -modified: 2018-01-09 +modified: 2018-01-25 modified_by: name: Linode published: 2018-01-09 @@ -15,18 +15,17 @@ title: 'Getting Started with NGINX - Part 2: (Slightly More) Advanced Configurat ## Before You Begin -- This guide is part 2 of our *Getting Started with NGINX* series and you will need a working NGINX setup with a website accessible via HTTP. If do not already have that, then complete [Part 1: Basic Installation and Setup](/docs/web-servers/nginx/nginx-installation-and-basic-setup/). +* This guide is Part 2 of our *Getting Started with NGINX* series, and you will need a working NGINX setup with a website accessible via HTTP. If you do not already have that, complete [Part 1: Basic Installation and Setup](/docs/web-servers/nginx/nginx-installation-and-basic-setup/). -- You will need root access to the system, or a user account with `sudo` privileges. +* You will need root access to the system, or a user account with `sudo` privileges. -- You may want to make another backup of your `nginx.conf` so you have a snapshot of the work you've done up to this point. +* You may want to make another backup of your `nginx.conf` so you have a snapshot of the work you've done up to this point:// cp etc/nginx/nginx.conf etc/nginx/nginx.conf.backup-pt2 +## Configure NGINX to Your Needs -## Configuration Notes - -The internet has no shortage of sites, posts, Gists and other places listing vast amounts of "tuning", "tweaking", or "optimizing" procedures for NGINX. +The internet has no shortage of sites, posts, Gists and other places listing endless methods of "tuning", "tweaking", or "optimizing" procedures for NGINX. However, rarely are these configurations tested to deduce if there is in fact a performance increase. Of those that are, the author's use case may be completely different than yours, so there's no guarantee you'll experience the same benefit using their configuration. @@ -34,12 +33,11 @@ Favor simplicity and your own results; do not blindly follow tuning guides you f Truly advanced system tuning for web services, such as adjusting Linux kernel parameters and TCP stack functionality, is out of the scope of this series. If you would like to explore the topic further, take a look at [this NGINX blog post](https://www.nginx.com/blog/tuning-nginx/) for more information. +## Host Multiple Websites from a Single Server -## Hosting Multiple Websites - -In NGINX speak, a *server block* basically equates to a website (same as *virtual host* in Apache terminology). NGINX can host multiple websites, and **each site's configuration should be in its own file**, with the name formatted as `example.com.conf` and that file located at `/etc/nginx/conf.d/`. +In NGINX speak, a *server block* basically equates to a website (same as *virtual host* in Apache terminology). NGINX can host multiple websites, and **each site's configuration should be in its own file**, with the name formatted as `example.com.conf`. That file should be located at `/etc/nginx/conf.d/`. -If you then want to disable the site *example.com*, then rename `example.com.conf` to `example.com.conf.disabled`. When hosting multiple sites, be sure to separate their access and error logs with specific directives inside each site's server block. See *[Server Block Examples](https://www.nginx.com/resources/wiki/start/topics/examples/server_blocks/)* in the NGINX docs for more info. +If you then want to disable the site *example.com*, then rename `example.com.conf` to `example.com.conf.disabled`. When hosting multiple sites, be sure to separate their access and error logs with specific directives inside each site's server block. See [*Server Block Examples*](https://www.nginx.com/resources/wiki/start/topics/examples/server_blocks/) in the NGINX docs for more info. 1. All the second site's configuration file needs is a server block inside: @@ -62,34 +60,33 @@ server { Your second website should be visible at its domain and/or IP address. -## Basic Caching +## NGINX Basic Caching -NGINX can cache files served by web applications and frameworks such as WordPress, Drupal and Ruby on Rails. Though covering caching at this point steps out of the basic workflow so far (we've not set up any application with data to cache), it's worth mentioning here briefly. +NGINX can cache files served by web applications and frameworks such as WordPress, Drupal and Ruby on Rails. Though covering caching at this point steps out of the basic workflow so far (we haven't set up any application with data to cache), it's worth mentioning here briefly. For more information, see the [NGINX docs](https://nginx.org/en/docs/http/ngx_http_proxy_module.html), [NGINX admin guide](https://www.nginx.com/resources/admin-guide/content-caching/), and the [NGINX blog](https://www.nginx.com/blog/nginx-caching-guide/). -1. Create a folder to store cache content: +1. Create a folder to store cached content: mkdir /var/www/example.com/cache/ -2. Add the `proxy_cache_path` directive to NGINX's `http` block. Make sure the file path references the folder you just created above. +2. Add the `proxy_cache_path` directive to NGINX's `http` block. Make sure the file path references the folder in Step 1: {{< file-excerpt "/etc/nginx/nginx.conf" nginx >}} proxy_cache_path /var/www/example.com/cache/ keys_zone=one:10m max_size=500m inactive=24h use_temp_path=off; {{< /file-excerpt >}} - - `keys_zone=one:10m` sets a 10 megabyte shared storage zone (simply called *one*, but you can change this for your needs) for cache keys and metadata. + * `keys_zone=one:10m` sets a 10 megabyte shared storage zone (simply called `one`, but you can change this for your needs) for cache keys and metadata. - - `max_size=500m` sets the actual cache size at 500 MB. + * `max_size=500m` sets the actual cache size at 500 MB. - - `inactive=24h` removes anything from the cache which has not been access in the last 24 hours. + * `inactive=24h` removes anything from the cache which has not been accessed in the last 24 hours. - - `use_temp_path=off` writes cache files directly to the cache path. This setting is [recommended by NGNIX](https://www.nginx.com/blog/nginx-caching-guide/). + * `use_temp_path=off` writes cached files directly to the cache path. This setting is [recommended by NGNIX](https://www.nginx.com/blog/nginx-caching-guide/). +3. Add the following to your site configuration's `server` block. If you changed the name of the storage zone in the previous step, change the directive below from `one` to the zone name you chose. -3. Add the following to your site configuration's `server` block. If you changed the name of the storage zone in the step above, make sure you change the directive below from *one* to the zone name you chose. - - Replace *ip-address* and *port* with the URL and port of the upstream service whose files you wish to cache. For example, you would fill in `127.0.0.1:9000` if using [WordPress](https://www.nginx.com/resources/wiki/start/topics/recipes/wordpress/) or `127.0.0.1:2638` with (Ghost](https://docs.ghost.org/v1/docs/config#section-server). + Replace *ip-address* and *port* with the URL and port of the upstream service whose files you wish to cache. For example, you would fill in `127.0.0.1:9000` if using [WordPress](https://www.nginx.com/resources/wiki/start/topics/recipes/wordpress/) or `127.0.0.1:2638` with [Ghost](https://docs.ghost.org/v1/docs/config#section-server). {{< file "/etc/nginx/conf.d/example.com" nginx >}} proxy_cache one; @@ -98,27 +95,25 @@ proxy_cache one; } {{< /file >}} -4. Should you need to clear the cache, [the easiest way](http://nginx.2469901.n2.nabble.com/best-way-to-empty-nginx-cache-td3017271.html#a3017429) is with the command: +4. If you need to clear the cache, [the easiest way](http://nginx.2469901.n2.nabble.com/best-way-to-empty-nginx-cache-td3017271.html#a3017429) is with the command: find /var/www/example.com/cache/ -type f -delete If you want more than just a basic cache clear, you can use the [proxy_cache_purge](https://www.nginx.com/products/nginx/caching/#purging) directive. - ## HTTP Response Header Fields -Use *[add_header](https://nginx.org/en/docs/http/ngx_http_headers_module.html)* directives in your configuration carefully. Unlike other directives, an `add_header` directive is not inherited from parent configuration blocks if you have the directive in both, meaning an `add_header` directive in a `server` block will override any in your `http` area. +Use [*add_header*](https://nginx.org/en/docs/http/ngx_http_headers_module.html) directives in your configuration carefully. Unlike other directives, an `add_header` directive is not inherited from parent configuration blocks. If you have the directive in both, an `add_header` directive in a `server` block will override any in your `http` area. For this reason, you should include them in one of two different ways: -- Put all `add_header` directives in the `http` block. This isn't practical unless you want every header directive to apply to every site in your configuration. +* Put all `add_header` directives in the `http` block. This isn't practical unless you want every header directive to apply to every site in your configuration. -- Add the desired `add_header` directives only to the `server` block (or an [include](https://nginx.org/en/docs/ngx_core_module.html#include) file) of the site you want those directives to apply to. This is the best scenario if you have multiple websites and want some header directives applied to some sites, but not all sites you're hosting. +* Add the desired `add_header` directives only to the `server` block (or an [include file](https://nginx.org/en/docs/ngx_core_module.html#include)) of the site for which those directives should apply. This is the best scenario if you have multiple websites and want some header directives applied to some sites, but not all sites you're hosting. Below are some of the more universally-applicable header modifications. There are many more available, and you should read through the [OWASP Secure Headers Project](https://www.owasp.org/index.php/OWASP_Secure_Headers_Project) for more information. - -### Disable Content Sniffing +### Disable Content Sniffing in nginx.conf Content sniffing allows browsers to inspect a byte stream in order to determine the file format of its contents. It is generally used to help sites that do not correctly identify the MIME type of their web content, but it also presents a vulnerability to cross-site scripting and other attacks. To disable content sniffing, add the following line to your configuration's `http` block: @@ -127,37 +122,35 @@ http { add_header X-Content-Type-Options nosniff; {{< /file-excerpt >}} -### Limit or Disable Content Embedding +### Use add_header to Limit or Disable Content Embedding Content embedding is when a website renders a 3rd party element (div, img, etc.), or even an entire page from a completely different website, in a ``, `