RageIRCd v2.0 (bluemoon): Dynamic Module Support
------------------------------------------------

$Id: dynamic-modules.txt,v 1.9.2.1 2005/02/21 02:32:45 amcwilliam Exp $
(C) 2000-2005 the RageIRCd Development Team, all rights reserved.

A lot of the code in RageIRCd v2.0 is now "modular". Provided dynamic 
module support was enabled at compile-time, this means server admins can 
load and unload portions of the server "on-the-fly", either via the 
/MODULE command, or via the modules{} config block.

Dynamic modules are an extremely advanced feature in RageIRCd, and you are 
strongly encouraged not to enable them unless you read the documentation 
provided, and learn how to configure them. Incorrect module config can 
result in weird results, or complete ircd failure.

Dynamic modules have both advantages and disadvantages. Enabling them will 
drastically increase the versatility and durability of your ircd. You can 
update your ircd on the fly without restarting, and you can "plug in" 
third party modules for extra, custom functionality. However, this can 
also lead to a minimal performance decrease, as well as a slightly 
increased level of memory usage.

When dynamic modules are enabled, all modules in the modules/ directory 
(those provided within the RageIRCd v2.0 distribution, and any custom 
modules inserted by you) will be compiled into separate "shared objects" 
(hence the .so suffix). These .so files are then installed into the 
modules/ directory from the top-level installation directory. All standard 
commands are installed to modules/commands.

These modules must be loaded into the ircd before it can begin serving. 
Required modules need to be loaded at runtime before ircd can start 
serving clients. It is therefore vital that your modules{} config block is 
setup correctly. See doc/example.conf for information on how to do so.

JOIN, KICK, MESSAGE, MODE, NICK, PART, PING, PONG, QUIT, and USER modules 
are "core" modules. Your ircd will not start up if they are not loaded at 
runtime.

Once your ircd is running, you can manipulate the modules on IRC via the 
/MODULE command. This command allows you to load new modules, list, unload 
and reload the current modules. "Core" modules can only be reloaded, not 
completely unloaded.

/MODULE LOAD <new-shared-object>
/MODULE UNLOAD <existing-shared-object>
/MODULE RELOAD <existing-shared-object>
/STATS M

WARNING: Be extremely careful when unloading or reloading modules. Due to 
the limitations in the way some operating systems handle shared objects, 
ircd may segfault if a module is replaced before it has been unloaded. To 
ease the chance of this, make install will not overwrite existing modules. 
Instead, it renames the entire modules installation directory, and 
installs the newly compiled modules to the standard directory. You can 
then rehash ircd, and it will unload the existing ones from memory, and 
load the newly installed modules.

Support will not be provided due to errors and stability issues as a 
result of using third party modules.

For security reasons, the /STATS M command is not restricted to opers. Any user
can perform this command. This allows, for example, private message loggers to
be seen.

End of document.
