.. image:: http://img.shields.io/pypi/v/dyndns.svg
    :target: https://pypi.org/project/dyndns
    :alt: This package on the Python Package Index

.. image:: https://github.com/Josef-Friedrich/dyndns/actions/workflows/tests.yml/badge.svg
    :target: https://github.com/Josef-Friedrich/dyndns/actions/workflows/tests.yml
    :alt: Tests

.. image:: https://readthedocs.org/projects/dyndns/badge/?version=latest
    :target: https://dyndns.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

About
-----

`dyndns <https://pypi.org/project/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``

.. code-block:: text

    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``

.. code-block:: text

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

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

.. code-block:: text

    $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
^^^^^^^^^^^^^^^^

.. code-block:: text

    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.

.. code-block:: text

    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``.

.. code-block:: 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.``

.. code-block:: text

    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``

.. code-block:: text

    [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``

.. code-block:: yaml

    ---
    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
<https://github.com/Josef-Friedrich/dyndns-update-script.sh>`_.

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

.. code-block:: text

    #! /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:

.. code-block:: text

    */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