Mercurial > hg > nginx-site

comparison xml/en/docs/beginners_guide.xml @ 936:99f8165723ca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Beginner's guide.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 25 Jun 2013 10:39:32 +0400
parents
children 8acfa16dd6ef
comparison
equal deleted inserted replaced
935:3860b37d56c0 936:99f8165723ca
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>&mdash;fast shutdown
65 </listitem>
66 <listitem>
67 <literal>quit</literal>&mdash;graceful shutdown
68 </listitem>
69 <listitem>
70 <literal>reload</literal>&mdash;reloading the configuration file
71 </listitem>
72 <listitem>
73 <literal>reopen</literal>&mdash;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>