479 lines
18 KiB
Text
479 lines
18 KiB
Text
|
|
LogServ Manual
|
|
_________________________________________________________________
|
|
|
|
1. Prerequisites and Installation.
|
|
|
|
1.1. Compiling and Installation
|
|
|
|
2. Basic Configuration
|
|
|
|
2.1. LogType
|
|
2.2. LOGSIZE SETTING
|
|
2.3. LOGAGE SETTING
|
|
|
|
3. Configuring LogServ to Log Individual Channels
|
|
|
|
3.1. Adding a Channel
|
|
3.2. Deleting a Channel
|
|
3.3. Changing Channel Settings
|
|
3.4. Viewing the Channel List
|
|
|
|
4. Misc Commands
|
|
|
|
4.1. STATS
|
|
4.2. VERSION
|
|
4.3. ABOUT
|
|
|
|
5. LogFile Parsers
|
|
|
|
Welcome to the LogServ Manual. This document will aid you in setting
|
|
up and running LogServServ on your IRC network.
|
|
|
|
LogServ is a basic Channel Logging Module for the NeoStats Services
|
|
that can log channel activity to a log file for processing by 3rd
|
|
party programs such as Onis or MircStats. These programs can then
|
|
produce HTML pages with interesting statistics on the channel
|
|
activities.
|
|
|
|
LogServ is flexible in the logging of channels, and can produce log
|
|
files in the same format as Xchat, Mirc, EggDrop, or our own custom
|
|
logging format, meaning you should be able to use just about any IRC
|
|
Log Parsing program to produce statistics for you.
|
|
|
|
Additionally, LogServ can rotate log files based on log file size or
|
|
age, and place them in a different directory for processing at any
|
|
time.
|
|
|
|
We recomend that you use the Onis Log file parser, as its what we have
|
|
done our testing with, and additionally, has several neat features
|
|
that are applicable to logging lots of channels. These are:
|
|
* Persistance. You don't need to keep old log files around if you
|
|
wish your statistics to have a long history, thus saving you
|
|
valuable file system space
|
|
* Easily Customizable with stylesheets
|
|
* Easily scriptable for processing many channels at once
|
|
|
|
We have provided a sample shell script and Onis configuration file to
|
|
automatically parse your log files in one go, producing the required
|
|
output.
|
|
|
|
LogServ is Copyright, 2003 by Justin Hammond.
|
|
|
|
1. Prerequisites and Installation.
|
|
|
|
LogServ is designed to run on Top of NeoStats. The Following
|
|
requirements at the time of writing are required for NeoStats:
|
|
* A Linux or BSD based Server or Shell.
|
|
* A supported IRCd. Currently, Hybrid7, Unreal, Ultimate2.x or
|
|
Ultimate3.x or NeoIRCd
|
|
* Some basic Unix administration Skill
|
|
* Of Course, a IRC network to connect it all together.
|
|
* Spare disk space and a webserver to display the output
|
|
* A log file parser such as Onis
|
|
|
|
Please refer to the NeoStats website for more information on the
|
|
requirements
|
|
|
|
1.1. Compiling and Installation
|
|
|
|
As long as you have successfully setup NeoStats, and installed it
|
|
correctly, Compiling LogServ is very simple and straight forward.
|
|
First you must extract the files from the download package. This is as
|
|
simple as:
|
|
bash$ tar -xzf LogServ-<ver>.tar.gz
|
|
|
|
This should then create a directory called LogServ-<version> where
|
|
<version> is the Version of LogServ. Then Proceed to Change into the
|
|
LogServ directory, and run Configure as follows:
|
|
bash$./configure [--enable-debug | --with-neostats=<dir>]
|
|
|
|
--enable-debug is only useful for diagnostics purposes when used in
|
|
conjunction with debugging tools. There should be no need to use this
|
|
option on a day to day basis
|
|
|
|
--with-neostats=<dir> should be used if your neostats directory is not
|
|
in a standard location (~/NeoStats/). Replace <dir> with the full path
|
|
to your NeoStats installation directory (NOT SOURCE DIRECTORY)
|
|
|
|
Configuring LogServ will look something like the following screen:
|
|
[Fish@fish-dt]$ ./configure
|
|
checking for gcc... gcc
|
|
checking for C compiler default output... a.out
|
|
checking whether the C compiler works... yes
|
|
checking whether we are cross compiling... no
|
|
checking for suffix of executables...
|
|
checking for suffix of object files... o
|
|
checking whether we are using the GNU C compiler... yes
|
|
checking whether gcc accepts -g... yes
|
|
checking for gcc option to accept ANSI C... none needed
|
|
checking for a BSD-compatible install... /usr/bin/install -c
|
|
checking for pcre_compile in -lpcre... yes
|
|
checking Location of NeoStats...... /home/fish/NeoStats/
|
|
checking for /home/fish/NeoStats//include/dl.h... yes
|
|
checking Version of NeoStats...... Compatible Version
|
|
checking Whether to Enable Debuging...... no
|
|
configure: creating ./config.status
|
|
config.status: creating Makefile
|
|
|
|
(*----------------------------------------------------------*)
|
|
(| To compile your module, please type 'make' |)
|
|
(| If make completes without errors, then you |)
|
|
(| Must 'make install', but please be sure that NeoStats |)
|
|
(| Is not currently running with a module of the same name |)
|
|
(| Running, otherwise Make install will not work |)
|
|
(| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |)
|
|
(| If you are running a BSD, make install may produce a |)
|
|
(| Error, if that is the case, then please manually copy |)
|
|
(| opsb.so to the NeoStats/dl directory |)
|
|
(| !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! |)
|
|
(*----------------------------------------------------------*)
|
|
(| For Support please visit: |)
|
|
(| IRC: /server irc.irc-chat.org |)
|
|
(| #neostats channel |)
|
|
(| WWW: http://www.neostats.net/boards/ |)
|
|
(*----------------------------------------------------------*)
|
|
(|This Module was written by: |)
|
|
(| fish (fish@dynam.ac) |)
|
|
(*----------------------------------------------------------*)
|
|
|
|
If the configuration did not produce a error, you may then move onto
|
|
Compiling LogServ. Compiling is simply just issuing the "make" command
|
|
(or "gmake" if you are running BSD):
|
|
[Fish@fish-dt]$ make
|
|
gcc -c -O2 -Wall -g -ggdb -I/home/fish/NeoStats//include/ -I. logserv.c
|
|
gcc -c -O2 -Wall -g -ggdb -I/home/fish/NeoStats//include/ -I. log_processing.c
|
|
ld -shared -o logserv.so logserv.o log_processing.o
|
|
|
|
again, check for Error messages. As long as there are not error
|
|
messages, "make install" will install LogServ, this README file, and
|
|
any auxiliary files needed into your NeoStats directory:
|
|
[Fish@fish-dt]$ make install
|
|
/usr/bin/install -c -m 644 LogServ.so /home/fish/NeoStats//dl/
|
|
/usr/bin/install -c -m 644 README.LogServ /home/fish/NeoStats//dl/../doc/
|
|
|
|
If you receive *ANY* errors at all during the this process, please
|
|
post them on our Support boards, at http//www.neostats.net/boards/
|
|
|
|
Once Installation is complete, you can either configure NeoStats to
|
|
load LogServ when it starts, or load LogServ via IRC.
|
|
|
|
To Configure NeoStats to automatically load LogServ when it boots, add
|
|
the following line to your "neostats.cfg" file in the NeoStats
|
|
directory:
|
|
|
|
LOAD_MODULE logserv
|
|
|
|
To load LogServ via IRC, you must make sure you have the appropriate
|
|
permissions and issue the following command:
|
|
|
|
/msg neostats load logserv
|
|
|
|
Thats it. LogServ is now loaded and ready for use
|
|
|
|
2. Basic Configuration
|
|
|
|
LogServ is completely configured online via IRC. When you first start
|
|
up LogServ, it attempts some "Sane" defaults for you get started with,
|
|
but you should always review these settings as soon as you install.
|
|
There are a few important settings you may want to review right away.
|
|
They are:
|
|
* LogType is the format we should be logging as (Xchat, Mirc,
|
|
EggDrop, or LogServ)
|
|
* Logfile size to rotate at (1Mb by default)
|
|
* Logfile age to rotate at (1Hr by default)
|
|
|
|
These are outlined below:
|
|
|
|
2.1. LogType
|
|
|
|
Logtype is the format you wish to perform your logging in. By default,
|
|
LogServ logs using its own internal logfile format, but as of
|
|
writting, no external logfile parser supports that format, so you are
|
|
advised to change it. There are four possible choices:
|
|
* 0 - LogServ Format. Our own Logging file format
|
|
* 1 - EggDrop Format. The Same logging format as the popular EggDrop
|
|
Bot
|
|
* 2 - Mirc Format. This is the same format as the mirc 6.0 series
|
|
* 3 - Xchat Format. This is the same format as Xchat 2.0.5 IRC
|
|
client
|
|
|
|
Warning
|
|
Changing the LogType is imediate, and all new entries into a
|
|
logfile will start with the new format imediatly. You should stop
|
|
NeoStats, and remove the files in NeoStats/logs/chanlogs/
|
|
directory after changing this setting, so when you next process
|
|
your log files, it will not be confused by the changing formats.
|
|
|
|
Changing the LogFile Format
|
|
|
|
Before starting to log any channels, you should select which format
|
|
you wish to log in. We recomend Xchat format. To change the LogType,
|
|
issue the following command:
|
|
/msg LogServ set logtype <type>
|
|
|
|
Where:
|
|
|
|
<type> = The Logging format time, indicated by a number from 0 to 3,
|
|
representing the differnt formats available as outlined above.
|
|
|
|
The output is as follows:
|
|
>logserv< set logtype 3
|
|
-LogServ- LOGTYPE set to 3
|
|
|
|
Viewing the current Logtype setting
|
|
|
|
To view the current logtype selected, simple type:
|
|
/msg LogServ set list
|
|
|
|
And all the current settings (the rest will be explained later in this
|
|
document) are displayed. The output is as follows:
|
|
>LogServ< set list
|
|
-LogServ- Current LogServ settings:
|
|
-LogServ- LOGTYPE: 3 Log Type
|
|
-LogServ- LOGSIZE: 2000 Bytes
|
|
-LogServ- LOGAGE: 3600 Seconds
|
|
|
|
2.2. LOGSIZE SETTING
|
|
|
|
LogServ stores logs in two places on your Shell. Live logs, or logs
|
|
that are currently being written are stored in the
|
|
~/NeoStats/logs/chanlogs/ directory, and these the logs that are
|
|
currently being updated. When the log reaches a certian size, or age,
|
|
it is closed, and moved to a the ~/NeoStats/ChanLogs/ directory where
|
|
you can process the log files. The LogFile size settings specifies how
|
|
big a "live log" is allowed to reach before it is moved to the final
|
|
directory. By default, LogServ will rotate all files larger than 1Mb,
|
|
and this should be satisfactory for most users.
|
|
|
|
Changing the LogSize to switch at.
|
|
|
|
To change the size at which a logfile will switch at, use the
|
|
following format:
|
|
/msg SecureServ set logsize <bytes>
|
|
|
|
Where:
|
|
|
|
<bytes> = if the file is larger than this size, it is "swapped"
|
|
|
|
The output is as follows:
|
|
>logserv< set logsize 20000
|
|
<LogServ> LOGSIZE set to 20000 by Fish
|
|
-LogServ- LOGSIZE set to 20000
|
|
|
|
Viewing the current setting
|
|
|
|
Please refer to the previous section.
|
|
|
|
2.3. LOGAGE SETTING
|
|
|
|
In addition to the logsize setting above, LogServ will rotate a
|
|
logfile after it has been opened for a period of time. This is so
|
|
channels that might not have much activity still get a chance to be
|
|
updated often.
|
|
|
|
The logage setting can be changed via:
|
|
/msg LogServ set logage <seconds>
|
|
|
|
Where:
|
|
|
|
<seconds> = The number of seconds the log file must be opened for
|
|
before rotating. Minium value is 5 minutes, but its recomended not to
|
|
go under 1 Hour (3600 seconds)
|
|
|
|
The output is as follows:
|
|
>LogServ< set logage 7200
|
|
<LogServ> LOGAGE set to 7200 by Fish
|
|
-LogServ- LOGAGE set to 7200
|
|
|
|
3. Configuring LogServ to Log Individual Channels
|
|
|
|
Obviously, we dont want to log every single IRC channel on the
|
|
network, so you have to tell LogServ what channels you wish to Log.
|
|
This is fairly basic. You have 4 options:
|
|
* Add A channel
|
|
* Delete A channel
|
|
* Change a Channels settings
|
|
* View the Channel list.
|
|
|
|
Each Setting is described in the following section.
|
|
|
|
3.1. Adding a Channel
|
|
|
|
Adding a Channel to be logged is instantanous, and the channel will
|
|
begin logging straight after this command has complete. LogServ will
|
|
join the channel, but not give itself any channel modes, so the
|
|
channel owner can decide if it should be OP'd or not.
|
|
|
|
The Syntax is:
|
|
/msg LogServ chans add <name> <public> <url>
|
|
|
|
Where:
|
|
|
|
<name> = The name of the channel you wish to Log. Must exist on the
|
|
IRC network.
|
|
|
|
<public> = Indicates weather to show the channel to non-privledged
|
|
users in the channel logging list or not. Either the words "public" or
|
|
"private". If a invalid entry is specified, defaults to Public.
|
|
Currently doesn't do anything.
|
|
|
|
<url> = For informational purposes only. Displays the Web Address that
|
|
users can visit to view the channel statistics.
|
|
|
|
The output is as follows:
|
|
>logserv< chans add #ircop public http://www.neostats.net
|
|
<LogServ> Fish used CHANS
|
|
-LogServ- Stats URL is set to http://www.neostats.net
|
|
-LogServ- Now Logging #ircop
|
|
<LogServ> Fish Activated Logging on #ircop
|
|
|
|
And the channel members of #ircop shall see:
|
|
--> LogServ (LogBot@stats.dynam.ac) has joined #ircop
|
|
-LogServ/#ircop- Fish Actived Channel Logging on #ircop
|
|
-LogServ/#ircop- Stats will be avaiable at http://www.neostats.net when Logs ar
|
|
e processed next
|
|
|
|
3.2. Deleting a Channel
|
|
|
|
Deleting a channel from LogServ means it will no longer log any
|
|
activity in that channel. If the channel is currently active, LogServ
|
|
shall part the channel, Close the "live log" and move it to its
|
|
processing directory.
|
|
|
|
The Syntax is:
|
|
/msg LogServ chans del <name>
|
|
|
|
Where:
|
|
|
|
<name> = The name of a channel we are currently logging.
|
|
|
|
The output is as follows:
|
|
>LogServ< chans del #ircop
|
|
<LogServ> Fish used CHANS
|
|
-LogServ- Deleted Channel #ircop
|
|
<LogServ> Fish deleted #ircop from Channel Logging
|
|
|
|
3.3. Changing Channel Settings
|
|
|
|
You can change the URL location displayed when viewing the channel
|
|
list using the chans set command.
|
|
|
|
The Syntax is:
|
|
/msg logserv chans set URL <name> <newurl>
|
|
|
|
Where:
|
|
|
|
<name> = The channel name you wish to alter
|
|
|
|
<newurl> = The new URL you wish to set.
|
|
|
|
The output is as follows:
|
|
<LogServ> Fish used CHANS
|
|
-LogServ- Changed URL for #blah to: http://nowhere.com
|
|
<LogServ> Fish changed the URL for #blah to: http://nowhere.com
|
|
|
|
3.4. Viewing the Channel List
|
|
|
|
The channel list can be viewed by issuing the following command:
|
|
/msg logserv chans list
|
|
|
|
The output is as follows:
|
|
-LogServ- Monitored Channel List:
|
|
-LogServ- #blah (-) URL: http://nowhere.com
|
|
-LogServ- #bl (-) URL: None
|
|
-LogServ- #ircop (*) URL: http://www.neostats.net
|
|
-LogServ- End Of List.
|
|
|
|
The (-) or (*) indicate if the channel is currently active.
|
|
|
|
4. Misc Commands
|
|
|
|
There are several other commands available. These are documented
|
|
below:
|
|
|
|
4.1. STATS
|
|
|
|
The stats command shows some basic stats about the Logging Activities.
|
|
With future versions its expected the amount of information will
|
|
increase with this command.
|
|
|
|
The Syntax is:
|
|
/msg LogServ stats
|
|
|
|
And the output is
|
|
<LogServ> Fish used STATS
|
|
-LogServ- LogServ Stats:
|
|
-LogServ- Monitoring 3 channels
|
|
|
|
4.2. VERSION
|
|
|
|
This displays LogServ's Version number
|
|
|
|
The Syntax is:
|
|
/msg LogServ version
|
|
|
|
And the Output is:
|
|
<LogServ> Fish used VERSION
|
|
-LogServ- LogServ Version Information
|
|
-LogServ- LogServ Version: $Rev: 19 $ Compiled Jan 13 2004 at 20:08:11
|
|
|
|
4.3. ABOUT
|
|
|
|
This displays a brief message to users describing the function of
|
|
LogServ:
|
|
|
|
The Syntax is:
|
|
/msg LogServ About
|
|
|
|
And the output is:
|
|
<LogServ> Fish used ABOUT
|
|
-LogServ- LogServ logs channel activities to produce HTML pages describing some
|
|
interesting Statistics
|
|
-LogServ- about that channel. If you wish to have your channel logged,
|
|
-LogServ- please contact the Network Adminstration
|
|
|
|
5. LogFile Parsers
|
|
|
|
As mentioned in the introduction, LogServ only generates Log files,
|
|
you still need to get some program to create the HTML pages from the
|
|
logfiles.
|
|
|
|
We currently recomend Onis for parsing the logfiles. You can obtain a
|
|
copy of Onis from http://verplant.org/onis/
|
|
|
|
We have provided a Sample Onis Configuration based on Onis 0.4.9, and
|
|
a shell script that can be executed by Crontab to process all your
|
|
Logfiles. This sample configuration and Shell script are installed
|
|
into the ~/NeoStats/ChanLogs/ directory by default.
|
|
|
|
This shell script will automatically go through each of the channels
|
|
logs running Onis to update the HTML pages. At the top of the script
|
|
are some variables that should be setup to configure where you wish to
|
|
place the resultant HTML files, and where Onis is installed. You
|
|
should read the begining of the file OnisDoLogs.sh to figure out what
|
|
needs to be configured.
|
|
|
|
This shell script assumes that you have a webserver on the same shell
|
|
as NeoStats. If not, its upto the reader to implement some sort of
|
|
FTP/SCP script to transfer either the logfiles, or the output from
|
|
Onis to his webserver.
|
|
|
|
Additionally, if you are using a different LogFile parser, other than
|
|
Onis, you will have to develop your own script or method for updating
|
|
the HTML pages. If you do develop a script for another Logfile
|
|
Processor, please send us a copy, so we may include it in future
|
|
versions.
|
|
|
|
The logs for each channel are placed into their own directory within
|
|
the ChanLogs directory, so if you are logging #neostats, The logfiles
|
|
would be placed in ChanLogs/#neostats.
|
|
|
|
Warning
|
|
|
|
# is a special charactor on most shells and needs to be escaped. So if
|
|
you wish to change directory to #neostats, you would actually type cd
|
|
\#neostats. Keep this in mind when developing any scripts.
|
|
|
|
Each Logfile is timestamped with the time it was rotated out of the
|
|
logs/chanlogs/ directory, with the format <name>-YYMMDDHHMMSS.log
|