                     ezbounce v1.02
             - - - - - - - - - - - - - -
	
Ezbounce is a very configurable, multi-user IRC proxy or 'bouncer'.

It has all the basic features of an IRC bouncer, as well as
features for the serious IRC user:

  * User accounts, which allow you to give different priviledges
      to different users.
  * Full access control with allow and ban lists
  * Detach and reattach features to maintain IRC connections while
     disconnected from the proxy.
  * Ability to listen and connect on different virtual hosts.
  * SSL Support
  * Fully Transparent DCC Proxying (incoming and outgoing)
  * Remote administration
  * Uses nonblocking sockets.
  * Logs chats while you are detached and DCC sends them back to you
      when you reattach.
  * Ability to reload configuration at run time.
  * Can be run in the background or foreground.
  * Support for fake ident-replies, when used with mdidentd ident
     daemon.
  * Numerous other tweakable settings.


ezbounce was written by Murat Deligonul (druglord@freelsd.org)

The web page is at http://druglord.freelsd.org/ezbounce/


1. REQUIREMENTS
----------------
You'll need:

	* a C++ compiler -- if you're using GCC, anything since
	  2.7.2.x should work.
	
	  Some versions failed to compile under GCC 2.95.x, but this
	  has been worked around.

	* The C++ Standard Library might be required, depending
	  on your system setup. (optional, see "other options"
	   in section 2)

ezbounce is developed on Linux, but should run on any POSIX compliant
system.


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

Basically:

  1. First, type ./configure. It will gather information about your system.
  
  2. Then type 'make'
  
  3. The resulting ezbounce executable can be put anywhere.


Other options:

  There are a few options available with the ./configure script:

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

  Configures ezbounce for SSL support. You need OpenSSL or the
equivalent installed on the machine.

  ./configure --enable-use-select
  
  Force ezbounce to use select() instead of poll() for all its
socket needs. poll() is used by default if found on the system.
It is not required.

  ./configure --disable-link-stdcxx
  
   This will attempt to build ezbounce without linking with the C++ 
libraries. This may or may not work; if it doesn't, you'll be greeted 
with a plethora of linker errors.


   ./configure --enable-debug

   Builds ezbounce with debugging options turned on. Useful if you
want to do development.



3. RUNNING
-----------------
	
  The syntax for running ezbounce is:
	ezbounce [options] <configuration file>

  Only the configuration file is required. Options can be one or more 
of the following:
	
       -f: 		  stay in the foreground
	   -b <address>:  listen on a different interface (virtual host)
	   -u <uid>:	  makes ezbounce use this userid

   Ezbounce comes with two sample config files, one called 
`ezb.conf' which is a barebones one, and `sample.conf' which
lists all the possible config options and descriptions for them.


4. BASIC CONFIGURATION & OPERATION
-----------------------------------
   
   ezbounce 1.0 is based on a user account system. You can have
as many users accounts as you'd like, each with different priviledges,
but there must be at least one.

   User accounts are set up like this (in the configuration file):

user bob {

    set password blahblah
    set enable-detach-command 1
    set enable-incoming-dcc-proxying 1

    allow {
        from *
        to irc.lagged.org
        to irc.qeast.net
        to irc.lightning.net
    }
}

   This defines a user named "bob", with a of password of
"blahblah"

   To log in as "bob", you would connect your IRC client to ezbounce,
and use the following command:

    /quote login bob blahblah


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

	/quote conn server[:port] [password]
 
   ezbounce will then check if it's configured to allow you to connect there
and will proceed if you are. You can cancel a connection attempt by doing

	/quote cancel
	

   Once you connect, you can go about IRCing as normal.
  
   Other 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.

	* IDENT
	   Allows users to set their own idents, regardless of the userid the
	   proxy is running as. Requires mdidentd to be running. See the section
           below on fake idents.

	* 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 die!!


		note: as of ezbounce 1.0, the 'ezb' command is parsed all the time,
		      even when you have not connected to an IRC server.
			
	* EZBOUNCE
	    The 'EZBOUNCE' command is the same as the 'EZB' command (it was the 
	    original one); it is simply a shorter and faster to write EZB. 
            
	* MOTD
	    Shows the proxy's Message of the Day, in case you missed it.
	
	* SET <option> <value>
	    Lets you customize a few options, like whether to automatically
	    detach, and your default vhost. Settings are saved to disk,
	    so they are retained across different sessions. See the section
        10 below
	


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

   Ezbounce lets you create password protected adminstrator accounts. In addit-
ion, you may restrict admin access to certain hosts. Look at the sample
configuration files. In short, an admin is defined just
like any other user, except this "user { }" block contains the line:

    set is-admin 1

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

   An administrator can:
  
	* Get information on where every user is coming from and where 
	   they are connected
	* Get the state of every users connection
	* Kill any user off the proxy
    * Kill the proxy entirely
    * Send messages to a user or everyone
	* Use any vhost he wants, regardless of whats in the vhost block
	* Use any command and feature he wants, even if its been disabled
	* Connect to any IRC server he wants, as many times, regardless of
	  config settings.

   The commands are as follows. You may need to use /quote ezb before them.
But you already knew that.

	* STATUS
	    Display proxy information. The letters stand for
	     
             (r)egistered 
             (p)assword given 
             (a)dmin 
             (c)onnecting
	         (b)ounced
             (d)etached 
             (w)aiting (newly connected)

            A unique user ID is also displayed.

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

    * TRACE <id>
        Shows a nifty diagram about a user's connection.

	* KILL <userid> <reason>
	    Boots the user with userid off the proxy. You must supply
	    a reason.

	* 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 extremly 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.
  
   While a user is detached ezbounce will respond to pings from the IRC
server to keep the connection active.  

   Here's how to use this feature:

	/quote ezb detach [password]
	
   This will detach the client, and optionally, protect it with a password.
While detached, ezbounce will respond to IRC and CTCP pings, and log chats
as well (see below).

   To reattach, you just need to log in as usual, and type:

   /quote sessions

   which will list all your detached detached sessions, along with an a unique
ID for them. Then type

   /quote reattach <id>

   And ezbounce will reattach to that connection. (note: if you supplied a
password when you detached, you must supply it here again)

   Here are the configuration file variables for using the detach system.

 user xxx {
        ....
        set enable-detach-command 1
        set enable-auto-detach 1
 }

  "enable-detach-command" ought to be self-explanatory. Auto-detach is a nifty
  feature that will automatically detach you if your connection to ezbounce dies
  for whatever reason. This can be cause you typed /quit, killed your client, or
  some other weird error. Ezbounce will automatically detach and keep your
  IRC session alive.

  See section 11 below.




7. LOGGING WHILE DETACHED
---------------------------

   While detached ezbounce can log channel activity and private messages for 
you. Upon reattach, the user is informed of available log files and can issue
a command to have ezbounce DCC Send the log files.
   
   
   * USER COMMANDS
      All log commands are handled through the LOG command.
      The syntax is:
	
	/quote [ezb] log <command> [parameters]
	
	Where the available commands and parameters are the following:
      
            SET <any combination of tfpcans>
                  
		  Sets logging options for a session:
                  p - log private messages
                  c - log channel messages
                  a - log both channel and private
                  n - don't log anything
                  s - log to seperate files
                  t - timestamp logs
                  f - show full addresses in *public* messages
            

            VIEW <# or ALL>

                 Sends the logfiles to you through a DCC Chat,
                 so that you don't have to save it on disk and view it through
                 a text editor

            SEND <# or ALL>
                        
    	         DCC Sends any logfiles to you that are ready to be sent.
                 You need to provide the index number as listed by LOG
                 FIND.

            
             FIND [password]
            
                 This allows you to recover log files from old detached
                 sessions that you were not able to retrieve. Password
                 is optional, and only necessary if you detached with one.

             LIST
                 Lists the results of your previous LOG FIND search and
                 and any other log files that are ready to be sent.
            
	Use LOG without any options to view current log settings
            

   * CONFIG OPTIONS

      You can enable logging on a per-user basis. The following
   commands need to be put inside a "user { }" block.
   
	set enable-private-logging [0/1]

	 - Allows users to log private messages while detached.

	set enable-public-logging [0/1]
	
	- Allows users to log channel messages while detached.

    set enable-seperate-logging [0/1]
	
	- Allows users to log channel and private messages to seperate
	  files to make them easier to handle.


      To completely disable this feature, set all of these options to 0.
    

      In addition, the following option controls where log files are to be 
      stored:
    
	set log-dir <directory>
	
	 The default directory is logs/
	
      And this user option lets you set the default log options for new users:
      
	set default-log-options <any combination of tfpcans>
	
	  Options are described above..


8. FAKE IDENTS
-----------------

Most IRC servers will make an ident request when you connect to them. Often
times it is required to connect to that server. 

For clients connecting to IRC through ezbounce, the replied ident request
will be the id of the user running ezbounce. So if you were running ezbounce
as 'nobody', anyone using IRC through it would also be 'nobody'.

To solve this problem, ezbounce allows users to set their own idents, with the
help of a special ident daemon (mdidentd). More info about it is in the
mdidentd/ directory. But basically, once you get it setup and running, users
can set their own idents by issuing the 'ident' command. 

In addition to running mdidentd you'll need these two items in your config file,
both inside a "user { }" definition:


set enable-fake-idents 1
	
	This should be self-explanatory. It basically enables the 'ident' 
command.

set auto-fake-idents (1 or 0)

	This is not required. It is basically a convenience thing for users,
as it sets their fake idents to whatever their client sends as their username.
It eliminates the need to use the 'ident' command.


9. DCC PROXYING
-----------------

ezbounce supports dcc proxying. This is especially useful for people
behind firewalls or stuck in 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.

To enable it, one or two items are needed in the config:

 -- This enables outgoing dcc proxying, meaning dccs initiated by the
client. Ezbounce detects these DCC requests as they are sent, and modifies
it a bit so the destination connects to ezbounce rather than the client.
And then once that has happened, ezbounce connects to the client and
from then on simply relays data from one side to the other. 

	 set enable-outgoing-dcc-proxying 1


 -- This enables incoming proxying. That is, DCC requests coming from
outside sources to the client using ezbounce. Again, ezbounce does some
clever interception tricks and ends up relaying data between the two.

	set enable-incoming-dcc-proxying 1

Note that these are both user variables, so they must be put inside
" user { } " blocks. This lets you enable and disable them for
different accounts.

You can enable either one, both, or none of them at all. It will all
depend on your needs and your network configuration. All transfers will be
logged to the log file. Other things:

* mIRC DCC Resume is *NOT SUPPORTED* (yet)

* It *SHOULD* handle DCC VOICE/VIDEO & other assorted dcc commands by
  some Windows clients.
  
* All DCC sessions are handled seperately from the users connection and ezbounce
  will try to keep them alive if the user disconnects from the proxy, until
  the users end closes the DCC connection.
  
* Those with restrictive network settings can restrict the ports used by 
  ezbounce DCC proxying to a specific range.. The option for this is:
	
	set dcc-listen-port-range <ports>
	
    where ports can any number or series of numbers seperated by
    commas, and where ranges of numbers can be indicated by a dash.
    Examples:
       7000,7005,8225,9000-9100
       2000-2300,4860
       6918
       5700-5710



10. MORE FUN USER ACCOUNT FEATURES
-----------------------------------

Each user can customize various options to his liking.

This is managed through the 'SET' command:

    /quote ezb set <preference> <value>

As of ezbounce 1.0, the following preferences are supported:

        vhost  <address>

           lets you choose a vhost to connect on

        auto-server  <irc server>

            lets you pick an IRC server to automatically connect to

        fake-ident

            ditto

        auto-detach <1/0>

            Makes you automatically detach from the proxy. This means,
            if you disconnect from ezbounce, close your client,
            type /quit, you WILL be detached. If you want to override
            this, you can set it to 0, or type /quote ezb QUIT,
            which will send a proper QUIT to the IRC server and
            disconnect you.

        proxy-dcc-in

            Makes ezbounce proxy your incoming DCC connections

        proxy-dcc-out

            Makes ezbounce proxy your outgoing DCC connections


There is also 'SAVE' command:

    /quote ezb save

    This will save your preferences, so that the next time you connect to
ezbounce they will be retained.

And, there is an ALLOWED command:

    /quote ezb allowed

    This simply shows what priviledges your user account has. (Such as,
if dcc proxying is enabled, or what not)


11. SSL SUPPORT
-----------------

Ezbounce supports both incoming and outgoing SSL connections.

That is, it can listen for SSL connections, as well as let you
connect to SSL IRC servers. This is useful especially if your
IRC client doesn't natively support SSL.

To enable SSL, you must first compile ezbounce with support for it.

This is done as follows:

    ./configure --with-ssl

Then run make as usual.

There are couple configuration variables to point out:

    set cert-file <SSL cert. file>

You must define this if you want SSL. You need a valid cert
file, which can be built with the Makefiles provided with
OpenSSL. (See the manuals for it)

    ssl-listen <ports>

This is just like the 'listen' config command, except it
makes the sockets listen in SSL mode.

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

    /quote conn -ssl irc.server.com

Simple, no?


12. FEATURES YOU NEVER KNEW ABOUT
----------------------------------

   Here are the 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.
	
	set auto-server <server[:port]> [password]
	
	  This config option does essentially the same as the above command.
	  It will automatically connect users to the given IRC server when
	  they connect to ezbounce. (Note: this is a user option, so
      use it in a user { } block)


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

   Nobody wants to read boring manuals. If you want to know all the commands
and what they do, may I suggest issuing the command '/quote ezb help'
If you need help with configuration file details, please look at
the sample.conf file included with the ezbounce distribution. Several other
fun configuration options are awaiting your discovery!


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 maintaining the Debian package, writing a man page, and 
       patches.
    * HoE for contributing the SSL support code

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

   ezbounce is released under the GNU Genereal Public License. The LICENCE file
has all the details about the license.


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

   My e-mail addresses are: druglord@erupt.com
                            druglord@freelsd.org

   You can catch me or my idling client on EFnet under
the nick 'druglord'.

   I'm also on AIM as 'druglord0'.

   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 skillz and wants to make a l33t 
banner or two for ezbounce, please let me know!!


