NGHTTP2 Module

Daniel-Constantin Mierla

Edited by

Daniel-Constantin Mierla

Copyright © 2024 asipto.com

Table of Contents

1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. listen_addr (str)
3.2. listen_port (str)
3.3. event_callback (str)
4. Functions
4.1. nghttp2_reply(code, body)
4.2. nghttp2_reply_header(name, value)
5. Event Routes
5.1. nghttp2:request

List of Examples

1.1. Set listen_addr parameter
1.2. Set listen_port parameter
1.3. Set event_callback parameter
1.4. nghttp2_reply usage
1.5. nghttp2_reply usage

Chapter 1. Admin Guide

Table of Contents

1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. listen_addr (str)
3.2. listen_port (str)
3.3. event_callback (str)
4. Functions
4.1. nghttp2_reply(code, body)
4.2. nghttp2_reply_header(name, value)
5. Event Routes
5.1. nghttp2:request

1. Overview

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

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

  • none.

2.2. 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+)

3. Parameters

3.1. 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).

Example 1.1. Set listen_addr parameter 

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

3.2. listen_port (str)

Port or service name to listen for HTTP2 connection.

Default value is "8282".

Example 1.2. Set listen_port parameter 

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

3.3. 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).

Example 1.3. 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
...

4. Functions

4.1.  nghttp2_reply(code, body)

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

Example 1.4. nghttp2_reply usage 

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

4.2.  nghttp2_reply_header(name, value)

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

Example 1.5. 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>");
}
...

5. Event Routes

5.1.  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>");
}
...