perlbot - <burke@pas.rochester.edu / jmuhlich@jhu.edu>
======================================================

http://perlbot.sourceforge.net

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
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.
    -> === IMPORTANT IMPORTANT IMPORTANT ===
       Net::ICQ 0.70 appears to be buggy, so stick with 0.63 for now.

  - Plugins may have their own requirements, and we trust plugin authors
    to put that in their documentation.


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

3.0 Settings
============

  Please consider using gperlbotcfg (in the gperlbotcfg/ directory) to
  configure your perlbot.  It makes it nearly impossible to screw up
  your config file due to bad syntax.  Many of the problems that users
  have emailed us about are syntax errors and such that would have been
  solved had they used gperlbotcfg.  gperlbotcfg does require the GTK
  module for perl, so make sure you install that.  It's extremely easy:

    root:/root# perl -MCPAN -e shell

    ...

    cpan> install Gtk

  that's it, you should be all set.

  But if you want to edit your config by hand or can't run gperlbotcfg:

  You should create and edit perlbot-<version>/config to suit your needs.  
  The syntax should be obvious from looking at the config-sample file,
  but here's a quick overview.  The config file consists of "objects"
  that look similar to C++ code (but don't get scared :).  Each object
  begins with the name of the "class" of the object (what type of thing
  it represents) and a "{" character ON THE SAME LINE.  Then there are
  rows, where each row begins with the name of a field of that class, and
  ends with the value for that field.  After all the fields, there is a
  "}" on a line by itself.  (Some of you might be thinking "this should
  really be XML!"  You would be correct. :)

  Here's an example for a user object:

  user {
    name       jimmy
    password   jhHHvkLL.IOo
    hostmask   jim!*jim@somewhere.com
    hostmask   jim!*jsmith@company.com
  }

  Blank lines and spaces/tabs within lines are not important.  Space it
  out however you want.  You can insert a comment by placing a # at the
  beginning (and only the beginning!) of a line.

  The rest of section 3 details the different classes that the base perlbot
  will recognize, and the fields of those classes.  The first line in each
  subsection is the name of the class.  Below that are any notes about
  the class, followed by each field in the class (preceeded by a "-") and
  a description of the field.

  Elsewhere in this document or in other perlbot documentation, you
  might see an expression such as bot.nick or user.hostmask.  These
  expressions follow the form <class>.<field> and refer to one of the
  fields listed below and the class it belongs to.

  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. you can
		  specify any number of these, and they will be tried
		  in the order that they're listed in the config file.
		  For example:

		    bot {
		      nick	perlbot
		      nick	timmykins
		      nick	sammykins
		      ...
        	    }

	          This would cause the bot to try perlbot first, then
	          timmykins, then sammykins if each nick was taken.

    - 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", e.g.:
                  ~/perlbot-<version> could hold your bot, and
                  ~/perlbot-logs could be your log dir.
                  (if you are running perlbot under MacOS, you must read
                  section 7.2)

    - plugindir - This sets the directory in which the bot will look
		  for plugins. it is set to "./plugins" by default (if you
                  are running perlbot under Win32 or MacOS, you must read
                  section 7.1/7.2)

    - nickappend- This specifies the character to append to the end of
	          the bot's nick when it cannot obtain any of the nicks
                  given in the "nick" fields. the default is "_" (the
                  underscore character).

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

    - commandprefix- This is a string to be used in a regular expression
                  to prefix internal commands when speaking them to the bot
                  in public or via msg.  The default is "#" to mimic
                  "classic" behavior.

    - pluginprefix - This is a string to be used in a regular expression
                  to prefix plugin commands when speaking them to the bot
                  in public or via msg.  The default is "!" to mimic
                  "classic" behavior.  Feel free to set pluginprefix and
                  commandprefix to the same thing if you like.  Also, you
                  could set pluginprefix to something like "mybotname,\s*"
                  which would allow you to say for example:
                    mybotname, foo 123
                  However, the character is the same in public and in
                  messages, so this trick might make msg commands
                  cumbersome.

    - 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.
                  If your bot crashes unexpectedly, email your crashlog.txt
                  to perlbot@fdntech.com (see section 5.0).  The default is
                  "." (the current directory, i.e. your perlbot directory).

  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.

    - name      - This is an internal value used by the bot. in other words
	          the owner/user need only worry that it is unique among
                  all the servers that are listed.

    - addr      - This sets the address of the server, it can be an IP
                  address or a domain name. (1.2.3.4 or irc.foo.com)

    - port      - This sets the port that the bot will try to connect to
	          the server on.  The default is 6667.

  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.

    - flag      - This sets a flag for the user.  The flags are:
	            w - specifies the user as an owner of the bot
                        (lets them execute priviledged commands)

    - 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, and they should be
		  specified one per line:

		    user {
		      ...
		      hostmask *!*@*                         # BAD hostmask
		      hostmask ircnick*!blah@abc.foobar.com  # good hostmask
		      hostmask billy*!billy*@*.blahblah.com  # this is decent
                      hostmask lamer!lamer@*.aol.com         # not good
		      ...
		    }

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

  3.4  chan
    - name      - The name of the channel.  If the leading # or & character
                  is omitted, perlbot will assume # .

	            chan {
	              name	perlbot
		      ...
                    }

	          We are aware of RFC1459 and of & channels.  We do not
	          make claims as to how well the bot will support them and
	          they have not been tested, but they should be OK.  If it
	          works out for you, let us know.  Known issue: having logging
	          turned on for #foo and &foo should break something because
                  they will both try to write to logdir/foo/* .  The # or &
	          is stripped from the log dir name since they're not nice
	          characters to have in a file or directory name.  Does
                  anyone out there even use & channels anymore?  Another
                  issue: private messages to the bot are currently logged
                  in a directory named 'msg', so if you have a channel
                  '#msg' or '&msg' then that will cause problems too.  Let
                  us know if this affects you.

    - key       - The channel key (only needed if the channel has a key).

    - flag      - This sets a channel flag, such as +s +n +t etc.  Specify
                  each flag on its own line (you currently need to
                  include the "+"):

                    chan {
                      ...
                      flag +s
                      flag +n
                    }

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

    - op        - This sets a user to be an op for the channel.  It expects
	          the name field from their user object:

                    # timmy is an op for channel #foo
                    user {
                      name  timmy
                      ...
                    }

                    chan {
                      name  #foo
                      op    timmy
                      ...
                    }

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

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 (the stuff that's
    not provided by a plugin) already has online documentation.  Simply msg
    the bot "#help" and you'll get information on how to use the online help
    facility.  To find out what commands the basic perlbot (without plugins)
    understands, msg it "#help Core".  To find out about one of the subtopics
    (commands) that it lists, msg it "#help Core <subtopic>".  For instance,
    "#help Core quit" will tell you about the #quit command.  Soon all the
    plugins will have help files, and you'll be able to access them in the same
    way, by msging the bot "#help <plugin> <subtopic>".

  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, #reload and
      #quit.  They join channels, reload the config file and quit the bot,
      respectively.  Message the bot:  #help Core  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:  #help Core
      for more information.


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 email pblog.txt and
  crashlog.txt (see "crashlogdir" under section 3.1 above) to
  perlbot@fdntech.com .


6.0 Mailing List
================

  To subscribe to the perlbot mailing list, go to perlbot.sourceforge.net,
  click on the link to SourceForge, and go to the Mailing Lists area.
  There you can sign up for our various lists for developers, users,
  announcements of new versions, etc.


7.0 Miscellaneous Stuff
=======================

  7.1  How to make perlbot work under win32 (Windows 9x / NT / 2000):

    Get ActiveState Perl from www.activestate.com.  As far as we know,
    most things work.  However, any plugins that use fork() will not work,
    as it isn't implemented in ActiveState perl.  We're looking at this
    issue, and we'll see what we can do.  In the meantime, the same
    plugins that work under MacPerl will also work under win32, so read
    section 7.2 below and follow those directions for plugins.

  7.2  How to make perlbot work under MacOS:

    Thanks to Cougar for getting us going on this stuff...

    Get MacPerl from www.macperl.com.  The base perlbot stuff should be
    fairly happy working with MacPerl.  However, you won't be able to take
    advantage of much of the cool functionality provided by some of the
    plugins.  Our suggestion?  Run an OS that has the infrastructure
    necessary to support fork().  But if you insist:

    First, change bot.logdir and bot.plugindir as follows.  This is
    necessary because of the way MacOS handles relative paths.  These
    settings will use log and plugin directories (folders) inside your
    main perlbot directory.  The example settings below mimic the default
    behavior on a unix system.  If you want to put logs or plugins in
    other directories, use the appropriate path(s) instead.

      bot {
        ...
        logdir    :logs
        plugindir :plugins
        ...
      }

    There is one other thing you'll have to do, which is disable the
    plugins that don't work under MacPerl.  The following plugins should
    work under MacPerl (or any other non-unix OS or Perl port, including
    win32):

      Foo
      Protection
      UserInfo
      WhereDaBitch

    The vast majority of perlbot plugins utilize the fork() call to do
    rudimentary multithreading.  When the Slahsdot plugin is off querying
    the Slashdot website, for example, the use of fork() allows perlbot
    to continue servicing other requests, logging, opping users and
    otherwise managing your channel.  Unfortunately, MacOS doesn't seem to
    provide the necessary functionality that would let MacPerl implement
    fork().  If you have a serious problem with this, take it up with the
    MacPerl team, or even better, Apple.  Don't bother us.

    That being said, you will need to disable the plugins that use fork()
    (and the ones that require a unix system for other reasons), because
    if they are ever triggered, your bot will simply quit.  So for all the
    plugins that aren't in the "approved" list above, you will need to
    add a bot.noload setting for each one.  So your bot section will have
    a lot of lines like:

      bot {
        ...
        noload     MegaHal
        noload     Stock
        noload     Whois
        ...
      }

    etc. etc. for all the "non-approved" plugins.

    The other option is to simply delete the non-functional plugins
    from your hard drive.  To delete a plugin, simply delete the directory
    with the same name as the plugin (these directories are in your
    plugins directory, which is by default the "plugins" directory under
    your main perlbot directory).  In this way you won't have to deal
    with a long list of noload settings, but some purists might object
    to actually deleting the plugins.  It's your call.  (if you ever need
    them back, you can always download perlbot again and copy them over)

    Your bot should now run.  The Base functionality is there (opping,
    notes, etc.), just not some of the bells and whistles.  Let us know
    how you're doing with it.  We ARE interested in perlbot's performance
    and usability on other platforms.

  7.3  Note about IRC server MOTDs

    While running our own IRC servers, we see that sometimes the bot won't
    automatically join the channels it's set to manage when it starts up.
    The problem was traced to the IRC server not having an MOTD (message of
    the day).  Perlbot listens for the 'end of MOTD' event to tell it
    when it should join its channels, so you need to have an MOTD for that
    feature to work.  The way to make sure you have an MOTD varies among
    the different IRC server packages.  If someone knows a better event
    to watch to tell the bot when it's connected to the server, please
    email perlbot@fdntech.com and tell us!  We looked into lusers and stuff
    like that, but that's not really any better.

    You can still use the #join command to tell the bot to join channels.
    All you lose by not having an MOTD is the ability to have the bot
    automatically join its channels when it connects to the IRC server.

