Skip to content
janvidarPublic

About

A high performance ADC peer to peer message hub.

Resources

Stars

72 stars

Watchers

15 watching

Forks

Repository files navigation

uhub

CI CodeQL codecov License: GPL v3

uhub is a small, fast, and secure peer-to-peer hub server for the ADC protocol. It lets ADC clients (DC++, AirDC++, and others) meet in a shared space to chat and to search each other's shared files; the actual file transfers happen directly between clients, peer to peer.

It is written in C as a mostly single-threaded, event-driven server with a small memory footprint, and scales from a Raspberry Pi or OpenWrt router up to multi-core machines and linked clusters that present a single logical hub. It supports TLS (OpenSSL or LibreSSL), and its feature set can be extended at runtime with plugins written in C or JavaScript.

Features

  • Efficient — one thread, a hand-rolled event loop (epoll / kqueue / select), and coalesced broadcast writes keep CPU and memory low under load.
  • Secure by default — TLS is available (OpenSSL or LibreSSL) and can be required per hub, passwords are compared in constant time, privileges are dropped and verified, and the wire parser is fuzzed and hardened against untrusted input.
  • Extensible — loadable plugins for authentication, logging, chat history, topic control, flood handling, welcome messages, and more, written in C (mod_*.so) or in JavaScript via an embedded QuickJS engine.
  • Federated — multiple hubs can be linked into a single logical hub with a shared user list, cross-hub routing, and cluster-wide bans (see doc/linking.txt).
  • Observable — an optional Prometheus metrics endpoint exposes counters, gauges, and event-loop timing (see doc/prometheus.txt).
  • Portable — runs on Linux, macOS, and the BSDs.

Who is this for?

  • Communities who want to run their own private or public ADC hub for chat and file sharing among their members.
  • Operators who need a hub that is cheap to host, easy to script with ! commands, and can scale across processes or linked nodes.
  • Developers interested in the ADC protocol, event-driven network servers, or writing hub plugins against a small C plugin API.

For a list of compatible clients, see the Comparison of ADC software.

Building

Prebuilt, self-contained packages for Linux, macOS and Windows (x86_64 and arm64) are attached to each release. TLS and SQLite are linked in, so there is nothing else to install: unpack, then run bin/uhub -c etc/uhub.conf from the unpacked directory. They are not code-signed — see RUNNING.txt inside the package for the one-line macOS Gatekeeper workaround.

To build it yourself, read on.

Get the source either by cloning with --recursive, or by downloading the uhub-<version>-src.tar.gz attached to a release. Do not use the "Source code (zip/tar.gz)" links GitHub generates for a tag: those are produced by git archive, which cannot include uhub's bundled third_party/ submodules, so they are incomplete.

Prerequisites

  • A C compiler (C23) and CMake ≥ 3.21
  • SQLite3 development headers
  • A TLS library: OpenSSL ≥ 3.0 or LibreSSL ≥ 3.4 (mandatory)
  • Perl 5 (used at build time to generate the test driver)

On Debian/Ubuntu:

sudo apt-get install build-essential cmake perl libsqlite3-dev libssl-dev

Build with CMake

git clone --recursive https://github.com/janvidar/uhub.git
cd uhub
mkdir -p build && cd build
cmake ..
make -j
sudo make install    # optional

This produces the uhub binary, the mod_*.so plugins, and the uhub-passwd helper. Useful CMake options: -DRELEASE=OFF (debug build), -DSYSTEMD_SUPPORT=ON, -DADC_STRESS=ON (build the stress tester), and -DUHUB_TESTS=OFF (skip autotest-bin; it defaults to off when the third_party/exotic submodule is absent, so the hub still builds there). To build against LibreSSL when both are installed, point CMake at its prefix with -DOPENSSL_ROOT_DIR=/path/to/libressl.

Build with Zig (self-contained, alternative)

The repository also ships a build.zig that fetches and statically links a bundled LibreSSL and SQLite3, so no system TLS or SQLite packages are needed — only Zig (≥ 0.17.0):

zig build                        # artifacts land in zig-out/bin
zig build -Dsystem-ssl=true      # link host OpenSSL/LibreSSL instead
zig build -Dtarget=aarch64-linux-musl   # cross-compile
zig build test                   # run the test suite

Running

sudo make install puts the sample configuration in /etc/uhub and the plugins where the hub looks for them, so there is nothing to set up first. Reinstalling never overwrites those files: an existing /etc/uhub/uhub.conf and friends are kept as they are, and only the missing ones are written. Start the hub in the foreground (stop it with Ctrl+C):

uhub
# INFO: Starting server, listening on :::1511...

uhub runs with no configuration file at all, and with no plugin configuration it loads a built-in default set — SQLite authentication, logging, topic commands, chat history and user commands. uhub -C prints which plugins a given configuration would actually run.

Give yourself an operator account, or nobody can administer the hub:

sudo uhub-passwd /var/lib/uhub/users.db create   # only needed once
sudo uhub-passwd /var/lib/uhub/users.db add <nick> <password> admin

Then connect an ADC client to adcs://localhost:1511 (use the prefix and the port number). TLS is on by default: the hub creates a self-signed certificate for itself on first start, and prints the address to connect to, including the ?kp= key fingerprint that ADC clients pin. Plaintext adc:// works on the same port, and tls_require=1 refuses it. To run as a background daemon under an unprivileged user:

uhub -f -l /var/log/uhub.log -u nobody -g nogroup

Common options (uhub -h lists them all): -c <file> config file, -C check config and exit, -f fork to background, -l <file> log file, -u/-g drop to user/group, -p <file> write a pid file, -V version.

After editing the config, reload it by sending SIGHUP:

killall -HUP uhub

Operating

  • Configuration — the hub is configured through uhub.conf; every option is documented inline in doc/uhub.conf. Run uhub -s to print the effective configuration.
  • Access control — banned CIDs and denied nicks live in a separate ACL file (file_acl, defaulting to users.conf in the configuration directory); see doc/users.conf. Registered users are not configured there — they belong to an authentication plugin.
  • In-hub commands — operators and users can control the hub from main chat with ! commands. Type !help to see what is available at your level.
  • Registered users — manage the SQLite user database with the uhub-passwd tool (man uhub-passwd), or load mod_selfregister for the !regme / !passwd self-service commands.
  • Plugins — the built-in default set covers a working hub. To depart from it, point file_plugins at a plugins config file; a fully commented example is in doc/plugins.conf. Note that setting it replaces the defaults rather than adding to them.
  • Status messages — the msg_* strings the hub sends to clients can be translated or reworded in a separate file; see doc/messages.conf and the file_messages option.
  • Scaling — for more than ~1024 users, raise the file-descriptor limit (ulimit -n) above the configured max_users. Use workers=N for multi-process mode, or link multiple hubs together for federation.

More documentation lives in the doc/ directory, including doc/getstarted.txt, doc/architecture.txt (the login state machine), and doc/linking.txt.

Contributing

Contributions are welcome!

  • Report bugs and request features via GitHub issues.

  • Submit changes as pull requests against master. Please keep the coding style consistent with the surrounding code, and add or update tests where it makes sense.

  • Build and test before opening a PR. The full test suite is a single binary:

    cd build && make -j && ./autotest-bin

    Because this codebase has a history of bounds bugs in the wire parser, running the test suite under AddressSanitizer is strongly encouraged:

    cmake -DCMAKE_C_FLAGS="-fsanitize=address -g -O1" \
          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address" ..

CI runs the build and test suite on Linux, macOS, and FreeBSD against both OpenSSL and LibreSSL, plus CodeQL static analysis, on every push and pull request.

License

uhub is free software, licensed under the GNU General Public License v3 (see COPYING). It links against OpenSSL/LibreSSL under the terms noted in COPYING.OpenSSL.

Copyright © 2007–2026 Jan Vidar Krey and contributors (see AUTHORS).

About

A high performance ADC peer to peer message hub.

Resources

Stars

72 stars

Watchers

15 watching

Forks

Releases

Packages

Used by

Contributors

Languages