/ 
NoZone-1.3
River stage zero No dependents
/ NoZone::Zone

NAME

Nozone::Zone - record information for a bind zone

SYNOPSIS

use Nozone::Zone;

my $nozone = Nozone::Zone->new(
  domains => [
    "nozone.org",
    "nozone.com",
  ],
  hostmaster => "hostmaster",
  lifetimes => {
    refresh => "1H",
    retry => "15M",
    expire => "1W"
    negative => "1H",
    ttl => "1H",
  },
  machines => {
    platinum => {
      ipv4 => "12.32.56.1"
      ipv6 => "2001:1234:6789::1"
    },
    gold => {
      ipv4 => "12.32.56.2"
      ipv6 => "2001:1234:6789::2"
    },
    silver => {
      ipv4 => "12.32.56.3"
      ipv6 => "2001:1234:6789::3"
    },
  },
  default => "platinum",
  spf => {
    policy => "reject",
    machines => [
       "gold",
       "silver"
    ]
  },
  dkim => {
    "default" => {
      version => "DKIM1",
      keytype => "rsa",
      pubkey => "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1TaNgLlSyQMNWVLNLvyY/neDgaL2oqQE8T5illKqCgDtFHc8eHVAU+nlcaGmrKmDMw9dbgiGk1ocgZ56NR4ycfUHwQhvQPMUZw0cveel/8EAGoi/UyPmqfcPibytH81NFtTMAxUeM4Op8A6iHkvAMj5qLf4YRNsTkKAV"
    },
  },
  dmarc => {
    version => "DMARC1",
    policy => "none",
    subdomain_policy => "none",
    percent => "20",
    forensic_report => "mailto:dmarcfail@example.com",
    aggregate_report => "mailto:dmarcagg@example.com",
  },
  mail => {
    mx0 => {
      priority => 10,
      machine => "gold"
    },
    mx1 => {
      priority => 30,
      machine => "silver"
    },
  },
  dns => {
    ns0 => "gold",
    ns1 => "silver",
  },
  names => {
    www => "platinum",
  },
  aliases => {
    db => "gold",
    backup => "silver",
  },
  txt => {
    challenge1 => "9e428dae-b677-49b6-9eb9-a5754cbbfc2c",
  },
  wildcard => "platinum",
  inherits => $parentzone,
);

foreach my $domain ($zone->get_domains()) {
  my $conffile = "/etc/named/$domain.conf";
  my $datafile = "/var/named/data/$domain.data";

  my $conffh = IO::File->new($conffile, ">");
  $zone->generate_conffile($conffh, $domain, $datafile);
  $conffh->close();

  my $datafh = IO::File->new($datafile, ">");
  $zone->generate_datafile($datafh, $domain);
  $datafh->close();
}

DESCRIPTION

The NoZone::Zone class records the information for a single DNS zone. A DNS zone can be associated with zero or more domain names. A zone without any associated domain names can serve as an abstract base from which other zones inherit data. Inheritance of zones allows admins to minimize the duplication of data across zones.

A zone contains a number of parameters, which are usually provided when the object is initialized.

domains

The domains parameter is an array reference providing the list of domain names associated with the DNS zone.

domains => [
  "nozone.org",
  "nozone.com",
]
hostmaster

The hostmaster parameter is the local part of the email address of the person who manages the domain. This will be combined with the domain name to form the complete email address

hostmaster => "hostmaster"
lifetimes

The lifetimes parameter specifies various times for DNS zone records. These are use to populate the SOA records in the zone.

lifetimes => {
  refresh => "1H",
  retry => "15M",
  expire => "1W"
  negative => "1H",
  ttl => "1H",
}
machines

The machines parameter is a hash reference whose keys are the names of physical machines. The values are further hash references specifying the IPv4 and IPv6 addresses for the names.

machines => {
  platinum => {
    ipv4 => "12.32.56.1"
    ipv6 => "2001:1234:6789::1"
  },
  gold => {
    ipv4 => "12.32.56.2"
    ipv6 => "2001:1234:6789::2"
  },
  silver => {
    ipv4 => "12.32.56.3"
    ipv6 => "2001:1234:6789::3"
  },
}
default

The default parameter is used to specify the name of the machine which will be use as the default when resolving the base domain name

default => "platinum"
mail

The mail parameter is a hash reference whose keys are the names to setup as mail servers. The values are an further has reference whose elements specify the priority of the mail server and the name of the machine defined in the machines parameter.

mail => {
  mx0 => {
    priority => 10,
    machine => "gold"
  },
  mx1 => {
    priority => 30,
    machine => "silver"
  },
}
dns

The dns parameter is a hash reference whose keys are the names to setup as DNS servers. The values are the names of machines defined in the machines parameter which are to used to define the corresponding IP addresses

dns => [
  ns0 => "gold",
  ns1 => "silver",
]
names

The names parameter is a hash reference whose keys reflect additional names to be defined as A/AAAA records for the zone. The values refer to keys in the machines parameter and are used to define the corresponding IP addresses

names => {
  www => "platinum",
}
aliases

The aliases parameter is a hash reference whose keys reflect additional names to be defiend as CNAME records for the zone. The values refer to keys in the machines or names parameter and are used to the define the CNAME target.

aliases => {
  db => "gold",
  backup => "silver",
}
wildcard

The wildcard parameter is a string refering to a name defined in the machines parameter. If set this parameter is used to defined a wildcard DNS entry in the zone.

wildcard => "platinum"
spf

The spf parameter is a hash reference setting up the SPF records. The policy key takes one of the values reject, accept, or mark, to specify what happens when an IP doesn't match the SPF. The machines key is an array reference that specifies the list of machine names that are permitted to send email.

dkim

The dkim parameter is a hash of hash references setting up the DKIM records. The key for the first level hash is the DKIM selector. The second level hashes contain the following keys.

The version key must always be DKIM1. The keytype key must be a public key algorithm name, typically 'rsa'. The service key is a string restricting the usage. The pubkey key is the public key.

dmarc

The dkim parameter is a hash reference setting up the DMARC records.

The version key must always be DMARC1. The policy key is one of none, quarantine or reject. The subdomain_policy key takes the same values. The percent key indicates how often to filter messages. The forensic_report and aggregate_report keys give a URI for sending reports.

txt

The txt parameter is a has of arbitrary key and value strings, which will be added as TXT records.

METHODS

my $zone = NoZone::Zone->new(%params);

Creates a new NoZone::Zone object to hold information about a DNS zone. The %params has keys are allowed to be any of the parameters documented earlier in this document. In addition the inherits parameter is valid and can refer to another instance of the NoZone::Zone class.

$zone->set_inherits($parentzone);

Sets the zone from which this zone will inherit data parameters. The $parentzone method should be an instance of the NoZone::Zone class.

my @domains = $zone->get_domains();

Returns the array of domain names associated directly with this zone.

my $name = $zone->get_hostmaster();

Returns the hostmaster setting associated with this zone, if any. If no hostmaster is set against this zone, then the hostmaster from any parent zone will be returned. If no parent zone is present, an undefined value will be returned.

my %lifetimes = $zone->get_lifetimes();

Return a hash containing the lifetimes defined against this zone. If no data is defined for this zone, then the data from any parent zone is returned. If not parent zone is set, then some sensible default times are returned.

my %machines = $zone->get_machines();

Return hash containing the union of all the machines defined in this zone and its parent(s) recursively.

$machine = $zone->get_machine($name);

Return a hash reference containing the IP addresses associated with the machine named $name.

my $name = $zone->get_default();

Returns the name of the machine to be used as the default for the zone. If no default is defined for this zone, then the default from any parent zone is defined. If no parent zone is defined, then return an undefined value

my %dns = $zone->get_dns();

Return a hash containing the union of all the machines defined as dns servers in this zone and its parent(s) recursively.

my %mail = $zone->get_mail();

Return a hash containing the union of all the machines defined as mail servers in this zone and its parent(s) recursively.

%names = $zone->get_names();

Return a hash containing the union of all the machine hostnames defined in this zone and its parent(s) recursively.

%names = $zone->get_aliases();

Return a hash containing the union of all the machine aliases defined in this zone and its parent(s) recursively.

%names = $zone->get_txt();

Return a hash containing the union of all the TXT records defined in this zone and its parent(s) recursively.

%selectors = $zone->get_dkim_selectors();

Return a hash containing the union of all the dkim records defined in this zone and its parent(s) recursively.

my $name = $zone->get_wildcard();

Return the name of the machine which will handle wildcard name lookups. If no wildcard is defined against the zone, returns the wildcard of the parent zone. If there is no parent zone, an undefined value is returned, indicating that no wildcard DNS entry will be created.

my $policy = $zone->get_spf_policy();

Returns the policy for SPF records for the domain. The policy is one of the string accept, reject or mark. If no SPF policy is defined gainst the zone, returns the SPF policy of the parent zone. if there is no parent zone an undefined value is returned indicating that no SPF entry will be created.

my @machines = $zone->get_spf_machines();

Returns the list of machines that are permitted to send mail to record as SPF records. If no machines are defined against the zone, returns the machines of teh parent zone. If there is no parent zone an empty list if returned

my $config = $zone->get_dmarc_config();

Returns the config for the DMARC records for the domain. If no DMARC config is defined gainst the zone, returns the DMAWRC config of the parent zone. if there is no parent zone undefined values are returned indicating that no DMARC entry will be created.

$zone->generate_conffile($fh, $domain, $datafile, \@masters, $verbose=0);

Generate a Bind zone conf file for the domain $domain writing the data to the file handle $fh. $fh should be an instance of IO::File. The optional $verbose parameter can be set to a true value to print progress on stdout. If @masters is a non-empty list, then a slave config will be created, otherwise a master config will be created. The $datafile parameter should specify the path to the corresponding zone data file, usually kept in /var/named/data.

$zone->generate_datafile($fh, $domain, $verbose=0);

Generate a Bind zone data file for the domain $domain writing the data to the file handle $fh. $fh should be an instance of IO::File. The optional $verbose parameter can be set to a true value to print progress on stdout.

AUTHORS

nozone was written by Daniel P. Berrange <dan@berrange.com>

LICENSE

nozone is distributed under the terms of the GNU GPL version 3 or any later version. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

SEE ALSO

NoZone, nozone(1)