# ADCH++ Basic User Guide

Created by the DC++ team
Document Version 0.3.5

This version of the guide corresponds with ADCH++ versions 2.9.x and later.

## 1. Introduction

ADCH++ is a hub server software for the ADC network. It implements the ADC protocol. The core application is very simple, but extensible using plugins. Among the standard plugins there is a scripting plugin that allows hub owners to further customize the hub using the Lua scripting language. The core is also exposed as a Python and a Ruby module, thus it is possible to use it within a Python or Ruby application.

## 2. Preface

This basic guide shows you how to do the minimum configuration, setup and administration of an ADCH++ hub. It contains the basic information required for newbies.

## 3. Installing ADCH++ on your Operating System

This part describes the installation procedure of ADCH++ under Linux and Windows.

### 3.1. Installing on Windows

ADCH++ needs Windows XP SP3 or later to run.

Before you go on you have to decide whether you want to run a debug or a release build of ADCH++. For normal usage the best choice is the release build which is available prepackaged for download in the official ADCH++ home page.

The differences between debug and release builds are as folows:

- Debug builds are bigger and slightly slower as they contain additional information for debugging

- The console output of a debug build is more verbose as it shows the software and the protocol at work (like session ids, messages, etc.)

- In case of problems (crashes, abnormal behavior) debug builds are able to provide vital information for the developers (crashlog)

This is how the console output of a debug build looks

This is how the console output of a release build looks

ADCH++ release packages are available to download at the official home page at SourceForge (http://sourceforge.net/projects/adchpp). At the download page you can find the three ADCH++ distribution files:

- Windows installer - a complete installer EXE file for Windows with uninstaller option.

- ZIP package - contains the pre-compiled binaries (release build) for Windows with all the required scripts and configuration files.

- Source code - an archive with the source code of the latest release distribution. You can use it to compile ADCH++ under other operating systems or for those who want to modify and compile the source themselves.

The easiest choice is the executable installer, when you start the installation you’ll go through the following steps:

1. Welcome Screen

2. Set up the installation Path:

| on Windows Vista and Windows 7 you should install ADCH++ to the Program files / Program files(x86) directory only if you familiar with UAC Data Redirection and its effects and how to store configuration files in the user profile path’s specified by the windows environment variables. If you don’t want to be bothered with this then the best choice is to install/unpack ADCH++ files to another folder outside of Program Files where UAC rules don’t apply. A good alternative path is: c:\Users\<Your Username>\

As the last step of the installation procedure you’ll be asked if you want to install ADCH++ as a service or not. The main difference between installing ADCH++ as an applciation or as a service is that in application mode the ADCH++ console window will be always visible. This can be an advantage as you always able to ensure the hub is there, up and running and you can easily stop the hub anytime. On the contrary, as the console window cannot be closed (only minimized) it will always reside on your taskbar which can be annoying for some users. If ADCH++ is running in service mode then you won’t see any opened console window and outputs will go to the log file only. In this mode you can start and stop the hub in the Windows Service Management Console or using the appropriate shell commands. You can find more detailed information about running ADCH++ in service mode in the Expert User Guide.

### 3.2. Installing on Linux

Installing on Linux/Unix operating systems requires the source code for ADCH++ since we don’t provide any prepackaged binaries for Unix/Linux distributions. The source code is available via Sourceforge (official releases) or from our Bazaar repository at Launchpad.

Source code download: https://sourceforge.net/projects/adchpp/files/

Launchpad repository: https://code.launchpad.net/adchpp

You need a Linux distribution with at least 2.6-based kernel to run ADCH++. The following tools needed to compile and install ADCH++ on a Linux/Unix machine.

Table 1. Installation tools
Application | Notes
--- | ---
swig |
ruby (optional) | (needs to be version 1.9.2 or higher)
python (optional) | (version 2.4.x … 2.7.x, 32 bit versions - even on 64 bit systems)
scons | (version 1.2.0 or higher)
gcc-c++ | (version 4.4.x or higher)
libstdc++-devel | (redhat resource)
readline-devel | (redhat resource)
libreadline-dev | (debian resource)
sys-libs/readline | (gentoo resource)
openssl-devel | (redhat resource)
libssl-dev | (debian resource)

If you have downloaded any of the zip archives then unpack the source to a folder. If you used Bazaar to fetch the source then navigate to the root folder of your local branch or checkout. After you have installed the tools necessary to compile, perform these actions in a command prompt or save the it as a shell script (<file.sh>) and run it as sh <file.sh>.

    [source,bat]
    cd adchpp
    scons
    cd build/release-default/bin/
    mkdir config
    mkdir scripts
    cp -rf plugins/Script/examples build/release-default/bin/scripts
    cp -rf etc/ build/release-default/bin/config
    /.adchppd

1. Enter the ADCH++ directory.

2. Start the compile of ADCH++.

3. Enter the bin directory and create the two folders.

4. Copy files to bin folder.

5. Start ADCH++.

## 4. Setting up your hub

This part focuses to the basic configuration of the hub describing how to manage and setup ADCH++ for operational use.

### 4.1. Basic configuration

ADCH++ is configurable using an XML settings file as are the standard plugins. In Linux, the default location for configuration files is "/etc/adchpp/". In Windows, it is a directory named "config" under the program directory. All ADCH++ settings are stored in a file called adchpp.xml. The default packaged file contains lots of comments to help you get started. Open up adchpp.xml in a text editor (such as Notepad under Windows) and start changing the values as you wish.

| Editing the values incorrectly can lead to problems so be careful what you’re doing. If the settings file doesn’t meet the XML standards it may won’t be processed correctly.

Table 2. Main parts of the ADCH++ configuration file
String | Purpose
--- | ---
HubName | Name of your hub
Description | Hub description
Server | Connection and port settings
Plugins Path | Path to plugins (Linux only)
Plugin | List of plugin engines

| Linux users should uncomment the following line in adchpp.xml <!--Plugins Path="/home/arnetheduck/adchpp/lib/adchpp/"-→ by removing !-- and — from the line and must modify the path to the actual adchpp directory. Under Linux, as like in each and every path setting in ADCH++, you must specify absolute path.

### 4.2. Setting up ports

Add a new <Server/> entry to adchpp.xml with the port you wish your hub to listen to. You must put a line similar to the following into the Servers part of the config file, between the <Servers> and </Servers> nodes.

Example:

    [source,xml]
            <Servers>
                    <Server Port="2113"/>
            </Servers>

In this example you will use the address adc://yourdomain:2113 in your DC client to log on to your hub.

To be able to connect to your hub in a secure encrypted way (ADCS connections), set TLS="1" and specify the following path’s: Certificate, PrivateKey, TrustedPath, DHParams.

| Linux users should always use absolute path’s in this setting.

An example of an encrypted server setting:

Example: insert this to the Server line in adchpp.xml:

    [source,xml]
            <Servers>
                    <Server Port="2780" TLS="1" Certificate="certs/cacert.pem" PrivateKey="certs/privkey.pem"
                    TrustedPath="certs/trusted/" DHParams="certs/dhparam.pem"/>
            </Servers>

In this example you will use the address adcs://yourdomain:2780 in your DC client to log on to your hub.

To make the SSL encrypted connectivity possible you must generate three security certificate (.pem) files for your hub (see the example above). You need to install OpenSSL to generate your cert files. The .pem files must be located in their path specified in the <Server …> settings to be able to make ADCS connections to the hub.

Table 3. How to get OpenSSL (needed for certificate generation)
Distribution | Command
--- | ---
Windows | OpenSSL for Windows
Debian | sudo install apt-get openssl
Redhat | yum install openssl

To automatically generate files and place them to the deafult path you can use the certificate files generator script (generate_certs.cmd/sh) provided in the ADCH++ release package. Alternatively you can download the script corresponding to your operating system (Windows or Linux) from the ADCH++ code repository as well.

The script will create and automatically place the generated certificate files to a folder named certs under the ADCH++ program folder.

| If you run the certificate files generator script under Windows it is recommended to install OpenSSL to its default folder (or into C:\Program Files\OpenSSL) and run the script in elevated mode (as Administrator) on Vista and later.

Alternatively you can generate the .pem files manually using the following commands:

Simple commands that use OpenSSL to generate certificate files for encrypted connections

    [source,bat]
    openssl genrsa -out privkey.pem 2048
    openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
    openssl dhparam -outform PEM -out dhparam.pem 1024

| Remember if you have specified TLS=1 in the server configuration, all users must connect to your hub using the prefix adcs:// added to the hub address (adcs://yourdomain:port). You can open more than one ports for your hub by adding more <Server/> entries. You can even mix secure and unsecure (non-TLS) port connections by adding TLS=1 parameter to a particular <Server/> entry only.

### 4.3. Script Management

Above the basic functions provided by the core ADCH++ relies on scripts performing various extended functions and commands (like handling registered users, login procedure, etc…). The hub software comes with prepackaged LUA scripts for handling basic hub functions and more. These (and any other) scripts can be configured using the Script.xml file located in the configuration folder of ADCH++.

The LUA scripts shipped with ADCH++ are configured to run by default. They should be always properly loaded to get the functionality described in the rest of this guide. If you want to use additional scripts then locate the Script.xml file and ensure that the scripts that you want to run are properly added to the existing ones.

Example: Default Script.xml, it loads the core LUA scripts, a chat history script and a MOTD script.

    [source,xml]
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <ScriptPlugin>
            <Engine language="lua" scriptPath="Scripts/">
                    <Script>access.lua</Script>
                    <Script>access.bans.lua</Script>
                    <Script>access.guard.lua</Script>
                    <Script>access.op.lua</Script>
                    <Script>access.bot.lua</Script>
                    <Script>history.lua</Script>
                    <Script>motd.lua</Script>
            </Engine>
    </ScriptPlugin>

Here’s how to disable a script in scripts.xml using the xml comment syntax:

Example: scripts.xml, we want to remove the MOTD script

    [source,xml]
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <ScriptPlugin>
            <Engine language="lua" scriptPath="Scripts/">
                    <Script>access.lua</Script>
                    <Script>access.bans.lua</Script>
                    <Script>access.guard.lua</Script>
                    <Script>access.op.lua</Script>
                    <Script>access.bot.lua</Script>
                    <Script>adchpp-ptokax.lua</Script>
                    <Script>history.lua</Script>
                    <Script>motd.lua</Script>
            </Engine>
    </ScriptPlugin>

Change to :

    [source,xml]
    <?xml version="1.0" encoding="utf-8" standalone="yes"?>
    <ScriptPlugin>
            <Engine language="lua" scriptPath="Scripts/">
                    <Script>access.lua</Script>
                    <Script>access.bans.lua</Script>
                    <Script>access.guard.lua</Script>
                    <Script>access.op.lua</Script>
                    <Script>access.bot.lua</Script>
                    <Script>adchpp-ptokax.lua</Script>
                    <Script>history.lua</Script>
                    <!--Script>motd.lua</Script-->
            </Engine>
    </ScriptPlugin>

| Linux users should use absolute paths pointing to the script folder in every <Script> entries.

You have to use the +reload command or restart the hub to changes take effect.

### 4.4. Setting up MOTD (Message of the day)

MOTD is a message that appears for every user in the main chat after a successful login. If you want to show something to your users then ensure that motd.lua is added to scripts.xml. The actual MOTD is stored in a file called motd.txt in the configuration folder. If the file doesn’t exist then just create a text file called motd.txt in that folder and add your content.

## 5. Additional configuration

There are additional settings and rules that can only be altered using hub commands. The hub settings are stored in a file called settings.txt. Ensure that this file exists in your configuration folder and its read/write accessible. If the file doesn’t exist then its best to create an empty file with the name above and appropriate rights before proceeding.

### 5.1. Account Creation

Registered users information are stored in a file called users.txt in your ADCH++ configuration folder. Ensure that this file can be read/write accessed by ADCH++. Now you can create your first admin account for your own hub.

The LUA scripts shipped with ADCH++ use numbers to specify user profile levels. The available profile level range is from 1 to infinite. By default level 3 and higher users are operators so you have to choose at least level 3 or higher for your own administrator account. If you want to build a bigger user/operator hiearchy then make sure you choose high enough level (eg. 10) for your admin account.

There are two possible ways to create the first administrator account:

#### 5.1.1. Create the admin account using the FirstReg.cmd shell script (Windows only)

You can use a small shell script to easily create your first admin account. The script called FirstReg.cmd and its provided in the release packages. To use it you must stop the hub before, then open up a Windows command prompt, navigate to and run the script from the ADCH++ program folder. Follow the onscreen instructions.

| The FirstReg script is for creating the initial admin account ONLY. Its not usable to create subsequent accounts as it deletes all existing registrations before creating the initial account!

If your account successfully created with the script you can skip the next chapter.

#### 5.1.2. Create the admin account manually (all OSes)

To create an administrator super user account for yourself start up the hub, log on and enter the following command:

    +regme <your desired password>

Example: Registering yourself

    [09-10-02][21:37:19] *** Connecting to adc://somehub.com:411
    [09-10-02][21:37:19] *** Connected
    [09-10-02][21:37:19] <ADCH++> MOTD content goes here
    [09-10-02][21:37:56] <Testuser> +regme test
    [09-10-02][21:37:26] <ADCH++> You're now registered

This will create a level 1 registration. Now stop the hub by pressing Ctrl-C in the hub console window (or stop the service if you use service mode). In order to elevate this first registration as an administrator account you must open up the users.txt file in a text editor.

Example: users.txt

    [{"password":"test","nick":"Testuser","level":1,"cid":"ABCDEFGHIJ1KLMNOPQRSTUVXYZA23BCDEFGHIJK"}]

Change the user level to your desired admin level (eg. 10):

    [{"password":"test","nick":"Testuser","level":10,"cid":"ABCDEFGHIJ1KLMNOPQRSTUVXYZA23BCDEFGHIJK"}]

Save the file and start the hub.

#### 5.1.3. Adding new registrations as administrator

Set up your newly created admin account in your ADC client software and reconnect to the hub. Now you have full access to all the administrator commands. You can register new administrators, operators and users. Use the command:

    +regnick <nick> <password> <level>

You can create registrations / get information only for accounts with lower user level than you. This is true for users with subsequently lower level as well so you can easily specify the administators' hiearchy by registering operators between the operator level (3 by default) and the superuser level. You should register normal users with lower level than the operators (1 or 2).

1. registered user at the hub

2. registered vip user at the hub

3. registered as a basic op

4. …

You can list all (or a subset of) registered users with the +listregs command.

### 5.2. Administration Setup

This chapter shows you how to administer your hub using hub commands and settings.

#### 5.2.1. Basic hub commands

A simple way to find out what commands are available and how they work is to use the +help command. To get information for a specific command use

    +help <command>

TIP:For <command> you can use partial names or abbreviations to get a list of available commands contaning the specified string in their names. Most commands are also available in the user menu of the connected ADC clients propagated as user commands. Here’s the list of the basic hub commands, those where mentioned are available for all users, the rest are for operators only.

Table 4. List of all commands
Command | Purpose
--- | ---
+ban nick [reason] [minutes] | Ban an online user. Use 0 for minutes to remove the ban.
+bancid CID [reason] [minutes] | Ban a CID. Use 0 for minutes to remove the ban.
+banip IP [reason] [minutes] | Ban an IP. Use 0 for minutes to remove the ban.
+bannick nick [reason] [minutes] | Ban a nick. Use 0 for minutes to remove the ban.
+cfg name value | Change hub configuration, use "+help cfg" to list all variables.
+help [command] | List all available commands, or display detailed information about one specific command. This command is available for everyone.
+history [lines] | Display main chat messages logged by the hub (empty lines means default / since last logoff) This command is available for everyone.
+info [nick or CID or IP] | Get information about a user or about the hub if no parameter given. This command is available for everyone.
+kick user [reason] | Disconnect the user, she can reconnect whenever she wants to.
+listbans | List the saved bans.
+listregs [string] | List the hub’s registered users, optional nick substring parameter for filtering results.
+loadbans | Reload the ban list.
+mass message [min-level] | Send a mass message to the specified user levels and higher. Empty parameter means send to everyone.
+mute nick [reason] [minutes] | Mute an online user. Use 0 for minutes to allow the user to talk again.
+myip | Show your IP. This command is available for everyone.
+mypass new_pass | Change your password, make sure you change it in your client options too. This command is available for everyone.
+redirect nick <address> [reason] | Redirect the user to the given address. Address must be enclosed by < and >. Reason is optional.
+regnick nick [password] [level] | Register a user; omit password and level to un-reg; level defaults to your own level minus one.
+reload | Reload scripts.
+test | Make the hub reply "Test ok". This command is available for everyone.
+topic topic | Change the hub topic (shortcut to +cfg topic).

The above list contains the basic hub commands only. Many additional commands not listed here belong to the advanced hub security and discussed in the Expert guide in detail.

#### 5.2.2. Basic hub settings

To see what basic configuration parameters are available for your hub and what are their current values you should enter:

    +help cfg

To change a basic hub setting you must use:

    +cfg [setting] [value]

Table 5. List of all basic hub setting variables
Setting | Purpose
--- | ---
address | Your hub address without port number (for hublist pingers)
allownickchange | Authorize registered users to connect with a different nick, 1 = allow, 0 = disallow
allowreg | Authorize un-regged users to register themselves with +mypass (otherwise, they’ll have to ask an operator), 1 = allow, 0 = disallow
botcid | CID of the hub bot, restart the hub after the change (in most cases you don’t need to change this)
botdescription | Description that shows in the userlist in the Description coloumn for the hub bot
botemail | Description that shows in the userlist in the E-mail coloumn for the hub bot
botname | The hub bot’s nickname
description | Your hub’s description (for hublist pingers)
history_connect | How much lines of the main chat history the hub displays to the user on connect, 0 = disabled
history_default | How much lines of the main chat history the hub displays for the +history command
history_max | Maximum amount of last main chat history lines that the hub saves
history_method | Strategy used by the +history command to record messages, restart the hub after the change, 1 = use a hidden bot, 0 = direct ADCH++ interface
history_prefix | Format of the timestamp to put before every message in the history. For the avaliable formatting parameters check the General time format variables in the Logs part of the DC++ help file or the same document online at http://dcplusplus.sourceforge.net/webhelp/settings_logs.html
maxusers | Maximum number of non-registered users to log in, -1 = no limit, 0 = no unregistered users allowed (private hub)
menuname | Name of the main user menu for the hub’s user commands (displayed in the clients)
minchatlevel | Minimum user level to be able to chat, 0 = disabled (hub restart recommended after change)
mindownloadlevel | Minimum user level to be able download, 0 = disabled (hub restart recommended after change)
minsearchlevel | Minimum user level to be able to search, 0 = disabled (hub restart recommended after change)
name | Name of the hub (for hublist pingers)
network | Name of the network the hub belongs to (for hublist pingers)
oplevel | Minimum user level for operators, all users >= this level will have OP rights (hub restart recommended after change)
owner | Hubowner’s name (for hublist pingers)
passinlist | Show passwords of users with lower level than you using the +listregs command, 1 = show, 0 = don’t show (enable only if you have trust in your lower level operators)
rulesredirect | Redirect address to use when rules like slots/hubs/sharesize aren’t obeyed, empty = users will be disconnected only
sendversion | Print hub version information at login and in the stats 1 = enabled, 0 = disabled
topic | Sets the hub topic: if set, overrides the description for normal users; the description is then only for use by hublists pingers
website | Sets the website for your hub network or hub (for hublist pingers)

### 5.3. FAQ

This chapter help you setup your hub by answering the most frequent questions. For additional FAQs visit: https://answers.launchpad.net/adchpp/+faqs

#### 5.3.1. How can I set up my hub to private so only registered users are able to log in?

      +cfg maxusers 0

The setting "maxusers" has the following description:

    maxusers - maximum number of non-registered users, -1 = no limit, 0 = no unregistered users allowed

When the hub is set to registered users only the connecting unregistered users will receive the following message:

Example: Connection Attempt (if not registered at the hub)

    [09-10-02][22:07:09] <ADCH++> Only registered users are allowed in here

#### 5.3.2. How can I setup so only registered users are able to chat/search/download?

It’s possible to restrict guest (unregistered) users to be able to chat/search/download until they get registered by an operator or until they use the self registraton command:

Example: Self-Register

    +regme <password>

Since ADCH++ version 2.5.1 setting up download/chat/search rules is pretty easy. You are just a few simple commands away to set these rules up. You have to specify what is the minimum userlevel needed to be able to do different things. Zero value means the function is available to all users.

Example: Configuration Variables

    +cfg minchatlevel <value>
    +cfg mindownloadlevel <value>
    +cfg minsearchlevel <value>

- minchatlevel - minimum level to chat - hub restart recommended

- mindownloadlevel - minimum level to download - hub restart recommended (aliases: mindllevel, mintransferlevel)

- minsearchlevel - minimum level to search - hub restart recommended

#### 5.3.3. How can I modify the password and user level of an already registered user?

You simply re-register the user with the new password and user level. You must specify the password even if you’re willing to change the level only. This means that you’re also able to change the password and the level of the user at the same time.

Example: Re-Register an user

    +regnick <user> <password> <new level>

## 6. More information

If you want to know more about ADCH++

1. There is an expert user guide available for advanced/expert users. It contains information about advanced scripting, extended hub security settings as well as topics about compiling, testing, bug reporting or contributing to the ADCH++ project. The Expert Guide is available at http://adchpp.sourceforge.net/user_guide/expert_guide.html The latest revisions of both user guides (corresponding to the current development revision) are also available in the ADCH++ repository at http://code.launchpad.net/adchpp/

2. You can get support for ADCH++ at the project’s official Answers tracker at Launchpad.

3. You can get more information or discuss topics about ADCH++ at the DCBase.org community portal forums.

## 7. Appendix

This document is published under GNU FDL

Copyright (c) 2010-2013 Jacek Sieka

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html