innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

Improved tone in docs/ref/settings.txt.

This commit is contained in:
Kate Berry 2018-10-04 16:35:19 +01:00 committed by Tim Graham
parent 5a23a285de
commit b8b1d8cad6
1 changed files with 28 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/ref/settings.txt
View File

@ -1102,9 +1102,6 @@ A boolean that turns on/off debug mode.
Never deploy a site into production with :setting:`DEBUG` turned on. Never deploy a site into production with :setting:`DEBUG` turned on.
Did you catch that? NEVER deploy a site into production with :setting:`DEBUG`
turned on.
One of the main features of debug mode is the display of detailed error pages. One of the main features of debug mode is the display of detailed error pages.
If your app raises an exception when :setting:`DEBUG` is ``True``, Django will If your app raises an exception when :setting:`DEBUG` is ``True``, Django will
display a detailed traceback, including a lot of metadata about your display a detailed traceback, including a lot of metadata about your
@ -1263,8 +1260,8 @@ backend supports it (see :doc:`/topics/db/tablespaces`).
Default: ``[]`` (Empty list) Default: ``[]`` (Empty list)
List of compiled regular expression objects representing User-Agent strings that List of compiled regular expression objects representing User-Agent strings
are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. that are not allowed to visit any page, systemwide. Use this for bots/crawlers.
This is only used if ``CommonMiddleware`` is installed (see This is only used if ``CommonMiddleware`` is installed (see
:doc:`/topics/http/middleware`). :doc:`/topics/http/middleware`).
@ -1640,8 +1637,7 @@ ignored when reporting HTTP 404 errors via email (see
:doc:`/howto/error-reporting`). Regular expressions are matched against :doc:`/howto/error-reporting`). Regular expressions are matched against
:meth:`request's full paths <django.http.HttpRequest.get_full_path>` (including :meth:`request's full paths <django.http.HttpRequest.get_full_path>` (including
query string, if any). Use this if your site does not provide a commonly query string, if any). Use this if your site does not provide a commonly
requested file such as ``favicon.ico`` or ``robots.txt``, or if it gets requested file such as ``favicon.ico`` or ``robots.txt``.
hammered by script kiddies.
This is only used if This is only used if
:class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see :class:`~django.middleware.common.BrokenLinkEmailsMiddleware` is enabled (see
@ -2056,8 +2052,8 @@ used if :class:`~django.middleware.common.CommonMiddleware` is installed
Default: Not defined Default: Not defined
A string representing the full Python import path to your root URLconf. For example: A string representing the full Python import path to your root URLconf, for
``"mydjangoapps.urls"``. Can be overridden on a per-request basis by example ``"mydjangoapps.urls"``. Can be overridden on a per-request basis by
setting the attribute ``urlconf`` on the incoming ``HttpRequest`` setting the attribute ``urlconf`` on the incoming ``HttpRequest``
object. See :ref:`how-django-processes-a-request` for details. object. See :ref:`how-django-processes-a-request` for details.
@ -2189,31 +2185,30 @@ A tuple representing a HTTP header/value combination that signifies a request
is secure. This controls the behavior of the request object's ``is_secure()`` is secure. This controls the behavior of the request object's ``is_secure()``
method. method.
This takes some explanation. By default, ``is_secure()`` is able to determine By default, ``is_secure()`` determines if a request is secure by confirming
whether a request is secure by looking at whether the requested URL uses that a requested URL uses ``https://``. This method is important for Django's
``https://``. This is important for Django's CSRF protection, and may be used CSRF protection, and it may be used by your own code or third-party apps.
by your own code or third-party apps.
If your Django app is behind a proxy, though, the proxy may be "swallowing" the If your Django app is behind a proxy, though, the proxy may be "swallowing" the
fact that a request is HTTPS, using a non-HTTPS connection between the proxy fact that a request is HTTPS, using a non-HTTPS connection between the proxy
and Django. In this case, ``is_secure()`` would always return ``False`` -- even and Django. In this case, ``is_secure()`` would always return ``False`` -- even
for requests that were made via HTTPS by the end user. for requests that were made via HTTPS by the end user.
In this situation, you'll want to configure your proxy to set a custom HTTP In this situation, configure your proxy to set a custom HTTP header that tells
header that tells Django whether the request came in via HTTPS, and you'll want Django whether the request came in via HTTPS, and set
to set ``SECURE_PROXY_SSL_HEADER`` so that Django knows what header to look ``SECURE_PROXY_SSL_HEADER`` so that Django knows what header to look for.
for.
You'll need to set a tuple with two elements -- the name of the header to look Set a tuple with two elements -- the name of the header to look for and the
for and the required value. For example:: required value. For example::
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https') SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
Here, we're telling Django that we trust the ``X-Forwarded-Proto`` header This tells Django to trust the ``X-Forwarded-Proto`` header that comes from our
that comes from our proxy, and any time its value is ``'https'``, then the proxy, and any time its value is ``'https'``, then the request is guaranteed to
request is guaranteed to be secure (i.e., it originally came in via HTTPS). be secure (i.e., it originally came in via HTTPS).
Obviously, you should *only* set this setting if you control your proxy or
have some other guarantee that it sets/strips this header appropriately. You should *only* set this setting if you control your proxy or have some other
guarantee that it sets/strips this header appropriately.
Note that the header needs to be in the format as used by ``request.META`` -- Note that the header needs to be in the format as used by ``request.META`` --
all caps and likely starting with ``HTTP_``. (Remember, Django automatically all caps and likely starting with ``HTTP_``. (Remember, Django automatically
@ -2222,9 +2217,8 @@ available in ``request.META``.)
.. warning:: .. warning::
**You will probably open security holes in your site if you set this **Modifying this setting can compromise your site's security. Ensure you
without knowing what you're doing. And if you fail to set it when you fully understand your setup before changing it.**
should. Seriously.**
Make sure ALL of the following are true before setting this (assuming the Make sure ALL of the following are true before setting this (assuming the
values from the example above): values from the example above):
@ -3000,10 +2994,10 @@ consistently by all browsers. However, when it is honored, it can be a
useful way to mitigate the risk of a client side script accessing the useful way to mitigate the risk of a client side script accessing the
protected cookie data. protected cookie data.
Turning it on makes it less trivial for an attacker to escalate a cross-site This makes it less trivial for an attacker to escalate a cross-site scripting
scripting vulnerability into full hijacking of a user's session. There's not vulnerability into full hijacking of a user's session. There aren't many good
much excuse for leaving this off, either: if your code depends on reading reasons for turning this off. Your code shouldn't read session cookies from
session cookies from JavaScript, you're probably doing it wrong. JavaScript.
.. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly .. _HTTPOnly: https://www.owasp.org/index.php/HTTPOnly
@ -3080,12 +3074,9 @@ Whether to use a secure cookie for the session cookie. If this is set to
``True``, the cookie will be marked as "secure," which means browsers may ``True``, the cookie will be marked as "secure," which means browsers may
ensure that the cookie is only sent under an HTTPS connection. ensure that the cookie is only sent under an HTTPS connection.
Since it's trivial for a packet sniffer (e.g. `Firesheep`_) to hijack a user's Leaving this setting off isn't a good idea because an attacker could capture an
session if the session cookie is sent unencrypted, there's really no good unencrypted session cookie with a packet sniffer and use the cookie to hijack
excuse to leave this off. It will prevent you from using sessions on insecure the user's session.
requests and that's a good thing.
.. _Firesheep: https://codebutler.com/firesheep/
.. setting:: SESSION_ENGINE .. setting:: SESSION_ENGINE