Commit 0b8cf4dc authored by ale's avatar ale

Convert README to Markdown

parent c6d231c3
Pipeline #1126 passed with stages
in 47 seconds
========
zonetool zonetool
======== ========
...@@ -11,119 +9,116 @@ simplify large deployments. ...@@ -11,119 +9,116 @@ simplify large deployments.
The basic entity of the data model is a dictionary corresponding to a The basic entity of the data model is a dictionary corresponding to a
DNS zone. The dictionary key/value pairs correspond to individual DNS DNS zone. The dictionary key/value pairs correspond to individual DNS
resource records. Some keys are special: they define attributes of resource records. Some keys are special: they define attributes of the
the zone itself - they are usually recognizable because they're zone itself - they are usually recognizable because they're uppercase
uppercase (while normal DNS record names are lowercase). (while normal DNS record names are lowercase).
## Configuration
Configuration
=============
The zone configuration is stored in YAML format, usually spread into The zone configuration is stored in YAML format, usually spread into
multiple files, one per template or zone (though it is possible to multiple files, one per template or zone (though it is possible to store
store the configuration for more than one zone in a single YAML file). the configuration for more than one zone in a single YAML file). By
By default, the tool scans a given directory recursively looking for default, the tool scans a given directory recursively looking for files
files with the ``.yml`` extension. File names are ignored and only with the *.yml* extension. File names are ignored and only have a
have a mnemonic purpose. mnemonic purpose.
Record syntax ### Record syntax
-------------
A DNS entry consists of a name and one or more resource records, so in A DNS entry consists of a name and one or more resource records, so in
our model the dictionary values can be either strings, or lists of our model the dictionary values can be either strings, or lists of
strings (a single string is just a shorthand syntax for a list strings (a single string is just a shorthand syntax for a list
containing a single element). All names are relative to the zone containing a single element). All names are relative to the zone origin,
origin, except for the special name consisting of a single underscore except for the special name consisting of a single underscore (`_`),
(``_``), which stands for the zone origin itself. which stands for the zone origin itself.
Each resource record consists of a DNS RR type, and the associated Each resource record consists of a DNS RR type, and the associated data,
data, separated by a space (the resource data can contain further separated by a space (the resource data can contain further spaces). The
spaces). The resource record will be written verbatim to the resulting resource record will be written verbatim to the resulting zone file (the
zone file (the ``IN`` namespace is assumed), for example:: *IN* namespace is assumed), for example:
inventati.org: ```yaml
_: inventati.org:
- A 1.2.3.4 _:
- AAAA 2001:1:2:3::4 - A 1.2.3.4
- MX 10 mx1.inventati.org. - AAAA 2001:1:2:3::4
- MX 10 mx1.inventati.org.
describes three different DNS records, all for the zone origin: one ```
IPv4 address, an IPv6 one, and a MX record for SMTP delivery.
describes three different DNS records, all for the zone origin: one IPv4
address, an IPv6 one, and a MX record for SMTP delivery.
Since A and AAAA records are usually the most common by far, a special Since A and AAAA records are usually the most common by far, a special
shorthand notation allows you to simply specify the IP address, and shorthand notation allows you to simply specify the IP address, and the
the record type will be automatically determined. So, the above zone record type will be automatically determined. So, the above zone could
could have been written as:: have been written as:
inventati.org: ```yaml
_: inventati.org:
- 1.2.3.4 _:
- 2001:1:2:3::4 - 1.2.3.4
- MX 10 mx1.inventati.org. - 2001:1:2:3::4
- MX 10 mx1.inventati.org.
```
Templates and inheritance ### Templates and inheritance
-------------------------
Each zone can have an *EXTENDS* attribute, which contains a list of zone
Each zone can have an ``EXTENDS`` attribute, which contains a list of names that will be merged into the current one. It is possible to use
zone names that will be merged into the current one. It is possible to this feature as a full-blown templating system by taking advantage of
use this feature as a full-blown templating system by taking advantage the fact that zones whose name starts with a *@* are not going to be
of the fact that zones whose name starts with a ``@`` are not going to present in the output. In fact, one such zone is always defined:
be present in the output. In fact, one such zone is always defined: *@default* (empty by default), and it is automatically added to the
``@default`` (empty by default), and it is automatically added to the *EXTENDS* attribute of every zone that does **not** start with a *@*
``EXTENDS`` attribute of every zone that does **not** start with a character.
``@`` character.
Perhaps some examples can clarify the mechanism:
Perhaps some examples can clarify the mechanism::
```yaml
autistici.org: autistici.org:
www: 1.2.3.4 www: 1.2.3.4
inventati.org: inventati.org:
www: 2.3.4.5 www: 2.3.4.5
"@default": "@default":
_: _:
- NS ns1.example.com. - NS ns1.example.com.
- NS ns2.example.com. - NS ns2.example.com.
```
In the above case, the two zones defined will both have NS records In the above case, the two zones defined will both have NS records
pointing at ``ns1.example.com`` and ``ns2.example.com``. pointing at *ns1.example.com* and *ns2.example.com*.
Another example:: Another example:
autistici.org: ```yaml
EXTENDS: autistici.org:
- @base EXTENDS:
www: 1.2.3.4 - @base
"@base": www: 1.2.3.4
_spf: TXT "v=spf1 -all" "@base":
"@default": _spf: TXT "v=spf1 -all"
_: NS ns1.example.com. "@default":
_: NS ns1.example.com.
```
here the ``autistici.org`` zone will not only include the NS record here the *autistici.org* zone will not only include the NS record from
from ``@default``, but it will also contain the ``_spf`` TXT record *@default*, but it will also contain the *_spf* TXT record from the
from the ``@base`` template. *@base* template.
### Special zone attributes
Special zone attributes Besides EXTENDS described above, there are a few other special
----------------------- attributes that can be set on a zone. They are recognizable from normal
records because they are specified in uppercase:
Besides `EXTENDS` described above, there are a few other special
attributes that can be set on a zone. They are recognizable from
normal records because they are specified in uppercase:
* `TTL` sets the TTL for the zone * `TTL` sets the TTL for the zone
* `REFRESH` sets the SOA refresh time * `REFRESH` sets the SOA refresh time
* `RETRY` sets the SOA retry time * `RETRY` sets the SOA retry time
* `EXPIRE` sets the SOA expire time * `EXPIRE` sets the SOA expire time
* `NEG_CACHE` sets the SOA negative caching time * `NEG\_CACHE` sets the SOA negative caching time
By default, generated zones will have a TTL of 1 hour. By default, generated zones will have a TTL of 1 hour.
### Variable substitution and configuration
Variable substitution and configuration
---------------------------------------
Along with the zone dictionaries, it is also possible to specify Along with the zone dictionaries, it is also possible to specify
arbitrary resource records in a global *configuration*: these records arbitrary resource records in a global *configuration*: these records
...@@ -131,24 +126,30 @@ are not associated with a specific zone, and they can be substituted ...@@ -131,24 +126,30 @@ are not associated with a specific zone, and they can be substituted
in-place using a shell-like variable expansion syntax. in-place using a shell-like variable expansion syntax.
For instance, assume that you have a list of IPs which appear in For instance, assume that you have a list of IPs which appear in
multiple records in your DNS zones: it would be nice to maintain multiple records in your DNS zones: it would be nice to maintain the
the full list in a single place. So, if your configuration contains:: full list in a single place. So, if your configuration contains:
FRONTENDS = ['1.2.3.4', '2.3.4.5'] ```
FRONTENDS = ['1.2.3.4', '2.3.4.5']
```
it is then possible to define a zone as follows:: it is then possible to define a zone as follows:
autistici.org: ```yaml
_: "$FRONTENDS" autistici.org:
www: "$FRONTENDS" _: "$FRONTENDS"
www: "$FRONTENDS"
```
The tool will try to do the right thing when expanding list variables, The tool will try to do the right thing when expanding list variables,
whether within a list or not. For instance, a zone such as:: whether within a list or not. For instance, a zone such as:
autistici.org: ```yaml
_: autistici.org:
- $SERVERS _:
- MX 10 $SERVERS - $SERVERS
- MX 10 $SERVERS
```
will result in a zone containing an A record and an MX record for each will result in a zone containing an A record and an MX record for each
entry defined in `SERVERS`. entry defined in *SERVERS*.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment