Skip to content

keyval: Nginx module for the key-value store

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-keyval

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-keyval

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_keyval_module.so;

This document describes nginx-module-keyval v0.4.0 released on Mar 30 2026.

Overview

nginx-keyval is a key-value store dynamic module for nginx. It was developed inspired by the commercial version of nginx's ngx_http_keyval_module.

License: MIT License

Key Features

  • Dual Backend: Supports two types of storage backends: shared memory (SHM) and Redis
  • HTTP / Stream Support: Works in both HTTP and Stream contexts
  • TTL Support: Configurable expiration time for key-value pairs
  • Composite Keys: Build keys by combining multiple variables and literal strings (e.g., $remote_addr:$http_user_agent)
  • Variable Expansion: Use nginx variables as keys, dynamically expanded at runtime

Quick Start

See INSTALL.md for installation instructions.

Minimal Configuration Example

http {
    keyval_zone zone=one:32k;
    keyval $arg_text $text zone=one;

    server {
        listen 80;

        location / {
            return 200 $text;
        }
    }
}

This configuration retrieves a value from the shared memory zone one using the query parameter text as the key, and stores it in the variable $text.

Directives

Directive Description Context
keyval Define a variable from key-value pairs http, stream
keyval_zone Define a shared memory zone http, stream
keyval_zone_redis Define a Redis zone http, stream

See DIRECTIVES.md for detailed directive reference.

Configuration & Operations: - DIRECTIVES.md: Directive Reference - EXAMPLES.md: Configuration Examples - INSTALL.md: Installation Instructions - SECURITY.md: Security Guidelines - TROUBLESHOOTING.md: Troubleshooting Guide

Reference: - COMMERCIAL_COMPATIBILITY.md: Commercial Version Compatibility

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-keyval.