HTTP/2 C library and tools

Nghttp2 v1.11.1

We released nghttp2 v1.11.1.

This release fixes the bug in nghttpx. The bug is that regular timeout on HTTP/1 backend makes that backend unavailable for load balancing.

Nghttp2 v1.11.0

We released nghttp2 v1.11.0.

This release fixes some bugs both in libnghttp2 and applications, and fixes minor API issue. We fixed compile error with OpenSSL 1.1.0 pre5. We also improved nghttpx functionality.

API bugs

libnghttp2 offers HPACK API. nghttp2_hd_inflate_hd() decodes incoming header block data to actual header field name/value pair. The shortcoming of its API is that its input parameter is not qualified as const. To fix this issue, we added new nghttp2_hd_inflate_hd2(). Other than the added const-ness, they share the same functionality.

Previously, nghttp2_submit_ping() ignored PING flag passed as flags parameter. This release fixes this bug.

kqueue issues

We use libev for our applications. According to the libev manual, kqueue is not selected as eligible backend for the BSD based system other than NetBSD. Because we usually use event for sockets, we explicitly enabled kqueue backend if it is available. For nghttpx, we have --no-kqueue option to disable it.

nghttp : Fixed zero length DATA frame issue

We fixed zero length DATA frame issue described in

This issue arises if nghttp client sends request body with content-length header field. If server only sends WINDOW_UPDATE with the same amount of content-length, tranfer stalls while all data have been sent. This comes from the design of libnghttp2; its nghttp2_data_source_read_callback is only called when there is at least 1 byte of flow control window. But it can completely be avoided. Since we have content-length, we can just tell libnghttp2 that we have read all data now. This effectively eliminates 0 length DATA farme

nghttpx: New attributes for mruby object, and other enhancements

In nghttpx, we added new env.server_addr, env.tls_used and env.server_port attributes. These are all documented in nghttpx manual page.

The timing when PID file is saved is pushed back, and it is now saved when setup of all listening sockets has completed. This is useful when we do graceful shutdown of nghttpx. Now we can just check PID file is changed, and then issue QUIT signal to the old process.

--backend option now has sni parameter to specify SNI field to send backend HTTPS server.

Previously, when we call fetch-ocsp-response script, we didn’t pass environ to the new program. Now we use execv to pass environ.

Previously, the proto and tls parameter in --backend option must be the same if they are the same routing pattern. Now this requirement is removed, and we can mix their combinations for the same pattern.

For HTTP/2 backend, we now consider the backend is alive only when we receive SETTINGS ACK from backend; just successfully connecting to the backend is not enough.

Nghttp2 v1.10.0

We released nghttp2 v1.10.0.

This release adds ALTSVC frame support in libnghttp2. nghttp gets new option to exercise expect/continue dance with server. nghttpx gets several new features, robust load balancing, and bug fixes.

ALTSVC frame support, and enchanced HTTP/2 extension support

ALTSVC frame is defined in RFC 7838. nghttp2’s ALTSVC frame support is very simple, and it does not parse Alt-Svc-Field-Value, and it just passes the received value to the application. This is because ALTSVC aware application most likely has a parser for this since ALTSVC can be sent via regular HTTP header field Alt-Svc.

By default, incoming ALTSVC frame is ignored. To receive ALTSVC frame, create nghttp2_option object, and use nghttp2_option_set_builtin_recv_extension_type(opt, NGHTTP2_ALTSVC), and pass the object to the nghttp2_session_client_new2() or nghttp2_session_client_new3(). Note that server always ignores ALTSVC regardless of the option settings.

To send ALTSVC frame, use nghttp2_submit_altsvc().

nghttp2 has introduced custom frame support in v1.8.0. So you can create your own ALTSVC handling if you wish.

Previously, we didn’t pass unknown incoming SETTINGS value to the application. Now those values are also passed to the application via nghttp2_on_frame_recv_callback.

nghttp : expect/continue exercises

Jacob Champion has implemented expect/continue dance with server in nghttp client. With new --expect-continue option, nghttp briefly waits for 100-continue from server before sending request body. HTTP/2 has flow control, and it is regarded as better feature for this, but this new option is useful to debug the server’s expect/continue feature since it is still supported by HTTP/2.

nghttpx: better load balancing, and bug fixes

Brian Suh fixed the bug that nghttpx returned 502 on FreeBSD (and possibly Mac OS X).

nghttpx now has the feature to detect the backend is online or offline. nghttpx’s --backend option now gets additional parameter rise=<N>, and fall=<N>. The fall=<N> specifies that if the backend cannot be connected in <N> times in a row, it is considered as offline, and excluded from load balancing group. The rise=<N> specifies that if nghttpx can connect to the offline backend in <N> times in a row, the backend is considered as online, and it is eligible for load balancing again. By default, these feature are disabled, and backend never be excluded from load balancing group.

Previously, when nghttpx could not connect to the one of backend, it did not use another backend, and just returns 5xx status code. Now it tries another backends in case of connect failure.

We fixed the bug that server push from mruby script did not work.

The server push using Link header field is extended, and now nghttpx can push resources using Link header field in non-final(1xx) response header fields from backend server.

Switch From Nginx to H2o

It is not a secret that we used nginx as backend Web server for We use nghttpx as frontend “Edge” reverse proxy, and all requests except for the ones to /httpbin were routed to nginx via HTTP/2 protocol.

Today, we have replaced backend nginx with h2o. h2o is a relatively new brazing fast Web server. Actually, we don’t require performance in our low traffic Web site. The reason we chose h2o is its better HTTP/2 implementation. Since we use HTTP/2 as backend protocol between proxy and backend server, we’d like to use better backend HTTP/2 server. h2o supports both HTTP/1.1 as well as HTTP/2 without TLS by default without extra configuration. Currently, HTTP/2 priority in the frontend proxy connection is not propagated to the backend connection, so we couldn’t utilize the great scheduling mechanism built in h2o. When we implement it, we definitely want clever HTTP/2 scheduler like h2o.

We still use nghttpx as frontend reverse proxy.

Previously, with nginx, we added link header field in nginx configuration so that nghttpx could push resource based on it. Now we initiate push using nghttpx’s mruby scripting feature. The following script initiates the push for the resource “/stylesheet/screen.css” when request path is either “/” or “/index.html”:

class App
  def on_req(env)
    req = env.req
    path = req.path
    if path == '/' || path == '/index.html'
      req.push '/stylesheets/screen.css'

And pass the file path containing the above script to nghttpx using --mruby-file option.

Nghttp2 v1.9.2

We released nghttp2 v1.9.2.

This release fixes several stability issues of nghttpx.

Nghttp2 v1.9.0

We released nghttp2 v1.9.0.

This release adds new callback functions to libnghttp2 for better debugging, and potential performance enhancements. We refactored nghttpx basic interface, and it gets many powerful features in this release. We fixed several bugs in h2load when it is used against HTTP/1.1 server. We also now have cmake build support.

New callback functions for better debugging and performance

We have added 2 new callback functions. nghttp2_error_callback is a callback that tells application about the detailed error message for human consumption. This is intended for debugging purpose.

The 2nd new callback function is nghttp2_on_header_callback2. This function is similar to existing nghttp2_on_header_callback. The crucial difference between these two is that new callback uses reference counted buffers for header field name/value. Application can increase their reference count by nghttp2_rcbuf_incref, and store its reference without copying the content. When its usage is done, don’t forget to call nghttp2_rcbuf_decref. Previously, the buffer storing header field name/value is owned solely by libnghttp2 library, and application has to copy them out if it wants to retain them for future use.

We also added new API function nghttp2_http2_strerror. This function returns text version of HTTP/2 error code (e.g., PROTOCOL_ERROR). This is useful to output debugging information about error code contained in RST_STREAM or GOAWAY frame.

We added new option nghttp2_option_set_no_auto_ping_ack, which disables automatic ping reply. Application can submit ping reply using nghttp2_submit_ping with NGHTTP2_FLAG_ACK in flags parameter.

cmake build, and more

Peter Wu has done a stellar job to add cmake build support for nghttp2. According to the PR documents, cmake build is faster than autotool build. It also supports Windows build at least for libnghttp2.

Jan-E fixed several rough edges in Makefile.msvc.

h2load bug fixes

We fixed 2 bugs in h2load when HTTP/1.1 is used. The first bug is that it did not try to connect to server again. This happens if server shutdowns the connection if it serves certain number of requests. This kind of behaviour is enabled by default for some server software.

The 2nd bug is that initial max concurrent streams was too large, and it causes undefined behaviour if -m option is not used.

nghttpx: better configuration for frontend/backend protocol and encryption

In this release, we reworked nghttpx command-line (and thus its configuration) interface. Previously, it had --http2-bridge, --client, and --client-proxy options to change its major mode. But they were quite inflexible, and became obstacles when we are extending nghttpx features. To ensure the further feature enhancements, they have been removed. Now nghttpx gets much simpler, and only has 2 modes: default mode, and HTTP/2 proxy mode (-s option). The removed modes can be achieved using other options. Read Migration from nghttpx v1.8.0 or earlier to know how to migrate from earlier release.

Now backend connections are not encrypted by default regardless of the used protocol. The exciting new feature is that backend protocol can be specified per routing pattern basis. Also the TLS can be enabled per routing pattern as well:


With above configuration, requests to /httpbin/ are routed to unix:/var/unix/httpbinsv via HTTP/1.1 protocol over cleartext TCP. The other requests are routed to via HTTP/2 protocol over TLS. tls keyword in --backend option enables encryption.

We now allow wildcard in routing pattern in --backend option. When we write:


All requests which have host (or :authority) header field whose suffix is are routed to

Since the previous release, nghttpx has got multiple frontend addresses support. Now its feature has been extended, and TLS can be enabled or disabled per frontend address. This means that single nghttpx instance finally can serve both TLS and non-TLS contents:


With the above configuration, nghttpx listens to port 443 for incoming TLS connection. It also listens to port 80, but this time for incoming cleartext connection. no-tls keyword in --frontend option disables encryption. --frontend-no-tls options has been removed in favor of no-tls keyword.

The encryption for memcached connections has been available since the previous release. In this release, we changed how to enable TLS. Now we use similar syntax for --frontend option. To enable TLS over memcached connection to get TLS ticket keys, use the following configuration:


In the above configuration, the tls keyword enables encryption.

nghttpx supports server push with Link header field with rel=preload. Now it recognizes nopush target attribute (see preload).

There are several deprecated options. If they are used, nghttpx will output warning level logging message. Please be careful for them, and they may contain the idea how to migrate to the new or existing other options.

Nghttpx: Reverse Proxied to H2 has been powered by nghttpx reverse proxy. It forwards most of the requests to backend nginx. And resources under /httpbin is forwarded to httpbin server. Previously, all backend forward link is cleartext HTTP/1.1. Now, with the new feature added to nghttpx, we forwards requests to nginx in HTTP/2 protocol.

nghttpx in the current nghttp2 master branch has a feature to specify backend protocol per host/request path routing pattern. So we just specify the following 2 options to make the above routing work:


The above configuration means that all requests whose path starts with /httpbin/ are forwarded to UNIX domain socket unix:/var/unix/httpbinsv.sock via HTTP/1.1 protocol. The rest of the requets are forwarded to server listening via HTTP/2 protocol.

The microbench mark shows that using HTTP/2 backend connection reduces backend TCP connection to about 1/100 (because of the concurrency in HTTP/2 protocol, and we coalesce frontend connections into fewer backend HTTP/2 connections), and roughly 2 times faster than HTTP/1.1 backend. HTTP/2 backend is a bit slower with default 64KiB stream window when transferring large objects, but it could be remedied by using larger window.

Nghttp2 v1.8.0

We released nghttp2 v1.8.0.

This release adds new library APIs to send and receive non-critical HTTP/2 extension frames. It also adds new features to nghttpx and nghttpd, and polishes many rough edges.

We added the APIs to send and receive non-critical HTTP/2 extension frames. “Non-critical” means that it won’t change HTTP/2 standard protocol rules, and those frames may be ignored by a receiver. We have added a set of functions and callbacks for this.

To send HTTP/2 extension frames, implement nghttp2_pack_extension_callback to encode data into wire format, and set it using nghttp2_session_callbacks_set_pack_extension_callback(). If the application wants to send multiple different types of extension frames, it should handle them in this single callback. Then use nghttp2_submit_extension() to submit a frame.

To receive HTTP/2 extension frames, implement 2 callbacks: nghttp2_unpack_extension_callback and nghttp2_on_extension_chunk_recv_callback. nghttp2_unpack_extension_callback implements the way how to decode wire format. nghttp2_on_extension_chunk_recv_callback implements how to buffer the incoming extension payload. These callbacks must be set using nghttp2_session_callbacks_set_unpack_extension_callback and nghttp2_session_callbacks_set_on_extension_chunk_recv_callback. The application also must tell the library which extension frame type it is willing to receive using nghttp2_option_set_user_recv_extension_type(). Note that the application has to create nghttp2_option object for that purpose, and initialize session with it.

Peter Wu sends many patches to fix various bugs, and rough edges, including out-of-tree documentation build and integration tests.

David Beitey documented how to build h2load, and detect the configuration error.

Bernard Spil fixed configure error related to dlopen/libdl detection on *BSD platform.

Reza Tavakoli fixed nghttp2 package version detection in Windows Makefile.

Jay Satiro refactored the portion of the code to check against HTTP/2 cipher black list. It is pretty neat.

We have updated default cipher list used in bundled applications using Security/Server Side TLS compiled by Mozilla.

We fixed compile error with gcc-6 which enables C++14 by default.

In libnghttp2_asio, we fixed the bug that connect timeout did not work. In the part of the fix, we removed nghttp2::asio_http2::client::session::connect_timeout() functon, and instead added connect timeout parameter to constructor. This will break backward compatibility.

We fixed bug in nghttpd that Trailer header field was not added when non-200 status response was returned.

We added -w and -W options to nghttpd to change stream-level and connection-level window size respectively.

nghttpx now supports multiple frontend addresses. --frontend (or -f) can be used multiple times to specify more than one frontend addresses.

nghttpx now interleaves text/html pushed resources with associated resource as well as text/css and application/javascript for Polymer use case.

We fixed the bug that nghttpx did not add headers given in add-response-headers to the response generated by mruby.

In nghttpx, we deprecated --backend-ipv4 and --backend-ipv6 in favor of new --backend-address-family option.

We have added TLS encryption support for memcached connections. We use memcached for sharing and storing TLS session cache and TLS ticket keys. We also added options to set address family, and client certificates for memcached connections.

We have added TLS encryption support for backend HTTP/1. Unlike HTTP/2 backend, backend HTTP/1 encryption is disabled by default for backward compatibility. To enable TLS, use --backend-http1-tls option. The existing option to specify client certificate is working with this as well.

We have added --no-http2-cipher-black-list to allow black listed cipher suite.

In nghttpx, we added --request-header-field-buffer and --max-request-header-fields options, and they deprecated --header-field-buffer and --max-header-fields options. To limit response headers as well, we added its response side counterparts, --response-header-field-buffer and --max-response-header-fields options.

Nghttp2 v1.7.1

We released nghttp2 v1.7.1.

This release addresses following security issue.

Security Advisory

CVE-2016-1544: Out of memory in nghttpd, nghttp, and libnghttp2_asio applications due to unlimited incoming HTTP header fields.


nghttpd, nghttp, and libnghttp2_asio applications do not limit the memory usage for the incoming HTTP header field. If peer sends specially crafted HTTP/2 HEADERS frames and CONTINUATION frames, they will crash with out of memory error.

HTTP/2 uses HPACK to compress header fields. The basic idea is that HTTP header field is stored in the receiver with the numeric index number. The memory used by this storage is tightly constrained, and it is 4KiB by default. When sender sends the same header field, it just sends the corresponding numeric index number, which is usually 1 or 2 bytes. This means that after sender makes the receiver store the relatively large header field (e.g., 4KiB), and it can send specially crafted HEADERS/CONTINUATION frames which contain a lot of references to the stored header field, sender easily effectively send lots of big header fields to the receiver quite easily. nghttpd, nghttp, and libnghttp2_asio applications do not limit the memory usage for received header fields, so if the peer performs the procedure described above, they will crash due to out of memory.

Note that libnghttp2 itself is not affected by this vulnerability.

Affected Versions

  • Affected versions: nghttp2 <= 1.7.0
  • Not affected versions: nghttp2 >= 1.7.1

The Solution

Install nghttp2 v1.7.1

Time Line

It was first reported to the nghttp2 team February 3 2016.

nghttp2 v1.7.1 was released on February 11 2016.


Reported by Noam Mazor. Fixed by the nghttp2 team.

Thank you for all who involved.

This security advisory format is inspired from curl/libcurl project.