EVOLUTION-MANAGER

Edit File: version-4.1.0.txt

============= Version 4.1.0 ============= With version 4.1.0 of mod_wsgi, a switch to a X.Y.Z version numbering scheme from the existing X.Y scheme is being made. This is to enable a much quicker release cycle with more incremental changes. Version 4.1.0 of mod_wsgi can be obtained from: https://github.com/GrahamDumpleton/mod_wsgi/archive/4.1.0.tar.gz Note that mod_wsgi 4.1.0 was originally derived from mod_wsgi 3.1. It has though all changes from later releases in the 3.X branch. Thus also see: * :doc:`version-3.2` * :doc:`version-3.3` * :doc:`version-3.4` * :doc:`version-3.5` Known Issues ------------ 1. The makefiles for building mod_wsgi on Windows are currently broken and need updating. As most new changes relate to mod_wsgi daemon mode, which is not supported under Windows, you should keep using the last available binary for version 3.X on Windows instead. Bugs Fixed ---------- 1. If a UNIX signal received by daemon mode process while still being initialised to signal that it should be shutdown, the process could crash rather than shutdown properly due to not registering the signal pipe prior to registering signal handler. 2. Python doesn't initialise codecs in sub interpreters automatically which in some cases could cause code running in WSGI script to fail due to lack of encoding for Unicode strings when converting them. The error message in this case was:: LookupError: no codec search functions registered: can't find encoding The 'ascii' encoding is now forcibly loaded when initialising sub interpreters to get Python to initialise codecs. 3. Fixed reference counting bug under Python 3 in SSL ``var_lookup()`` function which can be used from an auth handler to look up SSL variables. 4. The ``WWW-Authenticate`` headers returned from a WSGI application when run under daemon mode are now always preserved as is. Because of previously using an internal routine of Apache, way back in time the values of multiple ``WWW-Authenticate`` headers would be merged when there was more than one. This would cause an issue with some browsers. A workaround was subsequently implemented above the Apache routine to break apart the merged header to create separate ones again, however, if the value of a header validly had a ',' in it, this would cause the header value to be broken apart where it wasn't meant to. This could issues with some type of ``WWW-Authenticate`` headers. Features Removed ---------------- 1. No longer support the use of mod_python in conjunction with mod_wsgi. When this is attempted an error is forced and Apache will not be able to start. An error message is logged in main Apache error log. 2. No longer support the use of Apache 1.3. Minimum requirement is now Apache 2.0. Features Changed ---------------- 1. Use of kernel ``sendfile()`` function by ``wsgi.file_wrapper`` is now off by default. This was originally always on for embedded mode and completely disabled for daemon mode. Use of this feature can be enabled for either mode using ``WSGIEnableSendfile`` directive, setting it to ``On`` to enable it. The default is now off because kernel ``sendfile()`` is not always able to work on all file objects. Some instances where it will not work are described for the Apache ``EnableSendfile`` directive. http://httpd.apache.org/docs/2.2/mod/core.html#enablesendfile Although Apache has use of ``sendfile()`` enabled by default for static files, they are moving to having it off by default in future version of Apache. This change is being made because of the problems which arise and users not knowing how to debug it and solve it. Thus also erring on side of caution and having it off by default but allowing more knowledgeable users to enable it where they know always using file objects which will work with ``sendfile()``. 2. The ``HTTPS`` variable is no longer set within the WSGI environment. The authoritative indicator of whether a SSL connection is used is ``wsgi.url_scheme`` and a WSGI compliant application should check for ``wsgi.url_scheme``. The only reason that ``HTTPS`` was supplied at all was because early Django versions supporting WSGI interface weren't correctly using ``wsgi.url_scheme``. Instead they were expecting to see ``HTTPS`` to exist. This change will cause non conformant WSGI applications to finally break. This possibly includes some Django versions prior to Django version 1.0. Note that you can still set ``HTTPS`` in Apache configuration using the ``SetEnv`` or ``SetEnvIf`` directive, or via a rewrite rule. In that case, that will override what ``wsgi.url_scheme`` is set to and once ``wsgi.url_scheme`` is set appropriately, the ``HTTPS`` variable will be removed from the set of variables passed through to the WSGI environment. 3. The ``wsgi.version`` variable has been reverted to 1.0 to conform to the WSGI PEP 3333 specification. It was originally set to 1.1 on expectation that revised specification would use 1.1 but that didn't come to be. 4. The ``inactivity-timeout`` option to ``WSGIDaemonProcess`` now only results in the daemon process being restarted after the idle timeout period where there are no active requests. Previously it would also interrupt a long running request. See the new ``request-timeout`` option for a way of interrupting long running, potentially blocked requests and restarting the process. 5. If the ``home`` option is used with ``WSGIDaemonProcess``, in addition to that directory being made the current working directory for the process, an empty string will be added to the start of the Python module search path. This causes Python to look in the current working directory for Python modules when they are being imported. This behaviour brings things into line with what happens when running the Python interpreter from the command line. You must though be using the ``home`` option for this to come into play. Do not that if your application then changes the working directory, it will start looking in the new current working directory and not that which is specified by the ``home`` option. This again mirrors what the normal Python command line interpreter does. New Features ------------ 1. Add ``supplementary-groups`` option to ``WSGIDaemonProcess`` to allow group membership to be overridden and specified comma separate list of groups used instead. 2. Add a ``graceful-timeout`` option to ``WSGIDaemonProcess``. This option is applied in a number of circumstances. When ``maximum-requests`` and this option are used together, when maximum requests is reached, rather than immediately shutdown, potentially interupting active requests if they don't finished with shutdown timeout, can specify a separate graceful shutdown period. If the all requests are completed within this time frame then will shutdown immediately, otherwise normal forced shutdown kicks in. In some respects this is just allowing a separate shutdown timeout on cases where requests could be interrupted and could avoid it if possible. When ``cpu-time-limit`` and this option are used together, when CPU time limit reached, rather than immediately shutdown, potentially interupting active requests if they don't finished with shutdown timeout, can specify a separate graceful shutdown period. 3. Add potentially graceful process restart option for daemon processes when sent a graceful restart signal. Signal is usually ``SIGUSR1`` but is platform dependent as using same signal as Apache would use. If the ``graceful-timeout`` option had been provided to ``WSGIDaemonProcess``, then the process will attempt graceful shutdown first based on the that timeout, otherwise normal shutdown procedure used as if received a ``SIGTERM``. 4. Add ``memory-limit`` option to ``WSGIDaemonProcess`` to allow memory usage of daemon processes to be restricted. This will have no affect on some platforms as ``RLIMIT_AS``/``RLIMIT_DATA`` with ``setrlimit()`` isn't always implemented. For example MacOS X and older Linux kernel versions do not implement this feature. You will need to test whether this feature works or not before depending on it. 5. Add ``virtual-memory-limit`` option to ``WSGIDaemonProcess`` to allow virtual memory usage of daemon processes to be restricted. This will have no affect on some platforms as ``RLIMIT_VMEM`` with ``setrlimit()`` isn't always implemented. You will need to test whether this feature works or not before depending on it. 6. Access, authentication and authorisation hooks now have additional keys in the environ dictionary for ``mod_ssl.is_https`` and ``mod_ssl.var_lookup``. These equate to callable functions provided by ``mod_ssl`` for determining if the client connection to Apache used SSL and what the values of variables specified in the SSL certifcates, server or client, are. These are only available if Apache 2.0 or later is being used. 7. For Python 2.6 and above, the ``WSGIDontWriteBytecode`` directive can be used at global scope in Apache configuration to disable writing of all byte code files, ie., .pyc, by the Python interpreter when it imports Python code files. To disable writing of byte code files, set directive to ``On``. Note that this doesn't prevent existing byte code files on disk being used in preference to the corresponding Python code files. Thus you should first remove ``.pyc`` files from web application directories if relying on this option to ensure that ``.py`` file is always used. 8. Add ``request-timeout`` option to ``WSGIDaemonProcess`` to allow a separate timeout to be applied on how long a request is allowed to run for before the daemon process is automatically restarted to interrupt the request. This is to counter the possibility that a request may become blocked on some backend service, thereby using up available requests threads and preventing other requests to be handled. In the case of a single threaded process, then the timeout will happen at the specified time duration from the start of the request being handled. Applying such a timeout in the case of a multithreaded process is more problematic as doing a restart when a single requests exceeds the timeout could unduly interfere with with requests which just commenced. In the case of a multi threaded process, what is instead done is to take the total of the current running time of all requests and divide that by the number of threads handling requests in that process. When this average time exceeds the time specified, then the process will be restarted. This strategy for a multithreaded process means that individual requests can actually run longer than the specified timeout and a restart will only be performed when the overall capacity of the processes appears to be getting consumed by a number of concurrent long running requests, or when a specific requests has been blocked for an excessively long time. The intent of this is to allow the process to still keep handling requests and only perform a restart when the available capacity of the process to handle more requests looks to be potentially on the decline. 9. Add ``connect-timeout`` option to ``WSGIDaemonProcess`` to allow a timeout to be specified on how long the Apache child worker processes should wait on being able to obtain a connection to the mod_wsgi daemon process. As UNIX domain sockets are used, connections should always succeed, however there have been some incidences seen which could only be explained by the operating system hanging on the initial connect call without being added to the daemon process socket listener queue. As such the timeout has been added. The timeout defaults to 15 seconds. This timeout also now dictates how long the Apache child worker process will attempt to get a connection to the daemon process when the connection is refused due to the daemon socket listener queue being full. Previously how long connection attempts were tried was based on an internal retry count rather than a configurable timeout. 10. Add ``socket-timeout`` option to ``WSGIDaemonProcess`` to allow the timeout on indvidual read/writes on the socket connection between the Apache child worker and the daemon process to be specified separately to the Apache ``Timeout`` directive. If this option is not specified, it will default to the value of the Apache ``Timeout`` directive. 11. Add ``queue-timeout`` option to ``WSGIDaemonProcess`` to allow a request to be aborted if it never got handed off to a mod_wsgi daemon process within the specified time. When this occurs a '503 Service Unavailable' response will be returned. This is to allow one to control what to do when backlogging of requests occurs. If the daemon process is overloaded and getting behind, then it is more than likely that a user will have given up on the request anyway if they have to wait too long. This option allows you to specify that a request that was queued up waiting for too long is discarded, allowing any transient backlog to be quickly discarded and not simply cause the daemon process to become even more backlogged. 12. Add ``listen-backlog`` option to ``WSGIDaemonProcess`` to allow the daemon process socket listener backlog size to be specified. By default this limit is 100, although this is actually a hint, as different operating systems can have different limits on the maximum value or otherwise treat it in special ways. 13. Add ``WSGIPythonHashSeed`` directive to allow Python behaviour related to initial hash seed to be overridden when the interpreter supports it. This is equivalent to setting the ``PYTHONHASHSEED`` environment variable and should be set to either ``random`` or a number in the range in range ``[0; 4294967295]``. 14. Implemented a new streamlined way of installing mod_wsgi as a Python package using a setup.py file or from PyPi. This includes a ``mod_wsgi-express`` script that can then be used to start up Apache/mod_wsgi with an auto generated configuration on port 8000. This makes it easy to run up Apache for development without interfering with the main Apache on the system and without having to worry about configuring Apache. Command line options can be used to override behaviour. Once the ``mod_wsgi`` package has been installed into your Python installation, you can run:: mod_wsgi-express start-server Then open your browser on the listed URL. This will verify that everything is working. Enter CTRL-C to exit the server and shut it down. You can now point it at a specific WSGI application script file:: mod_wsgi-express start-server wsgi.py For options run:: mod_wsgi-express start-server --help If you already have another web server running on port 8000, you can override the port to be used using the ``--port`` option:: mod_wsgi-express start-server wsgi.py --port 8001 15. Implemented a Django application plugin to add a ``runmodwsgi`` command to the Django management command script. This allows the automatic run up of the new mod_wsgi express script, with it hosting the Django web site the plugin was added to. To enable, once the ``mod_wsgi`` package has been installed into your Python installation, add ``mod_wsgi.server`` to the ``INSTALLED_APPS`` setting in your Django settings file. After having run the ``collectstatic`` Django management command, you can then run:: python manage.py runmodwsgi For options run:: python manage.py runmodwsgi --help To enable automatic code reloading in a development setting, use the option:: python manage.py runmodwsgi --reload-on-changes 16. The maximum size that a response header/value can be that is returned from a WSGI application under daemon mode can now be configured. The default size has also now been increased from 8192 bytes to 32768 bytes. The name of the option to ``WSGIDaemonProcess`` to set the buffer size used is ``header-buffer-size``.