Skip to content

json-var: NGINX JSON variables module

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-json-var provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-json-var
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

Configuration

json_var

  • syntax: json_var $variable { ... }
  • default: none
  • context: http

Creates a new variable whose value is a json containing the items listed within the block. Parameters inside the json_var block specify a field that should be included in the resulting json. Each parameter has to contain two arguments - key and value. The value can contain nginx variables.

Sample configuration

http {
    json_var $output {
        timestamp $time_local;
        remoteAddr $remote_addr;
        xForwardedFor $http_x_forwarded_for;
        userAgent $http_user_agent;
        params $args;
    }

    server {
        location /get_json/ {
            return 200 $output;
        }
    }
Hitting http://domain/get_json/?key1=value1&key2=value2 can return a json like: 
{
    "timestamp": "21/Jul/2017:12:44:18 -0400",
    "remoteAddr": "127.0.0.1",
    "xForwardedFor": "",
    "userAgent": "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3",
    "params": "key1=value1&key2=value2"
}