# &adminguide;

## Overview

This module implements an embedded HTTP/2 server using nghttpd2 library.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- libnghttp2 - libnghttpd library (v1.43.0+)

## Parameters

### `listen_addr` (str)

IPv4 address to listen for HTTP2 connection. If not set, then it listens on all local addresses (port has to be specified by listen_port parameter).

Default value is "" (empty - not set).

#### Set `listen_addr` parameter

    ...
    modparam("nghttp2", "listen_addr", "127.0.0.1")
    ...

### `listen_port` (str)

Port or service name to listen for HTTP2 connection.

Default value is "8282".

#### Set `listen_port` parameter

    ...
    modparam("nghttp2", "listen_port", "8284")
    ...

### `event_callback` (str)

The name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, ...) to be executed instead of event_route[nghttp2:request] block.

The function has one string parameter with the value "nghttp2:request".

Default value is 'empty' (no function is executed for events).

#### Set `event_callback` parameter

    ...
    modparam("nghttp2", "event_callback", "ksr_nghttp2_event")
    ...
    -- event callback function implemented in Lua
    function ksr_nghttp2_event(evname)
    	KSR.info("===== nghttp2 module triggered event: " .. evname .. "\n");
    	return 1;
    end
    ...

## Functions

### `nghttp2_reply(code, body)`

Send back a reply with body. The body can be empty string. Both parameters can contain variables.

#### `nghttp2_reply` usage

    ...
    event_route[nghttp2:request] {
        nghttp2_reply("200",
            "<html><body>OK</body></html>");
    }
    ...

### `nghttp2_reply_header(name, value)`

Set a header to be added to reply. There can be up to 15 headers.

#### `nghttp2_reply` usage

    ...
    event_route[nghttp2:request] {
        nghttp2_reply_header("Content-Type", "text/html");
        nghttp2_reply_header("My-Header", "xyz");
        nghttp2_reply("200",
            "<html><body>OK</body></html>");
    }
    ...

## Event Routes

### `nghttp2:request`

The event route is executed when a new HTTP request is received.

Inside it, the $nghttp2(...) group of variables is available, giving access to several attributes of the HTTP request, such as method, URL path, data (body) or headers.

    ...
    ...
    loadmodule "nghttp2.so
    ...
    event_route[nghttp2:request] {
        xinfo("request: $nghttp2(method) - url: $nghttp2(path) - data: [$nghttp2(data)]\n");
        nghttp2_reply("200", "OK", "text/html",
            "<html><body>OK</body></html>");
    }
    ...