]> git.somenet.org - irc/bugbot.git/blob - INSTALL
some old base
[irc/bugbot.git] / INSTALL
1                        _           _ 
2         m o z i l l a |.| o r g   | | 
3     _ __ ___   ___ ___| |__   ___ | |_ 
4    | '_ ` _ \ / _ \_  / '_ \ / _ \| __|
5    | | | | | | (_) / /| |_) | (_) | |_ 
6    |_| |_| |_|\___/___|_.__/ \___/ \__|
7    ====================================
8
9
10 INSTALLATION
11 ------------
12
13 You will need the following programs and libraries to run mozbot2:
14
15    perl
16    wget
17    Net::IRC
18    Net::SMTP   
19    IO::Select  
20    IO::Pipe    
21
22 These packages may have additional requirements of their own.
23
24 In order to do anything useful with mozbot2, you will need some Bot
25 Modules. Several are included in this distribution, and they may have
26 requirements above and beyond those given above.
27
28 Once you have set up all the packages on which mozbot2 depends, make
29 mozbot.pl executable:
30
31    chmod +x mozbot.pl
32
33 This is needed since mozbot2 will occasionally attempt to restart
34 itself (e.g. if its source code is changed).
35
36 Then, simply run mozbot.pl:
37
38    ./mozbot.pl
39
40 Currently, you MUST run mozbot from the directory in which mozbot.pl
41 is placed. This may be changed in a future version.
42
43
44 SECURITY
45 --------
46
47 Since mozbot interacts with the outside world, do not run it as a
48 privileged user!!!
49
50 In addition, since mozbot calls external programs (currently perl and
51 wget, possibly others in future versions) make sure that none of the
52 directories on your path are writable by untrusted users! (e.g., do
53 not put /tmp into your path!)
54
55 Make sure that '.' is not in your path! This is a security risk in a
56 situation like this, and perl will rightly refuse to execute external
57 programs (like wget, used to get remote URIs for many functions) if
58 '.' is on your path.
59
60 Do not run the bot straight into a public channel on the first run!
61
62 One important reason not to load the bot straight into a public
63 channel on the first run is that until it has been properly
64 configured, it will have a well defined username and password to
65 access all its admin functions. Thus a malicious user could hijack the
66 bot the moment it joined the channel.
67
68 If this is a serious problem for you (e.g., your users are of a
69 particularly high calibre and are doing regular polls of the /who
70 command to see if any bots join) then use another server, such as one
71 that you control, on localhost!
72
73 See the "Administration" section for instructions on how to change the
74 administration password (important!).
75
76 Note: Passwords are printed in clear text on the console and in the
77 log files. Secure them accordingly. Of course, IRC is an inherently
78 insecure protocol anyway, and any machine between your IRC client's
79 and your bot's, going through the IRC network's servers, will have
80 access to the passwords. For this reason, change them often, and don't
81 use passwords that you use for important things here.
82
83 The default setting is for mozbot to run with taint checking
84 enabled. I *STRONGLY* recommend not changing this.
85
86
87 CONFIGURATION
88 -------------
89
90 When you start up mozbot for the first time, it will prompt you for
91 the following information:
92
93    1. IRC server.
94       What machine you want the bot to connect to. At the moment,
95       mozbot only supports connecting to a single server at a time. It
96       would require a *significant* amount of work to change this.
97
98    2. Port. 
99       What port to connect to on the IRC server. Typically, this will
100       be 6667 or therabouts.
101
102    3. Password.
103       If your server has a password, enter it here. If there isn't one
104       (and this is almost certainly the case) then just hit enter.
105
106    4. Channels.
107       What channels the bot should initially connect to. It is
108       recommended that this just be a bot channel or a test channel,
109       for example #mozbot, since running a bot for the first time
110       before it is known to be ready is a bad idea. You can enter more
111       than one channel, just hit enter after each one (leave a blank
112       line when you have finished). (To make mozbot join a keyed
113       channel, you must first add the channel's key to the
114       'channelKeys' variable. To do this, the bot will have to be on
115       IRC first, so don't worry about it for now.)
116
117    5. Your e-mail address.
118       In case of great difficulties, mozbot may try to e-mail you. If
119       this happens, it will use the e-mail address you gave here. This
120       only happens if (a) it absolutely cannot connect to the server
121       you gave it, or (b) it cannot find a nick that is not in use.
122
123    6. SMTP server. 
124       The name of the SMTP server it should try to talk with in order
125       to send you mail. If you type in an invalid server name, it will
126       just fail to send mail and instead will complain bitterly to its
127       console.
128
129    7. Nicks.
130       Some nicks for IRC. For example, 'mozbot'. It is customary to
131       clearly mark the bot as being non-human, for example by putting
132       'bot' in the name. You should enter several possibilities
133       here. Hit enter after each one. Leave a blank line to finish.
134
135 Once the bot is running, there are many other things that can be
136 configured with it. See "variables".
137
138 Note. The bot will treat all channel names as lowercase to avoid case
139 sensitivity issues.
140
141
142 LOGGING
143 -------
144
145 Normally, mozbot will output its complaints to the console
146 (stdout). If you run mozbot in an xterm or screen session, you can
147 therefore easily keep track of what is going on.
148
149 It will also continuously log output to ~/logs/$0.$$.log, where $0 is
150 the file name and $$ is the PID. You may wish to set up a cron job to
151 prune this file on a regular basis, it gets LARGE. However, it can
152 sometimes be the only way to track down how your system was
153 compromised if it turns out that mozbot has a security flaw.
154
155 Control over the logging is currently not available. This may change
156 in future versions.
157
158 Note that when the bot forks and then outputs a message, which happens
159 occasionally, it will therefore use a new log file for the forked
160 process. This should only happen when something bad happens,
161 e.g. something forces the bot to restart or the bot forks and then the
162 child enters a bad state.
163
164 Note. Authentication passwords will be displayed in cleartext on the
165 console and in the log files.
166
167
168 ADMINISTRATION
169 --------------
170
171 Once the bot is active and on the IRC server, it starts to listen to
172 all messages seen on any channels on which it is present, and all
173 messages sent to it using /msg.
174
175 Your first task should be to change the admin password. To do this,
176 authenticate yourself using the "auth" command. The default username
177 is "admin", and the default password is "password". If the bot is
178 called "mozbot", then the command to authenticate would be as follows:
179
180    /msg mozbot auth admin password
181
182 The bot should respond with "Hi admin!".
183
184 Now create yourself an account by adding a username/password pair to
185 the bot. You do this with the "newuser" command. Next, you should
186 bless this new user, making it a bot administrator. This is done using
187 these commands:
188
189    /msg mozbot newuser <username> <password> <password>
190    /msg mozbot bless <username>
191
192 Now authenticate yourself again, as the new user:
193
194    /msg mozbot auth <username> <password>
195
196 The moment you authenticate as the new admin, the default admin
197 account is deleted.
198
199 You are now in a position to add the modules you want and to put the
200 bot in the channels you want it in.
201
202 To load modules is easy.
203
204    /msg mozbot load module
205
206 ...where "module" is a module name, such as "HelloWorld" (note that
207 the ".bm" extension is not included). By default, the General,
208 Greeting, Infobot and Parrot modules are loaded. The General module
209 provides the 'help' command and responds to CTCP VERSION messages. The
210 Greeting module responds to greetings and generally tries to be
211 friendly. The Infobot module provides information storage and
212 retrieval functions. The Parrot module lets an admin control the bot
213 much like a puppet.
214
215 By default, modules will be enabled in all channels. See the
216 "variables" section below to change this.
217
218
219 HINTS
220 -----
221
222 If the bot goes mad and starts flooding a channel -- e.g., if someone
223 keeps asking it for information -- then authenticate and then send it
224 the following message:
225
226    /msg mozbot shutup please
227
228 It should respond within a few seconds. You can authenticate while it
229 is speaking, that's not a problem.
230
231
232 VARIABLES
233 ---------
234
235 For information on changing variables on the fly, use the "vars"
236 command:
237
238    /msg mozbot vars
239
240 Each module has several variables that you can change. You can see
241 what they are by typing:
242
243    /msg mozbot vars module
244
245 ...where module is the module in question. These always include
246 "Admin" and "General". Admin provides the commands such as "auth",
247 "newuser", "password", and provides additional commands to admins,
248 such as "shutdown", "cycle", "leave", "restart", and so on. "General"
249 provides the "help" command to everyone.
250
251 The main variables are:
252
253    channels -- which channels the module should listen in, and which
254    channels the module should send announcements to. Must be in
255    lowercase!
256
257    channelKeys -- a mapping of (lowercase) channel names to keys. It
258    is assumed that any channel without an entry in this variable has
259    no key. For example, to tell mozbot that the key for channel
260    #channel is 'password', you would use:
261
262       /msg mozbot vars Admin channelKeys '+|#channel|password'
263
264    autojoin -- whether (1) or not (0) the module should automatically
265    add a new channel to its "channels" list when the bot joins a new
266    channel. If this is not enabled, then you will have to add new
267    channels to the "channels" list of this module each time.
268
269    channelsBlocked -- channels that will not be autojoined, so if a
270    module has been disabled, it won't rejoin the channel if the bot is
271    kicked then reinvited.
272
273    denyusers -- user@host regexp masks of users that should be
274    completely ignored (for this module). The regexp will be placed
275    between "^" and "$" modifiers, so do not include them, and *do*
276    include everything required to make the whole user@host mask match.
277
278    allowusers -- identical in usage to denyusers, but checked first to
279    override it. So to give access to everyone but a few people, leave
280    allowusers blank and add some masks to denyusers, but to give
281    access to only a few people, add their user@host masks to
282    allowusers, and add ".*" to denyusers.
283
284 In addition, other modules may have extra variables.
285
286 The admin variable has quite a few variables, including all those that
287 are prompted for during initial startup. The interesting ones are:
288
289    currentnick -- the nick. This can be changed on the fly.
290
291    server, port, password -- the server and port to connect to, and
292    the server password to use. If you change these and then cycle the
293    bot (/msg mozbot cycle) then the bot will change servers without
294    shutting down.
295
296    localAddr -- if you don't seem to be able to establish a
297    connection, but it works fine with other software, then you should
298    try setting the localAddr variable to your IP address. Technically,
299    this variable sets which interface to use to form the outgoing
300    connection. (This is to work around a limitation of Net::IRC.) 
301    Typically you would set this variable directly in the configuration
302    file, by adding a line that says "localAddr=10.11.12.13" or
303    whatever your IP address is.
304
305    simpleIRCNameServer -- if the value of this variable equals the
306    name of the server, then the IRC Name sent to the server will be
307    simplified so that it doesn't include the URI of the mozbot help
308    files. This is usually dealt with automatically, but if you are
309    having troubles connecting, you could try setting it. (It is set to
310    the name of the server so that if you change servers, by default
311    mozbot will use a complete IRC Name again.)
312
313    username -- if this variable has a true value, then the bot will
314    use its value as its IRC username. By default, the bot uses
315    "pid-1234" as the username, where "1234" is the bot's process ID. 
316    This can cause problems on networks or with BNCs that require a
317    valid and accurate ident, in which case this variable can provide a
318    solution. (You can also set this variable by entering
319    "username=blah" into the configuration file, where blah is the
320    username you want to use.)
321
322    channels -- unlike other modules, the channels variable for the
323    Admin module actually controls which channels the bot itself
324    appears in. The preferred method for controlling this is using
325    /invite and /kick or "join" and "part", though (since editing the
326    list directly will probably require a cycle of the bot to take
327    effect).
328
329    admins -- the administrators. See "Administration" above.
330
331    allowInviting -- this controls whether the /invite IRC command will
332    be obeyed or not.
333
334    allowChannelAdmin -- this controls whether or not the bot will
335    accept admin commands that are given in a channel or not. In any
336    case, the "auth" command is never accepted in a channel.
337
338    files -- this is a list of files whose timestamps are monitored to
339    decide if the source code has changed. If it is established that
340    any of these files have changed while the bot is running, then the
341    bot will shutdown and restart itself. Modules are dealt with
342    separately, and need not be listed here. (And when modules change,
343    the whole bot is not restarted, only the module.)
344
345    sourceCodeCheckDelay -- number of seconds between checks of the bot
346    and module sources. Note that changes will only take effect after
347    the previous timer has passed, so changing it from 3600 (an hour)
348    to 10 (10 seconds) may not be of much immediate use. In these
349    cases, setting the variable to the new value then cycling the bot
350    is a good plan.
351
352    ignoredUsers -- a list of regular expressions that are matched
353    against the user@host strings of everything that is said. If a user
354    matches one of the entires in this list, then that user will be
355    completely ignored. (^ and $ symbols are implied at the start and
356    end of this regular expression.) Use this sparingly. It will stop
357    the user's statements from having _any_ effect on the bot,
358    including in any statistic-collecting modules, etc. If you just
359    want to block a user from certain modules, add a regular expression
360    to the 'denyusers' variable of those modules.
361    Example:
362       >mozbot< vars Admin ignoredUsers '+root@.*'
363       *** moron (root@example.org) has joined #mozbot
364       <moron> mozbot: help
365       * you watch the tumbleweed roll on by
366
367    ignoredTargets -- when someone says something to someone who
368    matches one of the regular expressions in this list, the line will
369    be ignored as if the person saying it was banned with ignoreUsers. 
370    This is useful when you have other bots in the channel, and don't
371    want the mozbot to respond in place of the other bots (e.g. with an
372    auto-helping Infobot module). Note: It is safe to user a regular
373    expression that matches the mozbot bot's name; it will always
374    respond to messages to itself (as well as messages that are sent
375    via /msg) irrespective of this setting.
376    Example:
377       <user> foobot: what is green?
378       <foobot> user: green is good.
379       <mozbot> user: green is good.
380       <user> mozbot: vars Admin ignoredTargets '+.*bot[0-9]*'
381       <mozbot> Variable 'ignoredTargets' in module 'Admin' has changed.
382       <user> foobot: what is green?
383       <foobot> user: green is good.
384       * user patpats mozbot
385
386 Changes to variables are usually immediately recorded in the
387 configuration file and will be saved for the next time the bot is
388 loaded.
389
390 There are three types of editable variables: scalars, arrays of
391 scalars, and hashes of scalars.
392
393 Scalars are easy, and lists are explained by the bot quite well, just
394 try to set a list and it will tell you if you are doing something
395 wrong!
396
397 To add a value to a hash, there is a more complex syntax. For example,
398 to add a new site to the list of sites that the RDF module monitors,
399 use the following command:
400
401    /msg mozbot vars RDF sites '+|slashdot|http://slashdot.org/slashdot.rdf'
402
403 First, note that the value is surrounded by quotes.  You can nest
404 quotes without any problems, the quotes are just needed to
405 differentiate significant trailing whitespace from mistakes.
406
407 The "+" means you want to add a value to the hash (as you'll see in a
408 minute, to remove an item you use "-"). Then, since a hash is a
409 key/value pair, you have to delimit the two. In this case, we have
410 used "|" as a delimiter. However, you could use anything.  The first
411 occurance tells mozbot what delimiter you have picked.  The second
412 separates the key (in this case the site nickname) from the value (in
413 this case the URI). For example:
414
415    /msg mozbot vars RDF sites '+*key*value'
416
417 You could even use a letter as a delimiter, but since that is usually
418 a sign that you have forgotten to declare which delimiter you are
419 using, mozbot will warn you about this. For example (the 'users' hash,
420 BTW, is the hash in which all the username/password pairs are kept):
421
422    /msg mozbot vars Admin users '+sarah|lisa'
423
424 ...will be treated the same as:
425
426    /msg mozbot vars Admin users '+*arah|li*a'
427
428 ..., i.e. the username added would be "arah|li" and the password would
429 be "a". This is not a bug, it's a feature. It means you can include
430 any character, including "'", "|", and so on, in the key, without fear
431 of it being interpreted as a delimiter.
432
433 To remove a user, or any key/value pair in a hash, you use this
434 syntax:
435
436    /msg mozbot vars Admin users '-admin'
437
438 That's it. No need to say what the value is, since each key in a hash
439 has to be unique. (Although, in this particular case, it should be
440 noted that the preferred way to remove users is actually the
441 'deleteuser' command.)
442
443 -- end --