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