gecko-dev/webtools/mozbot/INSTALL

                       _           _ 
        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. Password.
      If your server has a password, enter it here. If there isn't one
      (and this is almost certainly the case) then just hit enter.

   4. 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 mozbot 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.)

   5. 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.

   6. 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.

   7. 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, the General,
Greeting, Infobot and Parrot modules are loaded. The General module
provides the 'help' command and responds to CTCP VERSION messages. The
Greeting module responds to greetings and generally tries to be
friendly. The Infobot module provides information storage and
retrieval functions. The Parrot module lets an admin control the bot
much like a puppet.

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 provides the commands such as "auth",
"newuser", "password", and provides additional commands to admins,
such as "shutdown", "cycle", "leave", "restart", 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. For example, to tell mozbot that the key for channel
   #channel is 'password', you would use:

      /msg mozbot vars Admin channelKeys '+|#channel|password'

   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 of this module each time.

   channelsBlocked -- channels that will not be autojoined, so if a
   module has been disabled, it won't rejoin the channel if the bot is
   kicked then reinvited.

   denyusers -- user@host regexp masks of users that should be
   completely ignored (for this module). 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, password -- the server and port to connect to, and
   the server password to use. If you change these and then cycle the
   bot (/msg mozbot cycle) then the bot will change servers without
   shutting down.

   localAddr -- if you don't seem to be able to establish a
   connection, but it works fine with other software, then you should
   try setting the localAddr variable to your IP address. Technically,
   this variable sets which interface to use to form the outgoing
   connection. (This is to work around a limitation of Net::IRC.) 
   Typically you would set this variable directly in the configuration
   file, by adding a line that says "localAddr=10.11.12.13" or
   whatever your IP address is.

   simpleIRCNameServer -- if the value of this variable equals the
   name of the server, then the IRC Name sent to the server will be
   simplified so that it doesn't include the URI of the mozbot help
   files. This is usually dealt with automatically, but if you are
   having troubles connecting, you could try setting it. (It is set to
   the name of the server so that if you change servers, by default
   mozbot will use a complete IRC Name again.)

   username -- if this variable has a true value, then the bot will
   use its value as its IRC username. By default, the bot uses
   "pid-1234" as the username, where "1234" is the bot's process ID. 
   This can cause problems on networks or with BNCs that require a
   valid and accurate ident, in which case this variable can provide a
   solution. (You can also set this variable by entering
   "username=blah" into the configuration file, where blah is the
   username you want to use.)

   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 "join" and "part", 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.

   ignoredUsers -- a list of regular expressions that are matched
   against the user@host strings of everything that is said. If a user
   matches one of the entires in this list, then that user will be
   completely ignored. (^ and $ symbols are implied at the start and
   end of this regular expression.) Use this sparingly. It will stop
   the user's statements from having _any_ effect on the bot,
   including in any statistic-collecting modules, etc. If you just
   want to block a user from certain modules, add a regular expression
   to the 'denyusers' variable of those modules.
   Example:
      >mozbot< vars Admin ignoredUsers '+root@.*'
      *** moron (root@example.org) has joined #mozbot
      <moron> mozbot: help
      * you watch the tumbleweed roll on by

   ignoredTargets -- when someone says something to someone who
   matches one of the regular expressions in this list, the line will
   be ignored as if the person saying it was banned with ignoreUsers. 
   This is useful when you have other bots in the channel, and don't
   want the mozbot to respond in place of the other bots (e.g. with an
   auto-helping Infobot module). Note: It is safe to user a regular
   expression that matches the mozbot bot's name; it will always
   respond to messages to itself (as well as messages that are sent
   via /msg) irrespective of this setting.
   Example:
      <user> foobot: what is green?
      <foobot> user: green is good.
      <mozbot> user: green is good.
      <user> mozbot: vars Admin ignoredTargets '+.*bot[0-9]*'
      <mozbot> Variable 'ignoredTargets' in module 'Admin' has changed.
      <user> foobot: what is green?
      <foobot> user: green is good.
      * user patpats mozbot

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. (Although, in this particular case, it should be
noted that the preferred way to remove users is actually the
'deleteuser' command.)

-- end --