<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_keyval_module"
        link="/en/docs/http/ngx_http_keyval_module.html"
        lang="en"
        rev="11">

<section id="summary">

<para>
The <literal>ngx_http_keyval_module</literal> module (1.13.3) creates variables
with values taken from key-value pairs managed by the
<link doc="ngx_http_api_module.xml" id="http_keyvals_">API</link>
or a variable (1.15.10) that can also be set with
<link url="https://github.com/nginx/njs-examples/#logging-the-number-of-requests-per-client-http-logging-num-requests">njs</link>.
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
http {

    keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval;
    keyval $arg_text $text zone=one;
    ...
    server {
        ...
        location / {
            return 200 $text;
        }

        location /api {
            api write=on;
        }
    }
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="keyval">
<syntax>
    <value>key</value>
    <value>$variable</value>
    <literal>zone</literal>=<value>name</value></syntax>
<default/>
<context>http</context>

<para>
Creates a new <value>$variable</value> whose value
is looked up by the <value>key</value> in the key-value database.
Matching rules are defined by the
<link id="keyval_type"><literal>type</literal></link> parameter of the
<link id="keyval_zone"><literal>keyval_zone</literal></link> directive.
The database is stored in a shared memory zone
specified by the <literal>zone</literal> parameter.
</para>

</directive>


<directive name="keyval_zone">
<syntax>
    <literal>zone</literal>=<value>name</value>:<value>size</value>
    [<literal>state</literal>=<value>file</value>]
    [<literal>timeout</literal>=<value>time</value>]
    [<literal>type</literal>=<literal>string</literal>|<literal>ip</literal>|<literal>prefix</literal>]
    [<literal>sync</literal>]</syntax>
<default/>
<context>http</context>

<para>
Sets the <value>name</value> and <value>size</value> of the shared memory zone
that keeps the key-value database.
Key-value pairs are managed by the
<link doc="ngx_http_api_module.xml" id="http_keyvals_">API</link>.
</para>

<para id="keyval_state">
The optional <literal>state</literal> parameter specifies a <value>file</value>
that keeps the current state of the key-value database in the JSON format
and makes it persistent across nginx restarts.
Changing the file content directly should be avoided.
</para>

<para>
Examples:
<example>
keyval_zone zone=one:32k state=/var/lib/nginx/state/one.keyval; # path for Linux
keyval_zone zone=one:32k state=/var/db/nginx/state/one.keyval;  # path for FreeBSD
</example>
</para>

<para id="keyval_timeout">
The optional <literal>timeout</literal> parameter (1.15.0) sets
the time after which key-value pairs are removed from the zone.
</para>

<para id="keyval_type">
The optional <literal>type</literal> parameter (1.17.1) activates
an extra index optimized for matching the key of a certain type
and defines matching rules when evaluating
a <link id="keyval">keyval</link> <literal>$variable</literal>.
<note>
The index is stored in the same shared memory zone
and thus requires additional storage.
</note>

<list type="tag">

<tag-name id="keyval_type_string"><literal>type=string</literal></tag-name>
<tag-desc>
default, no index is enabled;
variable lookup is performed using exact match
of the record key and a search key
</tag-desc>

<tag-name id="keyval_type_ip"><literal>type=ip</literal></tag-name>
<tag-desc>
the search key is the textual representation of IPv4 or IPv6 address
or CIDR range;
to match a record key, the search key must belong to a subnet
specified by a record key or exactly match an IP address
</tag-desc>

<tag-name id="keyval_type_prefix"><literal>type=prefix</literal></tag-name>
<tag-desc>
variable lookup is performed using prefix match
of a record key and a search key (1.17.5);
to match a record key, the record key must be a prefix of the search key
</tag-desc>

</list>
</para>

<para id="keyval_sync">
The optional <literal>sync</literal> parameter (1.15.0) enables
<link doc="../stream/ngx_stream_zone_sync_module.xml" id="zone_sync">synchronization</link>
of the shared memory zone.
The synchronization requires the
<literal>timeout</literal> parameter to be set.
<note>
If the synchronization is enabled, removal of key-value pairs (no matter
<link doc="ngx_http_api_module.xml" id="patchHttpKeyvalZoneKeyValue">one</link>
or
<link doc="ngx_http_api_module.xml" id="deleteHttpKeyvalZoneData">all</link>)
will be performed only on a target cluster node.
The same key-value pairs on other cluster nodes
will be removed upon <literal>timeout</literal>.
</note>
</para>

</directive>

</section>

</module>