DynDRest :: A Simple Dynamic DNS Rest Service

• Preface
• Disclaimer
• Big Picture
• Setup & Configuration
  • File Structure
  • Configuration example for the provider 'domainrobot'
• Start
  • by Command Line
  • by systemd Service
  • by init.d Service
• Routes
• Setup a router for dynamic DNS

Give it a try!

DynDRest is kindly supported by

Preface

DynDRest is a simple REST-service for dynamic DNS. The basic idea is to have multiple implementations of different dns providers. AutoDNS will be one of them.
DynDRest is based on spring boot 3, that’s why Java 17 or later is required!

The restful-api can be used with many routers, for example the AVM Fritz!Box. DynDRest can be executed by commandline, init.d or systemd.

If you find a bug or certain features are missing, don’t hesitate to file an issue on Github.

This project is also a playground for the author to try things out. That’s why not all changes are really necessary to move the project forward!

Disclaimer

I’m not responsible for any data loss, hardware damage or broken keyboards. This guide comes without any warranty!

Big Picture

DynDRest is running as a service. A client can access the service via url and basic-auth. Let’s assume DynDRest is running on localhost, then we can update the IPv4 and IPv6 address of the host mydyndns.domain.com by calling the following curl command:

curl -u dyndns:test123 -i \
   "http://localhost:8081/update/mydyndns.domain.com?apitoken=1234567890abcdf&ipv4=127.1.2.4&ipv6=2a03:4000:41:32::2"

For each host an api-token must be defined. If the api-token doesn’t match the host, the update will be failed. Due to this security feature, DynDRest can be used by different people. They can’t update the IPs each other.

Setup & Configuration

DynDRest is a spring boot application, that’s why the application is extremely customizable just by configuration! Details of the configuration can be found here in Appendix A: Common Application Properties of the spring boot reference documentation.

Note	To avoid the use of the java keystore tool, DynDRest could be run behind a proxy. Corresponding headers are set by default.

File Structure

Here is the suggested file structure:

├── /opt/dyndrest
│   ├── dyndrest.yml
│   ├── dyndrest-0.7.0.jar
│   ├── dyndrest.jar -> dyndrest-0.7.0.jar
│   ├── logback.xml    (logback configuration)
│   ├── dyndrest.mv.db  (h2 database file)
│   ├── /backup
│       ├── dump.sql   (optional backup of the database)
│   ├── /restore
│       ├── dump.sql   (optional dump of the database to restore)
│   ├── /log
│       ├── dyndrest.log   (application log)

dyndrest.yml defines the individual properties. The file is read by default and will be merged with the default properties in the classpath, therefore the file can be kept as small as possible. A minimal configuration example can be found further below. If the file is inside the working directory, it is loaded automatically. The complete configuration settings can be found here.
Important: The basic-auth, the api-tokens and the credentials for AutoDNS should be defined in this file!

logback.xml is the configuration file of Logback. For further information have look at the Logback Configuration. There is example which demonstrates, how to configure an additional file appender for the update logging, which dependents on an application property.

Configuration example for the provider 'domainrobot'

This is a minimal configuration example for your individual properties file dyndrest.yml using the provider domainrobot:

spring:
  security:
    user:
      name: dyndns
      password: test123

logging:
  config: file:./logback.xml

dyndrest:
  provider: domainrobot

domainrobot:
  autodns:
    url: https://api.autodns.com/v1    # optional
    password: pwd_t
    user: user_t

zones:
- name: dynhost.info
  ns: ns.domain.info
  hosts:
    - myhost:1234567890abcdef

The zones section should be used for importing the hosts and zones configuration to the database initially. Existing data entries won’t be updated. The example defines a host myhost.dynhost.info with the api-token 1234567890abcdef.

Note	This project uses spring-doc to document the routes. The endpoints for this and the swagger-ui are disabled by default!

Backup and Restore

There is a very simple cron-triggered service to dump the database regulary. The configuration is part of the database configuration:

dyndrest:
  database:
    backup:
      enabled: true
      path: ./backup
      cron: "0 30 18 * * MON"
    restore:
      enabled: enabled
      path: ./restore
    dump-file: dump.sql

In this example every monday at 18:30 a database dump will be written to ./backup/dump.sql. The file will be overwritten every time!

If restore is enabled and the file ./restore/dump.sql exists at start, the dump will be restored and the file renamed to ./restore/dump.sql.bak.

Suggested AutoDNS setup

For security reasons, it makes sense to create a separate owner for the zones updated by DynDRest. This owner just needs the permission for zone-info and zone-updates!

Start

The fully executable jar can be executed in different ways.

by Command Line

The start by command line looks like:

cd /opt/dyndrest/
java -jar dyndrest.jar --logging.config=logback.xml

by systemd Service

DynDRest can also be started easily as a systemd service. An example for the desired service configuration can be found at the documentation systemd Service Configuration.

by init.d Service

Another possibility to start DynDRest is as init.d service. Further information can be found at the documentation of spring boot, Installation as an init.d Service (System V).

Routes

All routes are secured by basic-auth. A detailed description of the routes can be found at the OAS3 documentation.

There are additional routes:

• [/]: A simple html greeting page which is enabled by default. It can be disabled by setting the property dyndrest.greeting-enabled=false.

• [/manage/health]: A very simple health check with an extra basic-auth user. It can be enabled and configured by setting management.endpoint.health.enabled=true and the both properties dyndrest.healthcheck-user-name and dyndrest.healthcheck-user-password.

• [/log-ui]: Delivers a simple web page to view the zone update logs. It is secured by basic-auth and can be configured by setting the two properties dyndrest.update-log-user-name and dyndrest.update-log-user-password. It is enabled by default, but it can be disabled by setting the property dyndrest.update-log-page-enabled=false.

Setup a router for dynamic DNS

As an example, let’s have a look at the setup of dynamic DNS in the Fritz!Box 7590. The following settngs are required:

• DynDNS Provider: User-defined

• Domain name: The hostname for which the IPs should be updated.

• Username / Password: The credentials for basic-auth.

• Update-URL: [your-host:port]/update/<domain>?apitoken=[yourApitoken]&ipv4=<ipaddr>&ipv6=<ip6addr> If both IP parameters are omitted, an attempt is made to fetch the remote IP.