ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/2.html
Revision: 3389
Committed: Fri Apr 25 14:12:15 2014 UTC (9 years, 10 months ago) by michael
Content type: text/html
File size: 33591 byte(s)
Log Message:
- Imported ircservices-5.1.24

File Contents

# Content
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>&nbsp;&nbsp;&nbsp;&nbsp;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 * * * *&nbsp;&nbsp;&nbsp;&nbsp;/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>