[irc/evilnet/x3.git] / INSTALL

   	      X3 Installation Instructions

Introduction:
----------
If you encounter any problems compiling/running X3, please make sure
you have followed the directions in this file correctly and that all
of the requirements listed below are met.

If the problem persists, report it to one (or all) of the coders
listed in the AUTHORS file. Please try to include ALL relevant
information about the error/bug, including anything out of the
ordinary reported from make and the appropriate entries from the log
files.

Requirements:
----------
This release of X3 (1.8) only supports the Undernet P10
protocol and nefarious extensions. It is tested with Nefarious IRCu 
1.3. It does not support bahamut, hybrid, Unreal, or any other ircd 
not listed. Should you find other compatible ircds, please let us know.
Most of the testing has been done on Nefarious IRCu 1.3.0 (Based on ircu2.10.11.x).

X3 is known to compile on the following systems as long as you
are using GNU make (make on Linux, gmake on many other systems):

  * Linux (libc5 or glibc2); glibc2.1 recommended+    (SPARC, ALPHA, x86, PPC)
  * FreeBSD 4.x; tested on 4.2-RELEASE and 4.2-STABLE (SPARC, x86)
  * FreeBSD 3.x; tested on 3.3-RELEASE and 3.4-STABLE (SPARC, x86)
  * FreeBSD 2.x; tested on 2.2.8-RELEASE	      (SPARC, x86)
  * NetBSD 1.6+;                        	      (ALPHA, MIPS, x86)
  * SunOS 5.x; tested on 5.8			      (SPARC, x86)
  * OpenBSD 2.x; tested on 2.8			      (x86)
  * BSDi 4.x; tested on 4.0.1			      (x86)
  * CYGWIN 1.1.x and 1.3.x; tested on 1.1.8	      (x86)

X3 should compile on other system types also.  If you have success
on other platforms/archs or problems on any platforms/archs, please
contact the authors to let us know.

gcc 2.96 tends to emit spurious warnings; before reporting any
compiler warnings from it, make sure you are using the most recent
version of it or try using an official release of gcc.

You may also have trouble unless your compiler's C preprocessor
supports ISO C99 varadic macros.  gcc is the compiler we use for
almost all our testing, and we recommend it for use with X3.

Quick Install:
==============
$ ./configure --prefix=~/x3run  
    # Will install to x3run directory in your home directory
$ make
$ cp x3.conf.example x3.conf
$ nano -w x3.conf
    # use -w (no wrapping) option with nano, or use your favorite editor
$ ./x3
    # launches x3. 
    # Note: x3 runs in the background as a service by default. Give it arguments
    # -f -d  to have it run in the foreground and print debug information.

Detailed Install:
=================
It is generally a bad idea to run or install x3 as root. Choose an account x3
will run under, and configure it to install and run from somewhere that user
has permissions.

Compiling:
----------
  1) cd to the main directory of the X3 source tree.  

     $ cd evilnet-x3serv

  2) Run the configure script with correct arguments. You need to tell configure
     at minimum a path to install to (--prefix). Later, after x3 is working,
     you may want to recompile it with additional modules by adding
     "--modules=memoserv,helpserv" but leave modules out for now.
     
     Configure will verify that your system will have the resources needed for 
     X3 to compile. You should also turn debugging on to assist with setup: 

     $ ./configure --prefix=/path/to/install --enable-debug

  3) Run "make" to begin compiling.  If you encounter any
     uncorrectable errors/warnings, please scroll up to the introduction
     section and follow the instructions.

     $ make

  4) You may now either type "make install" to install it to your
     installation path, or work from your build directory, either is fine.

     $ make install

  5) Change to the install directory.

     $ cd /path/to/install

  6) Copy x3.conf.example to x3.conf 

     $ cp x3.conf.example x3.conf

  7) The example config contains help to assist you with modifications.
     Remember to begin by only editing the bare minimum ammount you need to
     edit to make it run. Then, when it is working, gradually customize the 
     config more. This way errors can be identified at their source.

     Errors in the configuration file will be logged to
     main.log (and if X3 is running in the foreground with -f, printed to
     stdout) when you start x3. 

     To start with you will want to tell x3 where to connect. Modify the "Hub"
     entry in "uplinks" with your ircd info. You'll need a matching connect
     block in ircd.conf and a server type listen block for the  port.
     
     You probably also want to modify the "hostname", "description", and "prefix",
     "numeric", "admin" etc. Other bits are documented, but generally must match
     how your ircd is configured. 

     $ nano -w x3.conf

  8) You can now run x3 for the first time. You can debug by
     running it with '-fd'. It will not background itself, and it
     will be fairly verbose if you gave the configure script the
     --enable-debug flag. If you would like to run in the foreground
     with no verbosity, use the '-f' flag. If you just want to run it,
     execute X3 without any flags.
     $ ./x3 -fd

  9) Once you have X3 started, you'll need to register a AuthServ
     account:
       /msg AuthServ@services.irc.com register <account> <password>
     Make sure that you register the first account -- it is
     automatically granted owner privileges and gives you admin
     access to O3 once you are opered up.

 10) New operators can be given access to O3 through AuthServ's
     (or whatever you've named the nick/authentication service) oset
     command:
       /msg AuthServ oset <nick>|*<account> level <level>
     Levels are generally beween 0 and 1000 by convention; higher
     numbers correspond to more access. You can also add helpers
     (users with extra privileges such as security override in
     traditional configurations) through AuthServ:
       /msg AuthServ oset <nick>|*<account> flags +H

 11) X3 stores its information in a flat text file (x3.db by default). If
     you shut down x3 first, you can edit this file by hand (but be careful!)
     If you delete it, x3 will start up brand new at step 9 (above) which
     can be handy if you think you have made a mistake.


If you get into trouble, stop by channel #Evilnet on irc.afternet.org for help.

--------------
Help guide originally created for srvx by: -Jedi (jedi@turboflux.net)
Adapted by Rubin
Commit	Line	Data
ceafd592	1	X3 Installation Instructions
d76ed9a9	2
	3	Introduction:
	4	----------
ceafd592	5	If you encounter any problems compiling/running X3, please make sure
d76ed9a9	6	you have followed the directions in this file correctly and that all
	7	of the requirements listed below are met.
	8
	9	If the problem persists, report it to one (or all) of the coders
	10	listed in the AUTHORS file. Please try to include ALL relevant
	11	information about the error/bug, including anything out of the
	12	ordinary reported from make and the appropriate entries from the log
	13	files.
	14
	15	Requirements:
	16	----------
5619b61c R	17	This release of X3 (1.8) only supports the Undernet P10
	18	protocol and nefarious extensions. It is tested with Nefarious IRCu
	19	1.3. It does not support bahamut, hybrid, Unreal, or any other ircd
	20	not listed. Should you find other compatible ircds, please let us know.
	21	Most of the testing has been done on Nefarious IRCu 1.3.0 (Based on ircu2.10.11.x).
d76ed9a9	22
ceafd592	23	X3 is known to compile on the following systems as long as you
d76ed9a9	24	are using GNU make (make on Linux, gmake on many other systems):
	25
	26	* Linux (libc5 or glibc2); glibc2.1 recommended+ (SPARC, ALPHA, x86, PPC)
	27	* FreeBSD 4.x; tested on 4.2-RELEASE and 4.2-STABLE (SPARC, x86)
	28	* FreeBSD 3.x; tested on 3.3-RELEASE and 3.4-STABLE (SPARC, x86)
	29	* FreeBSD 2.x; tested on 2.2.8-RELEASE (SPARC, x86)
	30	* NetBSD 1.6+; (ALPHA, MIPS, x86)
	31	* SunOS 5.x; tested on 5.8 (SPARC, x86)
	32	* OpenBSD 2.x; tested on 2.8 (x86)
	33	* BSDi 4.x; tested on 4.0.1 (x86)
	34	* CYGWIN 1.1.x and 1.3.x; tested on 1.1.8 (x86)
	35
ceafd592	36	X3 should compile on other system types also. If you have success
d76ed9a9	37	on other platforms/archs or problems on any platforms/archs, please
	38	contact the authors to let us know.
	39
	40	gcc 2.96 tends to emit spurious warnings; before reporting any
	41	compiler warnings from it, make sure you are using the most recent
	42	version of it or try using an official release of gcc.
	43
	44	You may also have trouble unless your compiler's C preprocessor
	45	supports ISO C99 varadic macros. gcc is the compiler we use for
ceafd592	46	almost all our testing, and we recommend it for use with X3.
d76ed9a9	47
d76ed9a9	48	Quick Install:
5619b61c R	49	==============
	50	$ ./configure --prefix=~/x3run
	51	# Will install to x3run directory in your home directory
d76ed9a9	52	$ make
5619b61c R	53	$ cp x3.conf.example x3.conf
	54	$ nano -w x3.conf
	55	# use -w (no wrapping) option with nano, or use your favorite editor
ceafd592	56	$ ./x3
5619b61c R	57	# launches x3.
	58	# Note: x3 runs in the background as a service by default. Give it arguments
	59	# -f -d to have it run in the foreground and print debug information.
	60
	61	Detailed Install:
	62	=================
	63	It is generally a bad idea to run or install x3 as root. Choose an account x3
	64	will run under, and configure it to install and run from somewhere that user
	65	has permissions.
d76ed9a9	66
	67	Compiling:
	68	----------
5619b61c	69	1) cd to the main directory of the X3 source tree.
d76ed9a9	70
a8aa6453 R	71	$ cd evilnet-x3serv
a8aa6453 R	72
5619b61c	73	2) Run the configure script with correct arguments. You need to tell configure
a8aa6453 R	74	at minimum a path to install to (--prefix). Later, after x3 is working,
	75	you may want to recompile it with additional modules by adding
	76	"--modules=memoserv,helpserv" but leave modules out for now.
	77
5619b61c R	78	Configure will verify that your system will have the resources needed for
5619b61c R	79	X3 to compile. You should also turn debugging on to assist with setup:
d76ed9a9	80
a8aa6453	81	$ ./configure --prefix=/path/to/install --enable-debug
d76ed9a9	82
a8aa6453	83	3) Run "make" to begin compiling. If you encounter any
d76ed9a9	84	uncorrectable errors/warnings, please scroll up to the introduction
d76ed9a9	85	section and follow the instructions.
a8aa6453	86
5619b61c	87	$ make
d76ed9a9	88
a8aa6453	89	4) You may now either type "make install" to install it to your
d76ed9a9	90	installation path, or work from your build directory, either is fine.
a8aa6453	91
5619b61c	92	$ make install
d76ed9a9	93
a8aa6453 R	94	5) Change to the install directory.
a8aa6453 R	95
5619b61c	96	$ cd /path/to/install
d76ed9a9	97
a8aa6453 R	98	6) Copy x3.conf.example to x3.conf
	99
	100	$ cp x3.conf.example x3.conf
	101
	102	7) The example config contains help to assist you with modifications.
5619b61c R	103	Remember to begin by only editing the bare minimum ammount you need to
	104	edit to make it run. Then, when it is working, gradually customize the
	105	config more. This way errors can be identified at their source.
a8aa6453 R	106
	107	Errors in the configuration file will be logged to
	108	main.log (and if X3 is running in the foreground with -f, printed to
	109	stdout) when you start x3.
	110
	111	To start with you will want to tell x3 where to connect. Modify the "Hub"
	112	entry in "uplinks" with your ircd info. You'll need a matching connect
	113	block in ircd.conf and a server type listen block for the port.
	114
	115	You probably also want to modify the "hostname", "description", and "prefix",
	116	"numeric", "admin" etc. Other bits are documented, but generally must match
	117	how your ircd is configured.
	118
5619b61c R	119	$ nano -w x3.conf
	120
	121	8) You can now run x3 for the first time. You can debug by
	122	running it with '-fd'. It will not background itself, and it
d76ed9a9	123	will be fairly verbose if you gave the configure script the
	124	--enable-debug flag. If you would like to run in the foreground
	125	with no verbosity, use the '-f' flag. If you just want to run it,
ceafd592	126	execute X3 without any flags.
5619b61c	127	$ ./x3 -fd
d76ed9a9	128
5619b61c	129	9) Once you have X3 started, you'll need to register a AuthServ
d76ed9a9	130	account:
e0bcaf30	131	/msg AuthServ@services.irc.com register <account> <password>
d76ed9a9	132	Make sure that you register the first account -- it is
5619b61c	133	automatically granted owner privileges and gives you admin
e0bcaf30	134	access to O3 once you are opered up.
d76ed9a9	135
5619b61c	136	10) New operators can be given access to O3 through AuthServ's
d76ed9a9	137	(or whatever you've named the nick/authentication service) oset
d76ed9a9	138	command:
e0bcaf30	139	/msg AuthServ oset <nick>\|*<account> level <level>
d76ed9a9	140	Levels are generally beween 0 and 1000 by convention; higher
	141	numbers correspond to more access. You can also add helpers
	142	(users with extra privileges such as security override in
e0bcaf30	143	traditional configurations) through AuthServ:
e0bcaf30	144	/msg AuthServ oset <nick>\|*<account> flags +H
d76ed9a9	145
5619b61c R	146	11) X3 stores its information in a flat text file (x3.db by default). If
	147	you shut down x3 first, you can edit this file by hand (but be careful!)
	148	If you delete it, x3 will start up brand new at step 9 (above) which
	149	can be handy if you think you have made a mistake.
	150
	151
	152
	153	If you get into trouble, stop by channel #Evilnet on irc.afternet.org for help.
	154
	155	--------------
	156	Help guide originally created for srvx by: -Jedi (jedi@turboflux.net)
	157	Adapted by Rubin
d76ed9a9	158