Migrating from Apache to Nginx
I've had this hanging out as a draft for a while, and never got it polished up as well as I'd like; but in case it's useful to anyone, here's some notes on my recent migration to nginx.
I run civilfritz.net on a VPS, but I do my best to keep as low a monthly payment as possible. That means running on the smallest (lowest-memory) VM available from my provider: a 1GB Linode.
1GB used to seem like a lot of memory; but when I'm trying to run a Minecraft server alongside a preforking Apache server alongside a Salt master, it fills up quickly.
I've wanted to try moving to a lighter-weight webserver for a while; so today I'm porting my Apache config to Nginx.
sites-available/civilfritz.net
civilfritz.net runs as a pair of Apache virtual hosts to support
http and https. I want the majority of the configuration between
the vhosts to be identical, so I include a separate common
configuration file in each.
The http vhost includes the common config, as well as a rewrite for
the ikiwiki /auth section. (Authentication should only happen over
https, but attempts to authenticate over http should be redirected
there.)
# apache http vhost <VirtualHost *:80> RewriteEngine on RewriteRule ^/auth(|/.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [R,L] Include sites-available/civilfritz.net-common </VirtualHost>
The transition to nginx was pretty simple. The ikiwiki /auth section
is a virtually equivalent rewrite rule, and the include directive is
also similar.
# nginx http vhost server { listen 80; rewrite ^/auth(|/.*)$ https://$server_name:443$request_uri? permanent; include sites-available/civilfritz.net-common; }
The https vhost also includes the common config, as well as the
requisite ssl config. To support http basic authentication, an
instance of pwauth is configured as an external authentication
module, which proxies to PAM.
# apache https vhost <VirtualHost *:443> SSLEngine on SSLCertificateFile /etc/ssl/certs/civilfritz.net.pem SSLCertificateKeyFile /etc/ssl/private/civilfritz.net.key AddExternalAuth pwauth /usr/sbin/pwauth SetExternalAuthMethod pwauth pipe <Location /> AuthType Basic AuthBasicProvider external AuthExternal pwauth AuthName "civilfritz.net" </Location> Include sites-available/civilfritz.net-common <Location /auth> Require valid-user </Location> </VirtualHost>
Again, the nginx vhost starts out similarly. Listen on tcp 443, initialize the requisite certificate and key, and include the common config.
pwauth is an Apache-specific interface, so I wasn't able to use it
to proxy to pam in nginx; but the auth_pam module works well enough
and, since I'm not trying to use PAM to auth directly against local
unix files (I'm using sssd to access kerberos), I still don't have to
run the server as root.
# nginx ssl vhost server { listen 443 ssl; ssl_certificate /etc/ssl/certs/civilfritz.net.pem; ssl_certificate_key /etc/ssl/private/civilfritz.net.key; include sites-available/civilfritz.net-common; location /auth { auth_pam "civilfritz.net"; include fastcgi_params; fastcgi_pass unix:/var/run/fcgiwrap.socket; fastcgi_index ikiwiki.cgi; fastcgi_param REMOTE_USER $remote_user; } }
The semantics of Nginx basic authentication differ from Apache. In
Apache I was able to set AuthName globally (at /) and then require
authentication arbitrarily at lower points in the tree. Here, the
inclusion of the auth_pam directive implies an auth requirement; so
I'll have to repeat the authentication realm ("civilfritz.net")
anywhere I want to authenticate.
The biggest difference, though, is how Nginx handles cgi. Whereas
Apache builds-in cgi execution for nominated files or directories,
Nginx proxies all cgi execution through an external interface: here,
fastcgi. A packed-in fastcgi_params file contains some useful
default cgi environment variables, but omits REMOTE_USER. I set here
so that ikiwiki can determine what user has authenticated.
sites-available/civilfritz.net-common
The vast majority of my local config is in the common file included by both vhosts.
# Apache initial config ServerAdmin anderbubble@gmail.com DirectoryIndex index.html ServerName civilfritz.net ServerAlias www.civilfritz.net LogLevel warn ErrorLog /var/log/apache2/error.log CustomLog /var/log/apache2/access.log combined DocumentRoot /srv/www/wiki RewriteEngine on Alias /robots.txt /srv/www/robots.txt Alias /minecraft/overview /srv/www/minecraft-overviewer <Location /users/janderson/private> Require user janderson </Location> <Directory /> Options FollowSymLinks AllowOverride None Order deny,allow Deny from all </Directory> <Directory /srv/www> Order allow,deny Allow from all </Directory> <Directory /srv/www/wiki> AddHandler cgi-script .cgi Order allow,deny Allow from all Options +ExecCGI ErrorDocument 404 /ikiwiki.cgi ExpiresActive on ExpiresDefault "access plus 0 seconds" Header set Cache-Control "no-store, no-cache, must-revalidate, max-age=0" Header set Pragma "no-cache" </Directory> <Location /gitweb> Order allow,deny Allow from all DirectoryIndex index.cgi </Location> <Directory /home/*/public_html/> AllowOverride FileInfo AuthConfig Limit Indexes Options=ExecCGI </Directory> WSGIApplicationGroup %{GLOBAL}
New Nginx config
sites-available/civilfritz.net-common
index index.html; server_name civilfritz.net www.civilfritz.net; root /srv/www/wiki/; location / { error_page 404 /ikiwiki-404.cgi; expires -1; } location /robots.txt { alias /srv/www/robots.txt; } location /minecraft/overview { alias /srv/www/minecraft-overviewer; } location /ikiwiki.cgi { include fastcgi_params; fastcgi_pass unix:/var/run/fcgiwrap.socket; fastcgi_index ikiwiki.cgi; } location /ikiwiki-404.cgi { internal; include fastcgi_params; fastcgi_pass unix:/var/run/fcgiwrap.socket; fastcgi_param REDIRECT_URL $request_uri; # also needed to remove explicit 200 fastcgi_param REDIRECT_STATUS 404; } location ~ /gitweb/(index|gitweb).cgi { root /usr/share/; gzip off; include fastcgi_params; fastcgi_pass unix:/var/run/fcgiwrap.socket; } location /gitweb/ { root /usr/share/; gzip off; index index.cgi; } location ~ ^/~(.+?)(/.*)?$ { alias /home/$1/public_html$2; autoindex on; }
Salt state
nginx.sls
nginx: pkg: - installed service: - running - enable: True - reload: True - watch: - pkg: nginx
civilfritz/www.sls
include: - nginx [...] /etc/nginx/sites-enabled/default: file: - absent - watch_in: - service: nginx /etc/nginx/sites-enabled/civilfritz.net: file: - symlink - target: /etc/nginx/sites-available/civilfritz.net - require: - file: /etc/nginx/sites-available/civilfritz.net - watch_in: - service: nginx /etc/nginx/sites-available/civilfritz.net: file: - managed - source: salt://civilfritz/nginx-sites/civilfritz.net - user: root - group: root - mode: 0644 - require: - file: /etc/nginx/sites-available/civilfritz.net-common - watch_in: - service: nginx /etc/nginx/sites-available/civilfritz.net-common: file: - managed - source: salt://civilfritz/nginx-sites/civilfritz.net-common - user: root - group: root - mode: 0644 - watch_in: - service: nginx /srv/www/wiki/ikiwiki-404.cgi: file: - symlink - target: /srv/www/wiki/ikiwiki.cgi
