Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
selfhost:nginx [2024/08/27 13:12] – willy | selfhost:nginx [2025/03/13 09:29] (current) – external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== The Reverse Proxy concept ====== | + | ====== |
The use of a **reverse proxy** is the key at the foundation of ensuring security, isolation and flexibility in accessing your self-hosted services. | The use of a **reverse proxy** is the key at the foundation of ensuring security, isolation and flexibility in accessing your self-hosted services. | ||
- | A reverse-proxy is a web server that sits in the middle and handles all requests toward your services adding, on top, layers of encyrption | + | A reverse-proxy is a web server that sits in the middle and handles all requests toward your services adding, on top, layers of encryption |
- | The reverse-proxy will also take care of handling | + | The reverse-proxy will take care of handling |
Also, using a well known, solid and proven web server will alleviate the risk that each service might expose a poorly written, non-scalable or worse, internal web server to end users. | Also, using a well known, solid and proven web server will alleviate the risk that each service might expose a poorly written, non-scalable or worse, internal web server to end users. | ||
Line 14: | Line 14: | ||
My choice for a web server in this case is [[https:// | My choice for a web server in this case is [[https:// | ||
- | * It's much easier than [[https:// | + | * It's much easier than [[https:// |
- | * It has more features than [[https:// | + | * It has more features than [[https:// |
* It is fully integrated in [[https:// | * It is fully integrated in [[https:// | ||
- | 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 [[https:// | + | 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 [[https:// |
===== Base URLs and sub-domains ===== | ===== Base URLs and sub-domains ===== | ||
- | There are two different philosophies on how to host services: serve as a sub-path of a domain, or use sub-domains. I used to like best the // | + | There are two different philosophies on how to host services: serve as a sub-path of a domain, or use sub-domains. I used to like best the // |
Let's assume you have your own domain **mydomain.com** and you want to expose a service called // | Let's assume you have your own domain **mydomain.com** and you want to expose a service called // | ||
Line 33: | Line 33: | ||
* Pros: only one domain needed, no need to create sub-domains | * Pros: only one domain needed, no need to create sub-domains | ||
* Pros: the service existence is unknown to anybody not authorized | * Pros: the service existence is unknown to anybody not authorized | ||
- | * Cons: each service must support Base URL setting | + | * Cons: each service must support Base URL setting |
- | * Cons: all services must wither support or not support SSO | + | * Cons: SSO support |
- | * Cons: security wise, cookies and CORS can bring uninstended | + | * Cons: security wise, cookies and CORS can bring unintended |
- | * Cons: all services share the same HTTPS certificate | + | * Cons: all services share the same HTTPS certificate. |
As a **sub-domain**: | As a **sub-domain**: | ||
Line 46: | Line 46: | ||
* Cons: also public knowledge because there are services indexing all existing certificates. | * Cons: also public knowledge because there are services indexing all existing certificates. | ||
- | __Note:__ you can create // | + | __Note:__ you can create // |
- | To make a story short, i go with subdomains for well separated services, while going with sub-paths when sharing stuff that kind belongs together. Also, a deciding factor is wether | + | To make a story short, i go with subdomains for well separated services, while going with sub-paths when sharing stuff that kind belongs together. Also, a deciding factor is whether |
- | ===== Reverse Proxy propagation | + | ===== Reverse Proxy propagation ===== |
- | The reverse proxy is installed on the local server, | + | The reverse proxy is installed on the local server, |
+ | |||
+ | The reverse proxy will need to be accessible to both the internal users and the external users. You could setup two different proxies, but i prefer to have only one listening to both worlds. I will assume that there might be differences between internal and external users in terms of authentication or service availability. The underlying idea is that you will have your reverse proxy listening to different ports: one for internal access | ||
The setup i am describing uses three different ports: | The setup i am describing uses three different ports: | ||
* Port 80: both to local and remote, will just be a redirect to HTTPS | * Port 80: both to local and remote, will just be a redirect to HTTPS | ||
- | * Port 443: standard HTTPS for **internal** access, no PAM authentication | + | * Port 443: standard HTTPS for **internal** access |
- | * Port 8443: HTTPS with SSO authentication | + | * Port 8443: HTTPS for **external** access |
**Note:** for Let's Encrypt CertBot to work properly you **need** to redirect **both** port 80 and 443 from your external server to your internal server. CertBot will shutdown your NGINX and spin a custom NGINX server that you cannot tweak so it's critical that your SSH tunnels are properly forwarding ports 80 and 443 from the external server to the internal one, or it will not work. | **Note:** for Let's Encrypt CertBot to work properly you **need** to redirect **both** port 80 and 443 from your external server to your internal server. CertBot will shutdown your NGINX and spin a custom NGINX server that you cannot tweak so it's critical that your SSH tunnels are properly forwarding ports 80 and 443 from the external server to the internal one, or it will not work. | ||
Line 65: | Line 67: | ||
===== Installing NGINX ===== | ===== Installing NGINX ===== | ||
- | NGINX installation on the home server is pretty straightforward, | + | NGINX installation on the home server is pretty straightforward, |
+ | * //auth_request//: needed for SSO like authelia | ||
+ | * // | ||
+ | * //sub// is used to allow substitutions inside the pages proxied, to fix web applications | ||
+ | * //gunzip// is used to unzip the requests | ||
+ | * //realip// is needed by SSO like authelia | ||
+ | |||
+ | While NGINX support WebDAV, i strongly suggest | ||
So create the file **/ | So create the file **/ | ||
Line 73: | Line 82: | ||
</ | </ | ||
- | Let's see the modules you are enabling here: | + | Note: you might want to tweak the second line to your needs, see the [[https:// |
- | * // | + | |
- | * // | + | |
- | * //dav// and // | + | |
- | * //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 | + | |
- | + | ||
- | Note: you might want to tweak the second line to your needs, see the [[https:// | + | |
Now install nginx: | Now install nginx: | ||
<code bash> | <code bash> | ||
- | > | + | emerge -v nginx |
</ | </ | ||
+ | |||
+ | You can start it after you have configured it. | ||
Line 94: | Line 98: | ||
Assumptions: | Assumptions: | ||
* Your domain is **mydomain.com**, | * Your domain is **mydomain.com**, | ||
- | * Your service X is reachable under **https:// | + | * Your service X is reachable under **https:// |
- | * Your service Y is reachable under **https:// | + | * Your service Y is reachable under **https:// |
* All HTTP traffic is redirected to HTTPS | * All HTTP traffic is redirected to HTTPS | ||
+ | * You have a single Let's Encrypt SSL certificate which covers all the subdomains of your domain (either a wildcard or a comulative cert it's up to you) | ||
+ | * You might have more than one main domain | ||
- | You will create a set of subfolders | + | The top-level **mydomain.com** will have it's own folder, then you will create a set of sub-folders |
So you will need the following files: | So you will need the following files: | ||
Line 109: | Line 115: | ||
The **certbot.conf** file will be created later on, the specific SSO config files are described in the [[selfhost: | The **certbot.conf** file will be created later on, the specific SSO config files are described in the [[selfhost: | ||
+ | |||
==== Top-level configuration | ==== Top-level configuration | ||
Line 149: | Line 156: | ||
proxy_headers_hash_bucket_size 128; | proxy_headers_hash_bucket_size 128; | ||
- | # Add domains here (only the main config file for each subdomain!) | + | # Add domains here (only the main config file for each domain!) |
include com.mydomain/ | include com.mydomain/ | ||
+ | | ||
+ | # This is for SSL and needs to be included only once for all the domains | ||
+ | include / | ||
} | } | ||
</ | </ | ||
This will set your defaults for every service and site served by this reverse proxy, then will load the // | This will set your defaults for every service and site served by this reverse proxy, then will load the // | ||
+ | |||
==== mydomain.com configuration | ==== mydomain.com configuration | ||
Line 166: | Line 177: | ||
# simple catch-all server for the domain | # simple catch-all server for the domain | ||
server { | server { | ||
- | | + | # You might want to specify also the internal |
+ | | ||
+ | # Port for users from outside | ||
listen 8443 ssl; | listen 8443 ssl; | ||
+ | # Port for users from inside | ||
listen 443 ssl; | listen 443 ssl; | ||
http2 on; | http2 on; | ||
Line 177: | Line 191: | ||
# include all sub-paths for mydomain.com: | # include all sub-paths for mydomain.com: | ||
- | | + | |
+ | |||
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
# include all sub-domains entry points: | # include all sub-domains entry points: | ||
include com.mydomain/ | include com.mydomain/ | ||
- | |||
- | # include HTTS certs stuff: | ||
- | include com.mydomain/ | ||
</ | </ | ||
- | This will create the basic setup for your base domain name. I have assumed you want a static landing page, but you might put a // | + | This will create the basic setup for your base domain name. I have assumed you want a static landing page, but you might put a // |
==== sub-domains configuration | ==== sub-domains configuration | ||
- | It sohuld | + | It should |
I will assume that // | I will assume that // | ||
<file - y.conf> | <file - y.conf> | ||
server { | server { | ||
- | | + | server_name y.mydomain.com; |
- | listen 8443 ssl; # external access | + | |
- | listen 443 ssl; # internal access | + | |
- | access_log / | + | |
- | error_log / | + | |
- | location / { | + | |
- | #Generic proxy pass to proxied service | + | |
- | proxy_pass http:// | + | |
- | } | + | |
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
</ | </ | ||
Line 212: | Line 228: | ||
- | ==== Internal or External access for services ==== | + | ==== Differentiate between |
In my setup i have some differences when a service is accessed from //within// the home network, or from //outside// the home network. | In my setup i have some differences when a service is accessed from //within// the home network, or from //outside// the home network. | ||
- | The key point is that // | + | The key point is that // |
So, for example, a service _only_ available inside the home network will have something like: | So, for example, a service _only_ available inside the home network will have something like: | ||
Line 230: | Line 246: | ||
proxy_pass http:// | proxy_pass http:// | ||
} | } | ||
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
</ | </ | ||
Line 246: | Line 264: | ||
proxy_pass http:// | proxy_pass http:// | ||
} | } | ||
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
</ | </ | ||
Line 261: | Line 281: | ||
proxy_pass http:// | proxy_pass http:// | ||
} | } | ||
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
server { | server { | ||
Line 273: | Line 295: | ||
proxy_pass http:// | proxy_pass http:// | ||
} | } | ||
+ | # include HTTPS certs stuff: | ||
+ | | ||
} | } | ||
</ | </ | ||
+ | |||
+ | In this case, you can even optimize more by moving the **location** lines, which are identical, inside another file that you __include__ twice. Better to avoid redundancy! | ||
Of course, refer to the [[selfhost: | Of course, refer to the [[selfhost: | ||
Line 327: | Line 353: | ||
Let's Encrypt certificates last 90 days, then they need to be renewed. This is automated by CertBot but you need to call it periodically. You can use crontab for this. Edit root crontab: | Let's Encrypt certificates last 90 days, then they need to be renewed. This is automated by CertBot but you need to call it periodically. You can use crontab for this. Edit root crontab: | ||
<code bash> | <code bash> | ||
- | > | + | crontab -e |
</ | </ | ||
Line 341: | Line 367: | ||
<code bash> | <code bash> | ||
- | > | + | rc-update add nginx default |
- | > / | + | / |
</ | </ | ||
+ | |||
+ | |||
+ | |||
+ | ==== Quick and dirty script for new subdomains ==== | ||
+ | |||
+ | When you need to **add** a new subbomain to your certificate, | ||
+ | <file - certbot_script.sh> | ||
+ | #!/bin/bash | ||
+ | |||
+ | DOMAINS=" | ||
+ | |||
+ | domains= | ||
+ | for i in ${DOMAINS} | ||
+ | do | ||
+ | domains=" | ||
+ | done | ||
+ | |||
+ | certbot certonly --expand --nginx ${domains} | ||
+ | </ | ||
+ | |||
+ | So __FIRST__ you **update** the script adding the new domain at the end of the DOMAINS line, then you run the script and restart your NGINX. | ||
Line 350: | Line 397: | ||
To be able to run system scripts and, in general, [[https:// | To be able to run system scripts and, in general, [[https:// | ||
- | For using CGI directly with NGGINX | + | For using CGI directly with NGINX (another option |
<code bash> | <code bash> | ||
emerge www-misc/ | emerge www-misc/ |