diff --git a/source/conf.py b/source/conf.py index 7bde283c..fecd8ab6 100644 --- a/source/conf.py +++ b/source/conf.py @@ -41,50 +41,70 @@ source_suffix = '.rst' rst_epilog = """ -.. |HttpRewriteModule| replace:: HttpRewriteModule +.. |HttpRewriteModule| replace:: ngx_http_rewrite_module .. _HttpRewriteModule: http://nginx.org/en/docs/http/ngx_http_rewrite_module.html -.. |HttpAccessModule| replace:: HttpAccessModule + +.. |HttpAccessModule| replace:: ngx_http_access_module .. _HttpAccessModule: http://nginx.org/en/docs/http/ngx_http_access_module.html -.. |HttpLogModule| replace:: HttpLogModule + +.. |HttpLogModule| replace:: ngx_http_log_module .. _HttpLogModule: http://nginx.org/en/docs/http/ngx_http_log_module.html -.. |HttpCoreModule| replace:: HttpCoreModule + +.. |HttpCoreModule| replace:: ngx_http_core_module .. _HttpCoreModule: http://nginx.org/en/docs/http/ngx_http_core_module.html -.. |HttpEchoModule| replace:: HttpEchoModule + +.. |HttpEchoModule| replace:: ngx_http_echo_module .. _HttpEchoModule: http://nginx.org/en/docs/http/ngx_http_echo_module.html -.. |HttpUpstreamModule| replace:: HttpUpstreamModule + +.. |HttpUpstreamModule| replace:: /ngx_http_upstream_module .. _HttpUpstreamModule: http://nginx.org/en/docs/http/ngx_http_upstream_module.html -.. |HttpProxyModule| replace:: HttpProxyModule + +.. |HttpProxyModule| replace:: ngx_http_proxy_module .. _HttpProxyModule: http://nginx.org/en/docs/http/ngx_http_proxy_module.html -.. |HttpFastCGIModule| replace:: HttpFastCGIModule + +.. |HttpFastCGIModule| replace:: ngx_http_fastcgi_module .. _HttpFastCGIModule: http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html -.. |HttpSsiModule| replace:: HttpSsiModule + +.. |HttpSsiModule| replace:: ngx_http_ssi_module .. _HttpSsiModule: http://nginx.org/en/docs/http/ngx_http_ssi_module.html -.. |HttpMapModule| replace:: HttpMapModule + +.. |HttpMapModule| replace:: ngx_http_map_module .. _HttpMapModule: http://nginx.org/en/docs/http/ngx_http_map_module.html -.. |HttpGZipModule| replace:: HttpGZipModule + +.. |HttpGZipModule| replace:: ngx_http_gzip_module .. _HttpGZipModule: http://nginx.org/en/docs/http/ngx_http_gzip_module.html + +.. |MailCoreModule| replace:: ngx_mail_core_module + +.. ngx_mail_core_module: http://nginx.org/en/docs/mail/ngx_mail_core_module.html + + +.. |EventsModule| replace:: ngx_http_core_module + +.. EventsModule: http://nginx.org/en/docs/http/ngx_http_core_module.html + """ # The encoding of source files. diff --git a/source/contributing/writing_docs.rst b/source/contributing/writing_docs.rst index 6e29da12..eebb013d 100644 --- a/source/contributing/writing_docs.rst +++ b/source/contributing/writing_docs.rst @@ -114,7 +114,7 @@ There are internal links as well as external links that are possible. .. _reference-location: - `Nginx Website `_ + `Nginx Website `_ A link to another document: :doc:`index` @@ -122,7 +122,7 @@ There are internal links as well as external links that are possible. .. _reference-location: -`Nginx Website `_ +`Nginx Website `_ A link to another document: :doc:`index` diff --git a/source/index.rst b/source/index.rst index 4a2e583a..4e982314 100644 --- a/source/index.rst +++ b/source/index.rst @@ -37,6 +37,7 @@ Zappos, Media Temple, Heroku, RightScale, Engine Yard, and many others. modules/index contributing/index start/index + temp/index .. |moduleicon| replace:: :icon:`puzzle-piece` .. _moduleicon: modules/index.html diff --git a/source/modules/auth_digest.rst b/source/modules/auth_digest.rst index 5ea4900e..8cb75437 100644 --- a/source/modules/auth_digest.rst +++ b/source/modules/auth_digest.rst @@ -174,4 +174,3 @@ This module is licensed under the terms of the :github:`BSD license `_ definition of basic and digest authentication. * Shane Holloway's werkzeug `module `_ which was used as a reference implementation. - diff --git a/source/modules/circle_gif.rst b/source/modules/circle_gif.rst old mode 100755 new mode 100644 index c8ec2f15..6e1bfcac --- a/source/modules/circle_gif.rst +++ b/source/modules/circle_gif.rst @@ -75,9 +75,11 @@ Where *radius* is the radius in pixels, and the colors are 24-bit hex colors (e. Installation ------------ -You first need the ImageMagick development headers. +You first need the ImageMagick development headers. This module is not distributed with the Nginx source. You can download the circle_gif module :github:`here `. -This module is not distributed with the Nginx source. You can download the circle_gif module `here `_. +.. + Dead link + You can download the circle_gif module `here `_. After extracting, add the following option to your Nginx ``./configure`` command: diff --git a/source/modules/clojure.rst b/source/modules/clojure.rst old mode 100755 new mode 100644 diff --git a/source/modules/concat.rst b/source/modules/concat.rst old mode 100755 new mode 100644 index 94ea155d..28ff67ac --- a/source/modules/concat.rst +++ b/source/modules/concat.rst @@ -100,7 +100,7 @@ size of your platform. On Linux you can get the page size issuing:: Usually is 4k. So if you try to concatenate a lot of files together in a given context you might hit this barrier. To overcome that OS defined limitation you must use -the `large_client_header_buffers `_ +the `large_client_header_buffers <|HttpCoreModule|#large_client_header_buffers>`_ directive. Set it to the value you need. diff --git a/source/modules/consistent_hash.rst b/source/modules/consistent_hash.rst old mode 100755 new mode 100644 diff --git a/source/modules/domain_resolve.rst b/source/modules/domain_resolve.rst old mode 100755 new mode 100644 diff --git a/source/modules/drizzle.rst b/source/modules/drizzle.rst old mode 100755 new mode 100644 diff --git a/source/modules/echo.rst b/source/modules/echo.rst old mode 100755 new mode 100644 diff --git a/source/modules/extended_status.rst b/source/modules/extended_status.rst old mode 100755 new mode 100644 diff --git a/source/modules/fair_balancer.rst b/source/modules/fair_balancer.rst old mode 100755 new mode 100644 diff --git a/source/modules/fancy_index.rst b/source/modules/fancy_index.rst old mode 100755 new mode 100644 diff --git a/source/modules/foot_filter.rst b/source/modules/foot_filter.rst old mode 100755 new mode 100644 diff --git a/source/modules/form_input.rst b/source/modules/form_input.rst old mode 100755 new mode 100644 diff --git a/source/modules/groovy_handler.rst b/source/modules/groovy_handler.rst old mode 100755 new mode 100644 diff --git a/source/modules/headers_more.rst b/source/modules/headers_more.rst old mode 100755 new mode 100644 diff --git a/source/modules/healthcheck.rst b/source/modules/healthcheck.rst old mode 100755 new mode 100644 diff --git a/source/modules/iconv.rst b/source/modules/iconv.rst old mode 100755 new mode 100644 diff --git a/source/modules/java_handler.rst b/source/modules/java_handler.rst old mode 100755 new mode 100644 diff --git a/source/modules/keepalive.rst b/source/modules/keepalive.rst old mode 100755 new mode 100644 diff --git a/source/modules/ketama_chash.rst b/source/modules/ketama_chash.rst old mode 100755 new mode 100644 diff --git a/source/modules/lua.rst b/source/modules/lua.rst old mode 100755 new mode 100644 diff --git a/source/modules/memc.rst b/source/modules/memc.rst old mode 100755 new mode 100644 diff --git a/source/modules/mp4_streaming.rst b/source/modules/mp4_streaming.rst old mode 100755 new mode 100644 diff --git a/source/modules/owner_match.rst b/source/modules/owner_match.rst old mode 100755 new mode 100644 diff --git a/source/modules/push_stream.rst b/source/modules/push_stream.rst old mode 100755 new mode 100644 diff --git a/source/modules/rdns.rst b/source/modules/rdns.rst old mode 100755 new mode 100644 diff --git a/source/modules/redis.rst b/source/modules/redis.rst old mode 100755 new mode 100644 diff --git a/source/modules/redis2.rst b/source/modules/redis2.rst old mode 100755 new mode 100644 diff --git a/source/modules/rrd_graph.rst b/source/modules/rrd_graph.rst old mode 100755 new mode 100644 diff --git a/source/modules/secure_download.rst b/source/modules/secure_download.rst old mode 100755 new mode 100644 diff --git a/source/modules/set_misc.rst b/source/modules/set_misc.rst old mode 100755 new mode 100644 diff --git a/source/modules/slice.rst b/source/modules/slice.rst old mode 100755 new mode 100644 diff --git a/source/modules/sr_cache.rst b/source/modules/sr_cache.rst old mode 100755 new mode 100644 diff --git a/source/modules/substitutions.rst b/source/modules/substitutions.rst old mode 100755 new mode 100644 diff --git a/source/modules/upload.rst b/source/modules/upload.rst old mode 100755 new mode 100644 diff --git a/source/modules/user_agent.rst b/source/modules/user_agent.rst old mode 100755 new mode 100644 diff --git a/source/modules/zip.rst b/source/modules/zip.rst old mode 100755 new mode 100644 diff --git a/source/start/topics/recipes/mybb.rst b/source/start/topics/recipes/mybb.rst index b040f27f..6b7e4a9e 100644 --- a/source/start/topics/recipes/mybb.rst +++ b/source/start/topics/recipes/mybb.rst @@ -34,7 +34,7 @@ Recipe } -There is a potential security flaw, e.g. if a user uploads an avatar images pic.gif with valid PHP-Code and calls it with /uploades/avatars/pic.gif/foo.php. The issue is discussed `here `_. Because the link is ending with .php, nginx is passing it to the PHP interpreter. PHP can't find the file /uploades/avatars/pic.gif/foo.php, but it tries to be smart and executes /uploades/avatars/pic.gif as an PHP-script. To avoid this, you need to set cgi.fix_pathinfo=0 in your php.ini, which is set to cgi.fix_pathinfo=1 as default (unfortunately). +There is a potential security flaw, e.g. if a user uploads an avatar images pic.gif with valid PHP-Code and calls it with /uploades/avatars/pic.gif/foo.php. The issue is discussed `here `. Because the link is ending with .php, nginx is passing it to the PHP interpreter. PHP can't find the file /uploades/avatars/pic.gif/foo.php, but it tries to be smart and executes /uploades/avatars/pic.gif as an PHP-script. To avoid this, you need to set cgi.fix_pathinfo=0 in your php.ini, which is set to cgi.fix_pathinfo=1 as default (unfortunately). See :doc:`../examples/phpfcgi` for details on creating the UNIX socket and `this forum post `_ on enabling human-understandable (aka SEO-friendly or human-readable) URLs using the Google SEO plugin. diff --git a/source/start/topics/recipes/piwik.rst b/source/start/topics/recipes/piwik.rst index 97e71035..46f8f4d6 100644 --- a/source/start/topics/recipes/piwik.rst +++ b/source/start/topics/recipes/piwik.rst @@ -4,13 +4,12 @@ Piwik Recipe ------ -This configuration file was provided by Seph. You can see the complete information [https://github.com/perusio/piwik-nginx here]. +This configuration file was provided by Seph. You can see the complete information :github:`here `. .. code-block:: nginx server { - ## This is to avoid the spurious if for sub-domain name - ## rewriting. See http://wiki.nginx.org/Pitfalls#Server_Name. + ## This is to avoid the spurious if for sub-domain name rewriting. listen [::]:80; server_name www.stats.example.com; rewrite ^ $scheme://stats.example.com$request_uri? permanent; @@ -22,7 +21,7 @@ This configuration file was provided by Seph. You can see the complete informati server_name stats.example.com; # Parameterization using hostname of access and log filenames. - access_log /var/log/nginx/stats.example.com_access.log; + access_log /var/log/nginx/stats.example.com_access.log; error_log /var/log/nginx/stats.example.com_error.log; # Disable all methods besides HEAD, GET and POST. diff --git a/source/start/topics/recipes/silverstripe.rst b/source/start/topics/recipes/silverstripe.rst index 5bc9f9ed..e17caef7 100644 --- a/source/start/topics/recipes/silverstripe.rst +++ b/source/start/topics/recipes/silverstripe.rst @@ -1,19 +1,24 @@ SilverStripe ============ -`SilverStripe `_ is a modern PHP based CMS Framework that runs happily on nginx. There are several built in failsafes that will attempt to rectify any errors in rewrite rules. First, SS relies on an .htaccess file to define how to handle URLs. Second, in the event that rewriting has failed the index.php file will attempt to set internal variables and include the core /sapphire/main.php file for processing. +`SilverStripe `_ is a modern PHP based CMS Framework that runs happily on nginx. + +There are several built in failsafes that will attempt to rectify any errors in rewrite rules. +First, SS relies on an ``.htaccess`` file to define how to handle URLs. +Second, in the event that rewriting has failed the ``index.php`` file will attempt to set internal variables and include the core ``/sapphire/main.php`` file for processing. .. note:: - These instructions assume you are using PHP configured as :doc:`../examples/phpfcgi` or PHP-FPM listening on 127.0.0.1:9000. Make any appropriate changes fastcgi_params as needed for your environment. + These instructions assume you are using PHP configured as :doc:`../examples/phpfcgi` or PHP-FPM listening on 127.0.0.1:9000. + Make any appropriate changes `fastcgi_params <|HttpFastCGIModule|#fastcgi_params>`_ as needed for your environment. Recipe ------ The basic rewrite that controls all SilverStripe calls involve passing the URI and any GET vars to ``$document_root/framework/main.php``. -# Remove the .htaccess file and index.php in the root of your SilverStripe installation (Just to be sure) -# Apply a config similar to the following: +#. Remove the ``.htaccess`` file and ``index.php`` in the root of your SilverStripe installation (Just to be sure) +#. Apply a config similar to the following: .. code-block:: nginx @@ -64,7 +69,7 @@ The basic rewrite that controls all SilverStripe calls involve passing the URI a location ~ \.ya?ml$ { deny all; } - + location ^~ /vendor/ { deny all; } diff --git a/source/start/topics/recipes/wordpress.rst b/source/start/topics/recipes/wordpress.rst index d07c1dee..2d2243df 100644 --- a/source/start/topics/recipes/wordpress.rst +++ b/source/start/topics/recipes/wordpress.rst @@ -96,7 +96,7 @@ Rewrite rules for Multisite `WordPress Multisite `_ can be used in multiple ways. Most notably "subdirectories" mode and "subdomains" mode. -Nginx provides 2 special directive: `X-Accel-Redirect `_ and `map `_. Using these 2 directives, one can eliminate performance hit for static-file serving on WordPress multisite network. +Nginx provides 2 special directive: `X-Accel-Redirect ` and `map `_. Using these 2 directives, one can eliminate performance hit for static-file serving on WordPress multisite network. Rewrite rules for Multisite using subdirectories """""""""""""""""""""""""""""""""""""""""""""""" diff --git a/source/start/topics/tutorials/basics_linux.rst b/source/start/topics/tutorials/basics_linux.rst index 94888b84..6a59b86f 100644 --- a/source/start/topics/tutorials/basics_linux.rst +++ b/source/start/topics/tutorials/basics_linux.rst @@ -19,15 +19,11 @@ section of the tutorial. Dead links now - Basic Linux Commands via `Google Code University`_ - Command Line Introduction via `tuxFiles`_ + - Learning the Shell via `LinuxCommand`_ -- Learning the Shell via `LinuxCommand`_ - -.. - Dead links now .. _Google Code University: http://code.google.com/edu/tools101/linux/basics.html .. _tuXfiles: http://www.tuxfiles.org/linuxhelp/cli.html - -.. _LinuxCommand: http://linuxcommand.org/learning_the_shell.php + .. _LinuxCommand: http://linuxcommand.org/learning_the_shell.php CLI Basics ========== diff --git a/source/temp/commandline.rst b/source/temp/commandline.rst new file mode 100644 index 00000000..9b1fe37e --- /dev/null +++ b/source/temp/commandline.rst @@ -0,0 +1,206 @@ +CommandLine +=========== + +Starting, Stopping, and Restarting Nginx +---------------------------------------- +This page shows you how to start Nginx, and once it's running, how to control it so that it will stop or restart. + + +Starting Nginx +^^^^^^^^^^^^^^ +Nginx is invoked from the command line, usually from ``/usr/bin/nginx``. + +Basic Example of Starting Nginx +""""""""""""""""""""""""""""""" + +.. code-block:: bash + + /usr/bin/nginx + + +Advanced Example of Starting Nginx +"""""""""""""""""""""""""""""""""" + +.. code-block:: bash + + /usr/bin/nginx -t -c ~/mynginx.conf -g "pid /var/run/nginx.pid; worker_processes 2;" + + +Options +^^^^^^^ + ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-?, -h`` | Print help. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-v`` | Print version. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-V`` | Print nginx version, compiler version and configure parameters. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-t`` | Don't run, just test the configuration file. | +| | Nginx checks configuration for correct syntax and then try to open files referred in configuration. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-q`` | Suppress non-error messages during configuration testing. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-s signal`` | Send signal to a master process: stop, quit, reopen, reload. (version >= 0.7.53) | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-p prefix`` | Set prefix path (default: ``/usr/local/nginx/``). (version >= 0.7.53) | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-c filename`` | Specify which configuration file Nginx should use instead of the default. | ++-------------------+-----------------------------------------------------------------------------------------------------+ +| ``-g directives`` | Set `global <|HttpCoreModule|>`_ directives. (version >= 0.7.4) | ++-------------------+-----------------------------------------------------------------------------------------------------+ + +.. note:: Nginx has only a few command-line parameters. Unlike many other software systems, the configuration is done entirely via the configuration file (imagine that). + + +Stopping or Restarting Nginx +---------------------------- +There are two ways to control Nginx once it's already running. +The first is to call Nginx again with the ``-s`` command line parameter. +For example, ``/usr/bin/nginx -s stop`` will stop the Nginx server. +(other ``-s`` options are given in the previous section) + +The second way to control Nginx is to send a signal to the Nginx master process... +By default nginx writes its master process id to ``/usr/local/nginx/logs/nginx.pid``. +You can change this by passing parameter with ``./configure`` at compile-time or by using ``pid`` directive in the configuration file. + +Here's how to send the ``QUIT`` (Graceful Shutdown) signal to the Nginx master process: + +.. code-block:: bash + + kill -QUIT $( cat /usr/local/nginx/logs/nginx.pid ) + +The master process can handle the following signals: + ++-----------+---------------------------------------------------------+ +| TERM, INT | Quick shutdown | ++-----------+---------------------------------------------------------+ +| QUIT | Graceful shutdown | ++-----------+---------------------------------------------------------+ +| KILL | Halts a stubborn process | ++-----------+---------------------------------------------------------+ +| | Configuration reload | +| | | +| HUP | Start the new worker processes with a new configuration | +| | | +| | Gracefully shutdown the old worker processes | ++-----------+---------------------------------------------------------+ +| USR1 | Reopen the log files | ++-----------+---------------------------------------------------------+ +| USR2 | Upgrade Executable on the fly | ++-----------+---------------------------------------------------------+ +| WINCH | Gracefully shutdown the worker processes | ++-----------+---------------------------------------------------------+ + +There's no need to control the worker processes yourself. +However, they support some signals, too: + ++-----------+----------------------+ +| TERM, INT | Quick shutdown | ++-----------+----------------------+ +| QUIT | Graceful shutdown | ++-----------+----------------------+ +| USR1 | Reopen the log files | ++-----------+----------------------+ + + +Loading a New Configuration Using Signals +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Nginx supports a few signals that you can use to control it's operation while it's running. + +The most common of these is 15, which just stops the running process: + +.. code-block:: bash + + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 2213 0.0 0.0 6784 2036 ? Ss 03:01 0:00 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf + + +The more interesting option however, is being able to change the nginx configuration on the fly (notice that we test the configuration prior to reloading it): + +.. code-block:: bash + + 2006/09/16 13:07:10 [info] 15686#0: the configuration file /etc/nginx/nginx.conf syntax is ok + 2006/09/16 13:07:10 [info] 15686#0: the configuration file /etc/nginx/nginx.conf was tested successfully + USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND + root 2213 0.0 0.0 6784 2036 ? Ss 03:01 0:00 nginx: master process /usr/sbin/nginx -c /etc/nginx/nginx.conf + + +What happens is that when nginx receives the ``HUP`` signal, it tries to parse the configuration file (the specified one, if present, otherwise the default), and if successful, tries to apply a new configuration (i.e. re-open the log files and listen sockets). +If successful, nginx runs new worker processes and signals graceful shutdown to old workers. +Notified workers close listen sockets but continue to serve current clients. +After serving all clients old workers shutdown. +If nginx couldn't successfully apply the new configuration, it continues to work with an old configuration. + +RequestForReviewCategory -- (Request For Review: Just What Happens With The Worker Processes at a HUP? -Olle) + + +Upgrading To a New Binary On The Fly +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you need to replace nginx binary with a new one (when upgrading to a new version or adding/removing server modules), you can do it without any service downtime - no incoming requests will be lost. + +First, replace old binary with a new one, then send USR2 signal to the master process. It renames its ``.pid`` file to ``.oldbin`` (e.g. ``/usr/local/nginx/logs/nginx.pid.oldbin``), then executes a new binary, which in turn starts a new master process and the new worker processes: + +.. code-block:: bash + + : PID PPID USER %CPU VSZ WCHAN COMMAND + 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx + 33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) + 33135 33126 nobody 0.0 1380 kqread nginx: worker process (nginx) + 33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) + 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx + 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + + +At this point, two instances of nginx are running, handling the incoming requests together. +To phase the old instance out, you have to send ``WINCH`` signal to the old master process, and its worker processes will start to gracefully shut down: + +.. code-block:: bash + + : PID PPID USER %CPU VSZ WCHAN COMMAND + 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx + 33135 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (nginx) + 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx + 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + + +After some time, old worker processes all quit and only new worker processes are handling the incoming requests: + +.. code-block:: bash + + : PID PPID USER %CPU VSZ WCHAN COMMAND + 33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx + 36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx + 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + + +At this point you can still revert to the old server because it hasn't closed its listen sockets yet, by following these steps: + +* Send ``HUP`` signal to the old master process - it will start the worker processes without reloading a configuration file +* Send ``QUIT`` signal to the new master process to gracefully shut down its worker processes +* Send ``TERM`` signal to the new master process to force it quit +* If for some reason new worker processes do not quit, send ``KILL`` signal to them + +After new master process quits, the old master process removes ``.oldbin`` suffix from its ``.pid`` file, and everything is exactly as before the upgrade attempt. + +If an update is successful and you want to keep the new server, send QUIT signal to the old master process to leave only new server running: + +.. code-block:: bash + + : PID PPID USER %CPU VSZ WCHAN COMMAND + : 36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/nginx + : 36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + : 36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + : 36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) + + +References +^^^^^^^^^^ +* `Command Line Options `_ +* `Signals `_ diff --git a/source/temp/debugging.rst b/source/temp/debugging.rst new file mode 100644 index 00000000..90c54430 --- /dev/null +++ b/source/temp/debugging.rst @@ -0,0 +1,91 @@ + +Debugging +========= + +Introduction +------------ +Nginx has wide range of debugging features, including detailed debug log. + +.. note:: Most debugging nits are only activated when nginx compiled with *--with-debug* configure argument. + + + +Debugging log +------------- +See `a debugging log `_ in documentation for details. + +To activate debugging log you have to compile nginx with *--with-debug* configure option and set debug level in `error_log <|HttpCoreModule|#error_log>`_ directive. + +It's possible to debug only connections from specified addresses via `debug_connection <|EventModule|#debug_connection>`_ directive. + +.. note:: In hard cases (e.g. debugging event method related problems) it's good idea to obtain full debugging log by setting debug level in global *error_log*. + + + +Core dump +--------- +To obtain core dump you usually have to tune your OS. Though nginx simplifies some typical cases and usually adding + +.. code-block:: nginx + + worker_rlimit_core 500M; + working_directory /path/to/cores/; + +to nginx.conf is enough. Then run gdb to obtain backtrace as usual, e.g. + +.. code-block:: bash + + gdb /path/to/nginx /path/to/cores/nginx.core + backtrace full + +If your gdb backtrace warns that No symbol table info available. then you will need to recompile Nginx with the appropriate compiler flags for debugging symbols. + +The exact flags required depend on the compiler used. If you use GCC, the flag ``-g`` enables the inclusion of debugging symbols. +Additionally disabling compiler optimization using ``-O0`` will make the debugger output easier to understand. + +.. code-block:: bash + + CFLAGS="-g -O0" ./configure .... + + + +Socket leaks +------------ +Sometimes socket leaks happen. +This usually results in ``[alert] 15248#0: open socket #123 left in connection 456`` messages in error log on nginx reload/restart/shutdown. +To debug add + +.. code-block:: bash + + debug_points abort; + +to ``nginx.conf`` and configure core dumps (see above). +This will result in ``abort()`` call once nginx detects leak and core dump. + +Something like this in gdb should be usefull (assuming 456 is connection number from error message from the process which dumped core): + +.. code-block:: bash + + set $c = &ngx_cycle->connections[456] + p $c->log->connection + p *$c + set $r = (ngx_http_request_t *) $c->data + p *$r + +In particular, ``p $c->log->connection`` will print connection number as used in logs. +It will be possible to grep debug log for relevant lines, e.g. + +.. code-block:: bash + + fgrep ' *12345678 ' /path/to/error_log; + + + +Asking for help +--------------- +When asking for help with debugging please provide: + +* ``nginx -V`` output +* full config +* debug log +* backtrace (if nginx exits on signal) diff --git a/source/temp/faq.rst b/source/temp/faq.rst new file mode 100644 index 00000000..cb643cb6 --- /dev/null +++ b/source/temp/faq.rst @@ -0,0 +1,260 @@ +Frequently Asked Questions +========================== + +Please review this entire FAQ before querying IRC or sending questions to the mailing list. + +HI I have a question about the nginx webserver whenever I start nginx by ``sudo ./nginx start`` and then type the ``ps -ef | grep nginx`` command I get the following output. (when I am in my ``/etc/init.d`` directory) + +.. code-block:: bash + + 1000 10760 10617 0 13:40 pts/0 00:00:00 grep --color=auto nginx + + + +General Questions +----------------- + +How do you pronounce "Nginx"? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The correct pronunciation sounds like: "engine-ex". (Next question: "What does that mean?" - We don't know, exactly.) + + +.. _faq.is_it_safe: + +Is it safe to use the development branch in production? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In general, all releases (development or otherwise) are quite stable. +This site runs the latest development version at all times. +Many nginx users tend to represent an "early adopter" crowd, so a large segment is using the bleeding edge version at any given point. +The major and most important point about development version is that it can occasionally break APIs for 3rd party modules (APIs are sometimes changed in the development branch). +Other than that, it gets all non-emergency bugfixes first. + +That said, if stability is crucial it is best to briefly hold off on deployment after a development release; critical bugs tend to show up within the first couple days (which often results in another release immediately afterwards). +If no new release shows up in two or three days, then it's likely no one has found any critical bugs. +In the event that you discover a bug, capture a debug log and submit a descriptive bug report! + + +How do I generate an .htpasswd file without having Apache tools installed? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* In Linux (and other Posix): given users John, Mary, Jane and Jim and passwords V3Ry, SEcRe7, V3RySEcRe7 and SEcRe7PwD, in order to generate a password file named .htpasswd, you would issue: + + .. code-block:: bash + + printf "John:$(openssl passwd -crypt V3Ry)\n" >> .htpasswd # this example uses crypt encryption + + .. code-block:: bash + + printf "Mary:$(openssl passwd -apr1 SEcRe7)\n" >> .htpasswd # this example uses apr1 (Apache MD5) encryption + + .. code-block:: bash + + printf "Jane:$(openssl passwd -1 V3RySEcRe7)\n" >> .htpasswd # this example uses MD5 encryption + + .. code-block:: bash + + (PASSWORD="SEcRe7PwD";SALT="$(openssl rand -base64 3)";SHA1=$(printf "$PASSWORD$SALT" | openssl dgst -binary -sha1 | sed 's#$#'"$SALT"'#' | base64);printf "Jim:{SSHA}$SHA1\n" >> .htpasswd) # this example uses SSHA encryption + +* Or, you may use the following `crypt.pl `_ Perl script. Simply save it as e.g. ``crypt.pl`` and ``chmod 700 crypt.pl`` in order to be able to execute it. + + .. code-block:: perl + + #!/usr/bin/perl + use strict; + + chomp(my $filename=$ARGV[0]); + chomp(my $username=$ARGV[1]); + chomp(my $password=$ARGV[2]); + + if (!$filename || !$username || !$password) { + print "USAGE: ./crypt.pl filename username password\n\n"; + } else { + open my $fh, ">>", $filename or die $!; + print $fh $username . ":" . crypt($password, $username) . "\n"; + close $fh or die $!; + } + +* Or, you may use the `htpasswd.py `_ python script. + + + +Why isn't my $foo (e.g. rewrite, proxy, location, unix:/$PATH, etc.) configuration working for me? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Start by investigating possible problem causes. Review :doc:`debugging` and carefully look **LINE BY LINE** through the error log. + +If you can't determine the problem cause through testing, experimentation, searches on the 'net, etc., then **gather all relevant details** and clearly explain your problem on IRC or in a note to the mailing list. +(If you are new to interacting with FOSS support communities, please read: `How To Ask Questions The Smart Way `_.) + + +Are there other, similar web servers? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* `Cherokee `_ +* `Lighttpd (Lighty) `_ +* `thttpd `_ + +What most people mean by "similar" in this context is: "lightweight" or "not Apache". +You can find many comparisons using Google, but most web servers fall into two categories: process-based (forking or threaded) and asynchronous. +Nginx and Lighttpd are probably the two best-known asynchronous servers and Apache is undoubtedly the best known process-based server. +Cherokee is a lesser-known process-based server (but with very high performance). + +The main advantage of the asynchronous approach is *scalability*. +In a process-based server, each simultaneous connection requires a thread which incurs significant overhead. +An asynchronous server, on the other hand, is event-driven and handles requests in a single (or at least, very few) threads. + +While a process-based server can often perform on par with an asynchronous server under light loads, under heavier loads they usually consume far too much RAM, which significantly degrades performance. +Also, they degrade much faster on less powerful hardware or in a resource-restricted environment such as a VPS. + +Pulling numbers from thin air for illustrative purposes: serving 10,000 simultaneous connections would probably only cause Nginx to use a few megabytes of RAM, while Apache would likely consume hundreds of megabytes (if it could do it at all). + + +Is support for chroot planned? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Unknown at this time. Unless/until that changes, you can achieve a similar - or better - effect by using OS-level features (e.g. ``BSD Jails``, ``OpenVZ`` with ``proxyarp`` on Linux, etc.). + + +What about support for something like mod_suexec? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +mod_suexec is a solution to a problem that Nginx does not have. +When running servers such as Apache, each instance consumes a significant amount of RAM, so it becomes important to only have a monolithic instance that handles all one's needs. +With Nginx, the memory and CPU utilization is so low that running dozens of instances of it is not an issue. + +A comparable Nginx setup to Apache + ``mod_suexec`` is to run a separate instance of Nginx as the CGI script user (i.e. *the user that would have been specified as suexec user under Apache*), and then proxy to that from the main Nginx instance. + +Alternatively, PHP could simply be executed through FastCGI, which itself would be running under a CGI script user account. + +.. note:: ``mod_php`` (the module suexec is normally utilized to defend against) does not exist with Nginx. + + + +HTTP +---- + +What's this @ thing mean? +^^^^^^^^^^^^^^^^^^^^^^^^^ +@location is a named location. Named locations preserve $uri as it was before entering such location. +They were introduced in 0.6.6 and can be reached only via `error_page <|HttpCoreModule|#error_page>`_, `post_action <|HttpCoreModule|#post_action>`_ (since 0.6.26) and `try_files <|HttpCoreModule|#try_files>`_ (since 0.7.27, backported to 0.6.36). + + + +HTTP Proxying +------------- + +For which general use cases is Nginx more appropriate than Squid? (And vice versa...) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Nginx is generally deployed as a reverse proxy, not as a caching proxy (like Squid). +The key advantage with Nginx is its nominal RAM and CPU usage under heavy load. +Squid is best applied to cache dynamic content for applications that cannot do it themselves. + +The |HttpProxyModule| offers configurations for caching upstream servers. + + +Can I disable the buffering for upload progress? / How can I display upload progress on the client side? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +These are both very frequently asked questions. + +.. + Temporarily omitted + Currently the only solution is the third-party module :doc:`../modules/upload_progress`. + +(This functionality is planned for a future release of Nginx.) + + + +Mail Proxying +------------- + +Could someone explain how to configure and test the IMAP module (with a complete .conf example)? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. + Temporarily omitted + Start with the configuration from the :doc:`imapproxyexample`. + +For detailed information about different configuration parameters, see the |MailCoreModule| page. + +Related resources: + +.. + Temporarily omitted + * :doc:`imapauthenticatewithapachephpscript` + * :doc:`imapauthenticatewithembeddedperlscript` + + +How can Nginx be deployed as an SMTP proxy, with a Postfix backend? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +First, declare the mail part as follows: + +.. code-block:: nginx + + mail { + server_name mail.somedomain.com; + + auth_http localhost:8008/auth-smtppass.php; + + server { + listen 212.104.99.24:25; + protocol smtp; + timeout 5s; + proxy on; + xclient off; + smtp_auth none; + } + } + + +The example is for unauthenticated e-mail as you can see, but if you need authentication just check out the |MailCoreModule| information on how to achieve it. +Postfix by default doesn't support XCLIENT, so it got turned off in the example as well. + +Next, you need to configure the authentication backend. If you just need to have some sort of pass-through mode towards a single address, you can do so with the following code: + +.. code-block:: nginx + + http { + log_format main + '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $bytes_sent ' + '"$http_referer" "$http_user_agent" ' + '"$gzip_ratio"'; + + server { + listen 127.0.0.1:8008; + server_name localhost; + access_log /var/log/nginx/localhost.access_log main; + error_log /var/log/nginx/localhost.error_log info; + + root /var/www/localhost/htdocs; + + location ~ .php$ { + add_header Auth-Server 127.0.0.1; + add_header Auth-Port 25; + return 200; + } + } + } + + +Basically, it accepts connections and for a request towards a .php file, it will return with code 200 and with the address of the (in this case) Postfix backend (on 127.0.0.1:25 here). + + + +Load Balancing +-------------- + +What algorithm does Nginx use to load balance? Can it balance based on connection load? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Currently, Nginx has round-robin, least connections and ip-hash algorithms (all come with weights). + +There are also a number of third-party modules for load balancing. + +.. note:: Many users have requested that Nginx implement a feature in the load balancer to limit the number of requests per backend (usually to one). While support for this is planned, it's worth mentioning that demand for this feature is rooted in misbehaviour on the part of the application being proxied ''to'' (Ruby on Rails seems to be one example). This is not an Nginx issue. In an ideal world, this particular problem fix request would be directed toward the backend application and its ability handle simultaneous requests. + + + +Miscellaneous +------------- + +Why do I see "Welcome to nginx!" when I'm trying to access Facebook, Yahoo!, Google or some other well-known website? Is nginx a virus? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Nginx is not a virus. Please check a detailed description here:: + + `Welcome to nginx! `_ diff --git a/source/temp/gettingstarted.rst b/source/temp/gettingstarted.rst new file mode 100644 index 00000000..54333468 --- /dev/null +++ b/source/temp/gettingstarted.rst @@ -0,0 +1,82 @@ +Getting Started +=============== + +Requirements +------------ + +* gzip module requires `zlib `_ library +* rewrite module requires `pcre `_ library +* ssl support requires openssl library + + + +Download +-------- +Go to the :doc:`install` Page of this wiki to download Nginx. +Alternatively, here is a link to the `English download page `_ and the original `Russian download page `_. + + + +Installation +------------ +After extracting the source, run these commands from a terminal: + +.. code-block:: bash + + ./configure + make + sudo make install + +By default, Nginx will be installed in ``/usr/local/nginx``. You may change this and other options with the :doc:`installoptions`. + + + +Platform-specific Notes and Builds +---------------------------------- + +.. + Temporarily omitted + #. :doc:`platformubuntu` + #. :doc:`platformfedora` + #. :doc:`platformgentoo` + +#. `x86/64 build for Solaris `_ +#. `Nginx for Windows (32-bit); development, stable, and legacy binaries available `_ + +.. + Dead links + #. `Nginx building script for Slackware `_ + #. `How to Compile nginx on MacOSX `_ + + +Running Nginx +------------- +Start the server by running ``/usr/local/nginx/sbin/nginx`` as root. +After editing the configuration file at ``/usr/local/nginx/conf/nginx.conf`` to your liking, you can reload the configuration with: + +.. code-block:: bash + + kill -HUP `cat /usr/local/nginx/logs/nginx.pid` + +The location of nginx.pid might be different on your machine. +For Ubuntu, it is located at ``/var/run/nginx.pid`` + +.. seealso:: + + * :doc:`commandline` for more command-line options and process signals + * :doc:`faq` for solutions to common problems + +.. + Temporarily omitted + * :doc:`modules` for learning more about nginx modules + * :doc:`configuration` for a configuration reference + * :doc:`community` if you still can't find the answers to your questions + + +Advanced topics +--------------- +* :doc:`debugging` + +.. + Temporarily omitted + * :doc:`optimizations` diff --git a/source/temp/index.rst b/source/temp/index.rst new file mode 100755 index 00000000..35357756 --- /dev/null +++ b/source/temp/index.rst @@ -0,0 +1,12 @@ +.. toctree:: + :hidden: + + commandline + debugging + faq + gettingstarted + install + installoptions + pronunciation + resources + \ No newline at end of file diff --git a/source/temp/install.rst b/source/temp/install.rst new file mode 100644 index 00000000..43e7d368 --- /dev/null +++ b/source/temp/install.rst @@ -0,0 +1,208 @@ +Install +======= + +After Installing +---------------- +.. + Temporarily omitted + The :doc:`configuration` page will give you some help getting things going after you get Nginx installed and the :doc:`pitfalls` page will help keep you from making mistakes that so many users before you did. + +These two pages give you the chance to learn from others mistakes and hard work. + + + +Binary Releases +--------------- + +Prebuilt Packages for Linux and BSD +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Most Linux distributions and BSD variants have Nginx in the usual package repositories and they can be installed via whatever method is normally used to install software (``apt-get`` on Debian, ``emerge`` on Gentoo, ``ports`` on FreeBSD, etc). + +Be aware that these packages are often somewhat out-of-date. +If you want the latest features and bugfixes, it's recommended to build from source or use packages directly from nginx.org. + + + +Official Red Hat/CentOS packages +-------------------------------- +To add nginx yum repository, create a file named ``/etc/yum.repos.d/nginx.repo`` and paste one of the configurations below: + +CentOS:: + + [nginx] + name=nginx repo + baseurl=http://nginx.org/packages/centos/$releasever/$basearch/ + gpgcheck=0 + enabled=1 + + +RHEL:: + + [nginx] + name=nginx repo + baseurl=http://nginx.org/packages/rhel/$releasever/$basearch/ + gpgcheck=0 + enabled=1 + + +Due to differences between how CentOS, RHEL, and Scientific Linux populate the ``$releasever`` variable, it is necessary to manually replace ``$releasever`` with either ``5`` (for 5.x) or ``6`` (for 6.x), depending upon your OS version. + + + +Official Debian/Ubuntu packages +------------------------------- +Append the appropriate stanza to ``/etc/apt/sources.list``. The Pgp page explains the signing of the nginx.org released packaging. + +Ubuntu 10.04: + +.. code-block:: bash + + deb http://nginx.org/packages/ubuntu/ lucid nginx + deb-src http://nginx.org/packages/ubuntu/ lucid nginx + + + +Debian 6: + +.. code-block:: bash + + deb http://nginx.org/packages/debian/ squeeze nginx + deb-src http://nginx.org/packages/debian/ squeeze nginx + + +Ubuntu PPA +^^^^^^^^^^ +This PPA is maintained by volunteers and is not distributed by nginx.org. It has some additional compiled-in modules and may be more fitting for your environment. + +You can get the latest stable version of Nginx from the `Nginx PPA `_ on Launchpad: +You will need to have root privileges to perform the following commands. + +For Ubuntu 10.04 and newer: + +.. code-block:: bash + + sudo -s + nginx=stable # use nginx=development for latest development version + add-apt-repository ppa:nginx/$nginx + apt-get update + apt-get install nginx + +If you get an error about add-apt-repository not existing, you will want to install ``python-software-properties``. +For other Debian/Ubuntu based distributions, you can try the lucid variant of the PPA which is the most likely to work on older package sets: + +.. code-block:: bash + + sudo -s + nginx=stable # use nginx=development for latest development version + echo "deb http://ppa.launchpad.net/nginx/$nginx/ubuntu lucid main" > /etc/apt/sources.list.d/nginx-$nginx-lucid.list + apt-key adv --keyserver keyserver.ubuntu.com --recv-keys C300EE8C + apt-get update + apt-get install nginx + + + +.. _install_win32_binaries: + +Official Win32 Binaries +----------------------- +As of nginx 0.8.50, nginx is now available as an `official Windows binary `_. + +Installation: + +.. code-block:: bash + + cd c:\ + unzip nginx-1.2.3.zip + ren nginx-1.2.3 nginx + cd nginx + start nginx + +Control: + +.. code-block:: bash + + nginx -s [ stop | quit | reopen | reload ] + + +For problems look in c:\nginx\logs\error.log or in EventLog. + +In addition, Kevin Worthington maintains earlier `Windows `_ builds of the development branch. + + + +Source Releases +--------------- +There are currently two versions of Nginx available: ``stable (1.8.x)``, ``mainline (1.9.x)``. +The mainline branch gets new features and bugfixes sooner but might introduce new bugs as well. +Critical bugfixes are backported to the stable branch. + +In general, the stable release is recommended, but the mainline release is typically quite stable as well. +See the `FAQ `. + +
+ +
    + +
  • +
    + + +Stable +^^^^^^ +`nginx 1.8.0 `_
    +21 Apr 2015
    +`changelog `_ +
    +
    • + +
  • +
    + + +Mainline +^^^^^^^^ +`nginx 1.9.2 `_
    +16 Jun 2015
    +`changelog `_ +
    +
    • + +
+ +
+ +Source code repository is at `hg.nginx.org/nginx `_. + +Older versions can be found `here `_. + + +Building Nginx From Source +^^^^^^^^^^^^^^^^^^^^^^^^^^ +After extracting the source, run these commands from a terminal: + +.. code-block:: bash + + ./configure + make + sudo make install + +By default, Nginx will be installed in ``/usr/local/nginx``. You may change this and other options with the :doc:`installoptions`. + +You might also want to peruse the :doc:`3rd party modules <../modules/index>`, since these must be built at compile-time. + + +Other Systems +^^^^^^^^^^^^^ + +.. + Temporarily omitted + * :doc:`installing_on_solaris_10_u5` + * :doc:`installing_on_solaris_11` + +.. warning:: These pages are not thoroughly, if at all, reviewed for accuracy as they are on this page. + + + +References +---------- +`Original Documentation `_ diff --git a/source/temp/installoptions.rst b/source/temp/installoptions.rst new file mode 100644 index 00000000..ecdd3847 --- /dev/null +++ b/source/temp/installoptions.rst @@ -0,0 +1,99 @@ +Installation and Compile-Time Options +===================================== + +The build is configured using the ``./configure`` command. It defines various aspects of the system, including the methods nginx is allowed to use for connection processing. +At the end it creates a Makefile. + +The configure command supports the following parameters: + +Files and Permissions +^^^^^^^^^^^^^^^^^^^^^ +**--prefix=*path*** + defines a directory that will keep server files. This same directory will also be used for all relative paths set by configure (except for paths to libraries sources) and in the nginx.conf configuration file. It is set to the ``/usr/local/nginx`` directory by default. +**--sbin-path=*path*** + sets the name of an nginx executable file. This name is used only during installation. By default the file is named ``prefix/sbin/nginx``. +**--conf-path=*path*** + sets the name of an ``nginx.conf`` configuration file. If needs be, nginx can always be started with a different configuration file, by specifying it in the command-line parameter ``-c file``. By default the file is named ``prefix/conf/nginx.conf``. +**--pid-path=*path*** + sets the name of an nginx.pid file that will store the process ID of the main process. After installation, the file name can always be changed in the ``nginx.conf`` configuration file using the pid directive. By default the file is named ``prefix/logs/nginx.pid``. +**--error-log-path=*path*** + sets the name of the primary error, warnings, and diagnostic file. After installation, the file name can always be changed in the ``nginx.conf`` configuration file using the `error log <|HttpCoreModule|#error_log>`_ directive. By default the file is named ``prefix/logs/error.log``. The special "stderr" value tells nginx to log pre-configuration messages to the standard error. +**--http-log-path=*path*** + sets the name of the primary request log file of the HTTP server. After installation, the file name can always be changed in the ``nginx.conf`` configuration file using the `access log <|HttpCoreModule|#access_log>`_ directive. By default the file is named ``prefix/logs/access.log``. +**--user=*name*** + sets the name of an unprivileged user whose credentials will be used by worker processes. After installation, the name can always be changed in the ``nginx.conf`` configuration file using the user directive. The default user name is nobody. +**--group=*name*** + sets the name of a group whose credentials will be used by worker processes. After installation, the name can always be changed in the ``nginx.conf`` configuration file using the user directive. By default, a group name is set to the name of an unprivileged user. + +Event Loop +^^^^^^^^^^ +**--with-select_module, --without-select_module** + enables or disables building a module that allows the server to work with the ``select()`` method. This module is built automatically if the platform does not appear to support more appropriate methods such as ``kqueue``, ``epoll``, ``rtsig``, or ``/dev/poll``. +**--with-poll_module, --without-poll_module** + enables or disables building a module that allows the server to work with the ``poll()`` method. This module is built automatically if the platform does not appear to support more appropriate methods such as ``kqueue``, ``epoll``, ``rtsig``, or ``/dev/poll``. + +Optional Modules +^^^^^^^^^^^^^^^^ +**--without-http_gzip_module** + disables building a module that compresses responses of an HTTP server. The zlib library is required to build and run this module. +**--without-http_rewrite_module** + disables building a module that allows an HTTP server to redirect requests and change URI of requests. The PCRE library is required to build and run this module. The module is experimental so its directives may change in the future. +**--without-http_proxy_module** + disables building an HTTP server proxying module. +**--with-http_ssl_module** + enables building a module that adds the HTTPS protocol support to an HTTP server. This module is not built by default. The OpenSSL library is required to build and run this module. +**--with-pcre=*path*** + sets the path to the sources of the PCRE library. The library distribution (version 4.4 — 8.21) needs to be downloaded from the PCRE site and extracted. The rest is done by nginx's ``./configure`` and ``make``. The library is required for regular expressions support in the location directive and for the |HttpRewriteModule|. See `notes `_ below for using system PCRE on FreeBSD systems. +**--with-pcre-jit** + builds the PCRE library with "just-in-time compilation" support. +**--with-zlib=*path*** + sets the path to the sources of the zlib library. The library distribution (version 1.1.3 — 1.2.5) needs to be downloaded from the zlib site and extracted. The rest is done by nginx's ``./configure`` and ``make``. The library is required for the |HttpGzipModule|. + +Compilation Controls +^^^^^^^^^^^^^^^^^^^^ +**--with-cc-opt=*parameters*** + sets additional parameters that will be added to the *CFLAGS* variable. +**--with-ld-opt=*parameters*** + sets additional parameters that will be used during linking. + + + +Example +------- +Example of parameters usage (all of this needs to be typed in one line): + +.. code-block:: bash + + ./configure + --sbin-path=/usr/local/nginx/nginx + --conf-path=/usr/local/nginx/nginx.conf + --pid-path=/usr/local/nginx/nginx.pid + --with-http_ssl_module + --with-pcre=../pcre-4.4 + --with-zlib=../zlib-1.1.3 + + + +.. _installoptions_notes: + +Notes +----- +When using the system PCRE library under FreeBSD, the following options should be specified: + +.. code-block:: bash + + --with-ld-opt="-L /usr/local/lib" \ + --with-cc-opt="-I /usr/local/include" + + +If the number of files supported by ``select()`` needs to be increased it can also be specified like this: + +.. code-block:: bash + + --with-cc-opt="-D FD_SETSIZE=2048" + + + +References +---------- +:doc:`install` diff --git a/source/temp/pronunciation.rst b/source/temp/pronunciation.rst new file mode 100644 index 00000000..e2a82172 --- /dev/null +++ b/source/temp/pronunciation.rst @@ -0,0 +1,14 @@ +Pronunciation +============= +There seems to be some confusion surrounding the pronunciation of Nginx. + +`Pronunciation Key `_ + +Correct +------- +* **en**-juhn-**eks** +* Engine-X + +Incorrect +--------- +* **en**-jingks \ No newline at end of file diff --git a/source/temp/resources.rst b/source/temp/resources.rst new file mode 100644 index 00000000..7258969b --- /dev/null +++ b/source/temp/resources.rst @@ -0,0 +1,82 @@ +Resources +========= + +Developer Resources +------------------- +* `Contributing Changes (official guide) `_ +* :doc:`gettingstarted` +* :doc:`faq` + +.. + Temporarily omitted + * :doc:`codingstyle` + * :doc:`sourcetricks` + + + +English Guides +-------------- +* `Evan Miller's Guide to Nginx Module Development `_ +* `Evan Miller's Advanced Topics In Nginx Module Development `_ +* Slides of agentzh's `Introduction to nginx.conf scripting `_ talk in Beijing (use arrow keys to navigate) +* Slides of agentzh's `Recent developments in nginx.conf scripting `_ talk in Beijing (use arrow keys to navigate) +* Slides of Joshua Zhu's `Nginx Internals `_ talk in Guangzhou +* `Nginx source code cross-reference `_ +* `nginx-devel mailing list archive `_ +* `Chapter about nginx in The Architecture of Open Source Applications Volume II `_ +* `nginx how-to at calomel.org `_ + +.. + Temporarily omitted + * Notes about :doc:`headersmanagement` + + +Russian Guides +-------------- +* `Guide `_ +* `Blog `_ + +.. + Dead links now + * `Translation of Emiller's Guide `_ + +.. note:: Translate with Google Translate or Babelfish. + + + +Chinese Guides +-------------- +* `Nginx Variable Tutorials `_ by `agentzh `_ +* `Nginx Code Review by chaoslawful and rainx `_ +* `Chinese Version of Emiller's Guide `_ + +.. + Dead links now + * `Chinese version of Notes about HTTP headers management `_ + * `CENTOS+NGINX+PHP5.4+MYSQL `_ + * `MAC INSTALL NGINX+PHP+MYSQL `_ + + + +Other Resources +--------------- +* `Nginx mailing list archive `_ +* `Geolocation database for Nginx in CIDR format (countries by IP) `_ +* `Experiment to automatically convert Apache rewrites to Nginx rewrites `_ +* `Nginx and Memcached, a 400% boost! `_ +* `Parsing PHP sessions in Nginx `_ +* `PyMunin - Multigraph Munin Plugins in Python `_ - PyMunin includes a Multigraph Munin Plugin for monitoring Nginx using http_stub_status module. Graphs active connections, connection rate, request rate and average requests per connection. + +.. + Temporarily omitted + * :doc:`whyuseit` + + Dead links now + * `nWeb Script - Easy installer script for Debian / Ubuntu `_ (Installs nginx, with PHP support and MySQL) + * `Intellij IDEA plugin for integration with nginx `_ + * `Unofficial Debian repository with the latest Nginx release `_ + * `Nginx vs Apache `_ + * `ISPConfig support for Nginx `_ + * `Latest bug reports about nginx found by bugspy.net `_ + * `Using nginx as reverse-proxy `_ +