***************************************************************** Channel member list dumper, activeusers.txt -- Documentation ***************************************************************** Table of contents: ------------------ 1. Short description 2. Files in this package 3. Authors & credits 4. Feedback 4.1. Bugs 4.2. Questions and opinions 5. Requirements 6. Installation 7. Configuration 8. Output file syntax 8.1. Plain-text database file 8.2. XML file 9. Change log ================================================================= 1. Short description ================================================================= Dumps a channel member list into a parsable file including member name, connection time, idle time and channel prefixes if present. Comes with XML support. Optionally, the permission of each given file can be set to a specified mode on *NIX systems. ================================================================= 2. Files in this package ================================================================= You might not understand all the things I wrote here, but that's certainly no problem. I'll clarify everything later. activeusers.c The source code of the module activeusers.php An example parser script written in PHP activeusers.txt This documentation activeusers.xsl An example style sheet for the XML output ================================================================= 3. Authors & credits ================================================================= The module was requested by Serevinus and written by AngryWolf (me) . The example php (activeusers.php) script was written by xsr. Rafe helped a lot to add XML support: the output is based on his example XML file and the example XSL style sheet (activeusers.xsl) was also written by Rafe originally, I've just made minor changes in it. Thanks to everyone for the help! ================================================================= 4. Feedback ================================================================= 4.1. Bugs --------- If you find bugs, please read http://www.angrywolf.org/bugs.php first, then report them at http://angrywolf.clanintern-irc.de/. 4.2. Questions and opinions --------------------------- I accept questions and opinions either on my forum, http://unrealircd.proboards24.com/, or privately by email (see my email address at section 2). ================================================================= 5. Requirements ================================================================= * Unreal >=3.2-beta18 * One of the supported operating systems (see unreal32docs.html) ================================================================= 6. Installation ================================================================= See http://angrywolf.linktipp.org/compiling.php?lang=en ================================================================= 7. Configuration ================================================================= Add the directives below to your UnrealIRCd configuration (either in unrealircd.conf or an other file that you include in unrealircd.conf, it's up to you): set { activeusers { /* * update-frequency ; [REQUIRED] * * This allows you to set the update frequency of the * output file(s). Note: a /rehash will reset the time * counters. You can use the usual measure units (s, * m, h, d) as well. */ update-frequency 5m; /* * show-realhost yes|no; [OPTIONAL] * * Enables showing users' real hostnames instead of * their virtual (or cloaked) hosts. */ show-realhost no; /* * monitorchan { ... }; * * This is the block where you can assign channels with * output files. You can use as many monitorchan blocks * as you want. Each block has a value, namely a channel. * Therefore you must enclose it in quotes. Example: */ monitorchan "#channel" { /* * db-file ; [OPTIONAL] * * The relative or absolute path of a plain-text * database file where the members of the channel * are dumped into. The output format, which is * explained in chapter 8, is designed for scripts. * See activeusers.php for a sample parser script * written in PHP. */ // db-file "data/channel.db"; /* * xml-file ; [OPTIONAL] * * If you wouldn't like to write a parser script, * you can simply choose this XML format. Then, * it's your own decision to write a file that * will describe how to display this XML document. */ xml-file "data/channel.xml"; /* * xsl-file ; [OPTIONAL] * * This allows you to include a line in the XML * output to tells web browers to use an XSL * style sheet to present data. Because the path * of the XSL file may vary per web servers, this * directive allows you to set the correct path. * Its value is used in the "href" attribute of * the tag (see chapter 8). * * An example XSL style sheet (activeusers.xsl) * is included in the package to see how easy is * XSL to use. */ // xsl-file "activeusers.xsl"; /* * chmod ; [OPTIONAL] * * On non-Windows system you might want to set * the correct permissions of the output files * if the current umask setting is not appropriate * for them. Use an octal number in the usual way. */ // chmod 0640; }; }; }; ================================================================= 8. Output file syntax ================================================================= 8.1. Plain-text database file ----------------------------- Syntax in brief: ------------------------------------------------------------ ... ------------------------------------------------------------ This output format starts with a header line containing the last modification time of the database file (the time format is a timestamp, which means the number of seconds since 1st January 1970, 01:00) and the database update frequency (set::activeusers::update-frequency, also in seconds). Every other lines contain the member list including the nickname, username and hostname of a member, the time he/she connected to the network (timestamp), his/her idle time (a duration in seconds) and the prefixes in front of his name if the person has. Prefixes are: ~ = +q, & = +a (if PREFIX_AQ is enabled), @ = +o, % = +h, and + = +v. Connection time is a timestamp containing a full date, while idle time is a duration (a period of time calculated by substracting the time now and the last time a RESETIDLE was received from the client). Example output: --------------------------------------------- 1061796738 10 AngryWolf ~wolf wolves.net 1061795128 70 @+ Friend someone somewhere.net 1081744338 99 --------------------------------------------- 8.2. XML file ------------- If you don't know what is XML, then this output format might not be for you. You should at least know something about the XML syntax, or you won't understand things described here. There are many tutorials on the net that you can find with Google. Example: http://www.w3schools.com/xml/default.asp To understand the format that the XML output uses is very easy. You will see that the XML declaration uses the ISO-8859-1 (Latin-1/West European) character set, which should be suitable for every UnrealIRCd networks: The next line is only displayed if you set a value for set::activeusers::monitorchan::xsl-file. It tells the browser what XSL style sheet to use, like so: Every data is in the root element. It has a
child element that contains the last modification time () and the update frequency (() of this document. Example:
2004-07-03 00:56:14 1 minute
Then come the details of the channel members one by one in a element, including their nickname (, ident (or user) name (), (cloaked or real) hostname or IP address (), the date and time they connected to the network (, their idle time and channel prefixes if they have any (). Finally, the closing tag. Example: TestBot testbot anope.org 1970-01-01 01:02:18 12601 days 22 hours 15 minutes 1 second &@ AngryWolf ~wolf netadmin.test.com 2004-07-03 00:45:29 10 minutes 44 seconds ~@ ================================================================= 9. Change log ================================================================= $Log: activeusers.txt,v $ Revision 3.2 2004/07/12 17:39:12 angrywolf - Fixed a configuration parser bug that wanted both db-file and xml-file to be present in the monitorchan block (reported by Rafe). Revision 3.1 2004/07/03 10:41:25 angrywolf - Fixed some possible memory leak bugs in the configuration parser code. - Added XML support. Thanks to Rafe for his help on this. - Wrote a new, separate documentation and added active.php as activeusers.php in the package. Revision 2.6 2004/03/08 21:19:39 angrywolf - Fixed some bugs that could cause crash if you compile the module statically (for example, under Windows). Revision 2.5 2004/02/03 10:07:26 angrywolf - Windows compilation fixes. Revision 2.4 2003/11/29 19:22:19 angrywolf *** empty log message *** Revision 2.3 2003/11/29 19:20:14 angrywolf - Fixed a win32 crash bug regarding ModuleGetError, reported by TuX. Revision 2.2 2003/09/22 05:25:52 angrywolf - Updated module to use the new MOD_* macros. - Renamed set::activeusers::every to set::activusers::update-frequency. - Added support for dumping usernames and hostnames of users (suggested by LRL). Also added directive set::activeusers::show-realhost to output real hostnames instead of virtual ones if needed. Revision 2.1 2003/08/31 20:13:55 angrywolf - From now on, I'm using RCS 2003-08-30: Documentation updates 2003-08-25: A small fix to display idle time correctly 2003-08-25: A fix to disable chmod on AMIGA systems 2003-08-25: Made it so update frequency is printed to the header line of the output file 2003-08-25: Coded module activeusers (requested by Serevinus) ================================================================= $Id: activeusers.txt,v 3.2 2004/07/12 17:39:12 angrywolf Exp $