Difference between pages "How Metro Works" and "Package:Nginx"

(Difference between pages)
(Introduction)
 
m (add media playlist)
 
Line 1: Line 1:
= Introduction =
+
{{Ebuild
 +
|Summary=Robust, small and high performance HTTP and reverse proxy server
 +
|CatPkg=www-servers/nginx
 +
|Maintainer=Drobbins
 +
|Repository=Funtoo Overlay
 +
|Overlay=Funtoo
 +
}}
 +
[[Image:nginx.gif|frame]]
  
[[Metro]] is a somewhat complex set of shell (specifically bash) and python scripts and various files that automagically creates stages 1/2/3 tarballs used to emerge your [[Funtoo Linux]] system.
+
nginx (pronounced "engin-x") is a Web and reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols. It focuses on high concurrency, performance and low memory usage. Nginx quickly delivers static content with efficient use of system resources, also dynamic content is delivered on a network using FastCGI, SCGI handlers for scripts, uWSGI application servers or Phusion Passenger module (atm broken in [http://funtoo.org funtoo]), further more it can serve a very capable software load balancer. It uses an asynchronos event-driven approach to handle requests which provides more predictable performance under load, in contrast to the Apache HTTP server model, that uses a threaded or process-oriented approach to handling request. Nginx is licensed under a BSD-like license and it runs on Unix, Linux, BSD variants, Mac OS X, Solaris, AIX and Microsoft Windows.  
Of course, [[Metro]] needs a seed to start its work and will recompile things like the so well known <tt>gcc</tt> and <tt>glibc</tt>.
+
A 'seed' is either a pre-built stage3 archive available on any Funtoo Linux [http://docs.funtoo.org/wiki/Download mirror] or a snapshot of your current [[Funtoo Linux]] installation.
+
  
= Arborescence description =  
+
=== USE Expanded flags ===
  
== Overview ==
+
Furthermore, you can set the nginx modules you like to use in ''/etc/make.conf'' in the NGINX_MODULES_HTTP variable as NGINX_MODULES_HTTP="variables".
Don't search through your bin directories, everything lies in '''/usr/lib/metro'''. An unfolded view as of Metro revision 1.5.1 is this one :
+
  
<pre>
+
nginx USE flags go into ''/etc/portage/package.use'' or ''/etc/portage/package.use/nginx'', while the HTTP and MAIL modules go as NGINX_MODULES_HTTP or NGINX_MODULES_MAIL are stored in /etc/make.conf. And as you wouldn't server only static html files, but most commonly also php files/scripts you should also install php with fpm enabled and xcache for caching the content, what makes your nginx setup way faster. For xcache you need to set PHP_TARGETS="php5-3" in '/etc/make.conf'.
├── BUGS
+
├── ChangeLog
+
├── TODO
+
├── etc
+
│   ├── builds
+
│   │   ├── funtoo
+
│   │   │   ├── build.conf
+
│   │   │   └── multi-targets
+
│   │   │      ├── freshen
+
│   │   │      ├── full
+
│   │   │      ├── quick
+
│   │   │      ├── stage1
+
│   │   │      └── strategy
+
│   │   │          └── seed
+
│   │   │              ├── stage1
+
│   │   │              └── stage3
+
│   │   ├── gentoo
+
│   │   │   ├── build.conf
+
│   │   │   └── multi-targets
+
│   │   │      ├── freshen
+
│   │   │      ├── full
+
│   │   │      ├── quick
+
│   │   │      ├── stage1
+
│   │   │      └── strategy
+
│   │   │          └── seed
+
│   │   │              ├── stage1
+
│   │   │              └── stage3
+
│   │   ├── hollow
+
│   │   │   ├── build.conf
+
│   │   │   └── multi-targets
+
│   │   │      ├── freshen
+
│   │   │      ├── full
+
│   │   │      ├── quick
+
│   │   │      ├── stage1
+
│   │   │      └── strategy
+
│   │   │          └── seed
+
│   │   │              ├── stage1
+
│   │   │              └── stage3
+
│   │   └── ~funtoo
+
│   │      ├── build.conf
+
│   │      └── multi-targets
+
│   │          ├── freshen
+
│   │          ├── full
+
│   │          ├── quick
+
│   │          ├── stage1
+
│   │          └── strategy
+
│   │              └── seed
+
│   │                  ├── stage1
+
│   │                  └── stage3
+
│   ├── fslayouts
+
│   │   └── funtoo
+
│   │      ├── layout.conf
+
│   │      └── type
+
│   │          ├── image
+
│   │          └── snapshot
+
│   └── metro.conf
+
├── features
+
│   └── probe.conf
+
├── metro
+
├── misc
+
│   └── locale.gen
+
├── modules
+
│   ├── catalyst_support.py
+
│   ├── catalyst_support.pyo
+
│   ├── flexdata.py
+
│   ├── flexdata.pyo
+
│   ├── flexdata2.py
+
│   ├── flexdata3.py
+
│   ├── flexdata4.py
+
│   ├── targets.py
+
│   └── targets.pyo
+
├── scripts
+
│   ├── build.sh
+
│   ├── cleaner.sh
+
│   ├── dlstats.sh
+
│   └── ezbuild.sh
+
├── subarch
+
│   ├── amd64
+
│   │   ├── 2008.spec
+
│   │   └── 2009.spec
+
│   ├── amd64.spec
+
│   ├── athlon-xp.spec
+
│   ├── core2.spec
+
│   ├── core2_32.spec
+
│   ├── generic32.spec
+
│   ├── generic64.spec
+
│   ├── i686
+
│   │   ├── 2008.spec
+
│   │   └── 2009.spec
+
│   ├── i686.spec
+
│   ├── native32.spec
+
│   ├── native64.spec
+
│   ├── opteron-sse3.spec
+
│   ├── opteron.spec
+
│   ├── opteron_32.spec
+
│   ├── pentium4.spec
+
│   ├── phenom.spec
+
│   ├── x86.spec
+
│   ├── xen-nocona.spec
+
│   └── xen-prescott.spec
+
└── targets
+
    └── gentoo
+
        ├── openvz.spec
+
        ├── snapshot
+
        │   ├── common.spec
+
        │   ├── global.spec
+
        │   ├── source
+
        │   │   ├── git
+
        │   │   └── rsync
+
        │   └── type
+
        │      ├── dead
+
        │      └── live
+
        ├── snapshot.spec
+
        ├── stage
+
        │   ├── capture
+
        │   │   ├── ami.spec
+
        │   │   └── tar.spec
+
        │   ├── common.spec
+
        │   ├── files.spec
+
        │   ├── stage3-derivative.spec
+
        │   ├── stage3-generator.spec
+
        │   └── steps.spec
+
        ├── stage1
+
        │   └── strategy
+
        │      ├── local
+
        │      └── remote
+
        ├── stage1.spec
+
        ├── stage2
+
        │   └── strategy
+
        │      ├── local
+
        │      │   ├── stage1
+
        │      │   └── stage3
+
        │      └── remote
+
        │          ├── stage1
+
        │          └── stage3
+
        ├── stage2.spec
+
        ├── stage3-freshen.spec
+
        ├── stage3-quick.spec
+
        ├── stage3.spec
+
        └── stage4.spec
+
</pre>
+
  
For the beginner, just retain that :
+
Example:
 +
<console>
 +
###i## echo "www-servers/nginx USE-FLAG-List" >> /etc/portage/package.use/nginx
 +
</console>
  
# Python is the master of the house, everything (or at least near everything) in Funtoo tools is written Python, and as being a Funtoo tool, Metro in itself plus all of the stuff it uses are written in Python.
+
=== Emerging nginx ===
# The first place to start with Metro tweaking are the .spec files located under '''targets/gentoo'''. Those files control what Metro does at each stage and are basically a melt of Metro directives and some Python embedded scripts and BASH embedded scripts. If something goes wrong.
+
# Another good place to look at is '''subarch''' : you will find here a couple of .spec files that governs how the build toolchain (libc, c/c++ compiler and related tools) will be generated, how they will be used (notice the CHOST variable) and at the end what will be put in the make.conf file in your stages archives.
+
  
The [[Metro Data Model]] page explains the logic used in spec files.
+
Now you are ready to install nginx with php and xcache support:
 +
<console>
 +
###i## emerge -avt nginx php xcache
 +
</console>
 +
so now just check your useflags and press enter to start emerge.
  
TBC
+
== Configuring ==
  
== The GNU toolchain ==
+
All configuration is done in ''/etc/nginx'' with ''nginx.conf'' as the main configuration file and all virtual hosts in ''/etc/nginx/sites/available'' while you have to symlink ''/etc/nginx/sites-available/{VHOST}'' to ''/etc/nginx/sites-enabled/{VHOST}'' to activate them. An example config for such a {VHOST} looks like that:
  
''"How the build toolchain will be generated",'' what does it mean ? As you may know, the GNU toolchain is a '''multiform''' set of tools that translate a source program written in a "high" level language like C, C++ or Fortan in a binary form understandable by the microprocessor of your computer. Moreover this set of tools do various sorts of things like source code grammar and syntax checking, code optimization, dead code removal, code instrumentation, and so on.
+
<pre>
 
+
server {
The '''multiform''' magic keyword  means that the GNU toolchain can be compiled for many processors archicture, this of course include the well-known IA-32 (x86 family processors) but also IA-64 (Itaninum), PA-RISC (HPPA), Motorola 68k series, Dec Alpha, SPARC series, ARM, and many others including the so well known DEC PDP/11 series (technically speaking, with the adequate packages and keywordings, Funtoo could bring the steam power on a DEC PDP/11 machine and it could be possible to build stage 3 images for that platform).
+
    listen          80;
 +
    server_name    www.example.com;
  
Basically the GNU tool chains relies on three components :
+
    access_log      /var/log/nginx/www.example.com.access_log main;
 +
    error_log      /var/log/nginx/www.example.com.error_log info;
  
* The so well-known '''GNU Compilers Collection''' (''sys-devel/gcc'' is the Funtoo package that deploys this suite). A common mistake is to call GNU Compiler, but set that aside for now.
+
    root /var/www/www.example.com/htdocs;
* '''Some related tools called behind the scene''' by the GNU Compiler Collection or required by the GNU autoconf/automake system upon which Funtoo relies on. Those behind the scene tools are for example the GNU linker (ld) or the the GNU Assembler (as). Under Funtoo, those tools are deployed by the package ''sys-devel/binutils''.
+
}
* '''The GNU lib C''' : this one regroups a large set of system functions used by a large numbers of programs out there and contains functionalities like files manipulation, memory allocation, and so on. It can be barely seen as being a software interface (abstraction) between the system kernel and a program that lives in the userland world.
+
</pre>
  
Note : the GNU libC is '''not''' the only one solution available in the Free Software world. Several alternatives like '''uLibC''' or '''newlib''' exist and can be used by the GNU Compiler Collection and the related tools it uses.
+
The ''nginx.conf'' and ''sites-available/localhost'' file is well commented. Customize it to your needs. Make sure you set the listen option correctly. By default, the listen option is set to listen on the loopback interface. If you leave this unchanged other computers on the network will not be able to connect to the server.  
  
The GNU toolchain can be built as being :
+
=== php-fpm ===
  
* '''a native toolchain''' : the computer that runs the toolchain is the same that executes the binaries produced the toolchain, this is the most common case. (e.g. an i686 processor machine running GNU/Linux with the GNU Lib C produces a toolchain that generates binaries for the exact same architecture an i686 processor machine running GNU/Linux with the GNU Lib C).
+
nginx does not natively support php, so we delegate that responsibility to [[Package:Php#Fpm | php-fpm]]
  
* '''a cross-compilation chain''' : the computer that runs the toolchain is NOT the same that executes the produced the toolchain (e.g. an i686 processor running GNU/Linux with the GNU Lib C produces a toolchain that generates binaries for a SPARC machine running Solaris). Moreover, you can do funny brain-dead things like : generate a toolchain running on a PowerPC GNU/Linux system that produces another toolchain targeting a SPARC machine under Solaris which, in its turn, produces binaries targeting an Alpha machine running under FreeBSD).
+
{{file|name=/etc/nginx/sites-available/localhost|desc=fpm configuration|body=
 +
server {
 +
        ...
 +
index index.php index.cgi index.htm index.html;
 +
location ~ .php$ {
 +
        fastcgi_pass 127.0.0.1:9000;
 +
include fastcgi.conf;
 +
        }
 +
        ...
 +
}
 +
}}
  
== Have you ever noticed ? ==
+
==== php caching ====
 +
{{file|name=/etc/nginx/sites-available/localhost|desc=fpm cache configuration|body=
 +
fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=MYAPP:100m inactive=60m;
 +
fastcgi_cache_key "$scheme$request_method$host$request_uri";
 +
server {
 +
...
 +
        location ~ \.php$ {
 +
...
 +
fastcgi_cache MYAPP;
 +
fastcgi_cache_valid 200 60m;
 +
...
 +
}}
 +
[https://www.digitalocean.com/community/tutorials/how-to-setup-fastcgi-caching-with-nginx-on-your-vps for more information on php caching]
  
By '''CONVENTION''', the GNU toolchain internal mechanisms '''REQUIRES''' to prefix all the toolchain executables by a quadruplet as below :
+
=== proxy_pass===
 +
This configuration proxies to other webservers.  In this example we have webrick running on port 3000 behind nginx producing the live link http://localhost/rails
  
<pre>CPU-machine-OS-libC</pre>
+
{{file|name=/etc/nginx/sites-available/localhost|desc=rails or python configurations|body=
 +
server {
 +
        ...
 +
location /rails/ {
 +
    proxy_set_header Host $host;
 +
    proxy_set_header X-Real-IP $remote_addr;
 +
    proxy_pass http://127.0.0.1:3000/; #for ruby on rails webrick
 +
            #proxy_pass http://127.0.0.1:8000/; #for python -m http.server
 +
            #proxy_pass http://127.0.0.1:8080/; #for other web servers like apache, lighttpd, tengine, cherokee, etc...
 +
}
 +
        ...
 +
}
 +
}}
  
* '''CPU''' : i486, i686, sparc, sparc64, alpha...
+
== Location Processing Order ==
* '''machine''' :  pc, sun4u, unknown...
+
One often confusing aspect of nginx configuration is the order in which it processes location directives. This section is intended to clarify the confusion and help you to write secure nginx location directives.  
* '''OS''' : linux, solaris, freebsd...
+
* '''libC''' : gnu (for glibc), ulibc...
+
  
This is stricly conventional but powerful as it allows the toolchain to easily detect when it has to be build it as a native toolchain or as a cross-compilation toolchain. Also note that some architectures like SPARC version 9 (i.e. UltraSPARC) uses a 64 bits kernel and 32 bits userland binaries (although it is possible to have 64 bits binaries, most of the time producing 64 bits binaries does not bring any advantage and worse, can degrade the performance on some machines due to additional memory read/write cycles required to get/write 64 bits values). This is exactly the reason why you have '''sys-devel/gcc''' and '''sys-devel/kgcc64''', the later being only used to build the system kernel.
+
=== Two basic types of Location directives ===
 +
There are two basic types of location directives. The first is called a "conventional string", and looks something like this:
 +
location /foo { deny all; }
 +
The second basic type of location directive is a regex, or regular expression block. In its most basic form, it looks like this, with a "~" and then a regular expression that is matched against the request path. "^" can be used to match the beginning of the request path, and "$" can be used to match the end of the request path. If you need to match a ".", you must escape it as "\." as per regular expression matching rules:
 +
location ~ \.php$ { blah; }
  
Now lets have a look on your machine at :
+
=== The basic algorithm ===
 +
Nginx uses a special algorithm to find the proper location string to match the incoming request. The basic concept to remember is that conventional string directives are placed in one "bucket", and then regular expression strings are placed in another "bucket". Nginx will use the first regular expression match that it finds, when scanning the file from top to bottom. If no matching regular expression is found, nginx will look in its "conventional string" bucket, and try to find a match. In the case of the conventional string matches, the most ''specific'' match will be used, in other words, the one will be used that matches the greatest number of characters in the request path.
  
* the '''CHOST''' variable in your '''/etc/make.conf''' and what lies under your /usr/sbin.
+
This is the foundation for nginx location processing, so always use these rules as a starting point for understanding location matching order. Nginx then provides various sub-types of location directives which modify this default behavior in a number of ways. This will be covered in the next section.
* where points commands like '''/usr/bin/ld''' or '''/usr/bin/as'''
+
* what prefixes g++ or gcc in /usr/bin (take note that /usr/bin/g++ and /usr/bin/<CPU-machine-OS-libC>-g++ are exactly the same).
+
  
This is not a coincidence if the CHOST variable and the prefix used by the toolchain executables matches ;-)
+
== Advanced Location Processing ==
 +
Always use the location processing logic described in the previous section as the foundation for understanding how nginx finds a matching location directive, and then once you are comfortable with how this works, read about these more advanced directives and understand how they fit into nginx's overall logic.
  
= How things works ? =
+
=== = (equals) Location ===
 +
One advanced location directive is the "=" location, which can be considered a variant of a "conventional string" directive. "=" directives are searched before all other directives, and if a match found, then the corresponding location block is used. A "=" location must the requested path ''exactly'' and ''completely''. For example, the following location block will match only the request /foo/bar, but not /foo/bar/oni.html:
 +
location = /foo/bar { deny all; }
  
 +
=== ~* (case-insensitive regex) Location ===
 +
A "~*" regex match is just like a regular "~" regex match, except matches will be performed in a case-insensitive manner. "~*" location directives, being regex directives, fall into the regex "bucket" and are processed along other regex directives. This means that they are processed in the order they appear in your configuration file and the first match will be used -- assuming no "=" directives match.
  
Playing with the cross-compilation capablities  of the GNU toolchain is out the scope of this article, just retain on this subject that it is mainly used with embedded systems which have too few resources to host a full compilation system or in build farms that generates binaries for several CPU architectures because it is now the time to dive in the main course of the action.
+
=== ^~ (short-circuit conventional string) Location ===
 +
You may think that a "^~" location is a regex location, but it is not. It is a variant of a conventional string location. If you recall, nginx will search for conventional string matches by finding the ''most specific'' match. However, when you use a "^~" location, nginx behavior is modified. Imagine the way a conventional string match works. Nginx scans your configuration file, looking at each conventional string match from line 1 to the end of file, but it scans ''all'' conventional string matches to find the ''best'' match. Well, the "~^" location match short-circuits this process. If, in the process of scanning each conventional string match in the config file, nginx encounters a "^~" match that matches the current request path, then nginx will apply this match, and stop looking for the ''best'' match.
  
As you may have noticed in the [[Metro Quick Start Tutorial]] the beginning of the story lies in the script
+
== Ebuild Update Protocol ==
  
TBC
+
To work on a new version of the ebuild, perform the following steps.
  
= Adding a new sub architecture =
+
First, temporarily set the following settings in <tt>/etc/make.conf</tt>:
  
As of January 2011, Metro can handle the IA-32 architecture (x86/32 and x86/64 bits) as well as being able to handle several x86 flavous lying beneath the generic 'x86 and 'amd64' taxonomies. The example here is a try to add the necessary specification file to make it generate stage 1/2/3 tarballs for tiers architectures.
+
<syntaxhighlight lang="bash">
 +
NGINX_MODULES_HTTP="*"
 +
NGINX_MODULES_MAIL="*"
 +
</syntaxhighlight>
  
 +
This will enable all available modules for nginx.
  
 +
Now, create a new version of the ebuild in your overlay, and look at all the modules listed at the top of the ebuild. Visit the URLs in the comments above each one and ensure that the latest versions of each are included. Now run <tt>ebuild nginx-x.y.ebuild clean install</tt> to ensure that all modules patch/build properly. Basic build testing is now complete.
  
[[Category:Metro]]
+
== Media ==
 +
{{#widget:YouTube|playlist=PL0k5C_Zqzft0QyD3G4l9cp8h1waSuNWlm}}
 +
{{EbuildFooter}}

Revision as of 22:59, January 2, 2015

www-servers/nginx


Current Maintainer(s):Daniel Robbins
Source Repository:Funtoo Overlay

Summary: Robust, small and high performance HTTP and reverse proxy server

Use Flags

addition
Enables HTTP addition filter module
aio
Enables file AIO support
flv
Enables special processing module for flv files
http
Enable HTTP core support
http-cache
Enable HTTP cache support
libatomic
Use libatomic instead of builtin atomic operations
pop
Enables POP3 proxy support
random-index
Enables HTTP random index module
realip
Enables realip module
smtp
Enables SMTP proxy support
static-gzip
Enables support for gzipping static content
status
Enables stub_status module
sub
Enables sub_filter module
webdav
Enable webdav support

News

Drobbins

Pre-built kernels!

Funtoo stage3's are now starting to offer pre-built kernels for ease of install. read more....
12 May 2015 by Drobbins
Drobbins

Better Experiences: Ego and Vim

Info on Funtoo's new personality tool called 'ego', and user-focused updates to vim's defaults.
27 April 2015 by Drobbins
Drobbins

How We're Keeping You At the Center of the Funtoo Universe

Read about recent developments that keep you, our users, at the forefront of our focus as Funtoo moves forward.
10 April 2015 by Drobbins
View More News...

Nginx

Tip

This is a wiki page. To edit it, Create a Funtoo account. Then log in and then click here to edit this page. See our editing guidelines to becoming a wiki-editing pro.

Nginx.gif

nginx (pronounced "engin-x") is a Web and reverse proxy server for HTTP, SMTP, POP3 and IMAP protocols. It focuses on high concurrency, performance and low memory usage. Nginx quickly delivers static content with efficient use of system resources, also dynamic content is delivered on a network using FastCGI, SCGI handlers for scripts, uWSGI application servers or Phusion Passenger module (atm broken in funtoo), further more it can serve a very capable software load balancer. It uses an asynchronos event-driven approach to handle requests which provides more predictable performance under load, in contrast to the Apache HTTP server model, that uses a threaded or process-oriented approach to handling request. Nginx is licensed under a BSD-like license and it runs on Unix, Linux, BSD variants, Mac OS X, Solaris, AIX and Microsoft Windows.

USE Expanded flags

Furthermore, you can set the nginx modules you like to use in /etc/make.conf in the NGINX_MODULES_HTTP variable as NGINX_MODULES_HTTP="variables".

nginx USE flags go into /etc/portage/package.use or /etc/portage/package.use/nginx, while the HTTP and MAIL modules go as NGINX_MODULES_HTTP or NGINX_MODULES_MAIL are stored in /etc/make.conf. And as you wouldn't server only static html files, but most commonly also php files/scripts you should also install php with fpm enabled and xcache for caching the content, what makes your nginx setup way faster. For xcache you need to set PHP_TARGETS="php5-3" in '/etc/make.conf'.

Example:

# echo "www-servers/nginx USE-FLAG-List" >> /etc/portage/package.use/nginx

Emerging nginx

Now you are ready to install nginx with php and xcache support:

# emerge -avt nginx php xcache

so now just check your useflags and press enter to start emerge.

Configuring

All configuration is done in /etc/nginx with nginx.conf as the main configuration file and all virtual hosts in /etc/nginx/sites/available while you have to symlink /etc/nginx/sites-available/{VHOST} to /etc/nginx/sites-enabled/{VHOST} to activate them. An example config for such a {VHOST} looks like that:

server {
    listen          80;
    server_name     www.example.com;

    access_log      /var/log/nginx/www.example.com.access_log main;
    error_log       /var/log/nginx/www.example.com.error_log info;

    root /var/www/www.example.com/htdocs;
}

The nginx.conf and sites-available/localhost file is well commented. Customize it to your needs. Make sure you set the listen option correctly. By default, the listen option is set to listen on the loopback interface. If you leave this unchanged other computers on the network will not be able to connect to the server.

php-fpm

nginx does not natively support php, so we delegate that responsibility to php-fpm

/etc/nginx/sites-available/localhost - fpm configuration
server {
        ...
	index index.php index.cgi index.htm index.html;
	location ~ .php$ {
	        fastcgi_pass 127.0.0.1:9000;
		include fastcgi.conf;
        }
        ...
}

php caching

/etc/nginx/sites-available/localhost - fpm cache configuration
fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=MYAPP:100m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
server {
...
        location ~ \.php$ {
...
		fastcgi_cache MYAPP;
		fastcgi_cache_valid 200 60m;
...

for more information on php caching

proxy_pass

This configuration proxies to other webservers. In this example we have webrick running on port 3000 behind nginx producing the live link http://localhost/rails

/etc/nginx/sites-available/localhost - rails or python configurations
server {
        ...
	location /rails/ {
	    proxy_set_header Host $host;
	    proxy_set_header X-Real-IP $remote_addr;
	    proxy_pass http://127.0.0.1:3000/; #for ruby on rails webrick
            #proxy_pass http://127.0.0.1:8000/; #for python -m http.server
            #proxy_pass http://127.0.0.1:8080/; #for other web servers like apache, lighttpd, tengine, cherokee, etc...
	}
        ...
}

Location Processing Order

One often confusing aspect of nginx configuration is the order in which it processes location directives. This section is intended to clarify the confusion and help you to write secure nginx location directives.

Two basic types of Location directives

There are two basic types of location directives. The first is called a "conventional string", and looks something like this:

location /foo { deny all; }

The second basic type of location directive is a regex, or regular expression block. In its most basic form, it looks like this, with a "~" and then a regular expression that is matched against the request path. "^" can be used to match the beginning of the request path, and "$" can be used to match the end of the request path. If you need to match a ".", you must escape it as "\." as per regular expression matching rules:

location ~ \.php$ { blah; }

The basic algorithm

Nginx uses a special algorithm to find the proper location string to match the incoming request. The basic concept to remember is that conventional string directives are placed in one "bucket", and then regular expression strings are placed in another "bucket". Nginx will use the first regular expression match that it finds, when scanning the file from top to bottom. If no matching regular expression is found, nginx will look in its "conventional string" bucket, and try to find a match. In the case of the conventional string matches, the most specific match will be used, in other words, the one will be used that matches the greatest number of characters in the request path.

This is the foundation for nginx location processing, so always use these rules as a starting point for understanding location matching order. Nginx then provides various sub-types of location directives which modify this default behavior in a number of ways. This will be covered in the next section.

Advanced Location Processing

Always use the location processing logic described in the previous section as the foundation for understanding how nginx finds a matching location directive, and then once you are comfortable with how this works, read about these more advanced directives and understand how they fit into nginx's overall logic.

= (equals) Location

One advanced location directive is the "=" location, which can be considered a variant of a "conventional string" directive. "=" directives are searched before all other directives, and if a match found, then the corresponding location block is used. A "=" location must the requested path exactly and completely. For example, the following location block will match only the request /foo/bar, but not /foo/bar/oni.html:

location = /foo/bar { deny all; }

~* (case-insensitive regex) Location

A "~*" regex match is just like a regular "~" regex match, except matches will be performed in a case-insensitive manner. "~*" location directives, being regex directives, fall into the regex "bucket" and are processed along other regex directives. This means that they are processed in the order they appear in your configuration file and the first match will be used -- assuming no "=" directives match.

^~ (short-circuit conventional string) Location

You may think that a "^~" location is a regex location, but it is not. It is a variant of a conventional string location. If you recall, nginx will search for conventional string matches by finding the most specific match. However, when you use a "^~" location, nginx behavior is modified. Imagine the way a conventional string match works. Nginx scans your configuration file, looking at each conventional string match from line 1 to the end of file, but it scans all conventional string matches to find the best match. Well, the "~^" location match short-circuits this process. If, in the process of scanning each conventional string match in the config file, nginx encounters a "^~" match that matches the current request path, then nginx will apply this match, and stop looking for the best match.

Ebuild Update Protocol

To work on a new version of the ebuild, perform the following steps.

First, temporarily set the following settings in /etc/make.conf:

NGINX_MODULES_HTTP="*"
NGINX_MODULES_MAIL="*"

This will enable all available modules for nginx.

Now, create a new version of the ebuild in your overlay, and look at all the modules listed at the top of the ebuild. Visit the URLs in the comments above each one and ensure that the latest versions of each are included. Now run ebuild nginx-x.y.ebuild clean install to ensure that all modules patch/build properly. Basic build testing is now complete.

Media