Denora Modules
-- 
-------------

1) Introduction
2) Installation
3) Usage
4) Usage Example
5) More Modules
6) Support

1) Introduction

    Denora 1.0 onwards supports external modules. External modules are pieces
    of code that can be attached to a running Denora process dynamically. These
    modules can serve several purposes, and perform all kind of operations to
    enhance your network.

2) Installation

    1. If modules are supported by your system, they will be configured
       automatically when you run ./Config. The modules will be installed
       to the modules directory in your data path (by default this will
       be ~/stats/modules).

       Note: you might need to run "make distclean" prior to running ./Config

    2. Compile Denora as usual. The (g)make process will now compile module
       support into Denora, and compile the default sample modules, and/or
       any other module located on the modules folder ("src/modules/").

    3. Install Denora as usual. The install process will place the compiled
       modules in their runtime location, making them available for loading.

    4. Start or restart denora to make use of the new Denora executable.
       Note that you do not need to restart to load new or changed modules,
       only to make use of a new Denora executable.

3) Usage

    All module manipulation commands are done through StatServ. These are:

       MODLOAD     Load a module
       MODUNLOAD   Un-Load a module
       MODLIST     List loaded modules
       MODINFO     Info about a loaded module

    These commands available to Stats Admins only.

    You can also load (and pre-load) Modules automatically by loading them
    on startup. To do so, edit your denora.conf file and change the values
    of "autoload" and "delayed" in the modules block to include the modules 
    you want to load every time Denora starts.

4) Usage Example

    /msg StatServ modload ss_uptime
    *** Global -- from StatServ: trystan loaded module ss_uptime
    -StatServ- Module ss_uptime loaded

    /msg StatServ modinfo ss_uptime
    -StatServ- Module: ss_uptime Version: 1.0 Author: Trystan loaded: Dec 27 23:39:22 2005 CET
    -StatServ- Providing command: /msg Denora UPTIME

    /msg StatServ uptime
    -StatServ- Stats up 17 hours, 38 minutes, 36 seconds

    /msg StatServ modunload ss_uptime
    *** Global -- from StatServ: trystan unloaded module ss_uptime
    -StatServ- Module ss_utime unloaded

    /msg StatServ uptime
    -StatServ- Unknown command uptime. "/msg StatServ HELP" for help.

    * Note that the name of the module file is "ss_uptime.c", yet we load
      and reference the module as "ss_uptime" only. By naming convention
      modules have an abbreviated service name they attach to (ss_ for
      StatServ) followed by a descriptive keyword.

5) More Modules

    Denora ships with 2 sample modules that only illustrates some of the
    implemented module capabilities. They don not really do much or anything
    useful.

    You can download more useful modules from http://www.denorastats.org/. Just
    grab the module file (usually with a .c extension). Place the module
    file in your modules (src/modules) folder; the same folder that contains
    both ss_uptime.c and example.c module files.

    The new modules need to be compiled and installed before you can make
    use of them:

    1. Make sure you're in the main source directory. (usually Denora-1.X.XX/)
    2. Run `make modules` to compile any new or changed modules.
    3. Run `make install` to install the modules.

    You can now use /msg StatServ MODLOAD to load the new modules.

6) Support

    The Denora team is not responsible or liable for any unofficial module
    (i.e. anything other than what was released with the Denora package).

    Use modules at your own risk, and make sure you get them from a
    reputable source. You might get module support by contacting the module
    author, posting on our online forum, or maybe on our #Denora channel
    at /server irc.denorastats.org

