What language are nginx conf files?

Question

I want to write some more complex conditions in my Nginx configuration files but I'm not sure of the syntax and can't find docs describing what you can do beyond the basics in the examples and I can't seem to find this on the Nginx forums or on the mailing list.

For example, is it possible for me to have an unless condition?

Answer 1

The Nginx conf files are written in their own language or syntax. I've included some of the basics below. These are my own personal notes taken from Mastering Nginx

Basic format

the basic file is split into sections

:

<section> {

  <directive> <parameters>; 

}

Global parameters

Not defined in the standard format described above, it has no {} surrounding global section. It is placed at the top of the config file

Important global params

user - user and group which the worker processes run. If group omitted it equals that to user used

worker_processes - the number of worker processes started. They handle connections from clients. as a rule for CPU-bound loads this should equal number of processors and for I/O bound loads times this by 1.5 or 2

error_log - locations of error_logs. can be overwritten within directives. A second param indicates the level of log debug (only available when debugging mod configured at compilation), info, notice, warn, error, crit, alert and emerg.

pid - the file where the process ID of the main process is written, overwriting the compiled-in default.

worker_connections - configures the maximum number of simultaneous connections that a worker process may have open. Especially important on reverse proxy servers – some additional tuning may be required at the operating-system level in order to reach this number of simultaneous connections.

Using include files can be used anywhere in your configuration file

include /opt/local/etc/nginx/mime.types;

A wildcard may appear in the path to match multiple files: include /opt/local/etc/nginx/vhost/*.conf;

A configuration file can be easily tested by calling NGINX as follows: nginx -t -c

The Http section will be the most commonly used section.

Answer 2

Nginx configuration files are written in a language (if you want to call it one) that was designed and implemented for Nginx configuration files. Chances are that the documentation is the only available reference beyond the source itself. I would start by either posting a message on one of the Nginx forums or joining the Nginx mailing list and asking there. Of course, you can also grab the source and start there.

Good luck.

Answer 3

So I'm a newbie to nginx, and had this same question. Turns out the syntax of the language as mentioned above is both custom and actually quite simple. The syntax is captured in a section in the NGINX docs, and repeated here for convenience:

nginx consists of modules which are controlled by directives specified in the configuration file. Directives are divided into simple directives and block directives. A simple directive consists of the name and parameters separated by spaces and ends with a semicolon (;). A block directive has the same structure as a simple directive, but instead of the semicolon it ends with a set of additional instructions surrounded by braces ({ and }). If a block directive can have other directives inside braces, it is called a context (examples: events, http, server, and location).

Directives placed in the configuration file outside of any contexts are considered to be in the main context. The events and http directives reside in the main context, server in http, and location in server.

The rest of a line after the # sign is considered a comment.

In summary: Everything in an NGINX config file is a directive which may reference a variable. All directives are listed alphabetically here, and all variables are listed alphabetically here. NGINX configuration is driven by modules that each implement a certain piece of functionality, and each module contributes directives and variables that become available for use within the config. That's it.

That is why even if -- which looks like a keyword like in a traditional programming language -- is actually just a directive contributed by the ngx_http_rewrite_module module.

Hope this helps!

PS - Also check out https://devdocs.io/, and specifically https://devdocs.io/nginx, for a much improved way to search/use the NGINX documentation.