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> 3-1-1. <a href="#1-1">Core NickServ features</a> |
16 |
<br> 3-1-2. <a href="#1-2">Netsplit recovery</a> |
17 |
<br> 3-1-3. <a href="#1-3">Nickname linking</a> |
18 |
<br> 3-1-4. <a href="#1-4">E-mail authentication</a> |
19 |
<br> 3-1-5. <a href="#1-5">Access lists</a> |
20 |
<br> 3-1-6. <a href="#1-6">Miscellaneous functions</a> |
21 |
<br> 3-1-7. <a href="#1-7">Command aliases</a> |
22 |
<br>3-2. <a href="#2">Channel management (ChanServ)</a> |
23 |
<br> 3-2-1. <a href="#2-1">Core ChanServ features</a> |
24 |
<br> 3-2-2. <a href="#2-2">Channel access lists</a> |
25 |
<br> 3-2-3. <a href="#2-3">Channel expiration</a> |
26 |
<br>3-3. <a href="#3">Memo sending (MemoServ)</a> |
27 |
<br> 3-3-1. <a href="#3-1">Core MemoServ features</a> |
28 |
<br> 3-3-2. <a href="#3-2">Memos and channels</a> |
29 |
<br> 3-3-3. <a href="#3-3">Memo ignore lists</a> |
30 |
<br> 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> 3-4-1. <a href="#4-1">Services privilege levels</a> |
33 |
<br> 3-4-2. <a href="#4-2">Core OperServ features</a> |
34 |
<br> 3-4-3. <a href="#4-3">Autokills and S-lines</a> |
35 |
<br> 3-4-4. <a href="#4-4">Session limiting</a> |
36 |
<br> 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> 3-6-1. <a href="#6-1">Core HTTP server module</a> |
40 |
<br> 3-6-2. <a href="#6-2">Authorization modules</a> |
41 |
<br> 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—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—see |
214 |
<a href="#7">section 3-7</a>—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—requiring at least 10-15 megabits/second of |
304 |
bandwidth—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—last seen time, address, name, and quit message—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—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—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—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—<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>—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—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—"K-lines", so named because the lines in the configuration |
1651 |
file defining them begin with the letter "<tt>K</tt>"—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>—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—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—if it did, the servers would block |
1848 |
users on the exclusion list as well without Services being able to |
1849 |
intervene—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—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 / 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 / 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/ </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—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—which includes almost all |
2444 |
messages sent to users, with the exception of a few messages intended for |
2445 |
administrators—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 NickServ 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 -dpr mymodule /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> |