Redis 中文文档
Build

About Webdis


A very simple web server providing an HTTP interface to Redis. It uses hiredis, jansson, libevent, and http-parser.

Webdis depends on libevent-dev. 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.

Build and run from source


  1. ``` shell
  2. $ make clean all

  4. $ ./webdis &

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

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

  12. $ curl -d "GET/hello" http://127.0.0.1:7379/
  13. → {"GET":"world"}
  14. ```

Try in Docker


  1. ``` shell
  2. $ docker run --name webdis-test --rm -d -p 127.0.0.1:7379:7379 nicolas/webdis
  3. 0d2ce311a4834d403cc3e7cfd571b168ba40cede6a0e155a21507bb0bf7bee81

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

  8. # To stop it:
  9. $ docker stop webdis-test
  10. 0d2ce311a483
  11. ```

Docker repositories and Docker Content Trust


Webdis images are published on Docker Hub and Amazon ECR.

Docker Hub


  1. ``` shell
  2. $ docker pull nicolas/webdis:0.1.21
  3. $ docker pull nicolas/webdis:latest
  4. ```

Starting from release 0.1.12 and including latest, Docker Hub images are signed (download public key ). You should see the following key ID if you verify the trust:

  1. ``` sh
  2. $ docker trust inspect nicolas/webdis:0.1.21 --pretty

  4. Signatures for nicolas/webdis:0.1.21

  6. SIGNED TAG   DIGEST                                                             SIGNERS
  7. 0.1.21       bea53be391b11fd8a33d55c5e3d49eb11c4c2f89e9e82ca70b3a91bc9c9aa208   (Repo Admin)

  9. List of signers and their keys for nicolas/webdis:0.1.21

  11. SIGNER      KEYS
  12. nicolasff   dd0768b9d35d

  14. Administrative keys for nicolas/webdis:0.1.21

  16.   Repository Key: fed0b56b8a8fd4d156fb2f47c2e8bd3eb61948b72a787c18e2fa3ea3233bba1a
  17.   Root Key: 40be21f47831d593892370a8e3fc5bfffb16887c707bd81a6aed2088dc8f4bef

  19. ```

The signing keys are listed on this documentation page ; please make sure they match what you see.

Amazon Elastic Container Registry (ECR)


  1. ``` shell
  2. $ docker pull public.ecr.aws/nicolas/webdis:0.1.21
  3. $ docker pull public.ecr.aws/nicolas/webdis:latest
  4. ```

A note on ECR and trust:AWS does not support Notary v2 at the time of this writing, although a security talk from 2020 mentions that the feature could be available in 2021.

The consequence is that Webdis images on ECR are not signed at this time.

They can still be verified, since the images uploaded there use the exact same hash as the ones on Docker Hub, which aresigned. This means that you can verify the signature using the docker trust inspect command described above, as long as you alsomake sure that the image hash associated with the image on ECR matches the one shown on Docker Hub.

For more details about Content Trust validation with ECR images, refer to the article titled Webdis and Docker Content Trust in the Webdis documentation.

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:

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

  6. ```

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.

  1. ``` sh
  2. $ docker pull nicolas/webdis:0.1.19 --platform linux/arm64/v8

  4. ```

Build and run a Docker image locally


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

  1. ``` shell
  2. $ docker build -t webdis:custom .
  3. [...]

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

  8. $ curl http://127.0.0.1:7379/PING
  9. {"PING":[true,"PONG"]}
  10. ```

To stop it:

  1. ``` sh
  2. $ docker stop webdis-test
  3. f0a2763fd456

  5. ```

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 openssl@1.1.

Then, build Webdis with SSL support enabled:

  1. ``` shell
  2. $ make SSL=1
  3. ```

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:

  1. ``` json
  2. {
  3.     "enabled": true,
  4.     "ca_cert_bundle": "/path/to/ca.crt",
  5.     "path_to_certs": "/path/to/trusted/certs",
  6.     "client_cert": "/path/to/redis.crt",
  7.     "client_key": "/path/to/redis.key",
  8.     "redis_sni": "redis.mydomain.tld"
  9. }
  10. ```

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 mustalso 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 ).
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.
Drop privileges on startup.
Custom Content-Type using a pre-defined file extension, or with ?type=some/thing.
URL-encoded parameters for binary data or slashes and question marks. For instance, %2f is decoded as / but not used as a command separator.
Logs, with a configurable verbosity.
Configurable fsync frequency for the log file:
Set "log_fsync": "auto" (default) to let the file system handle file persistence on its own.
Set "log_fsync": N where N is a number to call fsync every N milliseconds.
Set "log_fsync": "all" (very slow) to persist the log file to its storage device on each log message.

Cross-origin requests, usable with XMLHttpRequest2 (Cross-Origin Resource Sharing - CORS).
File upload with PUT.
With the JSON output, the return value of INFO is parsed and transformed into an object.
Optionally run as a daemon process: set "daemonize": true and "pidfile": "/var/run/webdis.pid" in webdis.json.
Default root object: Add "default_root": "/GET/index.html" in webdis.json to substitute the request to / with a Redis request.
HTTP request limit with http_max_request_size (in bytes, set to 128 MB by default).
Database selection in the URL, using e.g. /7/GET/key to run the command on DB 7.

Ideas, TODO…


Add better support for PUT, DELETE, HEAD, OPTIONS? How? For which commands?
This could be done using a “strict mode” with a table of commands and the verbs that can/must be used with each command. Strict mode would be optional, configurable. How would webdis know of new commands remains to be determined.

MULTI/EXEC/DISCARD/WATCH are disabled at the moment; find a way to use them.
Support POST of raw Redis protocol data, and execute the whole thing. This could be useful for MULTI/EXEC transactions.
Enrich config file:
Provide timeout (maybe for some commands only?). What should the response be? 504 Gateway Timeout? 503 Service Unavailable?

Multi-server support, using consistent hashing.
SSL/TLS?
It makes more sense to terminate SSL with nginx used as a reverse-proxy.

SPDY?
SPDY is mostly useful for parallel fetches. Not sure if it would make sense for Webdis.

Send your ideas using the github tracker, on twitter @yowgi or by e-mail to n.favrefelix@gmail.com.

HTTP error codes


Unknown HTTP verb: 405 Method Not Allowed.
Redis is unreachable: 503 Service Unavailable.
Matching ETag sent using If-None-Match : 304 Not Modified.
Could also be used:
Timeout on the redis side: 503 Service Unavailable.
Missing key: 404 Not Found.
Unauthorized command (disabled in config file): 403 Forbidden.

Command format


The URI /COMMAND/arg0/arg1/.../argN.ext executes the command on Redis and returns the response to the client. GET, POST, and PUT are supported:

GET /COMMAND/arg0/.../argN.ext
POST / with COMMAND/arg0/.../argN in the HTTP body.
PUT /COMMAND/arg0.../argN-1 with argN in the HTTP body (see section on file uploads.)

.ext is an optional extension; it is not read as part of the last argument but only represents the output format. Several formats are available (see below).

Special characters: / and . have special meanings, / separates arguments and . changes the Content-Type. They can be replaced by %2f and %2e, respectively.

Redis authentication


Webdis can connect to a Redis server that requires credentials. For Redis versions before 6.0, provide the password as a single string in webdis.json using the key "redis_auth". For example:

  1. ``` json
  2. "redis_auth": "enter-password-here"
  3. ```

Redis 6.0 introduces a more granular access control system and switches from a single password to a pair of username and password. To use these two values with Webdis, set "redis_auth" to an array containing the two strings, e.g.

  1. ``` json
  2. "redis_auth": ["my-username", "my-password"]
  3. ```

This new authentication system is only supported in Webdis 0.1.13 and above.

ACL


Access control is configured in webdis.json. Each configuration tries to match a client profile according to two criteria:

CIDR subnet + mask
HTTP Basic Auth in the format of "user:password".

Each ACL contains two lists of commands, enabled and disabled. All commands being enabled by default, it is up to the administrator to disable or re-enable them on a per-profile basis.

Examples:

  1. ``` json
  2. {
  3. "disabled": ["DEBUG", "FLUSHDB", "FLUSHALL"],
  4. },

  6. {
  7. "http_basic_auth": "user:password",
  8. "disabled":        ["DEBUG", "FLUSHDB", "FLUSHALL"],
  9. "enabled":         ["SET"]
  10. },

  12. {
  13. "ip":      "192.168.10.0/24",
  14. "enabled": ["SET"]
  15. },

  17. {
  18. "http_basic_auth": "user:password",
  19. "ip":              "192.168.10.0/24",
  20. "enabled":         ["SET", "DEL"]
  21. }
  22. ```

ACLs are interpreted in order, later authorizations superseding earlier ones if a client matches several. The special value "*" matches all commands.

Environment variables


Environment variables can be used in webdis.json to read values from the environment instead of using constant values. For this, the value must be a string starting with a dollar symbol and written in all caps. For example, to make the redis host and port configurable via environment variables, use the following:

  1. ``` json
  2. {
  3. "redis_host": "$REDIS_HOST",
  4. "redis_port": "$REDIS_PORT",
  5. }
  6. ```

JSON output


JSON is the default output format. Each command returns a JSON object with the command as a key and the result as a value.

Examples:

  1. ``` shell
  2. // string
  3. $ curl http://127.0.0.1:7379/GET/y
  4. {"GET":"41"}

  6. // number
  7. $ curl http://127.0.0.1:7379/INCR/y
  8. {"INCR":42}

  10. // list
  11. $ curl http://127.0.0.1:7379/LRANGE/x/0/1
  12. {"LRANGE":["abc","def"]}

  14. // status
  15. $ curl http://127.0.0.1:7379/TYPE/y
  16. {"TYPE":[true,"string"]}

  18. // error, which is basically a status
  19. $ curl http://127.0.0.1:7379/MAKE-ME-COFFEE
  20. {"MAKE-ME-COFFEE":[false,"ERR unkn