Skip to content

Managing Request Headers

This guide covers the internal structures and functions for handling HTTP headers in NGINX module development.

Header Storage Architecture

NGINX stores headers in two main structures:

Structure Purpose
headers_in Input request headers from client
headers_out Output headers for response

Both structures live in ngx_http_request_t. There is no separate "response" entity—all data is stored in a single request structure.

HTTP Header Flexibility

HTTP headers are flexible but complex:

  • Single header with one value
  • Multiple headers with the same name
  • One header split across multiple lines

NGINX handles this complexity with optimized storage:

  1. Known headers → Direct pointer in headers_in/headers_out
  2. Multi-value headers → Arrays (e.g., Cookies, Cache-Control)
  3. Numeric headers → Pre-parsed numeric field (e.g., content_length_n)
  4. Unknown headers → Plain list (headers.headers)

Getting Header Values

Search through all headers by name:

static ngx_table_elt_t *
search_headers_in(ngx_http_request_t *r, u_char *name, size_t len) {
    ngx_list_part_t  *part;
    ngx_table_elt_t  *h;
    ngx_uint_t        i;

    part = &r->headers_in.headers.part;
    h = part->elts;

    for (i = 0; /* void */ ; i++) {
        if (i >= part->nelts) {
            if (part->next == NULL) {
                break;
            }
            part = part->next;
            h = part->elts;
            i = 0;
        }

        if (len != h[i].key.len || 
            ngx_strcasecmp(name, h[i].key.data) != 0) {
            continue;
        }

        return &h[i];
    }

    return NULL;
}

Method 2: Hash Lookup (Known Headers)

Fast lookup for headers NGINX knows about:

ngx_table_elt_t *
search_hashed_headers_in(ngx_http_request_t *r, u_char *name, size_t len) {
    ngx_http_core_main_conf_t  *cmcf;
    ngx_http_header_t          *hh;
    u_char                     *lowcase_key;
    ngx_uint_t                  i, hash;

    lowcase_key = ngx_palloc(r->pool, len);
    if (lowcase_key == NULL) {
        return NULL;
    }

    hash = 0;
    for (i = 0; i < len; i++) {
        lowcase_key[i] = ngx_tolower(name[i]);
        hash = ngx_hash(hash, lowcase_key[i]);
    }

    cmcf = ngx_http_get_module_main_conf(r, ngx_http_core_module);
    hh = ngx_hash_find(&cmcf->headers_in_hash, hash, lowcase_key, len);

    if (hh == NULL || hh->offset == 0) {
        return NULL;
    }

    return *((ngx_table_elt_t **) ((char *) &r->headers_in + hh->offset));
}

Method 3: Direct Field Access (Fastest)

For known headers, access the field directly:

ngx_table_elt_t *
get_host_from_headers_in(ngx_http_request_t *r) {
    return r->headers_in.host;  // NULL if not present
}

Method 4: Pre-Parsed Numeric Values (Fastest)

For numeric headers:

off_t
get_content_length_n_from_headers_in(ngx_http_request_t *r) {
    return r->headers_in.content_length_n;  // -1 if not set
}

Setting Header Values

Setting Known Headers (e.g., Content-Length)

ngx_int_t
set_content_length_n_in_headers_out(ngx_http_request_t *r, 
                                     ngx_str_t *length, 
                                     off_t length_n) {
    ngx_table_elt_t *h;

    h = r->headers_out.content_length;
    if (h == NULL) {
        h = ngx_list_push(&r->headers_out.headers);
        if (h == NULL) {
            return NGX_ERROR;
        }

        h->key.data = (u_char *) "Content-Length";
        h->key.len = sizeof("Content-Length") - 1;
        r->headers_out.content_length = h;
    }

    h->value = *length;
    h->hash = 1;  // Mark as active (required!)

    r->headers_out.content_length_n = length_n;

    return NGX_OK;
}

Setting Custom (Unknown) Headers

ngx_int_t
set_custom_header_in_headers_out(ngx_http_request_t *r, 
                                  ngx_str_t *key, 
                                  ngx_str_t *value) {
    ngx_table_elt_t *h;

    h = ngx_list_push(&r->headers_out.headers);
    if (h == NULL) {
        return NGX_ERROR;
    }

    h->key = *key;
    h->value = *value;
    h->hash = 1;  // Mark as active

    return NGX_OK;
}

h->hash = 1

This tells ngx_http_header_module to include the header in the response. Without it, the header is ignored.

Proxy Pass Considerations

When using proxy_pass with custom headers, you must set the lowercased key:

header->key = (u_char *) "X-Custom-Header";
header->lowcase_key = (u_char *) "x-custom-header";

Crash Warning

The HTTP proxy module expects lowercased keys. Without lowcase_key, the module will crash on subrequests.

Common Known Headers

headers_in

Field Header
host Host
connection Connection
user_agent User-Agent
referer Referer
content_length Content-Length
content_type Content-Type
authorization Authorization
cookies Cookie (array)

headers_out

Field Header
status HTTP status code
content_length Content-Length
content_type Content-Type
location Location
last_modified Last-Modified
etag ETag

References