diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 7fa4085e..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,160 +0,0 @@ -# Makefile for Sphinx documentation -# -# if you want to compare this file to current sphinx defaults, recreate it: -# BUILDDIR=build sphinx-quickstart --sep --extensions=gunicorn_ext --templatedir=_templates --makefile --batchfile --no-use-make-mode --master=index - -# You can set these variables from the command line. -PYTHON = python -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source - -.PHONY: help clean html htmlview dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " htmlview to open the index page built by the html target in your browser" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -htmlview: html - $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Gunicorn.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Gunicorn.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Gunicorn" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Gunicorn" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/README.rst b/docs/README.rst deleted file mode 100644 index 9ec55d05..00000000 --- a/docs/README.rst +++ /dev/null @@ -1,19 +0,0 @@ -Generate Documentation -====================== - -Requirements ------------- - -To generate documentation you need to install: - - - Python >= 3.7 - - Sphinx (https://www.sphinx-doc.org/) - - -Generate html -------------- -:: - - $ make html - -The command generates html document inside ``build/html`` dir. diff --git a/docs/gunicorn_ext.py b/docs/gunicorn_ext.py deleted file mode 100755 index 4310162e..00000000 --- a/docs/gunicorn_ext.py +++ /dev/null @@ -1,102 +0,0 @@ -import os -import inspect - -from docutils import nodes, utils - -import gunicorn.config as guncfg - -HEAD = """\ -.. Please update gunicorn/config.py instead. - -.. _settings: - -Settings -======== - -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. - -.. note:: - - Settings can be specified by using environment variable - ``GUNICORN_CMD_ARGS``. All available command line arguments can be used. - For example, to specify the bind address and number of workers:: - - $ GUNICORN_CMD_ARGS="--bind=127.0.0.1 --workers=3" gunicorn app:app - - .. versionadded:: 19.7 - -""" -ISSUE_URI = 'https://github.com/benoitc/gunicorn/issues/%s' -PULL_REQUEST_URI = 'https://github.com/benoitc/gunicorn/pull/%s' - - -def format_settings(app): - settings_file = os.path.join(app.srcdir, "settings.rst") - ret = [] - known_settings = sorted(guncfg.KNOWN_SETTINGS, key=lambda s: s.section) - for i, s in enumerate(known_settings): - if i == 0 or s.section != known_settings[i - 1].section: - ret.append("%s\n%s\n\n" % (s.section, "-" * len(s.section))) - ret.append(fmt_setting(s)) - - with open(settings_file, 'w') as settings: - settings.write(HEAD) - settings.write(''.join(ret)) - - -def fmt_setting(s): - if hasattr(s, "default_doc"): - val = s.default_doc - elif callable(s.default): - val = inspect.getsource(s.default) - val = "\n".join(" %s" % line for line in val.splitlines()) - val = "\n\n.. code-block:: python\n\n" + val - elif s.default == '': - val = "``''``" - else: - val = "``%r``" % s.default - - if s.cli and s.meta: - cli = " or ".join("``%s %s``" % (arg, s.meta) for arg in s.cli) - elif s.cli: - cli = " or ".join("``%s``" % arg for arg in s.cli) - else: - cli = "" - - out = [] - out.append(".. _%s:\n" % s.name.replace("_", "-")) - out.append("``%s``" % s.name) - out.append("~" * (len(s.name) + 4)) - out.append("") - if s.cli: - out.append("**Command line:** %s" % cli) - out.append("") - out.append("**Default:** %s" % val) - out.append("") - out.append(s.desc) - out.append("") - out.append("") - return "\n".join(out) - - -def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): - issue = utils.unescape(text) - text = 'issue ' + issue - refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue) - return [refnode], [] - - -def pull_request_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): - issue = utils.unescape(text) - text = 'pull request ' + issue - refnode = nodes.reference(text, text, refuri=PULL_REQUEST_URI % issue) - return [refnode], [] - - -def setup(app): - app.connect('builder-inited', format_settings) - app.add_role('issue', issue_role) - app.add_role('pr', pull_request_role) diff --git a/docs/logo/gunicorn.png b/docs/logo/gunicorn.png deleted file mode 100644 index 8b9e4c9e..00000000 Binary files a/docs/logo/gunicorn.png and /dev/null differ diff --git a/docs/logo/gunicorn.svg b/docs/logo/gunicorn.svg deleted file mode 100644 index 073f2029..00000000 --- a/docs/logo/gunicorn.svg +++ /dev/null @@ -1,119 +0,0 @@ - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - g - - - - - diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 705fcdcd..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,190 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Gunicorn.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Gunicorn.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -:end diff --git a/docs/site/.nojekyll b/docs/site/.nojekyll deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/site/CNAME b/docs/site/CNAME deleted file mode 100644 index b9f0ffbc..00000000 --- a/docs/site/CNAME +++ /dev/null @@ -1 +0,0 @@ -gunicorn.org diff --git a/docs/site/community.html b/docs/site/community.html deleted file mode 100644 index f6fae4d4..00000000 --- a/docs/site/community.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Community - - -

- Redirecting to here -

- - diff --git a/docs/site/configuration.html b/docs/site/configuration.html deleted file mode 100644 index 88bcf302..00000000 --- a/docs/site/configuration.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Configuration - - -

- Redirecting to here -

- - diff --git a/docs/site/configure.html b/docs/site/configure.html deleted file mode 100644 index 3028eb9c..00000000 --- a/docs/site/configure.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Configure - - -

- Redirecting to here -

- - diff --git a/docs/site/css/style.css b/docs/site/css/style.css deleted file mode 100644 index aec17c99..00000000 --- a/docs/site/css/style.css +++ /dev/null @@ -1,402 +0,0 @@ -html,body { - margin: 0; - padding: 0; -} - -h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,cite, -code,del,dfn,em,img,q,s,samp,small,strike,strong,sub,sup,tt,var, -dd,dl,dt,li,ol,ul,fieldset,form,label,legend,button,table,caption, -tbody,tfoot,thead,tr,th,td { - margin: 0; - padding: 0; - border: 0; - font: inherit; - vertical-align: baseline; -} - -ol,ul { - list-style: none; -} - -html { - overflow-y: scroll; - font-size: 100%; - -webkit-text-size-adjust: 100%; - -ms-text-size-adjust: 100%; -} - -a:hover, a:active, a:focus { - outline: 0; -} - -img { - border: 0; - -ms-interpolation-mode: bicubic; -} - -body { - background: #F8F8F3; - margin: 0; - font: 14px/1.4 "Helvetica Neue", "HelveticaNeue", Helvetica, Arial, "Lucida Grande", sans-serif; - color: #67686B; - height: auto; -} - -a, -a:hover { - text-decoration: none; -} - -.clearall { - clear: both; - display: block; - overflow: hidden; - visibility: hidden; - width: 0; - height: 0; -} - -.logo-wrapper { - border-bottom: 1px solid #2A8729; -} - -.latest { - width: 150px; - top: 0; - display: block; - float: right; - font-weight: bold; -} - - -.logo-div { - width: 1000px; - margin: 0 auto; - padding: 5px; - height: 72px; -} - -.logo { - width: 250px; - margin: 0 auto; - height: 119px; - background: url(../images/logo-bottom.png) no-repeat bottom center; - position: relative; - z-index: 99999; -} - -.banner-wrapper { - background: url(../images/banner-bg.jpg) repeat; - display: block; - width: 100%; - min-height: 365px; - margin-top: 1px; - margin-bottom: 1px; -} - -.banner { - width: 1000px; - margin: 0 auto; - padding: 15px; -} - -.title { - width: 250px; - margin: 0 auto; - margin-top: 32px; - text-align:center; -} - -.banner h1 { - font-size: 20px; - color: #FFF; - margin: 15px 10px 0; - padding: 5px 40px; - text-align: center; - line-height: 28px; -} - -.greenbutton { - background: url(../images/greenbutton.jpg) repeat-x; - height: 54px; - width: 224px; - line-height: 54px; - display: inline-block; - text-align: center; - border-radius: 3px; - border: solid 1px #1D692D; - color: #fff; - font-size: 22px; - letter-spacing: 1px; - text-shadow: 1px 1px 1px #000; -} - -.greenbutton:hover { - background: url(../images/greenbutton.jpg) repeat-x bottom; -} - -.redbutton { - background: url(../images/redbutton.jpg) repeat-x; - height: 54px; - width: 224px; - line-height: 54px; - display: inline-block; - text-align: center; - border-radius: 3px; - border: solid 1px #7D180A; - color: #fff; - font-size: 22px; - letter-spacing: 1px; - text-shadow: 1px 1px 1px #000; -} - -.redbutton:hover { - background: url(../images/redbutton.jpg) repeat-x bottom; -} - -.banner-button { - width: 460px; - margin: 0 auto; - margin-top: 30px; -} - -.banner-link { - width: 250px; - margin: 0 auto; - margin-top: 15px; - padding: 5px; - text-align: center; -} - -.banner-link a { - color: #fff; - font-weight: 700; - letter-spacing: 1px; -} - -.banner-link a:hover { - color: #000; -} - -.mid-wrapper { - width: 100%; - border-top: 1px solid #2A8729; - padding-top: 15px; -} - -.tabs { - width: 1000px; - margin: 0 auto; - padding: 3px; - margin-top: 5px; - margin-bottom: 25px; -} - -.tab-bar li { - width: 230px; - padding: 3px; - text-align: center; - float: left; - margin-right: 5px; - margin-left: 6px; -} - -.tab-bar li a { - display: inline-block; -} - -.tab-bar li a:hover > p, -.tab-bar li a:hover > h2 { - color: #1D692D; -} - -.tab-bar li a p, -.tab-bar li a h2 { - color: #404028; - margin-top: 8px; - line-height: 1.2; -} - -.tab-bar li a h2 { - font-weight: 700; - text-transform: uppercase; -} - -.withborder { - background: url(../images/separator.jpg) no-repeat; -} - -.gabout, .gcommunity, .gdownloads, .gdocuments { - height: 80px; - width: 230px; - padding-top: 118px; -} - -.gabout { - background: url(../images/about.jpg) no-repeat 50% 0; -} - -.gcommunity { - background: url(../images/community.jpg) no-repeat 50% 0; -} - -.gdocuments { - background: url(../images/documents.jpg) no-repeat 50% 0; -} - -.gdownloads { - background: url(../images/downloads.jpg) no-repeat 50% 0; -} - -.tabs li.active a, -.gabout:hover, -.gcommunity:hover, -.gdocuments:hover, -.gdownloads:hover { - background-position: 50% -220px; -} - -.tabs div { - display:none; -} - -.tabs div.active { - display: block; -} - -.tab-box { - color: #3F3F27; - border: 1px solid #DDDDD5; - padding: 25px 35px; - position: relative; - margin-top: 20px; - border-radius: 3px; -} - -.tab-box h1 { - font-size: 28px; - color: #2A8729; -} - -.tab-box p { - margin: 0 0 9px; -} - -.tab-box ul { - padding-left: 40px; -} - -.tab-box li { - list-style: disc; - margin: 0 0 9px; -} - -.tab-box a, -.latest a { - color: #3F3F27; - text-decoration: underline; -} - -.tab-box a:hover, -.latest a:hover { - color: #1D692D; -} - -.arrow { - background: url(../images/arrow.png) no-repeat; - position: absolute; - left: 115px; - top: -7px; - height: 10px; - width: 20px; -} - -pre { - font-family: Menlo, Monaco, Consolas, "Courier New", monospace; - font-size: 14px; - color: #333333; - display: block; - padding: 8.5px; - margin: 0 0 9px; - font-size: 14px; - line-height: 18px; - word-break: break-all; - word-wrap: break-word; - white-space: pre; - white-space: pre-wrap; - background-color: #EEFFCC; - border-top: 1px solid #A9CC99; - border-bottom: 1px solid #A9CC99; -} - -.user-wrapper { - background: url(../images/banner-bg.jpg) repeat; - height: 110px; -} - -.users { - width: 1000px; - padding: 20px 5px; - margin: 0 auto; - color: #fff; -} - -.users h3 { - font-size: 12px; - margin-left: 5px; - padding-top: 15px; -} - -.users h2 { - font-size: 26px; - margin-left: 5px; -} - -.users .left-details { - width: 120px; - float: left; - height: 66px; - background: url(../images/footer-arrow.png) no-repeat top right; - padding-right: 15px; - text-align: right; -} - -.users .company-logos { - float: left; - width: 820px; - height: 70px; - margin-left: 20px; -} - -.users .company-logos a img { - float: left; - border: solid 1px #004000; - margin: 0 6px; -} - -.users .company-logos a:hover img { - border: solid 1px #000; -} - -.footer { - background-color: #F8F8F3; - display: block; - height: 70px; -} - -.footer .footer-wp { - margin: 0 auto; - padding: 15px 5px; - width: 930px; - background: url(../images/footer-logo.jpg) no-repeat 0 50%; - padding-left: 70px; -} - -.footer-wp a { - color: #3F3F27; - text-decoration: underline; -} - -.footer-wp a:hover { - color: #1D692D; -} diff --git a/docs/site/deploy.html b/docs/site/deploy.html deleted file mode 100644 index 97568d2e..00000000 --- a/docs/site/deploy.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Deployment - - -

- Redirecting to here -

- - diff --git a/docs/site/deployment.html b/docs/site/deployment.html deleted file mode 100644 index 2ccee4bb..00000000 --- a/docs/site/deployment.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Deployment - - -

- Redirecting to here -

- - \ No newline at end of file diff --git a/docs/site/design.html b/docs/site/design.html deleted file mode 100644 index 38f04705..00000000 --- a/docs/site/design.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Design - - -

- Redirecting to here -

- - diff --git a/docs/site/faq.html b/docs/site/faq.html deleted file mode 100644 index 5dbdc0b1..00000000 --- a/docs/site/faq.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - FAQ - - -

- Redirecting to here -

- - diff --git a/docs/site/images/about.jpg b/docs/site/images/about.jpg deleted file mode 100644 index 4aab4d50..00000000 Binary files a/docs/site/images/about.jpg and /dev/null differ diff --git a/docs/site/images/arrow.png b/docs/site/images/arrow.png deleted file mode 100644 index 754d3091..00000000 Binary files a/docs/site/images/arrow.png and /dev/null differ diff --git a/docs/site/images/banner-bg.jpg b/docs/site/images/banner-bg.jpg deleted file mode 100644 index 0ba44ffa..00000000 Binary files a/docs/site/images/banner-bg.jpg and /dev/null differ diff --git a/docs/site/images/community.jpg b/docs/site/images/community.jpg deleted file mode 100644 index 0cda8a88..00000000 Binary files a/docs/site/images/community.jpg and /dev/null differ diff --git a/docs/site/images/documents.jpg b/docs/site/images/documents.jpg deleted file mode 100644 index d96d8ca9..00000000 Binary files a/docs/site/images/documents.jpg and /dev/null differ diff --git a/docs/site/images/downloads.jpg b/docs/site/images/downloads.jpg deleted file mode 100644 index 9c4f9373..00000000 Binary files a/docs/site/images/downloads.jpg and /dev/null differ diff --git a/docs/site/images/favicon.png b/docs/site/images/favicon.png deleted file mode 100644 index 63bef255..00000000 Binary files a/docs/site/images/favicon.png and /dev/null differ diff --git a/docs/site/images/footer-arrow.png b/docs/site/images/footer-arrow.png deleted file mode 100644 index 483639f4..00000000 Binary files a/docs/site/images/footer-arrow.png and /dev/null differ diff --git a/docs/site/images/footer-logo.jpg b/docs/site/images/footer-logo.jpg deleted file mode 100644 index cf6e5e39..00000000 Binary files a/docs/site/images/footer-logo.jpg and /dev/null differ diff --git a/docs/site/images/greenbutton.jpg b/docs/site/images/greenbutton.jpg deleted file mode 100644 index 0f8d7ac3..00000000 Binary files a/docs/site/images/greenbutton.jpg and /dev/null differ diff --git a/docs/site/images/gunicorn.png b/docs/site/images/gunicorn.png deleted file mode 100644 index 98aaf382..00000000 Binary files a/docs/site/images/gunicorn.png and /dev/null differ diff --git a/docs/site/images/large_gunicorn.png b/docs/site/images/large_gunicorn.png deleted file mode 100644 index 403301fc..00000000 Binary files a/docs/site/images/large_gunicorn.png and /dev/null differ diff --git a/docs/site/images/logo-bottom.png b/docs/site/images/logo-bottom.png deleted file mode 100644 index 9264bed9..00000000 Binary files a/docs/site/images/logo-bottom.png and /dev/null differ diff --git a/docs/site/images/logo.jpg b/docs/site/images/logo.jpg deleted file mode 100644 index f96c50cf..00000000 Binary files a/docs/site/images/logo.jpg and /dev/null differ diff --git a/docs/site/images/logo.png b/docs/site/images/logo.png deleted file mode 100644 index c162d6ae..00000000 Binary files a/docs/site/images/logo.png and /dev/null differ diff --git a/docs/site/images/redbutton.jpg b/docs/site/images/redbutton.jpg deleted file mode 100644 index 735f7304..00000000 Binary files a/docs/site/images/redbutton.jpg and /dev/null differ diff --git a/docs/site/images/separator.jpg b/docs/site/images/separator.jpg deleted file mode 100644 index 6e6cbb8b..00000000 Binary files a/docs/site/images/separator.jpg and /dev/null differ diff --git a/docs/site/images/title.png b/docs/site/images/title.png deleted file mode 100644 index e257bf20..00000000 Binary files a/docs/site/images/title.png and /dev/null differ diff --git a/docs/site/images/user1.jpg b/docs/site/images/user1.jpg deleted file mode 100644 index 6373b77f..00000000 Binary files a/docs/site/images/user1.jpg and /dev/null differ diff --git a/docs/site/index.html b/docs/site/index.html deleted file mode 100644 index f8f811ca..00000000 --- a/docs/site/index.html +++ /dev/null @@ -1,185 +0,0 @@ - - - - - Gunicorn - Python WSGI HTTP Server for UNIX - - - - - - - -
-
-
- Latest version: 23.0.0 -
- - -
-
- - -
-
- -
- -
-

Installation

-

- Here's a quick rundown on how to get started with Gunicorn. For more details read the documentation. -

-
-  $ pip install gunicorn
-  $ cat myapp.py
-    def app(environ, start_response):
-        data = b"Hello, World!\n"
-        start_response("200 OK", [
-            ("Content-Type", "text/plain"),
-            ("Content-Length", str(len(data)))
-        ])
-        return iter([data])
-  $ gunicorn -w 4 myapp:app
-  [2014-09-10 10:22:28 +0000] [30869] [INFO] Listening at: http://127.0.0.1:8000 (30869)
-  [2014-09-10 10:22:28 +0000] [30869] [INFO] Using worker: sync
-  [2014-09-10 10:22:28 +0000] [30874] [INFO] Booting worker with pid: 30874
-  [2014-09-10 10:22:28 +0000] [30875] [INFO] Booting worker with pid: 30875
-  [2014-09-10 10:22:28 +0000] [30876] [INFO] Booting worker with pid: 30876
-  [2014-09-10 10:22:28 +0000] [30877] [INFO] Booting worker with pid: 30877
-
-
-
-

Deployment

-

- Gunicorn is a WSGI HTTP server. It is best to use Gunicorn behind an HTTP proxy server. We strongly advise you to use nginx. -

-

Here's an example to help you get started with using nginx:

-
-  server {
-    listen 80;
-    server_name example.org;
-    access_log  /var/log/nginx/example.log;
-
-    location / {
-        proxy_pass http://127.0.0.1:8000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    }
-  }
-
-

Nginx is set up as reverse proxy server to a Gunicorn server running on localhost port 8000.

-

Read the full documentation at docs.gunicorn.org

-
-
-

Project Management

-

Gunicorn uses GitHub for the project management. GitHub issues are used for 3 different purposes:

- -

Project maintenance guidelines are available on the wiki

- -

IRC

-

The Gunicorn channel is on the Libera Chat IRC - network. You can chat with the community on the #gunicorn channel.

- -

Issue Tracking

-

Bug reports, enhancement requests and tasks generally go in the Github - issue tracker.

- -

Security Issues

-

The security mailing list is a place to report security issues. Only - developers are subscribed to it. To post a message to the list use the - address security@gunicorn.org

- -
-
-

Documentation

-

You can read more comprehensive documentation at docs.gunicorn.org.

-

The contents are:

-
-
-
- - - -
-
- This open sourced site is hosted on GitHub.
- Patches, suggestions, and comments are welcome. -
-
- - - - - diff --git a/docs/site/install.html b/docs/site/install.html deleted file mode 100644 index b3dfbd47..00000000 --- a/docs/site/install.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Install - - -

- Redirecting to here -

- - diff --git a/docs/site/installation.html b/docs/site/installation.html deleted file mode 100644 index b3dfbd47..00000000 --- a/docs/site/installation.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Install - - -

- Redirecting to here -

- - diff --git a/docs/site/js/main.js b/docs/site/js/main.js deleted file mode 100755 index c285c8fd..00000000 --- a/docs/site/js/main.js +++ /dev/null @@ -1,46 +0,0 @@ -$(document).ready(function() { - Tabs.init(); -}); - -var Tabs = { - init: function(){ - var activateTab = function ($tab) { - var // this links tabs set - $tabs = $tab.parents('.tabs'), - // currently active tab - activeTab = { - 'tab' : $tabs.find('ul').children('li.active'), - 'content' : $tabs.find('div[data-tab].active') - }, - // newly clicked tab - newTab = { - 'tab' : $tab.parent('li'), - 'content' : $tabs.find('[data-tab=' + $tab.attr('href').replace('#', '') + ']') - }, - x, y; - - // remove active class from tab and content - for (x in activeTab) { - activeTab[x].removeClass('active'); - } - - // add active class to tab and content - for (y in newTab) { - newTab[y].addClass('active'); - } - }; - // hook up tab links - $(document).on('click', '.tabs ul li a', function(e) { - activateTab($(this)); - //alert($(this)); - }); - - // hook up initial load active tab - if (window.location.hash) { - var $activeTab = $('a[href="' + window.location.hash + '"]'); - if ($activeTab.length && $activeTab.parents('.tabs').length) { - activateTab($activeTab); - } - } - } -}; \ No newline at end of file diff --git a/docs/site/news.html b/docs/site/news.html deleted file mode 100644 index 318dcdf2..00000000 --- a/docs/site/news.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - News - - -

- Redirecting to here -

- - diff --git a/docs/site/run.html b/docs/site/run.html deleted file mode 100644 index 236fc3e4..00000000 --- a/docs/site/run.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Run - - -

- Redirecting to here -

- - diff --git a/docs/site/sitemap.xml b/docs/site/sitemap.xml deleted file mode 100644 index 6411a24e..00000000 --- a/docs/site/sitemap.xml +++ /dev/null @@ -1,73 +0,0 @@ - - - - http://gunicorn.org/ - 2019-11-27T00:02:48+01:00 - 1.0 - - - http://gunicorn.org/community.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/configuration.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/configure.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/deploy.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/deployment.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/design.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/faq.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/install.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/installation.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/news.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/run.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/tuning.html - 2012-10-04T00:43:15+05:45 - 0.5 - - - http://gunicorn.org/usage.html - 2012-10-04T00:43:15+05:45 - 0.5 - - diff --git a/docs/site/tuning.html b/docs/site/tuning.html deleted file mode 100644 index 5dbdc0b1..00000000 --- a/docs/site/tuning.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - FAQ - - -

- Redirecting to here -

- - diff --git a/docs/site/usage.html b/docs/site/usage.html deleted file mode 100644 index 236fc3e4..00000000 --- a/docs/site/usage.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Green Unicorn - Run - - -

- Redirecting to here -

- - diff --git a/docs/sitemap_gen.py b/docs/sitemap_gen.py deleted file mode 100644 index 29c7ca02..00000000 --- a/docs/sitemap_gen.py +++ /dev/null @@ -1,41 +0,0 @@ -import os -import subprocess -from xml.etree import ElementTree - - -def main(): - generate( - site_path=os.path.join(os.path.dirname(__file__), 'site'), - special_priorities={'index.html': 1.0}) - - -def generate(site_path, special_priorities, directory_index='index.html'): - urlset = ElementTree.Element('urlset', xmlns='http://www.sitemaps.org/schemas/sitemap/0.9') - urlset.text = '\n ' - for root, dirs, filenames in os.walk(site_path): - for filename in filenames: - if filename.endswith('.html'): - absolute_filepath = os.path.join(root, filename) - relative_path = os.path.relpath(absolute_filepath, site_path) - relative_url = os.path.dirname(relative_path) if filename == directory_index else relative_path - last_modification = subprocess.check_output( - ['git', 'log', '-1', '--pretty="%cI"', absolute_filepath]).decode('ascii').strip('\n"') - url_element = ElementTree.SubElement(urlset, 'url') - loc_element = ElementTree.SubElement(url_element, 'loc') - loc_element.text = 'http://gunicorn.org/' + relative_url - lastmod_element = ElementTree.SubElement(url_element, 'lastmod') - lastmod_element.text = last_modification - priority_element = ElementTree.SubElement(url_element, 'priority') - priority_element.text = str(special_priorities.get(relative_path, 0.5)) - url_element.tail = priority_element.tail = '\n ' - url_element.text = loc_element.tail = lastmod_element.tail = '\n ' - # We sort the url nodes instead of the filenames because - # filenames might be altered by the directory_index option - urlset[:] = sorted([url for url in urlset], key=lambda url: url[0].text) - urlset.tail = urlset[-1].tail = '\n' - with open(os.path.join(site_path, 'sitemap.xml'), 'wb') as sitemap_file: - ElementTree.ElementTree(urlset).write(sitemap_file, encoding='UTF-8', xml_declaration=True) - - -if __name__ == '__main__': - main() diff --git a/docs/source/2010-news.rst b/docs/source/2010-news.rst deleted file mode 100644 index e58c4819..00000000 --- a/docs/source/2010-news.rst +++ /dev/null @@ -1,211 +0,0 @@ -Changelog - 2010 -================ - -0.12.0 / 2010-12-22 -------------------- - -- Add support for logging configuration using a ini file. - It uses the standard Python logging's module Configuration - file format and allows anyone to use his custom file handler -- Add IPV6 support -- Add multidomain application example -- Improve gunicorn_django command when importing settings module - using DJANGO_SETTINGS_MODULE environment variable -- Send appropriate error status on http parsing -- Fix pidfile, set permissions so other user can read - it and use it. -- Fix temporary file leaking -- Fix setpgrp issue, can now be launched via ubuntu upstart -- Set the number of workers to zero on WINCH - -0.11.2 / 2010-10-30 -------------------- - -* Add SERVER_SOFTWARE to the os.environ -* Add support for django settings environment variable -* Add support for logging configuration in Paster ini-files -* Improve arbiter notification in asynchronous workers -* Display the right error when a worker can't be used -* Fix Django support -* Fix HUP with Paster applications -* Fix readline in wsgi.input - -0.11.1 / 2010-09-02 -------------------- - -* Implement max-requests feature to prevent memory leaks. -* Added 'worker_exit' server hook. -* Reseed the random number generator after fork(). -* Improve Eventlet worker. -* Fix Django command `run_gunicorn`. -* Fix the default proc name internal setting. -* Workaround to prevent Gevent worker to segfault on MacOSX. - -0.11.0 / 2010-08-12 -------------------- - -* Improve dramatically performances of Gevent and Eventlet workers -* Optimize HTTP parsing -* Drop Server and Date headers in start_response when provided. -* Fix latency issue in async workers - -0.10.1 / 2010-08-06 -------------------- - -* Improve gevent's workers. Add "egg:gunicorn#gevent_wsgi" worker using - `gevent.wsgi `_ and - "egg:gunicorn#gevent_pywsgi" worker using `gevent.pywsgi - `_ . - **"egg:gunicorn#gevent"** using our own HTTP parser is still here and - is **recommended** for normal uses. Use the "gevent.wsgi" parser if you - need really fast connections and don't need streaming, keepalive or ssl. -* Add pre/post request hooks -* Exit more quietly -* Fix gevent dns issue - -0.10.0 / 2010-07-08 -------------------- - -* New HTTP parser. -* New HUP behaviour. Re-reads the configuration and then reloads all - worker processes without changing the master process id. Helpful for - code reloading and monitoring applications like supervisord and runit. -* Added a preload configuration parameter. By default, application code - is now loaded after a worker forks. This couple with the new HUP - handling can be used for dev servers to do hot code reloading. Using - the preload flag can help a bit in small memory VM's. -* Allow people to pass command line arguments to WSGI applications. See: - `examples/alt_spec.py - `_ -* Added an example gevent reloader configuration: - `examples/example_gevent_reloader.py - `_. -* New gevent worker "egg:gunicorn#gevent2", working with gevent.wsgi. -* Internal refactoring and various bug fixes. -* New documentation website. - -0.9.1 / 2010-05-26 ------------------- - -* Support https via X-Forwarded-Protocol or X-Forwarded-Ssl headers -* Fix configuration -* Remove -d options which was used instead of -D for daemon. -* Fix umask in unix socket - -0.9.0 / 2010-05-24 ------------------- - -* Added *when_ready* hook. Called just after the server is started -* Added *preload* setting. Load application code before the worker processes - are forked. -* Refactored Config -* Fix pidfile -* Fix QUIT/HUP in async workers -* Fix reexec -* Documentation improvements - -0.8.1 / 2010-04-29 ------------------- - -* Fix builtins import in config -* Fix installation with pip -* Fix Tornado WSGI support -* Delay application loading until after processing all configuration - -0.8.0 / 2010-04-22 ------------------- - -* Refactored Worker management for better async support. Now use the -k option - to set the type of request processing to use -* Added support for Tornado_ - -0.7.2 / 2010-04-15 ------------------- - -* Added --spew option to help debugging (installs a system trace hook) -* Some fixes in async arbiters -* Fix a bug in start_response on error - -0.7.1 / 2010-04-01 ------------------- - -* Fix bug when responses have no body. - -0.7.0 / 2010-03-26 ------------------- - -* Added support for Eventlet_ and Gevent_ based workers. -* Added Websockets_ support -* Fix Chunked Encoding -* Fix SIGWINCH on OpenBSD_ -* Fix `PEP 333`_ compliance for the write callable. - -0.6.5 / 2010-03-11 ------------------- - -* Fix pidfile handling -* Fix Exception Error - -0.6.4 / 2010-03-08 ------------------- - -* Use cStringIO for performance when possible. -* Fix worker freeze when a remote connection closes unexpectedly. - -0.6.3 / 2010-03-07 ------------------- - -* Make HTTP parsing faster. -* Various bug fixes - -0.6.2 / 2010-03-01 ------------------- - -* Added support for chunked response. -* Added proc_name option to the config file. -* Improved the HTTP parser. It now uses buffers instead of strings to store - temporary data. -* Improved performance when sending responses. -* Workers are now murdered by age (the oldest is killed first). - -0.6.1 / 2010-02-24 ------------------- - -* Added gunicorn config file support for Django admin command -* Fix gunicorn config file. -c was broken. -* Removed TTIN/TTOU from workers which blocked other signals. - -0.6.0 / 2010-02-22 ------------------- - -* Added setproctitle support -* Change privilege switch behavior. We now work like NGINX, master keeps the - permissions, new uid/gid permissions are only set for workers. - -0.5.1 / 2010-02-22 ------------------- - -* Fix umask -* Added Debian packaging - -0.5.0 / 2010-02-20 ------------------- - -* Added `configuration file `_ handler. -* Added support for pre/post fork hooks -* Added support for before_exec hook -* Added support for unix sockets -* Added launch of workers processes under different user/group -* Added umask option -* Added SCRIPT_NAME support -* Better support of some exotic settings for Django projects -* Better support of Paste-compatible applications -* Some refactoring to make the code easier to hack -* Allow multiple keys in request and response headers - -.. _Tornado: http://www.tornadoweb.org/ -.. _`PEP 333`: https://www.python.org/dev/peps/pep-0333/ -.. _Eventlet: http://eventlet.net/ -.. _Gevent: http://www.gevent.org/ -.. _OpenBSD: https://www.openbsd.org/ -.. _Websockets: https://html.spec.whatwg.org/multipage/web-sockets.html diff --git a/docs/source/2011-news.rst b/docs/source/2011-news.rst deleted file mode 100644 index 3bc2a1a2..00000000 --- a/docs/source/2011-news.rst +++ /dev/null @@ -1,73 +0,0 @@ -Changelog - 2011 -================ - -0.13.4 / 2011-09-23 -------------------- - -- fix util.closerange function used to prevent leaking fds on python 2.5 - (typo) - -0.13.3 / 2011-09-19 -------------------- -- refactor gevent worker -- prevent leaking fds on reexec -- fix inverted request_time computation - -0.13.2 / 2011-09-17 -------------------- - -- Add support for Tornado 2.0 in tornado worker -- Improve access logs: allows customisation of the log format & add - request time -- Logger module is now pluggable -- Improve graceful shutdown in Python versions >= 2.6 -- Fix post_request root arity for compatibility -- Fix sendfile support -- Fix Django reloading - -0.13.1 / 2011-08-22 -------------------- - -- Fix unix socket. log argument was missing. - -0.13.0 / 2011-08-22 -------------------- - -- Improve logging: allows file-reopening and add access log file - compatible with the `apache combined log format `_ -- Add the possibility to set custom SSL headers. X-Forwarded-Protocol - and X-Forwarded-SSL are still the default -- New `on_reload` hook to customize how gunicorn spawn new workers on - SIGHUP -- Handle projects with relative path in django_gunicorn command -- Preserve path parameters in PATH_INFO -- post_request hook now accepts the environ as argument. -- When stopping the arbiter, close the listener asap. -- Fix Django command `run_gunicorn` in settings reloading -- Fix Tornado_ worker exiting -- Fix the use of sendfile in wsgi.file_wrapper - - -0.12.2 / 2011-05-18 -------------------- - -- Add wsgi.file_wrapper optimised for FreeBSD, Linux & MacOSX (use - sendfile if available) -- Fix django run_gunicorn command. Make sure we reload the application - code. -- Fix django localisation -- Compatible with gevent 0.14dev - -0.12.1 / 2011-03-23 -------------------- - -- Add "on_starting" hook. This hook can be used to set anything before - the arbiter really start -- Support bdist_rpm in setup -- Improve content-length handling (pep 3333) -- Improve Django support -- Fix daemonizing (#142) -- Fix ipv6 handling - - -.. _Tornado: http://www.tornadoweb.org/ diff --git a/docs/source/2012-news.rst b/docs/source/2012-news.rst deleted file mode 100644 index ce4f7cc4..00000000 --- a/docs/source/2012-news.rst +++ /dev/null @@ -1,128 +0,0 @@ -Changelog - 2012 -================ - -0.17.0 / 2012-12-25 -------------------- - -- allows gunicorn to bind to multiple address -- add SSL support -- add syslog support -- add nworkers_changed hook -- add response arg for post_request hook -- parse command line with argparse (replace deprecated optparse) -- fix PWD detection in arbiter -- miscellaneous PEP8 fixes - -0.16.1 / 2012-11-19 -------------------- - -- Fix packaging - -0.16.0 / 2012-11-19 -------------------- - -- **Added support for Python 3.2 & 3.3** -- Expose --pythonpath command to all gunicorn commands -- Honor $PORT environment variable, useful for deployment on heroku -- Removed support for Python 2.5 -- Make sure we reopen the logs on the console -- Fix django settings module detection from path -- Reverted timeout for client socket. Fix issue on blocking issues. -- Fixed gevent worker - -0.15.0 / 2012-10-18 -------------------- - -- new documentation site on http://docs.gunicorn.org -- new website on http://gunicorn.org -- add `haproxy PROXY protocol `_ support -- add ForwardedAllowIPS option: allows to filter Front-end's IPs - allowed to handle X-Forwarded-* headers. -- add callable hooks for paster config -- add x-forwarded-proto as secure scheme default (Heroku is using this) -- allows gunicorn to load a pre-compiled application -- support file reopening & reexec for all loggers -- initialize the logging config file with defaults. -- set timeout for client socket (slow client DoS). -- NoMoreData, ChunkMissingTerminator, InvalidChunkSize are now - IOError exceptions -- fix graceful shutdown in gevent -- fix limit request line check - -0.14.6 / 2012-07-26 -------------------- - - -- fix gevent & subproces -- fix request line length check -- fix keepalive = 0 -- fix tornado worker - -0.14.5 / 2012-06-24 --------------------- - -- fix logging during daemonisation - -0.14.4 / 2012-06-24 -------------------- - -- new --graceful-timeout option -- fix multiple issues with request limit -- more fixes in django settings resolutions -- fix gevent.core import -- fix keepalive=0 in eventlet worker -- fix handle_error display with the unix worker -- fix tornado.wsgi.WSGIApplication calling error - -- **breaking change**: take the control on graceful reload back. - graceful can't be overridden anymore using the on_reload function. - -0.14.3 / 2012-05-15 -------------------- - -- improvement: performance of http.body.Body.readline() -- improvement: log HTTP errors in access log like Apache -- improvement: display traceback when the worker fails to boot -- improvement: makes gunicorn work with gevent 1.0 -- examples: websocket example now supports hybi13 -- fix: reopen log files after initialization -- fix: websockets support -- fix: django1.4 support -- fix: only load the paster application 1 time - -0.14.2 / 2012-03-16 -------------------- - -- add validate_class validator: allows to use a class or a method to - initialize the app during in-code configuration -- add support for max_requests in tornado worker -- add support for disabling x_forwarded_for_header in tornado worker -- gevent_wsgi is now an alias of gevent_pywsgi -- Fix gevent_pywsgi worker - -0.14.1 / 2012-03-02 -------------------- - -- fixing source archive, reducing its size - -0.14.0 / 2012-02-27 -------------------- - -- check if Request line is too large: You can now pass the parameter - ``--limit-request-line`` or set the ``limit_request_line`` in your - configuration file to set the max size of the request line in bytes. -- limit the number of headers fields and their size. Add - ``--limit-request-field`` and ``limit-request-field-size`` settings -- add ``p`` variable to the log access format to log pidfile -- add ``{HeaderName}o`` variable to the logo access format to log the - response header HeaderName -- request header is now logged with the variable ``{HeaderName}i`` in the - access log file -- improve error logging -- support logging.configFile -- support django 1.4 in both gunicorn_django & run_gunicorn command -- improve reload in django run_gunicorn command (should just work now) -- allows people to set the ``X-Forwarded-For`` header key and disable it by - setting an empty string. -- fix support of Tornado -- many other fixes. diff --git a/docs/source/2013-news.rst b/docs/source/2013-news.rst deleted file mode 100644 index eb8cf556..00000000 --- a/docs/source/2013-news.rst +++ /dev/null @@ -1,90 +0,0 @@ -Changelog - 2013 -================ - -18.0 / 2013-08-26 ------------------ - -- new: add ``-e/--env`` command line argument to pass an environment variables to - gunicorn -- new: add ``--chdir`` command line argument to specified directory - before apps loading. - new: add wsgi.file_wrapper support in async workers -- new: add ``--paste`` command line argument to set the paster config file -- deprecated: the command ``gunicorn_django`` is now deprecated. You should now - run your application with the WSGI interface installed with your project (see - https://docs.djangoproject.com/en/1.4/howto/deployment/wsgi/gunicorn/) for - more infos. -- deprecated: the command ``gunicorn_paste`` is deprecated. You now should use - the new ``--paste`` argument to set the configuration file of your paster - application. -- fix: Removes unmatched leading quote from the beginning of the default access - log format string -- fix: null timeout -- fix: gevent worker -- fix: don't reload the paster app when using pserve -- fix: after closing for error do not keep alive the connection -- fix: responses 1xx, 204 and 304 should not force the connection to be closed - -17.5 / 2013-07-03 ------------------- - -- new: add signals documentation -- new: add post_worker_init hook for workers -- new: try to use gunicorn.conf.py in current folder as the default - config file. -- fix graceful timeout with the Eventlet worker -- fix: don't raise an error when closing the socket if already closed -- fix: fix --settings parameter for django application and try to find - the django settings when using the ``gunicorn`` command. -- fix: give the initial global_conf to paster application -- fix: fix 'Expect: 100-continue' support on Python 3 - -New versioning: -++++++++++++++++ - -With this release, the versioning of Gunicorn is changing. Gunicorn is -stable since a long time and there is no point to release a "1.0" now. -It should have been done since a long time. 0.17 really meant it was the -17th stable version. From the beginning we have only 2 kind of -releases: - -major release: releases with major changes or huge features added -services releases: fixes and minor features added So from now we will -apply the following versioning ``.``. For example ``17.5`` is a -service release. - -0.17.4 / 2013-04-24 -------------------- - -- fix unix socket address parsing - -0.17.3 / 2013-04-23 -------------------- - -- add systemd sockets support -- add ``python -m gunicorn.app.wsgiapp`` support -- improve logger class inheritance -- exit when the config file isn't found -- add the -R option to enable stdio inheritance in daemon mode -- don't close file descriptors > 3 in daemon mode -- improve STDOUT/STDERR logging -- fix pythonpath option -- fix pidfile creation on Python 3 -- fix gevent worker exit -- fix ipv6 detection when the platform isn't supporting it - -0.17.2 / 2013-01-07 -------------------- - -- optimize readline -- make imports errors more visible when loading an app or a logging - class -- fix tornado worker: don't pass ssl options if there are none -- fix PEP3333: accept only bytetrings in the response body -- fix support on CYGWIN platforms - -0.17.1 / 2013-01-05 -------------------- - -- add syslog facility name setting -- fix ``--version`` command line argument -- fix wsgi url_scheme for https diff --git a/docs/source/2014-news.rst b/docs/source/2014-news.rst deleted file mode 100644 index 3eec18fc..00000000 --- a/docs/source/2014-news.rst +++ /dev/null @@ -1,228 +0,0 @@ -================ -Changelog - 2014 -================ - -.. note:: - - Please see :doc:`news` for the latest changes. - -19.1.1 / 2014-08-16 -=================== - -Changes -------- - -Core -++++ - -- fix :issue:`835`: display correct pid of already running instance -- fix :pr:`833`: fix `PyTest` class in setup.py. - - -Logging -+++++++ - -- fix :issue:`838`: statsd logger, send statsd timing metrics in milliseconds -- fix :issue:`839`: statsd logger, allows for empty log message while pushing - metrics and restore worker number in DEBUG logs -- fix :issue:`850`: add timezone to logging -- fix :issue:`853`: Respect logger_class setting unless statsd is on - -AioHttp worker -++++++++++++++ - -- fix :issue:`830` make sure gaiohttp worker is shipped with gunicorn. - -19.1 / 2014-07-26 -================= - -Changes -------- - -Core -++++ - -- fix :issue:`785`: handle binary type address given to a client socket address -- fix graceful shutdown. make sure QUIT and TERMS signals are switched everywhere. -- :issue:`799`: fix support loading config from module -- :issue:`805`: fix check for file-like objects -- fix :issue:`815`: args validation in WSGIApplication.init -- fix :issue:`787`: check if we load a pyc file or not. - - -Tornado worker -++++++++++++++ - -- fix :issue:`771`: support tornado 4.0 -- fix :issue:`783`: x_headers error. The x-forwarded-headers option has been removed - in `c4873681299212d6082cd9902740eef18c2f14f1 - `_. - The discussion is available on :pr:`633`. - - -AioHttp worker -++++++++++++++ - -- fix: fetch all body in input. fix :issue:`803` -- fix: don't install the worker if python < 3.3 -- fix :issue:`822`: Support UNIX sockets in gaiohttp worker - - -Async worker -++++++++++++ - -- fix :issue:`790`: StopIteration shouldn't be caught at this level. - - -Logging -+++++++ - -- add statsd logging handler fix :issue:`748` - - -Paster -++++++ - -- fix :issue:`809`: Set global logging configuration from a Paste config. - - -Extra -+++++ - -- fix RuntimeError in gunicorn.reloader (:issue:`807`) - - -Documentation -+++++++++++++ - -- update faq: put a note on how `watch logs in the console - `_ - since many people asked for it. - - -19.0 / 2014-06-12 -================= - -Gunicorn 19.0 is a major release with new features and fixes. This -version improve a lot the usage of Gunicorn with python 3 by adding `two -new workers `_ -to it: `gthread` a fully threaded async worker using futures and `gaiohttp` a -worker using asyncio. - - -Breaking Changes ----------------- - -Switch QUIT and TERM signals -++++++++++++++++++++++++++++ - -With this change, when gunicorn receives a QUIT all the workers are -killed immediately and exit and TERM is used for the graceful shutdown. - -Note: the old behaviour was based on the NGINX but the new one is more -correct according the following doc: - -https://www.gnu.org/software/libc/manual/html_node/Termination-Signals.html - -also it is complying with the way the signals are sent by heroku: - -https://devcenter.heroku.com/articles/python-faq#what-constraints-exist-when-developing-applications-on-heroku - -Deprecations -++++++++++++ - -`run_gunicorn`, `gunicorn_django` and `gunicorn_paster` are now -completely deprecated and will be removed in the next release. Use the -`gunicorn` command instead. - - -Changes -------- - -core -++++ - -- add aiohttp worker named `gaiohttp` using asyncio. Full async worker - on python 3. -- fix HTTP-violating excess whitespace in write_error output -- fix: try to log what happened in the worker after a timeout, add a - `worker_abort` hook on SIGABRT signal. -- fix: save listener socket name in workers so we can handle buffered - keep-alive requests after the listener has closed. -- add on_exit hook called just before exiting gunicorn. -- add support for python 3.4 -- fix: do not swallow unexpected errors when reaping -- fix: remove incompatible SSL option with python 2.6 -- add new async gthread worker and `--threads` options allows to set multiple - threads to listen on connection -- deprecate `gunicorn_django` and `gunicorn_paster` -- switch QUIT and TERM signal -- reap workers in SIGCHLD handler -- add universal wheel support -- use `email.utils.formatdate` in gunicorn.util.http_date -- deprecate the `--debug` option -- fix: log exceptions that occur after response start … -- allows loading of applications from `.pyc` files (#693) -- fix: issue #691, raw_env config file parsing -- use a dynamic timeout to wait for the optimal time. (Reduce power - usage) -- fix python3 support when notifying the arbiter -- add: honor $WEB_CONCURRENCY environment variable. Useful for heroku - setups. -- add: include tz offset in access log -- add: include access logs in the syslog handler. -- add --reload option for code reloading -- add the capability to load `gunicorn.base.Application` without the loading of - the arguments of the command line. It allows you to :ref:`embed gunicorn in - your own application `. -- improve: set wsgi.multithread to True for async workers -- fix logging: make sure to redirect wsgi.errors when needed -- add: syslog logging can now be done to a unix socket -- fix logging: don't try to redirect stdout/stderr to the logfile. -- fix logging: don't propagate log -- improve logging: file option can be overridden by the gunicorn options - `--error-logfile` and `--access-logfile` if they are given. -- fix: don't override SERVER_* by the Host header -- fix: handle_error -- add more option to configure SSL -- fix: sendfile with SSL -- add: worker_int callback (to react on SIGTERM) -- fix: don't depend on entry point for internal classes, now absolute - modules path can be given. -- fix: Error messages are now encoded in latin1 -- fix: request line length check -- improvement: proxy_allow_ips: Allow proxy protocol if "*" specified -- fix: run worker's `setup` method before setting num_workers -- fix: FileWrapper inherit from `object` now -- fix: Error messages are now encoded in latin1 -- fix: don't spam the console on SIGWINCH. -- fix: logging -don't stringify T and D logging atoms (#621) -- add support for the latest django version -- deprecate `run_gunicorn` django option -- fix: sys imported twice - - -gevent worker -+++++++++++++ - -- fix: make sure to stop all listeners -- fix: monkey patching is now done in the worker -- fix: "global name 'hub' is not defined" -- fix: reinit `hub` on old versions of gevent -- support gevent 1.0 -- fix: add subprocess in monkey patching -- fix: add support for multiple listener - - -eventlet worker -+++++++++++++++ - -- fix: merge duplicate EventletWorker.init_process method (fixes #657) -- fix: missing errno import for eventlet sendfile patch -- fix: add support for multiple listener - - -tornado worker -++++++++++++++ - -- add graceful stop support diff --git a/docs/source/2015-news.rst b/docs/source/2015-news.rst deleted file mode 100644 index 61ea225b..00000000 --- a/docs/source/2015-news.rst +++ /dev/null @@ -1,219 +0,0 @@ -================ -Changelog - 2015 -================ - -.. note:: - - Please see :doc:`news` for the latest changes. - -19.4.3 / 2015/12/30 -=================== - -- fix: don't check if a file is writable using os.stat with SELINUX (:issue:`1171`) - -19.4.2 / 2015/12/29 -=================== - -Core -++++ - -- improvement: handle HaltServer in manage_workers (:issue:`1095`) -- fix: Do not rely on sendfile sending requested count (:issue:`1155`) -- fix: claridy --no-sendfile default (:issue:`1156`) -- fix: LoggingCatch sendfile failure from no file descriptor (:issue:`1160`) - -Logging -+++++++ - -- fix: Always send access log to syslog if syslog is on -- fix: check auth before trying to own a file (:issue:`1157`) - - -Documentation -+++++++++++++ - -- fix: Fix Slowloris broken link. (:issue:`1142`) -- Tweak markup in faq.rst - -Testing -+++++++ - -- fix: gaiohttp test (:issue:`1164`) - -19.4.1 / 2015/11/25 -=================== - -- fix tornado worker (:issue:`1154`) - -19.4.0 / 2015/11/20 -=================== - -Core -++++ - -- fix: make sure that a user is able to access to the logs after dropping a - privilege (:issue:`1116`) -- improvement: inherit the `Exception` class where it needs to be (:issue:`997`) -- fix: make sure headers are always encoded as latin1 RFC 2616 (:issue:`1102`) -- improvement: reduce arbiter noise (:issue:`1078`) -- fix: don't close the unix socket when the worker exit (:issue:`1088`) -- improvement: Make last logged worker count an explicit instance var (:issue:`1078`) -- improvement: prefix config file with its type (:issue:`836`) -- improvement: pidfile handing (:issue:`1042`) -- fix: catch OSError as well as ValueError on race condition (:issue:`1052`) -- improve support of ipv6 by backporting urlparse.urlsplit from Python 2.7 to - Python 2.6. -- fix: raise InvalidRequestLine when the line contains malicious data - (:issue:`1023`) -- fix: fix argument to disable sendfile -- fix: add gthread to the list of supported workers (:issue:`1011`) -- improvement: retry socket binding up to five times upon EADDRNOTAVAIL - (:issue:`1004`) -- **breaking change**: only honor headers that can be encoded in ascii to comply to - the RFC 7230 (See :issue:`1151`). - -Logging -+++++++ - -- add new parameters to access log (:issue:`1132`) -- fix: make sure that files handles are correctly reopened on HUP - (:issue:`627`) -- include request URL in error message (:issue:`1071`) -- get username in access logs (:issue:`1069`) -- fix statsd logging support on Python 3 (:issue:`1010`) - -Testing -+++++++ - -- use last version of mock. -- many fixes in Travis CI support -- miscellaneous improvements in tests - -Thread worker -+++++++++++++ - -- fix: Fix self.nr usage in ThreadedWorker so that auto restart works as - expected (:issue:`1031`) - -Gevent worker -+++++++++++++ - -- fix quit signal handling (:issue:`1128`) -- add support for Python 3 (:issue:`1066`) -- fix: make graceful shutdown thread-safe (:issue:`1032`) - -Tornado worker -++++++++++++++ - -- fix ssl options (:issue:`1146`, :issue:`1135`) -- don't check timeout when stopping gracefully (:issue:`1106`) - -AIOHttp worker -++++++++++++++ - -- add SSL support (:issue:`1105`) - -Documentation -+++++++++++++ - -- fix link to proc name setting (:issue:`1144`) -- fix worker class documentation (:issue:`1141`, :issue:`1104`) -- clarify graceful timeout documentation (:issue:`1137`) -- don't duplicate NGINX config files examples (:issue:`1050`, :issue:`1048`) -- add `web.py` framework example (:issue:`1117`) -- update Debian/Ubuntu installations instructions (:issue:`1112`) -- clarify `pythonpath` setting description (:issue:`1080`) -- tweak some example for python3 -- clarify `sendfile` documentation -- miscellaneous typos in source code comments (thanks!) -- clarify why REMOTE_ADD may not be the user's IP address (:issue:`1037`) - - -Misc -++++ - -- fix: reloader should survive SyntaxError (:issue:`994`) -- fix: expose the reloader class to the worker. - - - -19.3.0 / 2015/03/06 -=================== - -Core -++++ - -- fix: :issue:`978` make sure a listener is inheritable -- add `check_config` class method to workers -- fix: :issue:`983` fix select timeout in sync worker with multiple - connections -- allows workers to access to the reloader. close :issue:`984` -- raise TypeError instead of AssertionError - -Logging -+++++++ - -- make Logger.loglevel a class attribute - -Documentation -+++++++++++++ - -- fix: :issue:`988` fix syntax errors in examples/gunicorn_rc - - -19.2.1 / 2015/02/4 -================== - -Logging -+++++++ - -- expose loglevel in the Logger class - -AsyncIO worker (gaiohttp) -+++++++++++++++++++++++++ - -- fix :issue:`977` fix initial crash - -Documentation -+++++++++++++ - -- document security mailing-list in the contributing page. - -19.2 / 2015/01/30 -================= - -Core -++++ - -- optimize the sync workers when listening on a single interface -- add `--sendfile` settings to enable/disable sendfile. fix :issue:`856` . -- add the selectors module to the code base. :issue:`886` -- add `--max-requests-jitter` setting to set the maximum jitter to add to the - max-requests setting. -- fix :issue:`899` propagate proxy_protocol_info to keep-alive requests -- fix :issue:`863` worker timeout: dynamic timeout has been removed -- fix: Avoid world writable file - -Logging -+++++++ - -- fix :issue:`941` set logconfig default to paster more trivially -- add statsd-prefix config setting: set the prefix to use when emitting statsd - metrics -- :issue:`832` log to console by default - -Thread Worker -+++++++++++++ - -- fix :issue:`908` make sure the worker can continue to accept requests - -Eventlet Worker -+++++++++++++++ - -- fix :issue:`867` Fix eventlet shutdown to actively shut down the workers. - -Documentation -+++++++++++++ - -Many improvements and fixes have been done, see the detailed changelog for -more information. diff --git a/docs/source/2016-news.rst b/docs/source/2016-news.rst deleted file mode 100644 index b7a4e66b..00000000 --- a/docs/source/2016-news.rst +++ /dev/null @@ -1,91 +0,0 @@ -================ -Changelog - 2016 -================ - -.. note:: - - Please see :doc:`news` for the latest changes - -19.6.0 / 2016/05/21 -=================== - -Core & Logging -++++++++++++++ - -- improvement of the binary upgrade behaviour using USR2: remove file locking (:issue:`1270`) -- add the ``--capture-output`` setting to capture stdout/stderr tot the log - file (:issue:`1271`) -- Allow disabling ``sendfile()`` via the ``SENDFILE`` environment variable - (:issue:`1252`) -- fix reload under pycharm (:issue:`1129`) - -Workers -+++++++ - -- fix: make sure to remove the signal from the worker pipe (:issue:`1269`) -- fix: **gthread** worker, handle removed socket in the select loop - (:issue:`1258`) - -19.5.0 / 2016/05/10 -=================== - -Core -++++ - -- fix: Ensure response to HEAD request won't have message body -- fix: lock domain socket and remove on last arbiter exit (:issue:`1220`) -- improvement: use EnvironmentError instead of socket.error (:issue:`939`) -- add: new ``FORWARDED_ALLOW_IPS`` environment variable (:issue:`1205`) -- fix: infinite recursion when destroying sockets (:issue:`1219`) -- fix: close sockets on shutdown (:issue:`922`) -- fix: clean up sys.exc_info calls to drop circular refs (:issue:`1228`) -- fix: do post_worker_init after load_wsgi (:issue:`1248`) - -Workers -+++++++ - -- fix access logging in gaiohttp worker (:issue:`1193`) -- eventlet: handle QUIT in a new coroutine (:issue:`1217`) -- gevent: remove obsolete exception clauses in run (:issue:`1218`) -- tornado: fix extra "Server" response header (:issue:`1246`) -- fix: unblock the wait loop under python 3.5 in sync worker (:issue:`1256`) - -Logging -+++++++ - -- fix: log message for listener reloading (:issue:`1181`) -- Let logging module handle traceback printing (:issue:`1201`) -- improvement: Allow configuring logger_class with statsd_host (:issue:`1188`) -- fix: traceback formatting (:issue:`1235`) -- fix: print error logs on stderr and access logs on stdout (:issue:`1184`) - - -Documentation -+++++++++++++ - -- Simplify installation instructions in gunicorn.org (:issue:`1072`) -- Fix URL and default worker type in example_config (:issue:`1209`) -- update django doc url to 1.8 lts (:issue:`1213`) -- fix: miscellaneous wording corrections (:issue:`1216`) -- Add PSF License Agreement of selectors.py to NOTICE (:issue: `1226`) -- document LOGGING overriding (:issue:`1051`) -- put a note that error logs are only errors from Gunicorn (:issue:`1124`) -- add a note about the requirements of the threads workers under python 2.x (:issue:`1200`) -- add access_log_format to config example (:issue:`1251`) - -Tests -+++++ - -- Use more pytest.raises() in test_http.py - - -19.4.5 / 2016/01/05 -=================== - -- fix: NameError fileno in gunicorn.http.wsgi (:issue:`1178`) - -19.4.4 / 2016/01/04 -=================== - -- fix: check if a fileobject can be used with sendfile(2) (:issue:`1174`) -- doc: be more descriptive in errorlog option (:issue:`1173`) diff --git a/docs/source/2017-news.rst b/docs/source/2017-news.rst deleted file mode 100644 index 0fb201e6..00000000 --- a/docs/source/2017-news.rst +++ /dev/null @@ -1,46 +0,0 @@ -================ -Changelog - 2017 -================ - -.. note:: - - Please see :doc:`news` for the latest changes - -19.7.1 / 2017/03/21 -=================== - -- fix: continue if SO_REUSEPORT seems to be available but fails (:issue:`1480`) -- fix: support non-decimal values for the umask command line option (:issue:`1325`) - -19.7.0 / 2017/03/01 -=================== - -- The previously deprecated ``gunicorn_django`` command has been removed. - Use the :ref:`gunicorn-cmd` command-line interface instead. -- The previously deprecated ``django_settings`` setting has been removed. - Use the :ref:`raw-env` setting instead. -- The default value of :ref:`ssl-version` has been changed from - ``ssl.PROTOCOL_TLSv1`` to ``ssl.PROTOCOL_SSLv23``. -- fix: initialize the group access list when initgroups is set (:issue:`1297`) -- add environment variables to gunicorn access log format (:issue:`1291`) -- add --paste-global-conf option (:issue:`1304`) -- fix: print access logs to STDOUT (:issue:`1184`) -- remove upper limit on max header size config (:issue:`1313`) -- fix: print original exception on AppImportError (:issue:`1334`) -- use SO_REUSEPORT if available (:issue:`1344`) -- `fix leak `_ of duplicate file descriptor for bound sockets. -- add --reload-engine option, support inotify and other backends (:issue:`1368`, :issue:`1459`) -- fix: reject request with invalid HTTP versions -- add ``child_exit`` callback (:issue:`1394`) -- add support for eventlets _AlreadyHandled object (:issue:`1406`) -- format boot tracebacks properly with reloader (:issue:`1408`) -- refactor socket activation and fd inheritance for better support of SystemD (:issue:`1310`) -- fix: o fds are given by default in gunicorn (:issue:`1423`) -- add ability to pass settings to GUNICORN_CMD_ARGS environment variable which helps in container world (:issue:`1385`) -- fix: catch access denied to pid file (:issue:`1091`) -- many additions and improvements to the documentation - -Breaking Change -+++++++++++++++ - -- **Python 2.6.0** is the last supported version diff --git a/docs/source/2018-news.rst b/docs/source/2018-news.rst deleted file mode 100644 index 3b412cf5..00000000 --- a/docs/source/2018-news.rst +++ /dev/null @@ -1,68 +0,0 @@ -================ -Changelog - 2018 -================ - -.. note:: - - Please see :doc:`news` for the latest changes - -19.9.0 / 2018/07/03 -=================== - -- fix: address a regression that prevented syslog support from working - (:issue:`1668`, :pr:`1773`) -- fix: correctly set `REMOTE_ADDR` on versions of Python 3 affected by - `Python Issue 30205 `_ - (:issue:`1755`, :pr:`1796`) -- fix: show zero response length correctly in access log (:pr:`1787`) -- fix: prevent raising :exc:`AttributeError` when ``--reload`` is not passed - in case of a :exc:`SyntaxError` raised from the WSGI application. - (:issue:`1805`, :pr:`1806`) -- The internal module ``gunicorn.workers.async`` was renamed to ``gunicorn.workers.base_async`` - since ``async`` is now a reserved word in Python 3.7. - (:pr:`1527`) - -19.8.1 / 2018/04/30 -=================== - -- fix: secure scheme headers when bound to a unix socket - (:issue:`1766`, :pr:`1767`) - -19.8.0 / 2018/04/28 -=================== - -- Eventlet 0.21.0 support (:issue:`1584`) -- Tornado 5 support (:issue:`1728`, :pr:`1752`) -- support watching additional files with ``--reload-extra-file`` - (:pr:`1527`) -- support configuring logging with a dictionary with ``--logging-config-dict`` - (:issue:`1087`, :pr:`1110`, :pr:`1602`) -- add support for the ``--config`` flag in the ``GUNICORN_CMD_ARGS`` environment - variable (:issue:`1576`, :pr:`1581`) -- disable ``SO_REUSEPORT`` by default and add the ``--reuse-port`` setting - (:issue:`1553`, :issue:`1603`, :pr:`1669`) -- fix: installing `inotify` on MacOS no longer breaks the reloader - (:issue:`1540`, :pr:`1541`) -- fix: do not throw ``TypeError`` when ``SO_REUSEPORT`` is not available - (:issue:`1501`, :pr:`1491`) -- fix: properly decode HTTP paths containing certain non-ASCII characters - (:issue:`1577`, :pr:`1578`) -- fix: remove whitespace when logging header values under gevent (:pr:`1607`) -- fix: close unlinked temporary files (:issue:`1327`, :pr:`1428`) -- fix: parse ``--umask=0`` correctly (:issue:`1622`, :pr:`1632`) -- fix: allow loading applications using relative file paths - (:issue:`1349`, :pr:`1481`) -- fix: force blocking mode on the gevent sockets (:issue:`880`, :pr:`1616`) -- fix: preserve leading `/` in request path (:issue:`1512`, :pr:`1511`) -- fix: forbid contradictory secure scheme headers -- fix: handle malformed basic authentication headers in access log - (:issue:`1683`, :pr:`1684`) -- fix: defer handling of ``USR1`` signal to a new greenlet under gevent - (:issue:`1645`, :pr:`1651`) -- fix: the threaded worker would sometimes close the wrong keep-alive - connection under Python 2 (:issue:`1698`, :pr:`1699`) -- fix: re-open log files on ``USR1`` signal using ``handler._open`` to - support subclasses of ``FileHandler`` (:issue:`1739`, :pr:`1742`) -- deprecation: the ``gaiohttp`` worker is deprecated, see the - :ref:`worker-class` documentation for more information - (:issue:`1338`, :pr:`1418`, :pr:`1569`) \ No newline at end of file diff --git a/docs/source/2019-news.rst b/docs/source/2019-news.rst deleted file mode 100644 index 28b69216..00000000 --- a/docs/source/2019-news.rst +++ /dev/null @@ -1,121 +0,0 @@ -================ -Changelog - 2019 -================ - -.. note:: - - Please see :doc:`news` for the latest changes - -20.0.4 / 2019/11/26 -=================== - -- fix binding a socket using the file descriptor -- remove support for the `bdist_rpm` build - -20.0.3 / 2019/11/24 -=================== - -- fixed load of a config file without a Python extension -- fixed `socketfromfd.fromfd` when defaults are not set - -.. note:: we now warn when we load a config file without Python Extension - -20.0.2 / 2019/11/23 -=================== - -- fix changelog - -20.0.1 / 2019/11/23 -=================== - -- fixed the way the config module is loaded. `__file__` is now available -- fixed `wsgi.input_terminated`. It is always true. -- use the highest protocol version of openssl by default -- only support Python >= 3.5 -- added `__repr__` method to `Config` instance -- fixed support of AIX platform and musl libc in `socketfromfd.fromfd` function -- fixed support of applications loaded from a factory function -- fixed chunked encoding support to prevent any `request smuggling `_ -- Capture os.sendfile before patching in gevent and eventlet workers. - fix `RecursionError`. -- removed locking in reloader when adding new files -- load the WSGI application before the loader to pick up all files - -.. note:: this release add official support for applications loaded from a factory function - as documented in Flask and other places. - - -19.10.0 / 2019/11/23 -==================== - -- unblock select loop during reload of a sync worker -- security fix: http desync attack -- handle `wsgi.input_terminated` -- added support for str and bytes in unix socket addresses -- fixed `max_requests` setting -- headers values are now encoded as LATN1, not ASCII -- fixed `InotifyReloadeder`: handle `module.__file__` is None -- fixed compatibility with tornado 6 -- fixed root logging -- Prevent removalof unix sockets from `reuse_port` -- Clear tornado ioloop before os.fork -- Miscellaneous fixes and improvement for linting using Pylint - -20.0 / 2019/10/30 -================= - -- Fixed `fdopen` `RuntimeWarning` in Python 3.8 -- Added check and exception for str type on value in Response process_headers method. -- Ensure WSGI header value is string before conducting regex search on it. -- Added pypy3 to list of tested environments -- Grouped `StopIteration` and `KeyboardInterrupt` exceptions with same body together in Arbiter.run() -- Added `setproctitle` module to `extras_require` in setup.py -- Avoid unnecessary chown of temporary files -- Logging: Handle auth type case insensitively -- Removed `util.import_module` -- Removed fallback for `types.SimpleNamespace` in tests utils -- Use `SourceFileLoader` instead instead of `execfile_` -- Use `importlib` instead of `__import__` and eval` -- Fixed eventlet patching -- Added optional `datadog `_ tags for statsd metrics -- Header values now are encoded using latin-1, not ascii. -- Rewritten `parse_address` util added test -- Removed redundant super() arguments -- Simplify `futures` import in gthread module -- Fixed worker_connections` setting to also affects the Gthread worker type -- Fixed setting max_requests -- Bump minimum Eventlet and Gevent versions to 0.24 and 1.4 -- Use Python default SSL cipher list by default -- handle `wsgi.input_terminated` extension -- Simplify Paste Deployment documentation -- Fix root logging: root and logger are same level. -- Fixed typo in ssl_version documentation -- Documented systemd deployment unit examples -- Added systemd sd_notify support -- Fixed typo in gthread.py -- Added `tornado `_ 5 and 6 support -- Declare our setuptools dependency -- Added support to `--bind` to open file descriptors -- Document how to serve WSGI app modules from Gunicorn -- Provide guidance on X-Forwarded-For access log in documentation -- Add support for named constants in the `--ssl-version` flag -- Clarify log format usage of header & environment in documentation -- Fixed systemd documentation to properly setup gunicorn unix socket -- Prevent removal unix socket for reuse_port -- Fix `ResourceWarning` when reading a Python config module -- Remove unnecessary call to dict keys method -- Support str and bytes for UNIX socket addresses -- fixed `InotifyReloadeder`: handle `module.__file__` is None -- `/dev/shm` as a convenient alternative to making your own tmpfs mount in fchmod FAQ -- fix examples to work on python3 -- Fix typo in `--max-requests` documentation -- Clear tornado ioloop before os.fork -- Miscellaneous fixes and improvement for linting using Pylint - -Breaking Change -+++++++++++++++ - -- Removed gaiohttp worker -- Drop support for Python 2.x -- Drop support for EOL Python 3.2 and 3.3 -- Drop support for Paste Deploy server blocks diff --git a/docs/source/2020-news.rst b/docs/source/2020-news.rst deleted file mode 100644 index 1d91ef7e..00000000 --- a/docs/source/2020-news.rst +++ /dev/null @@ -1,7 +0,0 @@ -================ -Changelog - 2020 -================ - -.. note:: - - Please see :doc:`news` for the latest changes diff --git a/docs/source/2021-news.rst b/docs/source/2021-news.rst deleted file mode 100644 index 3057600d..00000000 --- a/docs/source/2021-news.rst +++ /dev/null @@ -1,54 +0,0 @@ -================ -Changelog - 2021 -================ - -.. note:: - - Please see :doc:`news` for the latest changes - -20.1.0 - 2021-02-12 -=================== - -- document WEB_CONCURRENCY is set by, at least, Heroku -- capture peername from accept: Avoid calls to getpeername by capturing the peer name returned by - accept -- log a warning when a worker was terminated due to a signal -- fix tornado usage with latest versions of Django -- add support for python -m gunicorn -- fix systemd socket activation example -- allows to set wsgi application in config file using `wsgi_app` -- document `--timeout = 0` -- always close a connection when the number of requests exceeds the max requests -- Disable keepalive during graceful shutdown -- kill tasks in the gthread workers during upgrade -- fix latency in gevent worker when accepting new requests -- fix file watcher: handle errors when new worker reboot and ensure the list of files is kept -- document the default name and path of the configuration file -- document how variable impact configuration -- document the `$PORT` environment variable -- added milliseconds option to request_time in access_log -- added PIP requirements to be used for example -- remove version from the Server header -- fix sendfile: use `socket.sendfile` instead of `os.sendfile` -- reloader: use absolute path to prevent empty to prevent0 `InotifyError` when a file - is added to the working directory -- Add --print-config option to print the resolved settings at startup. -- remove the `--log-dict-config` CLI flag because it never had a working format - (the `logconfig_dict` setting in configuration files continues to work) - - -** Breaking changes ** - -- minimum version is Python 3.5 -- remove version from the Server header - -** Documentation ** - - - -** Others ** - -- miscellaneous changes in the code base to be a better citizen with Python 3 -- remove dead code -- fix documentation generation - diff --git a/docs/source/2023-news.rst b/docs/source/2023-news.rst deleted file mode 100644 index b685d80d..00000000 --- a/docs/source/2023-news.rst +++ /dev/null @@ -1,39 +0,0 @@ -================ -Changelog - 2023 -================ - -21.2.0 - 2023-07-19 -=================== - -- fix thread worker: revert change considering connection as idle . - -*** NOTE *** - -This is fixing the bad file description error. - -21.1.0 - 2023-07-18 -=================== - -- fix thread worker: fix socket removal from the queue - -21.0.1 - 2023-07-17 -=================== - -- fix documentation build - -21.0.0 - 2023-07-17 -=================== - -- support python 3.11 -- fix gevent and eventlet workers -- fix threads support (gththread): improve performance and unblock requests -- SSL: now use SSLContext object -- HTTP parser: miscellaneous fixes -- remove unnecessary setuid calls -- fix testing -- improve logging -- miscellaneous fixes to core engine - -*** RELEASE NOTE *** - -We made this release major to start our new release cycle. More info will be provided on our discussion forum. diff --git a/docs/source/2024-news.rst b/docs/source/2024-news.rst deleted file mode 100644 index 376699b4..00000000 --- a/docs/source/2024-news.rst +++ /dev/null @@ -1,61 +0,0 @@ -================ -Changelog - 2024 -================ - -23.0.0 - 2024-08-10 -=================== - -- minor docs fixes (:pr:`3217`, :pr:`3089`, :pr:`3167`) -- worker_class parameter accepts a class (:pr:`3079`) -- fix deadlock if request terminated during chunked parsing (:pr:`2688`) -- permit receiving Transfer-Encodings: compress, deflate, gzip (:pr:`3261`) -- permit Transfer-Encoding headers specifying multiple encodings. note: no parameters, still (:pr:`3261`) -- sdist generation now explicitly excludes sphinx build folder (:pr:`3257`) -- decode bytes-typed status (as can be passed by gevent) as utf-8 instead of raising `TypeError` (:pr:`2336`) -- raise correct Exception when encounting invalid chunked requests (:pr:`3258`) -- the SCRIPT_NAME and PATH_INFO headers, when received from allowed forwarders, are no longer restricted for containing an underscore (:pr:`3192`) -- include IPv6 loopback address ``[::1]`` in default for :ref:`forwarded-allow-ips` and :ref:`proxy-allow-ips` (:pr:`3192`) - -** NOTE ** - -- The SCRIPT_NAME change mitigates a regression that appeared first in the 22.0.0 release -- Review your :ref:`forwarded-allow-ips` setting if you are still not seeing the SCRIPT_NAME transmitted -- Review your :ref:`forwarder-headers` setting if you are missing headers after upgrading from a version prior to 22.0.0 - -** Breaking changes ** - -- refuse requests where the uri field is empty (:pr:`3255`) -- refuse requests with invalid CR/LR/NUL in heade field values (:pr:`3253`) -- remove temporary ``--tolerate-dangerous-framing`` switch from 22.0 (:pr:`3260`) -- If any of the breaking changes affect you, be aware that now refused requests can post a security problem, especially so in setups involving request pipe-lining and/or proxies. - -22.0.0 - 2024-04-17 -=================== - -- use `utime` to notify workers liveness -- migrate setup to pyproject.toml -- fix numerous security vulnerabilities in HTTP parser (closing some request smuggling vectors) -- parsing additional requests is no longer attempted past unsupported request framing -- on HTTP versions < 1.1 support for chunked transfer is refused (only used in exploits) -- requests conflicting configured or passed SCRIPT_NAME now produce a verbose error -- Trailer fields are no longer inspected for headers indicating secure scheme -- support Python 3.12 - -** Breaking changes ** - -- minimum version is Python 3.7 -- the limitations on valid characters in the HTTP method have been bounded to Internet Standards -- requests specifying unsupported transfer coding (order) are refused by default (rare) -- HTTP methods are no longer casefolded by default (IANA method registry contains none affected) -- HTTP methods containing the number sign (#) are no longer accepted by default (rare) -- HTTP versions < 1.0 or >= 2.0 are no longer accepted by default (rare, only HTTP/1.1 is supported) -- HTTP versions consisting of multiple digits or containing a prefix/suffix are no longer accepted -- HTTP header field names Gunicorn cannot safely map to variables are silently dropped, as in other software -- HTTP headers with empty field name are refused by default (no legitimate use cases, used in exploits) -- requests with both Transfer-Encoding and Content-Length are refused by default (such a message might indicate an attempt to perform request smuggling) -- empty transfer codings are no longer permitted (reportedly seen with really old & broken proxies) - - -** SECURITY ** - -- fix CVE-2024-1135 diff --git a/docs/source/_static/gunicorn.png b/docs/source/_static/gunicorn.png deleted file mode 100644 index a3a78e0e..00000000 Binary files a/docs/source/_static/gunicorn.png and /dev/null differ diff --git a/docs/source/community.rst b/docs/source/community.rst deleted file mode 100644 index 5bfe51c0..00000000 --- a/docs/source/community.rst +++ /dev/null @@ -1,37 +0,0 @@ -========= -Community -========= - -Use these channels to communicate about the project: - -Project Management & Discussions -================================ - -Project maintenance guidelines are available on the `wiki `_ - -GitHub issues are used for 3 different purposes: - - * `Bug tracker `_ : To check for latest bugs. Tip: See existing issues before opening a new one! - * `Forum `_ : Stackoverflow-style questions about Gunicorn usage. - * `Other Issues `_ : Discussion of Gunicorn development, new features - and project management. - -IRC -=== - -The Gunicorn channel is on the `Libera Chat `_ IRC -network. You can chat with others on `#gunicorn channel -`_ - -Issue Tracking -============== - -Bug reports, enhancement requests and tasks generally go in the `Github -issue tracker `_ - -Security Issues -=============== - -The security mailing list is a place to report security issues. Only -developers are subscribed to it. To post a message to the list use the address -to `security@gunicorn.org `_ diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index f000c2db..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,72 +0,0 @@ -# -# Gunicorn documentation build configuration file -# - -import os -import sys -import time - -DOCS_DIR = os.path.abspath(os.path.dirname(__file__)) - -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -# for gunicorn_ext.py -sys.path.append(os.path.join(DOCS_DIR, os.pardir)) -sys.path.insert(0, os.path.join(DOCS_DIR, os.pardir, os.pardir)) - -extensions = ['gunicorn_ext'] -templates_path = ['_templates'] -source_suffix = '.rst' -master_doc = 'index' - -# General information about the project. -project = 'Gunicorn' -copyright = '2009-%s, Benoit Chesneau' % time.strftime('%Y') -# gunicorn version -import gunicorn -release = version = gunicorn.__version__ - -exclude_patterns = [] -pygments_style = 'sphinx' - - -# -- Options for HTML output --------------------------------------------------- - -if not on_rtd: # only import and set the theme if we're building docs locally - try: - import sphinx_rtd_theme - except ImportError: - html_theme = 'default' - else: - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -else: - html_theme = 'default' - -html_static_path = ['_static'] -htmlhelp_basename = 'Gunicorndoc' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { - -} - -latex_documents = [ - ('index', 'Gunicorn.tex', 'Gunicorn Documentation', - 'Benoit Chesneau', 'manual'), -] - - -# -- Options for manual page output -------------------------------------------- -man_pages = [ - ('index', 'gunicorn', 'Gunicorn Documentation', - ['Benoit Chesneau'], 1) -] - -texinfo_documents = [ - ('index', 'Gunicorn', 'Gunicorn Documentation', - 'Benoit Chesneau', 'Gunicorn', 'One line description of project.', - 'Miscellaneous'), -] diff --git a/docs/source/configure.rst b/docs/source/configure.rst deleted file mode 100644 index dc9ba62d..00000000 --- a/docs/source/configure.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _configuration: - -====================== -Configuration Overview -====================== - -Gunicorn reads configuration information from five places. - -Gunicorn first reads environment variables for some configuration -:ref:`settings `. - -Gunicorn then reads configuration from a framework specific configuration -file. Currently this only affects Paster applications. - -The third source of configuration information is an optional configuration file -``gunicorn.conf.py`` searched in the current working directory or specified -using a command line argument. Anything specified in this configuration file -will override any framework specific settings. - -The fourth place of configuration information are command line arguments -stored in an environment variable named ``GUNICORN_CMD_ARGS``. - -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. - -When a configuration file is specified in the command line arguments and in the -``GUNICORN_CMD_ARGS`` environment variable, only the configuration -file specified on the command line is used. - -Once again, in order of least to most authoritative: - 1. Environment Variables - 2. Framework Settings - 3. Configuration File - 4. ``GUNICORN_CMD_ARGS`` - 5. Command Line - - -.. note:: - - To print your resolved configuration when using the command line or the - configuration file you can run the following command:: - - $ gunicorn --print-config APP_MODULE - - To check your resolved configuration when using the command line or the - configuration file you can run the following command:: - - $ gunicorn --check-config APP_MODULE - - It also allows you to know if your application can be launched. - - -Command Line -============ - -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:: - - $ gunicorn -h - -There is also a ``--version`` flag available to the command line scripts that -isn't mentioned in the list of :ref:`settings `. - -.. _configuration_file: - -Configuration File -================== - -The configuration file should be a valid Python source file with a **python -extension** (e.g. `gunicorn.conf.py`). It only needs to be readable from the -file system. More specifically, it does not have to be on the module path -(sys.path, PYTHONPATH). Any Python is valid. Just consider that this will be -run every time you start Gunicorn (including when you signal Gunicorn to reload). - -To set a parameter, just assign to it. There's no special syntax. The values -you provide will be used for the configuration values. - -For instance:: - - import multiprocessing - - bind = "127.0.0.1:8000" - workers = multiprocessing.cpu_count() * 2 + 1 - -All the settings are mentioned in the :ref:`settings ` list. - - -Framework Settings -================== - -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 issue_ to -let us know. - -.. _issue: https://github.com/benoitc/gunicorn/issues - -Paster Applications -------------------- - -In your INI file, you can specify to use Gunicorn as the server like such: - -.. code-block:: ini - - [server:main] - use = egg:gunicorn#main - host = 192.168.0.1 - port = 80 - workers = 2 - proc_name = brim - -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. diff --git a/docs/source/custom.rst b/docs/source/custom.rst deleted file mode 100644 index 90f74209..00000000 --- a/docs/source/custom.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. _custom: - -================== -Custom Application -================== - -.. versionadded:: 19.0 - -Sometimes, you want to integrate Gunicorn with your WSGI application. In this -case, you can inherit from :class:`gunicorn.app.base.BaseApplication`. - -Here is a small example where we create a very small WSGI app and load it with -a custom Application: - -.. literalinclude:: ../../examples/standalone_app.py - :start-after: # See the NOTICE for more information - :lines: 2- - -Using server hooks ------------------- - -If you wish to include server hooks in your custom application, you can specify a function in the config options. Here is an example with the `pre_fork` hook: - -.. code-block:: python - - def pre_fork(server, worker): - print(f"pre-fork server {server} worker {worker}", file=sys.stderr) - - # ... - if __name__ == '__main__': - options = { - 'bind': '%s:%s' % ('127.0.0.1', '8080'), - 'workers': number_of_workers(), - 'pre_fork': pre_fork, - } - - -Direct Usage of Existing WSGI Apps ----------------------------------- - -If necessary, you can run Gunicorn straight from Python, allowing you to -specify a WSGI-compatible application at runtime. This can be handy for -rolling deploys or in the case of using PEX files to deploy your application, -as the app and Gunicorn can be bundled in the same PEX file. Gunicorn has -this functionality built-in as a first class citizen known as -:class:`gunicorn.app.wsgiapp`. This can be used to run WSGI-compatible app -instances such as those produced by Flask or Django. Assuming your WSGI API -package is *exampleapi*, and your application instance is *app*, this is all -you need to get going:: - - gunicorn.app.wsgiapp exampleapi:app - -This command will work with any Gunicorn CLI parameters or a config file - just -pass them along as if you're directly giving them to Gunicorn: - -.. code-block:: bash - - # Custom parameters - $ python gunicorn.app.wsgiapp exampleapi:app --bind=0.0.0.0:8081 --workers=4 - # Using a config file - $ python gunicorn.app.wsgiapp exampleapi:app -c config.py - -Note for those using PEX: use ``-c gunicorn`` as your entry at build -time, and your compiled app should work with the entry point passed to it at -run time. - -.. code-block:: bash - - # Generic pex build command via bash from root of exampleapi project - $ pex . -v -c gunicorn -o compiledapp.pex - # Running it - ./compiledapp.pex exampleapi:app -c gunicorn_config.py diff --git a/docs/source/deploy.rst b/docs/source/deploy.rst deleted file mode 100644 index 5f868979..00000000 --- a/docs/source/deploy.rst +++ /dev/null @@ -1,380 +0,0 @@ -================== -Deploying Gunicorn -================== - -We strongly recommend using Gunicorn behind a proxy server. - -Nginx Configuration -=================== - -Although there are many HTTP proxies available, we strongly advise that you -use Nginx_. If you choose another proxy server you need to make sure that it -buffers slow clients when you use default Gunicorn workers. Without this -buffering Gunicorn will be easily susceptible to denial-of-service attacks. -You can use Hey_ to check if your proxy is behaving properly. - -An `example configuration`_ file for fast clients with Nginx_: - -.. literalinclude:: ../../examples/nginx.conf - :language: nginx - :caption: **nginx.conf** - -If you want to be able to handle streaming request/responses or other fancy -features like Comet, Long polling, or Web sockets, you need to turn off the -proxy buffering. **When you do this** you must run with one of the async worker -classes. - -To turn off buffering, you only need to add ``proxy_buffering off;`` to your -``location`` block:: - - ... - location @proxy_to_app { - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header Host $http_host; - proxy_redirect off; - proxy_buffering off; - - proxy_pass http://app_server; - } - ... - -If you want to ignore aborted requests like health check of Load Balancer, some -of which close the connection without waiting for a response, you need to turn -on `ignoring client abort`_. - -To ignore aborted requests, you only need to add -``proxy_ignore_client_abort on;`` to your ``location`` block:: - - ... - proxy_ignore_client_abort on; - ... - -.. note:: - The default value of ``proxy_ignore_client_abort`` is ``off``. Error code - 499 may appear in Nginx log and ``Ignoring EPIPE`` may appear in Gunicorn - log if loglevel is set to ``debug``. - -It is recommended to pass protocol information to Gunicorn. Many web -frameworks use this information to generate URLs. Without this -information, the application may mistakenly generate 'http' URLs in -'https' responses, leading to mixed content warnings or broken -applications. To configure Nginx to pass an appropriate header, add -a ``proxy_set_header`` directive to your ``location`` block:: - - ... - proxy_set_header X-Forwarded-Proto $scheme; - ... - -If you are running Nginx on a different host than Gunicorn you need to tell -Gunicorn to trust the ``X-Forwarded-*`` headers sent by Nginx. By default, -Gunicorn will only trust these headers if the connection comes from localhost. -This is to prevent a malicious client from forging these headers:: - - $ gunicorn -w 3 --forwarded-allow-ips="10.170.3.217,10.170.3.220" test:app - -When the Gunicorn host is completely firewalled from the external network such -that all connections come from a trusted proxy (e.g. Heroku) this value can -be set to '*'. Using this value is **potentially dangerous** if connections to -Gunicorn may come from untrusted proxies or directly from clients since the -application may be tricked into serving SSL-only content over an insecure -connection. - -Gunicorn 19 introduced a breaking change concerning how ``REMOTE_ADDR`` is -handled. Previous to Gunicorn 19 this was set to the value of -``X-Forwarded-For`` if received from a trusted proxy. However, this was not in -compliance with :rfc:`3875` which is why the ``REMOTE_ADDR`` is now the IP -address of **the proxy** and **not the actual user**. - -To have access logs indicate **the actual user** IP when proxied, set -:ref:`access-log-format` with a format which includes ``X-Forwarded-For``. For -example, this format uses ``X-Forwarded-For`` in place of ``REMOTE_ADDR``:: - - %({x-forwarded-for}i)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" - -It is also worth noting that the ``REMOTE_ADDR`` will be completely empty if -you bind Gunicorn to a UNIX socket and not a TCP ``host:port`` tuple. - -Using Virtualenv -================ - -To serve an app from a Virtualenv_ it is generally easiest to just install -Gunicorn directly into the Virtualenv. This will create a set of Gunicorn -scripts for that Virtualenv which can be used to run applications normally. - -If you have Virtualenv installed, you should be able to do something like -this:: - - $ mkdir ~/venvs/ - $ virtualenv ~/venvs/webapp - $ source ~/venvs/webapp/bin/activate - $ pip install gunicorn - $ deactivate - -Then you just need to use one of the three Gunicorn scripts that was installed -into ``~/venvs/webapp/bin``. - -Note: You can force the installation of Gunicorn in your Virtualenv by -passing ``-I`` or ``--ignore-installed`` option to pip:: - - $ source ~/venvs/webapp/bin/activate - $ pip install -I gunicorn - -Monitoring -========== - -.. note:: - Make sure that when using either of these service monitors you do not - enable the Gunicorn's daemon mode. These monitors expect that the process - they launch will be the process they need to monitor. Daemonizing will - fork-exec which creates an unmonitored process and generally just - confuses the monitor services. - -Gaffer ------- - -Using Gafferd and gaffer -++++++++++++++++++++++++ - -Gaffer_ can be used to monitor Gunicorn. A simple configuration is:: - - [process:gunicorn] - cmd = gunicorn -w 3 test:app - cwd = /path/to/project - -Then you can easily manage Gunicorn using Gaffer_. - - -Using a Procfile -++++++++++++++++ - -Create a ``Procfile`` in your project:: - - gunicorn = gunicorn -w 3 test:app - -You can launch any other applications that should be launched at the same time. - -Then you can start your Gunicorn application using Gaffer_:: - - gaffer start - -If gafferd is launched you can also load your Procfile in it directly:: - - gaffer load - -All your applications will be then supervised by gafferd. - -Runit ------ - -A popular method for deploying Gunicorn is to have it monitored by runit_. -Here is an `example service`_ definition:: - - #!/bin/sh - - GUNICORN=/usr/local/bin/gunicorn - ROOT=/path/to/project - PID=/var/run/gunicorn.pid - - APP=main:application - - if [ -f $PID ]; then rm $PID; fi - - cd $ROOT - exec $GUNICORN -c $ROOT/gunicorn.conf.py --pid=$PID $APP - -Save this as ``/etc/sv/[app_name]/run``, and make it executable -(``chmod u+x /etc/sv/[app_name]/run``). -Then run ``ln -s /etc/sv/[app_name] /etc/service/[app_name]``. -If runit is installed, Gunicorn should start running automatically as soon -as you create the symlink. - -If it doesn't start automatically, run the script directly to troubleshoot. - -Supervisor ----------- - -Another useful tool to monitor and control Gunicorn is Supervisor_. A -`simple configuration`_ is:: - - [program:gunicorn] - command=/path/to/gunicorn main:application -c /path/to/gunicorn.conf.py - directory=/path/to/project - user=nobody - autostart=true - autorestart=true - redirect_stderr=true - -Upstart -------- - -Using Gunicorn with upstart is simple. In this example we will run the app -"myapp" from a virtualenv. All errors will go to -``/var/log/upstart/myapp.log``. - -**/etc/init/myapp.conf**:: - - description "myapp" - - start on (filesystem) - stop on runlevel [016] - - respawn - setuid nobody - setgid nogroup - chdir /path/to/app/directory - - exec /path/to/virtualenv/bin/gunicorn myapp:app - -Systemd -------- - -A tool that is starting to be common on linux systems is Systemd_. It is a -system services manager that allows for strict process management, resources -and permissions control. - -Below are configuration files and instructions for using systemd to create -a unix socket for incoming Gunicorn requests. Systemd will listen on this -socket and start gunicorn automatically in response to traffic. Later in -this section are instructions for configuring Nginx to forward web traffic -to the newly created unix socket: - -**/etc/systemd/system/gunicorn.service**:: - - [Unit] - Description=gunicorn daemon - Requires=gunicorn.socket - After=network.target - - [Service] - # gunicorn can let systemd know when it is ready - Type=notify - NotifyAccess=main - # the specific user that our service will run as - User=someuser - Group=someuser - # this user can be transiently created by systemd - # DynamicUser=true - RuntimeDirectory=gunicorn - WorkingDirectory=/home/someuser/applicationroot - ExecStart=/usr/bin/gunicorn applicationname.wsgi - ExecReload=/bin/kill -s HUP $MAINPID - KillMode=mixed - TimeoutStopSec=5 - PrivateTmp=true - # if your app does not need administrative capabilities, let systemd know - # ProtectSystem=strict - - [Install] - WantedBy=multi-user.target - -**/etc/systemd/system/gunicorn.socket**:: - - [Unit] - Description=gunicorn socket - - [Socket] - ListenStream=/run/gunicorn.sock - # Our service won't need permissions for the socket, since it - # inherits the file descriptor by socket activation. - # Only the nginx daemon will need access to the socket: - SocketUser=www-data - SocketGroup=www-data - # Once the user/group is correct, restrict the permissions: - SocketMode=0660 - - [Install] - WantedBy=sockets.target - - -Next enable and start the socket (it will autostart at boot too):: - - systemctl enable --now gunicorn.socket - - -Now let's see if the nginx daemon will be able to connect to the socket. -Running ``sudo -u www-data curl --unix-socket /run/gunicorn.sock http``, -our Gunicorn service will be automatically started and you should see some -HTML from your server in the terminal. - -.. note:: - - systemd employs cgroups to track the processes of a service, so it doesn't - need pid files. In the rare case that you need to find out the service main - pid, you can use ``systemctl show --value -p MainPID gunicorn.service``, but - if you only want to send a signal an even better option is - ``systemctl kill -s HUP gunicorn.service``. - -.. note:: - - ``www-data`` is the default nginx user in debian, other distributions use - different users (for example: ``http`` or ``nginx``). Check your distro to - know what to put for the socket user, and for the sudo command. - -You must now configure your web proxy to send traffic to the new Gunicorn -socket. Edit your ``nginx.conf`` to include the following: - -**/etc/nginx/nginx.conf**:: - - user www-data; - ... - http { - server { - listen 8000; - server_name 127.0.0.1; - location / { - proxy_pass http://unix:/run/gunicorn.sock; - } - } - } - ... - -.. note:: - - The listen and server_name used here are configured for a local machine. - In a production server you will most likely listen on port 80, - and use your URL as the server_name. - -Now make sure you enable the nginx service so it automatically starts at boot:: - - systemctl enable nginx.service - -Either reboot, or start Nginx with the following command:: - - systemctl start nginx - -Now you should be able to test Nginx with Gunicorn by visiting -http://127.0.0.1:8000/ in any web browser. Systemd is now set up. - - -Logging -======= - -Logging can be configured by using various flags detailed in the -`configuration documentation`_ or by creating a `logging configuration file`_. -Send the ``USR1`` signal to rotate logs if you are using the logrotate -utility:: - - kill -USR1 $(cat /var/run/gunicorn.pid) - -.. note:: - Overriding the ``LOGGING`` dictionary requires to set - ``disable_existing_loggers: False`` to not interfere with the Gunicorn - logging. - -.. warning:: - Gunicorn error log is here to log errors from Gunicorn, not from another - application. - -.. _Nginx: https://nginx.org/ -.. _Hey: https://github.com/rakyll/hey -.. _`example configuration`: https://github.com/benoitc/gunicorn/blob/master/examples/nginx.conf -.. _runit: http://smarden.org/runit/ -.. _`example service`: https://github.com/benoitc/gunicorn/blob/master/examples/gunicorn_rc -.. _Supervisor: http://supervisord.org/ -.. _`simple configuration`: https://github.com/benoitc/gunicorn/blob/master/examples/supervisor.conf -.. _`configuration documentation`: http://docs.gunicorn.org/en/latest/settings.html#logging -.. _`logging configuration file`: https://github.com/benoitc/gunicorn/blob/master/examples/logging.conf -.. _Virtualenv: https://pypi.python.org/pypi/virtualenv -.. _Systemd: https://www.freedesktop.org/wiki/Software/systemd/ -.. _Gaffer: https://gaffer.readthedocs.io/ -.. _`ignoring client abort`: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_ignore_client_abort diff --git a/docs/source/design.rst b/docs/source/design.rst deleted file mode 100644 index 6796e969..00000000 --- a/docs/source/design.rst +++ /dev/null @@ -1,150 +0,0 @@ - -.. _design: - -====== -Design -====== - -A brief description of the architecture of Gunicorn. - -Server Model -============ - -Gunicorn is based on the pre-fork worker model. This means that there is a -central master process that manages a set of worker processes. The master -never knows anything about individual clients. All requests and responses are -handled completely by worker processes. - -Master ------- - -The master process is a simple loop that listens for various process signals -and reacts accordingly. It manages the list of running workers by listening -for signals like TTIN, TTOU, and CHLD. TTIN and TTOU tell the master to -increase or decrease the number of running workers. CHLD indicates that a child -process has terminated, in this case the master process automatically restarts -the failed worker. - -Sync Workers ------------- - -The most basic and the default worker type is a synchronous worker class that -handles a single request at a time. This model is the simplest to reason about -as any errors will affect at most a single request. Though as we describe below -only processing a single request at a time requires some assumptions about how -applications are programmed. - -``sync`` worker does not support persistent connections - each connection is -closed after response has been sent (even if you manually add ``Keep-Alive`` -or ``Connection: keep-alive`` header in your application). - -Async Workers -------------- - -The asynchronous workers available are based on Greenlets_ (via Eventlet_ and -Gevent_). Greenlets are an implementation of cooperative multi-threading for -Python. In general, an application should be able to make use of these worker -classes with no changes. - -For full greenlet support applications might need to be adapted. -When using, e.g., Gevent_ and Psycopg_ it makes sense to ensure psycogreen_ is -installed and `setup `_. - -Other applications might not be compatible at all as they, e.g., rely on -the original unpatched behavior. - -Gthread Workers ---------------- - -The worker `gthread` is a threaded worker. It accepts connections in the -main loop. Accepted connections are added to the thread pool as a -connection job. On keepalive connections are put back in the loop -waiting for an event. If no event happens after the keepalive timeout, -the connection is closed. - -Tornado Workers ---------------- - -There's also a Tornado worker class. It can be used to write applications using -the Tornado framework. Although the Tornado workers are capable of serving a -WSGI application, this is not a recommended configuration. - - -.. _asyncio-workers: - -AsyncIO Workers ---------------- - -Third-party workers can be used to use Gunicorn with asyncio frameworks. - -Choosing a Worker Type -====================== - -The default synchronous workers assume that your application is resource-bound -in terms of CPU and network bandwidth. Generally this means that your -application shouldn't do anything that takes an undefined amount of time. An -example of something that takes an undefined amount of time is a request to the -internet. At some point the external network will fail in such a way that -clients will pile up on your servers. So, in this sense, any web application -which makes outgoing requests to APIs will benefit from an asynchronous worker. - -This resource bound assumption is why we require a buffering proxy in front of -a default configuration Gunicorn. If you exposed synchronous workers to the -internet, a DOS attack would be trivial by creating a load that trickles data to -the servers. For the curious, Hey_ is an example of this type of load. - - -Some examples of behavior requiring asynchronous workers: - - * Applications making long blocking calls (Ie, external web services) - * Serving requests directly to the internet - * Streaming requests and responses - * Long polling - * Web sockets - * Comet - -How Many Workers? -================= - -DO NOT scale the number of workers to the number of clients you expect to have. -Gunicorn should only need 4-12 worker processes to handle hundreds or thousands -of requests per second. - -Gunicorn relies on the operating system to provide all of the load balancing -when handling requests. Generally we recommend ``(2 x $num_cores) + 1`` as the -number of workers to start off with. While not overly scientific, the formula -is based on the assumption that for a given core, one worker will be reading -or writing from the socket while the other worker is processing a request. - -Obviously, your particular hardware and application are going to affect the -optimal number of workers. Our recommendation is to start with the above guess -and tune using TTIN and TTOU signals while the application is under load. - -Always remember, there is such a thing as too many workers. After a point your -worker processes will start thrashing system resources decreasing the -throughput of the entire system. - -How Many Threads? -=================== - -Since Gunicorn 19, a threads option can be used to process requests in multiple -threads. Using threads assumes use of the gthread worker. One benefit from threads -is that requests can take longer than the worker timeout while notifying the -master process that it is not frozen and should not be killed. Depending on the -system, using multiple threads, multiple worker processes, or some mixture, may -yield the best results. For example, CPython may not perform as well as Jython -when using threads, as threading is implemented differently by each. Using -threads instead of processes is a good way to reduce the memory footprint of -Gunicorn, while still allowing for application upgrades using the reload -signal, as the application code will be shared among workers but loaded only in -the worker processes (unlike when using the preload setting, which loads the -code in the master process). - -.. _Greenlets: https://github.com/python-greenlet/greenlet -.. _Eventlet: http://eventlet.net/ -.. _Gevent: http://www.gevent.org/ -.. _Hey: https://github.com/rakyll/hey -.. _aiohttp: https://docs.aiohttp.org/en/stable/deployment.html#nginx-gunicorn -.. _`example`: https://github.com/benoitc/gunicorn/blob/master/examples/frameworks/flaskapp_aiohttp_wsgi.py -.. _Psycopg: http://initd.org/psycopg/ -.. _psycogreen: https://github.com/psycopg/psycogreen/ diff --git a/docs/source/faq.rst b/docs/source/faq.rst deleted file mode 100644 index 8c52a486..00000000 --- a/docs/source/faq.rst +++ /dev/null @@ -1,244 +0,0 @@ -.. _faq: - -=== -FAQ -=== - -WSGI Bits -========= - -How do I set SCRIPT_NAME? -------------------------- - -By default ``SCRIPT_NAME`` is an empty string. The value could be set by -setting ``SCRIPT_NAME`` in the environment or as an HTTP header. Note that -this headers contains and underscore, so it is only accepted from trusted -forwarders listed in the :ref:`forwarded-allow-ips` setting. - -.. note:: - - If your application should appear in a subfolder, your ``SCRIPT_NAME`` - would typically start with single slash but contain no trailing slash. - -Server Stuff -============ - -How do I reload my application in Gunicorn? -------------------------------------------- - -You can gracefully reload by sending HUP signal to gunicorn:: - - $ kill -HUP masterpid - -How might I test a proxy configuration? ---------------------------------------- - -The Hey_ program is a great way to test that your proxy is correctly -buffering responses for the synchronous workers:: - - $ hey -n 10000 -c 100 http://127.0.0.1:5000/ - -This runs a benchmark of 10000 requests with 100 running concurrently. - -How can I name processes? -------------------------- - -If you install the Python package setproctitle_ Gunicorn will set the process -names to something a bit more meaningful. This will affect the output you see -in tools like ``ps`` and ``top``. This helps for distinguishing the master -process as well as between masters when running more than one app on a single -machine. See the proc_name_ setting for more information. - -Why is there no HTTP Keep-Alive? --------------------------------- - -The default Sync workers are designed to run behind Nginx which only uses -HTTP/1.0 with its upstream servers. If you want to deploy Gunicorn to -handle unbuffered requests (ie, serving requests directly from the internet) -you should use one of the async workers. - -.. _Hey: https://github.com/rakyll/hey -.. _setproctitle: https://pypi.python.org/pypi/setproctitle -.. _proc_name: settings.html#proc-name - - -Worker Processes -================ - -How do I know which type of worker to use? ------------------------------------------- - -Read the :ref:`design` page for help on the various worker types. - -What types of workers are there? --------------------------------- - -Check out the configuration docs for worker_class_. - -How can I figure out the best number of worker processes? ---------------------------------------------------------- - -Here is our recommendation for tuning the `number of workers`_. - -How can I change the number of workers dynamically? ---------------------------------------------------- - -TTIN and TTOU signals can be sent to the master to increase or decrease -the number of workers. - -To increase the worker count by one:: - - $ kill -TTIN $masterpid - -To decrease the worker count by one:: - - $ kill -TTOU $masterpid - -Does Gunicorn suffer from the thundering herd problem? ------------------------------------------------------- - -The thundering herd problem occurs when many sleeping request handlers, which -may be either threads or processes, wake up at the same time to handle a new -request. Since only one handler will receive the request, the others will have -been awakened for no reason, wasting CPU cycles. At this time, Gunicorn does -not implement any IPC solution for coordinating between worker processes. You -may experience high load due to this problem when using many workers or -threads. However `a work has been started -`_ to remove this issue. - -.. _worker_class: settings.html#worker-class -.. _`number of workers`: design.html#how-many-workers - -Why I don't see any logs in the console? ----------------------------------------- - -In version 19.0, Gunicorn doesn't log by default in the console. -To watch the logs in the console you need to use the option ``--log-file=-``. -In version 19.2, Gunicorn logs to the console by default again. - -Kernel Parameters -================= - -When dealing with large numbers of concurrent connections there are a handful -of kernel parameters that you might need to adjust. Generally these should only -affect sites with a very large concurrent load. These parameters are not -specific to Gunicorn, they would apply to any sort of network server you may be -running. - -These commands are for Linux. Your particular OS may have slightly different -parameters. - -How can I increase the maximum number of file descriptors? ----------------------------------------------------------- - -One of the first settings that usually needs to be bumped is the maximum number -of open file descriptors for a given process. For the confused out there, -remember that Unices treat sockets as files. - -.. warning:: ``sudo ulimit`` may not work - -Considering non-privileged users are not able to relax the limit, you should -firstly switch to root user, increase the limit, then run gunicorn. Using ``sudo -ulimit`` would not take effect. - -Try systemd's service unit file, or an initscript which runs as root. - -How can I increase the maximum socket backlog? ----------------------------------------------- - -Listening sockets have an associated queue of incoming connections that are -waiting to be accepted. If you happen to have a stampede of clients that fill -up this queue new connections will eventually start getting dropped. - -:: - - $ sudo sysctl -w net.core.somaxconn="2048" - -How can I disable the use of ``sendfile()`` -------------------------------------------- - -Disabling the use ``sendfile()`` can be done by using the ``--no-sendfile`` -setting or by setting the environment variable ``SENDFILE`` to 0. - - - -Troubleshooting -=============== - -How do I fix Django reporting an ``ImproperlyConfigured`` error? ----------------------------------------------------------------- - -With asynchronous workers, creating URLs with the ``reverse`` function of -``django.core.urlresolvers`` may fail. Use ``reverse_lazy`` instead. - -.. _blocking-os-fchmod: - -How do I avoid Gunicorn excessively blocking in ``os.fchmod``? --------------------------------------------------------------- - -The current heartbeat system involves calling ``os.fchmod`` on temporary file -handlers and may block a worker for arbitrary time if the directory is on a -disk-backed filesystem. For example, by default ``/tmp`` is not mounted as -``tmpfs`` in Ubuntu; in AWS an EBS root instance volume may sometimes hang for -half a minute and during this time Gunicorn workers may completely block in -``os.fchmod``. ``os.fchmod`` may introduce extra delays if the disk gets full. -Also Gunicorn may refuse to start if it can't create the files when the disk is -full. - -Currently to avoid these problems you can use a ``tmpfs`` mount (for a new -directory or for ``/tmp``) and pass its path to ``--worker-tmp-dir``. First, -check whether your ``/tmp`` is disk-backed or RAM-backed:: - - $ df /tmp - Filesystem 1K-blocks Used Available Use% Mounted on - /dev/xvda1 ... ... ... ... / - -No luck. If you are using Fedora or Ubuntu, you should already have a ``tmpfs`` -mount at ``/dev/shm``:: - - $ df /dev/shm - Filesystem 1K-blocks Used Available Use% Mounted on - tmpfs ... ... ... ... /dev/shm - -In this case you can set ``--worker-tmp-dir /dev/shm``, otherwise you can -create a new ``tmpfs`` mount:: - - sudo cp /etc/fstab /etc/fstab.orig - sudo mkdir /mem - echo 'tmpfs /mem tmpfs defaults,size=64m,mode=1777,noatime,comment=for-gunicorn 0 0' | sudo tee -a /etc/fstab - sudo mount /mem - -Check the result:: - - $ df /mem - Filesystem 1K-blocks Used Available Use% Mounted on - tmpfs 65536 0 65536 0% /mem - -Now you can set ``--worker-tmp-dir /mem``. - -Why are Workers Silently Killed? --------------------------------------------------------------- - -A sometimes subtle problem to debug is when a worker process is killed and there -is little logging information about what happened. - -If you use a reverse proxy like NGINX you might see 502 returned to a client. - -In the gunicorn logs you might simply see ``[35] [INFO] Booting worker with pid: 35`` - -It's completely normal for workers to be stop and start, for example due to -max-requests setting. Ordinarily gunicorn will capture any signals and log something. - -This particular failure case is usually due to a SIGKILL being received, as it's -not possible to catch this signal silence is usually a common side effect! A common -cause of SIGKILL is when OOM killer terminates a process due to low memory condition. - -This is increasingly common in container deployments where memory limits are enforced -by cgroups, you'll usually see evidence of this from dmesg:: - - dmesg | grep gunicorn - Memory cgroup out of memory: Kill process 24534 (gunicorn) score 1506 or sacrifice child - Killed process 24534 (gunicorn) total-vm:1016648kB, anon-rss:550160kB, file-rss:25824kB, shmem-rss:0kB - -In these instances adjusting the memory limit is usually your best bet, it's also possible -to configure OOM not to send SIGKILL by default. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 6c3d51f6..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,46 +0,0 @@ -====================== -Gunicorn - WSGI server -====================== - -.. image:: _static/gunicorn.png - -:Website: http://gunicorn.org -:Source code: https://github.com/benoitc/gunicorn -:Issue tracker: https://github.com/benoitc/gunicorn/issues -:IRC: ``#gunicorn`` on Libera Chat -:Usage questions: https://github.com/benoitc/gunicorn/issues - -Gunicorn 'Green Unicorn' is a Python WSGI HTTP Server for UNIX. It's a pre-fork -worker model ported from Ruby's Unicorn project. The Gunicorn server is broadly -compatible with various web frameworks, simply implemented, light on server -resources, and fairly speedy. - -Features --------- - -* Natively supports WSGI, Django, and Paster -* Automatic worker process management -* Simple Python configuration -* Multiple worker configurations -* Various server hooks for extensibility -* Compatible with Python 3.x >= 3.10 - - -Contents --------- - -.. toctree:: - :maxdepth: 2 - - install - run - configure - settings - instrumentation - deploy - signals - custom - design - faq - community - news diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index eb3e9aba..00000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,172 +0,0 @@ -============ -Installation -============ - -.. highlight:: bash - -:Requirements: **Python 3.x >= 3.10** - -To install the latest released version of Gunicorn:: - - $ pip install gunicorn - -From Source -=========== - -You can install Gunicorn from source just as you would install any other -Python package:: - - $ pip install git+https://github.com/benoitc/gunicorn.git - -This will allow you to keep up to date with development on GitHub:: - - $ pip install -U git+https://github.com/benoitc/gunicorn.git - - -Async Workers -============= - -You may also want to install Eventlet_ or Gevent_ if you expect that your -application code may need to pause for extended periods of time during request -processing. Check out the `design docs`_ for more information on when you'll -want to consider one of the alternate worker types. - -:: - - $ pip install greenlet # Required for both - $ pip install eventlet # For eventlet workers - $ pip install gunicorn[eventlet] # Or, using extra - $ pip install gevent # For gevent workers - $ pip install gunicorn[gevent] # Or, using extra - -.. note:: - Both require ``greenlet``, which should get installed automatically. - If its installation fails, you probably need to install - the Python headers. These headers are available in most package - managers. On Ubuntu the package name for ``apt-get`` is - ``python-dev``. - - Gevent_ also requires that ``libevent`` 1.4.x or 2.0.4 is installed. - This could be a more recent version than what is available in your - package manager. If Gevent_ fails to build even with libevent_ - installed, this is the most likely reason. - - -Extra Packages -============== -Some Gunicorn options require additional packages. You can use the ``[extra]`` -syntax to install these at the same time as Gunicorn. - -Most extra packages are needed for alternate worker types. See the -`design docs`_ for more information on when you'll want to consider an -alternate worker type. - -* ``gunicorn[eventlet]`` - Eventlet-based greenlets workers -* ``gunicorn[gevent]`` - Gevent-based greenlets workers -* ``gunicorn[gthread]`` - Threaded workers -* ``gunicorn[tornado]`` - Tornado-based workers, not recommended - -If you are running more than one instance of Gunicorn, the :ref:`proc-name` -setting will help distinguish between them in tools like ``ps`` and ``top``. - -* ``gunicorn[setproctitle]`` - Enables setting the process name - -Multiple extras can be combined, like -``pip install gunicorn[gevent,setproctitle]``. - -Debian GNU/Linux -================ - -If you are using Debian GNU/Linux it is recommended that you use -system packages to install Gunicorn except maybe when you want to use -different versions of Gunicorn with virtualenv. This has a number of -advantages: - -* Zero-effort installation: Automatically starts multiple Gunicorn instances - based on configurations defined in ``/etc/gunicorn.d``. - -* Sensible default locations for logs (``/var/log/gunicorn``). Logs - can be automatically rotated and compressed using ``logrotate``. - -* Improved security: Can easily run each Gunicorn instance with a dedicated - UNIX user/group. - -* Sensible upgrade path: Upgrades to newer versions result in less downtime, - handle conflicting changes in configuration options, and can be quickly - rolled back in case of incompatibility. The package can also be purged - entirely from the system in seconds. - -stable ("buster") ------------------- - -The version of Gunicorn in the Debian_ "stable" distribution is 19.9.0 -(December 2020). You can install it using:: - - $ sudo apt-get install gunicorn3 - -You can also use the most recent version 20.0.4 (December 2020) by using -`Debian Backports`_. First, copy the following line to your -``/etc/apt/sources.list``:: - - deb http://ftp.debian.org/debian buster-backports main - -Then, update your local package lists:: - - $ sudo apt-get update - -You can then install the latest version using:: - - $ sudo apt-get -t buster-backports install gunicorn - -oldstable ("stretch") ---------------------- - -While Debian releases newer than Stretch will give you gunicorn with Python 3 -support no matter if you install the gunicorn or gunicorn3 package for Stretch -you specifically have to install gunicorn3 to get Python 3 support. - -The version of Gunicorn in the Debian_ "oldstable" distribution is 19.6.0 -(December 2020). You can install it using:: - - $ sudo apt-get install gunicorn3 - -You can also use the most recent version 19.7.1 (December 2020) by using -`Debian Backports`_. First, copy the following line to your -``/etc/apt/sources.list``:: - - deb http://ftp.debian.org/debian stretch-backports main - -Then, update your local package lists:: - - $ sudo apt-get update - -You can then install the latest version using:: - - $ sudo apt-get -t stretch-backports install gunicorn3 - -Testing ("bullseye") / Unstable ("sid") ---------------------------------------- - -"bullseye" and "sid" contain the latest released version of Gunicorn 20.0.4 -(December 2020). You can install it in the usual way:: - - $ sudo apt-get install gunicorn - - -Ubuntu -====== - -Ubuntu_ 20.04 LTS (Focal Fossa) or later contains the Gunicorn package by -default 20.0.4 (December 2020) so that you can install it in the usual way:: - - $ sudo apt-get update - $ sudo apt-get install gunicorn - - -.. _`design docs`: design.html -.. _Eventlet: http://eventlet.net -.. _Gevent: http://www.gevent.org/ -.. _libevent: http://libevent.org/ -.. _Debian: https://www.debian.org/ -.. _`Debian Backports`: https://backports.debian.org/ -.. _Ubuntu: https://www.ubuntu.com/ diff --git a/docs/source/instrumentation.rst b/docs/source/instrumentation.rst deleted file mode 100644 index 60cde416..00000000 --- a/docs/source/instrumentation.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _instrumentation: - -=============== -Instrumentation -=============== - -.. versionadded:: 19.1 - -Gunicorn provides an optional instrumentation of the arbiter and -workers using the statsD_ protocol over UDP. Thanks to the -``gunicorn.instrument.statsd`` module, Gunicorn becomes a statsD client. -The use of UDP cleanly isolates Gunicorn from the receiving end of the statsD -metrics so that instrumentation does not cause Gunicorn to be held up by a slow -statsD consumer. - -To use statsD, just tell Gunicorn where the statsD server is: - -.. code-block:: bash - - $ gunicorn --statsd-host=localhost:8125 --statsd-prefix=service.app ... - -The ``Statsd`` logger overrides ``gunicorn.glogging.Logger`` to track -all requests. The following metrics are generated: - -* ``gunicorn.requests``: request rate per second -* ``gunicorn.request.duration``: histogram of request duration (in millisecond) -* ``gunicorn.workers``: number of workers managed by the arbiter (gauge) -* ``gunicorn.log.critical``: rate of critical log messages -* ``gunicorn.log.error``: rate of error log messages -* ``gunicorn.log.warning``: rate of warning log messages -* ``gunicorn.log.exception``: rate of exceptional log messages - -See the statsd-host_ setting for more information. - -.. _statsd-host: settings.html#statsd-host -.. _statsD: https://github.com/etsy/statsd diff --git a/docs/source/news.rst b/docs/source/news.rst deleted file mode 100644 index 2a61fafe..00000000 --- a/docs/source/news.rst +++ /dev/null @@ -1,83 +0,0 @@ -========= -Changelog -========= - -23.0.0 - 2024-08-10 -=================== - -- minor docs fixes (:pr:`3217`, :pr:`3089`, :pr:`3167`) -- worker_class parameter accepts a class (:pr:`3079`) -- fix deadlock if request terminated during chunked parsing (:pr:`2688`) -- permit receiving Transfer-Encodings: compress, deflate, gzip (:pr:`3261`) -- permit Transfer-Encoding headers specifying multiple encodings. note: no parameters, still (:pr:`3261`) -- sdist generation now explicitly excludes sphinx build folder (:pr:`3257`) -- decode bytes-typed status (as can be passed by gevent) as utf-8 instead of raising `TypeError` (:pr:`2336`) -- raise correct Exception when encounting invalid chunked requests (:pr:`3258`) -- the SCRIPT_NAME and PATH_INFO headers, when received from allowed forwarders, are no longer restricted for containing an underscore (:pr:`3192`) -- include IPv6 loopback address ``[::1]`` in default for :ref:`forwarded-allow-ips` and :ref:`proxy-allow-ips` (:pr:`3192`) - -** NOTE ** - -- The SCRIPT_NAME change mitigates a regression that appeared first in the 22.0.0 release -- Review your :ref:`forwarded-allow-ips` setting if you are still not seeing the SCRIPT_NAME transmitted -- Review your :ref:`forwarder-headers` setting if you are missing headers after upgrading from a version prior to 22.0.0 - -** Breaking changes ** - -- refuse requests where the uri field is empty (:pr:`3255`) -- refuse requests with invalid CR/LR/NUL in heade field values (:pr:`3253`) -- remove temporary ``--tolerate-dangerous-framing`` switch from 22.0 (:pr:`3260`) -- If any of the breaking changes affect you, be aware that now refused requests can post a security problem, especially so in setups involving request pipe-lining and/or proxies. - -22.0.0 - 2024-04-17 -=================== - -- use `utime` to notify workers liveness -- migrate setup to pyproject.toml -- fix numerous security vulnerabilities in HTTP parser (closing some request smuggling vectors) -- parsing additional requests is no longer attempted past unsupported request framing -- on HTTP versions < 1.1 support for chunked transfer is refused (only used in exploits) -- requests conflicting configured or passed SCRIPT_NAME now produce a verbose error -- Trailer fields are no longer inspected for headers indicating secure scheme -- support Python 3.12 - -** Breaking changes ** - -- minimum version is Python 3.7 -- the limitations on valid characters in the HTTP method have been bounded to Internet Standards -- requests specifying unsupported transfer coding (order) are refused by default (rare) -- HTTP methods are no longer casefolded by default (IANA method registry contains none affected) -- HTTP methods containing the number sign (#) are no longer accepted by default (rare) -- HTTP versions < 1.0 or >= 2.0 are no longer accepted by default (rare, only HTTP/1.1 is supported) -- HTTP versions consisting of multiple digits or containing a prefix/suffix are no longer accepted -- HTTP header field names Gunicorn cannot safely map to variables are silently dropped, as in other software -- HTTP headers with empty field name are refused by default (no legitimate use cases, used in exploits) -- requests with both Transfer-Encoding and Content-Length are refused by default (such a message might indicate an attempt to perform request smuggling) -- empty transfer codings are no longer permitted (reportedly seen with really old & broken proxies) - - -** SECURITY ** - -- fix CVE-2024-1135 - -History -======= - -.. toctree:: - :titlesonly: - - 2024-news - 2023-news - 2021-news - 2020-news - 2019-news - 2018-news - 2017-news - 2016-news - 2015-news - 2014-news - 2013-news - 2012-news - 2011-news - 2010-news - diff --git a/docs/source/run.rst b/docs/source/run.rst deleted file mode 100644 index 108956b8..00000000 --- a/docs/source/run.rst +++ /dev/null @@ -1,184 +0,0 @@ -================ -Running Gunicorn -================ - -.. highlight:: bash - -You can run Gunicorn by using commands or integrate with popular frameworks -like Django, Pyramid, or TurboGears. For deploying Gunicorn in production see -:doc:`deploy`. - -Commands -======== - -After installing Gunicorn you will have access to the command line script -``gunicorn``. - -.. _gunicorn-cmd: - -gunicorn --------- - -Basic usage:: - - $ gunicorn [OPTIONS] [WSGI_APP] - -Where ``WSGI_APP`` is of the pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. The -module name can be a full dotted path. The variable name refers to a WSGI -callable that should be found in the specified module. - -.. versionchanged:: 20.1.0 - ``WSGI_APP`` is optional if it is defined in a :ref:`config` file. - -Example with the test app: - -.. code-block:: python - - def app(environ, start_response): - """Simplest possible application object""" - data = b'Hello, World!\n' - status = '200 OK' - response_headers = [ - ('Content-type', 'text/plain'), - ('Content-Length', str(len(data))) - ] - start_response(status, response_headers) - return iter([data]) - -You can now run the app with the following command: - -.. code-block:: text - - $ gunicorn --workers=2 test:app - -The variable name can also be a function call. In that case the name -will be imported from the module, then called to get the application -object. This is commonly referred to as the "application factory" -pattern. - -.. code-block:: python - - def create_app(): - app = FrameworkApp() - ... - return app - -.. code-block:: text - - $ gunicorn --workers=2 'test:create_app()' - -Positional and keyword arguments can also be passed, but it is -recommended to load configuration from environment variables rather than -the command line. - -Commonly Used Arguments -^^^^^^^^^^^^^^^^^^^^^^^ - -* ``-c CONFIG, --config=CONFIG`` - Specify a config file in the form - ``$(PATH)``, ``file:$(PATH)``, or ``python:$(MODULE_NAME)``. -* ``-b BIND, --bind=BIND`` - Specify a server socket to bind. Server sockets - can be any of ``$(HOST)``, ``$(HOST):$(PORT)``, ``fd://$(FD)``, or - ``unix:$(PATH)``. An IP is a valid ``$(HOST)``. -* ``-w WORKERS, --workers=WORKERS`` - The number of worker processes. This - number should generally be between 2-4 workers per core in the server. - Check the :ref:`faq` for ideas on tuning this parameter. -* ``-k WORKERCLASS, --worker-class=WORKERCLASS`` - The type of worker process - to run. You'll definitely want to read the production page for the - implications of this parameter. You can set this to ``$(NAME)`` - where ``$(NAME)`` is one of ``sync``, ``eventlet``, ``gevent``, - ``tornado``, ``gthread``. - ``sync`` is the default. See the :ref:`worker-class` documentation for more - information. -* ``-n APP_NAME, --name=APP_NAME`` - If setproctitle_ is installed you can - adjust the name of Gunicorn process as they appear in the process system - table (which affects tools like ``ps`` and ``top``). - -Settings can be specified by using environment variable -:ref:`GUNICORN_CMD_ARGS `. - -See :ref:`configuration` and :ref:`settings` for detailed usage. - -.. _setproctitle: https://pypi.python.org/pypi/setproctitle - -Integration -=========== - -Gunicorn also provides integration for Django and Paste Deploy applications. - -Django ------- - -Gunicorn will look for a WSGI callable named ``application`` if not specified. -So for a typical Django project, invoking Gunicorn would look like:: - - $ gunicorn myproject.wsgi - - -.. note:: - - This requires that your project be on the Python path; the simplest way to - ensure that is to run this command from the same directory as your - ``manage.py`` file. - -You can use the -`--env `_ option -to set the path to load the settings. In case you need it you can also -add your application path to ``PYTHONPATH`` using the -`--pythonpath `_ -option:: - - $ gunicorn --env DJANGO_SETTINGS_MODULE=myproject.settings myproject.wsgi - -Paste Deployment ----------------- - -Frameworks such as Pyramid and Turbogears are typically configured using Paste -Deployment configuration files. If you would like to use these files with -Gunicorn, there are two approaches. - -As a server runner, Gunicorn can serve your application using the commands from -your framework, such as ``pserve`` or ``gearbox``. To use Gunicorn with these -commands, specify it as a server in your configuration file: - -.. code-block:: ini - - [server:main] - use = egg:gunicorn#main - host = 127.0.0.1 - port = 8080 - workers = 3 - -This approach is the quickest way to get started with Gunicorn, but there are -some limitations. Gunicorn will have no control over how the application is -loaded, so settings such as reload_ will have no effect and Gunicorn will be -unable to hot upgrade a running application. Using the daemon_ option may -confuse your command line tool. Instead, use the built-in support for these -features provided by that tool. For example, run ``pserve --reload`` instead of -specifying ``reload = True`` in the server configuration block. For advanced -configuration of Gunicorn, such as `Server Hooks`_ specifying a Gunicorn -configuration file using the ``config`` key is supported. - -To use the full power of Gunicorn's reloading and hot code upgrades, use the -`paste option`_ to run your application instead. When used this way, Gunicorn -will use the application defined by the PasteDeploy configuration file, but -Gunicorn will not use any server configuration defined in the file. Instead, -`configure gunicorn`_. - -For example:: - - $ gunicorn --paste development.ini -b :8080 --chdir /path/to/project - -Or use a different application:: - - $ gunicorn --paste development.ini#admin -b :8080 --chdir /path/to/project - -With both approaches, Gunicorn will use any loggers section found in Paste -Deployment configuration file, unless instructed otherwise by specifying -additional `logging settings`_. - -.. _reload: http://docs.gunicorn.org/en/latest/settings.html#reload -.. _daemon: http://docs.gunicorn.org/en/latest/settings.html#daemon -.. _Server Hooks: http://docs.gunicorn.org/en/latest/settings.html#server-hooks -.. _paste option: http://docs.gunicorn.org/en/latest/settings.html#paste -.. _configure gunicorn: http://docs.gunicorn.org/en/latest/configure.html -.. _logging settings: http://docs.gunicorn.org/en/latest/settings.html#logging diff --git a/docs/source/settings.rst b/docs/source/settings.rst deleted file mode 100644 index 04677061..00000000 --- a/docs/source/settings.rst +++ /dev/null @@ -1,1795 +0,0 @@ -.. Please update gunicorn/config.py instead. - -.. _settings: - -Settings -======== - -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. - -.. note:: - - Settings can be specified by using environment variable - ``GUNICORN_CMD_ARGS``. All available command line arguments can be used. - For example, to specify the bind address and number of workers:: - - $ GUNICORN_CMD_ARGS="--bind=127.0.0.1 --workers=3" gunicorn app:app - - .. versionadded:: 19.7 - -Config File ------------ - -.. _config: - -``config`` -~~~~~~~~~~ - -**Command line:** ``-c CONFIG`` or ``--config CONFIG`` - -**Default:** ``'./gunicorn.conf.py'`` - -:ref:`The Gunicorn config file`. - -A string of the form ``PATH``, ``file:PATH``, or ``python:MODULE_NAME``. - -Only has an effect when specified on the command line or as part of an -application specific configuration. - -By default, a file named ``gunicorn.conf.py`` will be read from the same -directory where gunicorn is being run. - -.. versionchanged:: 19.4 - Loading the config from a Python module requires the ``python:`` - prefix. - -.. _wsgi-app: - -``wsgi_app`` -~~~~~~~~~~~~ - -**Default:** ``None`` - -A WSGI application path in pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. - -.. versionadded:: 20.1.0 - -Debugging ---------- - -.. _reload: - -``reload`` -~~~~~~~~~~ - -**Command line:** ``--reload`` - -**Default:** ``False`` - -Restart workers when code changes. - -This setting is intended for development. It will cause workers to be -restarted whenever application code changes. - -The reloader is incompatible with application preloading. When using a -paste configuration be sure that the server block does not import any -application code or the reload will not work as designed. - -The default behavior is to attempt inotify with a fallback to file -system polling. Generally, inotify should be preferred if available -because it consumes less system resources. - -.. note:: - In order to use the inotify reloader, you must have the ``inotify`` - package installed. - -.. _reload-engine: - -``reload_engine`` -~~~~~~~~~~~~~~~~~ - -**Command line:** ``--reload-engine STRING`` - -**Default:** ``'auto'`` - -The implementation that should be used to power :ref:`reload`. - -Valid engines are: - -* ``'auto'`` -* ``'poll'`` -* ``'inotify'`` (requires inotify) - -.. versionadded:: 19.7 - -.. _reload-extra-files: - -``reload_extra_files`` -~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--reload-extra-file FILES`` - -**Default:** ``[]`` - -Extends :ref:`reload` option to also watch and reload on additional files -(e.g., templates, configurations, specifications, etc.). - -.. versionadded:: 19.8 - -.. _spew: - -``spew`` -~~~~~~~~ - -**Command line:** ``--spew`` - -**Default:** ``False`` - -Install a trace function that spews every line executed by the server. - -This is the nuclear option. - -.. _check-config: - -``check_config`` -~~~~~~~~~~~~~~~~ - -**Command line:** ``--check-config`` - -**Default:** ``False`` - -Check the configuration and exit. The exit status is 0 if the -configuration is correct, and 1 if the configuration is incorrect. - -.. _print-config: - -``print_config`` -~~~~~~~~~~~~~~~~ - -**Command line:** ``--print-config`` - -**Default:** ``False`` - -Print the configuration settings as fully resolved. Implies :ref:`check-config`. - -Logging -------- - -.. _accesslog: - -``accesslog`` -~~~~~~~~~~~~~ - -**Command line:** ``--access-logfile FILE`` - -**Default:** ``None`` - -The Access log file to write to. - -``'-'`` means log to stdout. - -.. _disable-redirect-access-to-syslog: - -``disable_redirect_access_to_syslog`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--disable-redirect-access-to-syslog`` - -**Default:** ``False`` - -Disable redirect access logs to syslog. - -.. versionadded:: 19.8 - -.. _access-log-format: - -``access_log_format`` -~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--access-logformat STRING`` - -**Default:** ``'%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"'`` - -The access log format. - -=========== =========== -Identifier Description -=========== =========== -h remote address -l ``'-'`` -u user name (if HTTP Basic auth used) -t date of the request -r status line (e.g. ``GET / HTTP/1.1``) -m request method -U URL path without query string -q query string -H protocol -s status -B response length -b response length or ``'-'`` (CLF format) -f referrer (note: header is ``referer``) -a user agent -T request time in seconds -M request time in milliseconds -D request time in microseconds -L request time in decimal seconds -p process ID -{header}i request header -{header}o response header -{variable}e environment variable -=========== =========== - -Use lowercase for header and environment variable names, and put -``{...}x`` names inside ``%(...)s``. For example:: - - %({x-forwarded-for}i)s - -.. _errorlog: - -``errorlog`` -~~~~~~~~~~~~ - -**Command line:** ``--error-logfile FILE`` or ``--log-file FILE`` - -**Default:** ``'-'`` - -The Error log file to write to. - -Using ``'-'`` for FILE makes gunicorn log to stderr. - -.. versionchanged:: 19.2 - Log to stderr by default. - -.. _loglevel: - -``loglevel`` -~~~~~~~~~~~~ - -**Command line:** ``--log-level LEVEL`` - -**Default:** ``'info'`` - -The granularity of Error log outputs. - -Valid level names are: - -* ``'debug'`` -* ``'info'`` -* ``'warning'`` -* ``'error'`` -* ``'critical'`` - -.. _capture-output: - -``capture_output`` -~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--capture-output`` - -**Default:** ``False`` - -Redirect stdout/stderr to specified file in :ref:`errorlog`. - -.. versionadded:: 19.6 - -.. _logger-class: - -``logger_class`` -~~~~~~~~~~~~~~~~ - -**Command line:** ``--logger-class STRING`` - -**Default:** ``'gunicorn.glogging.Logger'`` - -The logger you want to use to log events in Gunicorn. - -The default class (``gunicorn.glogging.Logger``) handles most -normal usages in logging. It provides error and access logging. - -You can provide your own logger by giving Gunicorn a Python path to a -class that quacks like ``gunicorn.glogging.Logger``. - -.. _logconfig: - -``logconfig`` -~~~~~~~~~~~~~ - -**Command line:** ``--log-config FILE`` - -**Default:** ``None`` - -The log config file to use. -Gunicorn uses the standard Python logging module's Configuration -file format. - -.. _logconfig-dict: - -``logconfig_dict`` -~~~~~~~~~~~~~~~~~~ - -**Default:** ``{}`` - -The log config dictionary to use, using the standard Python -logging module's dictionary configuration format. This option -takes precedence over the :ref:`logconfig` and :ref:`logconfig-json` options, -which uses the older file configuration format and JSON -respectively. - -Format: https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig - -For more context you can look at the default configuration dictionary for logging, -which can be found at ``gunicorn.glogging.CONFIG_DEFAULTS``. - -.. versionadded:: 19.8 - -.. _logconfig-json: - -``logconfig_json`` -~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--log-config-json FILE`` - -**Default:** ``None`` - -The log config to read config from a JSON file - -Format: https://docs.python.org/3/library/logging.config.html#logging.config.jsonConfig - -.. versionadded:: 20.0 - -.. _syslog-addr: - -``syslog_addr`` -~~~~~~~~~~~~~~~ - -**Command line:** ``--log-syslog-to SYSLOG_ADDR`` - -**Default:** ``'unix:///var/run/syslog'`` - -Address to send syslog messages. - -Address is a string of the form: - -* ``unix://PATH#TYPE`` : for unix domain socket. ``TYPE`` can be ``stream`` - for the stream driver or ``dgram`` for the dgram driver. - ``stream`` is the default. -* ``udp://HOST:PORT`` : for UDP sockets -* ``tcp://HOST:PORT`` : for TCP sockets - -.. _syslog: - -``syslog`` -~~~~~~~~~~ - -**Command line:** ``--log-syslog`` - -**Default:** ``False`` - -Send *Gunicorn* logs to syslog. - -.. versionchanged:: 19.8 - You can now disable sending access logs by using the - :ref:`disable-redirect-access-to-syslog` setting. - -.. _syslog-prefix: - -``syslog_prefix`` -~~~~~~~~~~~~~~~~~ - -**Command line:** ``--log-syslog-prefix SYSLOG_PREFIX`` - -**Default:** ``None`` - -Makes Gunicorn use the parameter as program-name in the syslog entries. - -All entries will be prefixed by ``gunicorn.``. By default the -program name is the name of the process. - -.. _syslog-facility: - -``syslog_facility`` -~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--log-syslog-facility SYSLOG_FACILITY`` - -**Default:** ``'user'`` - -Syslog facility name - -.. _enable-stdio-inheritance: - -``enable_stdio_inheritance`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``-R`` or ``--enable-stdio-inheritance`` - -**Default:** ``False`` - -Enable stdio inheritance. - -Enable inheritance for stdio file descriptors in daemon mode. - -Note: To disable the Python stdout buffering, you can to set the user -environment variable ``PYTHONUNBUFFERED`` . - -.. _statsd-host: - -``statsd_host`` -~~~~~~~~~~~~~~~ - -**Command line:** ``--statsd-host STATSD_ADDR`` - -**Default:** ``None`` - -The address of the StatsD server to log to. - -Address is a string of the form: - -* ``unix://PATH`` : for a unix domain socket. -* ``HOST:PORT`` : for a network address - -.. versionadded:: 19.1 - -.. _dogstatsd-tags: - -``dogstatsd_tags`` -~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--dogstatsd-tags DOGSTATSD_TAGS`` - -**Default:** ``''`` - -A comma-delimited list of datadog statsd (dogstatsd) tags to append to -statsd metrics. - -.. versionadded:: 20 - -.. _statsd-prefix: - -``statsd_prefix`` -~~~~~~~~~~~~~~~~~ - -**Command line:** ``--statsd-prefix STATSD_PREFIX`` - -**Default:** ``''`` - -Prefix to use when emitting statsd metrics (a trailing ``.`` is added, -if not provided). - -.. versionadded:: 19.2 - -Process Naming --------------- - -.. _proc-name: - -``proc_name`` -~~~~~~~~~~~~~ - -**Command line:** ``-n STRING`` or ``--name STRING`` - -**Default:** ``None`` - -A base to use with setproctitle for process naming. - -This affects things like ``ps`` and ``top``. 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. - -If not set, the *default_proc_name* setting will be used. - -.. _default-proc-name: - -``default_proc_name`` -~~~~~~~~~~~~~~~~~~~~~ - -**Default:** ``'gunicorn'`` - -Internal setting that is adjusted for each type of application. - -SSL ---- - -.. _keyfile: - -``keyfile`` -~~~~~~~~~~~ - -**Command line:** ``--keyfile FILE`` - -**Default:** ``None`` - -SSL key file - -.. _certfile: - -``certfile`` -~~~~~~~~~~~~ - -**Command line:** ``--certfile FILE`` - -**Default:** ``None`` - -SSL certificate file - -.. _ssl-version: - -``ssl_version`` -~~~~~~~~~~~~~~~ - -**Command line:** ``--ssl-version`` - -**Default:** ``<_SSLMethod.PROTOCOL_TLS: 2>`` - -SSL version to use (see stdlib ssl module's). - -.. deprecated:: 21.0 - The option is deprecated and it is currently ignored. Use :ref:`ssl-context` instead. - -============= ============ ---ssl-version Description -============= ============ -SSLv3 SSLv3 is not-secure and is strongly discouraged. -SSLv23 Alias for TLS. Deprecated in Python 3.6, use TLS. -TLS Negotiate highest possible version between client/server. - Can yield SSL. (Python 3.6+) -TLSv1 TLS 1.0 -TLSv1_1 TLS 1.1 (Python 3.4+) -TLSv1_2 TLS 1.2 (Python 3.4+) -TLS_SERVER Auto-negotiate the highest protocol version like TLS, - but only support server-side SSLSocket connections. - (Python 3.6+) -============= ============ - -.. versionchanged:: 19.7 - The default value has been changed from ``ssl.PROTOCOL_TLSv1`` to - ``ssl.PROTOCOL_SSLv23``. -.. versionchanged:: 20.0 - This setting now accepts string names based on ``ssl.PROTOCOL_`` - constants. -.. versionchanged:: 20.0.1 - The default value has been changed from ``ssl.PROTOCOL_SSLv23`` to - ``ssl.PROTOCOL_TLS`` when Python >= 3.6 . - -.. _cert-reqs: - -``cert_reqs`` -~~~~~~~~~~~~~ - -**Command line:** ``--cert-reqs`` - -**Default:** ```` - -Whether client certificate is required (see stdlib ssl module's) - -=========== =========================== ---cert-reqs Description -=========== =========================== -`0` no client verification -`1` ssl.CERT_OPTIONAL -`2` ssl.CERT_REQUIRED -=========== =========================== - -.. _ca-certs: - -``ca_certs`` -~~~~~~~~~~~~ - -**Command line:** ``--ca-certs FILE`` - -**Default:** ``None`` - -CA certificates file - -.. _suppress-ragged-eofs: - -``suppress_ragged_eofs`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--suppress-ragged-eofs`` - -**Default:** ``True`` - -Suppress ragged EOFs (see stdlib ssl module's) - -.. _do-handshake-on-connect: - -``do_handshake_on_connect`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--do-handshake-on-connect`` - -**Default:** ``False`` - -Whether to perform SSL handshake on socket connect (see stdlib ssl module's) - -.. _ciphers: - -``ciphers`` -~~~~~~~~~~~ - -**Command line:** ``--ciphers`` - -**Default:** ``None`` - -SSL Cipher suite to use, in the format of an OpenSSL cipher list. - -By default we use the default cipher list from Python's ``ssl`` module, -which contains ciphers considered strong at the time of each Python -release. - -As a recommended alternative, the Open Web App Security Project (OWASP) -offers `a vetted set of strong cipher strings rated A+ to C- -`_. -OWASP provides details on user-agent compatibility at each security level. - -See the `OpenSSL Cipher List Format Documentation -`_ -for details on the format of an OpenSSL cipher list. - -Security --------- - -.. _limit-request-line: - -``limit_request_line`` -~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--limit-request-line INT`` - -**Default:** ``4094`` - -The maximum size of HTTP request line in bytes. - -This parameter is used to limit the allowed size of a client's -HTTP request-line. Since the request-line consists of the HTTP -method, URI, and protocol version, this directive places a -restriction on the length of a request-URI allowed for a request -on the server. A server needs this value to be large enough to -hold any of its resource names, including any information that -might be passed in the query part of a GET request. Value is a number -from 0 (unlimited) to 8190. - -This parameter can be used to prevent any DDOS attack. - -.. _limit-request-fields: - -``limit_request_fields`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--limit-request-fields INT`` - -**Default:** ``100`` - -Limit the number of HTTP headers fields in a request. - -This parameter is used to limit the number of headers in a request to -prevent DDOS attack. Used with the *limit_request_field_size* it allows -more safety. By default this value is 100 and can't be larger than -32768. - -.. _limit-request-field-size: - -``limit_request_field_size`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--limit-request-field_size INT`` - -**Default:** ``8190`` - -Limit the allowed size of an HTTP request header field. - -Value is a positive number or 0. Setting it to 0 will allow unlimited -header field sizes. - -.. warning:: - Setting this parameter to a very high or unlimited value can open - up for DDOS attacks. - -Server Hooks ------------- - -.. _on-starting: - -``on_starting`` -~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def on_starting(server): - pass - -Called just before the master process is initialized. - -The callable needs to accept a single instance variable for the Arbiter. - -.. _on-reload: - -``on_reload`` -~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def on_reload(server): - pass - -Called to recycle workers during a reload via SIGHUP. - -The callable needs to accept a single instance variable for the Arbiter. - -.. _when-ready: - -``when_ready`` -~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def when_ready(server): - pass - -Called just after the server is started. - -The callable needs to accept a single instance variable for the Arbiter. - -.. _pre-fork: - -``pre_fork`` -~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def pre_fork(server, worker): - pass - -Called just before a worker is forked. - -The callable needs to accept two instance variables for the Arbiter and -new Worker. - -.. _post-fork: - -``post_fork`` -~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def post_fork(server, worker): - pass - -Called just after a worker has been forked. - -The callable needs to accept two instance variables for the Arbiter and -new Worker. - -.. _post-worker-init: - -``post_worker_init`` -~~~~~~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def post_worker_init(worker): - pass - -Called just after a worker has initialized the application. - -The callable needs to accept one instance variable for the initialized -Worker. - -.. _worker-int: - -``worker_int`` -~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def worker_int(worker): - pass - -Called just after a worker exited on SIGINT or SIGQUIT. - -The callable needs to accept one instance variable for the initialized -Worker. - -.. _worker-abort: - -``worker_abort`` -~~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def worker_abort(worker): - pass - -Called when a worker received the SIGABRT signal. - -This call generally happens on timeout. - -The callable needs to accept one instance variable for the initialized -Worker. - -.. _pre-exec: - -``pre_exec`` -~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def pre_exec(server): - pass - -Called just before a new master process is forked. - -The callable needs to accept a single instance variable for the Arbiter. - -.. _pre-request: - -``pre_request`` -~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def pre_request(worker, req): - worker.log.debug("%s %s", req.method, req.path) - -Called just before a worker processes the request. - -The callable needs to accept two instance variables for the Worker and -the Request. - -.. _post-request: - -``post_request`` -~~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def post_request(worker, req, environ, resp): - pass - -Called after a worker processes the request. - -The callable needs to accept two instance variables for the Worker and -the Request. - -.. _child-exit: - -``child_exit`` -~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def child_exit(server, worker): - pass - -Called just after a worker has been exited, in the master process. - -The callable needs to accept two instance variables for the Arbiter and -the just-exited Worker. - -.. versionadded:: 19.7 - -.. _worker-exit: - -``worker_exit`` -~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def worker_exit(server, worker): - pass - -Called just after a worker has been exited, in the worker process. - -The callable needs to accept two instance variables for the Arbiter and -the just-exited Worker. - -.. _nworkers-changed: - -``nworkers_changed`` -~~~~~~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def nworkers_changed(server, new_value, old_value): - pass - -Called just after *num_workers* has been changed. - -The callable needs to accept an instance variable of the Arbiter and -two integers of number of workers after and before change. - -If the number of workers is set for the first time, *old_value* would -be ``None``. - -.. _on-exit: - -``on_exit`` -~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def on_exit(server): - pass - -Called just before exiting Gunicorn. - -The callable needs to accept a single instance variable for the Arbiter. - -.. _ssl-context: - -``ssl_context`` -~~~~~~~~~~~~~~~ - -**Default:** - -.. code-block:: python - - def ssl_context(config, default_ssl_context_factory): - return default_ssl_context_factory() - -Called when SSLContext is needed. - -Allows customizing SSL context. - -The callable needs to accept an instance variable for the Config and -a factory function that returns default SSLContext which is initialized -with certificates, private key, cert_reqs, and ciphers according to -config and can be further customized by the callable. -The callable needs to return SSLContext object. - -Following example shows a configuration file that sets the minimum TLS version to 1.3: - -.. code-block:: python - - def ssl_context(conf, default_ssl_context_factory): - import ssl - context = default_ssl_context_factory() - context.minimum_version = ssl.TLSVersion.TLSv1_3 - return context - -.. versionadded:: 21.0 - -Server Mechanics ----------------- - -.. _preload-app: - -``preload_app`` -~~~~~~~~~~~~~~~ - -**Command line:** ``--preload`` - -**Default:** ``False`` - -Load application code before the worker processes are forked. - -By preloading an application you can save some RAM resources as well as -speed up server boot times. Although, if you defer application loading -to each worker process, you can reload your application code easily by -restarting workers. - -.. _sendfile: - -``sendfile`` -~~~~~~~~~~~~ - -**Command line:** ``--no-sendfile`` - -**Default:** ``None`` - -Disables the use of ``sendfile()``. - -If not set, the value of the ``SENDFILE`` environment variable is used -to enable or disable its usage. - -.. versionadded:: 19.2 -.. versionchanged:: 19.4 - Swapped ``--sendfile`` with ``--no-sendfile`` to actually allow - disabling. -.. versionchanged:: 19.6 - added support for the ``SENDFILE`` environment variable - -.. _reuse-port: - -``reuse_port`` -~~~~~~~~~~~~~~ - -**Command line:** ``--reuse-port`` - -**Default:** ``False`` - -Set the ``SO_REUSEPORT`` flag on the listening socket. - -.. versionadded:: 19.8 - -.. _chdir: - -``chdir`` -~~~~~~~~~ - -**Command line:** ``--chdir`` - -**Default:** ``'.'`` - -Change directory to specified directory before loading apps. - -.. _daemon: - -``daemon`` -~~~~~~~~~~ - -**Command line:** ``-D`` or ``--daemon`` - -**Default:** ``False`` - -Daemonize the Gunicorn process. - -Detaches the server from the controlling terminal and enters the -background. - -.. _raw-env: - -``raw_env`` -~~~~~~~~~~~ - -**Command line:** ``-e ENV`` or ``--env ENV`` - -**Default:** ``[]`` - -Set environment variables in the execution environment. - -Should be a list of strings in the ``key=value`` format. - -For example on the command line: - -.. code-block:: console - - $ gunicorn -b 127.0.0.1:8000 --env FOO=1 test:app - -Or in the configuration file: - -.. code-block:: python - - raw_env = ["FOO=1"] - -.. _pidfile: - -``pidfile`` -~~~~~~~~~~~ - -**Command line:** ``-p FILE`` or ``--pid FILE`` - -**Default:** ``None`` - -A filename to use for the PID file. - -If not set, no PID file will be written. - -.. _worker-tmp-dir: - -``worker_tmp_dir`` -~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--worker-tmp-dir DIR`` - -**Default:** ``None`` - -A directory to use for the worker heartbeat temporary file. - -If not set, the default temporary directory will be used. - -.. note:: - The current heartbeat system involves calling ``os.fchmod`` on - temporary file handlers and may block a worker for arbitrary time - if the directory is on a disk-backed filesystem. - - See :ref:`blocking-os-fchmod` for more detailed information - and a solution for avoiding this problem. - -.. _user: - -``user`` -~~~~~~~~ - -**Command line:** ``-u USER`` or ``--user USER`` - -**Default:** ``os.geteuid()`` - -Switch worker processes to run as this user. - -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. - -.. _group: - -``group`` -~~~~~~~~~ - -**Command line:** ``-g GROUP`` or ``--group GROUP`` - -**Default:** ``os.getegid()`` - -Switch worker process to run as this group. - -A valid group id (as an integer) or the name of a user that can be -retrieved with a call to ``grp.getgrnam(value)`` or ``None`` to not -change the worker processes group. - -.. _umask: - -``umask`` -~~~~~~~~~ - -**Command line:** ``-m INT`` or ``--umask INT`` - -**Default:** ``0`` - -A bit mask for the file mode on files written by Gunicorn. - -Note that this affects unix socket permissions. - -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 ``0``, ``0xFF``, ``0022`` are valid for decimal, hex, and octal -representations) - -.. _initgroups: - -``initgroups`` -~~~~~~~~~~~~~~ - -**Command line:** ``--initgroups`` - -**Default:** ``False`` - -If true, set the worker process's group access list with all of the -groups of which the specified username is a member, plus the specified -group id. - -.. versionadded:: 19.7 - -.. _tmp-upload-dir: - -``tmp_upload_dir`` -~~~~~~~~~~~~~~~~~~ - -**Default:** ``None`` - -Directory to store temporary request data as they are read. - -This may disappear in the near future. - -This path should be writable by the process permissions set for Gunicorn -workers. If not specified, Gunicorn will choose a system generated -temporary directory. - -.. _secure-scheme-headers: - -``secure_scheme_headers`` -~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Default:** ``{'X-FORWARDED-PROTOCOL': 'ssl', 'X-FORWARDED-PROTO': 'https', 'X-FORWARDED-SSL': 'on'}`` - -A dictionary containing headers and values that the front-end proxy -uses to indicate HTTPS requests. If the source IP is permitted by -:ref:`forwarded-allow-ips` (below), *and* at least one request header matches -a key-value pair listed in this dictionary, then Gunicorn will set -``wsgi.url_scheme`` to ``https``, so your application can tell that the -request is secure. - -If the other headers listed in this dictionary are not present in the request, they will be ignored, -but if the other headers are present and do not match the provided values, then -the request will fail to parse. See the note below for more detailed examples of this behaviour. - -The dictionary should map upper-case header names to exact string -values. The value comparisons are case-sensitive, unlike the header -names, so make sure they're exactly what your front-end proxy sends -when handling HTTPS requests. - -It is important that your front-end proxy configuration ensures that -the headers defined here can not be passed directly from the client. - -.. _forwarded-allow-ips: - -``forwarded_allow_ips`` -~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--forwarded-allow-ips STRING`` - -**Default:** ``'127.0.0.1,::1'`` - -Front-end's IPs from which allowed to handle set secure headers. -(comma separated). - -Set to ``*`` to disable checking of front-end IPs. This is useful for setups -where you don't know in advance the IP address of front-end, but -instead have ensured via other means that only your -authorized front-ends can access Gunicorn. - -By default, the value of the ``FORWARDED_ALLOW_IPS`` environment -variable. If it is not defined, the default is ``"127.0.0.1,::1"``. - -.. note:: - - This option does not affect UNIX socket connections. Connections not associated with - an IP address are treated as allowed, unconditionally. - -.. note:: - - The interplay between the request headers, the value of ``forwarded_allow_ips``, and the value of - ``secure_scheme_headers`` is complex. Various scenarios are documented below to further elaborate. - In each case, we have a request from the remote address 134.213.44.18, and the default value of - ``secure_scheme_headers``: - - .. code:: - - secure_scheme_headers = { - 'X-FORWARDED-PROTOCOL': 'ssl', - 'X-FORWARDED-PROTO': 'https', - 'X-FORWARDED-SSL': 'on' - } - - - .. list-table:: - :header-rows: 1 - :align: center - :widths: auto - - * - ``forwarded-allow-ips`` - - Secure Request Headers - - Result - - Explanation - * - .. code:: - - ["127.0.0.1"] - - .. code:: - - X-Forwarded-Proto: https - - .. code:: - - wsgi.url_scheme = "http" - - IP address was not allowed - * - .. code:: - - "*" - - - - .. code:: - - wsgi.url_scheme = "http" - - IP address allowed, but no secure headers provided - * - .. code:: - - "*" - - .. code:: - - X-Forwarded-Proto: https - - .. code:: - - wsgi.url_scheme = "https" - - IP address allowed, one request header matched - * - .. code:: - - ["134.213.44.18"] - - .. code:: - - X-Forwarded-Ssl: on - X-Forwarded-Proto: http - - ``InvalidSchemeHeaders()`` raised - - IP address allowed, but the two secure headers disagreed on if HTTPS was used - -.. _pythonpath: - -``pythonpath`` -~~~~~~~~~~~~~~ - -**Command line:** ``--pythonpath STRING`` - -**Default:** ``None`` - -A comma-separated list of directories to add to the Python path. - -e.g. -``'/home/djangoprojects/myproject,/home/python/mylibrary'``. - -.. _paste: - -``paste`` -~~~~~~~~~ - -**Command line:** ``--paste STRING`` or ``--paster STRING`` - -**Default:** ``None`` - -Load a PasteDeploy config file. The argument may contain a ``#`` -symbol followed by the name of an app section from the config file, -e.g. ``production.ini#admin``. - -At this time, using alternate server blocks is not supported. Use the -command line arguments to control server configuration instead. - -.. _proxy-protocol: - -``proxy_protocol`` -~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--proxy-protocol`` - -**Default:** ``False`` - -Enable detect PROXY protocol (PROXY mode). - -Allow using HTTP and Proxy together. It may be useful for work with -stunnel as HTTPS frontend and Gunicorn as HTTP server. - -PROXY protocol: http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt - -Example for stunnel config:: - - [https] - protocol = proxy - accept = 443 - connect = 80 - cert = /etc/ssl/certs/stunnel.pem - key = /etc/ssl/certs/stunnel.key - -.. _proxy-allow-ips: - -``proxy_allow_ips`` -~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--proxy-allow-from`` - -**Default:** ``'127.0.0.1,::1'`` - -Front-end's IPs from which allowed accept proxy requests (comma separated). - -Set to ``*`` to disable checking of front-end IPs. This is useful for setups -where you don't know in advance the IP address of front-end, but -instead have ensured via other means that only your -authorized front-ends can access Gunicorn. - -.. note:: - - This option does not affect UNIX socket connections. Connections not associated with - an IP address are treated as allowed, unconditionally. - -.. _raw-paste-global-conf: - -``raw_paste_global_conf`` -~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--paste-global CONF`` - -**Default:** ``[]`` - -Set a PasteDeploy global config variable in ``key=value`` form. - -The option can be specified multiple times. - -The variables are passed to the PasteDeploy entrypoint. Example:: - - $ gunicorn -b 127.0.0.1:8000 --paste development.ini --paste-global FOO=1 --paste-global BAR=2 - -.. versionadded:: 19.7 - -.. _permit-obsolete-folding: - -``permit_obsolete_folding`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--permit-obsolete-folding`` - -**Default:** ``False`` - -Permit requests employing obsolete HTTP line folding mechanism - -The folding mechanism was deprecated by rfc7230 Section 3.2.4 and will not be - employed in HTTP request headers from standards-compliant HTTP clients. - -This option is provided to diagnose backwards-incompatible changes. -Use with care and only if necessary. Temporary; the precise effect of this option may -change in a future version, or it may be removed altogether. - -.. versionadded:: 23.0.0 - -.. _strip-header-spaces: - -``strip_header_spaces`` -~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--strip-header-spaces`` - -**Default:** ``False`` - -Strip spaces present between the header name and the the ``:``. - -This is known to induce vulnerabilities and is not compliant with the HTTP/1.1 standard. -See https://portswigger.net/research/http-desync-attacks-request-smuggling-reborn. - -Use with care and only if necessary. Deprecated; scheduled for removal in 25.0.0 - -.. versionadded:: 20.0.1 - -.. _permit-unconventional-http-method: - -``permit_unconventional_http_method`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--permit-unconventional-http-method`` - -**Default:** ``False`` - -Permit HTTP methods not matching conventions, such as IANA registration guidelines - -This permits request methods of length less than 3 or more than 20, -methods with lowercase characters or methods containing the # character. -HTTP methods are case sensitive by definition, and merely uppercase by convention. - -If unset, Gunicorn will apply nonstandard restrictions and cause 400 response status -in cases where otherwise 501 status is expected. While this option does modify that -behaviour, it should not be depended upon to guarantee standards-compliant behaviour. -Rather, it is provided temporarily, to assist in diagnosing backwards-incompatible -changes around the incomplete application of those restrictions. - -Use with care and only if necessary. Temporary; scheduled for removal in 24.0.0 - -.. versionadded:: 22.0.0 - -.. _permit-unconventional-http-version: - -``permit_unconventional_http_version`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--permit-unconventional-http-version`` - -**Default:** ``False`` - -Permit HTTP version not matching conventions of 2023 - -This disables the refusal of likely malformed request lines. -It is unusual to specify HTTP 1 versions other than 1.0 and 1.1. - -This option is provided to diagnose backwards-incompatible changes. -Use with care and only if necessary. Temporary; the precise effect of this option may -change in a future version, or it may be removed altogether. - -.. versionadded:: 22.0.0 - -.. _casefold-http-method: - -``casefold_http_method`` -~~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--casefold-http-method`` - -**Default:** ``False`` - -Transform received HTTP methods to uppercase - -HTTP methods are case sensitive by definition, and merely uppercase by convention. - -This option is provided because previous versions of gunicorn defaulted to this behaviour. - -Use with care and only if necessary. Deprecated; scheduled for removal in 24.0.0 - -.. versionadded:: 22.0.0 - -.. _forwarder-headers: - -``forwarder_headers`` -~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--forwarder-headers`` - -**Default:** ``'SCRIPT_NAME,PATH_INFO'`` - -A list containing upper-case header field names that the front-end proxy -(see :ref:`forwarded-allow-ips`) sets, to be used in WSGI environment. - -This option has no effect for headers not present in the request. - -This option can be used to transfer ``SCRIPT_NAME``, ``PATH_INFO`` -and ``REMOTE_USER``. - -It is important that your front-end proxy configuration ensures that -the headers defined here can not be passed directly from the client. - -.. _header-map: - -``header_map`` -~~~~~~~~~~~~~~ - -**Command line:** ``--header-map`` - -**Default:** ``'drop'`` - -Configure how header field names are mapped into environ - -Headers containing underscores are permitted by RFC9110, -but gunicorn joining headers of different names into -the same environment variable will dangerously confuse applications as to which is which. - -The safe default ``drop`` is to silently drop headers that cannot be unambiguously mapped. -The value ``refuse`` will return an error if a request contains *any* such header. -The value ``dangerous`` matches the previous, not advisable, behaviour of mapping different -header field names into the same environ name. - -If the source is permitted as explained in :ref:`forwarded-allow-ips`, *and* the header name is -present in :ref:`forwarder-headers`, the header is mapped into environment regardless of -the state of this setting. - -Use with care and only if necessary and after considering if your problem could -instead be solved by specifically renaming or rewriting only the intended headers -on a proxy in front of Gunicorn. - -.. versionadded:: 22.0.0 - -Server Socket -------------- - -.. _bind: - -``bind`` -~~~~~~~~ - -**Command line:** ``-b ADDRESS`` or ``--bind ADDRESS`` - -**Default:** ``['127.0.0.1:8000']`` - -The socket to bind. - -A string of the form: ``HOST``, ``HOST:PORT``, ``unix:PATH``, -``fd://FD``. An IP is a valid ``HOST``. - -.. versionchanged:: 20.0 - Support for ``fd://FD`` got added. - -Multiple addresses can be bound. ex.:: - - $ gunicorn -b 127.0.0.1:8000 -b [::1]:8000 test:app - -will bind the `test:app` application on localhost both on ipv6 -and ipv4 interfaces. - -If the ``PORT`` environment variable is defined, the default -is ``['0.0.0.0:$PORT']``. If it is not defined, the default -is ``['127.0.0.1:8000']``. - -.. _backlog: - -``backlog`` -~~~~~~~~~~~ - -**Command line:** ``--backlog INT`` - -**Default:** ``2048`` - -The maximum number of pending connections. - -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. - -Must be a positive integer. Generally set in the 64-2048 range. - -Worker Processes ----------------- - -.. _workers: - -``workers`` -~~~~~~~~~~~ - -**Command line:** ``-w INT`` or ``--workers INT`` - -**Default:** ``1`` - -The number of worker processes for handling requests. - -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. - -By default, the value of the ``WEB_CONCURRENCY`` environment variable, -which is set by some Platform-as-a-Service providers such as Heroku. If -it is not defined, the default is ``1``. - -.. _worker-class: - -``worker_class`` -~~~~~~~~~~~~~~~~ - -**Command line:** ``-k STRING`` or ``--worker-class STRING`` - -**Default:** ``'sync'`` - -The type of workers to use. - -The default class (``sync``) should handle most "normal" types of -workloads. You'll want to read :doc:`design` for information on when -you might want to choose one of the other worker classes. Required -libraries may be installed using setuptools' ``extras_require`` feature. - -A string referring to one of the following bundled classes: - -* ``sync`` -* ``eventlet`` - Requires eventlet >= 0.24.1 (or install it via - ``pip install gunicorn[eventlet]``) -* ``gevent`` - Requires gevent >= 1.4 (or install it via - ``pip install gunicorn[gevent]``) -* ``tornado`` - Requires tornado >= 0.2 (or install it via - ``pip install gunicorn[tornado]``) -* ``gthread`` - Python 2 requires the futures package to be installed - (or install it via ``pip install gunicorn[gthread]``) - -Optionally, you can provide your own worker by giving Gunicorn a -Python path to a subclass of ``gunicorn.workers.base.Worker``. -This alternative syntax will load the gevent class: -``gunicorn.workers.ggevent.GeventWorker``. - -.. _threads: - -``threads`` -~~~~~~~~~~~ - -**Command line:** ``--threads INT`` - -**Default:** ``1`` - -The number of worker threads for handling requests. - -Run each worker with the specified number of threads. - -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. - -If it is not defined, the default is ``1``. - -This setting only affects the Gthread worker type. - -.. note:: - If you try to use the ``sync`` worker type and set the ``threads`` - setting to more than 1, the ``gthread`` worker type will be used - instead. - -.. _worker-connections: - -``worker_connections`` -~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--worker-connections INT`` - -**Default:** ``1000`` - -The maximum number of simultaneous clients. - -This setting only affects the ``gthread``, ``eventlet`` and ``gevent`` worker types. - -.. _max-requests: - -``max_requests`` -~~~~~~~~~~~~~~~~ - -**Command line:** ``--max-requests INT`` - -**Default:** ``0`` - -The maximum number of requests a worker will process before restarting. - -Any value greater than zero will limit the number of requests a worker -will process before automatically restarting. This is a simple method -to help limit the damage of memory leaks. - -If this is set to zero (the default) then the automatic worker -restarts are disabled. - -.. _max-requests-jitter: - -``max_requests_jitter`` -~~~~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--max-requests-jitter INT`` - -**Default:** ``0`` - -The maximum jitter to add to the *max_requests* setting. - -The jitter causes the restart per worker to be randomized by -``randint(0, max_requests_jitter)``. This is intended to stagger worker -restarts to avoid all workers restarting at the same time. - -.. versionadded:: 19.2 - -.. _timeout: - -``timeout`` -~~~~~~~~~~~ - -**Command line:** ``-t INT`` or ``--timeout INT`` - -**Default:** ``30`` - -Workers silent for more than this many seconds are killed and restarted. - -Value is a positive number or 0. Setting it to 0 has the effect of -infinite timeouts by disabling timeouts for all workers entirely. - -Generally, the default of thirty seconds should suffice. 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. - -.. _graceful-timeout: - -``graceful_timeout`` -~~~~~~~~~~~~~~~~~~~~ - -**Command line:** ``--graceful-timeout INT`` - -**Default:** ``30`` - -Timeout for graceful workers restart in seconds. - -After receiving a restart signal, workers have this much time to finish -serving requests. Workers still alive after the timeout (starting from -the receipt of the restart signal) are force killed. - -.. _keepalive: - -``keepalive`` -~~~~~~~~~~~~~ - -**Command line:** ``--keep-alive INT`` - -**Default:** ``2`` - -The number of seconds to wait for requests on a Keep-Alive connection. - -Generally set in the 1-5 seconds range for servers with direct connection -to the client (e.g. when you don't have separate load balancer). When -Gunicorn is deployed behind a load balancer, it often makes sense to -set this to a higher value. - -.. note:: - ``sync`` worker does not support persistent connections and will - ignore this option. - diff --git a/docs/source/signals.rst b/docs/source/signals.rst deleted file mode 100644 index c22ea036..00000000 --- a/docs/source/signals.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. _signals: - -=============== -Signal Handling -=============== - -A brief description of the signals handled by Gunicorn. We also document the -signals used internally by Gunicorn to communicate with the workers. - -Master process -============== - -- ``QUIT``, ``INT``: Quick shutdown -- ``TERM``: Graceful shutdown. Waits for workers to finish their - current requests up to the :ref:`graceful-timeout`. -- ``HUP``: Reload the configuration, start the new worker processes with a new - configuration and gracefully shutdown older workers. If the application is - not preloaded (using the :ref:`preload-app` option), Gunicorn will also load - the new version of it. -- ``TTIN``: Increment the number of processes by one -- ``TTOU``: Decrement the number of processes by one -- ``USR1``: Reopen the log files -- ``USR2``: Upgrade Gunicorn on the fly. A separate ``TERM`` signal should - be used to kill the old master process. This signal can also be used to use - the new versions of pre-loaded applications. See :ref:`binary-upgrade` for - more information. -- ``WINCH``: Gracefully shutdown the worker processes when Gunicorn is - daemonized. - -Worker process -============== - -Sending signals directly to the worker processes should not normally be -needed. If the master process is running, any exited worker will be -automatically respawned. - -- ``QUIT``, ``INT``: Quick shutdown -- ``TERM``: Graceful shutdown -- ``USR1``: Reopen the log files - -Reload the configuration -======================== - -The ``HUP`` signal can be used to reload the Gunicorn configuration on the -fly. - -:: - - 2013-06-29 06:26:55 [20682] [INFO] Handling signal: hup - 2013-06-29 06:26:55 [20682] [INFO] Hang up: Master - 2013-06-29 06:26:55 [20703] [INFO] Booting worker with pid: 20703 - 2013-06-29 06:26:55 [20702] [INFO] Booting worker with pid: 20702 - 2013-06-29 06:26:55 [20688] [INFO] Worker exiting (pid: 20688) - 2013-06-29 06:26:55 [20687] [INFO] Worker exiting (pid: 20687) - 2013-06-29 06:26:55 [20689] [INFO] Worker exiting (pid: 20689) - 2013-06-29 06:26:55 [20704] [INFO] Booting worker with pid: 20704 - - -Sending a ``HUP`` signal will reload the configuration, start the new -worker processes with a new configuration and gracefully shutdown older -workers. If the application is not preloaded (using the :ref:`preload-app` -option), Gunicorn will also load the new version of it. - -.. _binary-upgrade: - -Upgrading to a new binary on the fly -==================================== - -.. versionchanged:: 19.6.0 - PID file naming format has been changed from ``.pid.oldbin`` to - ``.pid.2``. - -If you need to replace the Gunicorn 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. Preloaded applications will also be reloaded. - -First, replace the old binary with a new one, then send a ``USR2`` signal to -the current master process. It executes a new binary whose PID file is -postfixed with ``.2`` (e.g. ``/var/run/gunicorn.pid.2``), -which in turn starts a new master process and new worker processes:: - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 20844 benoitc 20 0 54808 11m 3352 S 0.0 0.1 0:00.36 gunicorn: master [test:app] - 20849 benoitc 20 0 54808 9.9m 1500 S 0.0 0.1 0:00.02 gunicorn: worker [test:app] - 20850 benoitc 20 0 54808 9.9m 1500 S 0.0 0.1 0:00.01 gunicorn: worker [test:app] - 20851 benoitc 20 0 54808 9.9m 1500 S 0.0 0.1 0:00.01 gunicorn: worker [test:app] - 20854 benoitc 20 0 55748 12m 3348 S 0.0 0.2 0:00.35 gunicorn: master [test:app] - 20859 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.01 gunicorn: worker [test:app] - 20860 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.00 gunicorn: worker [test:app] - 20861 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.01 gunicorn: worker [test:app] - -At this point, two instances of Gunicorn are running, handling the -incoming requests together. To phase the old instance out, you have to -send a ``WINCH`` signal to the old master process, and its worker -processes will start to gracefully shut down. - -At this point you can still revert to the old process since it hasn't closed -its listen sockets yet, by following these steps: - -- Send a ``HUP`` signal to the old master process - it will start the worker - processes without reloading a configuration file -- Send a ``TERM`` signal to the new master process to gracefully shut down its - worker processes -- Send a ``QUIT`` signal to the new master process to force it quit - -If for some reason the new worker processes do not quit, send a ``KILL`` signal -to them after the new master process quits, and everything will back to exactly -as before the upgrade attempt. - -If the update is successful and you want to keep the new master process, send a -``TERM`` signal to the old master process to leave only the new server -running:: - - PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND - 20854 benoitc 20 0 55748 12m 3348 S 0.0 0.2 0:00.45 gunicorn: master [test:app] - 20859 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.02 gunicorn: worker [test:app] - 20860 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.02 gunicorn: worker [test:app] - 20861 benoitc 20 0 55748 11m 1500 S 0.0 0.1 0:00.01 gunicorn: worker [test:app] diff --git a/gunicorn/__init__.py b/gunicorn/__init__.py index cdcd1352..347557ce 100644 --- a/gunicorn/__init__.py +++ b/gunicorn/__init__.py @@ -2,7 +2,7 @@ # This file is part of gunicorn released under the MIT license. # See the NOTICE for more information. -version_info = (23, 0, 0) +version_info = (24, 0, 0) __version__ = ".".join([str(v) for v in version_info]) SERVER = "gunicorn" SERVER_SOFTWARE = "%s/%s" % (SERVER, __version__)