:toc: :toclevels: 3 :toc-title: :source-highlighter: highlightjs :highlightjs-languages: yaml,console
= DynDRest :: A Simple Dynamic DNS Rest Service
image:https://github.com/th-schwarz/DynDRest/actions/workflows/build-and-analyse.yml/badge.svg["GitHub CI Build Status",link="https://github.com/th-schwarz/DynDRest/actions/workflows/build-and-analyse.yml"] image:https://img.shields.io/github/license/th-schwarz/DynDRest["License badge for DynDRest",link="https://github.com/th-schwarz/DynDRest/blob/develop/LICENSE"]
:codecovURL: https://codecov.io/gh/th-schwarz/DynDRest :sonarURL: https://sonarcloud.io/dashboard?id=th-schwarz_DynDRest :sonarSummaryURL: https://sonarcloud.io/summary/new_code?id=th-schwarz_DynDRest
{codecovURL}[image:{codecovURL}/graph/badge.svg?token=ARXPZ8IDMZ[codecov]] + {sonarURL}[image:https://sonarcloud.io/api/project_badges/measure?project=th-schwarz_DynDRest&metric=alert_status[Quality Gate Status]] {sonarURL}[image:https://sonarcloud.io/api/project_badges/measure?project=th-schwarz_DynDRest&metric=security_rating[Security Rating]] {sonarSummaryURL}[image:https://sonarcloud.io/api/project_badges/measure?project=th-schwarz_DynDRest&metric=coverage[Coverage]] {sonarURL}[image:https://sonarcloud.io/api/project_badges/measure?project=th-schwarz_DynDRest&metric=ncloc[Lines of Code]] {sonarSummaryURL}[image:https://sonarcloud.io/api/project_badges/measure?project=th-schwarz_DynDRest&metric=code_smells[Code Smells]]
Give it a try! https://github.com/th-schwarz/DynDRest/releases[image:https://img.shields.io/github/v/release/th-schwarz/DynDRest?include_prereleases[GitHub release (latest by date including pre-releases)]]
DynDRest is kindly supported by
image::https://resources.jetbrains.com/storage/products/company/brand/logos/IntelliJ_IDEA.png[IntelliJ IDEA logo,250,link="https://jb.gg/OpenSourceSupport"]
== Preface
DynDRest is a simple REST-service for dynamic DNS. The basic idea is to have multiple implementations of different dns providers. https://www.internetx.com/en/domains/autodns[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 https://github.com/th-schwarz/DynDRest/issues[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:
For each host an api-token must be defined. If the api-token does not 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 https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#application-properties[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:
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 link:docs/dyndrest-configuration.adoc[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:
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 <<docs/dyndrest-configuration.adoc#backup_restore, 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:
=== 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 link:docs/systemd-configuration.adoc[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,
https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#deployment.installing.nix-services.init-d[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 https://th-schwarz.github.io/DynDRest/openapi-develop.html[OAS3 documentation].
There are additional routes:
dyndrest.greeting-enabled=false.management.endpoint.health.enabled=true and the both properties dyndrest.healthcheck-user-name and dyndrest.healthcheck-user-password.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 https://service.avm.de/help/en/FRITZ-Box-7530/019p2/hilfe_dyndns[Fritz!Box 7590]. The following settings are required: