blob: ad1642768c200af7344642932e41ebdafc747b75 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
=encoding utf-8
=head1 NAME
ngx_http_keyval_module - Module ngx_http_keyval_module
=head1
The C<ngx_http_keyval_module> module (1.13.3) creates variables
with values taken from key-value pairs managed by the
L<API|ngx_http_api_module>
or a variable (1.15.10) that can also be set with
L<njs|https://github.com/nginx/njs-examples/#logging-the-number-of-requests-per-client-http-logging-num-requests>.
B<NOTE>
This module is available as part of our
commercial subscription.
=head1 Example Configuration
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;
}
}
}
=head1 Directives
=head2 keyval
B<syntax:> keyval I<
I<C<key>>
I<C<$variable>>
C<zone>=I<C<name>>>
B<context:> I<http>
Creates a new I<C<$variable>> whose value
is looked up by the I<C<key>> in the key-value database.
Matching rules are defined by the
C<type> parameter of the
C<keyval_zone> directive.
The database is stored in a shared memory zone
specified by the C<zone> parameter.
=head2 keyval_zone
B<syntax:> keyval_zone I<
C<zone>=I<C<name>>:I<C<size>>
[C<state>=I<C<file>>]
[C<timeout>=I<C<time>>]
[C<type>=C<string>E<verbar>C<ip>E<verbar>C<prefix>]
[C<sync>]>
B<context:> I<http>
Sets the I<C<name>> and I<C<size>> of the shared memory zone
that keeps the key-value database.
Key-value pairs are managed by the
L<API|ngx_http_api_module>.
The optional C<state> parameter specifies a I<C<file>>
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.
Examples:
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
The optional C<timeout> parameter (1.15.0) sets
the time after which key-value pairs are removed from the zone.
The optional C<type> parameter (1.17.1) activates
an extra index optimized for matching the key of a certain type
and defines matching rules when evaluating
a keyval C<$variable>.
B<NOTE>
The index is stored in the same shared memory zone
and thus requires additional storage.
=over
=item C<type=string>
default, no index is enabled;
variable lookup is performed using exact match
of the record key and a search key
=item C<type=ip>
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
=item C<type=prefix>
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
=back
The optional C<sync> parameter (1.15.0) enables
L<synchronization|ngx_stream_zone_sync_module>
of the shared memory zone.
The synchronization requires the
C<timeout> parameter to be set.
B<NOTE>
If the synchronization is enabled, removal of key-value pairs (no matter
L<one|ngx_http_api_module>
or
L<all|ngx_http_api_module>)
will be performed only on a target cluster node.
The same key-value pairs on other cluster nodes
will be removed upon C<timeout>.
|
