Skip to main content

A simple dynamic DNS HTTP based update API using Python and the Flask web framework.

Project description

This package on the Python Package Index Tests Documentation Status

About

dyndns is a HTTP based API to dynamically update DNS records (DynDNS). It’s uses Python and the Flask web framework to accomplish this task.

Installation

Bind9 installation

apt install bind9

vim /etc/bind/named.conf

zone "dyndns.example.com" {
  type master;
  file "/var/cache/bind/dyndns.example.com.db";
  allow-update { key "dyndns.example.com."; };
};

tsig-keygen -a hmac-sha512 dyndns.example.com

vim /etc/bind/named.conf.local

key "dyndns.example.com." {
  algorithm hmac-sha512;
  secret "nbB5i/5pyFywRPaUpEkzxtS0she1JOuZlASceu0lLU8Pe7dYpzuVDn9vbGvof2wjGkVsSZBG2DlaM3RwPHkd9g==";
};

vim /var/cache/bind/dyndns.example.com.db

$ORIGIN dyndns.example.com.
$TTL 300 ; 5 minutes

;; NAME IN SOA MNAME RNAME
; NAME: name of the zone
; IN: zone class (usually IN for internet)
; SOA: abbreviation for Start of Authority
; MNAME: Primary master name server for this zone
; RNAME: Email address of the administrator responsible for this zone. address is encoded as a name. (john\.doe.example.com.)

@   IN SOA  ns1.example.com. admin.example.com. (
    1  ; SERIAL: Serial number for this zone.
    3600       ; REFRESH: number of seconds after which secondary name servers should query
    1000       ; RETRY: number of seconds after which secondary name servers should retry to request
    3600000    ; EXPIRE: number of seconds after which secondary name servers should stop answering request
    300        ; TTL: Time To Live for purposes of negative caching
    )
      NS    ns1.example.com.
      NS    ns2.example.com.
      A     185.11.138.33
      AAAA  2a03:2900:7:96::2

systemctl enable named.service

systemctl start named.service

Test Bind9 setup

echo "server ns1.example.com
debug
update add debug.dyndns.example.com. 10 IN TXT \"$(date)\"
send
quit
" | nsupdate -y 'hmac-sha512:dyndns.example.com:nbB5i/5pyFywRPaUpEkzxtS0she1JOuZlASceu0lLU8Pe7dYpzuVDn9vbGvof2wjGkVsSZBG2DlaM3RwPHkd9g=='

Show all records of the zone dyndns.example.com

dig @ns1.example.com. dyndns.example.com. axfr (axfr = Asynchronous Xfer Full Range)

dyndns installation

Install dyndns into the directory /usr/local/share/python-virtualenv/dyndns using a virtual environment.

python3 -m venv /usr/local/share/python-virtualenv/dyndns
source /usr/local/share/python-virtualenv/dyndns/bin/activate
pip3 install dyndns

The working directory of our flask web API is in the directory /var/www/dyndns.example.com. Create a file /var/www/dyndns.example.com/dyndns.ini.

[uwsgi]
module = dyndns.wsgi:app

master = true
processes = 5

socket = /var/www/dyndns.example.com/dyndns.sock
chmod-socket = 664
uid = www-data
gid = www-data
vacuum = true

die-on-term = true

Example configuration file for nginx: /etc/nginx/sites-available/dyndns.example.com.

server {
  server_name dyndns.example.com;
  listen 80;
  listen [::]:80;
  return 301 https://$host$request_uri;
}

server {
  listen 443 ssl;
  listen [::]:443 ssl;
  server_name dyndns.example.com;
  ssl_certificate /etc/letsencrypt/live/dyndns.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/dyndns.example.com/privkey.pem;

  location / {
    include uwsgi_params;
    uwsgi_pass unix:/var/www/dyndns.example.com/dyndns.sock;
  }

}

vim /etc/systemd/system/dyndns.service

[Unit]
Description=uWSGI instance to serve dyndns
After=network.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/dyndns.example.com
Environment="PATH=/usr/local/share/python-virtualenv/dyndns/bin"
ExecStart=/usr/local/share/python-virtualenv/dyndns/bin/uwsgi --ini uwsgi.ini

[Install]
WantedBy=multi-user.target

systemctl enable dyndns.service

systemctl start dyndns.service

Configuration

dyndns requires a configuration file in the YAML markup language.

dyndns looks on three places for its configuration. It picks the first existing configuration file and ignores the later in this order:

  1. Custom path specified in the environment variable dyndns_CONFIG_FILE

  2. Current working directory of the dyndns app (cwd): <cwd>/.dyndns.yml

  3. /etc/dyndns.yml

---
secret: '12345678'
nameserver: 127.0.0.1
port: 53
zones:
  - name: dyndns.example.com
    tsig_key: tPyvZA==
  • secret: A password-like secret string. The secret string must be at least 8 characters long and only alphanumeric characters are permitted.

  • nameserver: The IP address of your nameserver. Version 4 or version 6 are allowed. Use 127.0.0.1 to communicate with your nameserver on the same machine.

  • port: The port to which the DNS server listens. If the DNS server listens to port 53 by default, the value does not need to be specified.

  • zones: At least one zone specified as a list.
    • name: The domain name of the zone, for example dyndns.example.com.

    • tsig_key: The tsig-key. Use the hmac-sha512 algorithm to generate the key: tsig-keygen -a hmac-sha512 dyndns.example.com

Usage

dyndns offers two HTTP web APIs to update DNS records: A simple API and a more flexible API.

The simple API uses path segments (<your-domain>/update-by-path/secret/fqdn/ip_1 see section “Update by path”) and the more flexible API uses query strings (<your-domain>/update-by-query?secret=secret&fqdn=fqdn&ip_1=1.2.3.4 see section “Update by query”).

Update by path

  1. <your-domain>/update-by-path/secret/fqdn

  2. <your-domain>/update-by-path/secret/fqdn/ip_1

  3. <your-domain>/update-by-path/secret/fqdn/ip_1/ip_2

Update by query

<your-domain>/update-by-query?secret=secret&fqdn=fqdn&ip_1=1.2.3.4

Arguments for the query string

  • secret: A password like secret string. The secret string has to be at least 8 characters long and only alphnumeric characters are allowed.

  • fqdn: The Fully-Qualified Domain Name (e. g. www.example.com). If you specify the argument fqdn, you don’t have to specify the arguments zone_name and record_name.

  • zone_name: The zone name (e. g. example.com). You have to specify the argument record_name.

  • record_name: The record name (e. g. www). You have to specify the argument zone_name.

  • ip_1: An IP address, can be version 4 or version 6.

  • ip_2: A second IP address, can be version 4 or version 6. Must be a different version than ip_1.

  • ipv4: A version 4 IP address.

  • ipv6: A version 6 IP address.

  • ttl: Time to live. The default value is 300.

Delete by path

Hit this url to delete a DNS record corresponding to the fqdn. Both ipv4 and ipv6 entries are deleted.

<your-domain>/delete-by-path/secret/fqdn

Update script

To update the dyndns server you can use the corresponding shell script dyndns-update-script.sh.

Edit the top of the shell script to fit your needs:

#! /bin/sh

VALUE_DYNDNS_DOMAIN='dyndns.example.com'
VALUE_SECRET='123'
VALUE_ZONE_NAME='sub.example.com'

This update shell script is designed to work on OpenWRT. The only dependency you have to install is curl.

Use cron jobs (crontab -e) to periodically push updates to the dyndns server:

*/2 * * * * /usr/bin/dyndns-update-script.sh -S 5 -d br-lan -4 nrouter
*/2 * * * * /usr/bin/dyndns-update-script.sh -d br-lan -4 nuernberg

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dyndns-2.0.0.tar.gz (17.8 kB view hashes)

Uploaded Source

Built Distribution

dyndns-2.0.0-py3-none-any.whl (19.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page