/ 
PowerDNS-Control-Server-0.03
River stage zero No dependents
/ PowerDNS::Control::Server

NAME

PowerDNS::Control::Server - Provides an interface to control the PowerDNS daemon.

VERSION

Version 0.03

SYNOPSIS

use PowerDNS::Control::Server;

# Setting parameters and their default values.
my $params = {	port		=>	988,
		listen_address	=>	'0.0.0.0',
		allowed_methods =>	['auth_retrieve' , 'rec_wipe_cache'],
		debug		=>	0,
		syslog_ident	=>	'pdns-control-server',
		syslog_option	=>	LOG_PID | LOG_PERROR,
		syslog_facility	=>	LOG_LOCAL3,
		syslog_priority	=>	LOG_INFO,
		pid_file 	=>	'/var/run/pdns-control-server.pid',
		auth_cred	=>	'pa55word',
		allowed_ips	=>	['127.0.0.1/23' , '192.168.0.1/32'],
		socket_path	=>	'/var/run/',
};

my $pdns = PowerDNS::Control::Server->new($params);

DESCRIPTION

PowerDNS::Control::Server provides a way to create a server to control
both the PowerDNS Authoritative and Recursive servers.

PowerDNS::Control::Server was written in tandem with PowerDNS::Control::Client, 
but there is no reason why you could not write your own client.

The protocol PowerDNS::Control::Server implements is very simple and is based
off of SMTP; after successful connection the client can expect a banner, then
the client can execute commands agains the server; the server returns "+OK" if
all is well and "-ERR <error_message>" if there was a problem. A sample session
showing the protocol in use is below:

[augie@augnix Control]$ telnet localhost 10988
Trying 127.0.0.1...
Connected to augnix.noc.sonic.net (127.0.0.1).
Escape character is '^]'.
+OK Welcome 127.0.0.1
auth_retrieve schwer.us
+OK
quit
+OK Bye

The commands executed are based on the pdns_control and rec_control programs
on the server. Documentation for these programs can be found at:

http://docs.powerdns.com/

Note: All the commands may not be supported in this module, but the list of
supported commands is listed in the Methods section below. Methods that begin
with 'auth' control the Authoritative PowerDNS Server and methods that begin
with 'rec' control the Recursive PowerDNS Server.

METHODS

new(\%params)

my $params = {	port		=>	988,
		listen_address	=>	'0.0.0.0',
		allowed_methods =>	['auth_retrieve' , 'rec_wipe_cache'],
		debug		=>	0,
		syslog_ident	=>	'pdns-control-server',
		syslog_option	=>	LOG_PID | LOG_PERROR,
		syslog_facility	=>	LOG_LOCAL3,
		syslog_priority	=>	LOG_INFO,
		pid_file 	=>	'/var/run/pdns-control-server.pid',
		auth_cred	=>	'pa55word',
		allowed_ips	=>	['127.0.0.1/23' , '192.168.0.1/32'],
		socket_path	=>	'/var/run/',
};
my $pdns = PowerDNS::Control::Server->new($params);

Creates a PowerDNS::Control::Server object.
port

Port to listen on. Default is 988.

listen_address

Address to listen on. Default is 0.0.0.0 .

allowed_methods

List of methods the server is allowed to run; if not specified, then none of the control methods are allowed.

debug

Set to 1 to keep the server in the foreground for debugging. The default is 0.

syslog_ident

Use to set the Unix::Syslog::openlog($ident) variable. The default is 'pdns-control-server'.

syslog_option

Use to set the Unix::Syslog::openlog($option) variable. The default is LOG_PID | LOG_PERROR

syslog_facility

Use to set the Unix::Syslog::openlog($facility) variable. The default is LOG_LOCAL3

syslog_priority

Use to set the Unix::Syslog::syslog($priority) variable. The default is LOG_INFO

pid_file

Where to store the PID file; default is '/var/run/pdns-control-server.pid'.

auth_cred

Set if you want the server to require password authentication. If set, then the client should expect to see

"+OK ready for authentication"

to which it should reply

"AUTH pa55word"

Valid authentication will move the server into the main request loop; invalid authentication will disconnect the client.

allowed_ips

Set if you want the server to only accept connections from the IPs in this list. The list elements are IPs in CIDR notation, this means if you want to specify a single IP, then you must give it a '/32' this is an unfortunate bug in Net::CIDR .

socket_path

The path where the PowerDNS recursor and authoritative server control sockets are located. The default is '/var/run/'; this is also where temporary sockets will be placed for communicating with the PowerDNS control sockets, so make sure it is accessible by this program for reading and writing.

rec_control_socket

If the recursor's control socket is located someplace other then in socket_path, then you can set that location here.

pdns_control_socket

If the authoritative server's control socket is located someplace other then in socket_path, then you can set that location here.

control_socket_comm($message , $socket)

Internal method. Deal with the communication to and from the PowerDNS rec|auth. server. Expects a message to send and a control socket to send to. Returns the message received.

auth_retrieve($domain)

Expects a scalar domain name to be retrieved. Calls pdns_control retrieve domain . Returns "+OK" if successful or "-ERR error message" otherwise.

auth_wipe_cache($domain)

Expects a scalar domain name to be wiped out of cache. Calls pdns_control purge domain$ . Returns "+OK" if successful or "-ERR error message" otherwise.

rec_wipe_cache($domain)

Expects a scalar domain name to be wiped out of cache. Calls rec_control wipe-cache domain . Returns "+OK" if successful or "-ERR error message" otherwise.

rec_ping

Does not expect anything. Calls rec_control ping. Returns "+OK" if the recursor is running and "-ERR error message" otherwise.

auth_ping

Does not expect anything. Calls pdns_control ping. Returns "+OK" if the auth. server is running and "-ERR error message" otherwise.

start

Does not expect anything. Forks the server to the background unless "debug" was set.

stop

Does not expect anything. Kills the running server.

daemonize

Internal method. Close all file handles and fork to the background.

logmsg($message)

Internal method. Logs to syslog if debug is not turned on. If debug is on, then log to STDOUT.

method_is_allowed($method)

Internal method. Verify that the method is 'allowed'; i.e. that it is in the allowed_methods list.

AUTHOR

Augie Schwer, <augie at cpan.org>

http://www.schwer.us

BUGS

Please report any bugs or feature requests to bug-powerdns-control-server at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PowerDNS-Control-Server. 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::Control::Server

You can also look for information at:

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

Copyright 2007 Augie Schwer, all rights reserved.

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

VERSION

0.03
$Id: Server.pm 4430 2012-01-14 00:27:53Z augie $