Getting started guide
---------------------

Build uhub from source

uhub is distributed as source code -- there are no prebuilt binaries.
You will need a C compiler, CMake, SQLite3, and a TLS library
(OpenSSL >= 3.0 or LibreSSL >= 3.4). TLS support is mandatory.

On Debian/Ubuntu the build dependencies can be installed with:

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

Unpack the source and enter the directory:

  % tar xzf uhub-0.6.1-src.tar.gz
  % cd uhub-0.6.1

Configure and build (out-of-tree):

  % mkdir -p build && cd build
  % cmake ..
  % make -j

This produces the uhub binary (along with the mod_*.so plugins) in the
build directory. Install it to /usr/local/bin:

  % sudo make install

Or copy the binary by hand:

  % sudo cp uhub /usr/local/bin

Building with Zig (alternative)

The repository also ships a build.zig, which is more self-contained: it
fetches and statically links bundled LibreSSL and SQLite3, so no system
TLS or SQLite development packages are required. You only need Zig
(>= 0.14.1); get it from https://ziglang.org/download/.

  % tar xzf uhub-0.6.1-src.tar.gz
  % cd uhub-0.6.1
  % zig build

The artifacts (uhub, the plugins, and helper tools) are placed in
zig-out/bin. Useful options:

  % zig build -Drelease=false      # debug build
  % zig build -Dsystemd=true       # systemd notify + journal logging
  % zig build -Dsystem-ssl=true    # link the host OpenSSL/LibreSSL instead
  % zig build run                  # build and launch uhub
  % zig build test                 # build and run the autotest suite

Because Zig bundles its own cross-compiling toolchain, you can build for a
different platform by passing -Dtarget. For example, to produce a static
Linux binary for ARM64 or a 64-bit Windows binary:

  % zig build -Dtarget=aarch64-linux-musl
  % zig build -Dtarget=x86_64-windows

Create configuration files.
If no configuration files are created, uhub will use the default parameters, so you can skip this step if you are in a hurry to see it run.

As root, or use sudo.

  % mkdir /etc/uhub
  % cp doc/uhub.conf /etc/uhub
  % cp doc/users.conf /etc/uhub
  % echo "welcome to uhub" > /etc/uhub/motd.txt

Start the hub in the foreground for the first time. Shut it down, by pressing CTRL+C.

  % uhub
  Thu, 05 Feb 2009 00:48:04 +0000 INFO: Starting server, listening on :::1511...

Connect to the hub using an ADC client, use the address adc://localhost:1511, or replace localhost with the correct hostname or IP address.
NOTE: It is important to use the "adc://" prefix, and the port number when using DC++ and other ADC clients.

If you modify the configuration files in /etc/uhub you will have to notify uhub by sending a HUP signal.

  % ps aux | grep uhub
  % kill -HUP <pid of uhub>

Or, for the lazy people

  % killall -HUP uhub

In order to run uhub as a daemon, start it with the -f switch which will make it fork into the background.
In addition, use the -l to specify a log file instead of stdout. One can also specify a specific user and/or group, 
if one wishes to run uhub as a specific user using the -u and -g switches.

Example:

  % uhub -f -l mylog.txt -u nobody -g nogroup

If you are planning to more than 1024 users on hub, you must increase the max number of file descriptors allowed.
This limit needs to be higher than the configured max_users in uhub.conf.

In Linux can add the following lines to /etc/security/limits.conf (allows for ~4000 users)
      *     soft nofile 4096
      *     hard nofile 4096

Or, you can use (as root):

  % ulimit -n 4096

You can interact with uhub in your hub main chat using the `!` prefix, followed by a command:

Example :

      *     to display help and the command you can use:
            !help

To monitor uhub with Prometheus, uhub can expose its counters and gauges over an
HTTP/HTTPS endpoint on the regular server port. See doc/prometheus.txt for how to
enable it and point a Prometheus server at it.

Your mileage may vary -- Good luck!
