1 |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 |
<html> |
3 |
<head> |
4 |
<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1"> |
5 |
<title>IRC Services Manual - 2. Installing and using Services</title> |
6 |
</head> |
7 |
|
8 |
<body> |
9 |
<a name=top></a> |
10 |
<h1 align=center>IRC Services Manual</h1> |
11 |
|
12 |
<h2 align=center>2. Installing and using Services</h2> |
13 |
|
14 |
<br>2-1. <a href="#1">System and network requirements</a> |
15 |
<br>2-2. <a href="#2">Installing Services from a binary distribution</a> |
16 |
<br>2-3. <a href="#3">Installing Services from source code</a> |
17 |
<br>2-4. <a href="#4">Configuring Services</a> |
18 |
<br>2-5. <a href="#5">Configuring your IRC server</a> |
19 |
<br>2-6. <a href="#6">Starting, stopping and controlling Services</a> |
20 |
|
21 |
<p align=right><font size=-1><a href="1.html">Previous section: About IRC Services</a> | |
22 |
<a href="index.html">Table of Contents</a> | |
23 |
<a href="3.html">Next section: Overview of Services features</a></font> |
24 |
|
25 |
<p><hr> |
26 |
|
27 |
<a name=1></a> |
28 |
<h3>2-1. System and network requirements</h3> |
29 |
|
30 |
<p>In order to run Services, you will need the following:</p> |
31 |
|
32 |
<p><ul> |
33 |
<li><b>A POSIX-compliant operating system.</b> Services is designed |
34 |
for the Linux operating system, but should function on any POSIX-compliant |
35 |
(or nearly so) operating system; it is known to work on FreeBSD, OpenBSD, |
36 |
and Solaris, and has been reported to work on MacOS X and AmigaOS as well. |
37 |
(On AmigaOS, you will need to increase the program stack size using the |
38 |
CLI command <tt>STACK</tt>; a stack size of 512k, 524288 bytes, should be |
39 |
sufficient. Services is not supported on Windows, but some users have |
40 |
reported success in running it; see <a href="faq.html#A3">FAQ A.3</a>.) |
41 |
|
42 |
<p><li><b>A supported IRC server</b> (IRCD). Services supports several |
43 |
different types of IRC servers, as listed in Table 2-1 below. Your IRC |
44 |
network must be using one of these servers in order to use Services (the |
45 |
"Services module" column indicates which protocol module is used with that |
46 |
server; see <a href="#4">section 2-4</a> for details). |
47 |
</ul> |
48 |
|
49 |
<p>Additionally, if you plan to compile Services from the source code, you |
50 |
will also need the following (note that these are not necessary if you |
51 |
install from a binary package):</p> |
52 |
|
53 |
<p><ul> |
54 |
<li><b><a href="http://www.gnu.org/software/gcc/gcc.html">GCC</a> |
55 |
<font size=-1>[<tt>www.gnu.org</tt>]</font> (the GNU C compiler),</b> |
56 |
version 3.2 or later. Services uses some extensions to the C language |
57 |
provided by GCC, and is unlikely to compile on other compilers; Services |
58 |
also takes advantage of recent additions to the C standard (often referred |
59 |
to as "C99") which are not supported by older versions of GCC. |
60 |
|
61 |
<p><i>Notice: (1)</i> Services will not work with the |
62 |
<a href="http://www.trl.ibm.com/projects/security/ssp/">SSP (stack-smashing |
63 |
protector)</a> <font size=-1>[<tt>www.trl.ibm.com</tt>]</font> patch to GCC, |
64 |
due to a bug in SSP triggered by Services that causes crashes. The |
65 |
<tt>configure</tt> script (see below) will automatically detect the |
66 |
presence of this patch and deactivate the stack-protection feature, or |
67 |
refuse to compile if it cannot be deactivated. |
68 |
|
69 |
<p><i>(2)</i> Versions of GCC before 3.4 have bugs which cause Services to |
70 |
crash. Services has workarounds for the Intel x86, SPARC, and PowerPC |
71 |
platforms, but you will need to use GCC 3.4 or later on other systems. See |
72 |
<a href="faq.html#B1.5">FAQ B.1.5</a> for details. |
73 |
|
74 |
<p><li><b><a href="http://www.gnu.org/software/make/make.html">GNU |
75 |
make</a> [<font size=-1><tt>www.gnu.org</tt></font>], version 3.79 or |
76 |
later.</b> Services uses complex Makefiles which may or may not work with |
77 |
other "make" programs, and are known not to work with earlier versions of |
78 |
GNU make. Note that GNU make may be installed on your system as either |
79 |
<tt>make</tt> or <tt>gmake</tt>; if you're not sure, type <tt>make -v</tt> |
80 |
or <tt>gmake -v</tt> in your shell, and if you get output that looks like |
81 |
"<tt>GNU Make version 3.79.1, by Richard Stallman and Roland McGrath</tt>", |
82 |
then it's installed. |
83 |
|
84 |
<p><li><b>The Bourne shell</b> or a compatible shell. This is installed on |
85 |
most Unix-like systems as <tt>/bin/sh</tt>. If by any chance the |
86 |
<tt>configure</tt> script fails (see <a href="#3">section 2-3</a>), try |
87 |
installing <a href="http://www.gnu.org/software/bash/bash.html">Bash</a> |
88 |
<font size=-1>[<tt>www.gnu.org</tt>]</font> and using it to run the |
89 |
<tt>configure</tt> script. |
90 |
|
91 |
<p><li><b><a href="http://www.perl.com/">Perl</a> |
92 |
<font size=-1>[<tt>www.perl.com</tt>]</font></b> may also be needed if you |
93 |
modify certain files (the language data files in particular). |
94 |
</ul> |
95 |
|
96 |
<div align=center> |
97 |
<a name=table1></a> |
98 |
<b>Table 2-1.</b> Supported IRC server types<br><br> |
99 |
<table border=1> |
100 |
<tr><th>IRC server (IRCD) name<th>Services module |
101 |
<tr><td><a href="http://bahamut.dal.net/">Bahamut</a> |
102 |
<font size=-1>[<tt>bahamut.dal.net</tt>]</font> 1.8.0 and later |
103 |
<font color=red>(*)</font> |
104 |
<td align=center><tt>bahamut</tt> |
105 |
<tr><td>Chunky Monkey IRCD 1.0 and later |
106 |
<td align=center><tt>monkey</tt> |
107 |
<tr><td>DALnet (ircd.dal) 4.4.13 and earlier |
108 |
<td align=center><tt>dalnet</tt> |
109 |
<tr><td>DALnet (ircd.dal) 4.4.15 and latre |
110 |
<td align=center><tt>dreamforge</tt> |
111 |
<tr><td>Dreamforge (ircd.dal 4.6.x) |
112 |
<td align=center><tt>dreamforge</tt> |
113 |
<tr><td><a href="http://www.inspircd.org/">InspIRCd</a> |
114 |
<font size=-1>[<tt>www.inspircd.org</tt>]</font> 1.1 and later |
115 |
<td align=center><tt>inspircd</tt> |
116 |
<tr><td><a href="http://ircd-hybrid.com/">IRCD-Hybrid</a> |
117 |
<font size=-1>[<tt>ircd-hybrid.com</tt>]</font> 7.0 and later |
118 |
<font color=red>(**)</font> |
119 |
<td align=center><tt>hybrid</tt> |
120 |
<tr><td>ircd-2.8.x |
121 |
<td align=center><tt>rfc1459</tt> |
122 |
<tr><td>ircd-2.8.x+TS8 |
123 |
<td align=center><tt>ts8</tt> |
124 |
<tr><td><a href="http://coder-com.undernet.org/">ircu (Undernet)</a> |
125 |
<font size=-1>[<tt>coder-com.undernet.org</tt>]</font> 2.9.x |
126 |
<td align=center><tt>undernet-p9</tt> |
127 |
<tr><td><a href="http://www.ptlink.net/Coders/">PTlink IRCd</a> |
128 |
<font size=-1>[<tt>www.ptlink.net</tt>]</font> 6.10.0 and later |
129 |
<td align=center><tt>ptlink</tt> |
130 |
<tr><td><a href="http://www.ircd-ratbox.org/">ircd-ratbox</a> |
131 |
<font size=-2>[<tt>www.ircd-ratbox.org</tt>]</font>2.1.x and later |
132 |
<font color=red>(***)</font> |
133 |
<td align=center><tt>ratbox</tt> |
134 |
<tr><td><a href="http://www.solid-ircd.com/">solid-ircd</a> |
135 |
<font size=-2>[<tt>www.solid-ircd.com</tt>]</font>, all versions |
136 |
<font color=red>(*)</font> |
137 |
<td align=center><tt>ratbox</tt> |
138 |
<tr><td><a href="http://tr-ircd.sourceforge.net/">tr-ircd</a> |
139 |
<font size=-1>[<tt>tr-ircd.sourceforge.net</tt>]</font> 5.7 and |
140 |
later<br> |
141 |
<td align=center><tt>trircd</tt> |
142 |
<tr><td><i>UltimateIRCD 2.8.1</i> |
143 |
<td align=center><tt>dreamforge</tt> |
144 |
<tr><td><i>UltimateIRCD 3.0.0</i> |
145 |
<td align=center><tt>bahamut</tt> |
146 |
<tr><td><a href="http://www.unrealircd.com/">UnrealIRCd</a> |
147 |
<font size=-1>[<tt>www.unrealircd.com</tt>]</font> 3.1.1 and later |
148 |
<td align=center><tt>unreal</tt> |
149 |
</table> |
150 |
(servers listed in <i>italics</i> are listed based on user reports, but are <b>not supported</b>) |
151 |
</div> |
152 |
|
153 |
<p><font color=red>(*)</font> When using Bahamut or solid-ircd, <b>do |
154 |
not</b> configure your server as a "services hub" ("<tt>servtype |
155 |
serviceshub</tt>" in the <tt>ircd.conf</tt> file); this setting causes |
156 |
Bahamut and solid-ircd to not send certain information needed by Services |
157 |
to work correctly. If Services detects that your server is configured as a |
158 |
services hub, it will log a message to that effect and abort. |
159 |
|
160 |
<p><font color=red>(**)</font> To use Hybrid with Services, you must load |
161 |
the <tt>m_tburst.so</tt> module in your server's configuration. In recent |
162 |
versions of Hybrid (at least 7.2.3), this module is compiled automatically; |
163 |
in earlier versions, you may need to locate and compile it yourself. If |
164 |
the module is not loaded, Services will refuse to connect to the server. |
165 |
|
166 |
<p><font color=red>(***)</font> When using ircd-ratbox, make sure to |
167 |
include the "<tt>topicburst</tt>" server flag in the <tt>connect</tt> block |
168 |
for Services on the remote server; if topic burst support is not enabled, |
169 |
Services will refuse to connect to the server. Also, forced nickname |
170 |
changing will be unavailable unless all servers are compiled with the |
171 |
"<tt>--enable-services</tt>" option. |
172 |
|
173 |
<p align=right><font size="-1"><a href="#top">Back to top</a></font> |
174 |
|
175 |
<p><hr> |
176 |
|
177 |
<a name=2></a> |
178 |
<h3>2-2. Installing Services from a binary distribution</h3> |
179 |
|
180 |
<p>Binary distributions of Services are provided for Linux systems in the |
181 |
popular RPM and .deb formats. See the <a href="1.html#3">Services home |
182 |
page</a> to download the latest binary distribution, then install or |
183 |
upgrade it the same way you would for any other package. |
184 |
|
185 |
<p>Note that executable files in the binary distributions are compiled |
186 |
statically; this means that they will work on any modern system regardless |
187 |
of version, at the cost of requiring slightly more disk space and runtime |
188 |
memory, and requiring an upgrade (or recompile from source) if a bug is |
189 |
found in any of the system libraries used by Services. |
190 |
|
191 |
<p align=right><font size="-1"><a href="#top">Back to top</a></font> |
192 |
|
193 |
<p><hr> |
194 |
|
195 |
<a name=3></a> |
196 |
<h3>2-3. Installing Services from the source code</h3> |
197 |
|
198 |
<p>If no binary distribution is available for your platform or you prefer to |
199 |
compile Services yourself, you will need to install from the source code. |
200 |
Once you have <a href="1.html#3">downloaded the source</a>, you need to: |
201 |
|
202 |
<p><ol> |
203 |
<li><b>Run the <tt>configure</tt> script.</b> This script checks what |
204 |
type of system you are running and determines what adjustments to the base |
205 |
source code are necessary in order to compile. Certain compile-time |
206 |
settings can be set by passing command-line options to the script; the most |
207 |
common ones are: |
208 |
<ul><li><tt>-ignore-cache</tt> (ignore the results of any previous |
209 |
configuration; use this if your system configuration has changed) |
210 |
<li><tt>-prefix <i>pathname</i></tt> (set default installation location) |
211 |
<li><tt>-use-static-modules</tt> (compile using statically-linked |
212 |
modules, even if dynamic linking is available) |
213 |
<li><tt>-[no-]sorted-lists</tt> (select between sorted nickname/channel |
214 |
lists and unsorted ones; <tt>-sorted-lists</tt> is the default, but |
215 |
on large networks, keeping the lists sorted can slow down Services |
216 |
significantly) |
217 |
</ul> |
218 |
See Table 2-2 below for a full list of options, which can also be obtained |
219 |
with <tt>./configure -help</tt>. (If you prefer the GNU autoconf |
220 |
"<tt>--<i>option</i>[=<i>value</i>]</tt>" format, <tt>configure</tt> will |
221 |
accept that as well, <i>e.g.</i> "<tt>--prefix=/usr</tt>".) Note that |
222 |
<tt>configure</tt> will ignore environment variables like <tt>CC</tt> and |
223 |
<tt>CFLAGS</tt>; use the appropriate command-line options instead if you |
224 |
need to set these yourself. |
225 |
|
226 |
<p><b>Note on using alternate C compilers:</b> If you specify a particular |
227 |
C compiler using the <tt>-cc</tt> option, or if GCC is not installed on |
228 |
your system, you will also need to specify any necessary options using the |
229 |
<tt>-cflags</tt> option. In particular, Services uses a feature of C known |
230 |
as "pointer aliasing", which is technically forbidden by the C standard but |
231 |
necessary for clean programming. Some compilers attempt to optimize based |
232 |
on the assumption that pointer aliasing is not used; if your compiler does |
233 |
this, you will need to tell it not to. |
234 |
|
235 |
<a name="table2-2"></a> |
236 |
<div align=center> |
237 |
<b>Table 2-2.</b> Options to the <tt>configure</tt> script<br><br> |
238 |
<table border=1> |
239 |
<tr><th>Option<th>Description |
240 |
|
241 |
<tr><th colspan=2>Controlling the <tt>configure</tt> script |
242 |
<tr><td><tt>-help</tt> |
243 |
<td>Displays a list of command-line options and their meanings, then |
244 |
exits. |
245 |
<tr><td><tt>-ignore-cache</tt> |
246 |
<td>Prevents the cache file from being read. (The cache file, |
247 |
<tt>config.cache</tt>, is created the first time you run the |
248 |
<tt>configure</tt> script, and saves the results of configuration |
249 |
to speed up the script the next time you run it.) |
250 |
|
251 |
<tr><th colspan=2>Controlling compilation |
252 |
<tr><td><tt>-cc <i>PROGRAM</i></tt> |
253 |
<td>Specifies the C compiler to use, such as <tt>cc</tt> or <tt>gcc</tt>. |
254 |
If this option is given, the ordinary check for a compiler is |
255 |
skipped, and the given compiler is used. This option also causes |
256 |
the cached values of <tt>CFLAGS</tt> (compiler options) and |
257 |
<tt>LFLAGS</tt> (linker options) to be ignored; these options will |
258 |
revert to the defaults, unless the <tt>-cflags</tt> or |
259 |
<tt>-lflags</tt> options are also given. |
260 |
<tr><td><tt>-cflags <i>CFLAGS</i></tt> |
261 |
<td>Specifies command-line options to pass to the compiler when |
262 |
compiling source files. The default depends on the compiler, but |
263 |
typically includes standard optimization flags, such as <tt>-O2</tt> |
264 |
for GCC. |
265 |
<tr><td><tt>-lflags <i>LFLAGS</i></tt> |
266 |
<td>Specifies command-line options to pass to the compiler when linking |
267 |
executable files. The default is no flags. |
268 |
<tr><td><tt>-libs <i>LIBS</i></tt> |
269 |
<td>Specifies any extra libraries to be used when linking the main |
270 |
Services executable, using the linker library options <tt>-L</tt> |
271 |
and <tt>-l</tt>. Normally there is no need to use this option. |
272 |
<tr><td><tt>-os2</tt> |
273 |
<td>Specifies that the system on which Services is being compiled is |
274 |
an OS/2 system. On such systems, Services may not compile |
275 |
correctly without this switch. |
276 |
|
277 |
<tr><th colspan=2>Controlling installation |
278 |
<tr><td><tt>-program <i>NAME</i></tt> |
279 |
<td>Specifies the name to be used for the executable file (default: |
280 |
<tt>ircservices</tt>). The configuration file |
281 |
<tt>ircservices.conf</tt> and the <tt>ircservices-chk</tt> script (see |
282 |
<a href="#6-ircservices-chk">section 2-6</a>) will also be renamed |
283 |
to <tt><i>NAME</i>.conf</tt> and <tt><i>NAME</i>-chk</tt>; the |
284 |
installation directories selected by the <tt>-prefix</tt> option |
285 |
(see below) will be changed to match; and the example configuration |
286 |
files will use the given name in the default log, PID, and MOTD |
287 |
files. |
288 |
<tr><td><tt>-bindest <i>DIR</i></tt> |
289 |
<td>Specifies the directory to be used for program file installation. |
290 |
The main <tt>ircservices</tt> executable file and the |
291 |
<tt>ircservices-chk</tt> script will be installed in this directory. |
292 |
<tr><td><tt>-datdest <i>DIR</i></tt> |
293 |
<td>Specifies the directory to be used for data file installation. All |
294 |
Services files and subdirectories except the two program files |
295 |
listed above will be installed in this directory. |
296 |
<tr><td><tt>-prefix <i>DIR</i></tt> |
297 |
<td>Specifies the directory to be used for installation as a GNU-style |
298 |
installation prefix. Program files will be installed in |
299 |
<tt><i>DIR</i>/sbin</tt>, and data files will be installed in |
300 |
<tt><i>DIR</i>/lib/ircservices</tt> (or |
301 |
<tt><i>DIR</i>/lib/<i>NAME</i></tt>, where <tt><i>NAME</i></tt> is |
302 |
the executable name given to the <tt>-program</tt> option). If |
303 |
this option is given, the <tt>-bindest</tt> and <tt>-datdest</tt> |
304 |
options are ignored. |
305 |
|
306 |
<tr><th colspan=2>Controlling Services features (use <tt>-no-<i>option</i></tt> |
307 |
to disable) |
308 |
<tr><td><tt>-use-local-funcs</tt> |
309 |
<td>Forces the use of compatibility functions over system library |
310 |
functions. Normally, Services will use all system library |
311 |
functions available, except when a bug is detected in one of the |
312 |
functions; if this option is given, Services will instead make use |
313 |
of its own versions of these functions. This can be useful when |
314 |
debugging Services, or if you suspect a bug in the system libraries. |
315 |
<tr><td><tt>-use-static-modules</tt> |
316 |
<td>Forces modules to be compiled statically, even if dynamic modules |
317 |
could be used. Using static modules results in a larger executable |
318 |
file and more memory usage than using dynamic modules, but may be |
319 |
marginally faster. On some systems, dynamic modules are not |
320 |
supported, and modules will be compiled statically even if |
321 |
<tt>-no-use-static-modules</tt> is given. |
322 |
<tr><td><tt>-sorted-lists</tt> |
323 |
<td>Causes Services to keep the nickname and channel lists sorted; this |
324 |
can cause a performance penalty on large networks. <b>Enabled by |
325 |
default</b> (use <tt>-no-sorted-lists</tt> to disable). |
326 |
<tr><td><tt>-clean-compile</tt> |
327 |
<td>Attempts to compile Services with no compiler warnings; this may |
328 |
cause a slight performance penalty. <b>Enabled by default</b> (use |
329 |
<tt>-no-clean-compile</tt> to disable). |
330 |
<tr><td><tt>-memchecks</tt> |
331 |
<td>Performs extra checks on memory allocation. This option is |
332 |
intended for debugging only, and causes a significant performance |
333 |
penalty. |
334 |
<tr><td><tt>-showallocs</tt> |
335 |
<td>Causes all memory allocation activity to be logged to the Services |
336 |
logfile. This option is intended for debugging only, and will |
337 |
generate extremely large log files. This option is ignored unless |
338 |
<tt>-memchecks</tt> is enabled. |
339 |
<tr><td><tt>-dumpcore</tt> |
340 |
<td>Causes Services to attempt to write a core file if it crashes. |
341 |
This option can be useful in obtaining a backtrace to aid |
342 |
debugging; however, it prevents Services from shutting down |
343 |
cleanly, so you will not see a "shutting down" notice from Services |
344 |
when it detects a crash. |
345 |
|
346 |
<tr><th colspan=2>Other options |
347 |
<tr><td><tt>-check</tt> |
348 |
<td>Checks whether this script has already been run and whether the |
349 |
cache is up-to-date. Exits with status 0 if up-to-date, 1 if not. |
350 |
This option is used by the Makefile to ensure that the |
351 |
<tt>configure</tt> script is run before compilation. |
352 |
|
353 |
</table> |
354 |
</div> |
355 |
|
356 |
<p>When the script starts up, it will first determine the directories in |
357 |
which Services should be installed. These can be specified either through |
358 |
the <tt>-bindest</tt>/<tt>-datdest</tt> options or the <tt>-prefix</tt> |
359 |
option; if none of these are present, the script will use the same |
360 |
directories as when you last ran the script (if you have not run the script |
361 |
before or you use the <tt>-ignore-cache</tt> option, the defaults are |
362 |
<tt>/usr/local/sbin</tt> for the executable program and |
363 |
<tt>/usr/local/lib/ircservices</tt> for the data files). |
364 |
|
365 |
<p>After setting the installation directories, <tt>configure</tt> will |
366 |
check your system and print out status messages as it proceeds. At the |
367 |
end, if no errors occur, it will print out a message telling you to |
368 |
proceed with compilation. |
369 |
|
370 |
<p><li><b>Edit <tt>defs.h</tt> and the <tt>Makefile</tt>, if necessary</b>. |
371 |
There are a few settings at the top of these files which can be changed as |
372 |
needed. Usually, however, there is no need to change them, and you can |
373 |
proceed directly to compilation. |
374 |
|
375 |
<p>One case in which you may want to modify a setting is if you run a |
376 |
regional network which uses a language other than English as its primary |
377 |
language; in this case, you can change the <tt>DEF_LANGUAGE</tt> setting in |
378 |
<tt>defs.h</tt> to your local langauge. |
379 |
|
380 |
<p><li><b>Compile the program.</b> Run the command <tt>make</tt> (or |
381 |
<tt>gmake</tt>, depending on your system) from the top-level directory. |
382 |
Compilation time will vary depending on your system; on the author's system |
383 |
(Athlon64X2 4400+, 2GB RAM), compiling the entire program takes |
384 |
approximately one minute. If you have a multiple-processor system, you can |
385 |
use <tt>make -j<i>N</i></tt> (or <tt>gmake -j<i>N</i></tt>) to compile in |
386 |
parallel using <tt><i>N</i></tt> threads, which will significantly reduce |
387 |
compilation time. Parallel compilation is also useful if your system has |
388 |
slow I/O (such as disk access), since it lets one compilation run while |
389 |
another is waiting for a disk access to complete. |
390 |
|
391 |
<p><li><b>Install the program and data files.</b> Run the command <tt>make |
392 |
install</tt> (or <tt>gmake install</tt>) and the program and data files |
393 |
will be copied to their destinations. The program file is installed as |
394 |
<tt>ircservices</tt> in the program installation directory; the data |
395 |
installation directory will contain sample configuration files (see |
396 |
<a href="#4">section 2-4</a>), language data files, the |
397 |
<a href="5.html#3"><tt>convert-db</tt></a> utility, and (if you compiled |
398 |
modules with dynamic linking, which is the default on systems which support |
399 |
it) module files. |
400 |
|
401 |
<p>Note that if you are compiling the program as the same user you will |
402 |
install as, you can just use the single command <tt>make install</tt> to |
403 |
compile and install in one step. |
404 |
|
405 |
<p>If you need to install Services to a separate subtree, for example when |
406 |
setting up Services in a chroot'd environment, set the |
407 |
<tt>INSTALL_PREFIX</tt> variable on the <tt>make</tt> command line. For |
408 |
example, if the installation prefix is set as <tt>/usr/local</tt>, then: |
409 |
<br><tt> make install INSTALL_PREFIX=/usr/local/chroot/</tt> |
410 |
<br>will install files into <tt>/usr/local/chroot/usr/local/bin</tt> and |
411 |
<tt>/usr/local/chroot/usr/local/lib/ircservices</tt>. (The path given <i>must</i> include a trailing slash.) |
412 |
|
413 |
</ol> |
414 |
|
415 |
<p align=right><font size="-1"><a href="#top">Back to top</a></font> |
416 |
|
417 |
<p><hr> |
418 |
|
419 |
<a name=4></a> |
420 |
<h3>2-4. Configuring Services</h3> |
421 |
|
422 |
<p>Once Services has been installed, it must be configured for your |
423 |
network. Services uses two text files to control its behavior: |
424 |
<tt>ircservices.conf</tt> and <tt>modules.conf</tt>. (If Services is |
425 |
configured with a different program name, the first file's name will |
426 |
change to <tt><i>program-name</i>.conf</tt> as well; however, in this |
427 |
manual, the default of <tt>ircservices.conf</tt> is assumed.) |
428 |
<tt>ircservices.conf</tt> contains settings that affect Services as a |
429 |
whole, such as the remote server to connect to; <tt>modules.conf</tt> |
430 |
contains settings that apply to individual modules, such as NickServ and |
431 |
ChanServ. These files are stored in the Services data directory (the |
432 |
directory you gave when running the <tt>configure</tt> script; this is |
433 |
<tt>/var/opt/ircservices</tt> for the binary distributions). |
434 |
|
435 |
<p>When Services is installed, two sample files, |
436 |
<tt>example-ircservices.conf</tt> and <tt>example-modules.conf</tt>, are |
437 |
installed in the data directory. If you are installing Services for the |
438 |
first time, you should start out by copying or renaming these files to |
439 |
<tt>ircservices.conf</tt> and <tt>modules.conf</tt> respectively. Each file |
440 |
contains detailed information about all possible settings, which can also |
441 |
be found in <a href=a.html>Appendix A</a>. When setting up Services for |
442 |
the first time, you should at least check these settings: |
443 |
|
444 |
<div align=center> |
445 |
<b>Table 2-3.</b> Commonly used configuration directives<br><br> |
446 |
<table border=1> |
447 |
<tr><th>File<th>Setting and syntax<th>Description |
448 |
<tr><td><tt>ircservices.conf</tt> |
449 |
<td><tt>RemoteServer <i>host</i>[:<i>port</i>] <i>password</i></tt> |
450 |
<td>Sets the server to which Services connects and the password used to |
451 |
connect. |
452 |
<tr><td><tt>ircservices.conf</tt> |
453 |
<td><tt>ServerName <i>name</i></tt> |
454 |
<td>Sets the server name Services will use on the IRC network. |
455 |
<tr><td><tt>ircservices.conf</tt> |
456 |
<td><tt>ServerDesc <i>description</i></tt> |
457 |
<td>Sets the server description provided by Services. |
458 |
<tr><td><tt>ircservices.conf</tt> |
459 |
<td><tt>ServiceUser <i>user</i>@<i>host</i></tt> |
460 |
<td>Sets the username and hostname used by Services clients. You may |
461 |
want to set this to an E-mail address at which users can ask |
462 |
questions about Services or your IRC network. |
463 |
<tr><td><tt>ircservices.conf</tt> |
464 |
<td><tt>LoadModule <i>module-name</i></tt> |
465 |
<td>Loads the specified module. The example configuration file lists |
466 |
all of the possible modules; select which ones you want to load or |
467 |
not load. In particular, make sure you select the correct protocol |
468 |
module and enter its name in the line which reads |
469 |
"<tt>LoadModule protocol/(insert protocol name here)</tt>" |
470 |
or Services will not be able to start. |
471 |
<tr><td height=3> |
472 |
<tr><td><tt>modules.conf</tt> |
473 |
<td><tt>Module protocol/<i>protocol-name</i></tt> |
474 |
<td>Change this line (the first <tt>Module</tt> line in the file) so it |
475 |
contains the same protocol module you specified in |
476 |
<tt>ircservices.conf</tt>. |
477 |
<tr><td><tt>modules.conf</tt> |
478 |
<td><tt>FromAddress <i>user</i>@<i>host</i></tt> |
479 |
<td><tt>mail/main</tt> module: Sets the E-mail address used as the |
480 |
sender on outgoing mail. Set this to an address at which users can |
481 |
contact you with questions about Services. |
482 |
<tr><td><tt>modules.conf</tt> |
483 |
<td><tt>FromName "<i>name</i>"</tt> |
484 |
<td><tt>mail/main</tt> module: Set this to the "name" you want to use |
485 |
as the sender on outgoing mail. If you don't want a name (just the |
486 |
E-mail address), leave this setting commented out. |
487 |
<tr><td><tt>modules.conf</tt> |
488 |
<td><tt>ServicesRoot <i>nick</i></tt> |
489 |
<td><tt>operserv/main</tt> module: Set this to the nickname which |
490 |
should be granted Services root (super-user) privileges. |
491 |
<tr><td><tt>modules.conf</tt> |
492 |
<td><tt>ListenTo <i>address</i>:<i>port</i></tt> |
493 |
<td><tt>httpd/main</tt> module: Sets the ports to which the Services |
494 |
HTTP server will listen. See <a href="3.html#6">section 3-6</a> |
495 |
for details. |
496 |
</table> |
497 |
</div> |
498 |
|
499 |
<p align=right><font size="-1"><a href="#top">Back to top</a></font> |
500 |
|
501 |
<p><hr> |
502 |
|
503 |
<a name=5></a> |
504 |
<h3>2-5. Configuring your IRC server</h3> |
505 |
|
506 |
<p>The IRC server to which Services will connect must be configured to |
507 |
allow Services to connect as a server. For traditional irc2-based servers, |
508 |
this involves adding appropriate <tt>C:</tt> and <tt>N:</tt> lines to the |
509 |
server's configuration file; consult your IRC server program's |
510 |
documentation for details. |
511 |
|
512 |
<p>Some IRC server programs, including traditional irc2-based ones, do not |
513 |
allow servers to introduce other servers, <i>i.e.</i> act as hubs, without |
514 |
a special configuration setting (an <tt>H:</tt> line in irc2-based |
515 |
servers). If this setting is missing from any server in your network, |
516 |
Services may be disconnected when you use the |
517 |
<a href="4.html#oper.jupe"><tt>JUPE</tt></a> command. |
518 |
|
519 |
<p>In addition, some server programs support a "U-line" or similar concept, |
520 |
allowing servers named in a <tt>U:</tt> line or other configuration |
521 |
directive to override normal privilege checks (and consequently preventing |
522 |
other servers from overriding those checks). If your server program has |
523 |
such an option, ensure that it is set on all servers in your network, or |
524 |
you may encounter problems such as ChanServ being unable to change channel |
525 |
modes. |
526 |
|
527 |
<p>Also see the notes in <a href="#table1">table 2-1</a> above for special |
528 |
considerations when configuring particular types of IRC servers. |
529 |
|
530 |
<p><hr> |
531 |
|
532 |
<a name=6></a> |
533 |
<h3>2-6. Starting, stopping and controlling Services</h3> |
534 |
|
535 |
<p>Services can be started by simply running the <tt>ircservices</tt> |
536 |
program from a shell prompt. Upon starting, Services will parse its |
537 |
command-line arguments and the <tt>ircservices.conf</tt> file, then open |
538 |
the log file; if there are no errors, it will then print a short message to |
539 |
the terminal, put itself in the background and return control to the shell. |
540 |
If an error does occur, Services will print an error message and exit. |
541 |
|
542 |
<p>Several command-line options can be used to modify Services' behavior or |
543 |
override settings in the <tt>ircservices.conf</tt> configuration file; these |
544 |
are summarized in table 2-4 below. The command-line option <tt>-help</tt> |
545 |
can be used to get a list of all available options. |
546 |
|
547 |
<div align=center> |
548 |
<b>Table 2-4.</b> <tt>ircservices</tt> command-line options<br><br> |
549 |
<table border=1> |
550 |
<tr><th>Option<th>Meaning |
551 |
<tr><td><tt>-help</tt> |
552 |
<td>Prints a list of available options. |
553 |
<tr><td><tt>-dir=<i>pathname</i></tt> |
554 |
<td>Uses <tt><i>pathname</i></tt> as the data directory instead of the |
555 |
compiled-in default. |
556 |
<tr><td><tt>-remote=<i>host</i>[:<i>port</i>]</tt> |
557 |
<td>Connects to the specified server, overriding the |
558 |
<tt>RemoteServer</tt> setting in <tt>ircservices.conf</tt>. |
559 |
<tr><td><tt>-log=<i>filename</i></tt> |
560 |
<td>Writes logging information to <tt><i>filename</i></tt>, overriding |
561 |
the <tt>LogFilename</tt> setting in <tt>ircservices.conf</tt>. |
562 |
<tr><td><tt>-debug</tt> |
563 |
<td>Starts Services in debug mode; using this option multiple times |
564 |
will produce more debugging output. |
565 |
<tr><td><tt>-readonly</tt> |
566 |
<td>Starts Services in read-only mode; database and log files will not |
567 |
be written to, and online data modification will be limited to |
568 |
Services administrators. |
569 |
<tr><td><tt>-nofork</tt> |
570 |
<td>Prevents Services from forking (going into the background) after |
571 |
initialization, and causes log messages to be written to the |
572 |
terminal as well as the log file. |
573 |
<tr><td><tt>-noexpire</tt> |
574 |
<td>Disables expiration of database entries (nicknames, channels, |
575 |
autokills, and so on). |
576 |
<tr><td><tt>-noakill</tt> |
577 |
<td>Disables autokill checking. (However, the autokill list itself can |
578 |
still be modified.) |
579 |
<tr><td><tt>-forceload</tt> |
580 |
<td>When using the <tt>database/version4</tt> module, attempts to load |
581 |
as much data from corrupted databases as possible, rather than |
582 |
aborting when an error is found. |
583 |
<tr><td><tt>-encrypt-all</tt> |
584 |
<td>Re-encrypts all passwords on startup using the encryption type |
585 |
selected in <tt>ircservices.conf</tt>. (Passwords encrypted with |
586 |
one type generally cannot be re-encrypted with a different type, so |
587 |
this is generally useful only to ensure that no passwords are left |
588 |
unencrypted after activating encryption.) |
589 |
<tr><td><tt>-import=<i>filename</i></tt> |
590 |
<td>Imports data into Services' databases (see <a href="5.html#2">section |
591 |
5-2</a>). |
592 |
</table> |
593 |
</div> |
594 |
|
595 |
<p>Once in the background, Services will load language files and modules, |
596 |
then try to connect to the remote server specified in <tt>ircservices.conf</tt> |
597 |
(or on the command line). If any errors occur during these steps, an error |
598 |
message will be printed to the log file and Services will terminate. If |
599 |
Services appears to start up correctly but does not connect to your IRC |
600 |
network, check the log file for any errors that may have occurred. |
601 |
|
602 |
<p>Once Services successfully connects to your IRC network, it will |
603 |
continue running until either: |
604 |
<ul><li>the remote server closes the connection (for example, because of a |
605 |
<tt>/SQUIT</tt> command); |
606 |
<li>an OperServ <a href="4.html#oper.restart"><tt>RESTART</tt></a>, |
607 |
<a href="4.html#oper.shutdown"><tt>SHUTDOWN</tt></a>, or |
608 |
<a href="4.html#oper.quit"><tt>QUIT</tt></a> command is received; or |
609 |
<li>a termination signal (<tt>SIGINT</tt> [<tt>^C</tt>], |
610 |
<tt>SIGQUIT</tt>, <tt>SIGTERM</tt>, or <tt>SIGKILL</tt>, as well as |
611 |
fatal program errors) is received. |
612 |
</ul> |
613 |
In any of these cases (except in the case of a <tt>SIGKILL</tt> signal, |
614 |
which Services cannot detect), an appropriate message will be written to |
615 |
the log file describing why Services terminated. |
616 |
|
617 |
<p>The debug output level and read-only setting can be modified while |
618 |
Services is running using the OperServ |
619 |
<a href="4.html#oper.set"><tt>SET</tt></a> command as needed, and other |
620 |
OperServ commands can be used to monitor the status of Services or (as |
621 |
mentioned above) shut down or restart Services. |
622 |
|
623 |
<p>While it is running, Services will periodically save modified data |
624 |
(newly registered nicknames and channels, modified settings, and so on) to |
625 |
disk. This is done in such a way that even if Services crashes while |
626 |
writing the data, the previous contents of the databases will remain intact. |
627 |
However, should the database files become corrupt (whether because of a bug |
628 |
in Services or as the result of hardware failure or tampering), the |
629 |
<tt>-forceload</tt> command-line option can be used to recover as much data |
630 |
as possible from the corrupted data file. It is also <b>strongly |
631 |
recommended</b> that you make regular backups of your data files, to reduce |
632 |
potential damage from such problems. |
633 |
|
634 |
<p>If the contents of the <tt>ircservices.conf</tt> or <tt>modules.conf</tt> |
635 |
configuration files are changed, Services can be instructed to reread the |
636 |
files with either the OperServ |
637 |
<a href="4.html#oper.rehash"><tt>REHASH</tt></a> command or the |
638 |
<tt>SIGHUP</tt> signal. If no errors are found in the configuration files, |
639 |
Services' settings will be updated with the new configuration file |
640 |
contents. Modules can also be loaded and unloaded this way without |
641 |
restarting Services by adding or removing <tt>LoadModule</tt> directives in |
642 |
<tt>ircservices.conf</tt>; however, modules will not be able to be unloaded |
643 |
if other loaded modules depend on them. (For example, since the ChanServ |
644 |
module depends on NickServ being available, you cannot remove the NickServ |
645 |
module while leaving the ChanServ module loaded. You can, however, unload |
646 |
both of them at once.) |
647 |
|
648 |
<a name="6-ircservices-chk"></a> |
649 |
<p>If the system Services runs on supports periodic execution of programs, |
650 |
such as via the <tt>cron</tt> utility, you can use the supplied script |
651 |
<tt>ircservices-chk</tt>, installed in the same directory as the |
652 |
<tt>ircservices</tt> executable, to ensure that Services comes back up |
653 |
quickly if it should crash or otherwise terminate unexpectedly. (Of |
654 |
course, you will need to disable this check if you ever shut down Services |
655 |
intentionally!) On a typical Unix system, the following line, when added |
656 |
using the <tt>crontab</tt> utility, will cause the <tt>ircservices-chk</tt> |
657 |
script to be run once every five minutes (here, |
658 |
<tt>/path/to/ircservices-chk</tt> represents the full path to the |
659 |
<tt>ircservices-chk</tt> script): |
660 |
|
661 |
<div align=center> |
662 |
<blockquote> |
663 |
<tt>0,5,10,15,20,25,30,35,40,45,50,55 * * * * /path/to/ircservices-chk</tt> |
664 |
</blockquote> |
665 |
</div> |
666 |
|
667 |
<p>If you need to pass options to the <tt>ircservices</tt> executable, |
668 |
simply add them after <tt>ircservices-chk</tt> in the line above. You can |
669 |
also prevent the script from generating output (which would be sent to you |
670 |
by mail) by adding the <tt>-q</tt> option after <tt>ircservices-chk</tt> |
671 |
and before any other options. |
672 |
|
673 |
<p align=right><font size="-1"><a href="#top">Back to top</a></font> |
674 |
|
675 |
<p><hr> |
676 |
|
677 |
<p align=right><font size=-1><a href="1.html">Previous section: About IRC Services</a> | |
678 |
<a href="index.html">Table of Contents</a> | |
679 |
<a href="3.html">Next section: Overview of Services features</a></font> |
680 |
|
681 |
</body> |
682 |
</html> |