Metadata-Version: 1.1
Name: pdyndns
Version: 0.2.6
Summary: PEERING testbed dynamic PowerDNS backend
Home-page: https://github.com/PEERINGTestbed/powerdns-pdyndns-backend
Author: PEERING Testbed developers
Author-email: team@peering.usc.edu
License: GPLv3
Description: Dynamic PowerDNS backend
        ========================
        
        |PyPI| |Python|
        
        This repository implements a PowerDNS pipe backend to provide dynamic
        replies to DNS queries. Replies are taken round-robin from a predefined
        list read from a text file. We use this backend to steer RIPE Atlas
        traceroute measurements toward PEERING prefixes according to experiment
        requirements.
        
        Usage
        =====
        
        This module communicates with PowerDNS using PowerDNS's `pipe
        backend <https://doc.powerdns.com/md/authoritative/backend-pipe/>`__
        protocol version 3. The tool receives a single configuration file as
        parameter, and exchanges information with PowerDNS through standard
        input and output. The configuration file is in JSON format and is
        validated by the ``config-schema.json`` `JSON
        schema <http://json-schema.org/>`__.
        
        Backend configuration
        ---------------------
        
        The configuration file specifies the DNS domain the backend is
        responsible for, and information required to answer ``SOA`` and ``NS``
        DNS queries:
        
        .. code:: json
        
            {
              "domain": "atlas.peering.usc.edu",
              "soa": "atlas.peering.usc.edu noc.peering.usc.edu 20170723 7200 3600 7200 120",
              "nameservers": [
                "peering-atlas-ns.vms.uscnsl.net",
                "peering-atlas-ns.peering-vms.usc.edu"
              ],
              "ttl": 3600,
              "...": "..."
            }
        
        The ``domain`` parameter specifies what domain the backend is
        responsible for. The ``soa`` parameter specifies zone-specific timers
        and configuration, and is used verbatim in replies for DNS ``SOA``
        queries. The ``nameserver`` parameter specifies a list of name servers
        for the zone, used in replies for ``NS`` queries. The time-to-live
        parameter (``ttl``) specifies the period for which replies to ``SOA``
        and ``NS`` queries should be cached. Normally, the third field in the
        ``soa`` parameter (``20170723``, the `serial
        number <https://doc.powerdns.com/md/types/>`__) needs to be updated
        whenever a zone is updated. Although updating the serial number when the
        dynamic addresses are reconfigured is not essential (because replies
        have a time-to-live of zero to prevent caching), the serial number needs
        to be updated if the ``soa`` or ``nameservers`` parameters are updated.
        
        Each dynamic host name within ``domain`` is handled by a handler that
        reads the list of IP addresses from a text file. The handler replies to
        queries with IP addresses in the text file in round-robin order. Each
        handler has three parameters:
        
        .. code:: json
        
            {
              "...": "...",
              "handlers": [
                {
                  "qname": "target1.atlas.peering.usc.edu",
                  "qtype": "A",
                  "file": "data/peering-v4.txt",
                },
                {
                  "qname": "target2.atlas.peering.usc.edu",
                  "qtype": "AAAA",
                  "file": "data/peering-v6.txt"
                },
                "..."
              ]
            }
        
        Parameter ``qname`` specifies the fully-qualified domain name that
        should be answered with IP addresses within ``file``. The ``qtype``
        field specified whether IP addresses in ``file`` are IPv4 addresses
        (``qtype = A``) or IPv6 addresses (``qtype = AAAA``).
        
        Setting up the parent DNS server
        --------------------------------
        
        We also need to configure the authoritative name server for the parent
        domain (``peering.usc.edu`` in our case) to forward all requests for
        ``atlas.peering.usc.edu`` to the machine running the dynamic backend.
        
        If using BIND and if the dynamic backend server is
        ``peering-atlas-ns.vms.uscnsl.net``, this can be achieved by adding the
        following to the zone database (equivalent entries can be added to
        PowerDNS to achieve the same effect):
        
        ::
        
            atlas.peering.usc.edu.  NS          peering-atlas-ns.vms.uscnsl.net.
        
        Testing pdyndns.py
        ==================
        
        We have a test suite for ``pdyndns.py``. You can run it by installing
        `nose <http://nose.readthedocs.io/en/latest/>`__ and running
        ``nosetests``. Note that we require nose for Python 3. We also have a
        `tox <https://pypi.python.org/pypi/tox>`__ script that checks for
        formatting and performs some linting.
        
        Acknowledgements
        ================
        
        Precursors and early implementations for this code include `RIPE
        Atlas <https://atlas.ripe.net>`__'s
        `atlas-dyndns <https://github.com/RIPE-NCC/atlas-dyndns>`__, Emile
        Aben's `Scapy DNS
        Ninja <https://github.com/emileaben/scapy-dns-ninja>`__ and `Zeerover
        DNS <https://github.com/USC-NSL/RIPE2015HackAThon>`__.
        
        .. |PyPI| image:: https://img.shields.io/pypi/v/pdyndns.svg
           :target: https://pypi.org/project/pdyndns/
        .. |Python| image:: https://img.shields.io/pypi/pyversions/pdyndns.svg
           :target: https://pypi.org/project/pdyndns/
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3.3
Classifier: Operating System :: POSIX
Classifier: Topic :: System :: Networking
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Development Status :: 2 - Pre-Alpha
