Troubleshooting Nginx

Troubleshooting Nginx

Almost every Nginx report on this project is one of three errors. They look unrelated and they are not.

"directive is not allowed here"

nginx: [emerg] "if" directive is not allowed here in .../nginx/attack.conf:23
nginx: [emerg] "map" directive is not allowed here in .../nginx/attack.conf:5
nginx: [emerg] "location" directive is not allowed here in .../nginx/attack.conf:2

Cause. The per-category files (attack.conf, xss.conf, bots.conf, and so on) contain both map directives, which Nginx only accepts in the http block, and if directives, which it only accepts in server or location. No single include context can satisfy both, so including a category file directly fails whichever context you pick.

Fix. Do not include the category files. Include the two aggregate files, each in its own context:

http {
    include /etc/nginx/waf_patterns/nginx/waf_maps.conf;
}

server {
    include /etc/nginx/waf_patterns/nginx/waf_rules.conf;
}

A glob such as include /path/to/waf_patterns/nginx/*.conf; pulls in the category files too and reproduces the error. Reported in #17, #8 and #6.

"too long parameter, probably missing terminating character"

nginx: [emerg] too long parameter, probably missing terminating """ character in .../xss.conf:81

Cause. Nginx caps a single configuration parameter at 4096 characters. Some generated regular expressions exceed it. This is not a quoting mistake in your file: the line really is that long.

The occurrence in xss.conf was fixed (#7). A later report against waf_maps.conf is still open: see #22, which lists the offending lines.

Known open bugs

These are open in the tracker. If you hit one of them, you are not doing it wrong. The live list is the authority if this table has fallen behind:

Issue	Symptom
#21	waf_maps.conf wraps its content in an http block of its own. Including it inside your own http block produces "http" directive is not allowed here, because Nginx does not permit nested http.
#22	Several lines in waf_maps.conf exceed the 4096-character parameter limit.
#23	waf_rules.conf uses add_header inside an if block, which Nginx rejects.

They surface in sequence: work around the first and you meet the second. Subscribe to the issues rather than patching blindly, so your fix is not silently overwritten by the next daily release.

Before you open a new issue

Run the check and paste the whole thing:

nginx -t
nginx -v

The file name and line number in the error message are what makes a report actionable, along with the release you downloaded. A minimal reproduction with nginx -t -c /path/to/test.conf is even better, and is how #21 was pinned down.