Nginx as reverse proxy with acme (letsencrypt)

2017-11-23T13:07:22Z

Zixo:

== Introduction ==

This setup will allow you to have multiple servers/containers be accessible via a single IP address with the added benefit of centralized generation of letsencrypt certificates and secure https (according to ssllabs ssltest). Be aware you first need to setup regular HTTP server to be able to generate your HTTPS certificates and keys. After you have generated them you can add your HTTPS host based configuration.

== Installation ==

For this howto we need two tools, NGINX and acme-client.

{{Cmd|apk add nginx acme-client}}

== Setup ==

=== NGINX HTTP ===

==== Global configuration ====

First step is to refactor our global nginx.conf. Its target at a low traffic http server, to increase performance make changes at top level.

The security settings are taken from https://cipherli.st . Please also read https://hstspreload.org for details about HSTS.

<pre>
# ngnix configuration file

user nginx;

worker_processes 1; # use "auto" to use all available cores (high performance)

events {
worker_connections 1024; # increase if you need more connections
}

http {
# server_names_hash_bucket_size controls the maximum length
# of a virtual host entry (ie the length of the domain name).
server_names_hash_bucket_size 64;
server_tokens off; # hide who we are
sendfile off; # can cause issues

# secure nginx according to https://cipherli.st/
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH";
ssl_ecdh_curve secp384r1; # Requires nginx >= 1.1.0
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off; # Requires nginx >= 1.5.9
ssl_stapling on; # Requires nginx >= 1.3.7
ssl_stapling_verify on; # Requires nginx => 1.3.7
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=63072000"; # https://hstspreload.org
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;

ssl_dhparam dhparam.pem;

# nginx will find this file in the config directory set at nginx build time
include mime.types;

#fallback in case we can't determine a type
default_type application/octet-stream;

# buffering causes issues
proxy_buffering off;

# include hosts
include conf.d/*.conf;
}
</pre>

==== Diffie–Hellman Parameters ====

In the above configuration ssl_dhparam is used so we need to generate a global dhparam file. We want to use a 4096 key size but this can take a very long time. Because of this we are adding an extra option (dsaparam) to generate our dhparam file (see: https://wiki.openssl.org/index.php/Manual:Dhparam(1)#OPTIONS)

{{Cmd|openssl dhparam -dsaparam -out /etc/nginx/dhparam.pem 4096}}

At this point you should be able to (re)start your nginx server but it will not use any of the security features (yet).

==== Per site configuration files (conf.d) ====

Since Alpine v3.5 we ship NGINX with an default.conf within the /etc/nginx/conf.d directory.
To add support for another website you can add files with the .conf extension to this directory.

/etc/nginx/conf.d/alpinelinux.org.conf:

<pre>
server {
listen 80;
server_name alpinelinux.org;

location / {
include conf.d/proxy_set_header.inc;
proxy_pass http://downstream_http_server_host;
}
}
</pre>

==== Common configuration includes ====

If you need to setup multiple proxy setups you can include duplicated data like shown below.

/etc/nginx/conf.d/proxy_set_header.inc:

<pre>
proxy_set_header X-Forwarded-By $server_addr:$server_port;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;
</pre>

=== acme-client ===

To allow NGINX to support https we need to add certificates and support for ACME (Automatic Certificate Management Environment) responses.

==== ACME responses ====

/etc/nginx/conf.d/acme.inc:

<pre>
location /.well-known/acme-challenge {
alias /var/www/acme;
}
</pre>

And add this to your proxy configuration

/etc/nginx/conf.d/alpinelinux.org.conf

<pre>
server {
listen 80;
server_name alpinelinux.org;
include conf.d/acme.inc;

location / {
include conf.d/proxy_set_header.inc;
proxy_pass http://downstream_http_server_host;
}
}
</pre>

==== Automatic generate certificates ====

Create the following file and make it executable
/etc/periodic/weekly/acme-client

<pre>
#!/bin/sh

hosts="alpinelinux.org"

for host in $hosts; do
acme-client -a https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf -Nnmv $host && renew=1
done

[ "$renew" = 1 ] && rc-service nginx reload
</pre>

This script will run weekly to verify if one of your certificates is outdated and renew them when needed.

==== Initial generation of keys and certificates ====

To create your initial certificates and keys you have to run this manually the first time.

{{Cmd|/etc/periodic/weekly/acme-client}}

Watch the output and see if all goes well. When its finished you should have files in:

/etc/ssl/acme/alpinelinux.nl/fullchain.pem

/etc/ssl/acme/private/alpinelinux.org/privkey.pem

=== NGINX HTTPS ===

==== Per site HTTPS configuration ====

Add the following below the previous HTTP configuration:

/etc/nginx/conf.d/alpinelinux.org.conf

<pre>
server {
listen 443 ssl;
server_name alpinelinux.org
ssl on;
ssl_certificate /etc/ssl/acme/alpinelinux.org/fullchain.pem;
ssl_certificate_key /etc/ssl/acme/private/alpinelinux.org/privkey.pem;

location / {
include conf.d/proxy_set_header.inc;
proxy_pass http://downstream_http_server_host;
}
}
</pre>

=== Redirect HTTP to HTTPS ===

==== Shared configuration ====

Create the following file:

/etc/nginx/conf.d/redirect_http.inc

<pre>
location / {
return 301 https://$host$request_uri;
}
</pre>

==== Update host configuration ====

/etc/nginx/conf.d/alpinelinux.org.conf

<pre>
server {
listen 80;
server_name alpinelinux.org;
include conf.d/acme.inc;
include conf.d/redirect_http.inc;

location / {
include conf.d/proxy_set_header.inc;
proxy_pass http://downstream_http_server_host;
}
}
</pre>

=== Complete host example with IPv6 support ===

/etc/nginx/conf.d/alpinelinux.org.conf

<pre>
# alpinelinux.org

server {
listen 80;
listen [::]:80;
server_name alpinelinux.org;
include conf.d/acme.inc;
include conf.d/redirect_http.inc;
}

server {
listen 443 ssl;
listen [::]:443 ssl;
server_name alpinelinux.org;
ssl on;
ssl_certificate /etc/ssl/acme/alpinelinux.org/fullchain.pem;
ssl_certificate_key /etc/ssl/acme/private/alpinelinux.org/privkey.pem;

location / {
include conf.d/proxy_set_header.inc;
proxy_pass http://downstream_http_server_host;
}
}

</pre>

[[Category:Authentication]]
[[Category:Networking]]

Alpine Linux - User contributions [en]

Nginx as reverse proxy with acme (letsencrypt)