ezbounce v1.04c
- - - - - - - - - - - - - -
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
-
- First, type ./configure. It will gather information about your system.
- Then type 'make'
- 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 addition, 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
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!!