Documentation

ddserver is a server-side application for dynamic DNS management. Here you can find basic installation and configuration instructions.

Installation

The following sections describe the installation of ddserver, including the ddserver-interface, ddserver-updater and the ddserver-recursor.

For testing, a vagrant box is available which will install and start the ddserver-interface and ddserver-updater in a CentOS vm. See https://github.com/ddserver.

Prerequisites

Before you start, you need to fulfill some prerequisites.

As ddserver is written in python, the first step is to install python version 2.7. Further, the MySQL server and the PowerDNS server are needed to store DNS information and to answer DNS requests.

Also, some packages need to be installed on your system, before you will be able to compile the needed packages. Those include the python and mysql-client header files, which are available in separate packages on some GNU/Linux distributions.

If you are using Debian GNU/Linux or Ubuntu, please install the following packages:

libmysqlclient-dev 
python-dev
python-setuptools

If you are using CentOS please install the following packages:

mysql-devel
python-devel
python-setuptools

Getting the Source

Currently, ddserver is available from github only. To get the source please use git to clone the ddserver repository.

git clone https://github.com/ddserver/ddserver.git

Installing ddserver

Change to the source directory and use python-setuptools to install ddserver

cd ddserver
python setup.py install

After this steps, ddserver installed to the following locations:

  • <CurrentDirectory>/build contains the installed python packages
  • /etc/ddserver contains the configuration file
  • /etc/init.d/ddserver is a debian init-script for controlling ddserver
  • /usr/share/doc/ddserver contains the database schema and some readme files
  • /usr/share/ddserver contains static files like CSS, JavaScript, eMail-Templates, ..
  • /usr/local/bin contains the ddserver executables

Installing the database

ddserver uses a MySQL backend to store DNS information. To install the ddserver database schema, first create a database and a database user used for ddserver.

mysql -u root -p
mysql> CREATE DATABASE ddserver;
mysql> CREATE USER 'ddserver'@'localhost' IDENTIFIED BY 'YourSecurePassword';
mysql> GRANT USAGE ON *.* TO 'ddserver'@'localhost' IDENTIFIED BY 'YourSecurePassword' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0 MAX_USER_CONNECTIONS 0;
mysql> GRANT SELECT, INSERT, UPDATE, DELETE ON `ddserver`.* TO 'ddserver'@'localhost';

Now you can install the ddserver database schema by usng the following command.

mysql -u root -p ddserver < /usr/share/doc/ddserver/schema.sql

Congratz, you installed ddserver!

Note: When installing the default database schema, an initial user will be installed to log into the WebUI. The default login is: admin:admin

Running ddserver

After installing ddserver, you will find four executables in your installation directory (usually, /usr/local/src).

  • ddserver-bundle is the bundled version of
    • ddserver-interface: A nice-looking webinterface for adding hostnames, administrating dynamic zones and managing users
    • ddserver-updater: The implementation of the no-ip update protocol
  • ddserver-recursor is the application that answers DNS queries. It runs as a pipe-backend for the PowerDNS server.

Creating the configuration

Start by copying the example configuration file to /etc/ddserver/ddserver.conf and edit the file to match your requirements.

cp /etc/ddserver/ddserver.conf.example /etc/ddserver/ddserver.conf

Lines starting with a semicolon are interpreted as comments and are showing the default values. You need to configure at least the database password.

Running the ddserver WebUI and updater

Although, ddserver comes with a separate WebUI (ddserver-interface) and updater (ddserver-updater), the easiest way to run ddserver is by using ddserver-bundle, which starts both, the WebUI and the updater.

You can start the ddserver-bundle by using the init-script or by starting the ddserver-bundle executable on the command line

/etc/init.d/ddserver start

or

ddserver-bundle

Now, open your webbrowser and navigate to your configured URL (default: http://localhost:8080)

Running the ddserver-recursor

The ddserver-recursor is needed by PorweDNS to retrieve DNS records from the ddserver database. It gets called using the pdns-pipe-backend.

If you did not already install the PowerDNS pipe backend, you should do this now. On Debian GNU/Linux you can do this by typing

apt-get install pdns-backend-pipe

Now, edit your PowerDNS configuration file and add the following to connect ddserver to PowerDNS

launch=pipe
pipe-command=/usr/local/bin/ddserver-recursor

Note: The user, you are running powerdns as needs write privileges to the ddserver logfile /var/log/ddserver.log

Note: If you are already running powerdns using another backend (i.e. the gmysql backend), you can just append the pipe packend to your launch-configuration. (i.e. launch=gmysql,pipe).

Usage

The following sections give a brief overview of the usage of the ddserver WebUI.

Default account

While installing the ddserver database schema, an administrator user is created with the following credentials:

  • Username: admin
  • Password: admin

User registration

Depending on your configuration, account creation may be enabled or disabled. If it is enabled, new user accounts can be created/requested using the signup form.

If account creation is enabled in your configuration file, you can specify a comma-separated list of email-domains (or use the keyword any) to allow users to complete the account registration without the need to be accepted by an administrator. The default setting of this configuration parameter is to allow any user to complete the registration process by email-activation.

If a user registers using an email address that is not specified in the list of allowed_maildomains, an administrator has to accept the new user, before an activation email is sent, allowing the user to finish registration.

Adding a dynamic zone (suffix)

Each zone you want to make available by your ddserver installation, needs to be handled by the PowerDNS server, your ddserver-recursor is connected to. That means, you have to configure zone-delegation of the desired zone to your PowerDNS server(s).

If you want to use example.com as your dynamic zone

  • Configure your PowerDNS server(s) to be authoritative
  • Add example.com to the available suffixes in the ddserver WebUI

Note: Each zone available in ddserver, users are allowed to add any hostname (subdomain) to (including stuff like www or mail). You can prevent hostnames to be added by just pre-adding them in your admin account.

Note: You can not have duplicate zone records, i.e. by specifying a subdomain in the PowerDNS gmysql backend and ddserver at the same time.

Adding a hostname

After at least one dynamic zone is available, users can start adding hostnames. The number of hostnames each user can add depends on your configuration (default = 5).

A hostname can consist of a maximum of 63 alphanumeric characters. The special characters - (minus) and . (period) are allowed, however they can not be the first character of a hostname.

Each hostname is assigned a password, that is used to update the IP address of the hostname. If you want to update multiple hostnames at once (which is a specified usecase of the no-ip protocol), you have to assign the same password to these hostnames.