webdis

About Webdis

A very simple web server providing an HTTP interface to Redis. It embeds hiredis, jansson (with some local changes), and http-parser. It also depends on libevent, to be installed separately.

Build and run from source

Building Webdis requires the libevent development package. You can install it on Ubuntu by typing sudo apt-get install libevent-dev or on macOS by typing brew install libevent.

To build Webdis with support for encrypted connections to Redis, see Building Webdis with SSL support.

$ make clean all

$ ./webdis &

$ curl http://127.0.0.1:7379/SET/hello/world
→ {"SET":[true,"OK"]}

$ curl http://127.0.0.1:7379/GET/hello
→ {"GET":"world"}

$ curl -d "GET/hello" http://127.0.0.1:7379/
→ {"GET":"world"}

Configuration

Webdis is configured by a configuration file in JSON format, provided to the server as a command-line parameter:

./webdis /path/to/webdis.json

At start-up, Webdis will look for a file named webdis.json in the current directory if no file is specified on the command line.

This repository comes with a sample configuration file named webdis.json, to be used for local evaluation. Another file, webdis.prod.json, is provided as a starting point to build a production configuration file. Do not use either of these files in production without reviewing them.

The various features of Webdis are documented in this README.

Try in Docker

$ docker run --name webdis-test --rm -d -p 127.0.0.1:7379:7379 nicolas/webdis
0d2ce311a4834d403cc3e7cfd571b168ba40cede6a0e155a21507bb0bf7bee81

$ curl http://127.0.0.1:7379/PING
{"PING":[true,"PONG"]}

# To stop it:
$ docker stop webdis-test
webdis-test

Docker repositories and image signatures

Webdis images are published on Docker Hub and Amazon ECR. Starting with release 0.1.24, images (including latest) are signed with cosign using the public key webdis.pub at the root of this repository. For the public-key fingerprint, multi-architecture verification, and the chain of trust, see Image signing with cosign. Releases 0.1.12 through 0.1.23 were signed with Docker Content Trust, which has since been deprecated.

Docker Hub

$ docker pull nicolas/webdis:0.1.25
$ docker pull nicolas/webdis:latest

Verify the signature with cosign:

$ cosign verify --key webdis.pub nicolas/webdis:0.1.25

When this verification is successful, you should see a message like this:

Verification for public.ecr.aws/nicolas/webdis:0.1.25 --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key

The image is signed recursively, so verification covers the multi-arch index and each per-architecture manifest under it.

Amazon Elastic Container Registry (ECR)

$ docker pull public.ecr.aws/nicolas/webdis:0.1.25
$ docker pull public.ecr.aws/nicolas/webdis:latest

ECR images share the same digests as their Docker Hub counterparts, and the cosign signatures are mirrored alongside them. The same cosign verify command works against ECR:

$ cosign verify --key webdis.pub public.ecr.aws/nicolas/webdis:0.1.25

Multi-architecture images

Starting with release 0.1.19, Docker images for Webdis are published as manifest lists supporting multiple architectures. Each release points to an x86-64 image and an ARM64v8 image:

$ docker manifest inspect nicolas/webdis:0.1.19 | jq -r '.manifests | .[] | .platform.architecture + " -> " + .digest'
amd64 -> sha256:2ced2d99146e1bcaf10541d17dbac573cffd02237c3b268875be1868138d3b54
arm64 -> sha256:d026c5675552947b6a755439dfd58360e44a8860436f4eddfe9b26d050801248

By default docker pull will download only the relevant image for your architecture, but you can specify the platform to download the image for a specific architecture, e.g.

$ docker pull nicolas/webdis:0.1.19 --platform linux/arm64/v8

Build and run a Docker image locally

Clone the repository and open a terminal in the webdis directory, then run:

$ docker build -t webdis:custom .
[...]

$ docker run --name webdis-test --rm -d -p 127.0.0.1:7379:7379 webdis:custom
f0a2763fd456ac1f7ebff80eeafd6a5cd0fc7f06c69d0f7717fb2bdcec65926e

$ curl http://127.0.0.1:7379/PING
{"PING":[true,"PONG"]}

To stop it:

$ docker stop webdis-test
webdis-test

Docker images and embedded Redis

:information_source: The Docker images provided on Docker Hub under nicolas/webdis contain both Webdis and an embedded Redis server. They were built this way to make it easy to try Webdis without having to configure a Docker deployment with two containers, but this is likely not the best way to run Webdis in production.

The following documentation pages cover various such use cases:

• Running Webdis in Docker with an external Redis instance
• Running Webdis and Redis in Docker Compose
• Running Webdis and Redis in Docker Compose with SSL connections

More articles are available in the Webdis documentation.

Building Webdis with SSL support

Webdis needs libraries that provide TLS support to encrypt its connections to Redis:

• On Alpine Linux, install openssl-dev with apk-add openssl-dev.
• On Ubuntu, install libssl-dev with apt-get install libssl-dev.
• On macOS with HomeBrew, install OpenSSL with brew install [email protected].

Then, build Webdis with SSL support enabled:

$ make SSL=1

Configuring Webdis with SSL

Once Redis is configured with SSL support (see this guide for step-by-step instructions), you can configure Webdis to connect to Redis over encrypted connections.

Add a block to webdis.json under a key named "ssl" placed at the root level, containing the following object:

{
    "enabled": true,
    "ca_cert_bundle": "/path/to/ca.crt",
    "path_to_certs": "/path/to/trusted/certs",
    "client_cert": "/path/to/redis.crt",
    "client_key": "/path/to/redis.key",
    "redis_sni": "redis.mydomain.tld"
}

This means that "ssl" should be at the same level as "redis_host", "redis_port", etc.

Important: the presence of the "ssl" configuration block alone does not necessarily enable secure connections to Redis. The key "enabled" inside this block must also be set to true, otherwise Webdis will keep using unencrypted connections.

Use the following table to match the Redis configuration keys to the fields under "ssl" in webdis.json:

Redis field Webdis field Purpose tls-cert-file client_cert Client certificate tls-key-file client_key Client key tls-ca-cert-file ca_cert_bundle CA certificate bundle

Two other keys have no equivalent in redis.conf:

• path_to_certs is an optional directory path where trusted CA certificate files are stored in an OpenSSL-compatible format.
• redis_sni is an optional Redis server name, used as a server name indication (SNI) TLS extension.

See also the Hiredis docs and Hiredis source code for more information.

Running Redis and Webdis with SSL in Docker Compose

For a full tutorial showing how to configure and run Redis and Webdis under Docker Compose with SSL connections between the two services, head to the docs folder and open Running Webdis & Redis in Docker Compose with SSL connections.

SSL troubleshooting

Follow this table to diagnose issues with SSL connections to Redis.

Error message or issue Cause Solution Unexpected key or incorrect value in webdis.json: 'ssl' Webdis is not compiled with SSL support Build webdis with make SSL=1 Unexpected key or incorrect value under 'ssl' Invalid configuration One or more keys in the ssl object in was not recognized, make sure they are all valid Failed to load client certificate Invalid client certificate Verify the file that client_cert points to Failed to load private key Invalid client key Verify the file that client_key points to Failed to load CA Certificate or CA Path Invalid CA certificate bundle Verify the file that ca_cert_bundle points to All requests fail with HTTP 503, logs show "Error disconnecting: Connection reset by peer" SSL disabled in config but Webdis connected to an SSL port Make sure enabled is set to true and that Webdis connects to the SSL port for Redis Logs show "Server closed the connection" at start-up SSL connection failed The client key and/or client certificate was missing. Make sure the configuration is valid. No error but all requests hang Webdis connected to the non-SSL port Make sure Webdis is connecting to the port set under tls-port in redis.conf

Features

• GET and POST are supported, as well as PUT for file uploads (see example of PUT usage here).
• JSON output by default, optional JSONP parameter (?jsonp=myFunction or ?callback=myFunction).
• Raw Redis 2.0 protocol output with .raw suffix.
• MessagePack output with .msg suffix.
• HTTP 1.1 pipelining (70,000 http requests per second on a desktop Linux machine.)
• Multi-threaded server, configurable number of worker threads.
• WebSocket support (Currently using the specification from RFC 6455).
• Connects to Redis using a TCP or UNIX socket.
• Support for secure connections to Redis (requires Redis 6 or newer).
• Support for "Keep-Alive" connections to Redis: add "hiredis": { "keep_alive_sec": 15 } to webdis.json to enable it with the default value. See the Hiredis documentation for details, the value configured in webdis.json is the interval passed to redisEnableKeepAliveWithInterval. Important: note how it is used to set the value for TCP_KEEPALIVE (the same value) and to compute the value for TCP_KEEPINTVL (integer, set to 1/3 × interval).
• Restricted commands by IP range (CIDR subnet + mask) or HTTP Basic Auth, returning 403 errors.
• Support for Redis authentication in the config file: set redis_auth to a single string to use a password value, or to an array of two strings to use username+password auth (new in Redis 6.0).
• Environment variables can be used as values in the config file, starting with $ and in all caps (e.g. $REDIS_HOST).
• Pub/Sub using Transfer-Encoding: chunked, works with JSONP as well. Webdis can be used as a Comet server.
• D