This is the "README" file for DCBouncer. It contains the following sections:

1) What is DCBouncer?
2) Installing and running DCBouncer
3) A concrete usage example
4) Contact the author

--- 1) What is DCBouncer? ---

Project page: <https://launchpad.net/dcbouncer>.

DCBouncer is a bouncer / proxy for Direct Connect networks (used by DC++). It's a little program
that you start up on your remote server, and that stays connected all the time to your favorite
hubs. Instead of connecting to the hub directly, you connect to DCBouncer (residing on your remote
server) and DCBouncer connects to the hub. DCBouncer then ensures communication between you and the
hub. While you are offline, DCBouncer stays connected to the hub and it logs messages that you
miss; then when you log back in, it forwards them all back to you.

DCBouncer supports both the ADC <http://adc.sourceforge.net> and the (old) NMDC protocols.
DCBouncer supports secure TLS connections.

DCBouncer uses:
- Anders Hedström's C++ Sockets Library <http://www.alhem.net/Sockets/> for its networking functions.
- Jacek Sieka's DC++ <http://dcplusplus.sourceforge.net> for some ADC functions.

--- 2) Installing and running DCBouncer ---

The download page at <https://launchpad.net/dcbouncer/+download> contains:
- The source code, which you can compile following instructions in the "COMPILING" file.
- A pre-compiled executable for Windows.

Pre-compiled Linux packages are available on
<https://build.opensuse.org/package/show/home:poy:DCBouncer/DCBouncer>.

When installed, you should have the following 2 files:
	bin/DCBouncer: Binary file to run the DCBouncer daemon.
	etc/DCBouncer: Configuration file to edit with a text editor.

On Windows, the configuration file is first etc/DCBouncer_default.txt; edit it with a text editor
then rename it to etc/DCBouncer.txt.

Here is more information about what each mandatory option of that configuration file means:

	LISTENING_PORT: The port that DCBouncer will be listening on for incoming connections from your
	client. In your client, just connect to protocol://address_of_your_server:LISTENING_PORT (where
	"protocol" is either "dchub" or "adc" on DC++ and "address_of_your_server" is the address (IP
	or domain name) of the server on which this	DCBouncer is running) to reach DCBouncer, and
	through it, the remote hub. Note that if you want DCBouncer to handle multiple hubs
	simultaneously, each LISTENING_PORT has to be different from one another.

	HUB_ADDRESS: The address (IP or domain name) of the remote hub.

	HUB_PORT: The port number of the remote hub.

	OK: Mandatory line that tells DCBouncer that the profile for one hub has now be set.

Additionally, you may use the following options to customize each profile (add them before "OK"):

	PASS (facultative): The pass of your account on the remote hub. Must be defined for ADC hubs.

	OFFLINE_DESCRIPTION (facultative): If not empty, your description changes to the specified
	message and your share size to 0 when you go offline (when the connection between your client
	and DCBouncer dies). If a percent sign ('%') is found, it is replaced by the number of hours
	since the last disconnection. Defaults to "Offline for % hours (DCBouncer logging)". You might
	want to disable this (by specifying "OFFLINE_DESCRIPTION=") in some (old) NMDC hubs that limit
	the amount of information about yourself that you are allowed to send.

If you want DCBouncer to proxy multiple hubs, just copy-paste that list of options (from
"LISTENING_PORT" to "OK") as many times as you want.
Keep in mind that each hub definition must have a different "LISTENING_PORT" number.

---
DCBouncer accepts one command-line argument: the path to its configuration file. If not specified,
"../etc/DCBouncer" is used by default.

--
DCBouncer caches data in the "../var/DCBouncer/data" directory. It creates one directory for each
listening port. Delete the directory if necessary (such as after a configuration change).

---
Most of the following instructions apply to POSIX systems; for Windows, all you have to do is run
DCBouncer.bat. For the sake of licensing, note that the source code for the DLLs included in the
Windows package can be found on <www.cygwin.com>.

---
To run DCBouncer on auto-start, I add in my "/etc/rc.local" file:
	/usr/local/bin/DCBouncer

---
DCBouncer adds a "DCBouncer" sub-menu in your client's hub-related user commands. Current commands:

	[Reconnect the hub] Tells DCBouncer to disconnect the connection it has been maintaining with
	the remote hub; DCBouncer will then try to restore that connection as it always does.

	[Restart DCBouncer]
	[Quit DCBouncer]

---
DCBouncer runs as a daemon; as a result, the process used to start it will just fire up the daemon
and exit immediately, without displaying any message in the console. Instead, DCBouncer logs its
messages to the standard /var/log/messages place.

To exit DCBouncer, the easiest way is to use the above "Quit DCBouncer" user command. Otherwise,
you're going to have to kill the corresponding process:
	ps aux | grep DCBouncer (gives you the process ID of the process you want to kill.)
	kill PID (where PID is the process ID found above.)

--- 3) A concrete usage example ---

I like to connect to <adcs://hub.dcbase.org:16591>, the DCDev hub. In the past, I simply entered
that address in my DC++ to connect to it.

I have a server on <example.com>. I have installed DCBouncer there, under /usr/local.

My configuration file for DCBouncer (/usr/local/etc/DCBouncer) contains:
LISTENING_PORT=5200
HUB_ADDRESS=hub.dcbase.org
HUB_PORT=16591
PASS=my-pass
OK

From my server, I run DCBouncer (by running /usr/local/bin/DCBouncer, or in my case, by making it
auto-start when the server starts).

On my local computer, I open up DC++ and I edit the properties of the favorite hub entry
corresponding to the public DCDev hub; I change the address to:
	adcs://example.com:5200

So I don't connect to the remote hub directly anymore; instead, I connect to the proxy (DCBouncer)
which is running on my server. That proxy then connects to <adcs://hub.dcbase.org:16591>.

--- 4) Contact the author ---

Feel free to use the Launchpad interface for this project <http://launchpad.net/dcbouncer> or
e-mail me directly <poy@123gen.com> for any feedback / suggestion / bug.
