Installation And Usage Jon Travis

jtravis@p00p.org

v0.5.0, 27 November 2000 Mod Snake is an Apache module written for the purpose to give Python developers the same power that C module writers have, but with the added flexibility and power that Python provides. This manual will discuss how to install mod_snake, as well as provide some basic examples of usage. The main prerequisite for mod_snake is Python. If it is not already installed, it can be obtained from the Python website. Both Python 1.5.2, and 2.0 have been tested with mod_snake. Mod Snake has been tested with Apache 1.3.12, 1.3.14, and 1.3.17. Since Apache 2.0 is still in a pre-beta stage, its API is continually changing. Mod Snake development is currently matched against the CVS versions of Apache 2.0. Each version of mod_snake should coorespond to a publicly released version of Apache, such as Apache 2.0a9. For purposes of demonstration, in the subsequent sections, it will be assumed that Apache is installed under /home/httpd/apache, and that sources will be extracted under /usr/local/src. Currently, mod_snake is only supported as a DSO under Apache 2.0. Under Apache 1.3 it is supported both as a DSO and statically built in. Apache has the ability to load shared modules on the fly. These are called Dynamically Shared Objects (DSO). Mod Snake can be installed into an existing Apache installation which has DSO support with very little work. To check if Apache was built with DSO support, execute the following command: bash$ /home/httpd/apache/bin/httpd -l | grep mod_so.c If mod_so.c is returned as output, Apache contains DSO support. If not, see To install mod_snake, the following steps can be taken: Download mod_snake from modsnake.sourceforge.net. Extract, configure, and install mod_snake. bash$ gunzip -c mod_snake-0.5.0.tar.gz | tar -xvf - bash$ cd mod_snake-0.5.0 bash$ ./configure --with-apxs=/home/httpd/apache/bin/apxs bash$ make install Test the server. See . All done! Download Apache from www.apache.org For Apache 1.3 builds, extract, configure, and build Apache: bash$ gunzip -c apache_1.3.17.tar.gz | tar -xvf - bash$ cd apache_1.3.17 bash$ ./configure --prefix=/home/httpd/apache --enable-module=so bash$ make For Apache 2.0 builds, extract, configure, and build Apache: bash$ gunzip -c apache_2.0a9.tar.gz | tar -xvf - bash$ cd apache_2.0a9 bash$ ./configure --enable-so --prefix=/home/httpd/apache bash$ make If a DSO build is desired, or Apache 2.0 is being used, execute make install, and skip to . Extract, configure, and install mod_snake: bash$ gunzip -c mod_snake-0.5.0.tar.gz | tar -xvf - bash$ cd mod_snake-0.5.0 bash$ ./configure --with-apache=/usr/local/src/apache_1.3.17 --disable-dso bash$ make install Finally, reconfigure, build, and install Apache: bash$ cd /usr/local/src/apache_1.3.17 bash$ ./configure --activate-module=src/modules/mod_snake/libmod_snake.a bash$ make install Aside from needing to load mod_snake into Apache, other optional mod_snake libraries can be installed. These standard libraries add a lot of functionality, such as embedded Python and accelerated CGIs. bash$ cd /usr/local/src/mod_snake-0.5.0 bash$ mkdir /home/httpd/mod_snake bash$ cp -R snake_lib examples /home/httpd/mod_snake The following lines can be appended to the httpd.conf file: SnakeModuleDir /home/httpd/mod_snake/snake_lib SnakeModuleDir /home/httpd/mod_snake/examples These directives tell mod_snake to look in those directories for modules to load. To then load a module from either of those directories (e.g. SnakeLib's SnakeEPy embedded Python processor), the following directive can be added: SnakeModule mod_snake_epy.SnakeEPy This loads in the SnakeEPy module, and gives more directives that can be placed in the configuration file. To enable embedded Python processing for the main server, the following directives can be used: SnakeEPy on Other PyMods can be added and configured in similar ways. See the documentation for the individual PyMods, or look at the mod_snake_api documentation for the SnakeLib hooks. For more information about the directives, see To quickly test to ensure that everything is working correctly, the following lines can be added to the server configuration file (httpd.conf): SnakeModuleDir /usr/local/src/mod_snake-0.5.0/examples/tut SnakeModule 01_hello_world.Hello_World Connect to the webserver and attempt to retrieve the page ``/hello_world''. If the server responds with a page containing, ``Hello world!'', then everything is working correctly. SnakeModuleDir Directory Arguments Directory - A path to look for mod_snake PyMods. This path can be relative to the server root. Validity This configuration directive is currently only available within the main configuration file outside <Directory> and <Location> blocks. Description Mod Snake needs to know where it can locate PyMods to load. This directive also gives the modules loaded path information where they can also find other modules (for instance examples to load within the mod_snake_simple module.) SnakeModule module.class profile Arguments module.class - A module + class pair. The module is used the same as an 'import', and the class is a class within that module to instantiate. For instance, something like the following should be able to be performed on the module.class specified, in a typical Python interpreter. import module x = module.class() profile - An optional argument which allows the loaded module to be profiled. All calls to the module will be profiled, and can be analyzed through the mod_snake_info SnakeLib module. Extra installation work is required to use profiling -- see Validity This configuration directive is currently only available within the main configuration file outside <Directory> and <Location> blocks. Description This directive loads a PyMod into mod_snake. These can be active for virtual servers or the main server. As of Python release 1.5.2, a broken version of profile.py is shipped with Python. According to tim_one at sourceforge.net (a Python developer), this is not a bug, but is something one should just 'not do.' A hack is provided with mod_snake to allow profiling to work. To use it, the following steps should be taken: Copy the system's profile.py into the snake_lib directory, or another location where your Python modules are loaded. bash$ cp /usr/lib/python-2.0/profile.py /path/to/mod_snake/snake_lib/profile2.py Change into the directory containing the new profile2.py and patch it with the profile2.patch which ships with mod_snake. bash$ patch -p0 < profile2.patch After those steps, profiling should work with all modules