H2O

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

Powered by Oktavia

Install

Release Policy

As of April 2023, we have ceased to release versions. Rather, the each commit to master branch is considered stable and ready for general use except for the features marked as experimental.

Dependencies

H2O requires the following softwares to be installed:

Additional softwares may be required for using certain features. As an example, to build the mruby handler, bison and ruby have to be installed.

Installing from Source

First, clone the master branch from the source repository as well as the submodules. 

% git clone --recurse-submodules https://github.com/h2o/h2o.git

Then, build the obtained source using CMake2. 

% cd h2o
% 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.

-DCMAKE_INSTALL_PREFIX=directory
This option specifies the directory to which H2O will be installed (default: /usr/local).
-DWITH_MRUBY=on|off
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.
-DWITH_DTRACE=on|off
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.
-DWITH_H2OLOG=on|off
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.
-DOPENSSL_ROOT_DIR=/path/to/openssl
On most platforms, OpenSSL is automatically found by the FindOpenSSL.cmake module. This option is used when the automatic detection fails or if an alternative version of the TLS stack is to be used.
-DCMAKE_C_FLAGS=...
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".
-DCMAKE_BUILD_TYPE=Release|Debug
This option specifies the build type, Release or Debug. The default is Release.

Installing a Binary Package

Thanks to others, H2O is provided as a binary package on some environments. Up-to-date versions of H2O might be found at the following locations.

Notes:

  1. At the time of writing, H2O can be built with libressl and boringssl.
  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.