An HTTP module basics and configuration

In the previous article I explained how modules of all types link into Nginx. Now let’s  look closer at the specifics of HTTP modules.

An HTTP module has the value NGX_HTTP_MODULE in its type field and the ctx field points to a global instance of a structure ngx_http_module_t: Continue reading

How your module plugs into Nginx

In previous articles I have deliberately omitted almost everything related to the question of linking your module with Nginx. It is important, however, that you know about it.

Let’s take a closer look at the metainformation that your module must contain, so that Nginx can initialise and configure it. Continue reading

Working with cookies in a Nginx module

Imagine you run a PPC advertising campaign and you want to find out how many visitors coming from a search engine result in sales. We will create an Nginx module and use cookies for this purpose. Whenever a visitor clicks on your ad, a landing page is requested with a tracking argument in it. The tracking argument looks  like that: ‘?source=whatever’. We will put the content of tracking argument into a cookie that will be called a source cookie and write it into a log file. Whenever a visitor makes a transaction (e.g. buys an article or makes a booking), the name of the source will be recorded and we will be able to easily attribute every transaction to a source.

Let’s start with declaring a structure that will contain configuration of our module: Continue reading

How to return a simple page

Let’s see what we need to do in order to return a simple page to a client using Nginx module. We need to generate a header and a body of the response. To send a response header we use function ngx_http_send_header:

#include <ngx_http.h>

ngx_int_t ngx_http_send_header(ngx_http_request_t *r);

The only argument r is the request for which you want to generate and send a header. This function serializes headers from the list of response headers r->headers_out into a buffer and sends this buffer to a client or queues this buffer into output queue r->out if the client socket is not writeable. The HTTP version in the status line will be determined for you automatically. The HTTP status code is taken from r->headers_out.status and the status text will be filled according to the status code.

Lets see how we can add some custom header line to our response header. Continue reading

HTTP request processing phases in Nginx

Nginx processes HTTP requests in multiple phases. In each of the phases there might be 0 or more handlers called. In the Nginx source code phases have specific constants associated with them. Here is a list of all phases:

  1. NGX_HTTP_SERVER_REWRITE_PHASE — the phase of request URI transformation on the virtual server level;
  2. NGX_HTTP_FIND_CONFIG_PHASE — the phase of the configuration location lookup;
  3. NGX_HTTP_REWRITE_PHASE — the phase of request URI transformation on the location level;
  4. NGX_HTTP_POST_REWRITE_PHASE — request URI transformation post-processing phase;
  5. NGX_HTTP_PREACCESS_PHASE — access restrictions check preprocessing phase;
  6. NGX_HTTP_ACCESS_PHASE — access restrictions check phase;
  7. NGX_HTTP_POST_ACCESS_PHASE — access restrictions check post-processing phase;
  8. NGX_HTTP_TRY_FILES_PHASE — try_files directive processing phase;
  9. NGX_HTTP_CONTENT_PHASE — content generation phase;
  10. NGX_HTTP_LOG_PHASE — logging phase.

On every phase you can register any number of your handlers. Continue reading