Skip to content

DynDRest is a simple REST-service for dynamic DNS.

License

Notifications You must be signed in to change notification settings

th-schwarz/DynDRest

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

DynDRest :: A Simple Dynamic DNS Rest Service

GitHub CI Build Status License badge for DynDRest

codecov
Quality Gate Status Security Rating Coverage Lines of Code Code Smells

Give it a try! GitHub release (latest by date including pre-releases)

DynDRest is kindly supported by

IntelliJ IDEA logo

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.

Minimal configuration example

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

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

  datasource:
    username: dba
    password: secretpwd

logging:
  config: file:./logback.xml

dyndrest:
  provider: domainrobot

domainrobot:
  autodns:
    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 of the Database

There are 2 very basic configurations:

  • Backup: A cron-triggered service to dump the database regular.

  • Restore: Very basic strategy, 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.

Or further info, see Backup & Restore

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.