ezbounce v2.0 - - - - - - - - - - - - - - - Last updated: $Date: 2008-04-27 16:57:02 -0500 (Sun, 27 Apr 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] A configuration file must be specified. The following command line options are also recognized: -f: stay in the foreground -b
: 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 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 [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 Displays information about a user. * KILL Kicks a user off the proxy. * TRACE Shows a text diagram of a user's connection. * DIE Kills the proxy gracefully. * DIENOW 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 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. 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 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 This sets the certificate file. You can generate one by using the scripts in the tools/ directory. ssl-listen 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 [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 [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...