[ViewVC] Contents of: cvs/ermyth/INSTALL

ermyth -- a set of services for IRC networks
=====================================================

This program is free but copyrighted software; see doc/poddoc/license.pod
for details.

Information about Services may be found at http://ermyth.schmorp.de/.

TABLE OF CONTENTS
-----------------
  1. Installation
  2. Upgrading
  3. Setting up IRCd
  4. Starting Services
  5. Setting up a crontab entry

You should also read the README and FAQ files.

1. INSTALLATION
---------------

NOTE: if you are using a third party package of Services, most of this section
will not apply.

IMPORTANT NOTE: it is not recommended to use and install services as root.
Use an unprivileged user account.

Services should compile and run on most POSIX compliant systems.  The list of
platforms that ermyth has been tested on includes:
        FreeBSD 4.[8,9,10,11]
        FreeBSD 5.[0,1,2,3,4]
        FreeBSD 6.[0]
        FreeBSD 7.[0]
        OpenBSD 3.[5,6,7,8]      (i386, amd64, sparc)
        NetBSD 1.[5,6]           (i386, amd64, sparc)
        NetBSD 2.[0]             (i386, amd64, sparc, mips)
        NetBSD 3.[0]             (i386)
        DragonFly 1.[0,2,5]
        Linux (glibc) 2.6.x      (i386, amd64)
        Solaris [7,8,9,10]       (i86pc, sun4u)
        Solaris Express 10       (i86pc, sun4u)
        MacOS 10.[3.5,4.1]       (intel, powerpc)

Other BSD-based systems will probably work. Other SysV-based systems *might*
work provided they support BSD sockets and POSIX function calls.

Services requires a runtime linker. Systems which do not have a runtime linker
will not be able to run services. However, most systems include a runtime
linker these days.

IRCd's known to be supported by Services are listed in the example 
config (dist/example.conf). The recommended ones are charybdis, ratbox, 
inspircd, asuka, beware ircd (bircd), nefarious and undernet-ircu 
(undernet).

The easy way: run the "setup" script. This does it all for you:
        $ ./setup

Follow the instructions and you're good to go.

The slightly less easy but more traditional way:

Run the "configure" script:
        $ ./configure --prefix=/path/to/install/

If you're running a large network (more than 2000 users), you should 
pass the --enable-large-net switch to configure for enhanced performance.

The "configure" script will run several tests, write several files, and exit.
Once this is done you will want to compile services. To do this, simply 
type:
        $ make

Services will compile. To install, type:
        $ make install

The newly-compiled binary and several supporting files will be copied to the
directory you specified in the "configure" script.

It is recommended to keep the source directory; you will need it to
(re)compile modules later.

Next, you'll want to go to the directory you specified in "configure" and edit
etc/ermyth.conf. You'll need to change every setting or services will 
not work.

2. UPGRADING
------------

IMPORTANT NOTE: backup your configuration file and database!

All custom modules should be recompiled as well. Loading old modules can
cause services to crash.

Sometimes upgrading requires more than recompiling and reinstalling. Be sure to
read doc/RELEASE for important notes concerning the release. This file will
let you know if you need to change your configuration or convert your database
to a new format.

3. SETTING UP IRCD
------------------

Services acts as an IRC server with pseudo-clients on it. To link it to 
your network, you'll need to add some lines in your IRCd's 
configuration. Services connects to your IRCd, not the other way around.

It is suggested that you set up your IRCd (IRC operator access, etc) before
trying to connect services. Many IRCds do not log much about server 
connections, so it is best to connect as an IRC operator and watch the 
server notices.

As for the actual lines that need to be added, every IRCd is different. Look
for documentation for "connect{}" or "link{}" or "C/N lines" for your IRCd. You
need to allow services to introduce other servers (e.g. "hub_mask" or "H 
line"), otherwise it will probably be disconnected when the OperServ 
JUPE command is used.

To be perfectly honest, if you can't figure this out you should be running
neither IRCd nor services.

Additionally, you need to do some configuration on all servers on the network.
You need to reserve ("resv{}", "/resv", "Q line", etc) all nicks 
services uses to avoid normal users taking those nicks and causing 
trouble. Also, many IRCds need to be configured to grant special 
privileges to services ("service{}", "shared{}", "ulines{}", "U lines", 
etc).

See doc/IRCD for more details concerning IRCd-specific requirements for 
running services.

4. STARTING SERVICES
--------------------

Go into the directory where you installed ermyth (by default, 
~/ermyth/). Type ./bin/ermyth to launch services.

Services will report any errors and/or detach into the background.

If services doesn't link and/or terminates without warning check the log
file (var/ermyth.log) to see what happened. If this tells you nothing try
rerunning services via ./bin/ermyth -nd for more verbose 
information.

5. SETTING UP A CRONTAB ENTRY
-----------------------------

A crontab entry will allow you to check periodically whether services is 
still running, and restart it if not. You'll need to have ermyth
binaries and data installed in the same directory for this to work 
without modification.

First rename the dist/ermyth.chk script that is in Ermyth path (by default, 
~/ermyth/) and edit it. You'll need to modify the "cd" part of the file.
Then ensure that the file is marked as executable by typing
"chmod +x ermyth.chk" and try to launch the script to see if it works.

When this is done, you'll have to add the crontab entry. Type "crontab -e"
This will open the default text editor with the crontab file. Enter the
following (with correct path):

*/5 * * * * /home/yourname/ermyth/etc/ermyth.chk >/dev/null 2>&1

The */5 at the beginning means "check every 5 minutes." You may replace
the 5 with other another number if you want (but less than 60). Save and exit,
and it's installed.
Revision:	1.4
Committed:	Wed Sep 5 11:23:12 2007 UTC (16 years, 8 months ago) by pippijn
Branch:	MAIN
Changes since 1.3:	+1 -1 lines
Log Message:	removed GPLed code and put license back to BSD
#	Content
1	ermyth -- a set of services for IRC networks
2	=====================================================
3
4	This program is free but copyrighted software; see doc/poddoc/license.pod
5	for details.
6
7	Information about Services may be found at http://ermyth.schmorp.de/.
8
9	TABLE OF CONTENTS
10	-----------------
11	1. Installation
12	2. Upgrading
13	3. Setting up IRCd
14	4. Starting Services
15	5. Setting up a crontab entry
16
17	You should also read the README and FAQ files.
18
19	1. INSTALLATION
20	---------------
21
22	NOTE: if you are using a third party package of Services, most of this section
23	will not apply.
24
25	IMPORTANT NOTE: it is not recommended to use and install services as root.
26	Use an unprivileged user account.
27
28	Services should compile and run on most POSIX compliant systems. The list of
29	platforms that ermyth has been tested on includes:
30	FreeBSD 4.[8,9,10,11]
31	FreeBSD 5.[0,1,2,3,4]
32	FreeBSD 6.[0]
33	FreeBSD 7.[0]
34	OpenBSD 3.[5,6,7,8] (i386, amd64, sparc)
35	NetBSD 1.[5,6] (i386, amd64, sparc)
36	NetBSD 2.[0] (i386, amd64, sparc, mips)
37	NetBSD 3.[0] (i386)
38	DragonFly 1.[0,2,5]
39	Linux (glibc) 2.6.x (i386, amd64)
40	Solaris [7,8,9,10] (i86pc, sun4u)
41	Solaris Express 10 (i86pc, sun4u)
42	MacOS 10.[3.5,4.1] (intel, powerpc)
43
44	Other BSD-based systems will probably work. Other SysV-based systems might
45	work provided they support BSD sockets and POSIX function calls.
46
47	Services requires a runtime linker. Systems which do not have a runtime linker
48	will not be able to run services. However, most systems include a runtime
49	linker these days.
50
51	IRCd's known to be supported by Services are listed in the example
52	config (dist/example.conf). The recommended ones are charybdis, ratbox,
53	inspircd, asuka, beware ircd (bircd), nefarious and undernet-ircu
54	(undernet).
55
56	The easy way: run the "setup" script. This does it all for you:
57	$ ./setup
58
59	Follow the instructions and you're good to go.
60
61	The slightly less easy but more traditional way:
62
63	Run the "configure" script:
64	$ ./configure --prefix=/path/to/install/
65
66	If you're running a large network (more than 2000 users), you should
67	pass the --enable-large-net switch to configure for enhanced performance.
68
69	The "configure" script will run several tests, write several files, and exit.
70	Once this is done you will want to compile services. To do this, simply
71	type:
72	$ make
73
74	Services will compile. To install, type:
75	$ make install
76
77	The newly-compiled binary and several supporting files will be copied to the
78	directory you specified in the "configure" script.
79
80	It is recommended to keep the source directory; you will need it to
81	(re)compile modules later.
82
83	Next, you'll want to go to the directory you specified in "configure" and edit
84	etc/ermyth.conf. You'll need to change every setting or services will
85	not work.
86
87	2. UPGRADING
88	------------
89
90	IMPORTANT NOTE: backup your configuration file and database!
91
92	All custom modules should be recompiled as well. Loading old modules can
93	cause services to crash.
94
95	Sometimes upgrading requires more than recompiling and reinstalling. Be sure to
96	read doc/RELEASE for important notes concerning the release. This file will
97	let you know if you need to change your configuration or convert your database
98	to a new format.
99
100	3. SETTING UP IRCD
101	------------------
102
103	Services acts as an IRC server with pseudo-clients on it. To link it to
104	your network, you'll need to add some lines in your IRCd's
105	configuration. Services connects to your IRCd, not the other way around.
106
107	It is suggested that you set up your IRCd (IRC operator access, etc) before
108	trying to connect services. Many IRCds do not log much about server
109	connections, so it is best to connect as an IRC operator and watch the
110	server notices.
111
112	As for the actual lines that need to be added, every IRCd is different. Look
113	for documentation for "connect{}" or "link{}" or "C/N lines" for your IRCd. You
114	need to allow services to introduce other servers (e.g. "hub_mask" or "H
115	line"), otherwise it will probably be disconnected when the OperServ
116	JUPE command is used.
117
118	To be perfectly honest, if you can't figure this out you should be running
119	neither IRCd nor services.
120
121	Additionally, you need to do some configuration on all servers on the network.
122	You need to reserve ("resv{}", "/resv", "Q line", etc) all nicks
123	services uses to avoid normal users taking those nicks and causing
124	trouble. Also, many IRCds need to be configured to grant special
125	privileges to services ("service{}", "shared{}", "ulines{}", "U lines",
126	etc).
127
128	See doc/IRCD for more details concerning IRCd-specific requirements for
129	running services.
130
131	4. STARTING SERVICES
132	--------------------
133
134	Go into the directory where you installed ermyth (by default,
135	~/ermyth/). Type ./bin/ermyth to launch services.
136
137	Services will report any errors and/or detach into the background.
138
139	If services doesn't link and/or terminates without warning check the log
140	file (var/ermyth.log) to see what happened. If this tells you nothing try
141	rerunning services via ./bin/ermyth -nd for more verbose
142	information.
143
144	5. SETTING UP A CRONTAB ENTRY
145	-----------------------------
146
147	A crontab entry will allow you to check periodically whether services is
148	still running, and restart it if not. You'll need to have ermyth
149	binaries and data installed in the same directory for this to work
150	without modification.
151
152	First rename the dist/ermyth.chk script that is in Ermyth path (by default,
153	~/ermyth/) and edit it. You'll need to modify the "cd" part of the file.
154	Then ensure that the file is marked as executable by typing
155	"chmod +x ermyth.chk" and try to launch the script to see if it works.
156
157	When this is done, you'll have to add the crontab entry. Type "crontab -e"
158	This will open the default text editor with the crontab file. Enter the
159	following (with correct path):
160
161	/5 * * * /home/yourname/ermyth/etc/ermyth.chk >/dev/null 2>&1
162
163	The */5 at the beginning means "check every 5 minutes." You may replace
164	the 5 with other another number if you want (but less than 60). Save and exit,
165	and it's installed.