1 |
Ermyth -- a set of services for IRC networks |
2 |
===================================================== |
3 |
|
4 |
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 |
|
9 |
Information about Ermyth may be found at http://ermyth.xinutec.org/. |
10 |
|
11 |
TABLE OF CONTENTS |
12 |
----------------- |
13 |
1. Installation |
14 |
2. Upgrading |
15 |
3. Setting up IRCd |
16 |
4. Starting Ermyth |
17 |
5. Setting up a crontab entry |
18 |
|
19 |
You should also read the README and FAQ files. |
20 |
|
21 |
1. INSTALLATION |
22 |
--------------- |
23 |
|
24 |
NOTE: if you are using a third party package of Ermyth, most of this section |
25 |
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 |
Ermyth should compile and run on most POSIX compliant systems. The list of |
31 |
platforms that ermyth has been tested on includes: |
32 |
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 |
IRCd's known to be supported by Ermyth are listed in the example |
50 |
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 |
Ermyth will compile. To install, type: |
73 |
$ 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 |
etc/ermyth.conf. You'll need to change every setting or services will |
83 |
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 |
Ermyth acts as an IRC server with pseudo-clients on it. To link it to |
102 |
your network, you'll need to add some lines in your IRCd's |
103 |
configuration. Ermyth connects to your IRCd, not the other way around. |
104 |
|
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 |
Go into the directory where you installed ermyth (by default, |
133 |
~/ermyth/). Type ./bin/ermyth to launch services. |
134 |
|
135 |
Ermyth will report any errors and/or detach into the background. |
136 |
|
137 |
If services doesn't link and/or terminates without warning check the log |
138 |
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 |
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 |
still running, and restart it if not. You'll need to have ermyth |
147 |
binaries and data installed in the same directory for this to work |
148 |
without modification. |
149 |
|
150 |
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 |
Then ensure that the file is marked as executable by typing |
153 |
"chmod +x ermyth.chk" and try to launch the script to see if it works. |
154 |
|
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 |
*/5 * * * * /home/yourname/ermyth/etc/ermyth.chk >/dev/null 2>&1 |
160 |
|
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. |