JIYIK CN >

When working with Websockets or configuring a server with nginx, we may come across $connection_upgradevariables in the nginx configuration.

The $connection_upgrade variable is not available by default. However, it is recommended to define and use it in a reverse proxy setup.

This article will show you how to fix the nginx unknown variable error related to connection upgrades!

Unknown "connection_upgrade" Variable error

We may nginx -tencounter this problem when checking our nginx configuration (after an update) using:

$ sudo nginx -t

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

connection_upgradeThe variable is not a global nginx setting. However, we'll see it in tutorials and code snippets all over the Internet. Even nginx Inc. recommends defining and using connection_upgrade. Let's start fixing it!

Configure the “$connection_upgrade” variable

Connection upgrades are often used in conjunction with WebSockets. In nginx, we can $http_upgradeupgrade HTTP connections to WebSocket connections based on the variables.

We can define the dependency between connect and http upgrade in nginx using the map block:

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

If the Upgrade header is set to '', this map block tells nginx to properly set the relevant Connection headers to close the connection.

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

This is an example nginx configuration using a map block that defines the $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 configuration file. Then, check the 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  

We can see that the configuration has taken effect. ✌️

Using the “$connection_upgrade” variable

The following example shows how to use the newly defined $connection_upgradevariable. It is used in conjunction with the proxy header. Setting the proxy header in our location block looks 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, you have nginx configured to support WebSocket connections!