<?xml version="1.0"?>

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

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

<module name="Module ngx_stream_keyval_module"
        link="/en/docs/stream/ngx_stream_keyval_module.html"
        lang="en"
        rev="4">

<section id="summary">

<para>
The <literal>ngx_stream_keyval_module</literal> module (1.13.7) creates variables
with values taken from key-value pairs managed by the
<link doc="../http/ngx_http_api_module.xml" id="stream_keyvals_">API</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 {

    server {
        ...
        location /api {
            api write=on;
        }
    }
}

stream {

    keyval_zone zone=one:32k state=one.keyval;
    keyval      $ssl_server_name $name zone=one;

    server {
        listen              12345 ssl;
        proxy_pass          $name;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
    }
}
</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>stream</context>

<para>
Creates a new <value>$variable</value> whose value
is looked up by the <value>key</value> in the key-value database.
Strings are matched ignoring the case.
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>sync</literal>]</syntax>
<default/>
<context>stream</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="../http/ngx_http_api_module.xml" id="stream_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.
</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_sync">
The optional <literal>sync</literal> parameter (1.15.0) enables
<link doc="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="../http/ngx_http_api_module.xml" id="patchStreamKeyvalZoneKeyValue">one</link>
or
<link doc="../http/ngx_http_api_module.xml" id="deleteStreamKeyvalZoneData">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>