Ezbounce v0.99.12
                 - - - - - - - - - - - - - -
	
	Ezbounce is a very configurable IRC proxy or 'bouncer'. Its basic
features include password protection, remote administration, logging and
listening on multiple ports. It lets you configure hosts to give access
to and which addresses and ports they may connect to. It also can be setup
to ban connections to and from certain addresses. 
                                                  
While most useful to those without direct internet connections,
ezbounce has numerous tools for the serious IRC user.
                                                  
Features include: 

  * Ability to listen and connect on different interfaces or virtual
	hosts.
  * Configurable limits on amount of clients permitted to connect from an 
	address and to an address.
  * Configurable idle time limits.
  * Transparent DCC Proxying (incoming and outgoing)
  * Uses nonblocking sockets.
  * Users can set their own idents, regardless of the uid the proxy is running
    as.
  * Basic facilities to 'detach' and reattach clients from proxy but
      keep their connections to the IRC server alive. 
  * 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.


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

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


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

	* a C++ compiler, EGCS works, GCC 2.7.x + does too.
	* libstdc++, the standard c++ library (optional, see below)

Ezbounce is developed on Linux, but should run on your system too.


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

Basically:

  1. First, type ./configure. It will gather information about your system.
  
  2. Edit the makefile first if you'd like. 
  
  3. Then type 'make'
  
  4. The resulting ezbounce executable can be put anywhere.


Other options:

  There are a few options available with the ./configure script:
  
  ./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

   Those familiar with C++ may know of the ugly mess regarding what new
is supposed to do if it fails. Older compilers will return 0, the standard
today says it will throw an exception. The ezbounce configure script disables 
exception handling in the compiler when possible and uses new(nothrow)
(which returns 0).. However that requires the stdc++ library. This option
will make it use the regular new and not link, at the expense of not being
able to handle failed memory allocations (rare). 



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)
	   -c <address>:  do connections on a different interface
	   -u <uid>:	  makes ezbounce use this userid

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


4. BASIC OPERATION
-------------------
   
   To use the proxy the first thing you must do is connect with your 
IRC client. Once your client issues the standard USER and NICK commands
you will be asked to give a password. This is done with:

  	/quote pass <password>

   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
  
   Other commands:

	* HELP
	   Gets help on available commands.

	* VHOST [host] or INTERFACE [host]
	   Clients may bind their connections to different virtual hosts
	   available on the machine. The host field is optional,
	   if omitted ezbounce will use the interface specified by the -c
	   command line option or the default interface.
	   You can configure which ones they may  use, or let them use all 
	   available ones. See the sample config files.

 	* VHOSTS
	   This command lists the virtual hosts that a client may use with
	   the VHOST command.  It basically dumps everything that was given
	   in the vhosts { } block 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 is a special command that can only be used once the client
	    has established a connection to an IRC server. It is special
	    because it's intercepted by the proxy and not relayed
	    to the IRC server like other commands. The command field can be
	    most any ezbounce command. Here are some examples:
	
		/quote admin admin1 password

	    Will display IRC server administrative information. But

		/quote ezb admin admin1 password
	
   	    Will try to make you an administrator on the ezbounce proxy. The 
	    next command will terminate the IRC server:

		/quote DIE Die!!!!!!

	    But using the 'ezb' command you can terminate the proxy instead.
		
		/quote ezb DIE die!!

	    It will probably be most helpful to proxy admins as they will not
	    need to launch a second IRC connection or disconnect from their 
            current one to monitor things on the proxy. 
            The commands not accepted through this interface are:
	    USER, NICK, PASS, CONN, CANCEL. 
	    
	* 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.


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

   Ezbounce lets you create a password protected adminstrator account. In addit-
ion, you may restrict admin access to certain hosts. Please look at the sample
configuration files. 

   The 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 before them.
But you already knew that.

	* ADMIN <adminname> <password>
	    Attempts to become proxy administrator

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

	* KILL <userid> <reason>
	    Boots the user with userid off the proxy. You must supply
	    a reason.
	    It is not possible to kill yourself at this time.

	* 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. 
	    
	    Rehashing replaces all current configuration settings. Any existing
	    rulesets are marked as obsolete and compared to the newly created
	    ones. If there are duplicates, one of them is destroyed. Remaining
	    'obsolete' rule sets are checked if they have any users associated
	    with them. If not, they are destroyed. Such a ruleset that *has*
	    users will be put in a 'quarantine' state, and will be invisible
	    to clients that connect afterwards. Once the ruleset loses all of 
	    its users it will be deleted as soon as possible.

 	* 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> [awaymsg]
	
   This will detach the client and protect the session with the given 
password (password can be anything, not necessarily the proxy password).
In addition, an away message may be supplied after the password which
ezbounce will use in setting the user /away.
Note that the 'ezb' part is required. Clients may only detach
when they are connected to an IRC server. Once the client 
has detached ezbounce will send him a magic number that will needed to use 
the reattach command.

	/quote reattach <magicnumber> <password>

   If the proper number and password are given this will reattach the client
to the detached session with the magicnumber id.

   Reattaching doesn't happen immediately. Ezbounce tries to gather information
about the IRC session first. It gets the name of the server, the nickname and
hostname of the client and the channels he's on. Once that information is 
retrieved, ezbounce sends some text to the client to fool it into thinking
it is connecting to that server. Then it simulates joins to some channels.
This is all necessary for several reasons. One is that IRC clients can't 
handle things well if they are suddenly 'released into the wild' (that is, 
suddenly being on several channels, having a different nickname, etc).

   NOTE - The detaching feature hasn't been tested with all clients and/or 
scripts.  It seems to work fine with BitchX and mIRC. Let me know if there 
are problems using it with your particular client.


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
            
            
            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 <id> <password>
            
                 This allows you to recover log files from old detached
                 sessions that you were not able to retrieve.
                 ID and Password refer to the magic number and password
                 of the session whose logs you want to retrieve.
            
            
             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
      There are three configuration options that control this:
   
	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 options 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:


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, although it can be used
if ther user wants. 


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


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 crap 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 command 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. FEATURES YOU NEVER KNEW ABOUT
----------------------------------

   Here are the other commands available in ezbounce:
   
	/quote PASS <password> [server[:port]] [IRC server password]
	
	  Well you knew the PASS 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 your password. You can also provide a port
	  to connect on as well as a password to send to that IRC server.
	  
	
	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. Users can override it, though, by 
	  specifiying a different server through the PASS command.


11. OTHER CONFIGURATION
-----------------------

   For configuration help please look at the sample.conf file
included with the ezbounce distribution. Several other fun configuration
options are awaiting your discovery!


12. ACKNOWLEDGEMENTS
--------------------
  
  Special Thanks to:
    * Seth W. for providing web space and many suggestions.
    * Matt Sams for numerous suggestions (most notably the 'ezbounce'
       command) and testing of potentially dangerous untested code.
    * Jack M. for letting me test on his machine.
    * logiclrd, who presented the fundamental question in 1998 that
       is perhaps the reason for ezbounce's existance today:

	[logiclrd(logiclrd@ts1dl49.escape.ca)] would it be feasible for you to 
						make a bounce server?
    * Karl S. for maintaining the Debian package, writing a man page, and 
       patches.

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

  There is no Win32 port and there probably never will be. Apparently CYGWIN is
no longer free (?)
   
  You don't need to be become admin to reload the config file. Just get the pid
ezbounce and do kill -HUP <pid>.

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

   ezbounce is released under the GPL. The LICENCE file has all the 
details about the license. 

   The author can be reached at druglord@freelsd.org. You might also be able 
to catch me on EFnet with the nick druglord. Comments, questions, bug reports, 
patches, anything are most welcome.

   Unfortunately several animals were harmed during the making of ezbounce. 
This includes one spider and several flies.