-----
About
-----

Pastebot is perhaps the original web-based dropbox (pastebin) for
small texts.  It's a gateway from your clipboard to your favorite IRC
channel, and hopefully someday your favorite chat room.

On the one hand, Pastebot is a web server that accepts "pastes" from
one person to share with others.  On the other hand, it is an IRC bot
that announces paste URLs on appropriate channels.

-------------
Quick install
-------------

Most of Pastebot's files install the usual CPAN way, either by running
"install Bot::Pastebot" from the CPAN shell or CPANPLUS, or by
downloading the tarball and installing it manually:

  perl Makefile.PL
  make install

You will also need to create a configuration file.  A sample
configuration file is in the examples directory, and the perldoc for
pastebot describes each option.

  perldoc pastebot

------------
Requirements
------------

The installer will tell you what modules are necessary.  The CPAN and
CPANPLUS shells may install them automatically.

----------------
Use with Proxies
----------------

Pastebot is its own web server.  It often cannot bind to port 80
because some other web server is already there.  The recommended port
8888 may be hostile towards people behind firewalls.

Apache users can use ProxyPass to map a directory on their port-80
servers to a running pastebot. This feature requires Apache be built
with both mod_proxy and mod_proxy_add_forward.c support, and that the
add forward module come before the proxy module.  For example:

  ./configure --enable-module=proxy \
    --activate-module=src/modules/extra/mod_proxy_add_forward.c \
    --enable-module=proxy_add_forward \
    --permute-module=proxy:END \
    ...

Once Apache is built, you can create a virtual location for the proxy
directory.

  <Location /pastebot>
    Order allow,deny
    Allow from all
    Deny from none
  </Location>

Then you must tell Apache to forward any requests in the /pastebot/
directory through to the local Pastebot server.

  ProxyPass  /pastebot/  http://127.0.0.1:8888/

Now people can use your pastebot on port 80.  Be sure to set your
pastebot's "iname" to match your proxy's address and path.  For
example:

  web_server
    ...
    proxy 127.0.0.1
    iname http://example.org/pastebot/

The sample configuration file and Pastebot's documentation should
explain how to do this.

------
Errors
------

Here are some common errors and solutions.

* IRC client (NAME): socket error occurred: Can't assign requested address

  The most likely cause is an unknown host name, either for a local
  machine or a remote IRC server.  If you have multiple servers
  specified, the bot will try the next server in approximately one
  minute.

* Can't locate [some module] in @INC (@INC contains: ...)

  Somehow you managed to install one of pastebot's required modules
  without installing a module it in turn needs.  You'll need to install
  [some module] manually and try again.

  This error may show up multiple times until each required module is
  installed.  On a positive note, it should happen a lot less since
  Pastebot is distributed on the CPAN.

* <something> section <name> is redefined at ##

  This error looks something like:

    pastes section pbtest is redefined at 68
    Compilation failed in require at Server/Web.pm line 18, <MPH> line 85.
    BEGIN failed--compilation aborted at Server/Web.pm line 18, <MPH> line 85.
    Compilation failed in require at ./pastebot.perl line 9, <MPH> line 85.
    BEGIN failed--compilation aborted at ./pastebot.perl line 9, <MPH> line 85.
  
  The exact filenames and line numbers will be different, of course.

  The error is caused when two or more configuration sections share
  the same name.  To fix it, update your pastebot's configuration to
  use different names for each section, even if they are different
  types.  For example:

    web_server
      name poenet
      ...

    irc
      name efnet
      ...

    pastes
      name neitherpoenetnorefnet
      ...

-------
Support
-------

The project accepts feature requests and bug reports through its CPAN
bug queue: https://rt.cpan.org/Dist/Display.html?Queue=Bot-Pastebot

Patches are welcome.  Pastebot's repository is hosted publicly at
http://github.com/~rcaputo/bot-pastebot and
http://gitorious.org/bot-pastebot

The latest documentation is readable online:
http://search.cpan.org/dist/Bot-Pastebot/

A fine bunch of folks occasionally chat about pastebot in
irc://irc.perl.org/poe

---
End
---