head     1.1;
branch   1.1.1;
access   ;
symbols  INITIAL:1.1.1.1 TOLKIEN:1.1.1;
locks    ; strict;
comment  @# @;


1.1
date     2002.09.03.09.14.56;  author tolkien;  state Exp;
branches 1.1.1.1;
next     ;

1.1.1.1
date     2002.09.03.09.14.56;  author tolkien;  state Exp;
branches ;
next     ;


desc
@@



1.1
log
@Initial revision
@
text
@perlbot - <burke@@pas.rochester.edu / jmuhlich@@jhu.edu>
======================================================

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.

Table of Contents:
-----------------

1) Requirements
2) Installation
3) Settings
4) Debugging
5) Mailing List
6) Weird Stuff
   - How to make perlbot work with Win32
   - How to make perlbot work with MacPerl

----------------------------------------------

1.0 Requirements:
=================

  - Net::IRC		(http://www.perl.com/CPAN/modules/by-module/Net/)
  - HTML::Parser	(http://www.cpan.org/modules/by-module/HTML/)
  - DB_File		(http://www.cpan.org/modules/by-module/DB_File/)
  - HTML::Tagset	(http://www.cpan.org/modules/by-module/HTML/)
  - HTTP::Lite		(http://www.cpan.org/modules/by-module/HTTP/)
  - Net::DNS		(http://www.cpan.org/modules/by-module/Net/)
  - TimeDate		(http://www.cpan.org/modules/by-module/Time/)
  - XML_Parser		(http://www.cpan.org/modules/by-module/XML/)
    - expat		(http://sourceforge.net/projects/expat/)
  - XML_SimpleObject	(http://www.cpan.org/modules/by-module/XML/)


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.

  Of course, if you're reading this, you're a step ahead of the game...

  (add crontab)
  */5 * * * * BASEDIR=~/src/plbot ~/src/plbot/health.chk
  */30 * * * * BASEDIR=~/src/plbot ~/src/plbot/data/crontab.irc

3.0 Settings:
=============

  You should edit perlbot-<version>/config to suit your needs.

  3.1 - bot { } settings:
    - 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.

    - plugindir - this sets the default directory for the bot to look
		  for plugins.  It is set to "./plugins" by default.

    - addchar   - this specifies the character to append to the end of
	          the bot's nick when it cannot obtain any. By default
		  it is set to "_".

  3.2 - server { } settings:
    - name      - this is an internal setting for the bot, in other words
	          the owner/user need only worry that it is unique.

    - net       - this setting is not strictly necessary, but might be
	          advisable to have, if for no other reason than
	          organization.  It was a leftover from some of the network
	          bridging code that will be released later, and should
	          be used just incase.

    - addr      - this sets the address of the server, it can be an IP or a
	          qualified machine name.

    - port      - this sets the port that the bot will try to connect to
	          the server on. By default it is set to 6667.

    - ircname   - this sets the bots ircname for that server.

  3.3 - user { } settings:
    - name      - this sets the unique name that the bot will use to
	          refer to that user.  It is also used to leave notes, etc.

    - flags     - this sets the flags associated with the user.  The only
	          currently working flags are: "w"
	            - w - specifies the user as an owner

    - hostmask  - this adds a hostmask to 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 directive, ie:

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

  3.4 - chan { } settings:
    - name      - the name of the channel to join.  If the leading # or &
	          character is left off, it 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.

    - net       - this is meant for bridging and can be ignored for now.

    - flags     - this sets the channel flags

    - logging   - takes 'on' or 'off'. ie:

		    chan {
		      ...
		      logging	on
		      ...
		    }

		  Channel logging defaults to OFF if left unspecified.

    - op        - this sets a user to be an op for the channel.  It expects
	          the name field from their user entry. ie:

                    user {
	              name	timmy
	              ...
	            }

	            chan {
	              ...
	              op	timmy
	              ...
	            }

4.0 Debugging:
==============
  Should you have problems, please edit perlbot.pl and near the top where
  it says:

    $debug = 0;

  change it to:

    $debug = 1;

  Then, from your shell, run:

    ./perlbot.pl > pb_log.txt

  Now make the problem occur again, and then email pb_log.txt to
  burke@@pas.rochester.edu and jmuhlich@@jhu.edu .

5.0 Mailing List:
=================

  To subscribe to the perlbot mailing list, send a messaged to
  majordomo@@nimh.net with "subscribe perlbot" in the body.

6.0 Weird Stuff:
================

 - How to make perlbot work with Win32:

    As far as I know, most things work.  However, anything that uses
    fork will not work, as it isn't implemented on Win32... we're
    looking at this issue, and we'll see what we can do.  In the
    meantime: add the noload directives listed below (in the MacPerl
    section) to your config file, and the rest should be functional.

 - How to make perlbot work with MacPerl:

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

    As of 1.1.9, perlbot should be fairly happy working with
    MacPerl... however, you won't be able to take advantage of
    much of the cool functionality... my suggestion? Get an OS
    that has nicer threading... but if you insist:

    in config:

    change the logs and plugins dir to something like:

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

    now, as of this writing (1.1.9) you need to add the following
    'noload' directives:

    bot {
      ...
      noload	MegaHal
      noload	AVDemos
      noload	AVNews
      noload	Blues
      noload	Define
      noload	Dictionary
      noload	Freshmeat
      noload	KnowledgeBase
      noload	Linuxtoday
      noload	Math
      noload	NSLookup
      noload	Perldoc
      noload	PriceWatch
      noload	Slashdot
      noload	SpelCheck
      noload	Traceroute
      noload	Weather
      ...
    }

    or you can delete those plugins.  They will crash your bot if you
    attempt to run them because they all use 'fork' which is
    unimplemented in macperl.  That is neither our fault, nor
    their's.. so please don't bug either of us about it. When MacOS
    does proper multitasking, i'm sure the MacPerl people will do
    their best to implement 'fork'...

    your bot should now be working... the Core 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 on other platforms.










@


1.1.1.1
log
@initial from kang.sarang.net
@
text
@@
