Nginx - Revision history

WomboCombo: Documented configuration of nginx modules and where to find the module definitions.

2025-10-22T07:33:25Z

Documented configuration of nginx modules and where to find the module definitions.

@@ Line 287: / Line 287: @@
 systemd.services.hedgedoc.serviceConfig.UMask = "0000";
 </syntaxhighlight>
 == Let's Encrypt certificates ==

Moinakb001 at 16:21, 23 September 2025

2025-09-23T16:21:10Z

← Older revision		Revision as of 16:21, 23 September 2025
Line 450:		Line 450:
	== Extra config ==		== Extra config ==

	~~Appart~~ native options, Nix allows to specify verbatim Nginx configuration. Some options are mutually exclusive.		Apart native options, Nix allows to specify verbatim Nginx configuration. Some options are mutually exclusive.

	Below table assumes "services.nginx." prefix for all options. These options allows to keep using Nix configuration file while taking advantage of Nginx features which are not representend in options.		Below table assumes "services.nginx." prefix for all options. These options allows to keep using Nix configuration file while taking advantage of Nginx features which are not representend in options.

MichaelStapelberg: update SSL example to include required firewall and acceptTerms configuration for ACME to work

2025-07-22T16:32:51Z

update SSL example to include required firewall and acceptTerms configuration for ACME to work

← Older revision		Revision as of 16:32, 22 July 2025
Line 35:		Line 35:
	};		};
	};		};
	# Optional: You can configure the email address used with Let's Encrypt.
	# This way you get renewal reminders (automated by NixOS) as well as expiration emails.		networking.firewall.allowedTCPPorts = [ 80 443 ];
	~~security.acme.certs = {~~
	~~"blog.example.com"~~.email = "youremail@address.com";		security.acme = {
			# Accept the CA’s terms of service. The default provider is Let’s Encrypt, you can find their ToS at https://letsencrypt.org/repository/.
			acceptTerms = true;
			# Optional: You can configure the email address used with Let's Encrypt.
			# This way you get renewal reminders (automated by NixOS) as well as expiration emails.
			defaults.email = "youremail@address.com";
	};		};
	</syntaxhighlight>		</syntaxhighlight>

Pyluyten: Extra Config section added

2025-03-28T13:42:39Z

Extra Config section added

@@ Line 441: / Line 441: @@
 services.nginx.package = pkgs.nginxStable.override { openssl = pkgs.libressl; };
 </syntaxHighlight>
 == See more ==

Dander: add a proper installation section (see MoS)

2025-01-03T23:51:28Z

add a proper installation section (see MoS)

← Older revision		Revision as of 23:51, 3 January 2025
Line 1:		Line 1:
	[https://nginx.org/ {{PAGENAME}}] ([[wikipedia:en:{{PAGENAME}}]]) is a lightweight webserver. ~~Configuration is handled using~~ the {{nixos:option\|services.nginx.}} ~~options.~~		[https://nginx.org/ {{PAGENAME}}] ([[wikipedia:en:{{PAGENAME}}]]) is a lightweight webserver.

			== Installation ==
			To install Nginx, add the following to your NixOS configuration:{{file\|/etc/nixos/configuration.nix\|nix\|3=services.nginx.enable = true;}}
			More options are available: {{nixos:option\|services.nginx.}}

	== Sample setups ==		== Sample setups ==

Bmnascimento: It was missing the "virtualHosts.localhost" part, making the config file invalid.

2024-09-22T00:54:30Z

It was missing the "virtualHosts.localhost" part, making the config file invalid.

← Older revision		Revision as of 00:54, 22 September 2024
Line 8:		Line 8:
	services.nginx = {		services.nginx = {
	enable = true;		enable = true;
	locations."/" = {		virtualHosts.localhost = {
	return = "200 '<html><body>It works</body></html>'";		locations."/" = {
	extraConfig = ''		return = "200 '<html><body>It works</body></html>'";
	default_type text/html;		extraConfig = ''
	'';		default_type text/html;
			'';
			};
	};		};
	};		};

Krutonium: Add robots.txt

2024-09-21T07:49:27Z

Add robots.txt

@@ Line 70: / Line 70: @@
    };
 };
 </syntaxhighlight>

Malteneuss: Add rebind attack notice

2024-05-13T21:21:03Z

Add rebind attack notice

← Older revision		Revision as of 21:21, 13 May 2024
Line 287:		Line 287:
	We can also have a private server running in our local network (including VPN), that isn't reachable from the internet, but that still can get valid Let's Encrypt certificates that are accepted in a browser.		We can also have a private server running in our local network (including VPN), that isn't reachable from the internet, but that still can get valid Let's Encrypt certificates that are accepted in a browser.

	1. We have to '''modify DNS such that our domain''' like <code>myhost.org</code> '''resolves to the local IP address of our private server''' and port 80 and 443 have been opened. [https://www.youtube.com/watch?v=qlcVx-k-02E See this video tutorial] for an example on how to do that.		1. We have to '''modify DNS such that our domain''' like <code>myhost.org</code> '''resolves to the local IP address of our private server''' and port 80 and 443 have been opened. [https://www.youtube.com/watch?v=qlcVx-k-02E See this video tutorial] for an example on how to do that. Hint: You might need to '''add an exception to your router''' (definitely on Fritzboxes), because resolving to local IP address is usually blocked to prevent '''"DNS rebind attacks"'''.

	2. We have to setup the Let's Encrypt NixOS ACME services such that it uses an API token in a secrets file ([https://github.com/ryantm/agenix secrets for a server can be conveniently and securely deployed in NixOS with agenix]; just follow the tutorial) against our DNS provider to prove from our server that we own the domain. This way our server doesn't need to be exposed and reachable from the internet. NixOS ACME uses the [https://go-acme.github.io/lego/ LEGO library] to communicate to DNS providers (it supports a lot) and therefore we have to provide the token(s) in that library's secrets file format.		2. We have to setup the Let's Encrypt NixOS ACME services such that it uses an '''API token in a secrets file''' ([https://github.com/ryantm/agenix secrets for a server can be conveniently and securely deployed in NixOS with agenix]; just follow the tutorial) against our DNS provider to '''prove from our server that we own the domain'''. This way our server doesn't need to be exposed and reachable from the internet. NixOS ACME uses the [https://go-acme.github.io/lego/ LEGO library] to communicate to DNS providers (it supports a lot) and therefore we have to provide the token(s) in that library's secrets file format.

	In the example we use Hetzner as our "dnsProvider" that only needs a single API token environment in our secrets file:		In the example we use Hetzner as our "dnsProvider" that only needs a single API token environment in our secrets file:
Line 296:		Line 296:
	</syntaxhighlight>Other [https://carjorvaz.com/posts/setting-up-wildcard-lets-encrypt-certificates-on-nixos/ DNS providers need like OVH] require more environment variables.		</syntaxhighlight>Other [https://carjorvaz.com/posts/setting-up-wildcard-lets-encrypt-certificates-on-nixos/ DNS providers need like OVH] require more environment variables.

	See the section "Credentials" on what you have to specify in the secrets file: https://go-acme.github.io/lego/dns/hetzner/		See the section "'''Credentials'''" on what you have to specify in the secrets file: https://go-acme.github.io/lego/dns/hetzner/

	See Hetzner guide on how to get an API token for its "DNS console": https://docs.hetzner.com/dns-console/dns/general/api-access-token/		See Hetzner guide on how to get an API token for its "DNS console": https://docs.hetzner.com/dns-console/dns/general/api-access-token/
Line 350:		Line 350:

	</syntaxhighlight>		</syntaxhighlight>
	This will set up nginx to serve files for example.org, automatically request an ACME SSL Certificate using a "DNS-01" challenge (meaning your server ~~must not~~ be exposed to the internet) and will configure systemd timers to renew the certificate if required.		This will set up nginx to serve files for example.org, automatically request an ACME SSL Certificate using a "DNS-01" challenge (meaning '''your server doesn't need to be exposed to the internet''', which is great for self-hosting) and will configure systemd timers to renew the certificate if required.

	== Troubleshooting ==		== Troubleshooting ==

Malteneuss: Add a Private Local LAN Server Example Nix config code

2024-05-13T21:14:27Z

Add a Private Local LAN Server Example Nix config code

← Older revision		Revision as of 21:14, 13 May 2024
Line 289:		Line 289:
	1. We have to '''modify DNS such that our domain''' like <code>myhost.org</code> '''resolves to the local IP address of our private server''' and port 80 and 443 have been opened. [https://www.youtube.com/watch?v=qlcVx-k-02E See this video tutorial] for an example on how to do that.		1. We have to '''modify DNS such that our domain''' like <code>myhost.org</code> '''resolves to the local IP address of our private server''' and port 80 and 443 have been opened. [https://www.youtube.com/watch?v=qlcVx-k-02E See this video tutorial] for an example on how to do that.

	2. We have to setup the Let's Encrypt NixOS ACME services such that it uses an API token in a secrets file ([https://github.com/ryantm/agenix secrets for a server can be conveniently and securely deployed in NixOS with agenix]; just follow the tutorial) against our DNS provider to prove from our server that we own the domain. This way our server doesn't need to be exposed and reachable from the internet. NixOS ACME uses the [https://go-acme.github.io/lego/ LEGO library] to communicate to DNS providers and therefore we have to provide the token(s) in that ~~tool~~'s secrets format.		2. We have to setup the Let's Encrypt NixOS ACME services such that it uses an API token in a secrets file ([https://github.com/ryantm/agenix secrets for a server can be conveniently and securely deployed in NixOS with agenix]; just follow the tutorial) against our DNS provider to prove from our server that we own the domain. This way our server doesn't need to be exposed and reachable from the internet. NixOS ACME uses the [https://go-acme.github.io/lego/ LEGO library] to communicate to DNS providers (it supports a lot) and therefore we have to provide the token(s) in that library's secrets file format.

	In the example we use Hetzner as our "dnsProvider" that only needs a single API token environment in our secrets file:		In the example we use Hetzner as our "dnsProvider" that only needs a single API token environment in our secrets file:
Line 302:		Line 302:
	3. Point our virtualHost to the ACME entry.		3. Point our virtualHost to the ACME entry.
	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	services.nginx.enable = true;		{
	~~services.nginx~~.virtualHosts."~~myhost~~.org" = {		services.nginx = {
	~~addSSL~~ = true;		enable = true;
	~~enableACME~~ = true;		# we can use the main domain or any subdomain that's mentioned by
	~~root~~ = "/~~var~~/~~www~~/~~myhost.org"~~;		# "extraDomainNames" in the acme certificate.
	};		virtualHosts."subdomain.example.org" = {
	security.acme ~~= {~~		# 3. Instead of "enableACME = true;" we
	acceptTerms = true;		# reuse the certificate from "security.acme.certs."example.org"
	defaults.email = "~~foo~~@~~bar~~.~~com~~";		# down below
	};		useACMEHost = "example.org";
			forceSSL = true;
			locations."/" = {
			return = "200 '<html><body>It works</body></html>'";
			extraConfig = ''
			default_type text/html;
			'';
			};
			};
			};

			security.acme.acceptTerms = true;
			security.acme.defaults.email = "info@example.org";

			# 2. Let NixOS generate a Let's Encrypt certificate that we can reuse
			# above for several virtualhosts above.
			security.acme.certs."example.org" = {
			domain = "example.org";
			extraDomainNames = [ "subdomain.example.org" ];
			# The LEGO DNS provider name. Depending on the provider, need different
			# contents in the credentialsFile below.
			dnsProvider = "hetzner";
			dnsPropagationCheck = true;
			# agenix will decrypt our secrets file (below) on the server and make it available
			# under /run/agenix/secrets/hetzner-dns-token (by default):
			# credentialsFile = "/run/agenix/secrets/hetzner-dns-token";
			credentialsFile = config.age.secrets."hetzner-dns-token.age".path;
			};

			# Let agenix know about and copy our (encrypted) DNS API token secrets file
			# (containing "HETZNER_API_KEY=...") to the server an decrypt it there.
			# Follow the agenix tutorial on how to encrypt a secrets file
			# to a .age file and how to setup your Nix flake to use it.
			age.secrets."hetzner-dns-token.age".file = .../hetzner-dns-token.age;

			users.users.nginx.extraGroups = [ "acme" ];
			}

	</syntaxhighlight>		</syntaxhighlight>
	This will set up nginx to serve files for ~~<code>myhost~~.org~~</code>~~, automatically request an ACME SSL Certificate using a "DNS-01" challenge (meaning your server must not be exposed to the internet) and will configure systemd timers to renew the certificate if required.		This will set up nginx to serve files for example.org, automatically request an ACME SSL Certificate using a "DNS-01" challenge (meaning your server must not be exposed to the internet) and will configure systemd timers to renew the certificate if required.

	== Troubleshooting ==		== Troubleshooting ==

Malteneuss: Add a Private Local LAN Server Example

2024-05-13T20:56:27Z

Add a Private Local LAN Server Example

@@ Line 266: / Line 266: @@
 The nginx module for NixOS has native support for Let's Encrypt certificates;  {{nixos:option|services.nginx.+acme}}. The {{manual:nixos|sec=#module-security-acme-nginx|chapter=Chapter 20. SSL/TLS Certificates with ACME}} explains it in detail.
-=== Minimal Example ===
+=== Minimal Internet Exposed Server Example ===
-Assuming that <code>myhost.org</code> resolves to the IP address of your host and port 80 and 443 has been opened.
+Assuming that <code>myhost.org</code> resolves to the IP address of your host and port 80 and 443 have been opened.
 <syntaxhighlight lang="nix">
 services.nginx.enable = true;
@@ Line 281: / Line 281: @@
 };
 </syntaxhighlight>
-This will set up nginx to serve files for <code>myhost.org</code>, automatically request an ACME SSL Certificate and will configure systemd timers to renew the certificate if required.
+This will set up nginx to serve files for <code>myhost.org</code>, automatically request an ACME SSL Certificate using a "'''HTTP-01'''" challenge (meaning your server must be exposed to the internet) and will configure systemd timers to renew the certificate if required.
 == Troubleshooting ==