nginx-config-parser

1
2var ConfigParser = require('@webantic/nginx-config-parser')
3var parser = new ConfigParser()
4
5// parse straight from file. by default, will try to resolve includes
6var config = parser.readConfigFile('/path/to/file.conf')
7
8// to keep deterministic behaviour, set parseIncludes = false in the options
9var configWithoutIncludes = parser.readConfigFile('/path/to/file.conf', { parseIncludes: false })
10
11// write direct to file (overwriting existing one)
12parser.writeConfigFile('/path/to/newfile.conf', config, true)
13
14
15var sampleConfig = {
16  "server": {
17    "server_name": "_",
18    "location /": {
19      "try_files": "*.html"
20    }
21  }
22}
23
24// to multi-line config string
25var configString = parser.toConf(sampleConfig)
26// and back again
27var configJson = parser.toJSON(configString)
28
29// shorthand (will change object --> string and string --> object)
30parser.parse(configString)

Notes

Includes

.readConfigFile() will attempt to resolve includes and bundle them in the generated JavaScript object by default. If you call .toConf() (or .parse()) on the generated object, the generated conf string will differ from the original one as there is no way to replace the included content with the original include ... line. To control this behaviour, supply an options argument setting parseIncludes to false.

1
2parser.readConfigFile(filePath, callback, options)
3// or
4parser.readConfigFile(filePath, options)
5

By default, the .toJSON() method will not attempt to resolve includes (because the module has no idea where to look for the included files when it is only supplied a conf string instead of a file path). To force the module to attempt to resolve includes, you must set options.parseIncludes to true when calling the method. If you supply a value for options.includesRoot, the module will use that as the base path to search in. If you do not provide a value for options.includesRoot, the module will attempt to resolve the files in the CWD.

If a referenced include cannot be resolved, this method will throw an IncludeResolutionError. To ignore this error (which is the default behaviour in nginx), set options.ignoreIncludeErrors to true.

Lua blocks / openresty

If the config contains a block which ends with the string "by_lua_block", the parser will not tokenise the contents of the block. Instead, the raw contents of the block will be stored under a special key _lua as an array of strings. Each string in the array represents a single line from the block. For example:

1
2var config = [
3  'access_by_lua_block {',
4  '  ngx.var.url = ngx.unescape_uri(ngx.req.get_uri_args().url);',
5  '}'
6].join('\n')
7
8const parsed = parser.parse(config)
9console.log(JSON.stringify(parsed, null, 2))
10
11// {
12//   access_by_lua_block: {
13//     _lua: [
14//       'ngx.var.url = ngx.unescape_uri(ngx.req.get_uri_args().url);'
15//     ]
16//   }
17// }

Multiline

When parsing multiline blocks, the behaviour is non-deterministic. Effectively, this means that your values will be collapsed onto a single line when flipping to JSON and back to conf.

1const configString = `
2http {
3  proxy_cache_path /var/cache/nginx/users
4    keys_zone=users:1m
5    levels=2
6    use_temp_path=off
7    inactive=1d
8    max_size=16m;
9}
10`;
11
12const json = parser.toJSON(configString);
13
14const expectedOutput = `
15http {
16  proxy_cache_path /var/cache/nginx/users keys_zone=users:1m levels=2 use_temp_path=off inactive=1d max_size=16m;
17}
18`;
19
20parser.toConf(json) === expectedOutput; // true