|
936
|
1 <!--
|
|
|
2 Copyright (C) Nginx, Inc.
|
|
|
3 -->
|
|
|
4
|
|
|
5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
|
|
|
6
|
|
|
7 <article name="Beginner’s Guide"
|
|
|
8 link="/en/docs/beginners_guide.html"
|
|
|
9 lang="en"
|
|
|
10 rev="1">
|
|
|
11
|
|
|
12 <section>
|
|
|
13
|
|
|
14 <para>
|
|
|
15 This guide gives a basic introduction to nginx and describes some
|
|
|
16 simple tasks that can be done with it.
|
|
|
17 It is supposed that nginx is already installed on the reader’s machine.
|
|
|
18 If it is not, see the <link doc="install.xml"/> page.
|
|
|
19 This guide describes how to start and stop nginx, and reload its
|
|
|
20 configuration, explains the structure
|
|
|
21 of the configuration file and describes how to set up nginx
|
|
|
22 to serve out static content, how to configure nginx as a proxy
|
|
|
23 server, and how to connect it with a FastCGI application.
|
|
|
24 </para>
|
|
|
25
|
|
|
26 <para>
|
|
|
27 nginx has one master process and several worker processes.
|
|
|
28 The main purpose of the master process is to read and evaluate configuration,
|
|
|
29 and maintain worker processes.
|
|
|
30 Worker processes do actual processing of requests.
|
|
|
31 nginx employs event-based model and OS-dependent mechanisms to efficiently
|
|
|
32 distribute requests among worker processes.
|
|
|
33 The number of worker processes is defined in the configuration file and
|
|
|
34 may be fixed for a given configuration or automatically adjusted to the
|
|
|
35 number of available CPU cores (see
|
|
|
36 <link doc="ngx_core_module.xml" id="worker_processes"/>).
|
|
|
37 </para>
|
|
|
38
|
|
|
39 <para>
|
|
|
40 The way nginx and its modules work is determined in the configuration file.
|
|
|
41 By default, the configuration file is named <path>nginx.conf</path>
|
|
|
42 and placed in the directory
|
|
|
43 <path>/usr/local/nginx/conf</path>,
|
|
|
44 <path>/etc/nginx</path>, or
|
|
|
45 <path>/usr/local/etc/nginx</path>.
|
|
|
46 </para>
|
|
|
47
|
|
|
48 </section>
|
|
|
49
|
|
|
50
|
|
|
51 <section id="control" name="Starting, Stopping, and Reloading Configuration">
|
|
|
52
|
|
|
53 <para>
|
|
|
54 To start nginx, run the executable file.
|
|
|
55 Once nginx is started, it can be controlled by invoking the executable
|
|
|
56 with the <literal>-s</literal> parameter.
|
|
|
57 Use the following syntax:
|
|
|
58 <programlisting>
|
|
|
59 nginx -s <i>signal</i>
|
|
|
60 </programlisting>
|
|
|
61 Where <i>signal</i> may be one of the following:
|
|
|
62 <list type="bullet">
|
|
|
63 <listitem>
|
|
|
64 <literal>stop</literal>—fast shutdown
|
|
|
65 </listitem>
|
|
|
66 <listitem>
|
|
|
67 <literal>quit</literal>—graceful shutdown
|
|
|
68 </listitem>
|
|
|
69 <listitem>
|
|
|
70 <literal>reload</literal>—reloading the configuration file
|
|
|
71 </listitem>
|
|
|
72 <listitem>
|
|
|
73 <literal>reopen</literal>—reopening the log files
|
|
|
74 </listitem>
|
|
|
75 </list>
|
|
|
76 For example, to stop nginx processes with waiting for the worker processes
|
|
|
77 to finish serving current requests, the following command can be executed:
|
|
|
78 <programlisting>
|
|
|
79 nginx -s quit
|
|
|
80 </programlisting>
|
|
|
81 <note>This command should be executed under the same user that
|
|
|
82 started nginx.</note>
|
|
|
83 </para>
|
|
|
84
|
|
|
85 <para>
|
|
|
86 Changes made in the configuration file
|
|
|
87 will not be applied until the command to reload configuration is
|
|
|
88 sent to nginx or it is restarted.
|
|
|
89 To reload configuration, execute:
|
|
|
90 <programlisting>
|
|
|
91 nginx -s reload
|
|
|
92 </programlisting>
|
|
|
93 </para>
|
|
|
94
|
|
|
95 <para>
|
|
|
96 Once the master process receives the signal to reload configuration,
|
|
|
97 it checks the syntax validity
|
|
|
98 of the new configuration file and tries to apply the configuration provided
|
|
|
99 in it.
|
|
|
100 If this is a success, the master process starts new worker processes
|
|
|
101 and sends messages to old worker processes, requesting them to
|
|
|
102 shut down.
|
|
|
103 Otherwise, the master process rolls back the changes and
|
|
|
104 continues to work with the old configuration.
|
|
|
105 Old worker processes, receiving a command to shut down,
|
|
|
106 stop accepting new connections and continue to service current requests until
|
|
|
107 all such requests are serviced.
|
|
|
108 After that, the old worker processes exit.
|
|
|
109 </para>
|
|
|
110
|
|
|
111 <para>
|
|
|
112 A signal may also be sent to nginx processes with the help of Unix tools
|
|
|
113 such as the <command>kill</command> utility.
|
|
|
114 In this case a signal is sent directly to a process with a given process ID.
|
|
|
115 The process ID of the nginx master process is written, by default, to the
|
|
|
116 <path>nginx.pid</path> in the directory
|
|
|
117 <path>/usr/local/nginx/logs</path> or
|
|
|
118 <path>/var/run</path>.
|
|
|
119 For example, if the master process ID is 1628, to send the QUIT signal
|
|
|
120 resulting in nginx’s graceful shutdown, execute:
|
|
|
121 <programlisting>
|
|
|
122 kill -s QUIT 1628
|
|
|
123 </programlisting>
|
|
|
124 For getting the list of all running nginx processes, the <command>ps</command>
|
|
|
125 utility may be used, for example, in the following way:
|
|
|
126 <programlisting>
|
|
|
127 ps -ax | grep nginx
|
|
|
128 </programlisting>
|
|
|
129 For more information on sending signals to nginx, see
|
|
|
130 <link doc="control.xml"/>.
|
|
|
131 </para>
|
|
|
132
|
|
|
133 </section>
|
|
|
134
|
|
|
135
|
|
|
136 <section id="conf_structure" name="Configuration File’s Structure">
|
|
|
137
|
|
|
138 <para>
|
|
|
139 nginx consists of modules which are controlled by directives specified
|
|
|
140 in the configuration file.
|
|
|
141 Directives are divided into simple directives and block directives.
|
|
|
142 A simple directive consists of the name and parameters separated by spaces
|
|
|
143 and ends with a semicolon (<literal>;</literal>).
|
|
|
144 A block directive has the same structure as a simple directive, but
|
|
|
145 instead of the semicolon it ends with a set of additional instructions
|
|
|
146 surrounded by braces (<literal>{</literal> and <literal>}</literal>).
|
|
|
147 If a block directive can have other directives inside braces,
|
|
|
148 it is called a context (examples:
|
|
|
149 <link doc="ngx_core_module.xml" id="events"/>,
|
|
|
150 <link doc="http/ngx_http_core_module.xml" id="http"/>,
|
|
|
151 <link doc="http/ngx_http_core_module.xml" id="server"/>,
|
|
|
152 and
|
|
|
153 <link doc="http/ngx_http_core_module.xml" id="location"/>).
|
|
|
154 </para>
|
|
|
155
|
|
|
156 <para>
|
|
|
157 Directives placed in the configuration file outside
|
|
|
158 of any contexts are considered to be in the
|
|
|
159 <link doc="ngx_core_module.xml">main</link> context.
|
|
|
160 The <literal>events</literal> and <literal>http</literal> directives
|
|
|
161 reside in the <literal>main</literal> context, <literal>server</literal>
|
|
|
162 in <literal>http</literal>, and <literal>location</literal> in
|
|
|
163 <literal>server</literal>.
|
|
|
164 </para>
|
|
|
165
|
|
|
166 <para>
|
|
|
167 The rest of a line after the <literal>#</literal> sign is considered a comment.
|
|
|
168 </para>
|
|
|
169
|
|
|
170 </section>
|
|
|
171
|
|
|
172
|
|
|
173 <section id="static" name="Serving Static Content">
|
|
|
174
|
|
|
175 <para>
|
|
|
176 An important web server task is serving out
|
|
|
177 files (such as images or static HTML pages).
|
|
|
178 You will implement an example where, depending on the request,
|
|
|
179 files will be served from different local directories: <path>/data/www</path>
|
|
|
180 (which may contain HTML files) and <path>/data/images</path>
|
|
|
181 (containing images).
|
|
|
182 This will require editing of the configuration file and setting up of a
|
|
|
183 <link doc="http/ngx_http_core_module.xml" id="server"/>
|
|
|
184 block inside the <link doc="http/ngx_http_core_module.xml" id="http"/>
|
|
|
185 block with two <link doc="http/ngx_http_core_module.xml" id="location"/>
|
|
|
186 blocks.
|
|
|
187 </para>
|
|
|
188
|
|
|
189 <para>
|
|
|
190 First, create the <path>/data/www</path> directory and put an
|
|
|
191 <path>index.html</path> file with any text content into it and
|
|
|
192 create the <path>/data/images</path> directory and place some
|
|
|
193 images in it.
|
|
|
194 </para>
|
|
|
195
|
|
|
196 <para>
|
|
|
197 Next, open the configuration file.
|
|
|
198 The default configuration file already includes several examples of
|
|
|
199 the <literal>server</literal> block, mostly commented out.
|
|
|
200 For now comment out all such blocks and start a new
|
|
|
201 <literal>server</literal> block:
|
|
|
202 <programlisting>
|
|
|
203 http {
|
|
|
204 server {
|
|
|
205 }
|
|
|
206 }
|
|
|
207 </programlisting>
|
|
|
208 Generally, the configuration file may include several
|
|
|
209 <literal>server</literal> blocks
|
|
|
210 <link doc="http/request_processing.xml">distinguished</link> by ports on which
|
|
|
211 they <link doc="http/ngx_http_core_module.xml" id="listen">listen</link> to
|
|
|
212 and by
|
|
|
213 <link doc="http/server_names.xml">server names</link>.
|
|
|
214 Once nginx decides which <literal>server</literal> processes a request,
|
|
|
215 it tests the URI specified in the request’s header against the parameters of the
|
|
|
216 <literal>location</literal> directives defined inside the
|
|
|
217 <literal>server</literal> block.
|
|
|
218 </para>
|
|
|
219
|
|
|
220 <para>
|
|
|
221 Add the following <literal>location</literal> block to the
|
|
|
222 <literal>server</literal> block:
|
|
|
223 <programlisting>
|
|
|
224 location / {
|
|
|
225 root /data/www;
|
|
|
226 }
|
|
|
227 </programlisting>
|
|
|
228 This <literal>location</literal> block specifies the
|
|
|
229 “<path>/</path>” prefix compared with the URI from the request.
|
|
|
230 For matching requests, the URI will be added to the path specified in the
|
|
|
231 <link doc="http/ngx_http_core_module.xml" id="root"/>
|
|
|
232 directive, that is, to <path>/data/www</path>,
|
|
|
233 to form the path to the requested file on the local file system.
|
|
|
234 If there are several matching <literal>location</literal> blocks nginx
|
|
|
235 selects the one with the longest prefix.
|
|
|
236 The <literal>location</literal> block above provides the shortest
|
|
|
237 prefix, of length one,
|
|
|
238 and so only if all other <literal>location</literal>
|
|
|
239 blocks fail to provide a match, this block will be used.
|
|
|
240 </para>
|
|
|
241
|
|
|
242 <para>
|
|
|
243 Next, add the second <literal>location</literal> block:
|
|
|
244 <programlisting>
|
|
|
245 location /images/ {
|
|
|
246 root /data;
|
|
|
247 }
|
|
|
248 </programlisting>
|
|
|
249 It will be a match for requests starting with <literal>/images/</literal>
|
|
|
250 (<literal>location /</literal> also matches such requests,
|
|
|
251 but has shorter prefix).
|
|
|
252 </para>
|
|
|
253
|
|
|
254 <para>
|
|
|
255 The resulting configuration of the <literal>server</literal> block should
|
|
|
256 look like this:
|
|
|
257 <programlisting>
|
|
|
258 server {
|
|
|
259 location / {
|
|
|
260 root /data/www;
|
|
|
261 }
|
|
|
262
|
|
|
263 location /images/ {
|
|
|
264 root /data;
|
|
|
265 }
|
|
|
266 }
|
|
|
267 </programlisting>
|
|
|
268 This is already a working configuration of a server that listens
|
|
|
269 on the standard port 80 and is accessible on the local machine at
|
|
|
270 <literal>http://localhost/</literal>.
|
|
|
271 In response to requests with URIs starting with <literal>/images/</literal>,
|
|
|
272 the server will send files from the <path>/data/images</path> directory.
|
|
|
273 For example, in response to the
|
|
|
274 <literal>http://localhost/images/example.png</literal> request nginx will
|
|
|
275 send the <path>/data/images/example.png</path> file.
|
|
|
276 If such file does not exist, nginx will send a response
|
|
|
277 indicating the 404 error.
|
|
|
278 Requests with URIs not starting with <literal>/images/</literal> will be
|
|
|
279 mapped onto the <path>/data/www</path> directory.
|
|
|
280 For example, in response to the
|
|
|
281 <literal>http://localhost/some/example.html</literal> request nginx will
|
|
|
282 send the <path>/data/www/some/example.html</path> file.
|
|
|
283 </para>
|
|
|
284
|
|
|
285 <para>
|
|
|
286 To apply the new configuration, start nginx if it is not yet started or
|
|
|
287 send the <literal>reload</literal> signal to the nginx’s master process,
|
|
|
288 by executing:
|
|
|
289 <programlisting>
|
|
|
290 nginx -s reload
|
|
|
291 </programlisting>
|
|
|
292 </para>
|
|
|
293
|
|
|
294 <para>
|
|
|
295 <note>
|
|
|
296 In case something does not work as expected, you may try to find out
|
|
|
297 the reason in <path>access.log</path> and
|
|
|
298 <path>error.log</path> files in the directory
|
|
|
299 <path>/usr/local/nginx/logs</path> or
|
|
|
300 <path>/var/log/nginx</path>.
|
|
|
301 </note>
|
|
|
302 </para>
|
|
|
303
|
|
|
304 </section>
|
|
|
305
|
|
|
306
|
|
|
307 <section id="proxy" name="Setting Up a Simple Proxy Server">
|
|
|
308
|
|
|
309 <para>
|
|
|
310 One of the frequent uses of nginx is setting it up as a proxy server, which
|
|
|
311 means a server that receives requests, passes them to the proxied servers,
|
|
|
312 retrieves responses from them, and sends them to the clients.
|
|
|
313 </para>
|
|
|
314
|
|
|
315 <para>
|
|
|
316 We will configure a basic proxy server, which serves requests of
|
|
|
317 images with files from the local directory and sends all other requests to a
|
|
|
318 proxied server.
|
|
|
319 In this example, both servers will be defined on a single nginx instance.
|
|
|
320 </para>
|
|
|
321
|
|
|
322 <para>
|
|
|
323 First, define the proxied server by adding one more <literal>server</literal>
|
|
|
324 block to the nginx’s configuration file with the following contents:
|
|
|
325 <programlisting>
|
|
|
326 server {
|
|
|
327 listen 8080;
|
|
|
328 root /data/up1;
|
|
|
329
|
|
|
330 location / {
|
|
|
331 }
|
|
|
332 }
|
|
|
333 </programlisting>
|
|
|
334 This will be a simple server that listens on the port 8080
|
|
|
335 (previously, the <literal>listen</literal> directive has not been specified
|
|
|
336 since the standard port 80 was used) and maps
|
|
|
337 all requests to the <path>/data/up1</path> directory on the local
|
|
|
338 file system.
|
|
|
339 Create this directory and put the <path>index.html</path> file into it.
|
|
|
340 Note that the <literal>root</literal> directive is placed in the
|
|
|
341 <literal>server</literal> context.
|
|
|
342 Such <literal>root</literal> directive is used when the
|
|
|
343 <literal>location</literal> block selected for serving a request does not
|
|
|
344 include own <literal>root</literal> directive.
|
|
|
345 </para>
|
|
|
346
|
|
|
347 <para>
|
|
|
348 Next, use the server configuration from the previous section
|
|
|
349 and modify it to make it a proxy server configuration.
|
|
|
350 In the first <literal>location</literal> block, put the
|
|
|
351 <link doc="http/ngx_http_proxy_module.xml" id="proxy_pass"/>
|
|
|
352 directive with the protocol, name and port of the proxied server specified
|
|
|
353 in the parameter (in our case, it is <literal>http://localhost:8080</literal>):
|
|
|
354 <programlisting>
|
|
|
355 server {
|
|
|
356 location / {
|
|
|
357 proxy_pass http://localhost:8080;
|
|
|
358 }
|
|
|
359
|
|
|
360 location /images/ {
|
|
|
361 root /data;
|
|
|
362 }
|
|
|
363 }
|
|
|
364 </programlisting>
|
|
|
365 </para>
|
|
|
366
|
|
|
367 <para>
|
|
|
368 We will modify the second <literal>location</literal>
|
|
|
369 block, which currently maps requests with the <literal>/images/</literal>
|
|
|
370 prefix to the files under the <path>/data/images</path> directory,
|
|
|
371 to make it match the requests of images with typical file extensions.
|
|
|
372 The modified <literal>location</literal> block looks like this:
|
|
|
373 <programlisting>
|
|
|
374 location ~ \.(gif|jpg|png)$ {
|
|
|
375 root /data/images;
|
|
|
376 }
|
|
|
377 </programlisting>
|
|
|
378 The parameter is a regular expression matching all URIs ending
|
|
|
379 with <path>.gif</path>, <path>.jpg</path>, or <path>.png</path>.
|
|
|
380 A regular expression should be preceded with <literal>~</literal>.
|
|
|
381 The corresponding requests will be mapped to the <path>/data/images</path>
|
|
|
382 directory.
|
|
|
383 </para>
|
|
|
384
|
|
|
385 <para>
|
|
|
386 When nginx selects a <literal>location</literal> block to serve a request
|
|
|
387 it first checks <link doc="http/ngx_http_core_module.xml" id="location"/>
|
|
|
388 directives that specify prefixes, remembering <literal>location</literal>
|
|
|
389 with the longest prefix, and then checks regular expressions.
|
|
|
390 If there is a match with a regular expression, nginx picks this
|
|
|
391 <literal>location</literal> or, otherwise, it picks the one remembered earlier.
|
|
|
392 </para>
|
|
|
393
|
|
|
394 <para>
|
|
|
395 The resulting configuration of a proxy server will look like this:
|
|
|
396 <programlisting>
|
|
|
397 server {
|
|
|
398 location / {
|
|
|
399 proxy_pass http://localhost:8080/;
|
|
|
400 }
|
|
|
401
|
|
|
402 location ~ \.(gif|jpg|png)$ {
|
|
|
403 root /data/images;
|
|
|
404 }
|
|
|
405 }
|
|
|
406 </programlisting>
|
|
|
407 This server will filter requests ending with <path>.gif</path>,
|
|
|
408 <path>.jpg</path>, or <path>.png</path>
|
|
|
409 and map them to the <path>/data/images</path> directory (by adding URI to the
|
|
|
410 <literal>root</literal> directive’s parameter) and pass all other requests
|
|
|
411 to the proxied server configured above.
|
|
|
412 </para>
|
|
|
413
|
|
|
414 <para>
|
|
|
415 To apply new configuration, send the <literal>reload</literal> signal to
|
|
|
416 nginx as described in the previous sections.
|
|
|
417 </para>
|
|
|
418
|
|
|
419 <para>
|
|
|
420 There are many <link doc="http/ngx_http_proxy_module.xml">more</link>
|
|
|
421 directives that may be used to further configure a proxy connection.
|
|
|
422 </para>
|
|
|
423
|
|
|
424 </section>
|
|
|
425
|
|
|
426
|
|
|
427 <section id="fastcgi" name="Setting Up FastCGI Proxying">
|
|
|
428
|
|
|
429 <para>
|
|
|
430 nginx can be used to route requests to FastCGI servers which run
|
|
|
431 applications built with various frameworks and programming languages
|
|
|
432 such as PHP.
|
|
|
433 </para>
|
|
|
434
|
|
|
435 <para>
|
|
|
436 The most basic nginx configuration to work with a FastCGI server
|
|
|
437 includes using the
|
|
|
438 <link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>
|
|
|
439 directive instead of the <literal>proxy_pass</literal> directive,
|
|
|
440 and <link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_param"/>
|
|
|
441 directives to set parameters passed to a FastCGI server.
|
|
|
442 Suppose the FastCGI server is accessible on <literal>localhost:9000</literal>.
|
|
|
443 Taking the proxy configuration from the previous section as a basis,
|
|
|
444 replace the <literal>proxy_pass</literal> directive with the
|
|
|
445 <literal>fastcgi_pass</literal> directive and change the parameter to
|
|
|
446 <literal>localhost:9000</literal>.
|
|
|
447 In PHP, the <literal>SCRIPT_FILENAME</literal> parameter is used for
|
|
|
448 determining the script name, and the <literal>QUERY_STRING</literal>
|
|
|
449 parameter is used to pass request parameters.
|
|
|
450 The resulting configuration would be:
|
|
|
451 <programlisting>
|
|
|
452 server {
|
|
|
453 location / {
|
|
|
454 fastcgi_pass localhost:9000;
|
|
|
455 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
|
|
|
456 fastcgi_param QUERY_STRING $query_string;
|
|
|
457 }
|
|
|
458
|
|
|
459 location ~ \.(gif|jpg|png)$ {
|
|
|
460 root /data/images;
|
|
|
461 }
|
|
|
462 }
|
|
|
463 </programlisting>
|
|
|
464 This will set up a server that will route all requests except for
|
|
|
465 requests for static images to the proxied server operating on
|
|
|
466 <literal>localhost:9000</literal> through the FastCGI protocol.
|
|
|
467 </para>
|
|
|
468
|
|
|
469 </section>
|
|
|
470
|
|
|
471 </article>
|
