Difference between pages "Package:Nginx" and "Package:Eselect (OpenGL)"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
{{Ebuild
{{Ebuild
|Summary=Robust, small and high performance HTTP and reverse proxy server
|Summary=A Gentoo/Funtoo utility that allows the active OpenGL implementation on a system to be switched between a variety of installed options.
|CatPkg=www-servers/nginx
|CatPkg=app-admin/eselect-opengl
|Maintainer=Drobbins
|Maintainer=
|Repository=Funtoo Overlay
}}
|Overlay=Funtoo
== Introduction ==
}}  
[[Image:nginx.gif|frame]]


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.  
Eselect (OpenGL) (also called <tt>eselect-opengl</tt>) is a module for [[Package:Eselect|Eselect]] that allows the OpenGL implementation on a Funtoo Linux or Gentoo Linux system to be switched between a variety of installed OpenGL implementations. It functions by creating an <tt>env.d</tt> file at <tt>/etc/env.d/03opengl</tt> which contains OpenGL settings, as well as managing symbolic links to OpenGL libraries and headers.  


== Installation ==
=== Sample env.d File ===


=== USE flags ===
A sample <tt>env.d</tt> file for a multilib system with xorg-x11 OpenGL implementation may look like this:


Before you can install nginx, the following USE-flags are available, these can be set by ''/etc/portage/package.use'' or ''/etc/portage/package.use/nginx'', depending on your setup.
{{file|name=/etc/env.d/03opengl|desc=An example env.d file for eselect-opengl|body=
# Configuration file for eselect
# This file has been automatically generated.
LDPATH="/usr/lib32/opengl/xorg-x11/lib:/usr/lib64/opengl/xorg-x11/lib"
OPENGL_PROFILE="xorg-x11"
}}


{{SectionNeedsUpdates}}
== Implementation ==


{| class="wikitable" style="margin: 1em auto;" width=80%
Eselect-opengl is implemented as a single bash-based [[Package:Eselect|Eselect]] module approximately 10K in size, installed at <tt>/usr/share/eselect/modules/opengl.eselect</tt>. One interfaces with this module via the main <tt>eselect</tt> command:
! width="20%" | Use flag
! width="10%" | Default
! width="10%" | Recommended
! width="60%" | Description
|-
| style="text-align:center;" | aio
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables file AIO support.
|-
| style="text-align:center;" | debug
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables extra debug codepaths, like asserts and extra output.
|-
| style="text-align:center;" | http
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables http serving.
|-
| style="text-align:center;" | http-cache
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables caching for http files.
|-
| style="text-align:center;" | ipv6
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables IPv6 support.
|-
| style="text-align:center;" | libatomic
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Use libatomic instead of builtin atomic operations.
|-
| style="text-align:center;" | pcre
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Enables support for Perl Compatible Regular Expressions.
|-
| style="text-align:center;" | ssl
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Adds support for Secure Socket Layer connections.
|-
| style="text-align:center;" | vim-syntax
| style="text-align:center;" | ?
| style="text-align:center;" | ?
| Pulls in related vim syntax scripts.
|}
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".


=== USE Expanded flags ===
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:
<console>
<console>
###i## echo "www-servers/nginx USE-FLAG-List" >> /etc/portage/package.use/nginx
# ##i##eselect opengl help
</console>
Manage the OpenGL implementation used by your system
Usage: eselect opengl <action> <options>


=== Emerging nginx ===
##g##Standard actions:
  help                      Display help text
  usage                    Display usage information
  version                  Display version information


Now you are ready to install nginx with php and xcache support:
##g##Extra actions:
<console>
  list                      List the available OpenGL implementations.
###i## emerge -avt nginx php xcache
  set <target>              Select the OpenGL implementation.
    <target>                  The profile to activate
    --use-old                If an implementation is already set, use that one instead
    --prefix=<val>            Set the source prefix (default: /usr)
    --dst-prefix=<val>       Set the destination prefix (default: /usr)
    --ignore-missing          Ignore missing files when setting a new implementation
  show                      Print the current OpenGL implementation.
</console>
</console>
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:


<pre>
== What is Switched ==
server {
    listen          80;
    server_name    www.example.com;


    access_log      /var/log/nginx/www.example.com.access_log main;
Using <tt>eselect opengl set</tt> causes the following symbolic links to be updated to point to the files corresponding to the OpenGL implementation that you chose:
    error_log      /var/log/nginx/www.example.com.error_log info;


    root /var/www/www.example.com/htdocs;
* ''Libraries'' (32-bit and 64-bit):
}
** <tt>/usr/lib(64)/libGL.so.*</tt>
</pre>  
** <tt>/usr/lib(64)/libEGL.so.*</tt>
** <tt>/usr/lib/(32|64|)/libGLESv1.so.*</tt>
** <tt>/usr/lib/(32|64|)/libGLESv2.so.*</tt>
* ''C Headers'':
** <tt>/usr/include/GL/*</tt>
** <tt>/usr/include/EGL/*</tt>
** <tt>/usr/include/KHR/*</tt>
* <tt>/usr/lib(64|)/xorg/modules/extensions/libglx.so</tt>


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 symbolic links point to an installed OpenGL implementation, stored inside <tt>/usr/lib(32|64|)/opengl/(implementation-name)</tt>. These files are structured as follows:


=== php-fpm ===
* <tt>/usr/lib/opengl/(implementation-name)/lib</tt>
* <tt>/usr/lib/opengl/(implementation-name)/include/(GL|EGL|KHR)</tt>
* <tt>/usr/lib/opengl/(implementation-name)/extensions/libglx.so</tt>


nginx does not natively support php, so we delegate that responsibility to [[Package:Php#Fpm | php-fpm]]
On multilib systems, ebuilds that provide an OpenGL implementation install 32-bit libraries in <tt>/usr/lib32/opengl/(implementation name)/lib</tt> and 64-bit libraries in <tt>/usr/lib64/opengl/(implementation name)/lib</tt>.


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


== Location Processing Order ==
=== Violation of Build Consistency ===
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 ===
As documented in {{Bug|FL-1309}}, sometimes packages fail to merge when the "wrong" eselect opengl implementation is selected. This violates Portage's ability to consistently build a package from source, assuming all its dependencies are satisfied. This could be classified as a design bug -- eselect-opengl is functioning as intended, but its underlying theory of operation is not correct.
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 ===
== eselect-opengl-1.3* experiment ==
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.
=== Introduction ===


== Advanced Location Processing ==
As a result of {{Bug|FL-1309}}, an experimental solution was implemented in eselect-opengl-1.3*. With this version, all packages are built unconditionally against xorg-x11 OpenGL implementation and the other implementations are used only in runtime.
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 ===
The rationale for this design change is that:
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:
# There should be a consistent and repeatable build/linking process for all OpenGL applications.
location = /foo/bar { deny all; }
# AMD and NVIDIA implementations of OpenGL are designed to be more of a "drop-in" runtime replacement for xorg-x11, rather than a standalone replacement for xorg-x11, and thus appear to exhibit more build-time bugs.


=== ~* (case-insensitive regex) Location ===
=== Implementation ===
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 ===
The new version of eselect-opengl switched two files:
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.
* an env.d file <tt>000opengl</tt> specifying <tt>LDPATH</tt> for the run-time implementation override,
* an xorg.conf.d file overriding the ModulePath for custom glx xorg modules.


== Ebuild Update Protocol ==
The env.d file has the same contents as the original one, except that the name was changed to ensure that the additional linker paths are added before the system paths where xorg-x11 libraries are installed.


To work on a new version of the ebuild, perform the following steps.
The xorg.conf.d sets ModulePaths for non-xorg module replacements (such as the nvidia glx module), if necessary.


First, temporarily set the following settings in <tt>/etc/make.conf</tt>:
=== Issues ===


<syntaxhighlight lang="bash">
The widespread testing of eselect-opengl-1.3* has proven some issues with the new design:
NGINX_MODULES_HTTP="*"
NGINX_MODULES_MAIL="*"
</syntaxhighlight>


This will enable all available modules for nginx.
# xorg-server is unable to handle multiple occurences of <code>Files</code> section gracefully. Therefore, eselect-opengl's generated xorg.conf.d file collides with many user-defined configurations. This has been patched locally and the patch is awaiting upstream review)
# There are rumors of arm mali's prioprietary OpenGL implementations requiring applications to be built against its own GLES headers.


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.
{{EbuildFooter}}
{{EbuildFooter}}

Latest revision as of 08:00, March 1, 2015

Eselect (OpenGL)

   Tip

We welcome improvements to this page. To edit this page, 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.

Introduction

Eselect (OpenGL) (also called eselect-opengl) is a module for Eselect that allows the OpenGL implementation on a Funtoo Linux or Gentoo Linux system to be switched between a variety of installed OpenGL implementations. It functions by creating an env.d file at /etc/env.d/03opengl which contains OpenGL settings, as well as managing symbolic links to OpenGL libraries and headers.

Sample env.d File

A sample env.d file for a multilib system with xorg-x11 OpenGL implementation may look like this:

   /etc/env.d/03opengl - An example env.d file for eselect-opengl
# Configuration file for eselect
# This file has been automatically generated.
LDPATH="/usr/lib32/opengl/xorg-x11/lib:/usr/lib64/opengl/xorg-x11/lib"
OPENGL_PROFILE="xorg-x11"

Implementation

Eselect-opengl is implemented as a single bash-based Eselect module approximately 10K in size, installed at /usr/share/eselect/modules/opengl.eselect. One interfaces with this module via the main eselect command: 

root # eselect opengl help
Manage the OpenGL implementation used by your system
Usage: eselect opengl <action> <options>

root ##g##Standard actions:
  help                      Display help text
  usage                     Display usage information
  version                   Display version information

root ##g##Extra actions:
  list                      List the available OpenGL implementations.
  set <target>              Select the OpenGL implementation.
    <target>                  The profile to activate
    --use-old                 If an implementation is already set, use that one instead
    --prefix=<val>            Set the source prefix (default: /usr)
    --dst-prefix=<val>        Set the destination prefix (default: /usr)
    --ignore-missing          Ignore missing files when setting a new implementation
  show                      Print the current OpenGL implementation.

What is Switched

Using eselect opengl set causes the following symbolic links to be updated to point to the files corresponding to the OpenGL implementation that you chose:

  • Libraries (32-bit and 64-bit):
    • /usr/lib(64)/libGL.so.*
    • /usr/lib(64)/libEGL.so.*
    • /usr/lib/(32|64|)/libGLESv1.so.*
    • /usr/lib/(32|64|)/libGLESv2.so.*
  • C Headers:
    • /usr/include/GL/*
    • /usr/include/EGL/*
    • /usr/include/KHR/*
  • /usr/lib(64|)/xorg/modules/extensions/libglx.so

The symbolic links point to an installed OpenGL implementation, stored inside /usr/lib(32|64|)/opengl/(implementation-name). These files are structured as follows:

  • /usr/lib/opengl/(implementation-name)/lib
  • /usr/lib/opengl/(implementation-name)/include/(GL|EGL|KHR)
  • /usr/lib/opengl/(implementation-name)/extensions/libglx.so

On multilib systems, ebuilds that provide an OpenGL implementation install 32-bit libraries in /usr/lib32/opengl/(implementation name)/lib and 64-bit libraries in /usr/lib64/opengl/(implementation name)/lib.

Criticisms

Violation of Build Consistency

As documented in FL-1309, sometimes packages fail to merge when the "wrong" eselect opengl implementation is selected. This violates Portage's ability to consistently build a package from source, assuming all its dependencies are satisfied. This could be classified as a design bug -- eselect-opengl is functioning as intended, but its underlying theory of operation is not correct.

eselect-opengl-1.3* experiment

Introduction

As a result of FL-1309, an experimental solution was implemented in eselect-opengl-1.3*. With this version, all packages are built unconditionally against xorg-x11 OpenGL implementation and the other implementations are used only in runtime.

The rationale for this design change is that:

  1. There should be a consistent and repeatable build/linking process for all OpenGL applications.
  2. AMD and NVIDIA implementations of OpenGL are designed to be more of a "drop-in" runtime replacement for xorg-x11, rather than a standalone replacement for xorg-x11, and thus appear to exhibit more build-time bugs.

Implementation

The new version of eselect-opengl switched two files:

  • an env.d file 000opengl specifying LDPATH for the run-time implementation override,
  • an xorg.conf.d file overriding the ModulePath for custom glx xorg modules.

The env.d file has the same contents as the original one, except that the name was changed to ensure that the additional linker paths are added before the system paths where xorg-x11 libraries are installed.

The xorg.conf.d sets ModulePaths for non-xorg module replacements (such as the nvidia glx module), if necessary.

Issues

The widespread testing of eselect-opengl-1.3* has proven some issues with the new design:

  1. xorg-server is unable to handle multiple occurences of Files section gracefully. Therefore, eselect-opengl's generated xorg.conf.d file collides with many user-defined configurations. This has been patched locally and the patch is awaiting upstream review)
  2. There are rumors of arm mali's prioprietary OpenGL implementations requiring applications to be built against its own GLES headers.


Retrieved from "https://www.funtoo.org/index.php?title=Package:Nginx&oldid=9217"