One Hat Cyber Team

Edit File: awstats_dev_plugins.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<meta content="AWStats Documentation about plugins development" name="description">
<meta content="awstats, awstat, log, file, analyzer, contrib, plugins, resources, maxmind, geoipfree, geoip, cities, regions, countries, frontend" name="keywords">
<meta content="index,follow" name="robots">
<meta content="AWStats Documentation - Plugins Development" name="title">
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>AWStats Documentation - Plugins Development</title>
<link type="text/css" href="styles.css" rel="stylesheet">
</head>
<body onload="prettyPrint()">
<table style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;" bgcolor="#ffffff" border="0" cellpadding="0" cellspacing="0" width="100%">

<tbody>
<tr style="font-family: arial,helvetica,verdana; font-style: normal; font-variant: normal; font-weight: normal; font-size: 10pt; line-height: normal; font-size-adjust: none; font-stretch: normal;">
<td align="center" bgcolor="#9999cc"><a href="/"><img src="images/awstats_logo1.png" border="0"></a></td>
<td align="center" bgcolor="#9999cc">
 
<font style="font-family: arial,helvetica,sans-serif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 16pt; line-height: normal; font-size-adjust: none; font-stretch: normal;" color="#eeeeff">AWStats logfile analyzer 7.8 Documentation 
 
</td>
<td align="center" bgcolor="#9999cc">
&nbsp;
</td>
</tr>
</tbody>
</table>
 
 
<h1 style="font-family: arial,helvetica,sanserif; font-style: normal; font-variant: normal; font-weight: normal; font-size: 26px; line-height: normal; font-size-adjust: none; font-stretch: normal;">Plugin
Development</h1>
AWStats has a very flexible plugin architecture that is easy to use and
allows for powerful extensibility. Here is the information you need to
get&nbsp;started rolling your own. In this documentation, the terms
plugin and module will be used interchangeably. 
 
<ul>
<li><a href="#Plugin_Files_Location">Plugin Files,
Location</a></li>
<li><a href="#Hooks">Hooks</a></li>
<li><a href="#Required_Variables">Required
Variables</a></li>
<li><a href="#Accessible_Variables">Accessible
Variables</a></li>
<li><a href="#Accessible_Functions">Accessible
Functions</a></li>
<li><a href="awstats_dev_plugins_hooks.html">Available
Hooks</a></li>
</ul>
 
<a name="Plugin_Files_Location"></a>Plugin Files,
Location 
<hr>AWStats plugins are implemented as Perl modules with a file
extension of .pm. Every time you run AWStats, either in update mode or
HTML output mode, the configuration file will be parsed for the names
of plugins to load. Then AWStats will scan the plugins folder for
matching modules and load them into memory, executing hooks at the
appropriate time during a run. Thus, when you create a plugin, you have
to store the file in the plugins directory under the folder where
awstats.pl resides. 
 
<a name="Hooks"></a>Hooks 
<hr>In order to be useful, your&nbsp;plugin must implement
any number
of different "hooks" that will be called at various points during the
AWStats run. A hook is simply a Perl sub routine that will receive
various parameters, perform whatever actions you desire such as
calculations, modifications or output, and optionally return a value. 
Note: all
plugins MUST implement the Init_
hook to initialize the module and determine if the plugin will run
under the current version of AWStats. 
For information on the available hooks, <a href="awstats_dev_plugins_hooks.html">view the Hooks
document.</a> 
<a name="Required_Variables"></a> 
Required
Variables 
<hr>Each plugin must implement three required, local variables
including the name, hooks, implements and required AWStats Version.
Typically you implement these at the top of your plugin file as in this
example code: 
 
<code class="prettyprint">#----------------------------------------------------------------------------- 
# PLUGIN VARIABLES 
#----------------------------------------------------------------------------- 
# &lt;----- 
# ENTER HERE THE MINIMUM AWSTATS VERSION REQUIRED BY YOUR PLUGIN 
# AND THE NAME OF ALL FUNCTIONS THE PLUGIN MANAGE. 
my $PluginNeedAWStatsVersion="5.5"; 
my $PluginHooksFunctions="GetCountryCodeByAddr GetCountryCodeByName
ShowInfoHost"; 
my $PluginName = "geoipfree"; 
my $PluginImplements = "mou"; 
# -----&gt;</code> 
 
The $PluginNeedAWStatsVersion
indicates the minimum version of AWStats that your plugin requires to
run properly. If a user attempts to implement your plugin with an older
version of the program, the plugin will not load. 
 
$PluginHooksFunctions
is a space delimited list of the different hooks that your plugin will
implement. This list should only include names defined in the <a href="awstats_dev_plugins_hooks.html">hooks&nbsp;list</a>.
You should not list any private module functions or
the Init_
hook in this list. The naming convention for all hooks is HookName_PluginName.
The hooks like only includes the hook name without the underscore. 
 
$PluginName
is simply the name of your plugin, exactly as it appears in the hooks
and file name. This will be used by AWStats on load. 
 
$PluginImplements
is a list of letter codes mapped to operations that your plugin
performs. Without at least one of these letter codes, your plugin will
never run. The codes are: 
<ul>
<li>"m" - a Menu Handler plugin that
provides links to navigate around reports. The plugin will be called
any time a menu is displayed, such as in the left frame in cgi mode or
top navigation in static mode.&nbsp;</li>
<li>"o" - an Output plugin that will be loaded when AWStats is
generating a report via dynamic CGI or static HTML</li>
<li>"u" - an Update plugin that will process data and is run
when AWStats is parsing log files and updating the history data files.</li>
</ul>
<a name="Accessible_Variables"></a>Accessible Variables 
<hr>Your plugin has access to all of the global variables
declared at
the top of the AWStats.pl program. While you can write to these
variables, it's best to only read them as another plugin may make
unexpected modifications. However you can declare global variables
within your own plugin and share those across other plugins. Just
declare them inside the normal use
vars qw/ ... / block within your own module. 
 
Thus you can (and should) use settings from the configuration file and
determine the debug level. 
 
<a name="Accessible_Functions"></a>Accessible Functions 
<hr>Plugins have access to all of the functions declared in the
main
AWStats.pl file. For debugging and error handling, you should use the debug and error functions.
Below are some common functions that plugins take advantage of
(remember you don't have to re-invent the wheel): 
 
debug("debug message", debug_level)
- Writes the "debug message" to the standard output if the (integer)
debug_level is lower or equal to that set by the user at runtime. The
higher the debug level, the less important or more informational the
message. After outputting the message, the program continues running. 
 
error("error message")
- Writes the "error message" to the standard output and halts program
execution. 
 
Format_Bytes(bytes)
- Converts the incoming decimal value to Kilobytes, Megabytes,
Gigabytes and so forth. So if you put in 1024.5 it will spit out "1 KB" 
 
Format_Date(YYYYMMDDHHMMSS)
- Converts the incoming timestamps to something like 30 Apr 2010 - 16:55 
 
Format_Number(number) -
Adds commas or a user defined character where appropriate to separate
numbers for easier reading. 
 
<hr>

<div class="htmldoc-ignore">

Article written by <a href="https://www.destailleur.fr/awstats.php?category=awstats?rel=author" rel="author" style="color: #ccc; font-weight: normal;">Laurent Destailleur</a>. 
 

<a href="https://twitter.com/awstats_project" class="twitter-follow-button" data-show-count="false">Follow @awstats_project</a>
</div>

</body></html>