ADCH++ Expert User Guide

ADCH++ is created with very low resource usage in mind so it runs in wide variety of hardware, including even very old computers with fraction of system memory, CPU speed and disk space capacity of today’s standards. Therefore regarding the low level resource usage and connectivity parameters the hub comes with defaults targeting mid to low speed systems. These settings are sufficient for running the hub in many cases, with modest number of users, network traffic and number of shared files. However, in certain situations and use cases where these numbers go higher or to the extreme, some settings should be modified for optimal operation of the hub software.

Sympthoms of resource exhaustion include, but not limited to, cases when the hub becomes laggy (less responsive) with large usercount, users getting disconnected, experiencing extensive login time or failure to login (timeouts) when the hub is running or when (re)started.

There are three kinds of possible resource exhaustions : CPU, memory or network bandwith related ones. With default settings the first two is pretty much unlikely unless you use really ancient hardware to run ADCH++.

The most common cause of problems is (lack of) network bandwidth - the hub is constantly connected to all the users and dynamically allocating network sockets and buffer memory for each client connections. Given the way how DC hubs work their bandwidth usage is usually pretty asymmetric. Most of the traffic is outbound, the hub constantly communicating with the clients and more importantly, brodcasting searches to all clients and relaying connection requests between online clients. In the most common use case relaid search requests are the most significant outbound traffic from the hub to the connected users.

Given that many internet connection speeds are also asymmetric and outgoing ("upload") bandwidth is sometimes much narrower than the other way round, a hub administrator may easily face insufficient bandwith issues running the hub with large usercount. Quality of the connection can be also a big factor for data transfers to run smoothly.

The hub use operating system provided per user buffers allocated in the memory to manage incoming traffic and to store outgoing data until there is available network bandwidth to transmit the information to the client.

If there is too much incoming data that the hub cannot process (possibly due to high CPU usage or slow storage access) then some date will stay in the buffer for longer time than normal - the buffer will eventually overflow and the data flow will stall, some data even get lost resulting errors, timeouts or operation failures in the client side.

Buffer overflows are more likely for outgoing data (due to the bigger traffic in this direction, as explained earlier) when the outgoing network bandwidth getting exhausted for longer periods of time, the connection quality is bad throughout the network route to the client or when the client can’t process the sent data (in time).

ADCH++ therefore implements an additional dynamic outgoing per user buffer internally in its core as a strategy to combat against and ameliorate outgoing traffic peaks, overflows and data loss situations. This buffer is created and used when the fixed size socket buffer is already full.

There’s no hard size limit on this additional buffer but there is a configurable maximum size value (MaxBufferSize) and as long as the size of the stalling data to be sent is bigger than this value, the user will be marked internally as "overflowing". Also configurable a time value, a maximum period of time in which the hub allows a user to be in overflowing state (OverflowTimeout). After this period the user will be disconnected to save hub resources.

At last, you can also configure how much percent of the total online usercount can possibly be in an overflowing state (OverflowLimit), When this percentage value is reached the hub will refuse to accept new user logins until the value goes back under the limit you set.

Low level network connectivity parameters can be configured in the <Settings> node in the adchpp.xml configuration file. The sample file within the package contains all the default settings and also brief comments explaining their meaning and use. Read these comments carefully to understand the effects of the various configurable parameters.

Most times increasing socket read/write buffer sizes (<BufferSize> parameter) and the write overflow size limit (<MaxBufferSize> parameter) should solve connectivity issues and lags but as a consequence the hub will allocate more memory per user. So be careful with these settings otherwise you may force the hub to use too extensive memory.

The default buffer size values should be fine up to 50-100 hub users in a normal setup. However, the quality of the hub connection and increased per user traffic (e.g. large user commands, heavy shares, frequent searches etc…) may require a fine tuning of these parameters to avoid issues explained earlier.

The hub may disconnect users or refuse new users to login when and until certain percent of the total usercount’s outgoing connection is stalling (their outgoing socket buffers have overflown). This can reportedly be a problem in case of low quality or low bandwith hub connections, especially when large amount of users connecting to the hub in a short timeframe, for example, when you (re)start the hub. Increasing socket buffer sizes can fix these particular issues.

The maximum percentage of users allowed being in "overflowing" state is also configurable. This way the hub can be set up to be more graceful to the connecting users with the cost of intermittent higher memory usage periods. If you experience the above problems above you should try to find the best percentage value that is fixing the issue but not endangering the stability of the hub by exceeding the available free system memory.

You can also combine this approach with slight buffer size increases as feasible to get the optimal bargain. When you increasing the ratio of allowed buffer overflown users parameter (<OverflowLimit> in adchpp.xml), you may need to increase both the login (<LogTimeout>) and the owerflow (<OverflowTimeout>) timeout parameters as well to avoid mass refusing or dropping users.

Beware that large changes compared to the default values or specifying incorrect settings can easily render your hub unusable. Experiment with relatively small changes, change to only 1,5 or 2 times higher of the previous value at a time in a hope that it’ll fix the problem but remain as light as possible with the hub’s resource usage.

You always need to restart the hub for changes in these parameters to take effect. It is also advised to make a backup of the settings file before start experimenting.

ADCH\++ comes with a plugin that implements search filtering using a mathemathical model called Bloom filter. Bloom filters allow the hub to filter certain searches using some stored data that represents the hashes of the files in the users' share. The plugin allows the hub to create a map of the hashes of the shared files on the hub side, but with minimal effort, e.g. the hub doesn’t keep the full list of file hashes, but a small filter binary that, when queried, never produces false negatives but only possible false positives. This can potentially save bandwidth and resources on the client side. At login time and also later when users update (re-hash) their share, the hub, provided the Bloom plugin is enabled, will get and apply the updated filter binary arrived from Bloom supporting DC clients.

The Bloom filter plugin is enabled by default. You can enable or disable it just like other plugins as described in the Basic configuration part of the Basic User Guide.

As explained earlier the largest part of the hub connection bandwidth is used by the outgoing data of search requests, especially hash queries, relayed to all online users. The Bloom plugin tries to ameloriate the bandwidth usage of exactly that kind of requests by not passing searches to any Bloom supporting clients that don’t share the file in case, at the time. In a large hub with many active users the amount of bandwidth saved this way can be quite significant and it results potentially less resource usage at client side as well.

There are slight downsides and special behavior of this useful feature though: firstly, there’s additional bandwidth usage when clients sending their filter binary. It is an incoming data tough and incoming (download) bandwidth of the hub connections is usually plenty. A filter binary’s expected size is roughly 1,5 times of the number of shared files in client side, in bytes.

Bloom filters also require additional RAM usage of the hub as filters are stored in the memory. On the other hand, repeatedly arriving filters from the same user replaces the earlier filter so only one filter per user is stored at a time.

If you expect users sharing high number of files (10000+) visiting your hub then you most probably need to increase the sockect buffer size above the default values in order to keep using the Bloom plugin. This will help processing large incoming fliters and avoid user login issues, stalling, delays and disconnects (see the previous chapter for details).

As explained earlier the filter is getting updated when the number of files in the users' share are changing. This, though, does not include cases when only already shared files are changed by the user in any way (for example text file edits). Therefore these changes will not be reflected in the filter the hub stores and this may render these small changes unsearchable until the next major share change or a user re-login happens. Therefore on commumities where this kind of small changes often happen (a hub for collaborative work, etc…) use of the plugin’s is not recommended.

As a summary, you find the most frequent use cases and suggested resource usage setup actions in a tl;dr style table as follows:

Connection to hubs can be unsafe in many ways and hardening the security as much as possible without sacrificing usability is always an advantage. The most common way of attack is, for example, to take the ownership of the hub address domain and divert the connected clients elsewhere. Keyprint adds a simple, but secure, way to protect against man-in-the-middle attacks, ensures that clients are always connecting to the hub they desire and not to some other maliciously set up DC hub. It is also an easier-to-use replacement of trusted certificates.

Publishing your hub’s address with keyprint included is therefore allows the users to connect to the hub more securely. The keyprint itself is a BASE32 encoded value of the SHA256 hash of the server certificate file cacert.pem. You can get your hub’s keyprint value in the following ways:

Keyprint is sent to every capable DC client when they’re connecting to an ADCH++ hub. Once connected, some of the DC clients are capable to produce the complete hub address, with the keyprint value added, usually by an item in the context menu of the hub tab (this can vary client by client). This way the owner or even any user of a secure ADCH++ hub can easily get and use a keyprint-included hub address to connect to the hub more securely.

Even if your DC client is unable to show keyprints, you can determine the hub’s keyprint value yourself. You need a hash generator tool to get the SHA256 hash of the certification file (cacert.pem). There are plenty out there and some may even come with your operating system. The OpenSSL binary is also capable of producing this hash value by using the command

It will output the hash in following hexadecimal format:

You need to BASE32 encode the resulting hexadecimal value to get the keyprint. There are also plenty of online converting tools out there for this conversion, for example, this one. The conversion will result an encoded string similar to the following:

Once you’ve created your hub’s keyprint you can publish it as a part of your hub address URL. The keyprint parameter consists of a hash name, followed by a forward slash (/), followed by the generated keyprint.

When DC clients that support keyprint (most which supports the latest version of the ADC protocol should do) trying to connect to your hub using an address with the keyprint parameter specified, they will now compare the hash value what your hub sends to the public keyprint and refuse to connect if they mismatch.

The only caveat of using hub addresses with keyprint is that it obviously needs to be recreated once your certificate changes or becomes invalid. Since keyprint is part of the hub URL that clients may save as favorites, a certificate change may prevent some users connecting to the hub until they also change or remove the old keyprint from the saved hub address. To avoid this you can generate a new certificate that is valid for several years before you publish your hub address with a keyprint included. The basic ADCS setup part of the Basic Guide describes how to change the validity time of the generated cerificate.

Since version 3.0.0 ADCH++ requires TLS protocol version 1.2 or later by default for hub connections. The accepted TLS version and two other secure connection parameters can be altered so hub administrators can set up secure connectivity suitable for their needs. Ths can be done by adding extra parameters for each <Server> connection item in the <Servers> node of the adchpp.xml settings file. The following parameters are available:

You have to restart the hub for these changes to take effect.

This part shows how to achieve spam, badword or badsearch protection as well as how to protect the hub’s normal operation from malicious or accidental flooding or misuse.

The following command line parameters are available when starting ADCH++ from the command prompt / shell:

TIP:Installing ADCH++ as a service requires the command to be run as Administrator in an elevated command prompt window otherwise UAC will interfere with the process.

This is how it looks when launched without proper rights:

You elevate adchpp.exe in Windows the following way:

To verify that your ADCH++ service is correctly installed under the name you specified go to Control Panel\System and Security\Administrative Tools and start the "Services" application or simply run "services.msc" command from a Windows prompt.

Once the Sercvices configuration window opened you can find your adchpp service in the list:

The initial aim of this project was to create a reference implementation of the ADC protocol. The core application is simple, fast, low on resources and made highly extensible with modules to be able to implement feature additions for various use cases that is out of the scope of the project. The core can be exposed to modules written in many programming languages. C++, Python and Ruby interfaces are implemented and two plugins written in C++ (Script and Bloom) are included in the /plugins folder of the package and used to provide the hub management functions and features and also to serve as examples.

The current version of ADCH++ supports the following ADC protocol extensions:

BLOM - this extension that allows hub software to create a map (bloom filter) of the shared files on the hub, but with minimal effort, e.g. the hub doesn’t keep a list of files, but a filter that never produces false negatives but only possible false positives. This can potentially save bandwidth and effort on the client side.
UCMD - User commands are used to send hub-specific commands to the client which provide useful shortcuts for the user.
ADCS - ADCS is an extension that has the goal of adding the TLS/SSL layer just over the TCP layer and beneath the application layer (where ADC runs). This way, the ADC protocol remains unchanged while the connections are encrypted.
PING - This extension can be supported by both clients and hubs, and when present, if hub supports it, it must send additional information to the client.
FO - If a hub goes down, the client’s only option is to keep re-trying the last known hub address. This extension will add a list of failover hub addresses, field FO, that the client can try to connect to, if the main hub address fail.

Like most software ADCH++ can also contain flaws or bugs, may preform weird or contain unwanted features. It’s important to make the developers aware of such problems. If you want to help improving ADCH++ you can file your helpful feedback to the developers about bugs found, helping to reproduce and fix these problems. Many times, to be able to help solving found issues, you must run a debug build of ADCH++. If you are on Windows and cannot compile ADCH++ in debug mode you can download nightly debug builds from the adchpp folder at DCBase Builds Archive or ask for a recent one in the dev hub at adcs://hub.dcbase.org:16591. Otherwise please follow the compilation guide provided in this document on how to build ADCH++ in debug mode.

The differences between debug and release builds are as follows:

This is how the console output of a debug build looks

When you encounter a crash you can help the development by reporting the bug to the official bug tracker.

To be able to analyze and solve a crash problem the developers need the following information:

ADCH++ should build on wide variety, even ancient systems. These are the minimum versions of tools required to compile ADCH++:

On Windows, MinGW packages by the MinGW-w64 project are preferred. The project is currently using these 2 packages by the MinGW-w64 project for official releases :

To build ADCH++ from source you have to:

The maintainers do accept patches in general for every part of the application, but in order to avoid future licensing issues, you’re asked to give the author the copyright over any submitted code. Make sure that the code doesn’t break support for any of the platforms supported and that it looks more or less like the rest of the code (indent, names etc). Patches should be sent to the dcplusplus-devel mailing list or to the official bug tracker at Launchpad. Please use unified patches against the latest Mercurial trunk (ie. hg diff) and supply a description of what the patch does.