summary Common mod_wsgi configuration problems.
labels Phase-Deploy
If you are using mod_wsgi, please consider making a donation.
Configuration Issues
Many Linux distributions in particular do not structure an Apache installation in the default manner as dictated by the original Apache code distributed by the Apache Software Foundation. This fact, and differences between different operating systems and distributions means that the configuration for mod_wsgi may sometimes have to be tweaked.
The purpose of this document is to capture all the known problems that can arise in respect of configuration.
If you are having a problem which doesn't seem to be covered by this document, also make sure you see:
- Installation Issues
- Application Issues
Location Of UNIX Sockets
When mod_wsgi is used in 'daemon' mode, UNIX sockets are used to communicate between the Apache child processes and the daemon processes which are to handle a request.
These sockets and any related mutex lock files will be placed in the standard Apache runtime directory. This is the same directory that the Apache log files would normally be placed.
For some Linux distributions, restrictive permissions are placed on the standard Apache runtime directory such that the directory is not readable to others. This can cause problems with mod_wsgi because the user that the Apache child processes run as will subsequently not have the required permissions to access the directory to be able to connect to the sockets.
When this occurs, a '503 Service Temporarily Unavailable' error response would be received by the client. The Apache error log file would show messages of the form:
(13)Permission denied: mod_wsgi (pid=26962): Unable to connect to WSGI \
daemon process '<process-name>' on '/etc/httpd/logs/wsgi.26957.0.1.sock' \
after multiple attempts.
To resolve the problem, the WSGISocketPrefix directive should be defined to point at an alternate location. The value may be a location relative to the Apache root directory, or an absolute path.
On systems which restrict access to the standard Apache runtime directory, they normally provide an alternate directory for placing sockets and lock files used by Apache modules. This directory is usually called 'run' and to make use of this directory the WSGISocketPrefix directive would be set as follows:
WSGISocketPrefix run/wsgi
Although this may be present, do be aware that some Linux distributions, notably RedHat, also lock down the permissions of this directory as well so not readable to processes running as a non root user. In this situation you will be forced to use the operating system level '/var/run' directory rather than the HTTP specific directory.
WSGISocketPrefix /var/run/wsgi
Note, do not put the sockets in the system temporary working directory. That is, do not go making the prefix '/tmp/wsgi'. The directory should be one that is only writable by 'root' user, or if not starting Apache as 'root', the user that Apache is started as.
Alias Directives And Apache 1.3
When implementing Apache modules for Apache 2.X, it is possible for the code for the module to specify in what order relative to other modules that its directives should be interpreted. This means that it is possible to define that mod_alias directives such as Alias should be given precedence over directives implemented by mod_wsgi. This is important where the WSGIScriptAlias directive applies to '/' and the Alias directive is used to denote a sub directory which contains static media files. For example:
``` Alias /media/ /usr/local/django/mysite/media/
Order deny,allow Allow from all
WSGIScriptAlias / /usr/local/django/mysite/apache/django.wsgi
Order deny,allow Allow from all ```
If the directives are interpreted in the wrong order, the WSGIScriptAlias would get precedence and the media files would not be accessible.
When Apache 1.3 is being used, it is not possible for the code for the Apache module to specify this ordering, instead the order in which the directives pertaining to different Apache modules are applied is dictated by the order in which the LoadModule/AddModule directives are listed in the Apache configuration file.
Therefore, to ensure the directives are applied in the correct order when using Apache 1.3, it is necessary that mod_wsgi be loaded prior to the mod_alias module.
``` LoadModule wsgi_module libexec/httpd/mod_wsgi.so ... LoadModule alias_module libexec/httpd/mod_alias.so ...
ClearModuleList AddModule mod_wsgi.c ... AddModule mod_alias.c ... ```