Mercurial > hg > nginx-site
view xml/en/docs/stream/ngx_stream_keyval_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
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_stream_keyval_module" link="/en/docs/stream/ngx_stream_keyval_module.html" lang="en" rev="11"> <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> or a variable that can also be set with <link url="https://github.com/nginx/njs-examples/">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 { server { ... location /api { api write=on; } } } stream { keyval_zone zone=one:32k state=/var/lib/nginx/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. 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>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. 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="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>