NAME

Unix::Conf::Bind8::DB - Class implementing methods for manipulation of a Bind records file.

NOTE

Almost all methods need a label. All records are attached to one. If labels are not absolute (not ending in a '.'), they are considered relative to the DB origin (zone name). A label of '' means the records are attached to the origin itself. For example below the origin for the db is extremix.net. So any records with a label of '' is attached for extremix.net. Alternatively it could be specified as 'extremix.net.'

When an zone record file is read up, the label attribute is relative to the DB origin, the format it is in the zone record file notwithstanding. Same goes for the 'rdata' attribute.

The object must have a valid SOA record, since it is mandatory that every zone have one. If the object destructor is invoked without a defined SOA record, the destructor blows up. It is the responsibility of the user to ensure this.

SYNOPSIS

    use Unix::Conf::Bind8;

    my ($conf, $db, $rec, $ret);
    $conf = Unix::Conf::Bind8->new_conf (
        FILE    => 'named.conf',
        SECURE_OPEN     => 0
    ) or $conf->die ("couldn't get `named.conf'");

    $db = $conf->get_db ('extremix.net')
        or $db ->die ("couldn't get db for `extremix.net'");
        
    # All records have corresponding new_*, get_*, delete_*
    # methods. Only SOA doesn't have a set_* version, which
        # can be simulated by a delete_soa followed by a new_soa.

    # get a record object.
    $rec = $db->get_soa () or $rec->die ("couldn't get SOA");

    # add new A record. similarly for other record types 
    $ret = $db->new_a (
        LABEL   => 'ns3', 
        TTL             => '1d',
        RDATA   => '10.0.0.10',
    ) or $ret->die ("couldn't create A record for `ns3'");

    # delete a specific NS record
    $ret = $db->delete_ns ('', 'ns1')
        or $ret->die ("couldn't delete NS record `ns1' for `extremix.net'");

    # delete all MX records for domain www.extremix.net
    $ret = $db->delete_mx ('www')
        or $ret->die ("couldn't delete MX records for `extremix.net'");

        # delete all records for a label
        $ret = $db->delete_records ('subdomain.extremix.net.')
                or $ret->die ("couldnt delete records for `subdomain'");

        # get all NS records for extremix.net
        $ret = $db->get_ns ('')         
                or $ret->die ("couldn't get NS records for `extremix.net'");
        print ("NS records for extremix.net:\n");
        print $_->rdata (), "\n" for (@$ret);

        # get a specific record
        $rec = $db->get_a ('www', '192.168.1.1')
                or $rec->die ("couldn't get A record for www.extremix.net");
        print ("LABEL => www.extremix.net\n");
        printf ("TTL => %s\n", $ret) if ($ret = $rec->ttl ());
        printf ("CLASS => %s\n", $ret) if ($ret = $rec->class ());
        printf ("RTYPE => A\n", $ret);
        printf ("RDATA => 192.168.1.1");

        # Iterate over a list of all records.
        while (my $rec = $db->records ()) {
                # do stuff
        }

        # OR

        my @records = $db->records ();
        for (@records) {
                # do stuff
        }

DESCRIPTION

This class has interfaces for the various classes residing beneath Unix::Conf::Bind8::DB. This is an internal class should not be accessed directly. Methods in this class are to be accessed through a Unix::Conf::Bind8::DB object which is returned by Unix::Conf::Bind8->new_db () or by invoking the get_db () object method in Unix::Conf::Bind8::Conf or Unix::Conf::Bind8::Conf::Zone.

new ()

 Arguments
 FILE        => 'pathname',   # 
 ORIGIN      => 'value',      # origin
 CLASS       => 'class',      # ('in'|'hs'|'chaos')
 SECURE_OPEN => 0/1,          # optional (enabled (1) by default)

Class constructor Creates a Unix::Conf::Bind8::DB object and returns it if successful, an Err object otherwise. Direct use of this method is deprecated. Use Unix::Conf::Bind8::Zone::get_db (), or Unix::Conf::Bind8::new_db () instead.

origin ()

 Arguments
 'origin',   # optional. if the argument is not absolute, i.e.
             # having a trailing '.', the existing origin, if
                     # any will be appended to the argument.

Object method. Get/Set DB origin. If argument is passed, the method tries to set the origin of the DB object to 'origin' and returns true on success, an Err object otherwise. If no argument is specified, returns the name of the zone, if defined, an Err object otherwise.

fh ()

Object method. Returns the Unix::Conf::ConfIO object representing the DB file.

dirty ()

Object method. Get/Set the DIRTY flag in invoking Unix::Conf::Bind8::DB object.

class ()

 Arguments
 'class'      # ('in'|'hs'|'chaos')

Object method. Get/Set object class. If argument is passed, the method tries to set the class attribute to 'class' and returns true if successful, an Err object otherwise. If no argument is passed, returns the value of the class attribute if defined, an Err object otherwise. Note: Typically class is set in the zone statement. Each record can have a zone specified. But that cannot be different from the value set here.

delete_methods ()

 Argument
 'label'

Object method. Deletes all records attached to a label. Returns true on success, an Err object otherwise.

new_soa ()

 Arguments
 CLASS   =>
 TTL     =>
 AUTH_NS =>
 MAIL_ADDR   =>
 SERIAL  =>
 REFRESH =>
 RETRY   =>
 EXPIRE  =>
 MIN_TTL =>

Object method. Creates and associates a new Unix::Conf::Bind8::DB::SOA object with the invoking Unix::Conf::Bind8::DB object and returns it on success, an Err object otherwise.

get_soa ()

Object method. Returns the Unix::Conf::Bind8::DB::SOA object associated with the invoking Unix::Conf::Bind8::DB object if defined, an Err object otherwise.

delete_soa ()

Object method. Deletes the Unix::Conf::Bind8::DB::SOA object associated with the invoking Unix::Conf::Bind8::DB object if defined and returns true, an Err object otherwise.

new_ns ()

new_a ()

new_ptr ()

new_cname ()

 Arguments
 LABEL          =>
 CLASS          =>
 TTL            =>
 RDATA          =>

Object method. Creates and associates a corresponding Unix::Conf::Bind8::DB::* object with the invoking Unix::Conf::Bind8::DB object and returns it, on success an Err object otherwise.

new_mx ()

 Arguments
 LABEL          =>
 MXPREF         =>
 CLASS          =>
 TTL            =>
 RDATA          =>

Object method. Creates and associates a new Unix::Conf::Bind8::DB::MX object with the invoking Unix::Conf::Bind8::DB object and returns it, on success an Err object otherwise.

get_ns ()

get_a ()

get_ptr ()

get_cname ()

get_mx ()

 Arguments
 'label',
 'rdata'                        # optional

Object method. Returns the corresponding Unix::Conf::Bind8::DB::* object associated with the invoking Unix::Conf::Bind8::DB object, with label 'label' and rdata 'rdata'. If the rdata argument is not passed, then all `rdata' record objects attached to label 'label' are returned in an anonymous array. On failure an Err object is returned.

set_ns ()

set_a ()

set_ptr ()

set_cname ()

 Arguments
 'label',
 [
        { CLASS => 'class', TTL => 'ttl', RDATA => 'rdata',  },
        { CLASS => 'class', TTL => 'ttl', RDATA => 'rdata',  },
        ....
 ],

Object method. Creates and associates corresponding Unix::Conf::Bind8::DB::* objects with the relevant attributes with the invoking Unix::Conf::Bind8::DB object. Returns true on success, an Err object otherwise. The existing Unix::Conf::Bind8::DB::* objects attached to this label are deleted.

set_mx ()

 Arguments
 'label',
 [
        { CLASS => 'class', TTL => 'ttl', MXPREF => pref, RDATA => 'rdata',  },
        { CLASS => 'class', TTL => 'ttl', MXPREF => pref, RDATA => 'rdata',  },
        ....
 ],

Object method. Creates and associates Unix::Conf::Bind8::DB::MX objects with the relevant attributes with the invoking Unix::Conf::Bind8::DB object. Returns true on success, an Err object otherwise. The existing Unix::Conf::Bind8::DB::MX objects attached to this label are deleted.

delete_ns ()

delete_a ()

delete_ptr ()

delete_cname ()

delete_mx ()

 Arguments
 'label',
 'rdata',

Object method. Deletes the corresponding Unix::Conf::Bind8::DB::* object with label 'label' and rdata 'rdata', associated with the invoking Unix::Conf::Bind8::DB object if defined and returns true, an Err object. If the rdata argument is not passed, then all corresponding records attached to label 'label' are deleted.

records ()

Object method. Returns records defined in the zone. When called in a list context, returns all defined records. Iterates over defined records, when called in a scalar method. Returns `undef' at the end of one iteration, and starts over if called again.

TODO

1. Finalise on the interface. Remove superfluous ones.