NAME
DNS::WorldWideDns - An interface to the worldwidedns.net service.
SYNOPSIS
use DNS::WorldWideDns;
$dns = DNS::WorldWideDns->new($user, $pass);
$hashRef = $dns->getDomains;
$hashRef = $dns->getDomain($domain);
$dns->addDomain($domain);
$dns->updateDomain($domain, $properties);
$dns->deleteDomain($domain);DESCRIPTION
This module allows you to dynamically create, remove, update, delete, and report on domains hosted at http://www.worldwidedns.net. It makes working with their sometimes obtuse, but very useful, DNS API protocol (http://www.worldwidedns.net/dns_api_protocol.asp) a breeze.
USAGE
The following methods are available from this class:
addDomain ( domain, [ isPrimary, isDynamic ] )
Adds a domain to your account. Throws MissingParam, InvalidParam, InvalidAccount and RequestError.
NOTE: You should use updateDomain() directly after adding a domain to give it some properties and records.
Returns a 1 on success.
domain
A domain to add.
isPrimary
A boolean indicating if this is a primary domain, or a secondary. Defaults to 1.
NOTE: This module currently only supports primary domains.
isDynamic
A boolean indicating whether this domain is to allow Dynamic DNS ip updating. Defaults to 0.
deleteDomain ( domain )
Removes a domain from your account. Throws MissingParam, InvalidParam, InvalidAccount and RequestError.
Returns a 1 on success.
domain
A domain to delete.
getDomain ( domain, [ nameServer ] )
Retrieves the zone information about the domain. Throws MissingParam, InvalidParam, InvalidAccount and RequestError.
Returns a hash reference structure that looks like this:
{
hostmaster => "you.example.com",
refresh => "86400",
retry => "1200",
expire => "186400",
ttl => "3600",
secureTransfer => "*",
records => []
}The hostmaster field is the email address of the person in charge of this domain. Note that it should use dot notation, so don't use an at (@) sign.
The refresh field tells a cache name server how often (in seconds) to request fresh data from the authoratative name server. Minimum 3600.
The retry field tells a cache name server how long to wait (in seconds) before attempting to retry a failed refresh. Minimum 3600.
The expire field tells a cache name server how old (in seconds) to let data become before discarding it. Minimum 3600.
The ttl (Time To Live) is the default value for records that don't have a TTL specified.
The secureTransfer parameter is an access control list for zone transfers. Asterisk (*) implies that anyone can do zone transfers. Otherwise it could be a list of IP addresses separated by spaces. Setting it to an empty string means no servers may do zone transfers on the domain.
The records field is an array reference of records attached to this domain. It looks something like this:
[
{
name => "smtp",
ttl => 3600,
type => "A",
data => "1.1.1.1"
},
{
name => "@",
ttl => 3600,
type => "MX",
data => "10 smtp.example.com"
},
]The name field is the subdomain or host name that will be prepended on to the domain. For example the "www" in "www.example.com". The at (@) symbol means the domain itself, which is why you can type google.com not just www.google.com. The asterisk (*) is a wildcard, which means if no matching records are found, use this record to service the request.
The ttl field tells a caching name server how long (in seconds) it may use this record before it has to fetch new information about it. Minimum 3600.
The type field is the domain record type defined in RFC1035. Common record types are A, CNAME, an MX.
The data field holds the data of the record. It's usually an ip address or a fully qualified host name.
domain
A domain to request information about.
nameServer
Defaults to 1. Choose from 1, 2, or 3. The number of the primary, secondary or tertiary name server.
getDomains ( )
Returns a hash reference where the key is the domain and the value is either a 'Primary' or an 'Secondary'. Throws InvalidAccount and RequestError.
NOTE: This module does not currently handle creating, reading, or updating secondary domains, but it may in the future, so this indicator is left in.
makeRequest ( url, [ request ] )
Makes a GET request. Returns the HTTP::Response from the request. Throws MissingParam, InvalidParam, InvalidAccount and RequestError.
NOTE: Normally you never need to use this method, it's used by the other methods in this class. However, it may be useful in subclassing this module.
url
The URL to request.
request
Normally an HTTP::Request object is created for you on the fly. But if you want to make your own and pass it in you are welcome to do so.
new ( username, password )
Constructor. Throws MissingParam.
username
Your worldwidedns.net username.
password
The password to go with username.
password ()
Returns the password set in the constructor.
updateDomain ( domain, params )
Updates a domain in your account. Throws MissingParam, InvalidParam, InvalidAccount and RequestError.
Returns a 1 on success.
domain
A domain to update.
params
A hash reference identical to the one returned by getDomain().
username ()
Returns the username set in the constructor.
EXCEPTIONS
This module uses Exception::Class for exception handling. Each method is capable of throwing one or more of the following exceptions:
Exception
A general undefined error.
MissingParam
An expected parameter to a method was not passed.
InvalidParam
A parameter passed in doesn't match what was expected. This add a "got" field to the exception which contains what was received.
InvalidAccount
Authentication to worldwidedns.net failed.
RequestError
Some part of the request/response to worldwidedns.net did not go as expected. This adds url, response, and code fields to the exception.
The url field is the URL that was requested. This can be very helpful when debugging a problem.
The response field is the HTTP::Response object that was returned from the request.
The code field is the error code number or numbers that were returned by the worldwidedns.net API. More informationa about them can be found in the DNS API protocol documentation pages (http://www.worldwidedns.net/dns_api_protocol.asp).
BUGS
None known.
CAVEATS
This module is not feature complete with the API worldwidedns.net provides. It does your basic CRUD and that's it. They have other methods this doesn't use, and they have a whole reseller API which this doesn't support. If you need those features, patches are welcome.
AUTHOR
JT Smith
CPAN ID: RIZEN
Plain Black Corporation
jt_at_plainblack_com
http://www.plainblack.com/COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.