+ +
+

Configuring NGINX for Evennia with SSL

+
+

This is NOT a full set-up guide! It assumes you know how to get your own letsencrypt certs, that you already have nginx installed, and that you are familiar with nginx configuration files. If you don’t already use nginx, you should follow the guide for using HAProxy instead.

+
+
+

SSL on the website and websocket

+

Both the website and the websocket should be accessed through your normal HTTPS port, so they should be defined together.

+

For nginx, here is an example configuration, using Evennia’s default ports:

+
server {
+	server_name example.com;
+
+	listen [::]:443 ssl;
+	listen 443 ssl;
+	ssl_certificate	 /path/to/your/cert/file;
+	ssl_certificate_key /path/to/your/cert/key;
+
+	location /ws {
+		# The websocket connection
+		proxy_pass http://localhost:4002;
+		proxy_http_version 1.1;
+		# allows the handshake to upgrade the connection
+		proxy_set_header Upgrade $http_upgrade;
+		proxy_set_header Connection "Upgrade";
+		# forwards the connection IP
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header Host $host;
+	}
+
+	location / {
+		# The main website
+		proxy_pass http://localhost:4001;
+		proxy_http_version 1.1;
+		# forwards the connection IP
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header Host $http_host;
+		proxy_set_header X-Forwarded-Proto $scheme;
+	}
+}
+
+
+

This proxies the websocket connection through the /ws location, and the root location to the website.

+

Following that example, you then need the following in your server/conf/secret_settings.py

+
+

Using secret_settings.py for this means you can continue using default access points for local development, making your life easier.

+
+
SERVER_HOSTNAME = "example.com"
+# Set the FULL URI for the websocket, including the scheme
+WEBSOCKET_CLIENT_URL = "wss://example.com/ws"
+# Turn off all external connections
+LOCKDOWN_MODE = True
+
+
+

This makes sure that evennia uses the correct URI for websocket connections. Setting LOCKDOWN_MODE on will also prevents any external connections directly to Evennia’s ports, limiting it to connections through the nginx proxies.

+
+
+

SSL on telnet

+
+

This will proxy ALL telnet access through nginx! If you want players to connect directly to Evennia’s telnet ports instead of going through nginx, leave LOCKDOWN_MODE off and use a different SSL implementation.

+
+

If you’ve only used nginx for websites, telnet is slightly more complicated. You need to set up stream parameters in your primary configuration file, e.g. /etc/nginx/nginx.conf - which, at least in my case, was not there by default.

+

I chose to parallel the http structure, so I could have streams-available conf files symlinked in streams-enabled the same as my sites.

+
stream {
+	include /etc/nginx/conf.streams.d/*.conf;
+	include /etc/nginx/streams-enabled/*;
+}
+
+
+

Then of course you need to create the required folders in the same folder:

+
$ sudo mkdir conf.streams.d streams-available streams-enabled
+
+
+

An example configuration file for the telnet connection - using an arbitrary external port of 4040 - would then be:

+
server {
+	listen [::]:4040 ssl;
+	listen 4040 ssl;
+
+	ssl_certificate  /path/to/your/cert/file;
+	ssl_certificate_key  /path/to/your/cert/key;
+
+	# connect to Evennia's internal NON-SSL telnet port
+	proxy_pass localhost:4000;
+	# forwards the connection IP - requires --with-stream-realip-module
+	set_real_ip_from $realip_remote_addr:$realip_remote_port
+}
+
+
+

Players can now connect with telnet+SSL to your server at example.com:4040 - but not to the internal connection of 4000.

+
+

IMPORTANT: With this configuration, the default front page will be WRONG. You will need to change the index.html template and update the telnet section (NOT the telnet ssl section!) to display the correct information.

+
+
+
+

Don’t Forget!

+

certbot will automatically renew your certificates for you, but nginx won’t see them without reloading. Make sure to set up a monthly cron job to reload your nginx service to avoid service interruptions due to expired certificates.

+
+
+ + +