Lwan Web Server

Lwan is a high-performance & scalable web server.

The project web site contains more details.

Build status

| OS | Arch | Release | Debug | Static Analysis | Tests | |-------------|--------|---------|-------|-----------------|------------| | Linux | x86_64 | | | Report history | | | FreeBSD 14 | x86_64 | | | | | | OpenBSD 7.4 | x86_64 | | | | |

Installing

You can either build Lwan yourself, use a container image, or grab a package from your favorite distribution.

Building

Before installing Lwan, ensure all dependencies are installed. All of them are common dependencies found in any GNU/Linux distribution; package names will be different, but it shouldn't be difficult to search using whatever package management tool that's used by your distribution.

Required dependencies

• CMake, at least version 2.8
• libdeflate, zlib-ng or ZLib

Optional dependencies

The build system will look for these libraries and enable/link if available.

• Lua 5.1 or LuaJIT 2.0
• Valgrind
• Brotli
  • Can be disabled by passing -DENABLE_BROTLI=NO
• ZSTD
  • Can be disabled by passing -DENABLE_ZSTD=NO
• On Linux builds, if -DENABLE_TLS=ON (default) is passed:
  • mbedTLS
• Alternative memory allocators can be used by passing -DUSE_ALTERNATIVE_MALLOC to CMake with the following values:
  • "mimalloc"
  • "jemalloc"
  • "tcmalloc"
  • "auto": Autodetect from the list above, falling back to libc malloc if none found
• To run test suite:
  • Python (2.6+) with Requests
  • Lua 5.1
• To run benchmark:
  • Weighttp -- bundled and built alongside Lwan for convenience
  • Matplotlib
• To build TechEmpower benchmark suite:
  • Client libraries for MariaDB
  • SQLite 3

Common operating system package names

Minimum to build

• ArchLinux: pacman -S cmake zlib-ng pkgconf
• FreeBSD: pkg install cmake pkgconf
• Debian and Ubuntu 14+: apt-get update && apt-get install git cmake zlib1g-dev pkg-config
• macOS: brew install cmake

Build with all optional features

• ArchLinux: pacman -S cmake zlib-ng pkgconf sqlite luajit mariadb-libs gperftools valgrind mbedtls
• FreeBSD: pkg install cmake pkgconf sqlite3 lua51
• Debian and Ubuntu 14+: apt-get update && apt-get install git cmake zlib1g-dev pkg-config lua5.1-dev libsqlite3-dev libmariadb-dev libmbedtls-dev
• macOS: brew install cmake mariadb-connector-c sqlite lua@5.1 pkg-config

Build commands

Clone the repository

~$ git clone git://github.com/lpereira/lwan
~$ cd lwan

Create the build directory

~/lwan$ mkdir build
~/lwan$ cd build

Select build type

Selecting a release version (no debugging symbols, messages, enable some optimizations, etc):

~/lwan/build$ cmake .. -DCMAKE_BUILD_TYPE=Release

If you'd like to enable optimizations but still use a debugger, use this instead:

~/lwan/build$ cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo

To disable optimizations and build a more debugging-friendly version:

~/lwan/build$ cmake .. -DCMAKE_BUILD_TYPE=Debug

Build Lwan

~/lwan/build$ make

This will generate a few binaries:

• src/bin/lwan/lwan: The main Lwan executable. May be executed with --help for guidance.
• src/bin/testrunner/testrunner: Contains code to execute the test suite (src/scripts/testsuite.py).
• src/samples/freegeoip/freegeoip: FreeGeoIP sample implementation. Requires SQLite.
• src/samples/techempower/techempower: Code for the TechEmpower Web Framework benchmark. Requires SQLite and MariaDB libraries.
• src/samples/clock/clock: Clock sample. Generates a never-ending animated GIF file that always shows the local time.
• src/samples/forthsalon/forthsalon: Generates a never-ending animated GIF from a program written in the Forth Salon dialect of the Forth programming language. In construction!
• src/samples/forthsalon/forth: Test harness for the Forth dialect used in the forthsalon sample.
• src/bin/tools/mimegen: Builds the extension-MIME type table. Used during the build process.
• src/bin/tools/bin2hex: Generates a C file from a binary file, suitable for use with #include. Used during the build process.
• src/bin/tools/configdump: Dumps a configuration file using the configuration reader API. Used for testing.
• src/bin/tools/weighttp: Rewrite of the weighttp HTTP benchmarking tool.
• src/bin/tools/statuslookupgen: Generates a perfect hash table for HTTP status codes and their descriptions. Used during the build process.

Remarks

Passing -DCMAKE_BUILD_TYPE=Release will enable some compiler optimizations (such as LTO) and tune the code for current architecture.

[!IMPORTANT]

Please use the release build when benchmarking. The default is the Debug build, which not only logs all requests to the standard output, but does so while holding a lock, severely holding down the server.

The default build (i.e. not passing -DCMAKE_BUILD_TYPE=Release) will build a version suitable for debugging purposes. This version can be used under Valgrind (if its headers are present) and includes debugging messages that are stripped in the release version. Debugging messages are printed for each and every request.

On these builds, sanitizers can be enabled. To select which one to build Lwan with, specify one of the following options to the CMake invocation line:

• -DSANITIZER=ubsan selects the Undefined Behavior Sanitizer.
• -DSANITIZER=address selects the Address Sanitizer.
• -DSANITIZER=thread selects the Thread Sanitizer.

Alternative memory allocators can be selected as well. Lwan currently supports TCMalloc, mimalloc, and jemalloc out of the box. To use either one of them, pass -DALTERNATIVE_MALLOC=name to the CMake invocation line, using the names provided in the "Optional dependencies" section.

The -DUSE_SYSLOG=ON option can be passed to CMake to also log to the system log in addition to the standard output.

If you're building Lwan for a distribution, it might be wise to use the -DMTUNE_NATIVE=OFF option, otherwise the generated binary may fail to run on some computers.

TLS support is enabled automatically in the presence of a suitable mbedTLS installation on Linux systems with headers new enough to support kTLS, but can be disabled by passing -DENABLE_TLS=NO to CMake.

Tests

~/lwan/build$ make testsuite

This will compile the testrunner program and execute regression test suite in src/scripts/testsuite.py.

Benchmark

~/lwan/build$ make benchmark

This will compile testrunner and execute benchmark script src/scripts/benchmark.py.

Coverage

Lwan can also be built with the Coverage build type by specifying -DCMAKE_BUILD_TYPE=Coverage. This enables the generate-coverage make target, which will run testrunner to prepare a test coverage report with lcov.

Every commit in this repository triggers the generation of this report, and results are publicly available.

Running

Set up the server by editing the provided lwan.conf; the format is explained in details below.

[!NOTE]

Lwan will try to find a configuration file based in the executable name in the current directory; testrunner.conf will be used for the testrunner binary, lwan.conf for the lwan binary, and so on.

Configuration files are loaded from the current directory. If no changes are made to this file, running Lwan will serve static files located in the ./wwwroot directory. Lwan will listen on port 8080 on all interfaces.

Lwan will detect the number of CPUs, will increase the maximum number of open file descriptors and generally try its best to autodetect reasonable settings for the environment it's running on. Many of these settings can be tweaked in the configuration file, but it's usually a good idea to