You may encounter the $connection_upgrade variable in your nginx configuration when working with Websockets or using an nginx config generator.

The $connection_upgrade variable isn’t available by default. Yet, it’s a recommended practice to define and use it in your reverse proxy settings.

This tutorial shows you how to fix nginx’s unknown variable message related to the connection upgrade!

nginx Series Overview

The Problem: Unknown "$connection_upgrade" Variable

You may run into this issue while (updating and afterward) checking your nginx configuration using nginx -t:

$ sudo nginx -t

nginx: [emerg] unknown "connection_upgrade" variable  
nginx: configuration file /etc/nginx/nginx.conf test failed  

The connection_upgrade variable isn’t a global nginx setting. Yet, you’ll see it in tutorials and code snippets throughout the Internet. Even the nginx company recommends defining and use the connection_upgrade. Let’s do that!

Configure the “$connection_upgrade” Variable

The connection upgrade is typically used in combination with WebSockets. In nginx, you can upgrade your HTTP connection to a WebSocket connection depending on the $http_upgrade variable.

You can define the dependency between the connection and http upgrade in nginx using a map block:

map $http_upgrade $connection_upgrade {  
    default upgrade;
    ''      close;
}

This map block tells nginx to correctly set the related Connection header to close if the Upgrade header is set to ''.

Put the map block into the http block of your nginx configuration. The default file path for the nginx config is /etc/nginx/nginx.conf.

Here’s an example of our nginx configuration using the map block defining a $connection_upgrade“ variable.

/etc/nginx/nginx.conf

user www-data;  
worker_processes auto;  
pid /run/nginx.pid;

events {  
        multi_accept       on;
        worker_connections 65535;
}

http {  
        sendfile on;
        tcp_nopush on;
        tcp_nodelay on;
        …

        ##
        # Connection header for WebSocket reverse proxy
        ##
+       map $http_upgrade $connection_upgrade {
+           default upgrade;
+           ''      close;
+       }

        # further configurations …
}

Save the updated nginx config file. Then, check your configuration file again using nginx -t:

$ sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok  
nginx: configuration file /etc/nginx/nginx.conf test is successful  

The config is OK. Sweet!

Using the “$connection_upgrade” Variable

Here’s an example showing how you may use the newly defined $connection_upgrade variable. It’s used in combination with proxy headers. Set the proxy headers in your location block like this:

server {  
    listen 80;
    listen 443 ssl http2;

    location / {
        proxy_http_version             1.1;
        proxy_set_header Upgrade       $http_upgrade;
        proxy_set_header Connection    $connection_upgrade;

        proxy_pass http://127.0.0.1:1234;
    }
}

That’s it! Enjoy WebSocket connections with nginx!

---

Mentioned Resources

• Article on nginx as a WebSocket Proxy