Doco, and minor bugfixes and updates. Prepare for Beta Release
This commit is contained in:
parent
d39a1c3cbb
commit
f322b0c41a
2 changed files with 480 additions and 0 deletions
1
.gitattributes
vendored
1
.gitattributes
vendored
|
@ -3,6 +3,7 @@
|
|||
/COPYING -text
|
||||
/ChangeLog -text
|
||||
/LICENSE -text
|
||||
/LogServ.README -text
|
||||
/LogServ.README.html -text
|
||||
/LogServ.xml -text
|
||||
/Makefile.in -text
|
||||
|
|
479
LogServ.README
Normal file
479
LogServ.README
Normal file
|
@ -0,0 +1,479 @@
|
|||
|
||||
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
|
Reference in a new issue