the optimized HTTP/1.x, HTTP/2 server

Powered by Oktavia


Installing a Binary Package

Thanks to others, H2O is provided as a binary package on some environments. Therefore you may try to at first install the software using your favorite packaging system, and then resort to installing from source as described below.

At the time being, following packages are known to be actively maintained1:

Installing from Source

First, either download a release version from the releases page, or clone the master branch from the source repository. When cloning, submodules should also be fetched, e.g., by running git clone --recurse-submodules.

Then, build the obtained source using CMake2.

% mkdir -p build
% cd build
% cmake ..
% make
% sudo make install

When complete, H2O will be installed under /usr/local.

Start the installed server using the example configuration to confirm that it actually works (note: without the use of -m option the server runs as a foreground process; press Ctrl-C to stop).

% /usr/local/bin/h2o -c examples/h2o/h2o.conf

Or if you'd like to start H2O without installing it, you can use the H2O_ROOT environment variable.

% H2O_ROOT=$PWD build/h2o -c examples/h2o/h2o.conf

The example configuration starts a server that listens to port 8080 (HTTP) and port 8081 (HTTPS). Try to access the ports using the protocols respectively (note: when accessing via HTTPS it is likely that you would see hostname mismatch errors reported by the web browsers).

When complete, proceed to Configure section for how to setup the server.

CMake Options

Following list shows the interesting arguments recognized by CMake.

This option specifies the directory to which H2O will be installed (default: /usr/local).
This option instructs whether or not to build the standalone server with support for scripting using mruby. It is turned on by default if the prerequisites (bison, ruby and the development files3) are found.
This option instructs whether or not to enable DTrace support. It is turned on by default if the prerequisites (SystemTap on Linux, or DTrace on macOS) are found. See also wiki/macOS to use DTrace on macOS.
This option instructs whether or not to enable h2olog(1)> support. It is turned on by default if the prerequisites are found. See also h2olog for details.
This option can be used to add or override the compile options being passed to the C compiler. As an example, AddressSanitizer (ASan) can be enabled when using recent versions of GCC or Clang, by passing -DCMAKE_C_FLAGS="-fsanitize=address -fno-stack-protector -fno-omit-frame-pointer".
This option specifies the build type, Release or Debug. The default is Release.

Installing from Source, using OpenSSL

Generally speaking, we believe that using LibreSSL is a better choice for running H2O, since LibreSSL not only is considered to be more secure than OpenSSL but also provides support for new ciphersuites such as chacha20-poly1305 which is the preferred method of Google Chrome4. However, it is also true that LibreSSL is slower than OpenSSL on some benchmarks. So if you are interested in benchmark numbers, using OpenSSL is a reasonable choice.

The difficulty in using OpenSSL is that the HTTP/2 specification requires the use of an extension to the TLS protocol named ALPN, which has only been supported since OpenSSL 1.0.25. Therefore it is highly likely that you would need to manually install or upgrade OpenSSL on your system.

Once you have installed OpenSSL 1.0.2, it is possible to build H2O that links against the library. CMake will search for OpenSSL by looking at the default search paths.

% mkdir -p build
% cd build
% cmake ..
% make
% sudo make install

Two ways exist to specify the directory in which CMake should search for OpenSSL. The preferred approach is to use the PKG_CONFIG_PATH environment variable.

% mkdir -p build
% cd build
% PKG_CONFIG_PATH=/usr/local/openssl-1.0.2/lib/pkgconfig cmake ..
% make
% sudo make install

In case your OpenSSL installation does not have the lib/pkgconfig directory, you may use OPENSSL_ROOT_DIR environment variable to specify the root directory of the OpenSSL being installed. However, it is likely that CMake version 3.1.2 or above is be required when using this approach6.

% mkdir -p build
% cd build
% OPENSSL_ROOT_DIR=/usr/local/openssl-1.0.2 cmake ..
% make
% sudo make install


  1. Please open a new issue on Github if you want a new package to get added.
  2. CMake is a popular build tool that can be found as a binary package on most operating systems.
  3. mkmf - a program for building ruby extensions is required. In many distributions, the program is packaged as part of ruby-dev or ruby-devel package.
  4. ref: Do the ChaCha: better mobile performance with cryptography
  5. It is possible to build H2O using prior versions of OpenSSL, but some (if not all) web browsers are known for not using HTTP/2 when connecting to servers configured as such.
  6. ref: h2o issue #277, CMake issue 0015386