Mercurial > hg > nginx-site
annotate xml/en/docs/beginners_guide.xml @ 3094:f7e9bd7de0f9 default tip
freenginx-1.27.3
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 13 Aug 2024 17:45:23 +0300 |
parents | 8acfa16dd6ef |
children |
rev | line source |
---|---|
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 | |
2782
8acfa16dd6ef
Minor language correction in Beginner's Guide (trac #2256).
Yaroslav Zhuravlev <yar@nginx.com>
parents:
936
diff
changeset
|
344 include its own <literal>root</literal> directive. |
936 | 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> |