pjs/webtools/mozbot/INSTALL

                       _           _ 
        m o z i l l a |.| o r g   | | 
    _ __ ___   ___ ___| |__   ___ | |_ 
   | '_ ` _ \ / _ \_  / '_ \ / _ \| __|
   | | | | | | (_) / /| |_) | (_) | |_ 
   |_| |_| |_|\___/___|_.__/ \___/ \__|
   =======================-  2 . 0  -==


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). Currently, mozbot does not support
      joining keyed channels. To make oopsbot join a keyed channel,
      you must unkey the channel, make your bot join it, then rekey
      it. This may change in a future version, but would require a lot
      of work.

   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!

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