Mercurial > hg > nginx-site
annotate xml/en/docs/beginners_guide.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
| author | Sergey Budnevitch <sb@waeme.net> |
|---|---|
| date | Tue, 10 May 2022 18:07:27 +0400 |
| 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> |