Mercurial > hg > nginx

comparison docs/xml/ngx_core_module.xml @ 4068:22364b1f61c9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Initial English translation of Core and HTTP Core modules.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 05 Sep 2011 09:39:24 +0000
parents
children 9755cb2a39b2
comparison
equal deleted inserted replaced
4067:da811964e37c 4068:22364b1f61c9
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../dtd/module.dtd">
4
5 <module name="Core Module" id="core_module">
6
7 <section name="Example Configuration" id="example">
8
9 <para>
10 <example>
11 user www www;
12 worker_processes 2;
13
14 error_log /var/log/nginx-error.log info;
15
16 events {
17 use kqueue;
18 worker_connections 2048;
19 }
20
21 ...
22 </example>
23 </para>
24
25 </section>
26
27
28 <section name="Directives" id="directives">
29
30 <directive name="daemon">
31 <syntax>daemon <value>on</value> | <value>off</value></syntax>
32 <default>daemon on</default>
33 <context>main</context>
34
35 <para>
36 Determines whether nginx should become a daemon.
37 Mainly used during development.
38 </para>
39
40 </directive>
41
42
43 <directive name="env">
44 <syntax>env <argument>VAR</argument>[=<argument>VALUE</argument>]</syntax>
45 <default>env TZ</default>
46 <context>main</context>
47
48 <para>
49 Allows to limit a set of environment variables, change their values,
50 or create new environment variables, for the following cases:
51 <list type="bullet">
52
53 <listitem>
54 variable inheritance during a
55 <link doc="control.xml" id="upgrade">live upgrade</link>
56 of an executable file;
57 </listitem>
58
59 <listitem>
60 use of variables by the
61 <link doc="http/ngx_http_perl_module.xml">http_perl</link>
62 module;
63 </listitem>
64
65 <listitem>
66 use of variables by worker processes.
67 Please bear in mind that controlling system libraries in this way
68 isn't always possible as it's not uncommon for libraries to check
69 variables only during initialization, well before they can be set
70 using this directive.
71 An exception from this is an above mentioned
72 <link doc="control.xml" id="upgrade">live upgrade</link>
73 of an executable file.
74 </listitem>
75
76 </list>
77 </para>
78
79 <para>
80 The TZ variable is always inherited and made available to the
81 <link doc="http/ngx_http_perl_module.xml">http_perl</link>
82 module, unless configured explicitly.
83 </para>
84
85 <para>
86 Usage example:
87 <example>
88 env MALLOC_OPTIONS;
89 env PERL5LIB=/data/site/modules;
90 env OPENSSL_ALLOW_PROXY_CERTS=1;
91 </example>
92 </para>
93
94 </directive>
95
96 <directive name="include">
97 <syntax>include <argument>file</argument> | <argument>mask</argument></syntax>
98 <default/>
99 <context/>
100
101 <para>
102 Includes another <argument>file</argument>, or files matching the
103 specified <argument>mask</argument>, into configuration.
104 Included files should consist of
105 syntactically correct directives and blocks.
106 </para>
107
108 <para>
109 Usage example:
110 <example>
111 include mime.types;
112 include vhosts/*.conf;
113 </example>
114 </para>
115
116 </directive>
117
118
119 <directive name="master_process">
120 <syntax>master_process <value>on</value> | <value>off</value></syntax>
121 <default>master_process on</default>
122 <context>main</context>
123
124 <para>
125 Determines whether worker processes are started.
126 This directive is intended for nginx developers.
127 </para>
128
129 </directive>
130
131
132 <directive name="pid">
133 <syntax>pid <argument>file</argument></syntax>
134 <default>pid nginx.pid</default>
135 <context>main</context>
136
137 <para>
138 Defines a <argument>file</argument> which will store the process ID of the main process.
139 </para>
140
141 </directive>
142
143
144 <directive name="ssl_engine">
145 <syntax>ssl_engine <argument>device</argument></syntax>
146 <default/>
147 <context>main</context>
148
149 <para>
150 Defines the name of the hardware SSL accelerator.
151 </para>
152
153 </directive>
154
155
156 <directive name="user">
157 <syntax>user <argument>user</argument> [<argument>group</argument>]</syntax>
158 <default>user nobody nobody</default>
159 <context>main</context>
160
161 <para>
162 Defines <argument>user</argument> and <argument>group</argument>
163 credentials used by worker processes.
164 If <argument>group</argument> is omitted, a group whose name equals
165 that of <argument>user</argument> is used.
166 </para>
167
168 </directive>
169
170
171 <directive name="timer_resolution">
172 <syntax>timer_resolution <argument>interval</argument></syntax>
173 <default/>
174 <context>main</context>
175
176 <para>
177 Reduces timer resolution in worker processes, thus reducing the
178 number of <c-func>gettimeofday</c-func> system calls made.
179 By default, <c-func>gettimeofday</c-func> is called each time
180 on receiving a kernel event.
181 With reduced resolution, <c-func>gettimeofday</c-func> is only
182 called once per specified <argument>interval</argument>.
183 </para>
184
185 <para>
186 Example:
187 <example>
188 timer_resolution 100ms;
189 </example>
190 </para>
191
192 <para>
193 An internal implementation of interval depends on the method used:
194 <list type="bullet">
195
196 <listitem>
197 an <c-def>EVFILT_TIMER</c-def> filter if <code>kqueue</code> is used;
198 </listitem>
199
200 <listitem>
201 <c-func>timer_create</c-func> if <code>eventport</code> is used;
202 </listitem>
203
204 <listitem>
205 <c-func>setitimer</c-func> otherwise.
206 </listitem>
207
208 </list>
209 </para>
210
211 </directive>
212
213
214 <directive name="worker_rlimit_core">
215 <syntax>worker_rlimit_core <argument>size</argument></syntax>
216 <default/>
217 <context>main</context>
218
219 <para>
220 Changes the limit on the largest size of a core file
221 (<c-def>RLIMIT_CORE</c-def>) for worker processes.
222 Used to increase the limit without restarting the main process.
223 </para>
224
225 </directive>
226
227
228 <directive name="worker_rlimit_nofile">
229 <syntax>worker_rlimit_nofile <argument>number</argument></syntax>
230 <default/>
231 <context>main</context>
232
233 <para>
234 Changes the limit on the maximum number of open files
235 (<c-def>RLIMIT_NOFILE</c-def>) for worker processes.
236 Used to increase the limit without restarting the main process.
237 </para>
238
239 </directive>
240
241
242 <directive name="worker_priority">
243 <syntax>worker_priority <argument>number</argument></syntax>
244 <default>worker_priority 0</default>
245 <context>main</context>
246
247 <para>
248 Defines a scheduling priority for worker processes like is
249 done by the <command>nice</command>: a negative
250 <argument>number</argument>
251 means higher priority.
252 Allowed range normally varies from -20 to 20.
253 </para>
254
255 <para>
256 Example:
257 <example>
258 worker_priority -10;
259 </example>
260 </para>
261
262 </directive>
263
264
265 <directive name="worker_processes">
266 <syntax>worker_processes <argument>number</argument></syntax>
267 <default>worker_processes 1</default>
268 <context>main</context>
269
270 <para>
271 Defines the number of worker processes.
272 </para>
273
274 </directive>
275
276
277 <directive name="working_directory">
278 <syntax>working_directory <argument>directory</argument></syntax>
279 <default/>
280 <context>main</context>
281
282 <para>
283 Defines a current working directory for a worker process.
284 It's primarily used for writing a core-file, in which case
285 a working process should have write permission for the
286 specified directory.
287 </para>
288
289 </directive>
290
291 </section>
292
293 </module>