ezbounce v2.0
             - - - - - - - - - - - - - - -

Last updated: $Date: 2008-05-01 22:23:04 -0500 (Thu, 01 May 2008) $

ezbounce is a highly configurable, multi-user Internet Relay Chat proxy.

In addition to basic proxying, it has several features for the serious
IRC user:

	* Multiple user accounts with full access control.
	* Allow/deny lists and configuable privileges for each user.
	* Detach and reattach features to maintain IRC connections while
	  disconnected from the proxy.
	* Automatic server reconnection.
	* Chat logging with automatic compression.
	* Support for fake Ident replies.
	* Numerous customizable user preferences.
	* SSL and IPv6 Support.
	* Transparent DCC proxying.
	* Support for encrypted passwords.
	* Uses nonblocking sockets and DNS lookups.

ezbounce was written by Murat Deligonul (murat@linuxftw.com)

The project web site is at http://www.ezbounce.net/

There's also a page at SourceForge: http://sourceforge.net/projects/ezbounce/


1. REQUIREMENTS
----------------

	* a C++ compiler (gcc >= 3.2 recommended)
	* GNU Make
	* (Optional) Boost C++ Libraries, version 1.33 or later
	* (Optional) OpenSSL


ezbounce is written in C++ and developed on Linux.  It has been tested under Linux
and FreeBSD, but should work on any modern Unix-like system.


2. COMPILING
-----------------

  1. First, type ./configure. It will gather information about your system.

  2. Then type 'make' (NOTE: BSD users may need to type 'gmake')

  3. The resulting ezbounce executable can be put anywhere.


Other options:

  A few options are available to the ./configure script:

  	--with-ssl[=/path/to/ssl]

  Configures ezbounce for SSL support. You need OpenSSL or the
  equivalent installed on the machine.  By default, SSL support is not compiled.

	--with-boost[=/path/to/boost]

  Configures ezbounce for Boost support.  Boost is a collection of useful C++ libraries
  which is currently used for implementing chat log compression.  By default, this
  is not enabled.

	--enable-debug

   Builds ezbounce with debugging options turned on.  This is useful for
   development or tracking down bugs.  By default, debugging is turned off
   NOTE: enabling debug will mode will result in a much larger binary and a
   tremendous amount of debugging output being printed.


3. RUNNING
-----------------

The syntax for running ezbounce is:

	./ezbounce [options] <configuration file>

A configuration file must be specified.  The following command line options
are also recognized:

	-f: 		  stay in the foreground
	-b <address>:     listen for connections on a different interface


4. SETUP & OPERATION
---------------------

For your convenience, two sample configuration files are provided.
One is 'ezb.conf' which is a quick and simple one, and the other `sample.conf'
which lists all the possible configuration settings and describes them.  Both
are extensively commented and will be good starting points in configuring the
proxy for you needs.

ezbounce operates with a user account system.  You can have as many user accounts as
you'd like, each with different privileges, but there must be at least one.  You also
have full control over what hosts the users are allowed to connect from, what IRC
servers they may use, and how many of them are allowed at once.

User accounts are defined in the configuration file.  Here is an example:

	user "bob" {
		set password "secret1"
		set enable-detach-command 1
		set enable-incoming-dcc-proxying 1

		allow {
			from *
			to *
		}
	}

This defines a user named "bob", with a of password of "secret1".  It also
allows him to connect from any host and connect to any IRC server.

To log in as bob, connect your IRC client to ezbounce, and issue the
following command:

	/quote login bob secret1


Then use the CONN command to connect to an IRC server:

	/quote conn server [port] [password]

ezbounce will then attempt to connect you to that server.
You can cancel a connection attempt by doing:

	/quote cancel


Once connected, you can go about IRCing as normal.

Other basic commands:

	* HELP <command>
	   Lets you get help on any command. As of ezbounce v1.0, all commands
	   are documented through this system. Typing "/quote help" on its own
	   will just show a list of commands.

	* VHOST [host] or INTERFACE [host]
	   Lets you bind your connection to an available interface on the machine.
	   You can configure which ones they may  use, or let them use all
	   available ones. See the sample config files.

 	* VHOSTS
	   Lists the virtual hosts that a client may use with
	   the VHOST command.  It basically dumps everything that was given
	   in the vhosts { } blocks of the configuration file.

	* EZB <command> [args]
	    This command lets you issue commands directly to ezbounce while you
	    are connected to an IRC server.

	    Normally, ezbounce will stop parsing commands once you connect to IRC.
	    However, it will always check for 'ezb'. This is useful, as it lets you
	    issue most any command without dropping the IRC connection.

	    Some examples:

	    This will terminate the IRC server:

		/quote DIE shutting down the server

	    But using the 'ezb' command you can terminate the proxy instead.

		/quote ezb DIE shutting down

	* MOTD
	    Shows the Message of the Day.


5. ADMIN FEATURES
------------------

ezbounce lets you define certain user accounts as administrators.
Designating a user to be an admin is very easy; simply put this line in his
configuration:

	set is-admin 1

An admin gains his priviledges as soon as he connects and logs in.  There is
no need to use an additional "admin" command.

An administrator can:

	* Get detailed information on users and connections.
	* Kill any user off the proxy.
	* Shut down the proxy entirely.
	* Send messages to a user(s).
	* Use any network interface available on the machine.
	* Use any command and feature he wants, even if it has been disabled.
	* Connect to any IRC server he wants regardless of config settings.


Some admin commands are listed below:

	* STATUS
	    Display detailed information on the proxy, including uptime, resource usage, users,
	    and their connection states.

	* WHOIS <connection id or username>
	    Displays information about a user.

	* KILL <connection id> <reason>
	    Kicks a user off the proxy.

	* TRACE <id>
            Shows a text diagram of a user's connection.

	* DIE <reason>
	    Kills the proxy gracefully.

	* DIENOW <reason>
	    Immediately kills the proxy.

	* REHASH
	    Reloads the proxy configuration file. Has the same effect as
	    sending the proxy a SIGHUP signal. It will let you know whether
	    it was successful or not and dump any possible error messages
	    into the proxy log file.

 	* WRITE <userid> <message>
	    With this command you can send a message to another user. You
	    get the userid from the status command. You can use 'all' for
	    the userid to broadcast the message. Unfortunately, regular users
	    have no way of responding to your messages right now.


6. DETACHING AND REATTACHING
----------------------------

An extremely useful feature of ezbounce is the detach feature.  This allows a
user to disconnect from the proxy but keep the conncetion to the IRC server
alive.  He can later reconnect to the proxy and reattach to and resume his
detached connection.

By default, detaching is automatic.  If your connection to the proxy is abruptly
terminated, ezbounce will still maintain IRC connection.  You can also force a
detach with the following command:

	/ezb detach


To reattach, log in to proxy as usual, and type:

	/ezb sessions


This will list your  detached sessions along with unique IDs for them.
To reattach, type:

	/ezb reattach <id>


By default, all users are permitted to detach.  You may disable detach capabilities
if desired; the configuration option is 'enable-detach-command'.  Here is an example:

	user "steve" {
		....
		# Disable detach capabilities for steve
		set enable-detach-command 0
	}


The proxy can be setup to log chats while detached.  See the file "ChatLogging.txt"
in the docs/ directory.


7. FAKE IDENTS
-----------------

ezbounce allows users to set custom replies for IDENT queries.  Many IRC servers today
require identd to be running on the clients' machines.  Unfortunately, when connecting
through a proxy, a user's ident becomes the username that the proxy software is running
under on its host system.  This can be undesirable.

ezbounce provides a couple of methods for users to set custom ident replies.  Please see
"FakeIdents.txt" in the docs/ directory for details.


8. DCC PROXYING
-----------------

ezbounce supports DCC proxying.  This is especially useful for people
behind firewalls or on a LAN -- but note that ezbounce must be running on
a machine that has both global Internet access *and* local LAN access.

It's completely transparent, meaning the client can just use the regular
/dcc commands to send and receive DCC chats and file transfers. No special
settings or commands are required on the client software.

For more information on setting up DCC proxying, please see "DCCFeatures.txt" in the
docs/ directory.


9. VIRTUAL FILE SYSTEM
------------------------

A major new feature in ezbounce 2.0 is the Virtual File System.  This provides a common
location for not only chat log storage, but also for DCC transfers and other files.

The VFS is described in depth in "VirtualFileSystem.txt" in the docs/ directory.


10. USER PREFERENCES
----------------------

ezbounce has several preferences that users may customize to their liking.  They control
logging, auto-reconnection, detaching, and many other things.  In addition, they can be
set not only globally, but for specific IRC networks and servers as well, and sometimes even
for specific channels.

Please see "UserPreferences.txt" in the docs/ directory for more information.


11. LOGGING
------------

ezbounce can be set up to log chats while connected to IRC.  Users can then retrieve their
logs via DCC Send or even view them in their clients through DCC Chat.

Chat logging setup is described in "ChatLogging.txt" in the docs/ directory.

In addition, ezbounce maintains a "Event Log" for each user account.  This documents
connections, detaches, errors, and other information in a log file which the user can retrieve
via DCC.  For more information see "EventLog.txt" in the docs/ directory.


12. SSL SUPPORT
-----------------

ezbounce has basic support for SSL connections.

To enable SSL, you must first compile ezbounce with support for it.  See
the section above for compiling with SSL support.

Then you must define some settings in your configuration file:


	set cert-file <SSL certificate file>

This sets the certificate file.  You can generate one by using the scripts in the
tools/ directory.

        ssl-listen <ports>

This specifies the ports to listen for SSL connections on.  This is just like the
'listen' config command, except it makes the sockets listen in SSL mode.

Here is an example setup:

        ssl-listen 6900,6901,6902
        set cert-file "ezb.pem"


Finally, to connect to an IRC server in SSL mode, all you need to do is:

    /quote conn -ssl irc.server.com


13. OTHER FEATURES
--------------------

   Here are some other commands available in ezbounce:

	  /quote LOGIN <user> <password> [server[:port]] [IRC server password]

	Well you knew the LOGIN command already. But it has a special
	feature that lets you rapidly connect to an IRC server w/o
	having to issue the CONN command. Simply enter the name of the
	IRC server right after your password. You can also provide a port
	to connect on as well as a password to send to that IRC server.

	  /quote PASS <username:password> [server[:port]]

	There is also a PASS command, retained for compatibility reasons.
	An example for user bob, and password "blahblah" would be:

	  /quote pass bob:blahblah

	This is mainly useful if you want to set up your IRC client to
	automatically log in for you.


14. OTHER CONFIGURATION
-----------------------

Nobody wants to read boring manuals.  If you want to know all the commands
and what they do, try '/ezb help'

If you need help with configuration file details, please look at
the sample.conf file included with the ezbounce distribution.


15. ACKNOWLEDGEMENTS
--------------------

Special thanks to:

	* Seth W. and yewnix.net for many suggestions and many years
	  of providing web space.
	* Matt Sams for numerous suggestions and testing of potentially
	  dangerous untested code.
	* Jack M. for letting me test on his machine.
	* logiclrd, who asked if i could "make a bounce server" for him
	* Karl S. for writing a man page and patches.
	* HoE for contributing the original SSL code.
	* Nfs for helping with IPv6 testing efforts.
	* SNS for donating the ezbounce.net domain.
	* Andrew C. for machines to test on.


16. LICENSE
---------------

ezbounce is released under the GNU General Public License.  The COPYING file
has details about the license.


17. FEEDBACK
-------------

My e-mail address:    murat@linuxftw.com

If you have any questions, complaints, comments, suggestions, feel free
to drop me a line.  This project stays alive because of YOUR feedback.


18. OTHER
------------------

This program has a rather silly name. If you think of a better one let me
know please...

Also, if anyone has some ANSI Artwork skills and wants to make a l33t banner
or two, please let me know...