The 'Easy' Way

Creation of a regular PyMod is a very easy matter. Create a new file called mod_snake_log_syslog.py, and fill it out with the following (for those not included to do so, the real McCoy can be examined in mod_snake/examples/mod_snake_log_syslog.py):

import mod_snake

import syslog

 

class SnakeLogSyslog:

def __init__(self, module):

directives = { 'SnakeLogSyslog' : (mod_snake.OR_ALL, mod_snake.FLAG, self.cmd_SnakeLogSyslog), }

module.add_directives(directives)

hooks = { 'create_dir_config' : self.create_dir_config, 'open_logs' : self.open_logs, 'log_transaction' : self.log_transaction),}

for hook in hooks.keys():

module.add_hook(hook, hooks[hook])

def cmd_SnakeLogSyslog(self, per_dir, per_svr, on_or_off):

'cmd_SnakeLogSyslog: enable or disable special syslog logging'

per_dir['enabled'] = on_or_off

def create_dir_config(self, path):

return { 'path' : path, 'enabled' : 0 }

def open_logs(self, per_svr, module):

syslog.openlog('SnakeSyslog')

return mod_snake.HTTP_DECLINED

def log_transaction(self, per_dir, per_svr, request_rec):

if per_dir['enabled']:

conn = request_rec.connection

syslog.syslog('%s - %s' % (conn.remote_ip, request_rec.uri))

return mod_snake.HTTP_DECLINED

To activate this module, edit your httpd.conf file to add it:

SnakeModule mod_snake_log_syslog.SnakeLogSyslog

In order to enable the logging you will also need to put the directive:

SnakeLogSyslog on

either in the main configuration file, or in a .htaccess file. If it is in the main configuration file, the syslog logging will be enabled for the entire server, otherwise it will be bound by the same restrictions that other modules in .htaccess or <Directory> blocks are.

Let's examine the module piece by piece to understand what it does:

class SnakeLogSyslog:

This defines the class which is represented as a 'module'. Since each source file may contain multiple PyMods which may be imported, we use the class to designate a specific module. This coorelates directly to the SnakeModule mod_snake_log_syslog.SnakeLogSyslog directive. We could combine all of our modules into 1 big module called mod_snake_all, and then simply place directives like, SnakeModule mod_snake_all.SnakeLogSyslog and SnakeModule mod_snake_all.SnakeAuthMeNow in our configuration files.

directives = { 'SnakeLogSyslog' : (mod_snake.OR_ALL, mod_snake.FLAG, self.cmd_snakeLogSyslog), }

module.add_directives(directives)

It is very convenient for modules to be able to specify directives that may be used from configuration files. The directives dictionary specifies a key-val pair, with the key being the directive name, and the value being a tuple defining where the directive is valid, and what types of arguments the directive takes. In the above case, we would like the directive 'SnakeLogSyslog' to be available from any configuration entity (main config, .htaccess), and take 1 argument, either 'on' or 'off'. See the mod_snake_api document for more information about these flags.

The next line: module.add_directives(directives), tells mod_snake to insert these directives into its own internal list, so that Apache can use them.

hooks = {'create_dir_config' : self.create_dir_config, 'open_logs' : self.open_logs, 'log_transaction' : self.log_transaction }

for hook in hooks.keys():

module.add_hook(hook, hooks[hook])

Hooks are Apache's means of calling back to the module when a certain Apache phase has been called. In the aforementioned code, we register the following hooks:

• create_dir_config: This allows us to use per-directory configuration mechanisms that we specify. This routine gets called when Apache wants to give the module a chance to create its own configuration.
• open_logs: After Apache is done reading the main configuration files, it gives modules a chance to open up logs before it switches to a more secure state.
• log_transaction: After the request has been processed and completed, Apache calls this phase to let modules do any custom logging.

cmd_SnakeLogSyslog(self, per_dir, per_svr, on_or_off):

'cmd_SnakeLogSyslog: enable or disable special syslog logging'

This is the function which gets called when Apache reaches the directive 'SnakeLogSyslog' in any configuration file. The arguments that are passed in are:

• per_dir: The per-directory configuration information that we returned from a call to our create_dir_config hook
• per_svr: Per-server configuration information. Since no create_svr_config hook was bound to, this argument holds no value.
• on_or_off: A true-false value indicating what argument was specified to the configuration directive. on=true, off=false.

The subsequent doc-string is used when Apache detects that invalid arguments were passed to the directive. Apache will use this string to alert the user about how the function should have been called.

per_dir['enabled'] = on_or_off

For each configuration entity, main config, .htaccess, etc. where we have enabled or disabled our module via the SnakeLogSyslog directive, this routine gets called. We set how it was called in our per-directory configuration information, so we can use it later when our hooks get called.

def create_dir_config(self, path):

return { 'path' : path, 'enabled' : 0 }

The duty of this routine is to return our own defined configuration information back to Apache. We can return anything we like from this routine. In this case, we return enabled == 0 so that our default (i.e. no SnakeLogSyslog directive) is to not log to the syslog. The path argument, passed to the create_dir_config handler is the path where the configuration is defined. This can often be 'none' to indicate that the per-dir configuration is for the main configuration file.

def open_logs(self, per_svr, module):

syslog.openlog('SnakeSyslog')

This routine gets called by Apache when it is time to open logging files. In our case, we establish the connection with the syslog.

def log_transaction(self, per_dir, per_svr, request_rec):

if per_dir['enabled']:

conn = request_rec.connection

syslog.syslog('%s - %s' % (conn.remote_ip, request_rec.uri))

This handler gets called after all request processing has been done, and it is time to log the transaction. We first check to see if we are enabled (i.e. the SnakeLogSyslog directive has been set to 'on'), and if so, we log the transaction.