[ViewVC] Annotation of: cvs/ermyth/INSTALL

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

Ermyth is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Information about Ermyth may be found at http://ermyth.xinutec.org/.

TABLE OF CONTENTS
-----------------
  1. Installation
  2. Upgrading
  3. Setting up IRCd
  4. Starting Ermyth
  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 Ermyth, 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.

Ermyth 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.

IRCd's known to be supported by Ermyth 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

Ermyth 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
------------------

Ermyth 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. Ermyth 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.

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