Metadata-Version: 2.0
Name: docker-hostdns
Version: 2.0.0
Summary: Update BIND nameserver zone with Docker hosts via DNS Updates.
Home-page: https://github.com/glorpen/docker-hostdns
Author: Arkadiusz Dzięgiel
Author-email: arkadiusz.dziegiel@glorpen.pl
License: UNKNOWN
Description-Content-Type: UNKNOWN
Keywords: docker dns bind named
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Dist: docker (>=2.0.0)
Requires-Dist: dnspython (>=1.13.0)
Provides-Extra: development
Requires-Dist: unittest; extra == 'development'
Requires-Dist: python-daemon; extra == 'development'
Provides-Extra: suggested
Requires-Dist: python-daemon; extra == 'suggested'
Provides-Extra: testing
Requires-Dist: unittest; extra == 'testing'
Requires-Dist: python-daemon; extra == 'testing'

==============
Docker HostDNS
==============

Update BIND nameserver zone with Docker hosts via DNS Updates.

Usage
=====

*Docker HostDNS* can be run by ``docker-hostdns`` wrapper script or directly with ``python -m docker_hostdns``.

.. sourcecode::

   usage: docker-hostdns [-h] [--zone ZONE] [--dns-server DNS_SERVER]
                      [--dns-key-secret DNS_KEY_SECRET]
                      [--dns-key-name DNS_KEY_NAME] [--daemonize PIDFILE]
                      [--verbose] [--syslog]

   Update BIND nameserver zone with Docker hosts via DNS Updates.

   optional arguments:
     -h, --help            show this help message and exit
     --zone ZONE           Dns zone to update, defaults to "docker".
     --dns-server DNS_SERVER
                           Address of DNS server which will be updated, defaults
                           to 127.0.0.1.
     --dns-key-secret DNS_KEY_SECRET
                           DNS Server key secret for use when updating zone. Use
                           '-' to read from stdin.
     --dns-key-name DNS_KEY_NAME
                           DNS Server key name for use when updating zone.
     --name NAME           Name to differentiate between multiple instances inside
                           same dns zone, defaults to current hostname.
     --daemonize PIDFILE, -d PIDFILE
                           Daemonize after start and store PID at given path.
     --verbose, -v         Give more output. Option is additive, and can be used
                           up to 3 times.
     --syslog              Enable logging to syslog.


The ``--daemonize`` options is only available when you have installed ``python-daemon3`` package.

Example ``named.conf`` zone configuration with key auth:

.. sourcecode::

   include "/etc/bind/docker.key";

   zone "docker" in {
       type master;
       file "/var/bind/dyn/docker.zone";
       allow-update {
         key "docker-key";
       };
   };

``docker.key`` can be generated by:

.. sourcecode:: sh

   rndc-confgen -a -c docker.key -k docker-key

And then:

.. sourcecode:: sh

   echo 'my base64 key secret' | docker-hostdns --dns-key-name docker-key --dns-key-secret -

Host names
==========

Host name is created by using container name and slugifying & trimming it. So ``/example2::docker`` will result with ``example2-docker``.
In case of name duplication a "-<number>" will be appended, resulting with eg. ``example2-docker-1``

Following dns records are created for each container, given ``example`` hostname and ``docker`` zone:

- IPv4: ``example.docker``
- IPv4: ``*.example.docker``
- IPv6: ``example.docker``
- IPv6: ``*.example.docker``
- TXT: ``_container_<name>.docker`` with container name as value and instance name as ``<name>`` 

TXT record is used for keeping track of added hosts so when app is stopped or resumed it keeps its state. 

Custom host names
*****************

You can set custom host name by using container label ``pl.glorpen.hostname``, its content will be used as container name.

Docker Image
============

Docker image is available at ``glorpen/hostdns``.
For help try ``docker run --rm -it glorpen/hostdns:latest --help``.

Remember to mount ``/run/docker.sock`` inside container.

Securing DNS secret key
***********************

To secure secret key (the ``dns-key-secret`` option) you can:

- passing its contents to env var ``DNS_KEY_SECRET``
- setting env var ``DNS_KEY_SECRET_FILE`` to path of file with secret as its content

Option ``--dns-key-secret -`` will be then automatically prepended and secret key piped to docker-hostdns process.


2.0.0
=====

- added Docker image
- watched network interfaces can be now specified by user
- container name deduplication now only drops duplicate names
- single container can have multiple aliases
- short id and other container aliases are now available as dns names

1.1.1
=====

- it is now possible to run multiple instances in single dns zone
  `#2 <https://github.com/glorpen/docker-hostdns/pull/2>`__ (`dvenza <https://github.com/dvenza>`__)
- added option to override default instance name for use in txt records

1.1.0
=====

- possible breaking change: changed `dnspython3` package to just `dnspython` as Py3 is now supported

1.0.4
=====

- host names are now allowed to have dots in them

1.0.3
=====

- added tests
- added proper domain names coversion
- added a way to keep track of hosts when adding & removing containers

1.0.2
=====

- fixed error when handling disconnection event without earlier connect one
- added app exception logging


