************************************************************************
** NeoStats - IRC Statistical Services                                **
** Copyright (c) 1999-2003 NeoStats Group. All Rights Reserved.       **
** This program and all associated documentation is free but          **
** copyrighted software; see the file COPYING for details.            **
** Homepage: http://www.neostats.net/                                 **
************************************************************************

Thank you for downloading NeoStats. 

NeoStats is a powerful and extendable set of *services* for IRC. By 
Services, we do not mean NickServ/Chanserv etc (although those are 
being developed) but additional services. Things like StatServ which 
give you information on the number of users/operators/channels/servers 
basically IRC statistics, or MoraleServ, which is a *fun* module, to 
send funny messages to users, and utility modules. Some modules have a 
useful function on your network, other modules are developed for fun, 
and to make your IRC network more attractive to users (thats whats it 
all about right?, IRC users?)

With the release of 2.5 series of NeoStats, several changes have taken 
place compared to the old version of NeoStats 2.0 series (don't ask me 
what happened to versions 2.1, 2.2, 2.3 or 2.4, I don't know!)

A detailed list of changes can be found in the ChangeLog file, but a 
brief summary is:
	-ServiceRoots support
	-External MOTD files
	-Module Segfault protection
	-CrossIRCD support. Support for more IRCD's than just Unreal
	-StatServ supports dumping Statistics to a HTML file for output 
	 (the output of the HTML file is based on a template)
	-Changes to the ModuleAPI that make it nicer
	-Channel Support!
	-StatServ supports Channel Statistics now!
	-Many bugfixes and changes to the internal NeoStats core
	-Many updates to the various Modules

Visit http://www.neostats.net for the latest news and NeoStats updates.

Please read all documentation included with NeoStats carefully. The 
documents contain all the information you need to get NeoStats running
on your network. These Documents include README, and all the documents in
the doc directory. 

All documentation applies to version 2.5.3 and higher. For older 
versions consult the documentation with that version or consider 
upgrading. New versions of NeoStats have many new features and bug 
fixes. We are not able to provide support for older versions of
NeoStats. 

Following is a quick guide to the main NeoStats documentation:

README -        This file. Contains NeoStats Installation and 
                configuration information and support information.
DOCS/USERMAN - 	Manual for run time operation of NeoStats. You should 
		        read this when you have NeoStats running for information
		        on how to use NeoStats.
DOCS/FAQ -      Frequently asked questions about NeoStats.
RELNOTES -      Release notes about the current version. This is 
		        displayed during the installation process but you
		        should refer to it if you have problems.
ChangeLog -     Information about what has changed between versions. Consult
			this document for detailed information about the 
			changes. Additionally, some modules contain Changelogs 
			in their directorys (eg, dl/statserv) so you should 
			consult these documents as well.                 
README.kptool - Description and instructions for maintaining NeoStat's
			Internal Database and Dynamic Configuration. 
			FOR ADVANCED USERS ONLY!
-----------------------------------<>-----------------------------------

Contents
--------

1. Installing and configuring NeoStats
	1.1 General notes
	1.2 Getting Started.
	1.3 Running configure
	1.4 Compiling NeoStats
	1.5 Installing NeoStats
	1.6 Setting up the neostats.cfg file
	1.7 Compiling additional modules
	1.8 Running NeoStats
	1.9 Notes for upgraders
2. Support Information
	2.1 Before contacting support
	2.2 Where to get support
	2.3 What to provide when requesting support.
3. Contributions


1. Installing and configuring NeoStats
--------------------------------------

This section explains how to install and configure NeoStats. We 
recommend that  you read this section in full before trying to 
install NeoStats.

If you have any problems NOT addressed in this or other documents,
please see the Support section for how to contact us for help.

1.1 General notes
-----------------

	All commands and filenames are case sensitive. This means
	that NeoStats, neostats and NEOSTATS are all different things.
	When typing commands you should use the same case as provided 
	in this file or things will not work correctly.

1.2 Getting Started
-------------------

	First, you need to uncompress NeoStats. To do this type the 
	following:

		tar xvfz NeoStats2.5.x.tar.gz 

	This will vary depending on the version you run of NeoStats. 
	Change the x in NeoStats2.5.x.tar.gz to match your filename 
	e.g. NeoStats2.5.3.tar.gz

	** Note: For some systems that don't run a new version of tar
	you need to do this:

		gzip -d NeoStats2.5.x.tar.gz
		tar xvf NeoStats2.5.x.tar

1.3 Running configure
---------------------

	The configure script has been changed compared to older 
	releases and you must now make sure you supply the right
	arguments to configure.

	To run configure this, you must first change to the directory 
	where you uncompressed NeoStats. e.g.

	cd ~/NeoStats2.5.3

	Your prompt should look something like:
	[user@host NeoStats2.5.3]

	Now type:
	./configure [options]
	
	You should read below for the options you need to pass to 
	configure.

	Required settings:
	------------------
	IRCD Support:
		To specify the IRCD you are compiling for. eg:

		    --enable-unreal - enable Unreal IRCD Support

		    --enable-ultimate2 - enable Ultimate 2.x.x IRCD Support

		    --enable-ultimate3 - enable Ultimate 3.x.x IRCD Support

		    --enable-hybrid7 - enable Hybrid7 IRCD Support

		    --enable-neoircd - enable NeoIRCd IRCD Support

		    (Note, at the time of release of this version of NeoStats
		    Ultimate 3.x.x was still in alpha, it is possible that 
		    Ultimate3 compatibility might break in future releases 
		    of Ultimate as it matures)

	Optional settings:
	------------------
	Privledge System:
		Originally, NeoStats was based on Operator Flags on a 
		network. If you had TechAdmin on Unreal, you were 
		basically allowed full control to Neostats. Now though,
		you can enable what is called External Authentication.
		This allows different ways of the NeoStats Privledge
		system.
		The Currently available options are:

		--enable-auth=sr 	This Enables a ServiceRoots 
			option, which a user must be identified to services
			(with the +r flag) and they will have full access
			to NeoStats.

		if you do not specify --enable-auth then it uses IRCD
		flags for access to NeoStats Default. This 	reverts back 
		to the old NeoStats Privledge system, where 
		Authenication is based on the users flags (+oOANs etc)

	Modules Support:
		NeoStats has an expanding set of modules. Some Modules
		have their own --enable options, while other modules
		do not.
		
		To enable a module at compile time (or multiple modules)
		use the following option:
			--enable-modules="modulenames"
	
		By Default, no modules are compiled. 
		
		NeoStats ships with the following modules:
		
			ConnectServ		--enable-modules="cs"
			HostServ		--enable-modules="hostserv"
			LoveServ		--enable-modules="loveserv"
			MoraleServ		--enable-modules="ms"
			spam			--enable-modules="spam"
			StatServ		--enable-modules="statserv"

		To compile multiple modules combine the enable-modules 
		options together as follows:
			
			--enable-modules="statserv spam"
			(this would enable the statserv and spam modules).
		
		If you have downloaded additional modules from the 
		NeoStats website, DO NOT specify them in the 
		enable-modules option. Each module has its own 
		configure script, and must be configured and 
		installed after NeoStats is installed. (See section
		6 and the documentation with the module).

	Debuging:
		Most users will never look at this option. It compiles
		NeoStats with debuging turned on. I would only suggest
		using this if you have problems are are about to fill
		out a bug form.
		--enable-debug		Enables Debugging

	XWindows Config Tool:
		To enable building of the configtool program (Needs X windows)
		--enable-configtool
	
	Enabling RAW command:
		We strongly recommend against the use of this option.
		Use of RAW commands can cause desync on your network 
		and badly formatted commands can crash your network.
		If you do enable this option, we will not provide any 
		support for your use of this command. Please
		do contact us for support of the RAW command.
	 	--enable-raw 

	This script will check to see if all necessary programs to run 
	NeoStats are installed on your system. A small note here, for 
	those of you who have emailed me paranoid, NeoStats DOES NOT 
	actually check your back account balance, nor can it.

1.4 Compiling NeoStats
----------------------

	Ok, you should now be back at a shell prompt, type:

	make

	it will go through the source and compile it into an
	executable binary file.	If you get some warnings, please
	ignore them -- we are working on the warnings.


1.5 Installing NeoStats
-----------------------

	If you are upgrading a working version of NeoStats. Please
	read section 1.9 Notes for Upgraders now.
	
	With version 2.5.0 and higher, NeoStats needs to be 
	"installed" into its own directory if you wish to use 
	additional modules. By default NeoStats will install into
	~/NeoStats/ (in your home directory, eg, /home/fish/NeoStats/)
	if you wish to change the install location, please see the
	section 2.

	To install NeoStats type:

	make install

	This will create the necessary files, and copy them to the
	installation directory. 
	
	

1.6 Setting up the neostats.cfg file
------------------------------------

	Now you should change to the installation directory
	(~/NeoStats/, or whatever you specified in ./configure)

	Once in this directory, you need to create a configuration
	file. You should run the makeconf script (./makeconf) and
	answer the questions. You must edit neostats.cfg to check 
	that everything is set the way you want it before NeoStats
	will run. You can do this with:
	
	pico neostats.cfg

	All the options are pretty self explanatory. if you have a 
	question please feel free to ask me. Once you are done 
	editting the file save it. 
	
	If using pico as in the previous example, press Ctrl-X then 
	hit Y and enter to save the file.

	NOTE: some additional modules have additional configuration 
	options that must be specified 	in the neostats.cfg file. 
	Please see the documentation for the individual modules on 
	available configuration options for the main NeoStats 
	distribution are:

	The available options are:

	SERVER_NAME	- Specifies the name of the NeoStats Server
				as it will apear on the network. 
		eg: SERVER_NAME stats.neostats.net		
			-When it links, it will apear as stats.neostats.net.

	SERVER_PORT	- Specifies the port to connect to on the
		                IRC Server
		eg: SERVER_PORT 6667		
			-When connecting, NeoStats will connect to port 6667

	CONNECT_TO	- Specifies the IP address to connect to.
		eg: CONNECT_TO 127.0.0.1	
			- This will force stats to connect to 127.0.0.1
	
	CONNECT_PASS	-Specifies the password used to connect. 
			This must match your CN lines in your 
			IRCD configuration
		eg: CONNECT_PASS linkpass	
			- Send "linkpass" as the password to connect

	SERVER_INFOLINE	-Specify the description of the server that
				appears when you do /links
		eg: SERVER_INFOLINE Network Auxilurary Services	

	SERVICES_CHAN	-Specify the channel that all bots on NeoStats
				will automatically join, and echo out any
				important information
		eg: SERVICES_CHAN #services	
			-Makes NeoStats, and all the other bots join #services 
				channel on startup/load.

	STATSERV_NETNAME - Your network name e.g. for irc.irc-chat.net put 
				irc-chat, if unknown refer to your network 
				file. Does not apply to All IRCd's

	NEOSTAT_HOST - Specifies the Hostname that NeoStats comes from
			Some people like to make it the same as the Services 
			host (eg, services.irc-chat.net) or one just for 
			NeoStats (eg, stats.irc-chat.net)
		eg: NEOSTATS_HOST stats.neostats.net	
			 -Means the bot will apear as 
				NeoStats!user@stats.neostats.net

	NEOSTAT_USER - Specifies the User/ident of the NeoStats Bot
			(the part before the @host)
		eg: NEOSTATS_USER neo	
			- Means the bot will apear as NeoStats!neo@Host

	ONLY_OPERS - Restrict NeoStats and StatServ to opers use only.
		If not specified, users will have some acesss to NeoStats
		and StatServ commands. 

	BINDTO - Make NeoStats bind to a particular IP Address. If not
		specified NeoStats will attempt to find this address
		itself.
		eg: BINDTO 203.203.123.12
			- All outgoing connections from NeoStats will
			originate from thsi IP address. 

	WANT_PRIVMSG -Specify if the bots should send all
			messages as privmsg's or as notices (Most Services
			use notice)
		eg: WANT_PRIVMSG	
			- if present, will send all messages as Privmsg's 
			(if commented out, it will send as Notices)
		*NOTE:* This option Violates IRC RFC, and can cause Flooding
			Problems on your network. Its NOT recomended. 

	NO_LOAD	- If this is in the neostats.cfg your NeoStats WILL
		NOT START UP.  To disable this simply comment this
		line out.  
		eg: NO_LOAD  <- NeoStats will not load.
		eg2: #NO_LOAD <- NeoStats will load.

	RECONNECT_TIME	-If NeoStats server gets split from the	network, how 
			long to wait before attempting to reconnect to the 
			network
		eg: RECONNECT_TIME 10	
			-Specifies wait 10 seconds before trying to reconnect

	LOAD_MODULE	-what module to load at startup. Multiple
		instances of LOAD_MODULE may be specified
		eg: LOAD_MODULE statserv
			-Will load up StatServ at boot

	if you have enabled the ServiceRoots authentication module,
	the the additional configuration options are available:

	SERVICE_ROOTS	-Who should get access to NeoStats regardless
			of their O line flags. You can specify this option 
			upto 10 times to specify different nicks who will 
			be allowed this priveledge.
		eg: SERVICE_ROOTS fish!?Fish@*.neostats.net
			-Will give "fish" access to NeoStats privledged 
			commands if fish has Umode +r and comes from the
			specified hostname and ident. 

1.7 Compiling additional modules
--------------------------------

	If you have downloaded other NeoStats modules e.g. OPSB,
	you should now install them. If you upgrading NeoStats,
	you must rebuild all other seperate modules to work with
	the new version of NeoStats. See the documentation with
	these modules for instructions on building and installing
	them. 

1.8 Running NeoStats
--------------------

	NeoStats is now configured and installed. 

	Before running NeoStats you must make sure that your server(s) 
	have C: N: and U: lines for your NeoStats server. 
	I WILL NOT ASSIST YOU WITH ADDING C: N: AND U: LINES TO
	YOUR SERVER, YOU SHOULD READ THE IRCd's DOCUMENTATION IF
	YOU DO NOT KNOW HOW TO DO IT!!! DO NOT CONTACT US ABOUT
	C: N: and U: Lines

	Once your C/N/U lines are setup, you need to start NeoStats. You
	should change to the directory where NeoStats in installed e.g.

	cd ~/NeoStats
	
	Then to run NeoStats type:
	
	./neostats

	It should link and sync with your server in a matter of seconds.
	
	Please now read USERMAN for details on how to operate NeoStats 
	from an IRC Client.

	If anything goes wrong, there *might* be a error message in
	the log files. Have a look in ~/NeoStats/logs/NeoStats.log it
	might give you a clue to whats wrong! NeoStats might also 
	send a wallops to the network about what went wrong. Check the
	status window of your IRC client. 


1.9 Notes for upgraders
-----------------------

	If you are upgrading from an older version we recommend
	that you backup the current version first. 
	
	If you are running crontab for NeoStats, we recommend that you
	disable this before making the upgrade. 
	
	Make sure that NeoStats is not running. In an IRC client 
	connected to your network type:
	
	/msg NeoStats shutdown
	
	NeoStats will save important information so wait for this to
	finish. 
	
	To make the backup go to your home directory and type:
	
	cp NeoStats NeoStatsBackup -r
	
	If you fail to perform this backup and the upgrade causes you
	problems, you might lose all NeoStats information. 
	
	We also recommend rebuilding any additional modules after upgrading
	NeoStats. You may not need to upgrade the additional module, just
	rebuild and reinstall it after the make install in Step 1.4 above.
	
	If after upgrading, NeoStats crashes when loading one of your 
	modules e.g. OPSB, this usually means that you did not rebuild the
	module for the latest version of NeoStats. 

	If you do run into problems upgrading and need to restore your 
	backup, you can do so by going to your home directory and typing:

	cp NeoStatsBackup NeoStats -r
	
	Your old modules will also be restored along with the old version of
	NeoStats so there is no need to rebuild them for a restore. 


-----------------------------------<>-----------------------------------

2 Support Information
---------------------

2.1 Before contacting support
-----------------------------

** IMPORTANT - PLEASE READ BEFORE CONTACTING US **

In order that we can dedicate time tp developing NeoStats and can address 
support issues quickly, there are some ways you can help to reduce the 
unnecssary support calls to the NeoStats team. 

First, check you are using the latest release version of NeoStats as 
found on the NeoStats download page. It could be that your problem is 
fixed or your suggestion implemented in the latest version. We are not 
able to provide support for older versions of NeoStats than the 
current release. 

We provide no support for CVS snapshots whether released on the web 
site or not. If you have downloaded a CVS snapshot and are having 
problems, you should revert back to your previous working version or
if this is your first installation, the current release build as indicated
on the web site. Please do not contact us about problems with CVS
versions. We will advise users occasionally to try a CVS snapshot to fix a
problem, but as we do not put our CVS versions through extensive testings,
there might be new bugs or problems. 

Before contacting us with a problem or a bug, please make sure you have 
read all the documentation provided. You should then check the web site 
bug list and search the forums to see if your problem has already been 
reported and if a solution has been posted. 

Before sending us a suggestion, you should check the forums carefully to 
see if your suggestion has already been made and if the NeoStats team 
have decided to implement it or not. The use of the "Search" feature on the
forums is a great way to quickly get answers to your problem if other users
have already encountered the issue. 

You do not have to read all the messages to find out if your issue has 
already been discussed. The message board has a search function so 
you can quickly check to see if there is a discussion on your problem. 

NeoStats Group are only able to help with issues affecting NeoStats. 
We are not able to help set up your IRC Server or Services on 
your network (including the setup of C: N: and U: lines) so please
don't ask us. If you have a question about your IRC Server or Services 
package, please check the documentation that came with them and contact 
their team if you still need assistance. 

The RAW command is an usupported command. If you need help using it,
you should probably not be using it. Please do not ask us for help
on the RAW command.

Thank you. 


2.1 Where to get support
------------------------

You can get support for NeoStats in a number of different ways so choose
the one that suits you best.

* Bug reporting system
  A new bug reporting section has been introduced and you can check this  
  to see if there are any known bugs in NeoStats and find out when they 
  are fixed. Soon you will be able to report bugs using this system. 
  Visit http://bugs.neostats.net/index.php for the bug tracking system

* Message boards available at http://www.neostats.net/boards/

* The NeoStats IRC support channel at irc.irc-chat.net #neostats
  Be warned that we are not always available on the channel to help you. 
  There is a bot there called neoserv that contains the latest bugs and
  support information (duplicated from the NeoStats board)

2.2 What to provide when requesting support
-------------------------------------------

It always helps to provide as much information as possible about 
your environment when asking for help. Please make sure you
include at least the following information:
	Operating system version (ie, Redhat 7.0, Mandrake 9.1 etc)
	gcc version (found via gcc -v)
	Version of NeoStats you are using and if the problem
	is with a module, the version of the module (found 
	via /msg neostats modlist)
	The type of IRCD you are attempting to connect to
	(and version number)

We may request that you enable debugging and submit us the
results of debugging. 
To enable Debugging, use the following command to start NeoStats:

./neostats -d 9 -r
When it crashes, or the bug has been reproduced, send us:
logs/NeoStats.log
logs/recv.log (if it exists, You may wish to edit the first few lines of the
file to remove the link password)
and it will help us to be able to reproduce the bug

-----------------------------------<>-----------------------------------

3. Contributions
----------------

Want to Help us?

We are always looking for help.

Currently, what we really are looking for is people to help us out 
with translating our documentation and of course, other people that 
can code in C to help us with development.

We hope to shortly provide a Module Programers Guide to help those 
people out there take advantage of NeoStats and write their own 
extensions (or Modules) for NeoStats.

If you would like to help out, See Support Information above for 
details on how to contact us.

-----------------------------------<>-----------------------------------

************************************************************************
** This document was last updated on June 11, 2003 by M and is        **
** based on documents originally created by Shmad and Fish.           **
************************************************************************