gunicorn/doc/htdocs/configure.html
2010-05-30 14:36:06 -04:00

470 lines
20 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Green Unicorn - Configure</title>
<link rel="alternate" type="application/rss+xml" href="/feed.xml" />
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" />
</head>
<body>
<div class="container">
<div id="header">
<a href="./">
<img src="images/logo.png" alt="Gunicorn - Green Unicorn" />
</a>
</div>
<div id="menu">
<ul id="actions">
<li><a href="install.html">Install</a></li>
<li><a href="run.html">Run</a></li>
<li><a href="configure.html">Configure</a></li>
<li><a href="deploy.html">Deploy</a></li>
<li><a href="design.html">Design</a><li>
<li><a href="faq.html">FAQ</a></li>
<li><a href="news.html">News</a></li>
<li><a href="http://github.com/benoitc/gunicorn/">Code</a></li>
</ul>
</div>
<div id="content">
<div class="document">
<div class="contents sidebar topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
<li><a class="reference internal" href="#framework-settings" id="id2">Framework Settings</a><ul>
<li><a class="reference internal" href="#paster-applications" id="id3">Paster Applications</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-file" id="id4">Configuration File</a></li>
<li><a class="reference internal" href="#command-line" id="id5">Command Line</a></li>
<li><a class="reference internal" href="#settings" id="id6">Settings</a><ul>
<li><a class="reference internal" href="#config-file" id="id7">Config File</a><ul>
<li><a class="reference internal" href="#config" id="id8">config</a></li>
</ul>
</li>
<li><a class="reference internal" href="#server-socket" id="id9">Server Socket</a><ul>
<li><a class="reference internal" href="#bind" id="id10">bind</a></li>
<li><a class="reference internal" href="#backlog" id="id11">backlog</a></li>
</ul>
</li>
<li><a class="reference internal" href="#worker-processes" id="id12">Worker Processes</a><ul>
<li><a class="reference internal" href="#workers" id="id13">workers</a></li>
<li><a class="reference internal" href="#worker-class" id="id14">worker_class</a></li>
<li><a class="reference internal" href="#worker-connections" id="id15">worker_connections</a></li>
<li><a class="reference internal" href="#timeout" id="id16">timeout</a></li>
<li><a class="reference internal" href="#keepalive" id="id17">keepalive</a></li>
</ul>
</li>
<li><a class="reference internal" href="#debugging" id="id18">Debugging</a><ul>
<li><a class="reference internal" href="#debug" id="id19">debug</a></li>
<li><a class="reference internal" href="#spew" id="id20">spew</a></li>
</ul>
</li>
<li><a class="reference internal" href="#server-mechanics" id="id21">Server Mechanics</a><ul>
<li><a class="reference internal" href="#daemon" id="id22">daemon</a></li>
<li><a class="reference internal" href="#pidfile" id="id23">pidfile</a></li>
<li><a class="reference internal" href="#user" id="id24">user</a></li>
<li><a class="reference internal" href="#group" id="id25">group</a></li>
<li><a class="reference internal" href="#umask" id="id26">umask</a></li>
<li><a class="reference internal" href="#tmp-upload-dir" id="id27">tmp_upload_dir</a></li>
</ul>
</li>
<li><a class="reference internal" href="#logging" id="id28">Logging</a><ul>
<li><a class="reference internal" href="#logfile" id="id29">logfile</a></li>
<li><a class="reference internal" href="#loglevel" id="id30">loglevel</a></li>
</ul>
</li>
<li><a class="reference internal" href="#process-naming" id="id31">Process Naming</a><ul>
<li><a class="reference internal" href="#proc-name" id="id32">proc_name</a></li>
<li><a class="reference internal" href="#default-proc-name" id="id33">default_proc_name</a></li>
</ul>
</li>
<li><a class="reference internal" href="#server-hooks" id="id34">Server Hooks</a><ul>
<li><a class="reference internal" href="#pre-fork" id="id35">pre_fork</a></li>
<li><a class="reference internal" href="#post-fork" id="id36">post_fork</a></li>
<li><a class="reference internal" href="#pre-exec" id="id37">pre_exec</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#contents">Overview</a></h2>
<p>Gunicorn pulls configuration information from three distinct places.</p>
<p>The first place that Gunicorn will read configuration from is the framework
specific configuration file. Currently this only affects Paster applications.</p>
<p>The second source of configuration information is a configuration file that is
optionally specified on the command line. Anything specified in the Gunicorn
config file will override any framework specific settings.</p>
<p>Lastly, the command line arguments used to invoke Gunicorn are the final place
considered for configuration settings. If an option is specified on the command
line, this is the value that will be used.</p>
<dl class="docutils">
<dt>Once again, in order of least to most authoritative:</dt>
<dd><ol class="first last arabic simple">
<li>Framework Settings</li>
<li>Configuration File</li>
<li>Command Line</li>
</ol>
</dd>
</dl>
</div>
<div class="section" id="framework-settings">
<h2><a class="toc-backref" href="#contents">Framework Settings</a></h2>
<p>Currently, only Paster applications have access to framework specific
settings. If you have ideas for providing settings to WSGI applications or
pulling information from Django's settings.py feel free to open an <a class="reference external" href="http://github.com/benoitc/gunicorn/issues">issue</a> to
let us know.</p>
<div class="section" id="paster-applications">
<h3><a class="toc-backref" href="#contents">Paster Applications</a></h3>
<p>In your INI file, you can specify to use Gunicorn as the server like such:</p>
<pre class="literal-block">
[server:main]
use = egg:gunicorn#main
host = 192.168.0.1
port = 80
workers = 2
proc_name = brim
</pre>
<p>Any parameters that Gunicorn knows about will automatically be inserted into
the base configuration. Remember that these will be overridden by the config
file and/or the command line.</p>
</div>
</div>
<div class="section" id="configuration-file">
<h2><a class="toc-backref" href="#contents">Configuration File</a></h2>
<p>The configuration file should be a valid Python source file. It only needs to
be readable from the file system. More specifically, it does not need to be
importable. Any Python is valid. Just consider that this will be run every time
you start Gunicorn (including when you signal Gunicorn to reload).</p>
<p>To set a parameter, just assign to it. There's no special syntax. The values
you provide will be used for the configuration values.</p>
<p>For instance:</p>
<pre class="literal-block">
import os
def numCPUs():
if not hasattr(os, &quot;sysconf&quot;):
raise RuntimeError(&quot;No sysconf detected.&quot;)
return os.sysconf(&quot;SC_NPROCESSORS_ONLN&quot;)
bind = &quot;127.0.0.1:8000&quot;
workers = numCPUs() * 2 + 1
</pre>
</div>
<div class="section" id="command-line">
<h2><a class="toc-backref" href="#contents">Command Line</a></h2>
<p>If an option is specified on the command line, it overrides all other values
that may have been specified in the app specific settings, or in the optional
configuration file. Not all Gunicorn settings are available to be set from the
command line. To see the full list of command line settings you can do the
usual:</p>
<pre class="literal-block">
$ gunicorn -h
</pre>
<p>There is also a <tt class="docutils literal"><span class="pre">--version</span></tt> flag available to the command line scripts that
isn't mentioned in the list of settings.</p>
</div>
<div class="section" id="settings">
<h2><a class="toc-backref" href="#contents">Settings</a></h2>
<p>This is an exhaustive list of settings for Gunicorn. Some settings are only
able to be set from a configuration file. The setting name is what should be
used in the configuration file. The command line arguments are listed as well
for reference on setting at the command line.</p>
<div class="section" id="config-file">
<h3><a class="toc-backref" href="#contents">Config File</a></h3>
<div class="section" id="config">
<h4><a class="toc-backref" href="#contents">config</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-c</span> FILE, <span class="pre">--config</span> FILE</tt></li>
<li><tt class="docutils literal">None</tt></li>
</ul>
<p>The path to a Gunicorn config file.</p>
<p>Only has an effect when specified on the command line or as part of an
application specific configuration.</p>
</div>
</div>
<div class="section" id="server-socket">
<h3><a class="toc-backref" href="#contents">Server Socket</a></h3>
<div class="section" id="bind">
<h4><a class="toc-backref" href="#contents">bind</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-b</span> ADDRESS, <span class="pre">--bind</span> ADDRESS</tt></li>
<li><tt class="docutils literal">127.0.0.1:8000</tt></li>
</ul>
<p>The socket to bind.</p>
<p>A string of the form: 'HOST', 'HOST:PORT', 'unix:PATH'. An IP is a valid
HOST.</p>
</div>
<div class="section" id="backlog">
<h4><a class="toc-backref" href="#contents">backlog</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--backlog</span> INT</tt></li>
<li><tt class="docutils literal">2048</tt></li>
</ul>
<p>The maximum number of pending connections.</p>
<p>This refers to the number of clients that can be waiting to be served.
Exceeding this number results in the client getting an error when
attempting to connect. It should only affect servers under significant
load.</p>
<p>Must be a positive integer. Generally set in the 64-2048 range.</p>
</div>
</div>
<div class="section" id="worker-processes">
<h3><a class="toc-backref" href="#contents">Worker Processes</a></h3>
<div class="section" id="workers">
<h4><a class="toc-backref" href="#contents">workers</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-w</span> INT, <span class="pre">--workers</span> INT</tt></li>
<li><tt class="docutils literal">1</tt></li>
</ul>
<p>The number of worker process for handling requests.</p>
<p>A positive integer generally in the 2-4 x $(NUM_CORES) range. You'll
want to vary this a bit to find the best for your particular
application's work load.</p>
</div>
<div class="section" id="worker-class">
<h4><a class="toc-backref" href="#contents">worker_class</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-k</span> STRING, <span class="pre">--worker-class</span> STRING</tt></li>
<li><tt class="docutils literal">egg:gunicorn#sync</tt></li>
</ul>
<p>The type of workers to use.</p>
<p>The default async class should handle most 'normal' types of work loads.
You'll want to read <a class="reference external" href="http://gunicorn.org/design.hml">http://gunicorn.org/design.hml</a> for information on
when you might want to choose one of the other worker classes.</p>
<p>An string referring to a 'gunicorn.workers' entry point or a
MODULE:CLASS pair where CLASS is a subclass of
gunicorn.workers.base.Worker.</p>
<p>The default provided values are:</p>
<ul class="simple">
<li><tt class="docutils literal">egg:gunicorn#sync</tt></li>
<li><tt class="docutils literal">egg:gunicorn#eventlet</tt> - Requires eventlet &gt;= 0.9.7</li>
<li><tt class="docutils literal">egg:gunicorn#gevent</tt> - Requires gevent &gt;= 0.12.2 (?)</li>
<li><tt class="docutils literal">egg:gunicorn#tornado</tt> - Requires tornado &gt;= 0.2</li>
</ul>
</div>
<div class="section" id="worker-connections">
<h4><a class="toc-backref" href="#contents">worker_connections</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--worker-connections</span> INT</tt></li>
<li><tt class="docutils literal">1000</tt></li>
</ul>
<p>The maximum number of simultaneous clients.</p>
<p>This setting only affects the Eventlet and Gevent worker types.</p>
</div>
<div class="section" id="timeout">
<h4><a class="toc-backref" href="#contents">timeout</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-t</span> INT, <span class="pre">--timeout</span> INT</tt></li>
<li><tt class="docutils literal">30</tt></li>
</ul>
<p>Workers silent for more than this many seconds are killed and restarted.</p>
<p>Generally set to thirty seconds. Only set this noticeably higher if
you're sure of the repercussions for sync workers. For the non sync
workers it just means that the worker process is still communicating and
is not tied to the length of time required to handle a single request.</p>
</div>
<div class="section" id="keepalive">
<h4><a class="toc-backref" href="#contents">keepalive</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--keep-alive</span> INT</tt></li>
<li><tt class="docutils literal">2</tt></li>
</ul>
<p>The number of seconds to wait for requests on a Keep-Alive connection.</p>
<p>Generally set in the 1-5 seconds range.</p>
</div>
</div>
<div class="section" id="debugging">
<h3><a class="toc-backref" href="#contents">Debugging</a></h3>
<div class="section" id="debug">
<h4><a class="toc-backref" href="#contents">debug</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-d,</span> <span class="pre">--debug</span></tt></li>
<li><tt class="docutils literal">False</tt></li>
</ul>
<p>Turn on debugging in the server.</p>
<p>This limits the number of worker processes to 1 and changes some error
handling that's sent to clients.</p>
</div>
<div class="section" id="spew">
<h4><a class="toc-backref" href="#contents">spew</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--spew</span></tt></li>
<li><tt class="docutils literal">False</tt></li>
</ul>
<p>Install a trace function that spews every line executed by the server.</p>
<p>This is the nuclear option.</p>
</div>
</div>
<div class="section" id="server-mechanics">
<h3><a class="toc-backref" href="#contents">Server Mechanics</a></h3>
<div class="section" id="daemon">
<h4><a class="toc-backref" href="#contents">daemon</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-D,</span> <span class="pre">--daemon</span></tt></li>
<li><tt class="docutils literal">False</tt></li>
</ul>
<p>Daemonize the Gunicorn process.</p>
<p>Detaches the server from the controlling terminal and enters the
background.</p>
</div>
<div class="section" id="pidfile">
<h4><a class="toc-backref" href="#contents">pidfile</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-p</span> FILE, <span class="pre">--pid</span> FILE</tt></li>
<li><tt class="docutils literal">None</tt></li>
</ul>
<p>A filename to use for the PID file.</p>
<p>If not set, no PID file will be written.</p>
</div>
<div class="section" id="user">
<h4><a class="toc-backref" href="#contents">user</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-u</span> USER, <span class="pre">--user</span> USER</tt></li>
<li><tt class="docutils literal">None</tt></li>
</ul>
<p>Switch worker processes to run as this user.</p>
<p>A valid user id (as an integer) or the name of a user that can be
retrieved with a call to pwd.getpwnam(value) or None to not change
the worker process user.</p>
</div>
<div class="section" id="group">
<h4><a class="toc-backref" href="#contents">group</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-g</span> GROUP, <span class="pre">--group</span> GROUP</tt></li>
<li><tt class="docutils literal">None</tt></li>
</ul>
<p>Switch worker process to run as this group.</p>
<p>A valid group id (as an integer) or the name of a user that can be
retrieved with a call to pwd.getgrnam(value) or None to not change
the worker processes group.</p>
</div>
<div class="section" id="umask">
<h4><a class="toc-backref" href="#contents">umask</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-m</span> INT, <span class="pre">--umask</span> INT</tt></li>
<li><tt class="docutils literal">0</tt></li>
</ul>
<p>A bit mask for the file mode on files written by Gunicorn.</p>
<p>Note that this affects unix socket permissions.</p>
<p>A valid value for the os.umask(mode) call or a string compatible with
int(value, 0) (0 means Python guesses the base, so values like &quot;0&quot;,
&quot;0xFF&quot;, &quot;0022&quot; are valid for decimal, hex, and octal representations)</p>
</div>
<div class="section" id="tmp-upload-dir">
<h4><a class="toc-backref" href="#contents">tmp_upload_dir</a></h4>
<ul class="simple">
<li><tt class="docutils literal">None</tt></li>
</ul>
<p>Directory to store temporary request data as they are read.</p>
<p>This may disappear in the near future.</p>
<p>This path should be writable by the process permissions set for Gunicorn
workers. If not specified, Gunicorn will choose a system generated
temporary directory.</p>
</div>
</div>
<div class="section" id="logging">
<h3><a class="toc-backref" href="#contents">Logging</a></h3>
<div class="section" id="logfile">
<h4><a class="toc-backref" href="#contents">logfile</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--log-file</span> FILE</tt></li>
<li><tt class="docutils literal">-</tt></li>
</ul>
<p>The log file to write to.</p>
<p>&quot;-&quot; means log to stdout.</p>
</div>
<div class="section" id="loglevel">
<h4><a class="toc-backref" href="#contents">loglevel</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">--log-level</span> LEVEL</tt></li>
<li><tt class="docutils literal">info</tt></li>
</ul>
<p>The granularity of log output</p>
<p>Valid level names are:</p>
<ul class="simple">
<li>debug</li>
<li>info</li>
<li>warning</li>
<li>error</li>
<li>critical</li>
</ul>
</div>
</div>
<div class="section" id="process-naming">
<h3><a class="toc-backref" href="#contents">Process Naming</a></h3>
<div class="section" id="proc-name">
<h4><a class="toc-backref" href="#contents">proc_name</a></h4>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">-n</span> STRING, <span class="pre">--name</span> STRING</tt></li>
<li><tt class="docutils literal">gunicorn</tt></li>
</ul>
<p>A base to use with setproctitle for process naming.</p>
<p>This affects things like <tt class="docutils literal">ps</tt> and <tt class="docutils literal">top</tt>. If you're going to be
running more than one instance of Gunicorn you'll probably want to set a
name to tell them apart. This requires that you install the setproctitle
module.</p>
<p>It defaults to 'gunicorn'.</p>
</div>
<div class="section" id="default-proc-name">
<h4><a class="toc-backref" href="#contents">default_proc_name</a></h4>
<ul class="simple">
<li><tt class="docutils literal">gunicorn</tt></li>
</ul>
<p>Internal setting that is adjusted for each type of application.</p>
</div>
</div>
<div class="section" id="server-hooks">
<h3><a class="toc-backref" href="#contents">Server Hooks</a></h3>
<div class="section" id="pre-fork">
<h4><a class="toc-backref" href="#contents">pre_fork</a></h4>
<ul>
<li><pre class="first literal-block">
def def_pre_fork(server, worker):
pass
</pre>
</li>
</ul>
<p>Called just before a worker is forked.</p>
<p>The callable needs to accept two instance variables for the Arbiter and
new Worker.</p>
</div>
<div class="section" id="post-fork">
<h4><a class="toc-backref" href="#contents">post_fork</a></h4>
<ul>
<li><pre class="first literal-block">
def def_post_fork(server, worker):
server.log.info(&quot;Worker spawned (pid: %s)&quot; % worker.pid)
</pre>
</li>
</ul>
<p>Called just after a worker has been forked.</p>
<p>The callable needs to accept two instance variables for the Arbiter and
new Worker.</p>
</div>
<div class="section" id="pre-exec">
<h4><a class="toc-backref" href="#contents">pre_exec</a></h4>
<ul>
<li><pre class="first literal-block">
def def_pre_exec(server):
server.log.info(&quot;Forked child, reexecuting.&quot;)
</pre>
</li>
</ul>
<p>Called just before a new master process is forked.</p>
<p>The callable needs to accept a single instance variable for the Arbiter.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<p>This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0 Unported License</a>.</p>
<p>Hosted on <a href="http://github.com/">Github</a></p>
</div>
</div>
</body>
</html>