ViewVC Help
View File | Revision Log | Show Annotations | View Changeset | Root Listing
root/svn/vendor/ircservices-5.1.24/docs/3.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: 137040 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 - 3. Overview of Services features</title>
6 </head>
7
8 <body>
9 <a name=top></a>
10 <h1 align=center>IRC Services Manual</h1>
11
12 <h2 align=center>3. Overview of Services features</h2>
13
14 <p>3-1. <a href="#1">Nickname management (NickServ)</a>
15 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-1. <a href="#1-1">Core NickServ features</a>
16 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-2. <a href="#1-2">Netsplit recovery</a>
17 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-3. <a href="#1-3">Nickname linking</a>
18 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-4. <a href="#1-4">E-mail authentication</a>
19 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-5. <a href="#1-5">Access lists</a>
20 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-6. <a href="#1-6">Miscellaneous functions</a>
21 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-1-7. <a href="#1-7">Command aliases</a>
22 <br>3-2. <a href="#2">Channel management (ChanServ)</a>
23 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-2-1. <a href="#2-1">Core ChanServ features</a>
24 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-2-2. <a href="#2-2">Channel access lists</a>
25 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-2-3. <a href="#2-3">Channel expiration</a>
26 <br>3-3. <a href="#3">Memo sending (MemoServ)</a>
27 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-3-1. <a href="#3-1">Core MemoServ features</a>
28 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-3-2. <a href="#3-2">Memos and channels</a>
29 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-3-3. <a href="#3-3">Memo ignore lists</a>
30 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-3-4. <a href="#3-4">Memo forwarding</a>
31 <br>3-4. <a href="#4">Network/Services control and maintenance (OperServ)</a>
32 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-4-1. <a href="#4-1">Services privilege levels</a>
33 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-4-2. <a href="#4-2">Core OperServ features</a>
34 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-4-3. <a href="#4-3">Autokills and S-lines</a>
35 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-4-4. <a href="#4-4">Session limiting</a>
36 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-4-5. <a href="#4-5">News</a>
37 <br>3-5. <a href="#5">Network statistics collection (StatServ)</a>
38 <br>3-6. <a href="#6">Built-in HTTP server</a>
39 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-6-1. <a href="#6-1">Core HTTP server module</a>
40 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-6-2. <a href="#6-2">Authorization modules</a>
41 <br>&nbsp;&nbsp;&nbsp;&nbsp;3-6-3. <a href="#6-3">Content modules</a>
42 <br>3-7. <a href="#7">Password encryption</a>
43 <br>3-8. <a href="#8">E-mail sending</a>
44 <br>3-9. <a href="#9">Multilingual support</a>
45 <br>3-10. <a href="#10">Third-party extensions</a>
46
47 <p align=right><font size=-1><a href=2.html>Previous section: Installing and using Services</a> |
48 <a href=index.html>Table of Contents</a> |
49 <a href=4.html>Next section: Services command reference</a></font>
50
51 <!------------------------------------------------------------------------>
52 <p><hr>
53
54 <a name=1></a>
55 <h3>3-1. Nickname management (NickServ)</h3>
56
57 <a name=1-1></a>
58 <h4>3-1-1. Core NickServ features</h4>
59
60 <p>IRC Services' features are based around the concept of "registering" a
61 nickname as one's own. Once you have registered a nickname, Services will
62 recognize you as the "owner" of that nick, and will warn anyone else who
63 tries to use the nick that it is owned by someone else; Services can even
64 prevent other people from using a registered nick by removing ("killing")
65 them from the network or forcibly changing their nickname to something
66 else.
67
68 <p>The "<b>NickServ</b>" pseudoclient provides the interface to functions
69 related to nickname registration and maintenance. (The nickname "NickServ"
70 can be changed via the
71 <a href="a.html#nickserv/main.NickServName"><tt>NickServName</tt></a>
72 setting in the <tt>modules.conf</tt> configuration file.) NickServ
73 receives commands via <tt>/msg</tt>; for example, typing
74 <blockquote>
75 <tt>/msg NickServ REGISTER password</tt>
76 </blockquote>
77 would send NickServ the "<tt>REGISTER</tt>" command, used to register a
78 nickname, with "<tt>password</tt>" as its parameter. Command names are
79 case-insensitive, so "<tt>register</tt>" or "<tt>ReGiStEr</tt>" could be
80 used instead of "<tt>REGISTER</tt>", for example.
81
82 <p>Typically, when first connecting to a network using Services, a user
83 will use the <a href="4.html#nick.register"><tt>REGISTER</tt></a> command
84 (as in the example above) to register their nickname with Services,
85 assuming it is not already used. Once the nickname is registered, the user
86 would then use the <a href="4.html#nick.identify"><tt>IDENTIFY</tt></a>
87 command with the password given in the <tt>REGISTER</tt> command every time
88 they connected to the network, informing Services that they are the owner
89 of the nick and should be permitted to use it; this can be thought of as
90 similar to logging into an Internet service provider account. Finally, if
91 the user decides to stop using their nickname, whether because of changing
92 to another nickname or switching IRC networks entirely, they can use the
93 <a href="4.html#nick.drop"><tt>DROP</tt></a> command to cancel the
94 nickname's registration. (Even if the nickname is not explicitly dropped,
95 it will expire if not used for 30 days, or whatever value is given for the
96 <a href="a.html#nickserv/main.NSExpire"><tt>NSExpire</tt></a> setting in
97 <tt>modules.conf</tt>.)
98
99 <a name=1-1.NSRequireEmail></a>
100 <p>Users can also include an E-mail address when they register a nickname.
101 This will be stored with the nick and can be used to allow other users or
102 IRC operators to contact the user outside of IRC. By setting the
103 <a href="a.html#nickserv/main.NSRequireEmail"><tt>NSRequireEmail</tt></a>
104 option in <tt>modules.conf</tt>, the E-mail address can be made mandatory
105 at registration time. In addition, the
106 <a href="a.html#nickserv/main.NSRegEmailMax"><tt>NSRegEmailMax</tt></a>
107 option can be used to set the maximum number of nicknames that can be
108 registered to a single E-mail address, and the
109 <a href="a.html#RejectEmail"><tt>RejectEmail</tt></a> directive (in
110 <tt>ircservices.conf</tt>) can be used to specify addresses that cannot be
111 used for registration.
112
113 <p>The <a href="4.html#nick.list"><tt>LIST</tt></a> and
114 <a href="4.html#nick.info"><tt>INFO</tt></a> commands are available to
115 display, respectively, a list of registered nicknames matching a particular
116 pattern or detailed information on a single nickname. The <tt>LIST</tt>
117 command simply displays a list of nicknames with the last seen
118 <tt><i>user</i>@<i>host</i></tt> address for each nick; the <tt>INFO</tt>
119 command displays the nick owner's last seen address and "real name", the
120 time of registration and of last use, and last quit message, as well as any
121 URL, E-mail, or information line that have been set for the nickname (see
122 below). Of this information, the nick owner can choose to hide the last
123 seen address, last quit message, and E-mail address from ordinary users by
124 using the <a href="4.html#nick.set_hide"><tt>SET HIDE</tt></a> command.
125 Note that usage of the <tt>LIST</tt> command can be limited to IRC
126 operators by setting the
127 <a href="a.html#nickserv/main.NSListOpersOnly"><tt>NSListOpersOnly</tt></a>
128 option in <tt>modules.conf</tt>.
129
130 <a name="1-1.set-kill"></a>
131 <p>Normally, when a user tries to use a registered nickname, Services will
132 only send a warning that the nickname is registered, and not take any
133 further action (aside from denying privileges on registered channels, as
134 described in <a href="#2">section 3-2</a> on channel management). By using
135 the <a href="4.html#nick.set_kill"><tt>SET KILL</tt></a> command, however,
136 users can instruct Services to forcibly prevent other users from using
137 their nicknames. If a user does not identify for a nickname with the
138 <tt>KILL</tt> option set within a certain period of time, NickServ will
139 either use a <tt>/kill</tt> to disconnect the user from the network or (if
140 the IRC server supports it and the
141 <a href="a.html#nickserv/main.NSForceNickChange"><tt>NSForceNickChange</tt></a>
142 option is set in <tt>modules.conf</tt>) forcibly change the user's nickname
143 to a "guest" nick, like Guest12345 (the "Guest" prefix can be changed
144 using the <a href="a.html#GuestNickPrefix"><tt>GuestNickPrefix</tt></a>
145 directive in <tt>ircservices.conf</tt>). Services will also introduce an
146 "enforcer" pseudoclient with the nickname in question, to prevent the user
147 from immediately reconnecting or changing their nick back; the enforcer
148 will be removed after one minute. The <tt>KILL</tt> option defaults to
149 off, but can be set to on (60 second time limit), quick (20 second time
150 limit), or immediate&mdash;an option which comes into play with
151 <i><a href="#1-5">access lists</a>,</i> discussed below. (Note that the
152 "immediate" setting is not available unless the
153 <a href="a.html#nickserv/main.NSAllowKillImmed"><tt>NSAllowKillImmed</tt></a>
154 option has been set in <tt>modules.conf</tt>.)
155
156 <p>The <tt>SET HIDE</tt> and <tt>SET KILL</tt> commands mentioned above are
157 just two of the options available for the
158 <a href="4.html#nick.set"><tt>SET</tt></a> command, which allows users to
159 adjust various features of their nicknames. Users can change their
160 nickname password (<a href="4.html#nick.set_password"><tt>SET PASSWORD</tt></a>)
161 or set a URL (home page address), E-mail address, or "information line" for
162 their nickname (<tt>SET <a href="4.html#nick.set_url">URL</a></tt>,
163 <a href="4.html#nick.set_email"><tt>EMAIL</tt></a>, and
164 <a href="4.html#nick.set_info"><tt>INFO</tt></a> respectively), which will
165 be displayed when other users request information on the nick with the
166 <tt>INFO</tt> command; a number of options for the nickname can be set as
167 well, such as the aforementioned <tt>KILL</tt> and <tt>HIDE</tt> options,
168 or whether the nickname should appear in output from a <tt>LIST</tt>
169 command (<a href="4.html#nick.set_private"><tt>SET PRIVATE</tt></a>).
170 Default options for newly registered nicknames can be set using the
171 <a href="a.html#nickserv/main.NSDef..."><tt>NSDef...</tt></a> configuration
172 options in <tt>modules.conf</tt>. Users can also set their local time zone
173 (<tt>TIMEZONE</tt>), so that Services sends timestamps in the user's local
174 time, or change the language in which Services sends notices and replies
175 (<tt>LANGUAGE</tt>; see also <a href="#9">section 3-9</a>).
176
177 <p>For the URL, E-mail address, and information line, the
178 <a href="4.html#nick.unset"><tt>UNSET</tt></a> is available to clear any
179 previously set value. (If the <tt>NSRequireEmail</tt> configuration
180 option is set, the E-mail address may not be cleared.)
181
182 <p>If the owner of a nickname discovers that another user is using their
183 nick, then they can use the <a href="4.html#nick.recover"><tt>RECOVER</tt></a>
184 command to have Services disconnect (or change the nick of) the user
185 immediately; the <a href="4.html#nick.release"><tt>RELEASE</tt></a> command
186 is also available to remove the nickname enforcer before its one-minute
187 timeout. A related command, <a href="4.html#nick.ghost"><tt>GHOST</tt></a>,
188 simply disconnects the user of the nickname immediately without using an
189 enforcer, and is intended for cases where the nick's owner gets
190 disconnected from and reconnects to the IRC server, and the disconnected
191 ("ghost") session has not disappeared from IRC yet.
192
193 <p>One other command, <a href="4.html#nick.status"><tt>STATUS</tt></a>,
194 allows users (and bots or other automated clients) to check whether a
195 particular user is recognized as the owner of the nickname they are using;
196 the reply will contain a number indicating whether the nickname is
197 registered and whether the user has identified for that nickname.
198
199 <a name="1-1.servadmin"></a>
200 <p>Services administrators (see <a href="#4-1">section 3-4-1</a>) have
201 access to the following additional commands:</p>
202
203 <p><ul>
204 <li>the <a href="4.html#nick.dropnick"><tt>DROPNICK</tt></a> command,
205 which allows any nickname to be dropped;
206
207 <p><li>the <a href="4.html#nick.set_noexpire"><tt>SET NOEXPIRE</tt></a>
208 command, which allows a nickname to be marked so that it never
209 expires;
210
211 <p><li>the <a href="4.html#nick.getpass"><tt>GETPASS</tt></a> command,
212 which allows the password for a nickname to be retrieved (this may
213 not be possible when encryption is in use&mdash;see
214 <a href="#7">section 3-7</a>&mdash;and can be disabled anyway by
215 unsetting the
216 <a href="a.html#EnableGetpass"><tt>EnableGetpass</tt></a>
217 configuration option in <tt>ircservices.conf</tt>);
218
219 <p><li>the <a href="4.html#nick.suspend"><tt>SUSPEND</tt></a> command,
220 which can be used to prevent a nickname's owner from using that
221 nick for a certain period of time while retaining the nickname's
222 settings;
223
224 <p><li>and the <a href="4.html#nick.forbid"><tt>FORBID</tt></a> command,
225 which completely prevents any use of a nickname and erases any
226 previous settings.
227 </ul>
228
229 <p>Additionally, Services administrators may use the <tt>SET</tt> and
230 <tt>UNSET</tt> commands for any nickname (see the
231 <a href="4.html#nick.set"><tt>SET</tt></a> and
232 <a href="4.html#nick.unset"><tt>UNSET</tt></a> documentation). Note,
233 however, that if the
234 <a href="a.html#WallAdminPrivs"><tt>WallAdminPrivs</tt></a> configuration
235 option is set in <tt>ircservices.conf</tt>, then a message will be
236 broadcast to all IRC operators whenever any of these commands or command
237 formats are used.
238
239 <p>Without any safeguards on these commands, a rogue administrator could
240 abuse their privileges to lock other administrators out. If the
241 <a href="a.html#nickserv/main.NSSecureAdmins"><tt>NSSecureAdmins</tt></a>
242 configuration option is set in <tt>modules.conf</tt> (as it is in the
243 example configuration file), NickServ will reject any attempt to use the
244 <tt>DROPNICK</tt>, <tt>GETPASS</tt>, <tt>SUSPEND</tt>, <tt>FORBID</tt>, or
245 <tt>SET PASSWORD</tt> command on a Services administrator (or the Services
246 super-user; see <a href="#4-1">section 3-4-1</a>). These restrictions are
247 not applied to the Services super-user.
248
249 <p>Note that it is possible to prevent users from registering nicknames.
250 The <a href="a.html#nickserv/main.NSEnableRegister"><tt>NSEnableRegister</tt></a>
251 configuration option (in <tt>modules.conf</tt>) controls whether the
252 <tt>REGISTER</tt> command is available; if you remove this directive, then
253 NickServ will not allow nicknames to be registered. (However, nicknames
254 which have already been registered can be used with Services as usual.)
255
256 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
257
258 <a name=1-2></a>
259 <h4>3-1-2. Netsplit recovery</h4>
260
261 <p>One additional feature of NickServ is "netsplit recovery". Normally, if
262 a netsplit (<i>i.e.,</i> the breaking of a server-server link) occurs, or
263 if Services itself is terminated or otherwise disconnected from the
264 network, all users on and behind the disconnected server will appear to
265 Services to have left IRC. When the server (or Services) is reconnected,
266 those users will appear as new users, and normally Services would then
267 require each user to re-identify for their nickname; users who are away
268 from their computers could even be disconnected from the network, depending
269 on the nickname's settings.
270
271 <p>In order to avoid this hassle, Services remembers information about the
272 last user who identified for each nickname. When a new user connects to
273 the network, Services compares the information for the new user to that for
274 the last user who identified for the nickname, and if they match, Services
275 allows the user to continue using the nickname as if they had identified
276 again.
277
278 <p>Obviously, this can lead to security problems depending on the
279 information used to make this check. Unfortunately, the standard IRC
280 protocol definition (as defined in RFC 1459<sup><a href="#1-2.rfc">1</a></sup>)
281 only includes the username and hostname in the information sent to other
282 servers about each user; since users can usually set their own username,
283 and since there are ways, albeit difficult ones, to fool an IRC server into
284 seeing an arbitrary hostname, checking this information alone is not very
285 secure. Fortunately, various IRC server implementors have developed their
286 own methods of including such information, and Services can take advantage
287 of these as well. In decreasing order of security, these are:
288
289 <p><dl>
290 <dt><b>Services stamp</b> (available in the <tt>bahamut</tt>,
291 <tt>dreamforge</tt>, <tt>monkey</tt>, <tt>solidircd</tt>,
292 <tt>trircd</tt>, and <tt>unreal</tt> modules)
293 <dd>The most secure way to check whether a user is new or not. These
294 servers allow Services to set a "Services stamp", a unique number,
295 for each user; the server remembers the number until the user
296 leaves IRC, so even if the server splits from the network, Services
297 will be able to tell that it's the same user when the server
298 reconnects. The number has a range from 1 to over 2,000,000,000,
299 making it practically impossible for a malicious user to obtain the
300 same Services stamp as a user already on the network, at least
301 given current technology. (As an example, on a network of 30
302 servers, an attack introducing 50 new clients every second on every
303 server&mdash;requiring at least 10-15 megabits/second of
304 bandwidth&mdash;would need to be sustained for over 16 days to
305 cause the stamp to roll over.) Unless you have concerns about the
306 security of your servers themselves, this method can be considered
307 100% safe for all intents and purposes.
308 <dt><b>User timestamp</b> (available in the <tt>dalnet</tt>, <tt>hybrid</tt>,
309 <tt>inspircd</tt>, <tt>ptlink</tt>, <tt>ratbox</tt>, <tt>ts8</tt>, and
310 <tt>undernet-p9</tt> modules)
311 <dd>A number recorded by each server for each user, representing the time
312 at which the user connected to the server. Since this value
313 increases every second, it is difficult to obtain the same
314 timestamp as a user connected to the network, but it may still be
315 possible if your servers' clocks are not all synchronized. For
316 small- to medium-size networks, this method is reasonably secure.
317 <dt><b>Username and hostname only</b> (the <tt>rfc1459</tt> module)
318 <dd>As described above, checking only the username and hostname is not very
319 secure, and you may want to disable netsplit recovery, as described
320 below.
321 </dl>
322
323 <p>If you are concerned about the security of the check, you can disable
324 netsplit recovery by using the
325 <a href="a.html#NoSplitRecovery"><tt>NoSplitRecovery</tt></a> option in
326 <tt>ircservices.conf</tt>.
327
328 <a name=1-2.rfc></a>
329 <p><sup>1</sup><font size="-1">"RFC" is short for "Request For Comments",
330 the name given to documents describing Internet protocols and other
331 Internet-related information. See
332 <a href="http://www.rfc-editor.org/"><tt>http://www.rfc-editor.org/</tt></a>
333 for more information.</font>
334
335 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
336
337 <a name=1-3></a>
338 <h4>3-1-3. Nickname linking</h4>
339
340 <p>Several additional functions are available through add-on modules.
341 Chief among these is "nickname linking", available with the
342 <tt>nickserv/link</tt> module.
343
344 <p>Many users like to use variations on their main nickname; for example, a
345 user with the nickname "Alice" might use "AliceAway" while away from her
346 terminal, or "AliceZZZ" if she left her IRC client connected all night.
347 While it is of course possible to register each of these nicknames
348 separately, the owner would then have to identify for each nickname
349 separately as well; nickname settings, such as setting an E-mail address or
350 URL, would also have to be done individually for each nick. More
351 importantly, channel access lists (see <a href="#2-2">section 3-2-2</a>)
352 would require one entry for each nickname, causing the size of the access
353 list to double, triple, or worse.
354
355 <p>In order to avoid this problem, Services provides a way to link multiple
356 nicknames together so that they are, for all practical purposes, treated as
357 the same nick. Aside from information truly specific to each
358 nickname&mdash;last seen time, address, name, and quit message&mdash;all
359 information is shared among all of the linked nicknames, and they can be
360 used interchangeably with no extra effort on the part of the nickname owner
361 or other users. (A set of nicknames linked in this way is also called a
362 "nickname group".)
363
364 <p>Nickname owners can link other nicknames to their own with the
365 <a href="4.html#nick.link"><tt>LINK</tt></a> command; this command takes an
366 unregistered nickname and links it to the user's current nickname. The
367 <a href="4.html#nick.unlink"><tt>UNLINK</tt></a> command does the reverse,
368 cancelling a link from a nickname and releasing that nick for others to use.
369 Additionally, the <a href="4.html#nick.listlinks"><tt>LISTLINKS</tt></a>
370 command is available to give a list of all nicknames linked to the user's
371 current nickname; one of these will be marked with an asterisk
372 ("<tt>*</tt>"), which indicates the "main nickname" for the group of
373 nicknames. The main nickname defaults to the first nickname registered in
374 the group, and can be changed using the
375 <a href="4.html#nick.set_mainnick"><tt>SET MAINNICK</tt></a> command.
376 (Main nicknames are discussed in more detail in the section on channel
377 access lists.)
378
379 <p><tt>LISTLINKS</tt> can also be used by Services operators to view the
380 list of links for an arbitrary nickname, by giving that nickname after the
381 <tt>LISTLINKS</tt> command. While normal users are not allowed to use
382 <tt>LISTLINKS</tt> in this fashion, the same effect can be accomplished
383 for users whose E-mail address is not hidden by combining <tt>INFO</tt>
384 (to (to get the user's E-mail address) and <tt>LISTEMAIL</tt> (to list all
385 nicknames, including links, registered by that E-mail address). If this is
386 a concern, enable the <tt>NSListOpersOnly</tt> option in
387 <tt>modules.conf</tt> to prevent use of the <tt>LISTEMAIL</tt> command.
388
389 <p>The <tt>INFO</tt> command changes its behavior slightly for linked
390 nicknames: When a user has two or more linked nicknames and is using one
391 of them, an <tt>INFO</tt> on one of the nicknames that is not in use will
392 indicate which nickname is currently in use (for example,
393 "<tt>/msg NickServ INFO SomeNick</tt>" might respond with "<tt>Is using
394 nickname: SomeNick[away]</tt>"). This can be prevented by setting the
395 <tt>PRIVATE</tt> option for the nickname group (however, Services
396 administrators can always see this information).
397
398 <p>Note that the <tt>DROP</tt> command will drop <i>all</i> nicks linked to
399 the current nick (as well as the current nick itself); to cancel a single
400 linked nick while leaving the others intact, use the <tt>UNLINK</tt>
401 command instead.
402
403 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
404
405 <a name=1-4></a>
406 <h4>3-1-4. E-mail authentication</h4>
407
408 <p>In order to help enforce accountability for registered nicknames, Services
409 can require users to "authenticate" their nickname registration using a
410 numeric code sent via E-mail to the address provided when the nickname is
411 registered. In order to have Services recognize the nickname as a valid,
412 registered nickname, the owner must send the code back to Services first,
413 thus verifying that the E-mail address the owner provided is in fact valid.
414 This functionality is provided by the <tt>nickserv/mail-auth</tt> module.
415 Note that this module requires a mail module (<a href="#8">section 3-8</a>)
416 to be loaded in order to function.
417
418 <p>When this module is in use, registration of a nickname proceeds as
419 follows:</p>
420
421 <ol>
422 <li>The user sends a <tt>REGISTER</tt> command to NickServ, just as with
423 a normal registration; however, an E-mail address is mandatory with
424 the command. (The <tt>nickserv/mail-auth</tt> module will refuse
425 to load if the <tt>NSRequireEmail</tt> configuration option,
426 mentioned <a href="#1-1.NSRequireEmail">above</a>, is not set.)
427 <p><li>The normal registration checks are made: if the nickname is
428 forbidden, the E-mail address is invalid, or some other problem
429 occurs, Services reports an error and discards the
430 <tt>REGISTER</tt> command.
431 <p><li>A random 9-digit authentication code is generated, stored with the
432 nickname in Services' databases, and sent via E-mail to the user.
433 The E-mail looks like this, if the default language is set to
434 English:
435 <blockquote><tt>
436 The authentication code for your nickname (NickName) is: 123456789
437 <br>Please submit this code to NickServ with the command:
438 <br>/msg NickServ AUTH 123456789
439 <br>
440 <br>This message was sent by NickServ in response to registration by
441 <br>username@hostname.example.com.
442 </tt></blockquote>
443 <p><li>Services informs the user that their nickname has been registered,
444 and that they will need to authenticate it with the code sent to
445 their E-mail address before they can use it.
446 <p><li>The user sends an <tt><a href="4.html#nick.auth">AUTH</a></tt>
447 command to NickServ with the code given in the E-mail.
448 <p><li>Services checks that the code given matches the one sent, and if so,
449 marks the nickname as authenticated and allows it to be used
450 normally (the user will get privileges in channels if on the
451 channel's access list, etc.).
452 </ol>
453
454 <p>A procedure similar to the above is followed when a nickname owner
455 changes the E-mail address associated with the nickname using the <tt>SET
456 EMAIL</tt> command.
457
458 <p>If a user accidentally gives the wrong E-mail address to a <tt>SET
459 EMAIL</tt> command, they can restore the previous (authenticated) address
460 via the <a href="4.html#nick.restoremail"><tt>RESTOREMAIL</tt></a> command,
461 without having to interact with a Services administrator. This command is
462 not available once the new address has been authenticated.
463
464 <a name=1-3.sendauth></a>
465 <p>If for some reason, such as a mail server problem, the user does not
466 receive the E-mail message containing the authentication code, they can
467 request that an extra copy of the message be sent by using the
468 <a href="4.html#nick.sendauth"><tt>SENDAUTH</tt></a> command. By default,
469 Services will only allow this command to be used once a day per nickname
470 (nickname group when links are in use) in order to minimize potential abuse
471 of this command, <i>e.g.,</i> to send "mail-bombs" to other users. If
472 necessary, this interval can be changed using the
473 <a href="a.html#nickserv/mail-auth.NSSendauthDelay"><tt>NSSendauthDelay</tt></a>
474 option in <tt>modules.conf</tt>; however, if it is set too low or disabled,
475 malicious users will be able to abuse Services to send large amounts of
476 mail to arbitrary users.
477
478 <p>Services can be set to automatically drop unauthenticated nicknames after
479 a shorter period than the usual expiration time. The configuration option
480 <a href="a.html#nickserv/mail-auth.NSNoAuthExpire"><tt>NSNoAuthExpire</tt></a>
481 in <tt>modules.conf</tt> is used to set this time; by default it is not set,
482 meaning that unauthenticated nicknames will be retained until the usual
483 expiration time (defined by <tt>NSExpire</tt>). Note that
484 <tt>NSNoAuthExpire</tt> is not applied to nicknames pending authentication
485 for an E-mail address change.
486
487 <p>Additionally, the commands
488 <a href="4.html#nick.setauth"><tt>SETAUTH</tt></a>,
489 <a href="4.html#nick.getauth"><tt>GETAUTH</tt></a>, and
490 <a href="4.html#nick.clearauth"><tt>CLEARAUTH</tt></a> are available to
491 Services administrators. The <tt>SETAUTH</tt> command generates a new
492 authentication code for the given nickname, requiring its owner to
493 authenticate the nick before continuing to use it; the <tt>GETAUTH</tt>
494 command retrieves the authentication code stored for the given nickname,
495 if any; and the <tt>CLEARAUTH</tt> command clears any stored authentication
496 code and allows the nickname's owner to use the nick normally, as if they
497 had authenticated it with the <tt>AUTH</tt> command.
498
499 <p>Finally, NickServ recognizes the command-line option
500 "<tt>-clear-nick-email</tt>"; when this option is given, all nicknames'
501 E-mail addresses will be cleared on startup, which can be useful when
502 first activating the E-mail authentication module. See
503 <a href="upgrade.html#4.5-5">the upgrade notes</a> for details.
504
505 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
506
507 <a name=1-5></a>
508 <h4>3-1-5. Access lists</h4>
509
510 <p>Normally, when a user connects to the IRC network, the user must
511 identify to NickServ with their password before Services will recognize
512 them as the owner of their nickname. Access lists, provided by the
513 <tt>nickserv/access</tt> module, provide a way for users to be
514 recognized as nickname owners based on the user's
515 <tt><i>user</i>@<i>host</i></tt> address (the address shown in a
516 <tt>/whois</tt> reply among other places) and given limited privileges
517 without having to identify by password.
518
519 <p>A nickname's access list consists of one or more "masks"; these are
520 strings containing wildcards, similar to channel ban masks except that the
521 mask includes a username and hostname only, no nickname. When a nickname
522 is first registered, an access mask is added which matches the user's
523 current username and hostname. If the
524 <a href="a.html#nickserv/access.NSFirstAccessWild"><tt>NSFirstAccessWild</tt></a>
525 configuration option is set, then the the leftmost part of the hostname (if
526 a domain name; the rightmost part of an IP address) is replaced with a "*"
527 to match any address in that network, in case the user's IP address changes
528 (for example, due to disconnecting from and reconnecting to the user's
529 service provider). After registering a nickname, users can use the
530 <a href="4.html#nick.access"><tt>ACCESS</tt></a> command to view or modify
531 the nickname's access list.
532
533 <p>By default, even if a user matches an address on their nickname's access
534 list, they are not granted any special permissions in channels. This can
535 be changed with the <a href="4.html#nick.set_secure"><tt>SET SECURE</tt></a>
536 command; disabling the <tt>SECURE</tt> option allows the user to obtain
537 channel privileges without entering a password. (Note that there is also a
538 <tt>SET SECURE</tt> command for ChanServ, which, if set on a channel,
539 causes all nicknames to be treated as if the <tt>SECURE</tt> option was set
540 with respect to that channel, regardless of whether the particular nickname
541 actually has that option set.)
542
543 <p>Nickname access lists have one other effect, which is to prevent users
544 matching an access list entry from being disconnected or having their
545 nickname changed regardless of the nickname's <tt>KILL</tt> setting. This
546 allows a user to use the "quick" or even "immediate" setting to prevent
547 other users from using the nickname, while still having time to identify to
548 NickServ themselves. (When the "immediate" setting for the <tt>KILL</tt>
549 option is used, any user who does not match an entry on the access list
550 will immediately be disconnected or have their nickname changed; this has
551 the effect that if the access list for such a nickname ever becomes empty,
552 no one will be able to use it, and a Services administrator will need to
553 either drop the nickname or change its settings before it can be used
554 again.)
555
556 <p><b>Warning:</b> Access lists can lead to improper access to a nickname
557 if the nickname's owner does not have a fixed IP address. For example, a
558 user whose hostname may be any of <tt>ppp01.city.example.com</tt> through
559 <tt>ppp16.city.example.com</tt> would need to use an access mask of at least
560 <tt>ppp*.city.example.com</tt>, which would allow another user of the same
561 provider to impersonate the nickname owner by setting the username sent by
562 the impersonator's IRC client and/or RFC 1413 ident server. Such users
563 should always set the <tt>SECURE</tt> option on their nicknames to avoid
564 having an impersonator improperly obtain channel or other privileges.
565
566 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
567
568 <a name=1-6></a>
569 <h4>3-1-6. Miscellaneous functions</h4>
570
571 <p>One other additional function is available via a separate NickServ
572 module:
573
574 <p><ul>
575 <li><b>Autojoin lists</b> (module <tt>nickserv/autojoin</tt>), which
576 cause Services to automatically make a user join certain channels
577 when they identify for their nickname; this can be useful for users
578 who connect from shared computers or public terminals, for example,
579 and cannot customize the IRC client to automatically join channels
580 upon connecting. The list of channels to automatically join can be
581 viewed and updated with the
582 <a href="4.html#nick.ajoin"><tt>AJOIN</tt></a> command.
583 <p>This functionality requires the use of an IRC server which allows
584 users to be forcibly joined to certain channels (often known as
585 <tt>SVSJOIN</tt>).
586 </ul>
587
588 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
589
590 <a name=1-7></a>
591 <h4>3-1-7. Command aliases</h4>
592
593 <p>NickServ includes a simple "command alias" feature, which can be used
594 (for example) to create abbreviations for commands, such as "<tt>ID</tt>"
595 instead of "<tt>IDENTIFY</tt>", or to ease transition from another
596 Services-like program. Aliases are created via the
597 <a href="a.html#nickserv/main.NSAlias"><tt>NSAlias</tt></a> configuration
598 directive in <tt>modules.conf</tt>; the parameter format is
599 "<tt><i>alias</i>=<i>command</i></tt>", where <tt><i>alias</i></tt> is the
600 new name (alias) to create, and <tt><i>command</i></tt> is the
601 already-existing command to be executed when a user uses the alias. Only
602 one alias can be given in a single <tt>NSAlias</tt> directive, but multiple
603 directives can be given to create more aliases.
604
605 <p>Note that recursive aliases are <i>not</i> permitted. In other words,
606 if you have an alias "<tt>ID</tt>" for the <tt>IDENTIFY</tt> command, you
607 cannot then create another alias <tt>I=ID</tt>; attempting to use this
608 alias will give the error "<tt>Unknown command ID</tt>".
609
610 <p>Aliases are available for ChanServ and MemoServ as well, via the
611 <a href="a.html#chanserv/main.CSAlias"><tt>CSAlias</tt></a> and
612 <a href="a.html#memoserv/main.MSAlias"><tt>MSAlias</tt></a> directives in
613 <tt>modules.conf</tt>.
614
615 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
616
617 <!------------------------------------------------------------------------>
618 <p><hr>
619
620 <a name=2></a>
621 <h3>3-2. Channel management (ChanServ)</h3>
622
623 <a name=2-1></a>
624 <h4>3-2-1. Core ChanServ features</h4>
625
626 <p>Just as with nicknames, channels can also be registered with Services.
627 Once you register a channel, Services will automatically give you channel
628 operator privileges ("ops") when you enter the channel, even if you are not
629 the first user in the channel, and conversely it will not allow other users
630 to gain ops simply by being the first user in the channel; you can also
631 designate other users to be automatically granted ops or voice privileges
632 (mode <tt>+v</tt>). In addition, Services will save the topic on the
633 channel even when it is not in use, and can enforce various modes on the
634 channel, such as <tt>+m</tt> (moderated) or <tt>+s</tt> (secret).
635
636 <p>The "<b>ChanServ</b>" pseudoclient allows access to the various channel
637 management functions, much like NickServ does for nicknames, and as with
638 NickServ, ChanServ receives commands via <tt>/msg</tt>. (Also as with
639 NickServ, ChanServ's nickname can be changed via a configuration setting:
640 <a href="a.html#chanserv/main.ChanServName"><tt>ChanServName</tt></a> in
641 <tt>modules.conf</tt>.)
642
643 <p>ChanServ uses the same basic commands as NickServ for managing channels:
644 <a href="4.html#chan.register"><tt>REGISTER</tt></a> to register a channel
645 as one's own, <a href="4.html#chan.identify"><tt>IDENTIFY</tt></a> to
646 obtain privileges on a channel via password,
647 <a href="4.html#chan.set"><tt>SET</tt></a> and
648 <a href="4.html#chan.unset"><tt>UNSET</tt></a> to set various channel
649 options, <a href="4.html#chan.drop"><tt>DROP</tt></a> to cancel a channel's
650 registration, and <a href="4.html#chan.list"><tt>LIST</tt></a> and
651 <a href="4.html#chan.info"><tt>INFO</tt></a> to display information about
652 registered channels. Note that when a channel is registered, a
653 "description" parameter is required in addition to a password; this
654 description is displayed in the output from the <tt>LIST</tt> and
655 <tt>INFO</tt> commands.
656
657 <p>By default, a single user (<i>i.e.,</i> nickname group) is not permitted
658 to register more than 20 channels; any attempt to register channels above
659 this limit will result in an error. This limit can be changed via the
660 <a href="a.html#chanserv/main.CSMaxReg"><tt>CSMaxReg</tt></a> option in
661 <tt>modules.conf</tt>. Also by default, channels will expire in 14 days
662 (changeable via the <a href="a.html#chanserv/main.CSExpire"><tt>CSExpire</tt></a>
663 option in <tt>modules.conf</tt>) if they are not "used" for that period of
664 time; see <a href="#2-3">section 3-2-3</a> for detailed information on how
665 channel expiration is performed.
666
667 <p>When a user registers a channel, that user is recorded in Services'
668 databases as the channel's <i>founder</i>. The founder of a channel will
669 automatically receive ops in that channel when they enter, and is the only
670 one permitted to use certain ChanServ commands, in particular <tt>SET</tt>
671 and <tt>DROP</tt>. Channel founder privileges may be obtained either by
672 identifying for the nickname used to register a channel (or any nickname
673 linked to it) as described in <a href="#1-1">section 3-1-1</a>, or by using
674 the ChanServ <tt>IDENTIFY</tt> command with the password given at
675 registration to identify as the channel founder. The founder of a channel
676 can be changed without dropping and re-registering the channel by using the
677 <a href="4.html#chan.set_founder"><tt>SET FOUNDER</tt></a> command.
678
679 <p>If the founder's nickname is dropped, or if it expires and no other
680 unexpired nicknames are linked to it, then the channel will be
681 automatically dropped. However, if a <i>successor</i> is set with the
682 <a href="4.html#chan.set_successor"><tt>SET SUCCESSOR</tt></a> command,
683 then the nickname designated as the successor will become the new founder
684 of the channel, and the channel will not be dropped (unless the successor
685 nickname has already registered channels up to the registration limit, in
686 which case the channel will be dropped as usual). A channel's successor
687 can be cleared with the <tt>UNSET SUCCESSOR</tt> command.
688
689 <p>As with NickServ, the channel's password can be changed after
690 registration with the <a href="4.html#chan.set_password"><tt>SET
691 PASSWORD</tt></a> command. When used with ChanServ, however, this command
692 has an additional function: it clears founder privileges from any other
693 user which had previously obtained such privileges with the
694 <tt>IDENTIFY</tt> command, and each such user must re-identify with the
695 new password in order to regain founder privileges.
696
697 <p>The <a href="4.html#chan.set_mlock"><tt>SET MLOCK</tt></a> command
698 allows a channel's founder to have Services always set or clear certain
699 modes on the channel. This command is used similarly to the IRC
700 <tt>/mode</tt> command, with a list of mode characters interspersed with
701 <tt>+</tt> and <tt>-</tt>, possibly followed by mode parameters (such as a
702 channel key or user limit for the <tt>+k</tt> or <tt>+l</tt> modes). The
703 important difference is that modes specified here are always forced by
704 Services to be as specified; for example, if a mode lock of <tt>+s</tt> is
705 set on a channel, Services will always set <tt>+s</tt> on that channel when
706 it is first joined by a user, and will not allow anyone to set <tt>-s</tt>
707 on the channel (conversely, a mode lock of <tt>-s</tt> would prevent users
708 from setting <tt>+s</tt> on the channel). Any modes not specified in the
709 mode lock are not forced either on or off, so in the previous example of a
710 mode lock of <tt>+s</tt>, the <tt>+i</tt> mode could be set or unset freely
711 by channel operators. The default mode lock for a new channel is
712 <tt>+nt</tt>; this can be changed with the
713 <a href="a.html#chanserv/main.CSDefModeLock"><tt>CSDefModeLock</tt></a>
714 configuration directive in <tt>modules.conf</tt>.
715
716 <p>Note that setting certain modes in a channel's mode lock will cause
717 Services to automatically kickban users joining a channel if the locked
718 modes would not ordinarily permit that user to join the channel. This is
719 to compensate for the fact that the IRC server does not know about the mode
720 lock, so it cannot reject the inappropriate <tt>JOIN</tt> command from the
721 user. While none of the standard IRC channel modes fall into this
722 category, modes such as "IRC operators only" (<tt>+O</tt> in many
723 protocols) and "registered nicknames only" (<tt>+R</tt> in many protocols)
724 will trigger this behavior. Of these, the latter (<tt>+R</tt>) deserves
725 special mention: due to the way IRC works, netsplits and subsequent
726 netjoins can result in some users getting kicked from <tt>+R</tt> channels
727 they would normally be allowed into. If this causes problems, the check
728 can be disabled with the
729 <a href="a.html#chanserv/main.CSSkipModeRCheck"><tt>CSSkipModeRCheck</tt></a>
730 option in <tt>modules.conf</tt> (with the result that malicious users may
731 be able to take advantage of netsplits to enter <tt>+R</tt> channels with
732 unregistered nicknames).
733
734 <p>Other options available for the <tt>SET</tt> command include
735 <a href="4.html#chan.set_desc"><tt>DESC</tt></a>, to change the channel's
736 description; <a href="4.html#chan.set_url"><tt>URL</tt></a> and
737 <a href="4.html#chan.set_email"><tt>EMAIL</tt></a>, to set a URL or E-mail
738 address for the channel (both of which can be cleared with <tt>UNSET</tt>);
739 <a href="4.html#chan.set_entrymsg"><tt>ENTRYMSG</tt></a>, to set a message
740 to be sent from ChanServ to each user that enters the channel (this can
741 also be cleared with <tt>UNSET</tt>);
742 <a href="4.html#chan.set_keeptopic"><tt>KEEPTOPIC</tt></a>, to set whether
743 the channel's topic is saved when no one is in the channel;
744 <a href="4.html#chan.set_private"><tt>PRIVATE</tt></a>, to set whether the
745 channel should be shown in the results for a <tt>LIST</tt> command; and
746 <a href="4.html#chan.set_secure"><tt>SECURE</tt></a>, to enforce nickname
747 password security for the channel even for nicknames that don't have the
748 <tt>SECURE</tt> option set (as described in <a href="#1-5">section
749 3-1-5</a>).
750
751 <p>To assist a channel founder in recovering control from a malicious user
752 or out-of-control script, the <a href="4.html#chan.clear"><tt>CLEAR</tt></a>
753 command may be used to remove certain modes from the channel, or even to
754 remove all users from the channel at once (a "mass-kick").
755
756 <p>Additionally, a channel founder may define an <i>autokick list</i>,
757 also known as an "AKICK list" after the command used to maintain the list,
758 <a href="4.html#chan.akick"><tt>AKICK</tt></a>. This is a list of users
759 who should not be allowed to join the channel, and is similar to an
760 ordinary channel ban list (set with <tt>/mode <i>channel</i> +b ...</tt>),
761 except that Services will remember the list even when the channel is not
762 in use, and automatically kick and set a ban on the user as necessary.
763 Aside from the usual <tt>ADD</tt>, <tt>DEL</tt>, and <tt>LIST</tt>
764 subcommands, the following subcommands are also available:</p>
765 <ul>
766 <li><b><tt>VIEW</tt>:</b> Displays the autokick list, much as the
767 <tt>LIST</tt> subcommand does but with more details (including the
768 last time a user matching the entry tried to join the channel,
769 which can be helpful in finding out-of-date entries).
770 <p><li><b><tt>COUNT</tt>:</b> Returns the number of entries on the autokick
771 list.
772 <p><li><b><tt>ENFORCE</tt>:</b> Causes Services to check all users in the
773 channel against the autokick list and kick and ban any users which
774 match any entries in the autokick list. This can be used after
775 adding a new entry in place of kicking the user manually.
776 </ul>
777
778 <p>As with NickServ, several commands are reserved for Services
779 administrators. These commands are:
780 <ul>
781 <li><a href="4.html#chan.set_noexpire"><tt>SET NOEXPIRE</tt></a>
782 <li><a href="4.html#chan.getpass"><tt>GETPASS</tt></a>
783 <li><a href="4.html#chan.forbid"><tt>FORBID</tt></a>
784 <li><a href="4.html#chan.suspend"><tt>SUSPEND</tt></a>
785 <li><a href="4.html#chan.unsuspend"><tt>UNSUSPEND</tt></a>
786 </ul>
787 and operate on channels the same way as do their NickServ equivalents on
788 nicknames; see the <a href="#1-1.servadmin">relevant part of section
789 3-1-1</a>. The notes in that section on the <tt>SET</tt> command apply
790 as well, in the sense that Services administrators need not identify for
791 a channel in order to change its settings. Additionally, Services
792 administrators are allowed to enter forbidden and suspended channels.
793
794 <p>It is also possible to prevent ordinary users from registering channels.
795 The <a href="a.html#chanserv/main.CSEnableRegister"><tt>CSEnableRegister</tt></a>
796 configuration option (in <tt>modules.conf</tt>) controls whether the
797 <tt>REGISTER</tt> command is available; if you remove this directive, then
798 ChanServ will not allow new channels to be registered, except by Services
799 administrators (see <a href="#4-1">section 3-4-1</a>). Channels which have
800 already been registered can be used with Services as usual.
801
802 <a name="2-1.channel-ts"></a>
803 <p>Most modern IRC servers keep track of the time a channel was created,
804 and use that time to keep track of which channel is the "original" channel
805 during netsplits. For example, if server A splits from the network and
806 no users on server A are in channel <tt>#B</tt>, then channel <tt>#B</tt>
807 will disappear from server A; if a user on server A then enters channel
808 <tt>#B</tt> while the server is still split, he will gain channel operator
809 privileges, which he would (in the absence of these timestamps) keep even
810 after the server rejoined the network. Services can take advantage of this
811 feature to set the timestamp of registered channels to the time of channel
812 registration, ensuring that the channel's proper modes will always be
813 retained through netsplits. This functionality is enabled with the
814 <a href="a.html#protocol/(insert_protocol_name_here).CSSetChannelTime"><tt>CSSetChannelTime</tt></a>
815 configuration option in <tt>modules.conf</tt> (note that the option is
816 located in the protocol module section, rather than the ChanServ module
817 section). However, the use of this option has the unfortunate side effect
818 of generating spurious mode changes and warning messages on many IRC
819 servers; these can be safely ignored, but if they prove to be a bother, you
820 may want to consider disabling the option. (See <a href="faq.html#E11">FAQ
821 E.11</a> for details.)
822
823 <p>Finally, note that the channel "<tt>#</tt>" (a single "<tt>#</tt>"
824 character with no name following) is treated specially by Services. While
825 this channel is legal according to the IRC protocol (RFC 1459) and
826 supported by most, if not all, IRC servers, it requires special treatment
827 for use with a number of Services functions, and in fact bugs in previous
828 versions of Services as well as other Services-like programs have allowed
829 users to crash these programs using the channel "<tt>#</tt>". Thus, to
830 avoid the potential for such problems, Services explicitly refuses to allow
831 this channel to be registered (or forbidden), which in turn prevents any
832 other Services functions from being used with it.
833
834 <p>As a result of this (lack of) handling, users will be able to use the
835 channel "<tt>#</tt>" freely. If this bothers you, the
836 <a href="a.html#chanserv/main.CSForbidShortChannel"><tt>CSForbidShortChannel</tt></a>
837 option in <tt>modules.conf</tt> can be enabled, which causes Services to
838 treat this channel as a forbidden channel and not allow any clients to use
839 it. (Unlike normal forbidden channels, even Services administrators will
840 not be permitted to use the channel when this option is enabled.)
841
842 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
843
844 <a name=2-2></a>
845 <h4>3-2-2. Channel access lists</h4>
846
847 <p>The remainder of the ChanServ commands and options revolve around a
848 concept known as the <i>channel access list</i>. This is a list of
849 nicknames and associated <i>access levels</i> which defines who should be
850 allowed what privileges on a particular channel. Depending on the access
851 level assigned to a nickname, that nickname's user may be automatically
852 granted ops on entering the channel, or may be allowed to use privileged
853 commands such as <tt>AKICK</tt>. Alternatively, a low access level may
854 prevent a user from obtaining ops on the channel or even entering the
855 channel at all.
856
857 <p>Access levels are integral numbers between -999 and 999 inclusive, with
858 higher values meaning greater privilege; a user whose nickname is not on
859 the access list, or who has not identified for their nickname (except as
860 described for nickname access lists in <a href="#1-5">section 3-1-5</a>),
861 has an access level of 0 (zero). A user with a given access level has all
862 privileges listed in Table 3-1 with a lesser or equal minimum access level.
863 (The "name" column in the table refers to privilege names for the
864 <tt>LEVELS</tt> command, discussed <a href="#2-2.levels">later</a>.)
865
866 <div align=center>
867 <b>Table 3-1.</b> Channel privileges and default minimum access levels<br><br>
868 <table border=1>
869 <tr><th>Name<th>Level<th>Privilege
870 <tr><th colspan=3>Automatic-mode privileges
871 <tr><td><tt>AUTOVOICE</tt>
872 <td>30
873 <td>Automatic mode <tt>+v</tt> (voice) on entering channel
874 <tr><td><tt>AUTOHALFOP</tt>
875 <td>40
876 <td>Automatic mode <tt>+h</tt> (halfop) on entering channel (*)
877 <tr><td><tt>AUTOOP</tt>
878 <td>50
879 <td>Automatic mode <tt>+o</tt> (channel operator) on entering channel
880 <tr><td><tt>AUTOPROTECT</tt>
881 <td>100
882 <td>Automatic mode <tt>+a</tt> (protected) on entering channel (*)
883 <tr><th colspan=3>Command privileges
884 <tr><td><tt>ACC-LIST</tt>
885 <td>0
886 <td>Allowed to use the <tt>LIST</tt> subcommand for the <tt>ACCESS</tt>
887 command
888 <tr><td><tt>VOICE</tt>
889 <td>30
890 <td>Allowed to use the <tt>VOICE</tt> and <tt>DEVOICE</tt> commands
891 <tr><td><tt>HALFOP</tt>
892 <td>40
893 <td>Allowed to use the <tt>HALFOP</tt> and <tt>DEHALFOP</tt> commands
894 <tr><td><tt>ACC-CHANGE</tt>
895 <td>40
896 <td>Allowed to use the <tt>ACCESS</tt> command
897 <tr><td><tt>OPDEOP</tt>
898 <td>50
899 <td>Allowed to use the <tt>OP</tt> and <tt>DEOP</tt> commands
900 <tr><td><tt>INVITE</tt>
901 <td>50
902 <td>Allowed to use the <tt>INVITE</tt> command
903 <tr><td><tt>UNBAN</tt>
904 <td>50
905 <td>Allowed to use the <tt>UNBAN</tt> command
906 <tr><td><tt>KICK</tt>
907 <td>50
908 <td>Allowed to use the <tt>KICK</tt> command
909 <tr><td><tt>TOPIC</tt>
910 <td>50
911 <td>Allowed to use the <tt>TOPIC</tt> command
912 <tr><td><tt>PROTECT</tt>
913 <td>100
914 <td>Allowed to use the <tt>PROTECT</tt> command
915 <tr><td><tt>AKICK</tt>
916 <td>100
917 <td>Allowed to use the <tt>AKICK</tt> command
918 <tr><td><tt>STATUS</tt>
919 <td>100
920 <td>Allowed to use the <tt>STATUS</tt> command
921 <tr><td><tt>SET</tt>
922 <td>(**)
923 <td>Allowed to use the <tt>SET</tt> and <tt>UNSET</tt> commands
924 <tr><td><tt>CLEAR</tt>
925 <td>(**)
926 <td>Allowed to use the <tt>CLEAR</tt> command
927 <tr><th colspan=3>Other privileges
928 <tr><td><tt>MEMO</tt>
929 <td>100
930 <td>Receives copies of channel memos (see <a href="#3-2">section 3-3-2</a>)
931 </table>
932 <br>(*) Only on supporting IRC servers
933 <br>(**) Founder only
934 </div>
935
936 <p><b>Automatic modes</b>
937
938 <p>The most common use of access lists is to make Services automatically
939 give certain users channel operator or some other status when they enter
940 the channel. For example, by adding a user to the access list at level 50
941 (or above), that user will always gain channel operator privileges when
942 they enter the channel, even if they are not the first user in the channel.
943 Adding a user at level 30 (auto-voice) could be useful on moderated (mode
944 <tt>+m</tt>) channels to allow a user to speak freely on the channel
945 without giving them ops. Note that a user at level 50 or above does not
946 get mode <tt>+v</tt>, because channel operator privilege implies voice
947 privilege as well.
948
949 <p>The remaining privileges, auto-halfop (level 40) and auto-protect (level
950 100), apply only to IRC servers that have those modes (<tt>+h</tt> and
951 <tt>+a</tt> respectively), and cause users at or above those levels to be
952 given the respective modes automatically on joining. As with <tt>+o</tt>
953 and <tt>+v</tt>, a user at level 40 (<tt>+h</tt>) will not get <tt>+v</tt>,
954 and a user at level 50 (<tt>+o</tt>) will not get <tt>+h</tt>. Channel
955 protection (<tt>+a</tt>), however, is a separate status, and is given in
956 addition to <tt>+o</tt> rather than instead of it.
957
958 <p>Conversely, a user with a negative access level (-1 or less) will not be
959 allowed channel operator or halfop privileges; even if another channel
960 operator sets mode <tt>+o</tt> on such a user, Services will immediately
961 remove it. Furthermore, users with level -100 or less will not be
962 permitted to join the channel at all, and Services will kick and ban such
963 users if they try to join. Note that this behavior is handled separately
964 from the above privileges, and cannot be modified except with the <tt>SET
965 SECUREOPS</tt> and <tt>SET RESTRICTED</tt> commands, discussed below.
966
967 <p><b>Privileged commands</b>
968
969 <p>A number of ChanServ commands are available only to users with certain
970 privileges; these are listed below.
971
972 <p>The <a href="4.html#chan.voice"><tt>VOICE</tt></a>,
973 <a href="4.html#chan.halfop"><tt>HALFOP</tt></a>,
974 <a href="4.html#chan.op"><tt>OP</tt></a>, and
975 <a href="4.html#chan.protect"><tt>PROTECT</tt></a> commands, as well as
976 their negative counterparts
977 <a href="4.html#chan.devoice"><tt>DEVOICE</tt></a>,
978 <a href="4.html#chan.dehalfop"><tt>DEHALFOP</tt></a>,
979 <a href="4.html#chan.deop"><tt>DEOP</tt></a>, and
980 <a href="4.html#chan.deprotect"><tt>DEPROTECT</tt></a>, are the manual
981 equivalents of the automatic-mode privilege levels, and each can be used
982 only by users who would normally get the given automatic mode (or a better
983 one). For example, a user at level 50 (auto-op) can use the
984 <tt>VOICE</tt>, <tt>HALFOP</tt>, and <tt>OP</tt> commands, but not the
985 <tt>PROTECT</tt> command. As with automatic modes,
986 <tt>HALFOP</tt> / <tt>DEHALFOP</tt> and <tt>PROTECT</tt> /
987 <tt>DEPROTECT</tt> are only available on IRC servers supporting those
988 modes. Also, a channel option is available
989 (<a href="4.html#chan.set_opnotice"><tt>SET OPNOTICE</tt></a>) which causes
990 Services to send a message to the channel every time one of these commands
991 is used.
992
993 <p>The <a href="4.html#chan.access"><tt>ACCESS</tt></a> command is used to
994 modify or view the channel access list, and is discussed
995 <a href="#2-2.add">below</a>. Note that this command has two separate
996 privileges associated with it: <tt>ACC-LIST</tt>, for displaying the access
997 list (think of this as "read-only" privilege for the list), and
998 <tt>ACC-CHANGE</tt>, for modifying it ("read-write").
999
1000 <p>The <a href="4.html#chan.invite"><tt>INVITE</tt></a> and
1001 <a href="4.html#chan.unban"><tt>UNBAN</tt></a> commands can be used by
1002 users with sufficient privilege to circumvent restrictions on entering a
1003 channel. <tt>INVITE</tt> is used to cause Services to "invite" you to the
1004 channel, as if a channel operator had used the <tt>/invite</tt> IRC
1005 command, and is particularly useful when mode <tt>+i</tt> is locked on
1006 (with <tt>SET MLOCK</tt>). <tt>UNBAN</tt> causes Services to remove any
1007 bans on the channel which prevent you from entering.
1008
1009 <p>The <a href="4.html#chan.kick"><tt>KICK</tt></a> and
1010 <a href="4.html#chan.topic"><tt>TOPIC</tt></a> commands do the same thing
1011 as their IRC equivalents, <tt>/kick</tt> and <tt>/topic</tt>. The latter
1012 command, <tt>TOPIC</tt>, is particularly useful in combination with the
1013 <tt>TOPICLOCK</tt> channel option (set with
1014 <a href="4.html#chan.set_topiclock"><tt>SET TOPICLOCK</tt></a>), which
1015 prevents users from changing the channel topic except via the
1016 <tt>TOPIC</tt> command. Note, however, that the <tt>KICK</tt> command will
1017 not allow a user with Services operator or greater privileges (see
1018 <a href="#4-1">section 3-4-1</a>) to be kicked.
1019
1020 <p>The <a href="4.html#chan.status"><tt>STATUS</tt></a> command allows
1021 a user to check the access level of another user on the channel.
1022
1023 <p><b>Access-list-related channel options</b>
1024
1025 <p>Aside from the <tt>OPNOTICE</tt> and <tt>TOPICLOCK</tt> options
1026 mentioned above, several other options relating to channel access lists are
1027 available.
1028
1029 <p>Services does not normally take any particular action for automatic
1030 modes after a user has joined the channel; thus, for example, an auto-op
1031 user may be deopped by another channel operator (or they may deop
1032 themselves) and Services will do nothing. By setting the "enforce" option
1033 with <a href="4.html#chan.set_enforce"><tt>SET ENFORCE</tt></a>, Services
1034 can be made to watch for such improper mode changes and reverse them if
1035 they occur.
1036
1037 <p>At the other end of the spectrum, the leave-ops option
1038 (<a href="4.html#chan.set_leaveops"><tt>SET LEAVEOPS</tt></a>) tells
1039 Services to not deop the first user that joins a channel (such a user is
1040 automatically given ops by the IRC server). This can be useful if a
1041 channel is registered simply to save the channel topic and modes or
1042 establish an autokick list, and control of channel operator and voice
1043 privileges is not needed&mdash;but see <a href="#2-3">section 3-2-3</a>
1044 regarding problems that this sort of usage can raise with respect to
1045 channel expiration.
1046
1047 <p>As mentioned earlier, users not on the access list are assigned an
1048 access level of 0. Ordinarily, this means only that the users do not
1049 have any special privileges and are essentially ignored by Services;
1050 however, two channel options allow this behavior to be changed.
1051 <a href="4.html#chan.set_secureops"><tt>SET SECUREOPS</tt></a> prevents
1052 users not on the access list from being opped by other users, as with
1053 users with negative access levels;
1054 <a href="4.html#chan.set_restricted"><tt>SET RESTRICTED</tt></a> prevents
1055 such users from joining the channel at all, and will kick and ban them if
1056 they try.
1057
1058 <a name="2-2.add"></a>
1059 <p><b>Modifying the access list</b>
1060
1061 <p>Services provides two methods for modifying a channel's access list:
1062 the <a href="4.html#chan.access"><tt>ACCESS</tt></a> command, provided by
1063 the <tt>chanserv/access-levels</tt> module, and the
1064 <a href="4.html#chan.sop"><tt>SOP</tt></a> /
1065 <a href="4.html#chan.aop"><tt>AOP</tt></a> /
1066 <a href="4.html#chan.hop"><tt>HOP</tt></a> /
1067 <a href="4.html#chan.vop"><tt>VOP</tt></a> /
1068 <a href="4.html#chan.nop"><tt>NOP</tt></a> command set (often referred to
1069 collectively as <tt>XOP</tt>), provided by the <tt>chanserv/access-xop</tt>
1070 module. (Thus, at least one of these two modules must be loaded for access
1071 lists to be usable!) The <tt>ACCESS</tt> command allows the access list to
1072 be viewed or modified using access level values directly, while the
1073 <tt>XOP</tt> commands provide a simpler interface with five levels of
1074 access.
1075
1076 <p>Both the <tt>ACCESS</tt> command and the <tt>XOP</tt> command set share
1077 the same subcommands: <b><tt>ADD</tt></b> to add a user (nickname) to the
1078 access list, <b><tt>DEL</tt></b> to remove a user from the list,
1079 <b><tt>LIST</tt></b> to display all or part of the list, and
1080 <b><tt>COUNT</tt></b> to display the number of entries in the list. When a
1081 nickname is added to the access list, all nicknames in the same group (see
1082 <a href="#1-3">section 3-1-3</a> on nickname linking) receive the same
1083 privileges; the nickname displayed when using the <tt>LIST</tt> command is
1084 the one marked as the "main nickname" for the group (set using the NickServ
1085 <tt>SET MAINNICK</tt> command).
1086
1087 <p>Both of these methods operate internally on the same list of nicknames
1088 and access levels, and in fact both can be used simultaneously (with
1089 certain exceptions discussed at <a href="#2-2.levels-xop">the end of this
1090 section</a>). The
1091 difference in the two methods is how access list entries are managed from
1092 the user's standpoint.
1093
1094 <p>The <tt>ACCESS</tt> command provides direct access to the list of
1095 nicknames and access levels that comprise the channel access list. For
1096 example, a command like "<tt>ACCESS #somechannel ADD SomeNick 50</tt>"
1097 could be used to add the nickname "SomeNick" to the access list of channel
1098 "#somechannel" at level 50 (auto-op). The <tt>ADD</tt> subcommand can also
1099 be used to change the level of a user already on the list without having to
1100 remove them from the list first. When adding a new user to the access list
1101 or changing the access level of a user already on the list, the level given
1102 to the <tt>ADD</tt> command must be strictly less than the access level of
1103 the user giving the command; when removing a user or changing a user's
1104 access level, the current access level of the user being removed or changed
1105 must also be less than that of the user giving the command. The founder of
1106 a channel is treated as having an access level higher than any other user
1107 on that channel.
1108
1109 <p>The <tt>ACCESS</tt> command also includes an additional subcommand,
1110 <b><tt>LISTLEVEL</tt></b>, which filters the access list by level rather
1111 than nickname.
1112
1113 <p>The <tt>XOP</tt> command set, on the other hand, treats the access list
1114 as five (four, on IRC servers not supporting halfops) separate lists, each
1115 managed by its own command:
1116 <ul>
1117 <li><tt>SOP</tt> (level 100), for the "super-op" list (auto-op,
1118 auto-protect on supporting servers, and access to the
1119 <tt>AKICK</tt> command);
1120 <li><tt>AOP</tt> (level 50), for the auto-op list (auto-op and access to
1121 most privileged channel commands);
1122 <li><tt>HOP</tt> (level 40), for the auto-halfop list (only available on
1123 servers supporting halfops);
1124 <li><tt>VOP</tt> (level 30), for the auto-voice list; and
1125 <li><tt>NOP</tt> (level -1), for the never-op list.
1126 </ul>
1127 This system, which is roughly based on the system employed by
1128 <a href="http://www.dal.net/">DALnet</a>
1129 <font size=-1>[<tt>www.dal.net</tt>]</font> Services and other
1130 Services-like programs, hides the numeric access levels from the user,
1131 providing them instead with a small set of distinct levels for easy
1132 control. Since the name of the command directly indicates the access
1133 level, there is no need for the user to explicitly give an access level
1134 with the <tt>ADD</tt> subcommand. As with the <tt>ACCESS</tt> command,
1135 users can only add users to or remove users from lists at a lower access
1136 level than their own; for example, a user on the <tt>AOP</tt> list can only
1137 modify the <tt>HOP</tt>, <tt>VOP</tt>, and <tt>NOP</tt> lists.
1138
1139 <p>Note that since the <tt>XOP</tt> command set operates internally on a
1140 single access list, attempting to add a user to one <tt>XOP</tt> list when
1141 that user is already on another such list is treated as a change of access
1142 level, as with the <tt>ACCESS ADD</tt> command; the command will fail if
1143 the user being added is already on the same or a higher list than the user
1144 giving the command, and if the command succeeds, the target user will be
1145 removed from the list they were previously on. Also, users added to the
1146 access list with the <tt>ACCESS ADD</tt> command at a level other than the
1147 five access levels given above (100, 50, 40, 30, or -1) will be invisible
1148 to the <tt>XOP</tt> commands.
1149
1150 <a name="2-2.levels"></a>
1151 <p><b>Changing the minimum access levels for privileges</b>
1152
1153 <p>Experienced users may want to change the minimum access levels required
1154 for certain privileges; for example, one could set the <tt>AUTOVOICE</tt>
1155 privilege to have a minimum level of zero, meaning that users not on the
1156 access list will automatically get mode <tt>+v</tt> upon entering the
1157 channel. This can be accomplished through the
1158 <a href="4.html#chan.levels"><tt>LEVELS</tt></a> command, provided by the
1159 <tt>chanserv/access-levels</tt> module (which also provides the
1160 <tt>ACCESS</tt> command).
1161
1162 <p>The <tt>LEVELS</tt> command has four primary subcommands. <tt>SET</tt>
1163 takes a privilege name (from the "name" column in Table 3-2) and access
1164 level, and sets the minimum access level for that privilege to the given
1165 level. <tt>DISABLE</tt> (which may be abbreviated to <tt>DIS</tt>)
1166 disables a privilege; for automatic mode privileges, this means that no
1167 users get the mode regardless of their access level, and for command
1168 privileges, it means that only the founder is permitted to use the command
1169 in question. <tt>RESET</tt> resets all privileges to their default levels,
1170 and <tt>LIST</tt> displays the minimum access level for each privilege on
1171 the channel.
1172
1173 <a name="2-2.levels-xop"></a>
1174 <p>There is one important thing to remember when using the <tt>LEVELS</tt>
1175 command in combination with the <tt>XOP</tt> command set: Since the
1176 <tt>XOP</tt> commands always use the same fixed access levels (100, 50, 40,
1177 30, and -1), changing the automatic mode levels, in particular, can have
1178 unexpected effects! For example, if the auto-op level is raised to 75,
1179 then users on the <tt>AOP</tt> (supposedly "auto-op") list will not get
1180 ops when they enter the channel. In general, it is not a good idea to use
1181 both the <tt>LEVELS</tt> and <tt>XOP</tt> commands on the same channel.
1182
1183 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1184
1185 <a name=2-3></a>
1186 <h4>3-2-3. Channel expiration</h4>
1187
1188 <p>Channel expiration is a somewhat complex issue. The major problem in
1189 determining when to expire a channel is: How do you determine whether the
1190 channel is "in use"?
1191
1192 <p>One simple idea is to measure from the last time any user was in the
1193 channel, but this can be overly protective in some circumstances. For
1194 example, suppose user A has registered channel <tt>#mychannel</tt>, but no
1195 longer uses it. One day before the channel is to expire, user B comes onto
1196 the network, wanting to use <tt>#mychannel</tt> herself but not knowing
1197 that it has already been registered. When user B enters the channel,
1198 ChanServ tells her that it is registered&mdash;and updates the last-used time, forcing her to wait much longer than one day before the
1199 channel is finally released.
1200
1201 <p>Clearly, Services needs some way to determine whether a user should be
1202 considered a user of the registered channel, as opposed to an unrelated
1203 user who just happened to enter the channel. The wide variety of channel
1204 management styles makes this difficult, but since most channels are likely
1205 to take advantage of the auto-op channel privilege (as described in
1206 <a href="#2-2">section 3-2-2</a>), Services uses this privilege as a basis
1207 for determining who to count as a user of the registered channel.
1208
1209 <p>Thus, the rule for channel expirations is: <b>A channel's expiration
1210 timer counts from the last time a user with auto-op provileges was present
1211 in the channel.</b> (This time is the "last used time" shown in the
1212 channel information.) As a corollary, <i>channels will not expire as long
1213 as a user with auto-op privileges is in the channel.</i>
1214
1215 <p>If you only use the <tt>XOP</tt> commands to modify the channel list,
1216 this is easy to understand: anyone on the <tt>AOP</tt> and <tt>SOP</tt>
1217 lists, as well as the channel founder, will cause the channel's last-used
1218 time to be updated. Likewise, with the <tt>ACCESS</tt> command, any user
1219 with access level 50 or above will reset the expiration countdown.
1220 However, if you use the <tt>LEVELS</tt> command to alter the auto-op
1221 privilege level, then this no longer holds; in particular, <b>if you
1222 disable the auto-op channel privilege, then you will not be able to stop
1223 the channel from expiring!</b>
1224
1225 <p>Also, for the purpose of these checks, Services uses each user's
1226 <i>current</i> channel privileges on the channel. Even if the channel
1227 founder remains in the channel, he will not be counted as a channel user
1228 unless he has identified for his nickname (or the nickname and channel
1229 <tt>SECURE</tt> options are disabled).
1230
1231 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1232
1233 <!------------------------------------------------------------------------>
1234 <p><hr>
1235
1236 <a name=3></a>
1237 <h3>3-3. Memo sending (MemoServ)</h3>
1238
1239 <a name=3-1></a>
1240 <h4>3-3-1. MemoServ core features</h4>
1241
1242 <p>"Memos" are short messages which can be sent to users even if they are
1243 not online, and will be stored by Services for the recipient to read later.
1244 Memos are handled by the "<b>MemoServ</b>" pseudoclient, which functions in
1245 the same way as NickServ and ChanServ. (The nickname can be changed via
1246 the <a href="a.html#memoserv/main.MemoServName"><tt>MemoServName</tt></a>
1247 option in <tt>modules.conf</tt>.) To avoid potential problems with
1248 anonymous memo flooding and other issues, as well as to simplify memo
1249 storage, MemoServ requires a user to register and identify for their
1250 nickname before sending or receiving memos or performing other memo-related
1251 operations. If a user has two or more nicknames linked together into a
1252 group, then all of those nicknames share the same set of memos, and memos
1253 to one nickname in the group can be read using another one.
1254
1255 <p>Sending a memo to another user is accomplished via the
1256 <a href="4.html#memo.send"><tt>SEND</tt></a> command. When you send a memo
1257 to a user, it will be stored in Services' database, ready for the recipient
1258 to read the next time they connect. If the recipient happens to be online
1259 (and identified for their nickname) at the time the memo is sent, they will
1260 receive a notice that a memo has been sent to them. If nickname linking
1261 is enabled, the recipient will also receive a notice if they are using any
1262 nickname linked to the nickname that received the memo.
1263
1264 <p>When a user receives a memo, they can use the
1265 <a href="4.html#memo.read"><tt>READ</tt></a> command to view its contents.
1266 This command displays the text of the memo whose number is given with the
1267 command (the string "<tt>LAST</tt>" can be used to mean "the last memo
1268 received", or "<tt>NEW</tt>" to mean "all unread memos"), as well as the
1269 nickname of the user who sent it and the date and time it was sent. It is
1270 also possible to read multiple memos at once, by separating the numbers
1271 with commas (for individual memos) or hyphens (for ranges of memos); for
1272 example, "<tt>READ 2,4-6,9</tt>" causes memos 2, 4, 5, 6, and 9 to be
1273 displayed.
1274
1275 <p>If a user has several new memos, or wants to look for an old memo, it is
1276 usually easier to get a one-line-per-memo list of memos; this is
1277 accomplished with the <a href="4.html#memo.list"><tt>LIST</tt></a> command,
1278 which displays the sender's nickname and time sent for each memo requested.
1279 This command can take either a single memo number, a list or range of
1280 numbers, the string "<tt>NEW</tt>" for all new memos, or nothing at all to
1281 list every saved memo.
1282
1283 <p>Once a memo has been read, it typically is not needed any more, and can
1284 be deleted. In fact, since a single nickname group can only receive a
1285 limited number of memos (20 by default, changeable via the
1286 <a href="a.html#memoserv/main.MSMaxMemos"><tt>MSMaxMemos</tt></a> option in
1287 <tt>modules.conf</tt>), deleting unused memos is important to make room for
1288 new ones. This is done with the <a href="4.html#memo.del"><tt>DEL</tt></a>
1289 command, which takes as a parameter a single memo number or list of numbers,
1290 or the string "<tt>ALL</tt>" to delete every stored memo. Be aware that
1291 deletion is an irreversible operation: once memos are deleted, there is no
1292 way to get them back!
1293
1294 <p>If the <a href="a.html#memoserv/main.MSExpire"><tt>MSExpire</tt></a>
1295 option is set in <tt>modules.conf</tt>, then memos will be automatically
1296 deleted after the period of time given with that option even if they are
1297 not explicitly deleted with the <tt>DEL</tt> command (unread memos will
1298 never be automatically deleted). However, the
1299 <a href="4.html#memo.save"><tt>SAVE</tt></a> command is available to mark
1300 certain memos as non-expiring. Once a memo is so marked, it remains that
1301 way until the <tt>DEL</tt> command is used to delete it, and will never be
1302 automatically deleted.
1303
1304 <p>To avoid old but unread memos from being deleted immediately upon being
1305 read, the
1306 <a href="a.html#memoserv/main.MSExpireDelay"><tt>MSExpireDelay</tt></a>
1307 option can be set in <tt>modules.conf</tt>. If set, this option specifies
1308 how long Services should wait <i>after the memo is first read</i> before
1309 expiring the memo. If memo expiration is not in use, this option is
1310 ignored.
1311
1312 <p>Note that when a memo in the middle of the memo list is deleted or
1313 expires, the numbers of later memos do <i>not</i> change; this is to
1314 prevent successive <tt>DEL</tt> commands from doing the wrong (unintuitive)
1315 thing. For example, imagine a user who has four memos, numbered 1, 2, 3,
1316 and 4. If the user gives the command <tt>DEL 2</tt>, then memo 2 will be
1317 deleted, but memos 3 and 4 will remain as memos 3 and 4; thus, if the user
1318 then enters <tt>DEL 3</tt>, the third memo in the original list will be
1319 deleted. (If the memos were automatically renumbered, <tt>DEL 3</tt> would
1320 instead delete what was originally memo 4&mdash;probably not what the user
1321 wanted to do!) However, this leaves "holes" in the numbering, and if a
1322 user keeps some memos for a long time or receives memos more frequently
1323 than they expire, they can end up with very large memo numbers. To resolve
1324 this problem, the user can use the
1325 <a href="4.html#memo.renumber"><tt>RENUMBER</tt></a> command, which keeps
1326 the user's memos in the same order but reassigns numbers sequentially
1327 starting with 1.
1328
1329 <p>Normally, users will be notified when they connect to the network of any
1330 new memos, and will also be notified when they receive new memos, as
1331 described above. This behavior can be altered using the
1332 <a href="4.html#memo.set_notify"><tt>SET NOTIFY</tt></a> command. Users
1333 can also set a limit on the number of memos they can receive between 0,
1334 which prevents the user from receiving any memos at all, and the default
1335 limit using the <a href="4.html#memo.set_limit"><tt>SET LIMIT</tt></a>
1336 command. (Note, however, that the limit is ignored for memos sent by
1337 Services administrators.)
1338
1339 <p>However, the <tt>SET LIMIT</tt> command is more intended for Services
1340 administrators (see <a href="#4-1">section 3-4-1</a>), who can use it to
1341 allow a nickname to receive an unlimited number of memos ("<tt>SET LIMIT
1342 <i>nickname</i> NONE</tt>") or to prevent a user from changing their own
1343 limit ("<tt>SET LIMIT <i>nickname</i> 0 HARD</tt>" to enforce a limit of 0,
1344 preventing receipt of any memos).
1345
1346 <p>Finally, the <a href="4.html#memo.info"><tt>INFO</tt></a> command can be
1347 used to display a user's number of stored and unread memos, memo limit, and
1348 notification options. Ordinary users can only use this command for their
1349 own nick, while Services administrators can view memo information for any
1350 nick ("<tt>INFO <i>nickname</i></tt>").
1351
1352 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1353
1354 <a name=3-2></a>
1355 <h4>3-3-2. Memos and channels</h4>
1356
1357 <p>While MemoServ is typically used to send messages from one user
1358 (nickname) to another, it can also be used to leave messages for a
1359 channel instead. In this case, the memo is sent to the founder of the
1360 channel and any user with the <tt>MEMO</tt> privilege on the channel (see
1361 <a href="#2-2">section 3-2-2</a>). The channel must be registered in order
1362 to receive memos, and if the
1363 <a href="4.html#chan.set_memo_restricted"><tt>MEMO-RESTRICTED</tt></a>
1364 channel option is set on the channel, only users with the <tt>MEMO</tt>
1365 privilege will be allowed to send memos to the channel.
1366
1367 <p>When sending the memo, simply replacing the target nickname with a
1368 channel name is sufficient to send the memo. Any user of that channel with
1369 the <tt>MEMO</tt> privilege will be notified of the new memo (depending on
1370 the user's <tt>SET NOTIFY</tt> setting), and can read or delete it with the
1371 <tt>READ</tt> or <tt>DEL</tt> commands, in the same way as ordinary memos.
1372 In order to differentiate channel memos from ordinary memos, Services will
1373 include the name of the channel the memo was sent to when notifying users
1374 of or displaying channel memos.
1375
1376 <p>Since a channel memo can have multiple recipients, the memo might not
1377 be deliverable to all of them; for example, one of the recipients might be
1378 on vacation and have disabled memos for their nickname. However, Services
1379 will say "message sent successfully" if the memo was delivered to at least
1380 one user; only if all recipients are unable to receive the memo will
1381 Services display an error message.
1382
1383 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1384
1385 <a name=3-3></a>
1386 <h4>3-3-3. Memo ignore lists</h4>
1387
1388 <p>Users may, on occasion, want to avoid receiving memos from certain other
1389 users, such as in cases of harrassment. The <tt>memoserv/ignore</tt>
1390 module allows users to do exactly that, by maintaining an <i>ignore
1391 list</i> of wildcard masks (which can be either nickname or
1392 <tt><i>user</i>@<i>host</i></tt> masks) from which memos should not be
1393 received. When a memo is sent to the user, Services compares the nickname
1394 and <tt><i>user</i>@<i>host</i></tt> address of the sender to each entry on
1395 the recipient's ignore list; if a match is found, Services will refuse to
1396 send the memo, informing the sender that the recipient is "not allowed to
1397 receive memos" (using the same message sent when the recipient has used the
1398 <tt>SET LIMIT 0</tt> command to prevent receipt of any memos at all; this
1399 way, the sender cannot tell directly whether the user is refusing all memos
1400 or only memos from that particular nickname or address). <tt>IGNORE</tt>
1401 also blocks delivery of channel memos from users on the ignore list.
1402
1403 <p>The <a href="4.html#memo.ignore"><tt>IGNORE</tt></a> command is used to
1404 manage the ignore list. It has three subcommands: <tt>ADD</tt> to add a
1405 mask to the ignore list, <tt>DEL</tt> to delete a mask, and <tt>LIST</tt>
1406 to display all masks on the list.
1407
1408 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1409
1410 <a name=3-4></a>
1411 <h4>3-3-4. Memo forwarding</h4>
1412
1413 <p>Some users may find it easier to have their memos forwarded directly to
1414 their E-mail address rather than connecting to IRC to check them. The
1415 <tt>memoserv/forward</tt> module allows users to select this behavior for
1416 their nicknames, and will convert each memo to the user into an E-mail
1417 message sent to the E-mail address registered with the nickname. (To
1418 prevent spamming, this module requires that nickname E-mail authentication
1419 be active; see <a href="#1-4">section 3-1-4</a> for details.) Note that
1420 this module requires a mail module (<a href="#8">section 3-8</a>) to be
1421 loaded in order to function.
1422
1423 <p>When this module is loaded, users can use the
1424 <a href="4.html#memo.set_forward"><tt>SET FORWARD</tt></a> command to
1425 select whether to have their memos forwarded to their E-mail address. This
1426 option can be set to either "<tt>ON</tt>" (forward memos via E-mail),
1427 "<tt>OFF</tt>" (do not forward), or "<tt>COPY</tt>" (forward memos but also
1428 store a copy in the Services database). When set to <tt>COPY</tt>, the
1429 limit on the number of stored memos per nickname group applies to E-mail as
1430 well: if the limit is reached, all further memos will be refused, even
1431 though they could potentially have been sent via E-mail. In such a case,
1432 the user must connect to IRC and delete unneeded memos before being
1433 allowed to receive more, just as if the <tt>FORWARD</tt> option was set to
1434 <tt>OFF</tt>.
1435
1436 <p>Additionally, a separate <a href="4.html#memo.forward"><tt>FORWARD</tt></a>
1437 command is available which allows users to selectively forward memos to
1438 their E-mail address. This can be useful, for example, to save certain
1439 messages in a more permanent form without having every single memo sent to
1440 one's mailbox.
1441
1442 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1443
1444 <!------------------------------------------------------------------------>
1445 <p><hr>
1446
1447 <a name=4></a>
1448 <h3>3-4. Network/Services control and maintenance (OperServ)</h3>
1449
1450 <a name=4-1></a>
1451 <h4>3-4-1. Services privilege levels</h4>
1452
1453 <p>Before discussing OperServ's functions, it is necessary to understand
1454 the concept of <i>Services privilege levels</i>. These are privilege
1455 levels assigned to IRC operators which are used by both OperServ and other
1456 parts of Services to limit access to certain functions. There are four
1457 different Services privilege levels a user can have:
1458 <ul>
1459 <li>No privilege
1460 <li>Services operator privilege
1461 <li>Services administrator privilege
1462 <li>Services super-user privilege
1463 </ul>
1464 By default, all users have no special privileges.
1465
1466 <p><b>Services operator</b> (also known as "Services oper" or "servoper")
1467 privilege allows IRC operators to change modes on or kick users from any
1468 channel or "mass-kill" users sharing the same hostname (clones, for
1469 example), as well as modify the autokill, session exception, and S-line
1470 lists when the relevant modules are in use, and is intended for IRC
1471 operators who can be trusted not to run wild on the network. The
1472 <a href="4.html#oper.oper"><tt>OPER</tt></a> command is used to change or
1473 view the list of users with Services operator status.
1474
1475 <p><b>Services administrator</b> (also known as "Services admin" or
1476 "servadmin") privilege allows IRC operators control of Services itself;
1477 Services administrators can set various Services options, rehash (re-read)
1478 the configuration files and update settings, and restart or terminate
1479 Services entirely. Services administrator privilege is also needed to
1480 modify the Services operator list or to gain Services super-user privilege
1481 (see below). The <a href="4.html#oper.admin"><tt>ADMIN</tt></a> command is
1482 used to change or view the list of users with Services administrator
1483 status. Note that giving a user Services administrator status will cause
1484 them to be removed from the Services operator list if they are on it; users
1485 on the Services administrator list must first be removed from that list
1486 before they can be added to the Services operator list, thus preventing one
1487 Services administrator from downgrading another's privilege level by making
1488 them a Services operator.
1489
1490 <p><b>Services super-user</b> (also known as "Services root", after the
1491 Unix super-user username <tt>root</tt>) privilege is the highest Services
1492 privilege level available, and is required for modifying the Services
1493 administrator list. It also allows the use of the dangerous
1494 <a href="4.html#oper.raw"><tt>RAW</tt></a> command, which sends text
1495 directly to the IRC network without intervention by Services, if the
1496 <a href="a.html#operserv/main.AllowRaw"><tt>AllowRaw</tt></a> option is set
1497 in <tt>modules.conf</tt>; this can be useful for testing new features of an
1498 IRC server, but improper use can cause Services and other servers on the
1499 network to behave improperly or even crash. Normally, only the nickname
1500 given with the
1501 <a href="a.html#operserv/main.ServicesRoot"><tt>ServicesRoot</tt></a>
1502 configuration directive in <tt>modules.conf</tt> has Services super-user
1503 privilege, but if that user sets a super-user password with the
1504 <a href="4.html#oper.set_supass"><tt>SET SUPASS</tt></a> command, Services
1505 administrators can obtain temporary Services super-user privilege by giving
1506 that password with the <a href="4.html#oper.su"><tt>SU</tt></a> command.
1507
1508 <p>As a special exception to the normal nickname dropping and expiration
1509 rules, the nickname designated as the Services super-user with the
1510 <tt>ServicesRoot</tt> directive will never expire regardless of the setting
1511 of the nickname's <tt>NOEXPIRE</tt> option and cannot be dropped by other
1512 Services administrators with the <tt>DROPNICK</tt> command. This prevents
1513 unauthorized users from capitalizing on the accidental or deliberate
1514 deletion of the nickname by re-registering it themselves.
1515
1516 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1517
1518 <a name=4-2></a>
1519 <h4>3-4-2. Core OperServ features</h4>
1520
1521 <p>This section discusses the core features provided by OperServ (in the
1522 <tt>operserv/main</tt> module). It is split into four subsections by
1523 Services privilege level:
1524 <ul>
1525 <li><a href="#4-2.all">Commands for all IRC operators</a>
1526 <li><a href="#4-2.oper">Commands limited to Services operators</a>
1527 <li><a href="#4-2.admin">Commands limited to Services administrators</a>
1528 <li><a href="#4-2.root">Commands limited to the Services super-user</a>
1529 </ul>
1530 An IRC operator with a certain Services privilege level also has access to
1531 commands for lower privilege levels; for example, a Services administrator
1532 has access to Services operator commands as well, and a user with Services
1533 super-user privilege can use every OperServ command. If a user who is not
1534 an IRC operator sends a command to OperServ, it will be refused regardless
1535 of content, and (if the
1536 <a href="a.html#operserv/main.WallBadOS"><tt>WallBadOS</tt></a> option is
1537 set in <tt>modules.conf</tt>) a message will be broadcast to all online IRC
1538 operators.
1539
1540 <p>Note that all commands sent to OperServ are recorded in the Services log
1541 file (with the exception of passwords given for the <tt>SU</tt> and <tt>SET
1542 SUPASS</tt> commands, discussed below), so be careful of what you type!
1543
1544 <a name="4-2.all"></a>
1545 <p><b>Commands for all IRC operators</b>
1546
1547 <p>IRC operators without any Services privileges are primarily limited to
1548 commands for displaying the current status of Services and the IRC network.
1549 These commands include <a href="4.html#oper.stats"><tt>STATS</tt></a>
1550 command, which displays the time elapsed since Services was started and
1551 current/maximum number of users and IRC operators, and the
1552 <a href="4.html#oper.servermap"><tt>SERVERMAP</tt></a> command, which
1553 displays the IRC network's topology from the viewpoint of Services.
1554 Another command, <a href="4.html#oper.global"><tt>GLOBAL</tt></a>, allows a
1555 notice to be sent to all users on the IRC network.
1556
1557 <p>Additionally, the <a href="4.html#oper.admin"><tt>ADMIN</tt></a> and
1558 <a href="4.html#oper.oper"><tt>OPER</tt></a> commands can be used by any
1559 IRC operator to view the current list of Services administrators and
1560 operators, respectively (the <tt>LIST</tt> subcommand). However, Services
1561 will not permit any changes to either of these lists from a user without
1562 the necessary privileges.
1563
1564 <a name="4-2.oper"></a>
1565 <p><b>Commands limited to Services operators</b>
1566
1567 <p>In addition to the commands usable by all IRC operators, Services
1568 operators have access to commands which can be used to maintain stability
1569 and resolve problems in the IRC network. Five of these
1570 commands&mdash;<a href="4.html#oper.getkey"><tt>GETKEY</tt></a>,
1571 <a href="4.html#oper.mode"><tt>MODE</tt></a>,
1572 <a href="4.html#oper.clearmodes"><tt>CLEARMODES</tt></a>,
1573 <a href="4.html#oper.kick"><tt>KICK</tt></a>, and
1574 <a href="4.html#oper.clearchan"><tt>CLEARCHAN</tt></a>&mdash;allow control of
1575 channel modes as well as providing the ability to remove a user (or all
1576 users) from a channel. The last Services operator-specific command,
1577 <a href="4.html#oper.killclones"><tt>KILLCLONES</tt></a>, allows quick
1578 resolution to "clone" problems, where many clients connect to the IRC
1579 network at once from the same address; this command causes all clients with
1580 the same address as the nickname given to the command to be immediately
1581 disconnected, and will also add a temporary autokill (if
1582 <a href="#4-3">autokill support</a> is enabled) to prevent the clients from
1583 immediately reconnecting.
1584
1585 <a name="4-2.admin"></a>
1586 <p><b>Commands limited to Services administrators</b>
1587
1588 <p>Services administrators have access to commands which control Services
1589 itself. One of these is the <a href="4.html#oper.set"><tt>SET</tt></a>
1590 command, which allows various Services options to be set:
1591 <a href="4.html#oper.set_readonly"><tt>READONLY</tt></a>, which controls
1592 whether Services allows changes to be made to its database, and
1593 <a href="4.html#oper.set_debug"><tt>DEBUG</tt></a>, which controls whether and
1594 how much debugging information is written to the log file. (The third
1595 <tt>SET</tt> option, <a href="4.html#oper.set_supass"><tt>SUPASS</tt></a>,
1596 is restricted to users with Services super-user privileges.) Services
1597 administrators can also force Services to update the on-disk copies of its
1598 databases with the <a href="4.html#oper.update"><tt>UPDATE</tt></a>
1599 command, make Services re-read its configuration file with the
1600 <a href="4.html#oper.rehash"><tt>REHASH</tt></a> command, and shut down or
1601 restart Services with the <a href="4.html#oper.shutdown"><tt>SHUTDOWN</tt></a>,
1602 <a href="4.html#oper.quit"><tt>QUIT</tt></a>, and
1603 <a href="4.html#oper.restart"><tt>RESTART</tt></a> commands.
1604
1605 <p>With respect to the IRC network, Services administrators can use the
1606 <a href="4.html#oper.jupe"><tt>JUPE</tt></a> command to "jupiter" a
1607 server&mdash;that is, to make Services create a fake server with a particular
1608 name to prevent a real server of the same name from connecting. This can
1609 be useful if a server on your network is broken (or hacked into) and causes
1610 problems for other servers on the network.
1611
1612 <p>Finally, if the Services super-user has set a super-user password with
1613 the <tt>SET SUPASS</tt> command, Services administrators can use that
1614 password with the <a href="4.html#oper.su"><tt>SU</tt></a> command to gain
1615 super-user privileges.
1616
1617 <a name="4-2.root"></a>
1618 <p><b>Commands limited to the Services super-user</b>
1619
1620 <p>The Services super-user privilege level is similar to the Services
1621 administrator level; it primarily exists to allow modification of the
1622 Services administrator list (with the
1623 <a href="4.html#oper.admin"><tt>ADMIN</tt></a> command) and setting of the
1624 super-user password (with the <a href="4.html#oper.set_supass"><tt>SET
1625 SUPASS</tt></a> command). However, one other command is limited to the
1626 Services super-user (or Services administrators with super-user privilege):
1627 the <a href="4.html#oper.raw"><tt>RAW</tt></a> command, which allows any
1628 arbitrary data to be sent directly to the server to which Services is
1629 connected. This can be used to achieve certain kinds of "special effects"
1630 or to aid in development or debugging of an IRC server or Services module.
1631 As mentioned earlier, however, this command is <i>very dangerous,</i> and
1632 improper use can easily cause Services or your network's IRC servers (or
1633 both) to crash or corrupt data. For this reason, the <tt>RAW</tt> command
1634 is unavailable even to the Services super-user unless the
1635 <a href="a.html#operserv/main.AllowRaw"><tt>AllowRaw</tt></a> option is set
1636 in <tt>modules.conf</tt> (it is disabled by default).
1637
1638 <p>Additionally, certain debugging commands are available to the Services
1639 super-user if enabled in the <tt>Makefile</tt>. These commands are not
1640 documented; see the source code (<tt>modules/operserv/main.c</tt>) for
1641 information.
1642
1643 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1644
1645 <a name=4-3></a>
1646 <h4>3-4-3. Autokills and S-lines</h4>
1647
1648 <p>Just about any network will have its share of troublemakers or other
1649 "unwanted" users. IRC servers have always provided a
1650 method&mdash;"K-lines", so named because the lines in the configuration
1651 file defining them begin with the letter "<tt>K</tt>"&mdash;of preventing
1652 these users from connecting to the network. The problem with these,
1653 however, is that they only affect the server on which they are defined; to
1654 prevent a user from connecting to the network at all, every server has to
1655 add the appropriate K-lines for that user. Additionally, K-lines can only
1656 be used to block username/hostname combinations; in some circumstances it
1657 may be desirable to block users based on nickname, "real name", or IP
1658 address.
1659
1660 <p>The former problem, of keeping K-lines synchronized across servers, is
1661 solved by Services' <i>autokill</i> feature, provided by the
1662 <tt>operserv/akill</tt> module. This module keeps a list of K-lines
1663 (<i>i.e.,</i> username/hostname wildcard masks) which should be maintained
1664 across all servers, and if a user matching any such mask attempts to
1665 connect to the network, Services will automatically issue a <tt>KILL</tt>
1666 message for that user, removing them from the network (hence the name
1667 "autokill"). Some servers support a feature which allows Services to
1668 dynamically update K-lines for all servers, and Services takes advantage of
1669 this as well.
1670
1671 <p>The latter problem, of blocking users based on things other than their
1672 username and hostname, is handled by the <i>S-line</i> feature, provided by
1673 the <tt>operserv/sline</tt> module. There are three varieties of S-line:
1674 <ul>
1675 <li><b>SGline</b>, which matches against a user's "real name" (also called
1676 "gecos", hence the "G");
1677 <li><b>SQline</b>, which matches against a user's nickname (the "Q" comes
1678 from "quarantine", and some servers support "Q-lines" in configuration files
1679 to ban certain nicknames from being used on that server); and
1680 <li><b>SZline</b>, which matches against a user's IP address (the "Z" comes
1681 from "zap", and some servers support "Z-lines" in configuration files).
1682 </ul>
1683 As with autokills, Services will automatically issue a <tt>KILL</tt>
1684 message for any user which matches any of these masks, with two exceptions.
1685 For SQlines, if the IRC server in use supports forced nick changing and if
1686 <a href="a.html#operserv/sline.SQlineKill"><tt>SQlineKill</tt></a> is not
1687 set in <tt>modules.conf</tt>, Services will not kill the user, but rather
1688 change the user's nickname to a "guest" nickname, and also send an error
1689 message which will cause the client to force the user to choose a different
1690 nickname. IRC operators can be exempted from the SQline check by setting
1691 the
1692 <a href="a.html#operserv/sline.SQlineIgnoreOpers"><tt>SQlineIgnoreOpers</tt></a>
1693 option in <tt>modules.conf</tt>. Also, some servers do not provide IP
1694 address information, and thus Services will be unable to check SZlines on
1695 these servers; in this case, Services will issue a warning and SZlines will
1696 be disabled. (Some servers allow SZlines to be set by Services on each
1697 server, and in this case SZlines can still be used if the
1698 <a href="a.html#operserv/sline.ImmediatelySendSline"><tt>ImmediatelySendSline</tt></a>
1699 option is set in <tt>modules.conf</tt>.)
1700
1701 <p>Since the autokill and S-line features are virtually identical, only the
1702 autokill feature will be described in detail here; see the documentation
1703 for the <a href="4.html#oper.sgline"><tt>SGLINE</tt></a>,
1704 <a href="4.html#oper.sqline"><tt>SQLINE</tt></a>, and
1705 <a href="4.html#oper.szline"><tt>SZLINE</tt></a> commands and the
1706 <a href="a.html#operserv/sline"><tt>operserv/sline</tt></a> section of
1707 <tt>modules.conf</tt> for details on S-line usage.
1708
1709 <p><b>How autokills work</b>
1710
1711 <p>When a user connects to the IRC network, the server to which the user
1712 connected will forward information about that user, including the user's
1713 username and hostname, to Services along with the other IRC servers on the
1714 network. When Services receives this information, it joins the username
1715 and hostname with an at-sign character to form a
1716 <tt><i>username</i>@<i>hostname</i></tt> string. This string is then
1717 compared against each mask in the autokill list. If a match is found,
1718 Services issues a <tt>KILL</tt> message for the user, causing the user to
1719 be disconnected from the network; the text used in the <tt>KILL</tt>
1720 message can be set with the
1721 <a href="a.html#operserv/akill.AutokillReason"><tt>AutokillReason</tt></a>
1722 option in <tt>modules.conf</tt>. Additionally, for servers supporting a
1723 "network K-line" mechanism, which includes every supported server except
1724 for classic RFC 1459 and TS8-based servers, Services will send out a K-line
1725 for the username and hostname which the user matched; this directs the
1726 servers to immediately disconnect any user matching that username and
1727 hostname mask. (If more than one autokill mask matches, then the first one
1728 found will be used.)
1729
1730 <p>Autokills can be set to expire (be automatically deleted) after a
1731 certain length of time. This length of time is set by the
1732 <a href="a.html#operserv/akill.AutokillExpiry"><tt>AutokillExpiry</tt></a>
1733 configuration option in <tt>modules.conf</tt>, and is set to 30 days in the
1734 example <tt>modules.conf</tt> file distributed with Services. After this
1735 length of time, Services will remove the mask from the autokill list,
1736 allowing users matching the mask to connect again; if the
1737 <a href="a.html#operserv/akill.WallAutokillExpire"><tt>WallAutokillExpire</tt></a>
1738 configuration option is set, Services will inform all IRC operators when
1739 this occurs. For servers with a "network K-line" mechanism, K-lines
1740 corresponding to a mask will automatically be removed when it expires (or
1741 is explicitly deleted). The length of time before expiration can also be
1742 set for each individual autokill mask, as described below.
1743
1744 <p><b>Using the <tt>AKILL</tt> command</b>
1745
1746 <p>The <a href="4.html#oper.akill"><tt>AKILL</tt></a> command, available
1747 only to Services operators, is used to manage the autokill list. It has
1748 five subcommands:
1749 <ul>
1750 <li><b><tt>ADD</tt></b>, to add a mask to the autokill list;
1751 <li><b><tt>DEL</tt></b>, to remove a mask from the autokill list;
1752 <li><b><tt>LIST</tt></b>, to list all masks on the autokill list;
1753 <li><b><tt>VIEW</tt></b>, to give detailed information about masks on the
1754 autokill list;
1755 <li><b><tt>CHECK</tt></b>, to find autokill masks that match a given
1756 <tt><i>user</i>@<i>host</i></tt> pair; and
1757 <li><b><tt>COUNT</tt></b>, to show the number of masks on the autokill list.
1758 </ul>
1759
1760 <p>Autokill masks take the form <tt><i>user</i>@<i>host</i></tt>&mdash;note
1761 that nicknames are <i>not</i> used. (S-lines use different formats; see
1762 the relevant command documentation.) When adding a mask to the autokill
1763 list, you must also include a reason for it; this allows other Services
1764 operators (or you, if you later forget) to know why the mask was added.
1765 The reason is shown in the response to a <tt>LIST</tt> or <tt>VIEW</tt>
1766 command. If the
1767 <a href="a.html#operserv/akill.WallOSAkill"><tt>WallOSAkill</tt></a> option
1768 is set in <tt>modules.conf</tt>, OperServ will send a notice to all IRC
1769 operators when an autokill is added or deleted.
1770
1771 <p>As mentioned above, autokills expire by default after the amount of time
1772 specified in the
1773 <a href="a.html#operserv/akill.AutokillExpiry"><tt>AutokillExpiry</tt></a>
1774 option in <tt>modules.conf</tt>. A particular autokill can be set to
1775 expire in a different amount of time, or to not expire at all, by including
1776 the desired expiration time in the <tt>ADD</tt> command, as described in
1777 the <tt>AKILL</tt> command documentation. It is also possible to place an
1778 upper limit on expiration times set by Services operators (as opposed to
1779 Services administrators), using the
1780 <a href="a.html#operserv/akill.OperMaxExpiry"><tt>OperMaxExpiry</tt></a>
1781 option in <tt>modules.conf</tt>; if this is set, Services operators will
1782 not be allowed to set autokills that last longer than the given period of
1783 time or that do not expire.
1784
1785 <p>The difference between the <tt>LIST</tt> and <tt>VIEW</tt> subcommands
1786 is their verbosity. <tt>LIST</tt> displays each autokill mask on one line,
1787 showing only the mask and the reason (though if the mask or reason is long,
1788 this may be wrapped onto multiple lines by your IRC client). <tt>VIEW</tt>,
1789 on the other hand, uses multiple lines for each mask, displaying the
1790 nickname of the person who added it, the date and time it was added, the
1791 last time it was used (if at all), and when it expires, in addition to the
1792 mask itself and reason. The last-used time shows the last time a user who
1793 matched the mask connected to the network, and is helpful when determining
1794 whether an autokill mask is still needed. However, this may not be
1795 accurate if your IRC servers support a server-based autokill mechanism;
1796 such servers will block the user from connecting without informing
1797 Services, so the last-used time will show only the first time a matching
1798 user connected. (If the
1799 <a href="a.html#operserv/akill.ImmediatelySendAutokill"><tt>ImmediatelySendAutokill</tt></a>
1800 option in <tt>modules.conf</tt> is enabled, the last-used time will never
1801 be set at all on these servers.)
1802
1803 <p>The <tt>CHECK</tt> command can be thought of as an "inverse <tt>LIST</tt>":
1804 instead of finding autokills which match a given pattern, <tt>CHECK</tt>
1805 looks for autokills which a given <tt><i>user</i>@<i>host</i></tt> string
1806 would match. This can be useful in finding which autokill was applied to a
1807 particular user who was disconnected from the network.
1808
1809 <a name=4-3-exclude></a>
1810 <p><b>Autokill exclusions</b>
1811
1812 <p>(Note: this section applies to autokills only; S-lines do not have
1813 exclusion capability.)
1814
1815 <p>It is also possible to add "anti-autokill" masks&mdash;that is, masks
1816 for users that should be allowed to connect even if they match an autokill.
1817 These are known as <i>autokill exclusions</i>, and are enabled with the
1818 <a href="a.html#operserv/akill.EnableExclude"><tt>EnableExclude</tt></a>
1819 option in <tt>modules.conf</tt>. The autokill exclusion list is managed
1820 with the <a href="4.html#oper.exclude"><tt>EXCLUDE</tt></a> command, which
1821 functions in much the same way as the <tt>AKILL</tt> command described
1822 above. (However, newly-added exclusions are always sent immediately to the
1823 server regardless of the state of the
1824 <a href="a.html#operserv/akill.ImmediatelySendAutokill"><tt>ImmediatelySendAutokill</tt></a>
1825 setting; this is to avoid an autokill being triggered by a non-excluded
1826 match before the exclusion has been sent, resulting in the excluded users
1827 being blocked as well.)
1828
1829 <p>When autokill exclusions are in use, Services will first check the
1830 exclusion list for each user connecting to the network. If a matching mask
1831 is found on the exclusion list, Services allows that user to connect,
1832 skipping the ordinary check of the autokill list for that user. For
1833 example, if an autokill was placed on <tt>*@*.example.com</tt>, but one of
1834 the IRC operators for a server on the network connected from the host
1835 <tt>foo.example.com</tt>, an autokill exclusion for
1836 <tt>*@foo.example.com</tt> would allow that user to connect, while still
1837 preventing any other users in the <tt>example.com</tt> domain from
1838 connecting.
1839
1840 <p>One important side effect of autokill exclusions is a potential increase
1841 in network traffic. If the IRC server in use supports server-based
1842 autokills, then ordinarily Services will take advantage of it to prevent
1843 users matching autokills from connecting to the network on the server end.
1844 However, if the servers do not support server-based autokill exclusions
1845 (the only supported servers which have this ability are the InspIRCd,
1846 tr-ircd, and Unreal 3.2 IRC servers), then Services will not be able to use
1847 server-based autokills either&mdash;if it did, the servers would block
1848 users on the exclusion list as well without Services being able to
1849 intervene&mdash;and will fall back to the default method of sending a
1850 <tt>KILL</tt> message for autokilled users. Aside from resulting in more
1851 traffic on the IRC network, this leaves open the potential for autokilled
1852 users to send messages before getting killed if there is enough lag between
1853 Services and the server to which the user connected.
1854
1855 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1856
1857 <a name=4-4></a>
1858 <h4>3-4-4. Session limiting</h4>
1859
1860 <p>One other way of preventing undesired clients from connecting to the
1861 network is via <i>session limiting</i>, provided by the
1862 <tt>operserv/sessions</tt> module. When session limiting is active
1863 (<i>i.e.,</i> when the module is in use), Services will keep track of the
1864 number of clients connected from each host, and will issue <tt>KILL</tt>
1865 messages for any clients exceeding the limit set by the
1866 <a href="a.html#operserv/sessions.DefSessionLimit"><tt>DefSessionLimit</tt></a>
1867 configuration option in <tt>modules.conf</tt> (or specific limits for the
1868 host as set by session exceptions, described below). Before actually
1869 disconnecting the client, Services can be configured to send notices with the
1870 <a href="a.html#operserv/sessions.SessionLimitExceeded"><tt>SessionLimitExceeded</tt></a> and
1871 <a href="a.html#operserv/sessions.SessionLimitDetailsLoc"><tt>SessionLimitDetailsLoc</tt></a>
1872 configuration options.
1873
1874 <p>If the autokill module (see <a href="#4-3">section 3-4-3</a>) is loaded,
1875 Services can also add an autokill if a particular host's session limit is
1876 exceeded frequently in a short period of time. This is controlled by the
1877 <a href="a.html#operserv/sessions.SessionLimitAutokill"><tt>SessionLimitAutokill</tt></a>
1878 configuration directive, which allows precise definitions of "frequently"
1879 and "short" as well as the expiration time for such autokills to be set.
1880
1881 <p>Session exceptions are managed through the
1882 <a href="4.html#oper.exception"><tt>EXCEPTION</tt></a> command. This
1883 command functions similarly to the <tt>AKILL</tt> command, but when adding
1884 session exceptions, you need to include the limit (the maximum number of
1885 clients to allow) in the command. An upper bound can be set on this value
1886 with the
1887 <a href="a.html#operserv/sessions.MaxSessionLimit"><tt>MaxSessionLimit</tt></a>
1888 option. As with autokills, exceptions can be set to expire after a
1889 certain amount of time
1890 (<a href="a.html#operserv/sessions.ExceptionExpiry"><tt>ExceptionExpiry</tt></a>),
1891 and Services can be set to inform IRC operators when an exception is added
1892 or deleted
1893 (<a href="a.html#operserv/sessions.WallOSException"><tt>WallOSException</tt></a>)
1894 or expires
1895 (<a href="a.html#operserv/sessions.WallExceptionExpire"><tt>WallExceptionExpire</tt></a>),
1896
1897 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1898
1899 <a name=4-5></a>
1900 <h4>3-4-5. News</h4>
1901
1902 <p>The <tt>operserv/news</tt> module provides a simple "news" service to
1903 allow messages to be automatically sent to all users when logging onto the
1904 network, or to IRC operators when they give the <tt>/oper</tt> command.
1905 News items are added and deleted through the
1906 <a href="4.html#oper.logonnews"><tt>LOGONNEWS</tt></a> and
1907 <a href="4.html#oper.opernews"><tt>OPERNEWS</tt></a> commands, respectively.
1908 For each set, the most recent three items (or all the items, if there are
1909 three or less) are displayed.
1910
1911 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1912
1913 <!------------------------------------------------------------------------>
1914 <p><hr>
1915
1916 <a name=5></a>
1917 <h3>3-5. Network statistics collection (StatServ)</h3>
1918
1919 <p>IRC Services provides a simple network statistics collection service,
1920 accessible through the "<b>StatServ</b>" pseudoclient. StatServ tracks the
1921 last time each server on the network connected and disconnected, along with
1922 the number of users on each server and the total number of users on the
1923 network. Normally all users have access to this information, but use of
1924 StatServ can be limited to IRC operators only by setting the
1925 <a href="a.html#statserv/main.SSOpersOnly"><tt>SSOpersOnly</tt></a> option
1926 in <tt>modules.conf</tt>.
1927
1928 <p>Server information is accessed through the
1929 <a href="4.html#stat.servers"><tt>SERVERS</tt></a> command. StatServ can
1930 display information on all servers or only online or offline servers,
1931 including the last connect and disconnect time, the current number of users
1932 and IRC operators, and the respective percentages of the total number of
1933 users and IRC operators on the network. Additionally, Services
1934 administrators can copy, rename, or delete server entries to keep the data
1935 up-to-date with respect to network changes.
1936
1937 <p>The <a href="4.html#stat.users"><tt>USERS</tt></a> command can be used
1938 to display the current number of users and IRC operators on the network, as
1939 well as the average number of users and operators per server.
1940
1941 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
1942
1943 <!------------------------------------------------------------------------>
1944 <p><hr>
1945
1946 <a name=6></a>
1947 <h3>3-6. Built-in HTTP server</h3>
1948
1949 <p>Aside from interacting directly with the IRC network, Services is also
1950 capable of providing information to World Wide Web clients (browsers) via
1951 the HTTP protocol. While this functionality is not nearly as extensive as
1952 full-fledged HTTP servers such as Apache, it does provide the ability to
1953 access current information on Services and the IRC network without having
1954 to go through a CGI or other external program.
1955
1956 <p>Services' HTTP server functionality is comprised of three parts: the
1957 core HTTP server module, authorization modules, and content modules. These
1958 are discussed in the following sections.
1959
1960 <a name=6-1></a>
1961 <h4>3-6-1. Core HTTP server module</h4>
1962
1963 <p>The core HTTP server module, <tt>httpd/main</tt>, provides the
1964 foundation for the other HTTP modules, including the ability to listen for
1965 and parse HTTP requests. This module is akin to, although considerably
1966 less full-featured than, a typical standalone HTTP server (httpd).
1967
1968 <p>The HTTP server's behavior is defined by settings in the
1969 <tt>modules.conf</tt> file. The most important of these,
1970 <a href="a.html#httpd/main.ListenTo"><tt>ListenTo</tt></a>, specifies the
1971 IP address and port number on which the HTTP server listens for
1972 connections; it is possible to specify multiple addresses, which will cause
1973 Services to listen for connections on all of them. The port number can be
1974 any port which is not already used by another service on the same machine,
1975 although using ports below 1024 normally requires super-user privileges.
1976 The IP address can be specified as "<tt>*</tt>" in the simplest case; this
1977 means "listen for connections on any IP address". However, if you are
1978 using a machine with multiple IP addresses, you may need to enter a
1979 specific IP address to avoid collisions with services listening on other IP
1980 addresses. You may also choose to only allow connections from clients on
1981 the same machine by specifying the "<tt>localhost</tt>" address,
1982 <tt>127.0.0.1</tt>; the same sort of access control can also be performed
1983 on a per-resource basis using the <tt>httpd/auth-ip</tt> authorization
1984 module, discussed later, but if you want to limit all resources to the
1985 local machine, this method is safer and more efficient.
1986
1987 <p>It is also possible to use a hostname in place of the IP address; in
1988 this case, Services will look up the hostname at startup and use the IP
1989 address found (all addresses, if more than one is found) as the address to
1990 listen to. However, these addresses will not change even if the hostname's
1991 DNS information changes, unless Services is restarted or instructed to
1992 reread the configuration files (see <a href="2.html#6">section 2-6</a>).
1993
1994 <p>The number of connections allowed at once and the length of time a
1995 single connection can remain open are set by the
1996 <a href="a.html#httpd/main.MaxConnections"><tt>MaxConnections</tt></a>,
1997 <a href="a.html#httpd/main.MaxRequests"><tt>MaxRequests</tt></a>, and
1998 <a href="a.html#httpd/main.IdleTimeout"><tt>IdleTimeout</tt></a>
1999 directives. <tt>MaxConnections</tt> sets the maximum number of
2000 simultaneous connections Services will accept; any connections above this
2001 limit will be dropped as soon as they are accepted. <tt>MaxRequests</tt>
2002 sets the maximum number of HTTP requests that can be sent over a single
2003 connection, while <tt>IdleTimeout</tt> gives the maximum length of time a
2004 connection can be idle (<i>i.e.,</i> not receiving any data from the
2005 client); if either of these limits are passed, the connection is dropped.
2006 (Note that some resources cause the connection to be dropped after the
2007 server finishes sending data, regardless of these settings.)
2008
2009 <p>If the
2010 <a href="a.html#httpd/main.LogConnections"><tt>LogConnections</tt></a>
2011 directive is given, the HTTP server will write a log message to the
2012 Services log file for each connection accepted. Note that the resource
2013 (URL) requested is not logged, and only one message is written per
2014 connection, even if several HTTP requests are made over the same
2015 connection. (If per-request logging is desired, <tt>MaxRequests</tt> can
2016 be set to 1 to force clients to open a new connection for each request.)
2017
2018 <p>The remaining settings,
2019 <a href="a.html#httpd/main.ListenBacklog"><tt>ListenBacklog</tt></a> and
2020 <a href="a.html#httpd/main.RequestBufferSize"><tt>RequestBufferSize</tt></a>,
2021 can usually be left as is. <tt>ListenBacklog</tt> specifies how many
2022 connections the OS should allow to be made to a single HTTP server port
2023 without being accepted by Services, a situation which can arise if the HTTP
2024 server is under heavy load and requests come in faster than Services can
2025 process them. (However, some operating systems do not allow a value
2026 greater than the default of 5; on such systems, increasing the value will
2027 not cause an error but will have no effect.) <tt>RequestBufferSize</tt>
2028 specifies the size of the receive buffer allocated for each request; if a
2029 request exceeds this size, the client will be sent a "Request Entity Too
2030 Large" error and the connection will be dropped. There should be no need
2031 to modify this value for the modules distributed with Services.
2032
2033 <p>Note that the <tt>RequestBufferSize</tt> setting only affects the size
2034 of the receive buffer itself. In addition to this buffer, a fixed-size
2035 control structure and a list of headers and form variables are also
2036 allocated for each connection; in the worst case, these will require
2037 approximately 4/3 of the value given for <tt>RequestBufferSize</tt>. Thus,
2038 the maximum amount of memory used by the HTTP server module can be
2039 conservatively calculated as approximately <tt>MaxConnections *
2040 RequestBufferSize * 2.5</tt>.
2041
2042 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2043
2044 <a name=6-2></a>
2045 <h4>3-6-2. Authorization modules</h4>
2046
2047 <p>Since it may not be desirable to allow anyone access to the resources
2048 provided by the HTTP server, Services provides "authorization modules",
2049 whose names start with "<tt>auth-</tt>", to control access to those
2050 resources.
2051
2052 <p><b>Control by client IP address: the <tt>httpd/auth-ip</tt> module</b>
2053
2054 <p>The <tt>httpd/auth-ip</tt> module allows access control based on the IP
2055 address of the connecting client. The module uses two configuration
2056 directives, <a href="a.html#httpd/auth-ip.AllowHost"><tt>AllowHost</tt> and
2057 <tt>DenyHost</tt></a>, to control access to particular resources (URLs).
2058 Both directives take two parameters: the resource to control access to, and
2059 the IP address or hostname to allow or deny access from.
2060
2061 <p>The first parameter, the resource to control access to, consists of a
2062 relative URL beginning with the <tt>/</tt> character; <i>i.e.,</i> not
2063 including the leading "<tt>http://<i>host.name</i></tt>" typed into the
2064 browser. Services will control access as specified by the directive to
2065 this resource, <i>and</i> to any resource whose URL begins with the same
2066 string&mdash;so, for example, giving "<tt>/dir</tt>" as the resource to
2067 control will affect not only "<tt>/dir/file</tt>" but "<tt>/dirty</tt>" as
2068 well. To limit the directive's effect to a particular directory, make sure
2069 to include a "<tt>/</tt>" at the end of the resource URL, <i>e.g.</i>
2070 "<tt>/dir/</tt>". Access control can be applied to every resource on the
2071 server by using the resource URL "<tt>/</tt>".
2072
2073 <p>The second parameter, the IP address, is specified much the same as with
2074 the core module's <tt>ListenTo</tt> directive: the string "<tt>*</tt>" can
2075 be used to mean "all IP addresses", and a hostname will be replaced with
2076 the IP address or addresses associated with that hostname. (Keep in mind
2077 that hostnames are resolved to IP address only once, at program startup; if
2078 the hostname's IP address changes while Services is running, Services will
2079 not recognize the new IP address for authorization purposes.) For these
2080 directives, one additional type of IP address specification is possible: a
2081 network specification of the form
2082 <tt><i>aaa</i>.<i>bbb</i>.<i>ccc</i>.<i>ddd</i>/<i>xx</i></tt>, where
2083 <tt><i>xx</i></tt> is an integer from 1 to 31 inclusive that gives the
2084 number of bits in the network part of the address. For example,
2085 <tt>192.168.1.64/26</tt> represents the range of IP addresses from
2086 192.168.1.64 through 192.168.1.127 (all IP addresses whose first 26 bits
2087 are the same as those in 192.168.1.64).
2088
2089 <p>When specifying multiple control directives, it is important that they
2090 are given in the proper order. All <tt>AllowHost</tt> and <tt>DenyHost</tt>
2091 directives are checked in the order they are listed in <tt>modules.conf</tt>
2092 without regard to specificity of either the IP address or the resource, and
2093 the first matching entry found is used; as a result, a more specific entry
2094 will have no effect if placed below (after) a more general one. As an
2095 example, consider the following pair of directives:
2096
2097 <blockquote>
2098 <tt>AllowHost / 192.168.0.1
2099 <br>DenyHost&nbsp;&nbsp;/ 192.168.0.0/24</tt>
2100 </blockquote>
2101
2102 The first one allows access to the entire server from the IP address
2103 <tt>192.168.0.1</tt>, while the second denies access from all IP addresses
2104 in the <tt>192.168.0.*</tt> network. In the order given, this allows
2105 access from <i>only</i> <tt>192.168.0.1</tt> in that network, while
2106 preventing all other hosts in the network from connecting. However, if the
2107 directives are given in the reverse order:
2108
2109 <blockquote>
2110 <tt>DenyHost&nbsp;&nbsp;/ 192.168.0.0/24
2111 <br>AllowHost / 192.168.0.1</tt>
2112 </blockquote>
2113
2114 then clients from <tt>192.168.0.1</tt> will be blocked along with the rest
2115 of the <tt>192.168.0.*</tt> network, because the first directive tells
2116 Services to deny access to <tt>192.168.0.1</tt> as well as other hosts on
2117 that network, so the second directive is never checked.
2118
2119 <p>The list of directives should always end with either
2120 "<tt>AllowHost / *</tt>" or "<tt>DenyHost / *</tt>" to control whether
2121 requests which do not match any other directive should be allowed or
2122 denied. The behavior of the module when no entries match a particular
2123 client's IP address is undefined.
2124
2125 <p><b>Control by password: the <tt>httpd/auth-password</tt> module</b>
2126
2127 <p>It is also possible to control access by requiring the client to enter a
2128 username and password to access a particular resource. This is
2129 accomplished using the <tt>httpd/auth-password</tt> module. Like the
2130 <tt>httpd/auth-ip</tt> module, access is controlled by a list of
2131 directives; for this module, the directive name is
2132 <a href="a.html#httpd/auth-password.Protect"><tt>Protect</tt></a>, and the
2133 second parameter is a username and password pair with the username and
2134 password separated by a colon (<i>e.g.,</i> "<tt>username:password</tt>").
2135 Additionally, the
2136 <a href="a.html#httpd/auth-password.AuthName"><tt>AuthName</tt></a>
2137 directive specifies the name used by the HTTP client in password prompts,
2138 such as "Enter username and password for <i>name</i>:".
2139
2140 <p>Like the <tt>httpd/auth-ip</tt> module, the first <tt>Protect</tt>
2141 directive matching a particular request will be used, so specific entries
2142 should be placed before general ones. However, it is not necessary to
2143 include a <tt>Protect /</tt> directive at the end of the list, unless you
2144 want password protection for the entire server; if a request does not match
2145 any directives, then it is allowed through without a password.
2146
2147 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2148
2149 <a name=6-3></a>
2150 <h4>3-6-3. Content modules</h4>
2151
2152 <p>The remainder of the HTTP server modules are "content modules", which,
2153 as the name suggests, provide the actual content served to browsers.
2154
2155 <p><b>"Index" page: the <tt>httpd/top-page</tt> module</b>
2156
2157 <p>This simple module allows you to provide an HTML (or other) file to be
2158 served when the HTTP server's "top page" (the "<tt>/</tt>" URL) is accessed.
2159 Since in a typical setup, other content modules will each have their own
2160 sub-path within the HTTP server, this module lets you provide (for example)
2161 an index of the information available. The file to serve is given by the
2162 <a href="a.html#httpd/top-page.Filename"><tt>Filename</tt></a> directive in
2163 <tt>modules.conf</tt>; the file's MIME type can optionally be specified as
2164 well.
2165
2166 <p>It is also possible to specify a URL to a remote site (which could be a
2167 separate HTTP server on the same machine) for the top page, using the
2168 <a href="a.html#httpd/top-page.Redirect"><tt>Redirect</tt></a> directive;
2169 in this case, Services will redirect top-page accesses to the given URL.
2170 If both <tt>Redirect</tt> and <tt>Filename</tt> are given,
2171 <tt>Redirect</tt> takes precedence, and <tt>Filename</tt> is ignored.
2172
2173 <p>Note that with <tt>Filename</tt>, the file specified is served as-is;
2174 Services will not attempt to execute it even if it looks like a CGI script,
2175 and cannot process PHP or other such languages embedded in the file.
2176
2177 <p><b>Providing links to nickname and channel URLs: the
2178 <tt>httpd/redirect</tt> module</b>
2179
2180 <p>The <tt>httpd/redirect</tt> module can be used to provide automatic
2181 redirects from a nickname or channel to the URL (if any) registered for the
2182 nickname or channel. This can be used as a simple way to let your users
2183 provide information about themselves without requiring the viewer to log
2184 onto IRC and execute a NickServ or ChanServ <tt>INFO</tt> command.
2185
2186 <p>Nickname and channel redirects each use a base URL specified in
2187 <tt>modules.conf</tt>:
2188 <a href="a.html#httpd/redirect.NicknamePrefix"><tt>NicknamePrefix</tt></a>
2189 for nicknames, and
2190 <a href="a.html#httpd/redirect.ChannelPrefix"><tt>ChannelPrefix</tt></a>
2191 for channels. The nickname or channel whose URL is used is the string
2192 immediately following the given prefix (in the case of channels, the
2193 leading "<tt>#</tt>" is discarded, since it cannot be used in URLs). This
2194 means that to get URLs like
2195 "<tt>http://services.example.net/channel/<i>channel-name</i></tt>", the prefix
2196 should be specified as "<tt>/channel/</tt>" with a trailing slash, but also
2197 allows you to specify "<tt>/~</tt>" for the nickname prefix and get URLs
2198 like "<tt>http://services.example.net/~<i>nickname</i></tt>". (Both of
2199 these are the default settings.)
2200
2201 <p><tt>NicknamePrefix</tt> and <tt>ChannelPrefix</tt> should be specified
2202 so that they do not overlap; if a particular URL can be interpreted as both
2203 a nickname reference and a channel reference, the nickname will always take
2204 precedence, even if it is not registered or does not have a URL associated
2205 with it.
2206
2207 <p><b>Online database access: the <tt>httpd/dbaccess</tt> module</b>
2208
2209 <p><b>Warning:</b> This module provides complete access to all Services
2210 data; unauthorized access can result in password theft, denial of service
2211 attacks, or worse. Be certain to protect access to this module with
2212 authorization modules or other means.
2213
2214 <p>The <tt>httpd/dbaccess</tt> module is an administrative tool which
2215 allows the Services databases to be accessed through the simple
2216 point-and-click interface of a browser rather than the text-based commands
2217 of IRC. While the module does not permit the databases to be modified,
2218 registered nicknames and channels, autokills and S-lines, and so on can all
2219 be accessed and viewed through a simple menu system. Additionally, a copy
2220 of all Services data in XML format can be downloaded if the
2221 <tt>misc/xml-export</tt> module is loaded (see <a href="5.html#1">section
2222 5-1</a> for details).
2223
2224 <p>Especially when performing an XML download of the Services databases,
2225 keep in mind that Services will not respond to any network activity until
2226 the HTTP request completes; if you have a slow machine or a large database,
2227 this can cause Services to appear to "lag" on the IRC network, or in
2228 extreme cases get disconnected from the network entirely, so use caution.
2229
2230 <p>The URL at which the data is accessible is set by the
2231 <a href="a.html#httpd/dbaccess.Prefix"><tt>Prefix</tt></a> directive in
2232 <tt>modules.conf</tt>; if it does not end with a slash, one will be
2233 appended automatically. Accessing this URL will bring up a menu of
2234 available data. If you want to use different access rules for different
2235 categories of data, refer to the following table for the appropriate
2236 pathnames (in all cases, <tt><i>path</i></tt> is the URL pathname given in
2237 the <tt>Prefix</tt> directive):
2238
2239 <div align=center><p><table border=0 cellspacing=2>
2240 <tr><td><tt><i>path</i>/</tt>
2241 <td>Main menu
2242 <tr><td><tt><i>path</i>/operserv/</tt>
2243 <td>OperServ data and menu
2244 <tr><td><tt><i>path</i>/operserv/akill/</tt>
2245 <td>Autokill list
2246 <tr><td><tt><i>path</i>/operserv/news/</tt>
2247 <td>News item list
2248 <tr><td><tt><i>path</i>/operserv/sessions/&nbsp;&nbsp;</tt>
2249 <td>Session and exception lists
2250 <tr><td><tt><i>path</i>/operserv/sline/</tt>
2251 <td>S-line lists
2252 <tr><td><tt><i>path</i>/nickserv/</tt>
2253 <td>Nickname list and information
2254 <tr><td><tt><i>path</i>/chanserv/</tt>
2255 <td>Channel list and information
2256 <tr><td><tt><i>path</i>/statserv/</tt>
2257 <td>Network statistics
2258 <tr><td><tt><i>path</i>/xml-export/</tt>
2259 <td>XML-format database download
2260 </table></div>
2261
2262 <p><b>Debugging information: the <tt>httpd/debug</tt> module</b>
2263
2264 <p>The <tt>httpd/debug</tt> module is intended primarily for module
2265 developers, and provides information about the HTTP request received by
2266 Services at a URL specified by the
2267 <a href="a.html#httpd/debug.DebugURL"><tt>DebugURL</tt></a> directive in
2268 <tt>modules.conf</tt>. This module is unneeded for normal operation of
2269 Services, and should not be enabled except when testing the HTTP server.
2270
2271 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2272
2273 <!------------------------------------------------------------------------>
2274 <p><hr>
2275
2276 <a name=7></a>
2277 <h3>3-7. Password encryption</h3>
2278
2279 <p>Services has the ability to encrypt passwords (nickname passwords,
2280 channel passwords, and the OperServ super-user password) to provide an
2281 additional layer of protection against password theft. Normally, passwords
2282 are not encrypted, and if an unauthorized user gains access to the
2283 databases, users' passwords will be compromised; encryption prevents this
2284 compromise from occurring (although it is still possible for an attacker to
2285 "crack" the encrypted passwords, especially if the passwords are easily
2286 guessable). Note that under the default installation procedures, only the
2287 user installing Services and the administrator of the machine Services is
2288 installed on will have access to the databases.
2289
2290 <p>The downside to using encryption, although minor, is that the NickServ
2291 and ChanServ <tt>GETPASS</tt> commands will become unusable. This is
2292 because some types of encryption, including all the types supported by
2293 Services, are one-way only (also known as "trapdoor functions"); such
2294 encryption types allow a password to be converted into an encrypted string,
2295 but do not allow the password to be recovered from that string.
2296
2297 <p>To enable encryption of passwords, ensure that the desired encryption
2298 module is loaded with a <tt>LoadModule</tt> directive, then enter the
2299 encryption type (the name of the module without the leading
2300 "<tt>encryption/</tt>") in the
2301 <a href="a.html#EncryptionType"><tt>EncryptionType</tt></a> directive in
2302 <tt>ircservices.conf</tt>. There is no penalty for loading multiple
2303 encryption modules, but only the module specified by the
2304 <tt>EncryptionType</tt> directive will be used to encrypt new passwords.
2305
2306 <p>The available encryption modules are as follows:
2307
2308 <p><ul>
2309 <li><b><tt>encryption/md5</tt></b>: Uses the MD5 hashing algorithm to
2310 encrypt passwords. This is a one-way encryption algorithm which generates
2311 a 128-bit "digest" of the password, and is used by several Unix systems to
2312 encrypt user passwords as well.
2313 <p><li><b><tt>encryption/unix-crypt</tt></b>: <b>DISCOURAGED.</b> Uses the
2314 <tt>crypt()</tt> function available in most Unix systems, typically a
2315 variant of the DES encryption algorithm, to encrypt passwords. This is a
2316 one-way encryption algorithm; as it is not very strong (only 56 bits),
2317 recent operating systems tend to avoid it in favor of MD5, SHA1, or other
2318 stronger algorithms, and this module is provided primarily for
2319 compatibility with externally-generated passwords or databases from other
2320 Services-like programs. Note that this module requires that your operating
2321 system support the <tt>crypt()</tt> function, and it will refuse to load
2322 otherwise.
2323 </ul>
2324
2325 <p>When a password is encrypted, Services stores the encryption type used,
2326 so that even if the <tt>EncryptionType</tt> directive is later changed,
2327 older passwords can still be used (provided the appropriate module is
2328 loaded).
2329
2330 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2331
2332 <!------------------------------------------------------------------------>
2333 <p><hr>
2334
2335 <a name=8></a>
2336 <h3>3-8. E-mail sending</h3>
2337
2338 <p>Services has the ability to send E-mail to users outside of the IRC
2339 protocol. This ability is used, for example, by the NickServ E-mail
2340 authentication (<a href="#1-4">section 3-1-4</a>) module. E-mail
2341 functionality is split into two parts: a main module, which provides an
2342 interface for other modules to use, and method modules, which actually
2343 implement the E-mail functions at the system level.
2344
2345 <p>The main module, <tt>mail/main</tt>, provides a method-independent
2346 interface for sending mail, and this module is used by other modules which
2347 need to send mail. (If you do not load this module, then other modules
2348 which depend on it may print errors such as "<tt>unable to resolve symbol
2349 `sendmail'</tt>" and cause Services to abort. Remember that order of
2350 module loading is important&mdash;you must load this module before any that
2351 use it!)
2352
2353 <p>The main mail module has four configuration settings in
2354 <tt>modules.conf</tt>:
2355 <a href="a.html#mail/main.FromAddress"><tt>FromAddress</tt></a> and
2356 <a href="a.html#mail/main.FromName"><tt>FromName</tt></a>, which indicate
2357 the E-mail address and name to be used in the "From" line of E-mail
2358 messages; <a href="a.html#mail/main.MaxMessages"><tt>MaxMessages</tt></a>,
2359 which sets the maximum number of messages which can be "in transit" (not
2360 yet finished sending) at once; and
2361 <a href="a.html#mail/main.SendTimeout"><tt>SendTimeout</tt></a>, which
2362 sets the amount of time Services will wait for a message to finish being
2363 sent before aborting it.
2364
2365 <p>The method modules provide the interface between the main module and the
2366 operating system. Two method modules are available:
2367
2368 <p><ul><li><b><tt>mail/sendmail</tt></b>: Uses the Sendmail program found
2369 on many Unix systems to send e-mail. The module may also work with other
2370 mail software that provides a <tt>sendmail</tt> executable program.
2371 However, this method is subject to delays by the <tt>sendmail</tt> program,
2372 during which Services will not be able to respond to any messages; some
2373 <tt>sendmail</tt> programs also do not let you set the "From" address to
2374 anything but your real address and name, which may not be desirable in some
2375 cases. Thus, it is recommended that the <tt>mail/smtp</tt> module (below)
2376 be used when possible.
2377
2378 <p>The configuration setting
2379 <a href="a.html#mail/sendmail.SendmailPath"><tt>SendmailPath</tt></a> (in
2380 <tt>modules.conf</tt>) should be set to the pathname of your
2381 <tt>sendmail</tt> program. Typical locations on Unix systems are
2382 <tt>/usr/lib/sendmail</tt> or <tt>/usr/sbin/sendmail</tt>; if you do not
2383 know the proper setting for your system, ask your system administrator.
2384
2385 <p><li><b><tt>mail/smtp</tt></b>: Uses the SMTP protocol to send E-mail
2386 through an SMTP relay server. The server to use is specified by the
2387 <a href="a.html#mail/smtp.RelayHost"><tt>RelayHost</tt></a> configuration
2388 directive (in <tt>modules.conf</tt>); if possible, this should be set to
2389 either the same machine Services is running on or another server on the
2390 same local network, to reduce delays in sending mail. (Services does not
2391 perform actual delivery of mail; that is left to the relay server.) The
2392 server name to use when connecting to the remote server is set by the
2393 <a href="a.html#mail/smtp.SMTPName"><tt>SMTPName</tt></a> directive; this
2394 should usually be the same as the hostname of the machine on which
2395 Services runs.
2396
2397 </ul>
2398
2399 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2400
2401 <!------------------------------------------------------------------------>
2402 <p><hr>
2403
2404 <a name=9></a>
2405 <h3>3-9. Multilingual support</h3>
2406
2407 <p>Services has the ability to send messages to users in several different
2408 languages, allowing users from different countries to read messages in
2409 their own native language. The following non-English languages are fully
2410 or almost fully supported:
2411 <ul>
2412 <li>Dutch
2413 <li>Hungarian
2414 <li>Japanese
2415 <li>Spanish
2416 <li>Turkish
2417 </ul>
2418
2419 <p>The following languages are partially supported (some messages in these
2420 languages are out of date or missing, and will be displayed in English):
2421 <ul>
2422 <li>French
2423 <li>German
2424 <li>Russian
2425 </ul>
2426
2427 <p>Users with registered nicknames can use the NickServ
2428 <a href="4.html#nick.set_language"><tt>SET LANGUAGE</tt></a> command to
2429 select the language to be used by Services for notices and replies
2430 (this does not include things like memos and channel entry messages which
2431 are entered by users). By default, Services will use the language given by
2432 the <tt>DEF_LANGUAGE</tt> constant defined in the <tt>defs.h</tt> source
2433 file. As distributed, this is set to English (<tt>LANG_EN_US</tt>); unless
2434 you plan to run a regional network where the majority of the users speak
2435 the same non-English language, you should probably leave the default
2436 setting alone.
2437
2438 <p>It is possible to change the messages used by Services through the use
2439 of "external language files" (as opposed to the standard language files
2440 included with Services) and the
2441 <a href="a.html#LoadLanguageText"><tt>LoadLanguageText</tt></a>
2442 configuration directive in <tt>ircservices.conf</tt>. Any message which is
2443 handled by Services' multilingual system&mdash;which includes almost all
2444 messages sent to users, with the exception of a few messages intended for
2445 administrators&mdash;can be modified in this way. ("Message" here refers
2446 to a unit of text sent by Services in response to a specific event; there
2447 is not always a one-to-one correspondence between these units of text and
2448 the "messages" as seen by users, as described below.)
2449
2450 <p>External language files are simple text files that consist of a series
2451 of <i>message descriptors</i>, each containing a one-line header followed
2452 by zero or more lines of replacement text. As with the Services
2453 configuration files, blank lines and lines beginning with the <tt>#</tt>
2454 character are ignored. If you give a message identifier line without any
2455 following text, then nothing will be output for that message. Each line of
2456 replacement text must start with a tab character (ASCII 9, TAB), which will
2457 not be included in the text itself; when creating your file, make sure that
2458 your text editor does not convert tabs into spaces, which Services will not
2459 recognize.
2460
2461 <p>The first line of a message descriptor consists of a message identifier
2462 and language identifier separated by whitespace. The language identifier
2463 is simply the filename of the corresponding standard language file
2464 (installed into the <tt>languages</tt> subdirectory of the data directory);
2465 for example, the language identifier for United States English is
2466 <tt>en_us</tt>. The message descriptor is the internal name used by
2467 Services to refer to the message, and is written in upper case. To find
2468 the message name for a particular message, search the Services language
2469 source files (the <tt>*.l</tt> files in the <tt>lang</tt> directory of the
2470 source distribution) for the desired text, then find the first line above
2471 that message that does not contain a tab; that line is the message name.
2472
2473 <p>As an example, the following two-line file could be used to replace the
2474 "password incorrect" message (note that the second line begins with a tab
2475 character, not spaces):
2476
2477 <pre>
2478 PASSWORD_INCORRECT en_us
2479 This is a replacement for the PASSWORD_INCORRECT message.
2480 </pre>
2481
2482 <p>One thing that is important to remember when replacing messages is that
2483 some "messages" actually consist of several distinct units of text, some of
2484 which may only be displayed under certain conditions. For example, the
2485 basic help text for NickServ, displayed in response to a
2486 <tt>/msg&nbsp;NickServ&nbsp;HELP</tt> command, is made up of three
2487 "messages" in the Services sense: <tt>NICK_HELP</tt>, with the basic help
2488 text; <tt>NICK_HELP_EXPIRES</tt>, displayed if nickname expiration is
2489 active; and <tt>NICK_HELP_WARNING</tt>, displayed if the
2490 <a href="a.html#nickserv/main.NSHelpWarning"><tt>NSHelpWarning</tt></a>
2491 configuration option is set. If you want to change the NickServ help
2492 message, you will probably want to redefine all three of these messages.
2493
2494 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2495
2496 <!------------------------------------------------------------------------>
2497 <p><hr>
2498
2499 <a name=10></a>
2500 <h3>3-10. Third-party extensions</h3>
2501
2502 <p>The module system in IRC Services allows the easy addition of features
2503 to Services by third-party contributors. Third-party extension modules are
2504 typically distributed as source code packages, consisting of a directory
2505 containing a <tt>Makefile</tt> and various source code files.
2506
2507 <p>To install such a third-party extension, you need to copy the extension
2508 module's source code directory into the Services source code tree under the
2509 <tt>modules</tt> directory. (Make certain that you do not copy the source
2510 files themselves into the <tt>modules</tt> directory, or Services may no
2511 longer compile correctly! For example, if the source code is contained in
2512 a directory called "<tt>mymodule</tt>", you might use the command:
2513 "<tt>cp&nbsp;-dpr&nbsp;mymodule&nbsp;/usr/local/src/ircservices/modules/mymodule</tt>"
2514 to copy the files.) Once this is done, you can compile Services as usual
2515 (see <a href="2.html#3">section 2-3</a>), and Services will automatically
2516 recognize the extension module and compile it. When the compilation
2517 completes, the extension module can then be used in exactly the same way as
2518 a built-in module, by adding an appropriate <tt>LoadModule</tt> directive
2519 to the <tt>ircservices.conf</tt> file.
2520
2521 <p align=right><font size="-1"><a href="#top">Back to top</a></font>
2522
2523 <!------------------------------------------------------------------------>
2524 <p><hr>
2525
2526 <p align=right><font size=-1><a href=2.html>Previous section: Installing and using Services</a> |
2527 <a href=index.html>Table of Contents</a> |
2528 <a href=4.html>Next section: Services command reference</a></font>
2529
2530 </body>
2531 </html>