NAME¶

nginx-confgen — A preprocessor and macro system for nginx(-like) configuration files

SYNOPSIS¶

DESCRIPTION¶

nginx-confgen can be used to do pre-processing for nginx configuration files (and other configuration files with a similar syntax). It has support for "compile-time" macro expansion and variable interpolation, which should make it less tedious to maintain large and complex configurations.

nginx-confgen works by parsing the input into a syntax tree, modifying this tree, and then formatting the tree to generate the output. It is completely oblivious to nginx contexts and directives, so it is possible to do nonsensical transformations and generate incorrect configuration files. Comments in the input file will not be present in the output. See also the BUGS & WARTS below.

SECURITY CONSIDERATION: Do NOT use nginx-confgen with untrusted input, the pre_exec directive allows arbitrary code execution by design.

OPTIONS¶

The following command-line options are supported:

-h

Show help text.

-v, --version

Show program version.

-i file

Use the given file name as input file. If this option is not given or set to a dash (-), then the file will be read from standard input.

-o file

Write the output to the given file. If this option is not given or set to a dash (-), then the file will be written to standard output.

-I path

Set the search path for pre_include directives. This option can be given multiple times to search several directories in order. If this option is not given, then include files are resolved relative to the directory that nginx-confgen is run from (i.e. "-I .").

DIRECTIVES¶

nginx-confgen recognizes and interprets the following directives:

pre_set $var outer;
location / {
  pre_set $var inner;
}
# $var is "inner" at this point.

pre_set $ip 127.0.0.1;
deny $ip;      # This will output as: deny 127.0.0.1;
deny $otherip; # This will output as: deny $otherip;

pre_exec $nameserver "grep nameserver /etc/resolv.conf \
                      | head -n 1 | sed 's/^nameserver //'";
resolver $nameserver;

pre_if -f $certdir/ocsp.der {
  ssl_stapling on;
  ssl_stapling_file $certdir/ocsp.der;
}
pre_if (!-f $certdir/ocsp.der) {
  ssl_stapling off;
}

# You can have different configuration depending on the name of
# the system on which nginx-confgen runs. Like... yeah.
pre_exec $hostname 'hostname';
pre_if $hostname ~* ^proxy_for_(.+) {
  proxy_pass http://$1/;
}

pre_if -e /etc/offline-mode {
  pre_warn "Putting website in offline mode!";
}

pre_macro proxy_cache $var {
  pre_warn "Using proxy_cache with $var violates company policy!";

  # But we can output it anyway.
  proxy_cache $var;
}

macro macro_name $var1 $var2 @remaining_vars &block_var {
  # contents
}

macro le {
  location /.well-known/acme-challenge {
    alias /etc/letsencrypt/challenge;
  }
}
# Usage:
le;

macro redir $path $to {
  location $path {
    return 301 $to;
  }
}
# Usage:
redir / http://blicky.net/;

macro vhost $primary_name @aliases &block {
  server {
    listen [::]:443 ssl;
    server_name $primary_name @aliases;
    ssl_certificate $crtdir/$primary_name/fullchain.pem;
    ssl_certificate_key $crtdir/$primary_name/privkey.pem;
    █
  }
}
# Usage:
vhost example.com {
  root /var/www/example.com;
}
vhost example.org alias.example.org {
  root /var/www/example.org;
}

pre_var $dest /a;
macro redir {
  # This will be /a, regardless of the context in which this macro is called.
  return 301 $dest;
}
# $dest is still '/a' inside the macro after this new variable definition.
pre_var $dest /b;
redir;

BUGS & WARTS¶

nginx-confgen is a quickly written hack to solve a particular use case, it is quite likely to have some weird behavior and bugs. In particular, processing performance may suffer on large configuration files with many macros and/or variables. Performance has simply not been a problem for me, but if you do run into trouble with your use case, let me know so I can fix it.

Comments and whitespace in the input files are thrown away and ignored. The generated output is completely reformatted.

The nginx configuration syntax is not as regular as I had hoped. It's possible for nginx modules to extend the syntax somewhat. A good example is the types directive in ngx_http_core_module. While nginx-confgen should be able to handle the types directive just fine, other extensions may cause syntax errors or will not survive a round-trip through nginx-confgen. This applies to all *_by_lua_block directives in the ngx_http_lua_module. The _by_lua directives that accept a string should work just fine.

SEE ALSO¶

nginx(8)

nginx-confgen has a website: https://dev.yorhel.nl/nginx-confgen

AUTHORS¶

Written by Yorhel <projects@yorhel.nl>