This is the initial commit of the docs found in the original project.…

… Doing 'make html' won't work because the paths referenced in the docs are not correct and will be fixed when we decide on definite module path names.
ngokevin · Oct 10, 2012 · 6a5c287 · 6a5c287
1 parent 66d883c
commit 6a5c287
Show file tree

Hide file tree

Showing 30 changed files with 1,457 additions and 16 deletions.
diff --git a/docs/BIND.rst b/docs/BIND.rst
@@ -0,0 +1,6 @@
+.. _bind:
+
+Bind Files
+==========
+.. automodule:: mozdns.mozbind.build
+    :inherited-members:
diff --git a/docs/DHCP.rst b/docs/DHCP.rst
@@ -0,0 +1,53 @@
+.. _dhcp:
+.. |intr_ref| replace:: :ref:`StaticInterface`
+.. |intr| replace:: :class:`StaticInterface`
+.. |range| replace:: :class:`Range`
+
+DHCP
+====
+
+.. warning::
+    DHCP is implemented for |intr_ref| objects with IPv4 addresses. |intr|'s with IPv6 addresses
+    will not be included in the build output.
+
+The core function of the DHCP build system is the :func:`build_subnet` function which accecpts a
+:ref:`Network` instance as it's only input. Using the ``network``'s network address
+(``network_start``) and network broadcast (``network_end``) every |intr| with an IPv4 address
+greater than ``network_start`` less than ``network_end`` is used to generate a ``host`` statement::
+
+    host {{ intr.dhcp_name() }} {
+        hardware ethernet {{ intr.mac }};
+        fixed-address {{ intr.ip_str }};
+    }
+
+The above example is a ``host`` statement where jinja2 syntax is used to show how data from the
+|intr| is used to fill in data. The |intr| member function :func:`dhcp_name` is used as a way to
+make sure no two ``host`` statements have the same ``hostname``.
+
+.. note::
+
+    Because we are on a tight schedule, it might be worth it to just generate the host entries and
+    include them in the DHCP flat files in SVN like we are doing with current inventory. This would
+    be a slight modification and would save us time. Doing this means we don't have to put pool and
+    subnet options into inventory (could be time consuming sinse they are hard to parse and would
+    probably need to be entered by hand).
+
+Address Pools
+---------------
+There is a 1-to-1 mapping betweek address pools and :ref:`range` objects. A |range| object has a
+reference back to it's containing :ref:`Network`, so :func:`build_subnet` selects all |range|
+objects and passes the objects one by one into :func:`build_pool`. For each range all statements and
+options are gathered and added to the build output. Finally ``range.start_lower`` and
+``range.end_lower`` are used as the start and end number in the ``range`` statement (``start_upper``
+and ``end_upper`` are only relevent for IPv6 addresses who have more than 64 bits of information).
+
+DHCP Options and Statements
+---------------------------
+
+Both ranges and networks have ways of controlling what options and statements go into their
+respective ``subnet`` and ``pool`` statements. These options and statements are stored in the
+:class:`NetworkKeyValue` and :class:`RangeKeyValue` tables as Key Value pairs.
+
+
+.. autofunction:: core.build.subnet.build_subnet
+.. autofunction:: core.build.subnet.build_pool
diff --git a/docs/address_record.rst b/docs/address_record.rst
@@ -0,0 +1,7 @@
+.. _address_record:
+
+Address Record
+==============
+.. automodule:: mozdns.address_record.models
+    :inherited-members:
+
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,75 @@
+Inventory DNS API
+=================
+
+A high level view of how the API works::
+
+    +------+
+    | User |
+    +------+
+        |
+    +------------------------+
+    | Command Line Interface |   <----------- See page on CLI for this
+    +------------------------+
+        |
+    +---------------+
+    | HTTP POST/GET |   <----------- This document defines what is happening here.
+    +---------------+
+        |
+    +----------+
+    | Iventory |
+    +----------+
+        |
+    +----------+
+    | Database |
+    +----------+
+
+DNS Objects
+-----------
+The following DNS objects can be created, updated, and deleted via HTTP API requests.
+
+    * A records
+    * AAAA records
+    * CNAME records
+    * TXT records
+    * MX records
+    * SRV records
+    * NS records
+    * SSHFP records
+
+The following cannot be created, updated, or deleted via HTTP API requests.
+
+    * SOA records
+    * Certain Domain objects
+        - see :ref:`label_domain`. Only purgeable domains can be created via the API.
+
+Views and Key Value
+-------------------
+View objects need their associated object to exist before they can be created. Underneath the hood,
+these objects are validated and saved *after* their associtated object is saved or updated.
+
+Currently, updating views is done by supplying the desired objects' state. For example, if you
+want to add an object to the public view and the object was already in the private view, you would
+post the list::
+
+    'views': ['public', 'private']
+
+If you were to send an emtry list::
+
+    'views': []
+
+Any views the object was associated with would be deleted.
+
+The best way to update an object is to first GET the object, modify the JSON returned by the API,
+and then PATCH it back.
+
+Key Value Pairs
+---------------
+Updating key value (kv) pairs that are associated with an object is done just like any other
+attribute on the object except it must be done with only the 'key' and 'value' parameters in the
+request. This means that updating a field, like 'comment', and a key value pair is not allowed::
+
+    {'key': 'foo', 'value': 'bar', 'comment': 'a new comment'}
+
+The above is not allowed because 'key' and 'value' must be the only elements in the JSON.
+
+You should post kv pairs to the end point of the object is associated to the kv pair.
diff --git a/docs/cname.rst b/docs/cname.rst
@@ -0,0 +1,17 @@
+.. _cname:
+
+CNAME
+=====
+
+    "Don't go overboard with CNAMEs."
+
+    "Domain names in RRs which point at another name should always point at the primary name and not the
+    alias."
+
+    -- `RFC 1034 <http://tools.ietf.org/html/rfc1034>`_
+
+
+CNAME
+-----
+.. automodule:: mozdns.cname.models
+    :inherited-members:
diff --git a/docs/coding_standard.rst b/docs/coding_standard.rst
@@ -0,0 +1,40 @@
+.. _coding_standards:
+
+Coding Ideas (Standards)
+========================
+
+The Zen of Python, by Tim Peters::
+
+    Beautiful is better than ugly.
+    Explicit is better than implicit.
+    Simple is better than complex.
+    Complex is better than complicated.
+    Flat is better than nested.
+    Sparse is better than dense.
+    Readability counts.
+    Special cases aren't special enough to break the rules.
+    Although practicality beats purity.
+    Errors should never pass silently.
+    Unless explicitly silenced.
+    In the face of ambiguity, refuse the temptation to guess.
+    There should be one-- and preferably only one --obvious way to do it.
+    Although that way may not be obvious at first unless you're Dutch.
+    Now is better than never.
+    Although never is often better than *right* now.
+    If the implementation is hard to explain, it's a bad idea.
+    If the implementation is easy to explain, it may be a good idea.
+    Namespaces are one honking great idea -- let's do more of those!
+
+
+Follow pep8::
+
+    pip install pep8
+    pep8 <all of the files!!>
+
+Model code should have 100% statement coverage.
+
+Before you do anything with an IP address (as a string or int) put it into the ipaddr library
+functions IPv4Address and IPv6Address. This will standardize how things are formated, stored, and
+displayed.
+
+In most cases policy should happen in forms and function should happen in models.
diff --git a/docs/common_record.rst b/docs/common_record.rst
@@ -0,0 +1,13 @@
+.. _common_record:
+
+Common Record
+=============
+
+The common record class is inherited by common DNS record classes. ``CommonRecord`` is an abstract class meaning there is not table in the database coresponding to it's declaration. It is subclassed by the ``TXT``, ``MX``, ``CNAME``, and ``SRV`` classes.
+
+
+.. automodule:: mozdns.models
+    :inherited-members:
+
+.. automodule:: mozdns.views
+    :inherited-members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,7 +17,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 

diff --git a/docs/core.rst b/docs/core.rst
@@ -0,0 +1,93 @@
+.. _core:
+
+IPAM
+====
+A system that manages DNS and DHCP is useless without knowledge of the networks
+the hosts using DNS and DHCP are located in. The core of inventory is it's
+:class:`Site`\s, :class:`Network`\s, and :class:`Range`\s.
+
+Sites
+-----
+A :ref:`site` represents a datacenter or a business unit. Much like
+:ref:`domain`\s are organized into a hierarchy with 'master domains', a site
+can have a 'parent site'.
+
+
+.. figure:: images/mozcore_sites.png
+
+Here four sites are shown. Scl3 is the parent site of Releng and Phx1 is the
+Parent site of Svc. If Relenge were also in Scl2, there would be another
+instance of a site called Relenge that had a parent site of Scl2.
+
+Networks
+--------
+A :ref:`network` represents an IPv4/IPv6 network. Networks also related to eachother in a heirarchical way. Since networks are inherently contained within other networks, no explicit parent child relationship is stored in the database. Networks are homed in a site.
+
+
+.. figure:: images/mozcore_networks.png
+
+Here networks are laid out along their logical CIDER boundaries. Multiple networks can
+be associated with one site, but a network cannot be associated with multiple
+sites.
+
+Vlans
+-----
+
+For the majority of cases, a network is associated with a :ref:`vlan`.
+
+.. figure:: images/mozcore_all.png
+
+Here networks are shown under vlans. A network can belong to zero or one vlan.
+Many networks can belong to the same vlan.
+
+The little red lines under the network objects are :ref:`range` objects.
+
+Ranges
+------
+
+Range objects belong inside of a network; a range's start number is greater than or equal to the
+network address and the range's end number is less than the broadcast address. Ranges are used to
+help determine where free IP's lay within a network, which is useful when creating a
+:ref:`staticinterface`.
+
+Here is a beautiful depiction of a range and a network::
+
+    Network:                    192.168.0.0/24
+    |--------------------------------------------------------------|
+    192.168.0.0                                                    192.168.0.255
+
+    Range:
+                |-------------------------------------------------|
+                192.168.0.10                                      192.168.0.254
+
+
+Ranges can be used as a pool of allocatable IP addresses. When a new :ref:`staticinterface`
+(seriously, read about these things) is created it needs an IP address and a range is where the
+interface will look if the interface is to have it's IP address assigned automatically.
+
+Other Purposes
+++++++++++++++
+
+.. note::
+    These features (as of 08/12/2012) are not implemented.
+
+Ranges are multipurpose. For example a range can be used as a 'dynamic' range. A dynamic range is a
+pool ip addresses where wireless clients or other clients that don't need a fixed addresses have
+their IP assignment come from. In DHCP these dynamic ranges usually associated with a pool statement
+that contains an ``allow`` clause. In DNS a dynamic range will usually have a long list of similar
+names statically created for every ip in the range; for example ``GENERATE 4-100
+dynamic-$.vlan.mozilla.com``. When you flag a range as 'dynamic' the DNS build scripts will
+automatically print these records when DNS zone files are generated.
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/cyder_intro.rst b/docs/cyder_intro.rst
@@ -0,0 +1,45 @@
+`Cyder <https://github.com/uberj/Cyder>`_ is an `IPAM <http://en.wikipedia.org/wiki/IP_address_management>`_ solution. It is split up into two logically separate apps; ``cydns`` (DNS) and ``cydhcp`` (DHCP). The goal is two have the two apps be standalone and have less generic code 'glue' them together.
+
+The 'glue' (not to be confused with DNS glue records) is found in ``core/``.
+
+Maintain
+--------
+Cyder is designed to replace `Maintain <http://maintainproject.osuosl.org/>`_. Maintain 2.5 was the
+last version released. Maintain 3 was written in purely in PHP and didn't work too well.
+Aside from initially being written almost a decade ago, Maintain has been used in production at OSU
+for over 10 years.
+
+Taken from Maintain's README, here are the abridged requirements of Maintain:
+
+* Web-based interface
+* Ability to delegate authority of zone information to individual users/groups
+* Quick updates (changes need to be reflected within 10 minutes)
+* Advanced error reporting for zone transfers and DHCP server problems
+* Generate zone files and DHCP configurations for primary and secondary DNS & DHCP servers
+* Edit host information including MAC address, hostname, domain name, etc.
+* Zone statistics such as total bandwidth used and bandwidth history for individual hosts
+* Support for automatic registration on public networks (using authentication)
+* Search by hostname, domain, zone, IP address and any other DNS type
+* Ability to develop additional features through a module interface
+
+Cyder will have all of these features and more.
+
+Maintain Bugs
++++++++++++++
+* DNSSEC is not supported.
+* Certain DNS records that were at domain level were not supported (they have been hacked in).
+* No support of other DNS output types. Only ``tinydns`` is supported.
+* The following DNS record types are not supported ``SRV``, ``TXT``, (more)?
+* DNS Zone delegation is broken.
+* When a (maintain) zone administrator wants to manually assign an IP address to a client, DHCP needs to be bypassed.
+  Maintian does this by providing a mac with all zeroes. It's a kludge.
+* There can be several different ``defualt_domains`` assigned to the same range.
+* Poor searching capabilities.
+* Maintain was not built with a web framework. Ironically, this makes the code very hard to maintain.
+* Written in PHP.
+
+Maintain has it's weaknesses, but overall it does get the job done. It has already been shown that
+Maintain's existing DNS scheme *does* `support building bind files
+<https://github.com/uberj/maintain-bindbuilds>`_ (some modification to data in the database was
+required due to poor data validation). Cyder is Maintain with a more formal structure. Cyder uses
+many core concepts from Maintain.