NAME

PowerDNS::Backend::MySQL - Provides an interface to manipulate PowerDNS data in the MySQL Backend.

VERSION

Version 0.12

SYNOPSIS

use PowerDNS::Backend::MySQL;

# Setting parameters and their default values.
my $params = {	db_user			=>	'root',
		db_pass			=>	'',
		db_name			=>	'pdns',
		db_port			=>	'3306',
		db_host			=>	'localhost',
		mysql_print_error	=>	1,
		mysql_warn		=>	1,
		mysql_auto_commit	=>	1,
		mysql_auto_reconnect	=>	1,
		lock_name		=>	'powerdns_backend_mysql',
		lock_timeout		=>	3,
};

my $pdns = PowerDNS::Backend::MySQL->new($params);

DESCRIPTION

PowerDNS::Backend::MySQL provides a layer of abstraction 
for manipulating the data stored in the PowerDNS MySQL backend.

METHODS

new(\%params)

my $params = {	db_user			=>	'root',
		db_pass			=>	'',
		db_name			=>	'pdns',
		db_port			=>	'3306',
		db_host			=>	'localhost',
		mysql_print_error	=>	1,
		mysql_warn		=>	1,
		mysql_auto_commit	=>	1,
		mysql_auto_reconnect	=>	1,
		lock_name		=>	'powerdns_backend_mysql',
		lock_timeout		=>	3,
};

my $pdns = PowerDNS::Backend::MySQL->new($params);

Creates a PowerDNS::Backend::MySQL object.

db_user: The DB user to use when connecting to the MySQL Backend.
db_pass: The DB password to use when connecting to the MySQL Backend.
db_name: The DB name to use when connecting to the MySQL Backend.
db_port: The DB port to use when connecting to the MySQL Backend.
db_host: The DB host to use when connecting to the MySQL Backend.
mysql_print_error: Used to set the DBI::PrintError value.
mysql_warn: Used to set the DBI::Warn value.
mysql_auto_commit: Used to set the DBI::AutoCommit value.
mysql_auto_reconnect: Used to set the DBD::mysql::mysql_auto_reconnect value.
lock_name: Critical sections (adds, deletes, updates on records) get MySQL application level locks (GET_LOCK : http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_get-lock); this option can be used to override the default lock name used in those calls.
lock_timeout: Critical sections (adds, deletes, updates on records) get MySQL application level locks (GET_LOCK : http://dev.mysql.com/doc/refman/5.0/en/miscellaneous-functions.html#function_get-lock); this option can be used to override the default lock timeout used in those calls.

add_domain(\$domain)

Expects a scalar reference domain name to add to the DB. Returns 1 on success and 0 on failure.

add_master(\$domain)

Expects a scalar reference domain name to add to the DB as type master. Returns 1 on success and 0 on failure.

add_slave(\$slave_domain , \$master_ip)

Expects two scalar references; first the domain to slave, then the IP address to slave from. Returns 1 on success and 0 on failure. Updates the existing record if there is one, otherwise inserts a new record.

delete_domain(\$domain)

Expects a scalar reference domain name to delete from the DB. Returns 1 on success and 0 on failure.

list_domain_names

Does not expect anything. Returns a reference to an array which contains all the domain names listed in the PowerDNS backend.

list_domain_names_by_type(\$type)

Expects a scalar reference to a string which is the domain 'type' (i.e. NATIVE, SLAVE, MASTER, etc.) Returns a reference to an array which contains all the domain names of that type.

list_slave_domain_names(\$master_ip)

Expects a scalar reference to an IP address which is the master IP. Returns a reference to an array which contains all the slave domain names with $master as their 'master'.

domain_exists(\$domain)

Expects a scalar reference to a domain name to be found in the "domains" table. Returns 1 if the domain name is found, and 0 if it is not found.

list_records(\$rr , \$domain)

Expects two scalar references; the first to a resource record and the second to a domain name. Returns a reference to a two-dimensional array which contains the resource record name, content, TTL, and priority if any.

list_all_records(\$domain)

Expects a scalar reference to a domain name. Returns a reference to a two-dimensional array which contains the resource record name, type, content, TTL, and priority if any of the supplied domain.

add_record(\$rr , \$domain)

Adds a single record to the backend. Expects two scalar references; one to an array that contains the information for the resource record (name, type, content, ttl, prio); name, type and content are required values. The other scalar reference is the zone you want to add the RR to. Returns 1 if the record was successfully added, and 0 if not.

delete_record(\$rr , \$domain)

Deletes a single record from the backend. Expects two scalar references; one to an array that contains the information for the resource record (name, type, content); these are all required values. The other scalar reference is the zone you want to delete the RR from. Returns 1 if the record was successfully deleted, and 0 if not.

update_record(\$rr1 , \$rr2 , \$domain)

Updates a single record in the backend.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type , $content) - all required.

2) A reference to an array that contains the updated values; ($name , $type , $content , $ttl , $prio) - only $name , $type , $content are required. Defaults for $ttl and $prio will be used if none are given.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

update_records(\$rr1 , \$rr2 , \$domain)

Can update multiple records in the backend.

Like update_record() but without the requirement that the 'content' be set in the resource record(s) you are trying to update; also not limited to updating just one record, but can update any number of records that match the resource record you are looking for.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type) - all required.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

update_or_add_records(\$rr1 , \$rr2 , \$domain)

Can update multiple records in the backend; will insert records if they don't already exist.

Expects three scalar references:

1) A reference to an array that contains the Resource Record to be updated; ($name , $type) - all required.

3) The domain to be updated.

Returns 1 on a successful update, and 0 when un-successful.

find_record_by_content(\$content , \$domain)

Finds a specific (single) record in the backend. Expects two scalar references; the first is the content we are looking for, and the second is the domain to be checked. Returns a reference to an array that contains the name and type from the found record, if any.

find_record_by_name(\$name, \$domain)

Finds a specific (single) record in the backend. Expects two scalar references; the first is the name we are looking for, and the second is the domain to be checked. Returns a reference to an array that contains the content and type from the found record, if any.

make_domain_native(\$domain)

Makes the specified domain a 'NATIVE' domain. Expects one scalar reference which is the domain name to be updated. Returns 1 upon succes and 0 otherwise.

make_domain_master(\$domain)

Makes the specified domain a 'MASTER' domain. Expects one scalar reference which is the domain name to be updated. Returns 1 upon succes and 0 otherwise.

get_domain_type(\$domain)

Expects one scalar reference which is the domain name to query for. Returns a string containing the PowerDNS 'type' of the domain given or 'undef' if the domain does not exist in the backend or an empty string if the domain has no master (i.e. a NATIVE domain).

get_master(\$domain)

Expects one scalar reference which is the domain name to query for. Returns a string containing the PowerDNS 'master' of the domain given or 'undef' if the domain does not exist in the PowerDNS backend or an empty string if the domain has no master (i.e. a NATIVE domain).

increment_serial(\$domain)

Increments the serial in the SOA by one. Assumes the serial is an eight digit date (YYYYMMDD) followed by a two digit increment. Expects one scalar reference which is the domain name to update. Returns 1 upon succes and 0 otherwise.

EXAMPLES

	my $params = {	db_user			=>	'root',
			db_pass			=>	'',
			db_name			=>	'pdns',
			db_port			=>	'3306',
			db_host			=>	'localhost',
			mysql_print_error	=>	1,
			mysql_warn		=>	1,
			mysql_auto_commit	=>	1,
			mysql_auto_reconnect	=>	1,
	};

	my $pdns = PowerDNS::Backend::MySQL->new($params);

	my $domain = 'example.com';
	my $master = '127.0.0.1';

	unless ( $pdns->add_domain(\$domain) )
        { print "Could not add domain : $domain \n"; }

        unless ( $pdns->add_master(\$domain) )
        { print "Could not add master domain : $domain \n"; }

	unless ( $pdns->add_slave(\$domain,\$master) )
        { print "Could not add slave domain : $domain \n"; }

	unless ( $pdns->delete_domain(\$domain) )
	{ print "Could not delete domain : $domain \n"; }

	my $domain_names = $pdns->list_domain_names;

	for my $domain (@$domain_names)
	{ print "$domain \n"; }

	my $type = 'NATIVE';
	my $domain_names = $pdns->list_domain_names_by_type(\$type);

	for my $domain (@$domain_names)
	{ print "$domain \n"; }

	my $master = '127.0.0.1';
	my $domain_names = $pdns->list_slave_domain_names(\$master);

	for my $domain (@$domain_names)
	{ print "$domain \n"; }
	
	if ( $pdns->domain_exists(\$domain) )
	{ print "The domain $domain does exist. \n"; }
	else
	{ print "The domain $domain does NOT exist. \n"; }
	
	my $rr = 'CNAME';
	my $records = $pdns->list_records(\$rr , \$domain);
	for my $record  (@$records)
	{ print "@$record\n"; }
	
	my @rr = ('www.example.com','CNAME','example.com');
	unless ( $pdns->add_record( \@rr , \$domain) )
	{ print "Could not add a RR for $domain \n"; }
	
	unless ( $pdns->delete_record(\@rr , \$domain) )
	{ print "Could not delete RR for $domain \n"; }
	
	my $domain = 'example.com';
	my @rr1 = ('localhost.example.com','A','127.0.0.1');
	my @rr2 = ('localhost.example.com','CNAME','example.com');
	
	unless ( $pdns->update_record(\@rr1 , \@rr2 , \$domain) )
	{ print "Update failed for $domain . \n"; }

	my (@rr1,@rr2,$domain);

	@rr1 = ('example.com','MX');
	@rr2 = ('example.com','MX','mx.example.com');
	$domain = 'example.com';

	unless ( $pdns->update_records( \@rr1 , \@rr2 , \$domain ) )
	{ print "Update failed for $domain . \n"; }

	@rr1 = ('example.com','MX');
	@rr2 = ('example.com','MX','mx.example.com');
	$domain = 'example.com';

	unless ( $pdns->update_or_add_records(\@rr1,\@rr2,\$domain) )
	{ print "Could not update/add record.\n"; }
	
	my $domain = 'example.com';
	my $content = 'localhost.example.com';
	my $records = $pdns->find_record_by_content(\$content , \$domain);
	my ($name , $type) = @$records;
	print "Name: $name\n";
	print "Type: $type\n";

	my $domain = 'example.com';
	my $name = 'localhost.example.com';
	my $records = $pdns->find_record_by_name(\$name, \$domain);
	my ($content, $type) = @$records;
	print "Content: $content\n";
	print "Type: $type\n";

	my $domain = 'example.com';
	$pdns->make_domain_native(\$domain);

        my $domain = 'example.com';
        $pdns->make_domain_master(\$domain);

	my $domain = 'example.com';
	my $type = $pdns->get_domain_type(\$domain);
	if ( $type )
	{ print "Type is '$type'\n"; }
	else
	{ print "Domain $domain does not exist.\n" }

	my $master = $pdns->get_master(\$domain);
	print "Master: $master\n";

	my $domain = 'augnix.net';
	unless ( $pdns->increment_serial(\$domain) )
	{ print "Could not increment serial."; }

NOTES

Because PowerDNS::Backend::MySQL uses DBI you can get the last DBI error from the global variable "$DBI::errstr"; this can be handy when you want more details as to why a particular method failed.

AUTHOR

Augie Schwer, <augie at cpan.org>

http://www.schwer.us

BUGS

Please report any bugs or feature requests to bug-net-powerdns-backend-mysql at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PowerDNS-Backend-MySQL. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc PowerDNS::Backend::MySQL

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/PowerDNS-Backend-MySQL
CPAN Ratings

http://cpanratings.perl.org/d/PowerDNS-Backend-MySQL
RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=PowerDNS-Backend-MySQL
Search CPAN

http://search.cpan.org/dist/PowerDNS-Backend-MySQL
Github

https://github.com/augieschwer/PowerDNS-Backend-MySQL

ACKNOWLEDGEMENTS

I would like to thank Sonic.net for allowing me to release this to the public.

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

0.12

To install PowerDNS::Backend::MySQL, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PowerDNS::Backend::MySQL

CPAN shell

perl -MCPAN -e shell
install PowerDNS::Backend::MySQL

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new(\%params)

add_domain(\$domain)

add_master(\$domain)

add_slave(\$slave_domain , \$master_ip)

delete_domain(\$domain)

list_domain_names

list_domain_names_by_type(\$type)

list_slave_domain_names(\$master_ip)

domain_exists(\$domain)

list_records(\$rr , \$domain)

list_all_records(\$domain)

add_record(\$rr , \$domain)

delete_record(\$rr , \$domain)

update_record(\$rr1 , \$rr2 , \$domain)

update_records(\$rr1 , \$rr2 , \$domain)

update_or_add_records(\$rr1 , \$rr2 , \$domain)

find_record_by_content(\$content , \$domain)

find_record_by_name(\$name, \$domain)

make_domain_native(\$domain)

make_domain_master(\$domain)

get_domain_type(\$domain)

get_master(\$domain)

increment_serial(\$domain)

EXAMPLES

NOTES

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

VERSION

Module Install Instructions