PowerDNS::Control::Server - Provides an interface to control the PowerDNS daemon.
Version 0.03
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);
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.
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 to listen on. Default is 988.
Address to listen on. Default is 0.0.0.0 .
List of methods the server is allowed to run; if not specified, then none of the control methods are allowed.
Set to 1 to keep the server in the foreground for debugging. The default is 0.
Use to set the Unix::Syslog::openlog($ident) variable. The default is 'pdns-control-server'.
Use to set the Unix::Syslog::openlog($option) variable. The default is LOG_PID | LOG_PERROR
Use to set the Unix::Syslog::openlog($facility) variable. The default is LOG_LOCAL3
Use to set the Unix::Syslog::syslog($priority) variable. The default is LOG_INFO
Where to store the PID file; default is '/var/run/pdns-control-server.pid'.
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.
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 .
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.
If the recursor's control socket is located someplace other then in socket_path, then you can set that location here.
If the authoritative server's control socket is located someplace other then in socket_path, then you can set that location here.
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.
Expects a scalar domain name to be retrieved. Calls pdns_control retrieve domain . Returns "+OK" if successful or "-ERR error message" otherwise.
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.
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.
Does not expect anything. Calls rec_control ping. Returns "+OK" if the recursor is running and "-ERR error message" otherwise.
Does not expect anything. Calls pdns_control ping. Returns "+OK" if the auth. server is running and "-ERR error message" otherwise.
Does not expect anything. Forks the server to the background unless "debug" was set.
Does not expect anything. Kills the running server.
Internal method. Close all file handles and fork to the background.
Internal method. Logs to syslog if debug is not turned on. If debug is on, then log to STDOUT.
Internal method. Verify that the method is 'allowed'; i.e. that it is in the allowed_methods list.
Augie Schwer, <augie at cpan.org>
<augie at cpan.org>
http://www.schwer.us
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.
bug-powerdns-control-server at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc PowerDNS::Control::Server
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/PowerDNS-Control-Server
CPAN Ratings
http://cpanratings.perl.org/d/PowerDNS-Control-Server
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=PowerDNS-Control-Server
Search CPAN
http://search.cpan.org/dist/PowerDNS-Control-Server
I would like to thank Sonic.net for allowing me to release this to the public.
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.
0.03 $Id: Server.pm 4430 2012-01-14 00:27:53Z augie $
To install PowerDNS::Control::Server, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PowerDNS::Control::Server
CPAN shell
perl -MCPAN -e shell install PowerDNS::Control::Server
For more information on module installation, please visit the detailed CPAN module installation guide.