Nginx
Nginx is a lightweight webserver. Configuration is handled using the services.nginx. options.
Let's Encrypt certificates
The nginx module for NixOS has native support for Let's encrypt certificates; services.nginx.+acme. The NixOS Manual, Chapter 20. SSL/TLS Certificates with ACME explains it in detail.
Minimal Example
Assuming that myhost.org resolves to the ip address of your host and port 80 and 443 has been opened.
services.nginx.enable = true;
services.nginx.virtualHosts."myhost.org" = {
addSSL = true;
enableACME = true;
root = "/var/www/myhost.org";
};
This will set up nginx to serve files for myhost.org, automatically request an ACME SSL Certificate and will configure systemd timers to renew the certificate if required.
Troubleshooting
Read-only Filesystem for nginx upgrade to 20.09
With the upgrade to nixos-20.09 the nginx comes with extra hardening parameters, most prominently the restriction of write access to the Operating System Disk.
When you see errors like [emerg] open() "/var/spool/nginx/logs/binaergewitter.access.log" failed (30: Read-only file system) you can add extra paths to nginx service like this:
systemd.services.nginx.serviceConfig.ReadWritePaths = [ "/var/spool/nginx/logs/" ];
SIGTERM received from 1
If you turn debug logging on:
services.nginx.logError = "stderr debug";
You may see this:
[notice] 12383#12383: signal 15 (SIGTERM) received from 1, exiting
This means systemd is killing nginx for you, but systemd (in nixOS 20.09) isn't nice enough to tell you why it's happening. Chances are it's because your nginx config has daemon mode turned on, turn off daemon mode in your nginx config like so:
daemon off;
And it should fix nginx so systemd won't go killing your nginx anymore.
General
Nginx is run as SystemD service nginx, so systemctl status nginx may say something useful. If you have a problem with configuration, you can find the configuration location in the systemctl status, it should be at /nix/store/*-nginx.conf.
Sample setups
Static blog with ssl enforced in configuration.nix
services.nginx = {
enable = true;
virtualHosts."blog.example.com" = {
enableACME = true;
forceSSL = true;
root = "/var/www/blog";
};
};
# 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.
security.acme.certs = {
"blog.example.com".email = "youremail@address.com";
};
LEMP stack
(Nginx/MySQL/PHP) in configuration.nix
{ config, ...}: {
services.nginx = {
enable = true;
virtualHosts."blog.example.com" = {
enableACME = true;
forceSSL = true;
root = "/var/www/blog";
locations."~ \.php$".extraConfig = ''
fastcgi_pass unix:${config.services.phpfpm.pools.mypool.socket};
fastcgi_index index.php;
'';
};
};
services.mysql = {
enable = true;
package = pkgs.mariadb;
};
services.phpfpm.pools.mypool = {
user = "nobody";
settings = {
pm = "dynamic";
"listen.owner" = config.services.nginx.user;
"pm.max_children" = 5;
"pm.start_servers" = 2;
"pm.min_spare_servers" = 1;
"pm.max_spare_servers" = 3;
"pm.max_requests" = 500;
};
};
HTTP Authentication
Basic Authentication
Nginx can require users to login using HTTP Basic Authentication. In NixOS, this is set using the `basicAuth` option:
services.nginx = {
virtualHosts."example.com" = {
basicAuth = { user = "password"; anotherUser = "..."; };
...
};
};
Authentication via PAM
It is also possible to authenticate system users, e.g. users in the /etc/passwd file, by using the PAM module.
security.pam.services.nginx.setEnvironment = false;
systemd.services.nginx.serviceConfig = {
SupplementaryGroups = [ "shadow" ];
NoNewPrivileges = lib.mkForce false;
PrivateDevices = lib.mkForce false;
ProtectHostname = lib.mkForce false;
ProtectKernelTunables = lib.mkForce false;
ProtectKernelModules = lib.mkForce false;
RestrictAddressFamilies = lib.mkForce [ ];
LockPersonality = lib.mkForce false;
MemoryDenyWriteExecute = lib.mkForce false;
RestrictRealtime = lib.mkForce false;
RestrictSUIDSGID = lib.mkForce false;
SystemCallArchitectures = lib.mkForce "";
ProtectClock = lib.mkForce false;
ProtectKernelLogs = lib.mkForce false;
RestrictNamespaces = lib.mkForce false;
SystemCallFilter = lib.mkForce "";
};
services.nginx = {
enable = true;
additionalModules = [ pkgs.nginxModules.pam ];
...
virtualHosts."example.com".extraConfig = ''
auth_pam "Password Required";
auth_pam_service_name "nginx";
'';
...
};
};
TLS reverse proxy
This is a "minimal" example in terms of security, see below for more tips.
services.nginx = {
enable = true;
recommendedProxySettings = true;
recommendedTlsSettings = true;
# other Nginx options
virtualHosts."example.com" = {
enableACME = true;
forceSSL = true;
locations."/" = {
proxyPass = "https://127.0.0.1:12345";
proxyWebsockets = true; # needed if you need to use WebSocket
extraConfig =
# required when the target is also TLS server with multiple hosts
"proxy_ssl_server_name on;" +
# required when the server wants to use HTTP Authentication
"proxy_pass_header Authorization;"
;
};
};
};
Hardened setup with TLS and HSTS preloading
For testing your TLS configuration, you might want to visit [1]. If you configured preloading and want to apply for being included in the preloading list, check out [2]. Please read enough about preloading to understand the consequences, as it takes some effort to be removed from the list.
services.nginx = {
enable = true;
# Use recommended settings
recommendedGzipSettings = true;
recommendedOptimisation = true;
recommendedProxySettings = true;
recommendedTlsSettings = true;
# Only allow PFS-enabled ciphers with AES256
sslCiphers = "AES256+EECDH:AES256+EDH:!aNULL";
commonHttpConfig = ''
# Add HSTS header with preloading to HTTPS requests.
# Adding this header to HTTP requests is discouraged
map $scheme $hsts_header {
https "max-age=31536000; includeSubdomains; preload";
}
add_header Strict-Transport-Security $hsts_header;
# Enable CSP for your services.
#add_header Content-Security-Policy "script-src 'self'; object-src 'none'; base-uri 'none';" always;
# Minimize information leaked to other domains
add_header 'Referrer-Policy' 'origin-when-cross-origin';
# Disable embedding as a frame
add_header X-Frame-Options DENY;
# Prevent injection of code in other mime types (XSS Attacks)
add_header X-Content-Type-Options nosniff;
# Enable XSS protection of the browser.
# May be unnecessary when CSP is configured properly (see above)
add_header X-XSS-Protection "1; mode=block";
# This might create errors
proxy_cookie_path / "/; secure; HttpOnly; SameSite=strict";
'';
# Add any further config to match your needs, e.g.:
virtualHosts = let
base = locations: {
inherit locations;
forceSSL = true;
enableACME = true;
};
proxy = port: base {
"/".proxyPass = "http://127.0.0.1:" + toString(port) + "/";
};
in {
# Define example.com as reverse-proxied service on 127.0.0.1:3000
"example.com" = proxy 3000 // { default = true; };
};
};