<commit_before>pydnstest
=========

.. image:: https://pypip.in/v/pydnstest/badge.png
   :target: https://crate.io/packages/pydnstest

.. image:: https://pypip.in/d/pydnstest/badge.png
   :target: https://crate.io/packages/pydnstest


.. image:: https://secure.travis-ci.org/jantman/pydnstest.png?branch=master
   :target: http://travis-ci.org/jantman/pydnstest
   :alt: travis-ci for master branch

.. image:: https://coveralls.io/repos/jantman/pydnstest/badge.png?branch=master
   :target: https://coveralls.io/r/jantman/pydnstest?branch=master
   :alt: coverage report for master branch

Python tool for testing DNS changes (add, remove, rename, change records)
against a staging DNS server, verifying the same changes against production,
or confirming that a record returns the same result in both environments.

pydnstest is licensed under the GNU Affero General Public License version 3.

**Note - while the code is 100% covered by tests, this is a young project, and
I'm not sure that every code path has been executed in a live environment. As
such, until I can confirm that, I'd recommend repeating the same tests
manually for critical applications (like... say... everything in DNS...)** I
expect this to change quite soon, and am happy to receive both bug reports and
confirmations that everything works.

Requirements
------------

* Python 2.6+ (currently tested with 2.6, 2.7, 3.2, 3.3)
* Python `VirtualEnv <http://www.virtualenv.org/>`_ and ``pip`` (recommended installation method; your OS/distribution should have packages for these)
* *or* the following packages:

  * `pydns <https://pypi.python.org/pypi/pydns>`_ (python2) or `py3dns <https://pypi.python.org/pypi/py3dns>`_ (python3)
  * `pyparsing <https://pypi.python.org/pypi/pyparsing>`_

Installation
------------

It's recommended that you install into a virtual environment (virtualenv /
venv). See the `virtualenv usage documentation <http://www.virtualenv.org/en/latest/>`_
for information on how to create a venv. If you really want to install
system-wide, you can (using sudo).

.. code-block:: bash

    pip install pydnstest

Configuration
-------------

Either run ``pydnstest --promptconfig`` to interactively build and write out a configuration file
(to ``~/.dnstest.ini``) or run ``pydnstest --example-config > ~/.dnstest.ini`` and edit the
resulting file as desired.

You can view your current configuration with the ``--configprint`` option.

Usage
-----

pydnstest takes one or more specifications for DNS changes to be made, in a natural-language-like grammar, and tests a staging DNS server (and optionally verifies against a production/live server once the changes are live). For each specification, it prints out a simple one-line OK/NG summary, and optionally some helpful secondary messages and/or warnings. At the moment, it takes input either on STDIN or read from a file.

The following usage examples all assume that you've installed pydnstest in a
virtualenv located at ``~/venv_dir``. If you installed system-wide, simply
omit the first two lines (``cd ~/venv_dir`` and ``source bin/activate``).

Grammar
^^^^^^^

.. code-block:: bash

    add [record|name|entry] <hostname_or_fqdn> [with ][value|address|target] <hostname_fqdn_or_ip>
    remove [record|name|entry] <hostname_or_fqdn>
    rename [record|name|entry] <hostname_or_fqdn> [with] [value|address|target] <value> to <hostname_or_fqdn>
    change [record|name|entry] <hostname_or_fqdn> to <hostname_fqdn_or_ip>
    confirm <hostname_or_fqdn> (checks that TEST and PROD return identical results)

Sample input file
^^^^^^^^^^^^^^^^^

.. code-block:: bash

    add foo.example.com with address 1.2.3.4
    remove bar.example.com
    rename baz.example.com with value 1.2.3.5 to blam.example.com
    change quux.example.com to 1.2.3.6
    confirm blam.example.com

Usage with input file
^^^^^^^^^^^^^^^^^^^^^

Write a test file with the following content, at ~/inputfile.txt:

.. code-block:: bash

    add record newhost.example.com with address 10.188.8.90
    add record newhost-console.example.com with address 10.188.15.90

And then run the tests on it:

.. code-block:: bash

    jantman@palantir$ cd ~/venv_dir
    jantman@palantir$ source bin/activate
    (venv_dir)jantman@palantir$ pydnstest -f ~/inputfile.txt
    OK: newhost.example.com => 10.188.8.90 (TEST)
            PROD server returns NXDOMAIN for newhost.example.com (PROD)
            REVERSE OK: 10.188.8.90 => newhost.example.com (TEST)
    OK: newhost-console.example.com => 10.188.15.90 (TEST)
            PROD server returns NXDOMAIN for newhost-console.example.com (PROD)
            REVERSE OK: 10.188.15.90 => newhost-console.example.com (TEST)
    ++++ All 2 tests passed. (pydnstest 0.1.0)


Verify once in prod
^^^^^^^^^^^^^^^^^^^

After making the above changes live, verify them in production:

.. code-block:: bash

    jantman@palantir$ cd ~/venv_dir
    jantman@palantir$ source bin/activate
    (venv_dir)jantman@palantir$ pydnstest -f ~/inputfile.txt -V
    OK: newhost.example.com => 10.188.8.90 (PROD)
            REVERSE OK: 10.188.8.90 => newhost.example.com (PROD)
    OK: newhost-console.example.com => 10.188.15.90 (PROD)
            REVERSE OK: 10.188.15.90 => newhost-console.example.com (PROD)
    ++++ All 2 tests passed. (pydnstest 0.1.0)

Run one quick test
^^^^^^^^^^^^^^^^^^

Do a quick one-off test passed in on stdin, to confirm that prod and test
return the same result for a given name:

.. code-block:: bash

    jantman@palantir$ cd ~/venv_dir
    jantman@palantir$ source bin/activate
    (venv_dir)jantman@palantir$ echo "confirm foo.example.com" | pydnstest
    OK: prod and test servers return same response for 'foo.example.com' 
        response: {'name': 'foo.example.com', 'data': '10.10.8.2', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    ++++ All 1 tests passed. (pydnstest 0.1.0)

Run interactively from STDIN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also provide test data on STDIN. This is mainly useful when pulling test data
from another file, such as:

.. code-block:: bash

    jantman@phoenix:pts/12:~/tmp$ cat sample_zone.txt 
    $ORIGIN example.com.
    
    ;PYDNSTEST add record foo.example.com with address 10.10.8.2
    foo       IN     A     10.10.8.2
    ;PYDNSTEST add record bar.example.com with address 10.10.8.3
    bar       IN     A     10.10.8.3
    ;PYDNSTEST add record baz.example.com with address 10.10.8.4
    baz       IN     A     10.10.8.4
    jantman@palantir$ cd ~/venv_dir
    jantman@palantir$ source bin/activate
    (venv_dir)jantman@palantir$ grep "^;PYDNSTEST" ~/tmp/sample_zone.txt | sed 's/^;PYDNSTEST //' | pydnstest
    OK: prod and test servers return same response for 'foo.example.com' 
        response: {'name': 'foo.example.com', 'data': '10.10.8.2', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    OK: prod and test servers return same response for 'bar.example.com' 
        response: {'name': 'bar.example.com', 'data': '10.10.8.3', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    OK: prod and test servers return same response for 'baz.example.com' 
        response: {'name': 'baz.example.com', 'data': '10.10.8.4', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    ++++ All 3 tests passed. (pydnstest 0.2.2)

Bugs and Feature Requests
-------------------------

Bug reports and feature requests are happily accepted via the `GitHub Issue Tracker <https://github.com/jantman/pydnstest/issues>`_. Pull requests are
welcome. Issues that don't have an accompanying pull request will be worked on
as my time and priority allows.

License
-------

pydnstest is licensed under the `GNU Affero General Public
License <http://www.gnu.org/licenses/agpl-3.0.html>`_ version 3, with the
additional term that the Copyright and Authors attributions may not be removed
or otherwise altered, except to add the Author attribution of a contributor to
the work. (Additional Terms pursuant to Section 7b of the AGPL v3).

I chose AGPL mostly because I want this software to continue to evolve and
benefit from community involvement and improvement.

Development
===========<commit_msg>at least make the hostname the same in the examples<commit_after>pydnstest
=========

.. image:: https://pypip.in/v/pydnstest/badge.png
   :target: https://crate.io/packages/pydnstest

.. image:: https://pypip.in/d/pydnstest/badge.png
   :target: https://crate.io/packages/pydnstest


.. image:: https://secure.travis-ci.org/jantman/pydnstest.png?branch=master
   :target: http://travis-ci.org/jantman/pydnstest
   :alt: travis-ci for master branch

.. image:: https://coveralls.io/repos/jantman/pydnstest/badge.png?branch=master
   :target: https://coveralls.io/r/jantman/pydnstest?branch=master
   :alt: coverage report for master branch

Python tool for testing DNS changes (add, remove, rename, change records)
against a staging DNS server, verifying the same changes against production,
or confirming that a record returns the same result in both environments.

pydnstest is licensed under the GNU Affero General Public License version 3.

**Note - while the code is 100% covered by tests, this is a young project, and
I'm not sure that every code path has been executed in a live environment. As
such, until I can confirm that, I'd recommend repeating the same tests
manually for critical applications (like... say... everything in DNS...)** I
expect this to change quite soon, and am happy to receive both bug reports and
confirmations that everything works.

Requirements
------------

* Python 2.6+ (currently tested with 2.6, 2.7, 3.2, 3.3)
* Python `VirtualEnv <http://www.virtualenv.org/>`_ and ``pip`` (recommended installation method; your OS/distribution should have packages for these)
* *or* the following packages:

  * `pydns <https://pypi.python.org/pypi/pydns>`_ (python2) or `py3dns <https://pypi.python.org/pypi/py3dns>`_ (python3)
  * `pyparsing <https://pypi.python.org/pypi/pyparsing>`_

Installation
------------

It's recommended that you install into a virtual environment (virtualenv /
venv). See the `virtualenv usage documentation <http://www.virtualenv.org/en/latest/>`_
for information on how to create a venv. If you really want to install
system-wide, you can (using sudo).

.. code-block:: bash

    pip install pydnstest

Configuration
-------------

Either run ``pydnstest --promptconfig`` to interactively build and write out a configuration file
(to ``~/.dnstest.ini``) or run ``pydnstest --example-config > ~/.dnstest.ini`` and edit the
resulting file as desired.

You can view your current configuration with the ``--configprint`` option.

Usage
-----

pydnstest takes one or more specifications for DNS changes to be made, in a natural-language-like grammar, and tests a staging DNS server (and optionally verifies against a production/live server once the changes are live). For each specification, it prints out a simple one-line OK/NG summary, and optionally some helpful secondary messages and/or warnings. At the moment, it takes input either on STDIN or read from a file.

The following usage examples all assume that you've installed pydnstest in a
virtualenv located at ``~/venv_dir``. If you installed system-wide, simply
omit the first two lines (``cd ~/venv_dir`` and ``source bin/activate``).

Grammar
^^^^^^^

.. code-block:: bash

    add [record|name|entry] <hostname_or_fqdn> [with ][value|address|target] <hostname_fqdn_or_ip>
    remove [record|name|entry] <hostname_or_fqdn>
    rename [record|name|entry] <hostname_or_fqdn> [with] [value|address|target] <value> to <hostname_or_fqdn>
    change [record|name|entry] <hostname_or_fqdn> to <hostname_fqdn_or_ip>
    confirm <hostname_or_fqdn> (checks that TEST and PROD return identical results)

Sample input file
^^^^^^^^^^^^^^^^^

.. code-block:: bash

    add foo.example.com with address 1.2.3.4
    remove bar.example.com
    rename baz.example.com with value 1.2.3.5 to blam.example.com
    change quux.example.com to 1.2.3.6
    confirm blam.example.com

Usage with input file
^^^^^^^^^^^^^^^^^^^^^

Write a test file with the following content, at ~/inputfile.txt:

.. code-block:: bash

    add record newhost.example.com with address 10.188.8.90
    add record newhost-console.example.com with address 10.188.15.90

And then run the tests on it:

.. code-block:: bash

    jantman@phoenix$ cd ~/venv_dir
    jantman@phoenix$ source bin/activate
    (venv_dir)jantman@phoenix$ pydnstest -f ~/inputfile.txt
    OK: newhost.example.com => 10.188.8.90 (TEST)
            PROD server returns NXDOMAIN for newhost.example.com (PROD)
            REVERSE OK: 10.188.8.90 => newhost.example.com (TEST)
    OK: newhost-console.example.com => 10.188.15.90 (TEST)
            PROD server returns NXDOMAIN for newhost-console.example.com (PROD)
            REVERSE OK: 10.188.15.90 => newhost-console.example.com (TEST)
    ++++ All 2 tests passed. (pydnstest 0.1.0)


Verify once in prod
^^^^^^^^^^^^^^^^^^^

After making the above changes live, verify them in production:

.. code-block:: bash

    jantman@phoenix$ cd ~/venv_dir
    jantman@phoenix$ source bin/activate
    (venv_dir)jantman@phoenix$ pydnstest -f ~/inputfile.txt -V
    OK: newhost.example.com => 10.188.8.90 (PROD)
            REVERSE OK: 10.188.8.90 => newhost.example.com (PROD)
    OK: newhost-console.example.com => 10.188.15.90 (PROD)
            REVERSE OK: 10.188.15.90 => newhost-console.example.com (PROD)
    ++++ All 2 tests passed. (pydnstest 0.1.0)

Run one quick test
^^^^^^^^^^^^^^^^^^

Do a quick one-off test passed in on stdin, to confirm that prod and test
return the same result for a given name:

.. code-block:: bash

    jantman@phoenix$ cd ~/venv_dir
    jantman@phoenix$ source bin/activate
    (venv_dir)jantman@phoenix$ echo "confirm foo.example.com" | pydnstest
    OK: prod and test servers return same response for 'foo.example.com' 
        response: {'name': 'foo.example.com', 'data': '10.10.8.2', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    ++++ All 1 tests passed. (pydnstest 0.1.0)

Run interactively from STDIN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can also provide test data on STDIN. This is mainly useful when pulling test data
from another file, such as:

.. code-block:: bash

    jantman@phoenix:pts/12:~/tmp$ cat sample_zone.txt 
    $ORIGIN example.com.
    
    ;PYDNSTEST add record foo.example.com with address 10.10.8.2
    foo       IN     A     10.10.8.2
    ;PYDNSTEST add record bar.example.com with address 10.10.8.3
    bar       IN     A     10.10.8.3
    ;PYDNSTEST add record baz.example.com with address 10.10.8.4
    baz       IN     A     10.10.8.4
    jantman@phoenix$ cd ~/venv_dir
    jantman@phoenix$ source bin/activate
    (venv_dir)jantman@phoenix$ grep "^;PYDNSTEST" ~/tmp/sample_zone.txt | sed 's/^;PYDNSTEST //' | pydnstest
    OK: prod and test servers return same response for 'foo.example.com' 
        response: {'name': 'foo.example.com', 'data': '10.10.8.2', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    OK: prod and test servers return same response for 'bar.example.com' 
        response: {'name': 'bar.example.com', 'data': '10.10.8.3', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    OK: prod and test servers return same response for 'baz.example.com' 
        response: {'name': 'baz.example.com', 'data': '10.10.8.4', 'typename': 'A', 'classstr': 'IN', 'ttl': 360, 'type': 1, 'class': 1, 'rdlength': 4}
    ++++ All 3 tests passed. (pydnstest 0.2.2)

Bugs and Feature Requests
-------------------------

Bug reports and feature requests are happily accepted via the `GitHub Issue Tracker <https://github.com/jantman/pydnstest/issues>`_. Pull requests are
welcome. Issues that don't have an accompanying pull request will be worked on
as my time and priority allows.

License
-------

pydnstest is licensed under the `GNU Affero General Public
License <http://www.gnu.org/licenses/agpl-3.0.html>`_ version 3, with the
additional term that the Copyright and Authors attributions may not be removed
or otherwise altered, except to add the Author attribution of a contributor to
the work. (Additional Terms pursuant to Section 7b of the AGPL v3).

I chose AGPL mostly because I want this software to continue to evolve and
benefit from community involvement and improvement.

Development
===========
{'fraction_non_alphanumeric': 0.13669325598259607, 'fraction_numerical': 0.026831036983321246, 'mean_word_length': 3.553935057787562, 'pattern_counts': {'":': 0, '<': 35, '<?xml version=': 0, '>': 53, 'https://': 22, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 46, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '162178', 'n_tokens_mistral': 5769, 'n_tokens_neox': 5348, 'n_words': 1829}