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