beginners_guide.xml

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE article SYSTEM "../../../dtd/article.dtd">

<article name="Beginner’s Guide"
         link="/en/docs/beginners_guide.html"
         lang="en"
         rev="1">

<section>

<para>
This guide gives a basic introduction to nginx and describes some
simple tasks that can be done with it.
It is supposed that nginx is already installed on the reader’s machine.
If it is not, see the <link doc="install.xml"/> page.
This guide describes how to start and stop nginx, and reload its
configuration, explains the structure
of the configuration file and describes how to set up nginx
to serve out static content, how to configure nginx as a proxy
server, and how to connect it with a FastCGI application.
</para>

<para>
nginx has one master process and several worker processes.
The main purpose of the master process is to read and evaluate configuration,
and maintain worker processes.
Worker processes do actual processing of requests.
nginx employs event-based model and OS-dependent mechanisms to efficiently
distribute requests among worker processes.
The number of worker processes is defined in the configuration file and
may be fixed for a given configuration or automatically adjusted to the
number of available CPU cores (see
<link doc="ngx_core_module.xml" id="worker_processes"/>).
</para>

<para>
The way nginx and its modules work is determined in the configuration file.
By default, the configuration file is named <path>nginx.conf</path>
and placed in the directory
<path>/usr/local/nginx/conf</path>,
<path>/etc/nginx</path>, or
<path>/usr/local/etc/nginx</path>.
</para>

</section>


<section id="control" name="Starting, Stopping, and Reloading Configuration">

<para>
To start nginx, run the executable file.
Once nginx is started, it can be controlled by invoking the executable
with the <literal>-s</literal> parameter.
Use the following syntax:
<programlisting>
nginx -s <i>signal</i>
</programlisting>
Where <i>signal</i> may be one of the following:
<list type="bullet">
<listitem>
<literal>stop</literal>&mdash;fast shutdown
</listitem>
<listitem>
<literal>quit</literal>&mdash;graceful shutdown
</listitem>
<listitem>
<literal>reload</literal>&mdash;reloading the configuration file
</listitem>
<listitem>
<literal>reopen</literal>&mdash;reopening the log files
</listitem>
</list>
For example, to stop nginx processes with waiting for the worker processes
to finish serving current requests, the following command can be executed:
<programlisting>
nginx -s quit
</programlisting>
<note>This command should be executed under the same user that
started nginx.</note>
</para>

<para>
Changes made in the configuration file
will not be applied until the command to reload configuration is
sent to nginx or it is restarted.
To reload configuration, execute:
<programlisting>
nginx -s reload
</programlisting>
</para>

<para>
Once the master process receives the signal to reload configuration,
it checks the syntax validity
of the new configuration file and tries to apply the configuration provided
in it.
If this is a success, the master process starts new worker processes
and sends messages to old worker processes, requesting them to
shut down.
Otherwise, the master process rolls back the changes and
continues to work with the old configuration.
Old worker processes, receiving a command to shut down,
stop accepting new connections and continue to service current requests until
all such requests are serviced.
After that, the old worker processes exit.
</para>

<para>
A signal may also be sent to nginx processes with the help of Unix tools
such as the <command>kill</command> utility.
In this case a signal is sent directly to a process with a given process ID.
The process ID of the nginx master process is written, by default, to the
<path>nginx.pid</path> in the directory
<path>/usr/local/nginx/logs</path> or
<path>/var/run</path>.
For example, if the master process ID is 1628, to send the QUIT signal
resulting in nginx’s graceful shutdown, execute:
<programlisting>
kill -s QUIT 1628
</programlisting>
For getting the list of all running nginx processes, the <command>ps</command>
utility may be used, for example, in the following way:
<programlisting>
ps -ax | grep nginx
</programlisting>
For more information on sending signals to nginx, see
<link doc="control.xml"/>.
</para>

</section>


<section id="conf_structure" name="Configuration File’s Structure">

<para>
nginx consists of modules which are controlled by directives specified
in the configuration file.
Directives are divided into simple directives and block directives.
A simple directive consists of the name and parameters separated by spaces
and ends with a semicolon (<literal>;</literal>).
A block directive has the same structure as a simple directive, but
instead of the semicolon it ends with a set of additional instructions
surrounded by braces (<literal>{</literal> and <literal>}</literal>).
If a block directive can have other directives inside braces,
it is called a context (examples:
<link doc="ngx_core_module.xml" id="events"/>,
<link doc="http/ngx_http_core_module.xml" id="http"/>,
<link doc="http/ngx_http_core_module.xml" id="server"/>,
and
<link doc="http/ngx_http_core_module.xml" id="location"/>).
</para>

<para>
Directives placed in the configuration file outside
of any contexts are considered to be in the
<link doc="ngx_core_module.xml">main</link> context.
The <literal>events</literal> and <literal>http</literal> directives
reside in the <literal>main</literal> context, <literal>server</literal>
in <literal>http</literal>, and <literal>location</literal> in
<literal>server</literal>.
</para>

<para>
The rest of a line after the <literal>#</literal> sign is considered a comment.
</para>

</section>


<section id="static" name="Serving Static Content">

<para>
An important web server task is serving out
files (such as images or static HTML pages).
You will implement an example where, depending on the request,
files will be served from different local directories: <path>/data/www</path>
(which may contain HTML files) and <path>/data/images</path>
(containing images).
This will require editing of the configuration file and setting up of a
<link doc="http/ngx_http_core_module.xml" id="server"/>
block inside the <link doc="http/ngx_http_core_module.xml" id="http"/>
block with two <link doc="http/ngx_http_core_module.xml" id="location"/>
blocks.
</para>

<para>
First, create the <path>/data/www</path> directory and put an
<path>index.html</path> file with any text content into it and
create the <path>/data/images</path> directory and place some
images in it.
</para>

<para>
Next, open the configuration file.
The default configuration file already includes several examples of
the <literal>server</literal> block, mostly commented out.
For now comment out all such blocks and start a new
<literal>server</literal> block:
<programlisting>
http {
    server {
    }
}
</programlisting>
Generally, the configuration file may include several
<literal>server</literal> blocks
<link doc="http/request_processing.xml">distinguished</link> by ports on which
they <link doc="http/ngx_http_core_module.xml" id="listen">listen</link> to
and by
<link doc="http/server_names.xml">server names</link>.
Once nginx decides which <literal>server</literal> processes a request,
it tests the URI specified in the request’s header against the parameters of the
<literal>location</literal> directives defined inside the
<literal>server</literal> block.
</para>

<para>
Add the following <literal>location</literal> block to the
<literal>server</literal> block:
<programlisting>
location / {
    root /data/www;
}
</programlisting>
This <literal>location</literal> block specifies the
“<path>/</path>” prefix compared with the URI from the request.
For matching requests, the URI will be added to the path specified in the
<link doc="http/ngx_http_core_module.xml" id="root"/>
directive, that is, to <path>/data/www</path>,
to form the path to the requested file on the local file system.
If there are several matching <literal>location</literal> blocks nginx
selects the one with the longest prefix.
The <literal>location</literal> block above provides the shortest
prefix, of length one,
and so only if all other <literal>location</literal>
blocks fail to provide a match, this block will be used.
</para>

<para>
Next, add the second <literal>location</literal> block:
<programlisting>
location /images/ {
    root /data;
}
</programlisting>
It will be a match for requests starting with <literal>/images/</literal>
(<literal>location /</literal> also matches such requests,
but has shorter prefix).
</para>

<para>
The resulting configuration of the <literal>server</literal> block should
look like this:
<programlisting>
server {
    location / {
        root /data/www;
    }

    location /images/ {
        root /data;
    }
}
</programlisting>
This is already a working configuration of a server that listens
on the standard port 80 and is accessible on the local machine at
<literal>http://localhost/</literal>.
In response to requests with URIs starting with <literal>/images/</literal>,
the server will send files from the <path>/data/images</path> directory.
For example, in response to the
<literal>http://localhost/images/example.png</literal> request nginx will
send the <path>/data/images/example.png</path> file.
If such file does not exist, nginx will send a response
indicating the 404 error.
Requests with URIs not starting with <literal>/images/</literal> will be
mapped onto the <path>/data/www</path> directory.
For example, in response to the
<literal>http://localhost/some/example.html</literal> request nginx will
send the <path>/data/www/some/example.html</path> file.
</para>

<para>
To apply the new configuration, start nginx if it is not yet started or
send the <literal>reload</literal> signal to the nginx’s master process,
by executing:
<programlisting>
nginx -s reload
</programlisting>
</para>

<para>
<note>
In case something does not work as expected, you may try to find out
the reason in <path>access.log</path> and
<path>error.log</path> files in the directory
<path>/usr/local/nginx/logs</path> or
<path>/var/log/nginx</path>.
</note>
</para>

</section>


<section id="proxy" name="Setting Up a Simple Proxy Server">

<para>
One of the frequent uses of nginx is setting it up as a proxy server, which
means a server that receives requests, passes them to the proxied servers,
retrieves responses from them, and sends them to the clients.
</para>

<para>
We will configure a basic proxy server, which serves requests of
images with files from the local directory and sends all other requests to a
proxied server.
In this example, both servers will be defined on a single nginx instance.
</para>

<para>
First, define the proxied server by adding one more <literal>server</literal>
block to the nginx’s configuration file with the following contents:
<programlisting>
server {
    listen 8080;
    root /data/up1;

    location / {
    }
}
</programlisting>
This will be a simple server that listens on the port 8080
(previously, the <literal>listen</literal> directive has not been specified
since the standard port 80 was used) and maps
all requests to the <path>/data/up1</path> directory on the local
file system.
Create this directory and put the <path>index.html</path> file into it.
Note that the <literal>root</literal> directive is placed in the
<literal>server</literal> context.
Such <literal>root</literal> directive is used when the
<literal>location</literal> block selected for serving a request does not
include its own <literal>root</literal> directive.
</para>

<para>
Next, use the server configuration from the previous section
and modify it to make it a proxy server configuration.
In the first <literal>location</literal> block, put the
<link doc="http/ngx_http_proxy_module.xml" id="proxy_pass"/>
directive with the protocol, name and port of the proxied server specified
in the parameter (in our case, it is <literal>http://localhost:8080</literal>):
<programlisting>
server {
    location / {
        proxy_pass http://localhost:8080;
    }

    location /images/ {
        root /data;
    }
}
</programlisting>
</para>

<para>
We will modify the second <literal>location</literal>
block, which currently maps requests with the <literal>/images/</literal>
prefix to the files under the <path>/data/images</path> directory,
to make it match the requests of images with typical file extensions.
The modified <literal>location</literal> block looks like this:
<programlisting>
location ~ \.(gif|jpg|png)$ {
    root /data/images;
}
</programlisting>
The parameter is a regular expression matching all URIs ending
with <path>.gif</path>, <path>.jpg</path>, or <path>.png</path>.
A regular expression should be preceded with <literal>~</literal>.
The corresponding requests will be mapped to the <path>/data/images</path>
directory.
</para>

<para>
When nginx selects a <literal>location</literal> block to serve a request
it first checks <link doc="http/ngx_http_core_module.xml" id="location"/>
directives that specify prefixes, remembering <literal>location</literal>
with the longest prefix, and then checks regular expressions.
If there is a match with a regular expression, nginx picks this
<literal>location</literal> or, otherwise, it picks the one remembered earlier.
</para>

<para>
The resulting configuration of a proxy server will look like this:
<programlisting>
server {
    location / {
        proxy_pass http://localhost:8080/;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}
</programlisting>
This server will filter requests ending with <path>.gif</path>,
<path>.jpg</path>, or <path>.png</path>
and map them to the <path>/data/images</path> directory (by adding URI to the
<literal>root</literal> directive’s parameter) and pass all other requests
to the proxied server configured above.
</para>

<para>
To apply new configuration, send the <literal>reload</literal> signal to
nginx as described in the previous sections.
</para>

<para>
There are many <link doc="http/ngx_http_proxy_module.xml">more</link>
directives that may be used to further configure a proxy connection.
</para>

</section>


<section id="fastcgi" name="Setting Up FastCGI Proxying">

<para>
nginx can be used to route requests to FastCGI servers which run
applications built with various frameworks and programming languages
such as PHP.
</para>

<para>
The most basic nginx configuration to work with a FastCGI server
includes using the
<link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>
directive instead of the <literal>proxy_pass</literal> directive,
and <link doc="http/ngx_http_fastcgi_module.xml" id="fastcgi_param"/>
directives to set parameters passed to a FastCGI server.
Suppose the FastCGI server is accessible on <literal>localhost:9000</literal>.
Taking the proxy configuration from the previous section as a basis,
replace the <literal>proxy_pass</literal> directive with the
<literal>fastcgi_pass</literal> directive and change the parameter to
<literal>localhost:9000</literal>.
In PHP, the <literal>SCRIPT_FILENAME</literal> parameter is used for
determining the script name, and the <literal>QUERY_STRING</literal>
parameter is used to pass request parameters.
The resulting configuration would be:
<programlisting>
server {
    location / {
        fastcgi_pass  localhost:9000;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param QUERY_STRING    $query_string;
    }

    location ~ \.(gif|jpg|png)$ {
        root /data/images;
    }
}
</programlisting>
This will set up a server that will route all requests except for
requests for static images to the proxied server operating on
<literal>localhost:9000</literal> through the FastCGI protocol.
</para>

</section>

</article>