Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_keyval_module.xml @ 3017:f55e18559df9
Updated OpenSSL and zlib versions.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 03 Oct 2023 09:57:16 +0100 |
parents | 79ebb6a3812b |
children |
line wrap: on
line source
<?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>