From be1c7e50e1e8809ea56f2c9d472eccd8ffd73a97 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 04:57:58 +0200 Subject: Adding upstream version 1.44.3. Signed-off-by: Daniel Baumann --- web/server/h2o/libh2o/srcdoc/install.mt | 121 ++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 web/server/h2o/libh2o/srcdoc/install.mt (limited to 'web/server/h2o/libh2o/srcdoc/install.mt') diff --git a/web/server/h2o/libh2o/srcdoc/install.mt b/web/server/h2o/libh2o/srcdoc/install.mt new file mode 100644 index 00000000..e2a37134 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/install.mt @@ -0,0 +1,121 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Install")->(sub { + +

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 maintained{note}->(q{Please open a new issue on Github if you want a new package to get added.}) ?>: +

+

+ +

Installing from Source

+ +

+Download a release version from the releases page or clone the master branch from the source repository, and build it using CMake{note}->("CMake is a popular build tool that can be found as a binary package on most operating systems.") ?>. +

+ +{code}->(<< 'EOT') +% cmake -DWITH_BUNDLED_SSL=on . +% make +% sudo make install +EOT +?> + +

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

+ +{code}->(<< 'EOT') +% /usr/local/bin/h2o -c examples/h2o/h2o.conf +EOT +?> + +

+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_BUNDLED_SSL=on|off
+
+This option instructs whether or not to use LibreSSL being bundled (default: off if OpenSSL version >= 1.0.2 is found, on if otherwise). Read the section below for comparison between OpenSSL and LibreSSL. +
+
-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 files{note}->(q{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.}) ?>) are found. +
+

+ +

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 Chrome{note}->(q{ref: Do the ChaCha: better mobile performance with cryptography}) ?>. 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.2{note}->("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.") ?>. 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. As an safeguard it is advised to use -DWITH_BUNDLED_SSL set to off, so that the server would not accidentally link against the bundled LibreSSL. +CMake will search for OpenSSL by looking at the default search paths. +

+ +{code}->(<< 'EOT') +% cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +

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

+ +{code}->(<< 'EOT') +% PKG_CONFIG_PATH=/usr/local/openssl-1.0.2/lib/pkgconfig cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +

+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 approach{note}->(q{ref: h2o issue #277, CMake issue 0015386}) ?>. +

+ +{code}->(<< 'EOT') +% OPENSSL_ROOT_DIR=/usr/local/openssl-1.0.2 cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +? }) -- cgit v1.2.3