The Reverse Proxy concept

Most of the tools described in these pages have web-based interfaces. It is not a good idea to access them directly for quite many reasons:

• Scalability, since the tools don't come with a fully featured web server
• Security, since the tools don't come with a fully featured web server
• Access control, since the tools don't come with a fully featured web server
• Configuration, since you might want to provide specific URL's for each service
• Organization, since you will want to have a centralized dashboard to manage all the links to the tools

In other words, you want a reverse-proxy even if you are going to use this setup only from inside your home. More so, if you plan to have remote access, a reverse-proxy is a must. But what is a reverse-proxy? Basically a front-end web server that is capable to wrap a series or services together adding login, security, SSL and a common access point for them all.

There are lots of possible software to use. Basically any web server can act as a reverse proxy. Some are more suited than others, and my choice is on NGINX for a few reasons:

• Much easier than Apache to setup as a reverse-proxy
• Much lighter and less features full than Apache
• More complex and more features than Caddy
• Fully integrated in Let's Encrypt SSL infrastructure / CertBot script
• I don't personally know how to setup other similar tools

In general NGINX is fully featured but still very lightweight and secure HTTP server that shines as reverse-proxy. If you need to add more features, like PHP support or FastCGI, NGINX will support you without the need for an additional service on your server.

In order for a service to operate correctly behind a reverse proxy, it needs to support at least the base_url concept or, even better, also the authentication pass-trough.

The base_url is the address to the service. Instead of having your media server at https://mediaserver.mydomain.org, using a base_url would have it accessible at https://mydomain.org/mediaserver, where mediaserver is the base_url. Since you will reverse-proxy all your services toward one single server (and you don't even require a domain name for that, the 99.99.99.99 IP address is enough) you will need to specify base_url's for each one of the services. Some services will not support custom base_urls (which is bad practice, but whatever) in this case NGINX comes to your aid with the capability to rewrite the pages (html, javascript, css, etc) to “fix” the base_url for your service.

The authentication pass-trough is great, but it's even less supported by services. It will allow your nginx authentication to get picked up by the service and used without the need for a double authentication, which is annoying. Not many services support this, i am afraid.

NGINX installation on the home server is pretty straightforward, but we need to enable one specific authentication module, the pam authentication module, because i will show you how to link NGINX authentication to your home server users directly, without the need to create more users and passwords. If you prefer to use a different authentication, like basic_auth, i leave this out to you.

So create the file /etc/portage/package.use/nginx with the following lines:

app-misc/mime-types nginx
www-servers/nginx NGINX_MODULES_HTTP: auth_pam gunzip sub

(the first line is needed at the time of writing this page, YMMV)

Note: you might want to tweak the second line to your needs, see the flags for nginx and adapt.

A brief explanation of the above USE flags:

• auth_pam is used to enable PAM based authentication
• sub is used to allow substitutions inside the pages proxied, to fix web applications that don't play well with reverse-proxies
• gunzip is used to unzip the requests and let the sub module works also on compressed requests

Now install nginx:

 > emerge -v nginx

I think it's nice that with NGINX you can authenticate your users directly with your home server users. This means you don't need to add a second set of users, and that the users will only need one password, and no sync is required between HTTP users and server users. This is achieved using the pam_auth module on Linux. You have already built nginx with pam_auth support, but you need to configure it.

Create the file /etc/pam.d/nginx with these lines:

auth required pam_unix.so
account required pam_unix.so

You need two different NINX configurations. One facing the home network, which will serve on HP only, and one facing the external world, which will serve HTTPS only with HTTP as a redirect to HTTPS.

NGINX is very flexible in configuration, i will show you how to properly separate it's configuration file so that the main core is shared between home and remote access.

The main configuration file is located at /etc/nginx/nginx.conf, the default one is fine for the standard stuff, i will let you tweak and adapt it to your needs for everything outside the server sections. You will need to remove all server sections of your file and replace with the following:

        server {
                # Home facing server, HTTP only
                listen 127.0.0.1:80;
                server_name 192.168.0.1;
 
                include "folders/main.conf";
 
                access_log /var/log/nginx/localhost.access_log main;
                error_log /var/log/nginx/localhost.error_log info;
        }
 
        server {
                # remote facing server, HTTPS 
                server_name my_remote_server_name;
                auth_pam "Home";
                auth_pam_service_name "nginx";
 
                include "folders/main.conf";
 
                access_log /var/log/nginx/remote.access_log main;
                error_log /var/log/nginx/remote.error_log info;
 
                listen 127.0.0.1:8443 ssl; # managed by Certbot
                ssl_certificate /etc/letsencrypt/live/my_remote_server_name/fullchain.pem; # managed by Certbot
                ssl_certificate_key /etc/letsencrypt/live/my_remote_server_name/privkey.pem; # managed by Certbot
                include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
                ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
 
                location .well-known/acme-challenge/ {
                        auth_pam off;
                        autoindex on;
                }
 
        }
 
 
        server {
                # remote facing server, HTTP to HTTPS redirection
                listen 8080;
                access_log /var/log/nginx/remote.access_log main;
                error_log /var/log/nginx/remote.error_log info;
                return 301 https://$host$request_uri;
        }

I will walk you trough it a bit.

You have one simple section for the home server: it listen on port 80 and logs to some specific home only files. I choose not to use HTTPS inside the home network because it would be complicated to automatically generate the required certificates. If you still want HTTPS on the home side, you should use self-signed certificates, but i leave this exercise to you.

The remote HTTP server is even simpler: just a redirect to the remote HTTPS server, listening on port 8080 since port 80 is already taken by the home server. You never, ever, want to go not encrypted on the outside world. The remote HTTPS server is on port 8443 and adds all the specific HTTPS certificate stuff. Do not bother with it yet, i will explain a bit more later on.

Please note that due to the HTTPS certificates (which at this point are still to be created) you cannot yet start NGINX.

You can see that i used the include directive to point to a common folders/main.conf configuration file that will contain the gist of the common configuration. So, create the /etc/inginx/folders subfolder and put the following in the main.conf:

# This might be needed to direct upload of NZB files 
client_max_body_size 200M;
# This is required sometimes by Deluge web GUI giant cookies
large_client_header_buffers 4 32k;
 
# Here you will put your dashboard
root /data/daemons/htdocs;
 
# Specific service configurations
include "folders/deluge.conf";
include "folders/transmission.conf";
include "folders/nzbget.conf";
include "folders/radarr.conf";
include "folders/readarr_books.conf";
include "folders/readarr_audiobooks.conf";
include "folders/sonarr.conf";
include "folders/lidarr.conf";
include "folders/jellyfin.conf";
include "folders/ombi.conf";
include "folders/bazarr.conf";

As you can see, beside a few settings on top, it includes each service specific config as a separate file. This will give you lots of flexibility in adding or removing single services. The content of each specific service config file will be described in each service page.

The root directive is where you will need to put your dashboard to put all services together in a nice linked page, more details on this later on.

Next to: The *Arr's setup

Prev to: Network setup