mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-05 20:15:58 +00:00
369 lines
13 KiB
Plaintext
369 lines
13 KiB
Plaintext
_ _
|
|
m o z i l l a |.| o r g | |
|
|
_ __ ___ ___ ___| |__ ___ | |_
|
|
| '_ ` _ \ / _ \_ / '_ \ / _ \| __|
|
|
| | | | | | (_) / /| |_) | (_) | |_
|
|
|_| |_| |_|\___/___|_.__/ \___/ \__|
|
|
====================================
|
|
|
|
|
|
INSTALLATION
|
|
------------
|
|
|
|
You will need the following programs and libraries to run mozbot2:
|
|
|
|
perl
|
|
wget
|
|
Net::IRC
|
|
Net::SMTP
|
|
IO::Select
|
|
IO::Pipe
|
|
|
|
These packages may have additional requirements of their own.
|
|
|
|
In order to do anything useful with mozbot2, you will need some Bot
|
|
Modules. Several are included in this distribution, and they may have
|
|
requirements above and beyond those given above.
|
|
|
|
Once you have set up all the packages on which mozbot2 depends, make
|
|
mozbot.pl executable:
|
|
|
|
chmod +x mozbot.pl
|
|
|
|
This is needed since mozbot2 will occasionally attempt to restart
|
|
itself (e.g. if its source code is changed).
|
|
|
|
Then, simply run mozbot.pl:
|
|
|
|
./mozbot.pl
|
|
|
|
Currently, you MUST run mozbot from the directory in which mozbot.pl
|
|
is placed. This may be changed in a future version.
|
|
|
|
|
|
SECURITY
|
|
--------
|
|
|
|
Since mozbot interacts with the outside world, do not run it as a
|
|
privileged user!!!
|
|
|
|
In addition, since mozbot calls external programs (currently perl and
|
|
wget, possibly others in future versions) make sure that none of the
|
|
directories on your path are writable by untrusted users! (e.g., do
|
|
not put /tmp into your path!)
|
|
|
|
Make sure that '.' is not in your path! This is a security risk in a
|
|
situation like this, and perl will rightly refuse to execute external
|
|
programs (like wget, used to get remote URIs for many functions) if
|
|
'.' is on your path.
|
|
|
|
Do not run the bot straight into a public channel on the first run!
|
|
|
|
One important reason not to load the bot straight into a public
|
|
channel on the first run is that until it has been properly
|
|
configured, it will have a well defined username and password to
|
|
access all its admin functions. Thus a malicious user could hijack the
|
|
bot the moment it joined the channel.
|
|
|
|
If this is a serious problem for you (e.g., your users are of a
|
|
particularly high calibre and are doing regular polls of the /who
|
|
command to see if any bots join) then use another server, such as one
|
|
that you control, on localhost!
|
|
|
|
See the "Administration" section for instructions on how to change the
|
|
administration password (important!).
|
|
|
|
Note: Passwords are printed in clear text on the console and in the
|
|
log files. Secure them accordingly. Of course, IRC is an inherently
|
|
insecure protocol anyway, and any machine between your IRC client's
|
|
and your bot's, going through the IRC network's servers, will have
|
|
access to the passwords. For this reason, change them often, and don't
|
|
use passwords that you use for important things here.
|
|
|
|
The default setting is for mozbot to run with taint checking
|
|
enabled. I *STRONGLY* recommend not changing this.
|
|
|
|
|
|
CONFIGURATION
|
|
-------------
|
|
|
|
When you start up mozbot for the first time, it will prompt you for
|
|
the following information:
|
|
|
|
1. IRC server.
|
|
What machine you want the bot to connect to. At the moment,
|
|
mozbot only supports connecting to a single server at a time. It
|
|
would require a *significant* amount of work to change this.
|
|
|
|
2. Port.
|
|
What port to connect to on the IRC server. Typically, this will
|
|
be 6667 or therabouts.
|
|
|
|
3. Channels.
|
|
|
|
What channels the bot should initially connect to. It is
|
|
recommended that this just be a bot channel or a test channel,
|
|
for example #mozbot, since running a bot for the first time
|
|
before it is known to be ready is a bad idea. You can enter more
|
|
than one channel, just hit enter after each one (leave a blank
|
|
line when you have finished). (To make oopsbot join a keyed
|
|
channel, you must first add the channel's key to the
|
|
'channelKeys' variable. To do this, the bot will have to be on
|
|
IRC first, so don't worry about it for now.)
|
|
|
|
4. Your e-mail address.
|
|
In case of great difficulties, mozbot may try to e-mail you. If
|
|
this happens, it will use the e-mail address you gave here. This
|
|
only happens if (a) it absolutely cannot connect to the server
|
|
you gave it, or (b) it cannot find a nick that is not in use.
|
|
|
|
5. SMTP server.
|
|
The name of the SMTP server it should try to talk with in order
|
|
to send you mail. If you type in an invalid server name, it will
|
|
just fail to send mail and instead will complain bitterly to its
|
|
console.
|
|
|
|
6. Nicks.
|
|
Some nicks for IRC. For example, 'mozbot'. It is customary to
|
|
clearly mark the bot as being non-human, for example by putting
|
|
'bot' in the name. You should enter several possibilities
|
|
here. Hit enter after each one. Leave a blank line to finish.
|
|
|
|
Once the bot is running, there are many other things that can be
|
|
configured with it. See "variables".
|
|
|
|
Note. The bot will treat all channel names as lowercase to avoid case
|
|
sensitivity issues.
|
|
|
|
|
|
LOGGING
|
|
-------
|
|
|
|
Normally, mozbot will output its complaints to the console
|
|
(stdout). If you run mozbot in an xterm or screen session, you can
|
|
therefore easily keep track of what is going on.
|
|
|
|
It will also continuously log output to ~/logs/$0.$$.log, where $0 is
|
|
the file name and $$ is the PID. You may wish to set up a cron job to
|
|
prune this file on a regular basis, it gets LARGE. However, it can
|
|
sometimes be the only way to track down how your system was
|
|
compromised if it turns out that mozbot has a security flaw.
|
|
|
|
Control over the logging is currently not available. This may change
|
|
in future versions.
|
|
|
|
Note that when the bot forks and then outputs a message, which happens
|
|
occasionally, it will therefore use a new log file for the forked
|
|
process. This should only happen when something bad happens,
|
|
e.g. something forces the bot to restart or the bot forks and then the
|
|
child enters a bad state.
|
|
|
|
Note. Authentication passwords will be displayed in cleartext on the
|
|
console and in the log files.
|
|
|
|
|
|
ADMINISTRATION
|
|
--------------
|
|
|
|
Once the bot is active and on the IRC server, it starts to listen to
|
|
all messages seen on any channels on which it is present, and all
|
|
messages sent to it using /msg.
|
|
|
|
Your first task should be to change the admin password. To do this,
|
|
authenticate yourself using the "auth" command. The default username
|
|
is "admin", and the default password is "password". If the bot is
|
|
called "mozbot", then the command to authenticate would be as follows:
|
|
|
|
/msg mozbot auth admin password
|
|
|
|
The bot should respond with "Hi admin!".
|
|
|
|
Now create yourself an account by adding a username/password pair to
|
|
the bot. You do this with the "newuser" command. Next, you should
|
|
bless this new user, making it a bot administrator. This is done using
|
|
these commands:
|
|
|
|
/msg mozbot newuser <username> <password> <password>
|
|
/msg mozbot bless <username>
|
|
|
|
Now authenticate yourself again, as the new user:
|
|
|
|
/msg mozbot auth <username> <password>
|
|
|
|
The moment you authenticate as the new admin, the default admin
|
|
account is deleted.
|
|
|
|
You are now in a position to add the modules you want and to put the
|
|
bot in the channels you want it in.
|
|
|
|
To load modules is easy.
|
|
|
|
/msg mozbot load module
|
|
|
|
...where "module" is a module name, such as "HelloWorld" (note that
|
|
the ".bm" extension is not included).
|
|
|
|
By default, modules will be enabled in all channels. See the
|
|
"variables" section below to change this.
|
|
|
|
|
|
HINTS
|
|
-----
|
|
|
|
If the bot goes mad and starts flooding a channel -- e.g., if someone
|
|
keeps asking it for information -- then authenticate and then send it
|
|
the following message:
|
|
|
|
/msg mozbot shutup please
|
|
|
|
It should respond within a few seconds. You can authenticate while it
|
|
is speaking, that's not a problem.
|
|
|
|
|
|
VARIABLES
|
|
---------
|
|
|
|
For information on changing variables on the fly, use the "vars"
|
|
command:
|
|
|
|
/msg mozbot vars
|
|
|
|
Each module has several variables that you can change. You can see
|
|
what they are by typing:
|
|
|
|
/msg mozbot vars module
|
|
|
|
...where module is the module in question. These always include
|
|
"Admin" and "General". Admin is only available to authenticated users,
|
|
and provides the commands such as "shutdown", "cycle", "leave",
|
|
"password", and so on. "General" provides the "help" command to
|
|
everyone.
|
|
|
|
The main variables are:
|
|
|
|
channels -- which channels the module should listen in, and which
|
|
channels the module should send announcements to. Must be in
|
|
lowercase!
|
|
|
|
channelKeys -- a mapping of (lowercase) channel names to keys. It
|
|
is assumed that any channel without an entry in this variable has
|
|
no key.
|
|
|
|
autojoin -- whether (1) or not (0) the module should automatically
|
|
add a new channel to its "channels" list when the bot joins a new
|
|
channel. If this is not enabled, then you will have to add new
|
|
channels to the "channels" list each time.
|
|
|
|
channelsBlocked -- channels that will not be autojoined, so if the
|
|
module has been disabled, it won't rejoin the channel if it is
|
|
kicked then reinvited.
|
|
|
|
denyusers -- user@host regexp masks of users that should be
|
|
completely ignored. The regexp will be placed between "^" and "$"
|
|
modifiers, so do not include them, and *do* include everything
|
|
required to make the whole user@host mask match.
|
|
|
|
allowusers -- identical in usage to denyusers, but checked first to
|
|
override it. So to give access to everyone but a few people, leave
|
|
allowusers blank and add some masks to denyusers, but to give
|
|
access to only a few people, add their user@host masks to
|
|
allowusers, and add ".*" to denyusers.
|
|
|
|
In addition, other modules may have extra variables.
|
|
|
|
The admin variable has quite a few variables, including all those that
|
|
are prompted for during initial startup. The interesting ones are:
|
|
|
|
currentnick -- the nick. This can be changed on the fly.
|
|
|
|
server, port -- the server and port to connect to. If you change
|
|
these and then cycle the bot (/msg mozbot cycle) then the bot will
|
|
change servers without shutting down.
|
|
|
|
channels -- unlike other modules, the channels variable for the
|
|
Admin module actually controls which channels the bot itself
|
|
appears in. The preferred method for controlling this is using
|
|
/invite and /kick or "go" and "leave", though (since editing the
|
|
list directly will probably require a cycle of the bot to take
|
|
effect).
|
|
|
|
admins -- the administrators. See "Administration" above.
|
|
|
|
allowInviting -- this controls whether the /invite IRC command will
|
|
be obeyed or not.
|
|
|
|
allowChannelAdmin -- this controls whether or not the bot will
|
|
accept admin commands that are given in a channel or not. In any
|
|
case, the "auth" command is never accepted in a channel.
|
|
|
|
files -- this is a list of files whose timestamps are monitored to
|
|
decide if the source code has changed. If it is established that
|
|
any of these files have changed while the bot is running, then the
|
|
bot will shutdown and restart itself. Modules are dealt with
|
|
separately, and need not be listed here. (And when modules change,
|
|
the whole bot is not restarted, only the module.)
|
|
|
|
sourceCodeCheckDelay -- number of seconds between checks of the bot
|
|
and module sources. Note that changes will only take effect after
|
|
the previous timer has passed, so changing it from 3600 (an hour)
|
|
to 10 (10 seconds) may not be of much immediate use. In these
|
|
cases, setting the variable to the new value then cycling the bot
|
|
is a good plan.
|
|
|
|
Changes to variables are usually immediately recorded in the
|
|
configuration file and will be saved for the next time the bot is
|
|
loaded.
|
|
|
|
There are three types of editable variables: scalars, arrays of
|
|
scalars, and hashes of scalars.
|
|
|
|
Scalars are easy, and lists are explained by the bot quite well, just
|
|
try to set a list and it will tell you if you are doing something
|
|
wrong!
|
|
|
|
To add a value to a hash, there is a more complex syntax. For example,
|
|
to add a new site to the list of sites that the RDF module monitors,
|
|
use the following command:
|
|
|
|
/msg mozbot vars RDF sites '+|slashdot|http://slashdot.org/slashdot.rdf'
|
|
|
|
First, note that the value is surrounded by quotes. You can nest
|
|
quotes without any problems, the quotes are just needed to
|
|
differentiate significant trailing whitespace from mistakes.
|
|
|
|
The "+" means you want to add a value to the hash (as you'll see in a
|
|
minute, to remove an item you use "-"). Then, since a hash is a
|
|
key/value pair, you have to delimit the two. In this case, we have
|
|
used "|" as a delimiter. However, you could use anything. The first
|
|
occurance tells mozbot what delimiter you have picked. The second
|
|
separates the key (in this case the site nickname) from the value (in
|
|
this case the URI). For example:
|
|
|
|
/msg mozbot vars RDF sites '+*key*value'
|
|
|
|
You could even use a letter as a delimiter, but since that is usually
|
|
a sign that you have forgotten to declare which delimiter you are
|
|
using, mozbot will warn you about this. For example (the 'users' hash,
|
|
BTW, is the hash in which all the username/password pairs are kept):
|
|
|
|
/msg mozbot vars Admin users '+sarah|lisa'
|
|
|
|
...will be treated the same as:
|
|
|
|
/msg mozbot vars Admin users '+*arah|li*a'
|
|
|
|
..., I.e. the username added would be "arah|li" and the password would
|
|
be "a". This is not a bug, it's a feature. It means you can include
|
|
any character, including "'", "|", and so on, in the key, without fear
|
|
of it being interpreted as a delimiter.
|
|
|
|
To remove a user, or any key/value pair in a hash, you use this
|
|
syntax:
|
|
|
|
/msg mozbot vars Admin users '-admin'
|
|
|
|
That's it. No need to say what the value is, since each key in a hash
|
|
has to be unique.
|
|
|
|
-- end --
|