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",
    mail => {
      mx0 => {
        priority => 10,
        machine => "gold"
      },
      mx1 => {
        priority => 30,
        machine => "silver"
      },
    },
    dns => {
      ns0 => "gold",
      ns1 => "silver",
    },
    names => {
      www => "platinum",
    },
    aliases => {
      db => "gold",
      backup => "silver",
    },
    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 has 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"

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.

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.

$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.