<commit_before>=======
minidns
=======

:Date: 2013-09-11
:Author: <NAME> <<EMAIL>>
:Website: http://github.com/yaybu/minidns

Description
===========

MiniDNS is a DNS server for developers. It is intended to serve DNS only for a
single machine - your desktop. It will support automated deployment systems
that coordinate with DNS services, for example Yaybu.

Desktops vary in their client DNS configuration quite widely, and MiniDNS
supports a number of different modes to enable it to service your DNS effectively.

The DNS service provides recursive queries, so you can continue to use DNS as usual.

You can then set new authoritative domains and A records that are available
locally.

For example::

    $ minidns start
    $ host www.example.com
    www.example.com has address 172.16.31.10
    www.example.com has IPv6 address fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b
    $ minidns add example.com
    $ minidns record example.com a www 192.168.0.10
    $ minidns show example.com
    www 192.168.0.10
    $ host www.example.com
    www.example.com has address 192.168.0.10
    $ minidns stop
    $ host www.example.com
    www.example.com has address 172.16.31.10
    www.example.com has IPv6 address fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b

Usage::

    Usage: minidns [options] command

    daemon control commands:
        start  start the minidns server and forward localhost:53 to it
        stop   stop the minidns server and remove iptables rules

    zone commands:
        add name  add a new local authoritative zone "name"
        del name  delete the local authoritative zones "name"
        list      list all authoritative zones
        show name list records for the zone "name"

    record commands:
        record zone a host [data]   create A record
        record zone del host        delete record

        e.g. record example.com a www 192.168.0.1

    Options:
      -h, --help            show this help message and exit
      -c CONFIG, --config=CONFIG
                            path to configuration file

Modes of operation
==================

For the standard libc resolver DNS services must be provided on port 53 - there
is no option for the resolver to consult other ports.

MiniDNS must therefore either run on udp port 53 (which means it must be
started as root), or run on a high port and have some form of port-forwarding
configured.

If you already have a nameservice running locally (which is not uncommon) then
you may wish to use the port-forwarding features.

The standard configuration for the libc resolver is in /etc/resolv.conf. This
file will need to have only a single nameserver, 127.0.0.1, configured for
MiniDNS to work. MiniDNS provides options to overwrite the configuration in
resolv.conf as part of starting up. It will then replace the previous
configuration when it is stopped.

Finally MiniDNS requires "forwarders" - other servers that will answer
recursive queries for domains for which MiniDNS is not authoritative.

MiniDNS attempts to provide intelligent behaviour by default so that none of these things need to be configured manually, as follows:

    1. on starting it will read /etc/resolv.conf. If this does not contain a 127.0.0.1 nameserver then it will read the nameservers and use them as forwarders, otherwise it will use the forwarders from the configuration file or 8.8.8.8 / 8.8.4.4 as fallbacks.
    2. it will then attempt to bind to port 53 locally.
    3. if it cannot bind to port 53, because it is in use or because MiniDNS was not started as root, then it will bind to the port configured in the configuration file (or 5053 by default) and trigger port-forwarding behaviour (as below)
    4. if the resolv.conf file did not contain 127.0.0.1 then it is copied out to the temporary directory and the original rewritten to use 127.0.0.1

port-forwarding:

    1. if a "port-forward" configuration option is provided, then it is executed
    2. otherwise, if the "iptables" program is available, then appropriate iptables incantations are used.
    3. if neither of these options is available then the program will terminate with an error, and you will need to provide configuration

You can force particular behaviour by setting the "forward" and "rewrite" configuration options:

forward
-------

If this is "true" then the server will not attempt to bind to port 53. If this is "false" then the server will bail if it cannot bind to port 53.

rewrite<commit_msg>clearer shutdown<commit_after>=======
minidns
=======

:Date: 2013-09-11
:Author: <NAME> <<EMAIL>>
:Website: http://github.com/yaybu/minidns

Description
===========

MiniDNS is a DNS server for developers. It is intended to serve DNS only for a
single machine - your desktop. It will support automated deployment systems
that coordinate with DNS services, for example Yaybu.

Desktops vary in their client DNS configuration quite widely, and MiniDNS
supports a number of different modes to enable it to service your DNS effectively.

The DNS service provides recursive queries, so you can continue to use DNS as usual.

You can then set new authoritative domains and A records that are available
locally.

For example::

    $ minidns start
    $ host www.example.com
    www.example.com has address 172.16.31.10
    www.example.com has IPv6 address fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b
    $ minidns add example.com
    $ minidns record example.com a www 192.168.0.10
    $ minidns show example.com
    www 192.168.0.10
    $ host www.example.com
    www.example.com has address 192.168.0.10
    $ minidns stop
    $ host www.example.com
    www.example.com has address 172.16.31.10
    www.example.com has IPv6 address fd00:a516:7c1b:17cd:6d81:2137:bd2a:2c5b

Usage::

    Usage: minidns [options] command

    daemon control commands:
        start  start the minidns server and forward localhost:53 to it
        stop   stop the minidns server and remove iptables rules

    zone commands:
        add name  add a new local authoritative zone "name"
        del name  delete the local authoritative zones "name"
        list      list all authoritative zones
        show name list records for the zone "name"

    record commands:
        record zone a host [data]   create A record
        record zone del host        delete record

        e.g. record example.com a www 192.168.0.1

    Options:
      -h, --help            show this help message and exit
      -c CONFIG, --config=CONFIG
                            path to configuration file

Modes of operation
==================

For the standard libc resolver DNS services must be provided on port 53 - there
is no option for the resolver to consult other ports.

MiniDNS must therefore either run on udp port 53 (which means it must be
started as root), or run on a high port and have some form of port-forwarding
configured.

If you already have a nameservice running locally (which is not uncommon) then
you may wish to use the port-forwarding features.

The standard configuration for the libc resolver is in /etc/resolv.conf. This
file will need to have only a single nameserver, 127.0.0.1, configured for
MiniDNS to work. MiniDNS provides options to overwrite the configuration in
resolv.conf as part of starting up. It will then replace the previous
configuration when it is stopped.

Finally MiniDNS requires "forwarders" - other servers that will answer
recursive queries for domains for which MiniDNS is not authoritative.

MiniDNS attempts to provide intelligent behaviour by default so that none of these things need to be configured manually, as follows:

    1. on starting it will read /etc/resolv.conf. If this does not contain a 127.0.0.1 nameserver then it will read the nameservers and use them as forwarders, otherwise it will use the forwarders from the configuration file or 8.8.8.8 / 8.8.4.4 as fallbacks.
    2. it will then attempt to bind to port 53 locally.
    3. if it cannot bind to port 53, because it is in use or because MiniDNS was not started as root, then it will bind to the port configured in the configuration file (or 5053 by default) and trigger port-forwarding behaviour (as below)
    4. if the resolv.conf file did not contain 127.0.0.1 then it is copied out to the temporary directory and the original rewritten to use 127.0.0.1

port-forwarding:

    1. if a "port-forward" configuration option is provided, then it is executed
    2. otherwise, if the "iptables" program is available, then appropriate iptables incantations are used.
    3. if neither of these options is available then the program will terminate with an error, and you will need to provide configuration

When the server is stopped it will:

    1. put the resolv.conf file back as it was before, if it was rewritten
    2. stop port-forwarding, either by using the port-unforward option or by using iptables, as appropriate

Configuring behaviour
---------------------

You can force particular behaviours by setting the "forward" and "rewrite" configuration options:

forward
-------

If this is "true" then the server will not attempt to bind to port 53. If this is "false" then the server will bail if it cannot bind to port 53.

rewrite
{'fraction_non_alphanumeric': 0.06104207543056464, 'fraction_numerical': 0.03466317854807063, 'mean_word_length': 3.2516218721038, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 22, 'xml': 0}, 'pii_count': 24, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1810697', 'n_tokens_mistral': 2717, 'n_tokens_neox': 2462, 'n_words': 1298}