-
Notifications
You must be signed in to change notification settings - Fork 3
/
README
572 lines (420 loc) · 16.8 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
Please note that this code is largely abandoned.
----
Perlbot / http://www.perlbot.org
An IRC bot written in perl.
Authors: Andrew Burke and Jeremy Muhlich
aburke@bitflood.org / jmuhlich@bitflood.org
======================================================
WARNING!: DO NOT RUN AS ROOT. We have seen people around the net run
perlbot as root. This is ill advised. Although the perlbot core
*should* be fairly secure, we make no claims as to its actual level
of security. In addition, every plugin you run is a potential security
risk. Please do NOT run this as root.
NOTE: When we use an expression like <version> or <botnick>, that
means you should substitute your perlbot version or your bot's nick or
whatever is inside the angle brackets, WITHOUT the actual angle
brackets. So perlbot-<version> would mean perlbot-1.2.0 if you're
running version 1.2.0 .
Table of Contents
-----------------
1) Requirements
2) Installation
2a) Upgrading from 1.x to 2.x
3) Settings
4) Using It
5) Debugging
6) Mailing List
7) Miscellaneous Stuff
(including how to make perlbot work on non-unix systems)
=======================================================================
1.0 Requirements
================
- Net::IRC (http://www.perl.com/CPAN/modules/by-module/Net/)
-> Make sure you check back there periodically for new versions. This
package is still sort of in development, and we're not afraid to
make use of features in the newest version. Bugfixes here are
important too.
- XML::Simple (http://www.cpan.org/modules/by-module/XML/)
- Plugins may have their own requirements, and we trust plugin authors
to put that in their documentation.
- Optional, but recommended:
Algorithm::MarkovChain (For the Outlander plugin)
Calendar::Simple (For the Cal plugin)
Date::Manip (Misc modules use this)
HTML::CalendarMonth (Used by the LogServer plugin)
HTML::TableExtract (Used by some web plugins)
HTTP::Daemon (Used by the integrated webserver)
LWP::Simple (Many web plugins use this module)
Net::DNS (For the Host plugin)
Net::Google (For the Google and SpelCheck plugins)
String::Approx (Used by the Trivia plugin)
Weather::Underground (For the Weather plugin)
WWW::Babelfish (For the Babelfish plugin)
2.0 Installation
================
For personal use, you should simply be able to expand the archive in
your home directory:
tar zxvf perlbot-<version>.tar.gz
System-wide use isn't possible just yet, but we're working towards
that in future versions.
However, some work has been done to allow you to run multiple perlbots
from a machine if you have root access. If you create a 'perlbot' user
whose home directory is '/home/perlbot', you can add new bots under that
directory, for instance: '/home/perlbot/logbot' would contain a perlbot
tree. You can then copy the file 'perlbot.initscript' to
/etc/rc.d/init.d/logbot and run 'chkconfig --add logbot' (for RedHat-based
Linux distros only; make the symlinks by hand otherwise) to have the logbot
start at boot. You can also use this script to stop/start the bot
manually by passing it the parameter 'start' or 'stop'. This is currently
experimental, and you probably shouldn't play with it unless you know what
you're doing. (it's also a pretty poor hack :)
2.0a Upgrading from 1.x to 2.x
==============================
Perlbot 2.0 is a significant revision of almost every aspect of the bot.
As such, upgrading isn't trivial. Perlbot 2.0 uses XML as the format for
storing its config file. This allows us much greater flexibility as
developers and opens the door to all kinds of inter-bot communication.
Under the miscscripts directory, you will find a script called: convertconfig
It takes a perlbot 1.x config file as its argument and prints out an XML
version of it. (With some caveats)
Example:
convertconfig config > config.xml
Would convert the perlbot 1.x config in 'config' to XML and write it to
'config.xml'. This will bring over a great deal of the configuration
you've done for your 1.x bot, hopefully saving you some time.
**You still need to look over the generated XML and make some minor
changes.**
- Any channel flags you specified in your 1.x configuration will be gone.
They should be respecified ala the instructions below.
- Your plugindir specifications will almost certainly need to be corrected.
- Pluginprefix will be gone, it has been unified with commandprefix.
3.0 Settings
============
You should create and edit perlbot-<version>/config.xml to suit your
needs. This file is XML and uses XML syntax. The provided
config-sample.xml should be a good place to start.
3.1 bot
--------
This class holds settings that pertain to the bot itself, such as its
IRC nick and directories for logfiles and plugins. There must be only
ONE bot object in your config file!
nick
- Specify a nick that the bot will try to use.
Example:
<bot nick="perlbot" />
logdir
- This sets the directory that the bot will use for logs,
which defaults to "./logs" if it is not set. A good
way to set this up to keep logs independent of perlbot
version is to set it to "../logs" or some other directory
external to the perlbot tree.
Example:
<bot nick="perlbot"
logdir="../logs" />
defaultlogtype
- This sets the default type of logging for a channel to
use. It normally defaults to 'Files', which are separate
log files per day. Another example would be 'SingleFile'
which stores all your logs for a given channel in a file
named channelname.log.
Example:
<bot nick="perlbot"
defaultlogtype="SingleFile" />
plugindir
- This sets the directories in which the bot will look
for plugins. (You should almost definitely specify
Plugins/Core and Plugins/Basic to get any useful
action out of your perlbot)
Example:
<bot nick="perlbot"
logdir="../logs>
...
<plugindir>Plugins/Core</plugindir>
<plugindir>Plugins/Basic</plugindir>
<plugindir>Plugins/Misc</plugindir>
...
</bot>
noload
- This tells the bot not to load certain plugins.
Example:
<bot nick="perlbot"
logdir="../logs">
...
<noload>Weather</noload>
<noload>Seen</noload>
...
</bot>
admin
- This specifies which users (See section 3.3) are to be
considered bot administrators. This gives them the power
to control the bot. You will most likely want to make
at least yourself an admin. Be careful who you make an
admin.
Example:
<bot nick="perlbot"
logdir="../logs">
...
<admin>billy</admin>
<admin>tommy</admin>
...
</bot>
nickappend
- This specifies the character to append to the end of
the bot's nick when it cannot obtain its specified
nick. Defaults to '_'.
Example:
<bot nick="perlbot"
logdir="../logs"
nickappend="_">
...
...
</bot>
ircname
- This sets the bot's ircname. Some IRC networks require
that all bots are identified as such in either their
nick or ircname. So putting "bot" somewhere in the
ircname would be a good idea on these nets. The default
is "imabot".
Example:
<bot nick="perlbot"
logdir="../logs"
nickappend="_"
ircname="imabot">
...
...
</bot>
commandprefix
- This is a character that will preface all the bot's
commands. This has no default and must be set or the
bot will respond without any kind of prefix.
Example:
<bot nick="perlbot"
logdir="../logs"
nickappend="_"
ircname="imabot"
commandprefix="!">
...
...
</bot>
crashlogdir
- This is the directory to which crash logs will be written.
When something goes wrong and the bot crashes unexpectedly,
a perl stack trace will be dumped to "crashlog.txt" in this
directory, along with the error message from the crash.
The default is "." (the current directory, i.e. your perlbot
directory).
Example:
<bot nick="perlbot"
logdir="../logs"
nickappend="_"
ircname="imabot"
commandprefix="!"
crashlogdir=".">
...
...
</bot>
localaddr
- This will set the hostname to which Net::IRC will attempt
to bind. If you have multiple network interfaces in your
computer, you should set this to the ip or hostname of the
one you wish your bot to connect from. It is safe in most
cases to leave this option out.
Example:
<bot nick="perlbot"
localaddr="somehost.example.com">
...
...
</bot>
username
- This allows you to set the username that will be displayed
on irc on machines not running ident. Ie, if normally the
bot appears as ~you@someplace.com, but setting the username
to blahblah, it would appear as ~blahblah@someplace.com
Example:
<bot nick="perlbot"
username="blahblah">
...
...
</bot>
ignore
- Causes the bot to ignore someone.
Example:
<bot nick="perlbot">
<ignore>*!*someone@*.someplace.com</ignore>
...
</bot>
3.2 server
-----------
Each server object represents an IRC server that you want your perlbot
to use. You should specify several servers, so that if your bot loses
its connection to one, it can roll over to another and stay on IRC. You
must have at least one server object or perlbot will print an error and
refuse to start.
address
- This sets the address of the server, it can be an IP
address or a domain name. (1.2.3.4 or irc.example.com)
Example:
<server address="irc.example.com" />
port
- This sets the port that the bot will try to connect to
the server on. The default is 6667.
Example:
<server address="irc.example.com" port="6667" />
password
- This sets the server password if your server requires authentication.
Example:
<server address="irc.example.com" port="6667" password="secret" />
ssl
- This toggles the use of Net::IRC's SSL support for connecting to
secure servers. (Note: Net::IRC 0.74+ required)
Example:
<server address="irc.example.com" port="36901" ssl="1" />
3.3 user
---------
Each user object represents one person that you want your perlbot to
recognize on IRC.
name
- This sets the unique name that the bot and other users
will use to refer to that user. It would ideally be
the same as the user's usual IRC nick, perhaps without
extra punctuation like trailing _ or ` characters.
Example:
<user name="billy" />
hostmask
- This sets a hostmask for the user, which is how they
are recognized. Be mindful of your users' hostmasks,
they can easily allow the wrong person to access the
bot as that user if not configured correctly. There
can be any number of these specified. The bot may
refuse to add certain hostmasks if they are deemed
insecure.
Example:
<user name="billy">
...
<hostmask>*!*billy@*.billy.com</hostmask>
<hostmask>*!*billy@*.funtimes.com</hostmask>
...
</user>
password
- Allows users to authenticate themselves when not
connected via a hostmask specified in the config file.
Look in miscscripts/ for the perlbotpasswd script to
help you generate user passwords.
Example:
<user name="billy"
password="lakLKJAS./ASD">
<hostmask>*!*billy@*.billy.com</hostmask>
</user>
3.4 channel
------------
name
- The name of the channel. If the leading # or & character
is omitted, perlbot will assume # .
Example:
<channel name="#perlbot" />
key
- The channel key (only needed if the channel has a key).
Example:
<channel name="#perlbot"
key="secret" />
flags
- This sets the channel flags, such as +snt etc.
Example:
<channel name="#perlbot"
flags="-s+tn" />
logging
- Turns logging on or off for the channel. Takes "yes" or
"no" (which mean "logging on" and "logging off", respectively).
The default is "no"! If perlbot is not logging your channel,
make sure logging is set to "yes".
Example:
<channel name="#perlbot"
flags="-s+tn"
logging="yes" />
logtype
- Tells the bot how to store logs. Will use one of the modules
under Perlbot/Logs. It defaults to the bot.defaultlogtype, or
if that it not set, 'Files'. The 'Files' type of logging
will split your logs into a single file for each day. Another
example would be 'SingleFile' which would store all your logs
in a single file named channelname.log.
Example:
<channel name="#perlbot"
logging="yes"
logtype="SingleFile" />
op
- This sets a user to be an op for the channel. It expects
the name field from their user object.
Example:
<channel name="#perlbot">
<op>billy</op>
<op>timmy</op>
</channel>
limit
- This sets the maximum number of users in the channel.
The default is 0 which means there is no limit.
(this setting is not currently implemented/enforced)
Example:
<channel name="#perlbot"
limit="100" />
3.5 webserver
-------------
host
- This sets the hostname to bind the integrated webserver to. It
defaults to binding to all interfaces.
Example:
<webserver host="www.example.com" />
port
- This is the port the integrated webserver will bind to. It
defaults to 9090.
Example:
<webserver host="www.example.com" port="9000" />
enabled
- This option allows you to disable the webserver. A value
other than 'no' or '0' will enable the webserver. If this
key is absent, the webserver is ENABLED by default.
Example:
<webserver host="www.example.com" port="9000" enabled="no" />
4.0 Using It
============
4.1 What now?
--------------
So you have this shiny new perlbot, all configured, and you want to know
what you can do with it. The basic bot functionality already has online
documentation. Simply msg the bot "<commandprefix>help" and you'll get
information on how to use the online help facility.
4.2 How do I freakin' run this thing?
--------------------------------------
4.2.1 I'm the bot admin
------------------------
The commands you'll most often use are probably join, and quit.
They join channels and quit the bot, respectively. Message the
bot:
<commandprefix>help
for more information.
4.2.2 I'm a user
-----------------
The commands you'll most often use are auth, password, addhost,
and the note-related commands. Message the bot:
<commandprefix>help Authentication
for more information.
4.2.3 I need more help!
------------------------
Check the FAQ included with perlbot. If you still need more help, try
contacting the authors.
5.0 Debugging
=============
If you have major problems, please set the environment variable
PERLBOT_DEBUG to 1. Then, run:
./perlbot.pl > pblog.txt
Now make the problem occur again, and then attach pblog.txt and
crashlog.txt (see "crashlogdir" under section 3.1 above) to
a github issue.
7.0 Miscellaneous Stuff
=======================
7.1 How to make perlbot work under win32 (Windows 9x / NT / 2000):
-------------------------------------------------------------------
Let us know if you have experience with getting 2.x to work.
7.2 How to make perlbot work under MacOS:
------------------------------------------
Let us know if you have experience with getting 2.x to work.