NAME
Net::EPP::Simple - a simple EPP client interface for the most common jobs
SYNOPSIS
#!/usr/bin/perl
use Net::EPP::Simple;
use strict;
my $epp = Net::EPP::Simple->new(
host => 'epp.nic.tld',
user => 'my-id',
pass => 'my-password',
);
my $domain = 'example.tld';
if ($epp->check_domain($domain) == 1) {
print "Domain is available\n" ;
} else {
my $info = $epp->domain_info($domain);
printf("Domain was registered on %s by %s\n", $info->{crDate}, $info->{crID});
}
DESCRIPTION
EPP is the Extensible Provisioning Protocol. EPP (defined in RFC 4930) is an application layer client-server protocol for the provisioning and management of objects stored in a shared central repository. Specified in XML, the protocol defines generic object management operations and an extensible framework that maps protocol operations to objects. As of writing, its only well-developed application is the provisioning of Internet domain names, hosts, and related contact details.
This module provides a high level interface to the EPP protocol. It hides all the boilerplate of connecting, logging in, building request frames and parsing response frames behind a simple, Perlish interface.
It is based on the Net::EPP::Client
module and uses Net::EPP::Frame
to build request frames.
CONSTRUCTOR
The constructor for Net::EPP::Simple
has the same general form as the one for Net::EPP::Client
, but with the following exceptions:
Unless otherwise set,
port
defaults to 700Unless the
no_ssl
parameter is set, SSL is always onYou can use the
user
andpass
parameters to supply authentication information.The
timeout
parameter controls how long the client waits for a response from the server before returning an error.
The constructor will establish a connection to the server and retrieve the greeting (which is available via $epp->{greeting}
) and then send a <login>
request.
If the login fails, the constructor will return undef
and set $Net::EPP::Simple::Error
and $Net::EPP::Simple::Code
.
Availability Checks
You can do a simple <check>
request for an object like so:
my $result = $epp->check_domain($domain);
my $result = $epp->check_host($host);
my $result = $epp->check_contact($contact);
Each of these methods has the same profile. They will return one of the following:
undef
in the case of an error (check$Net::EPP::Simple::Error
and$Net::EPP::Simple::Code
).0
if the object is already provisioned.1
if the object is available.
Retrieving Object Information
You can retrieve information about an object by using one of the following:
my $info = $epp->domain_info($domain, $authInfo, $follow);
my $info = $epp->host_info($host);
my $info = $epp->contact_info($contact, $authInfo);
Net::EPP::Simple
will construct an <info>
frame and send it to the server, then parse the response into a simple hash ref. The layout of the hash ref depends on the object in question. If there is an error, these methods will return undef
, and you can then check $Net::EPP::Simple::Error
and $Net::EPP::Simple::Code
.
If $authInfo
is defined, it will be sent to the server as per RFC 4931, Section 3.1.2 and RRC 4933, Section 3.1.2. If the supplied authInfo code is validated by the registry, additional information will appear in the response. If it is invalid, you should get an error.
If the $follow
parameter is true, then Net::EPP::Simple
will also retrieve the relevant host and contact details for a domain: instead of returning an object name or ID for the domain's registrant, contact associations, DNS servers or subordinate hosts, the values will be replaced with the return value from the appropriate host_info()
or contact_info()
command (unless there was an error, in which case the original object ID will be used instead).
Domain Information
The hash ref returned by domain_info()
will usually look something like this:
$info = {
'contacts' => {
'admin' => 'contact-id'
'tech' => 'contact-id'
'billing' => 'contact-id'
},
'registrant' => 'contact-id',
'clID' => 'registrar-id',
'roid' => 'tld-12345',
'status' => [
'ok'
],
'authInfo' => 'abc-12345',
'name' => 'example.tld',
'trDate' => '2007-01-18T11:08:03.0Z',
'ns' => [
'ns0.example.com',
'ns1.example.com',
],
'crDate' => '2001-02-16T12:06:31.0Z',
'exDate' => '2009-02-16T12:06:31.0Z',
'crID' => 'registrar-id',
'upDate' => '2007-08-29T04:02:12.0Z',
hosts => [
'ns0.example.tld',
'ns1.example.tld',
],
};
Members of the contacts
hash ref may be strings or, if there are multiple associations of the same type, an anonymous array of strings. If the server uses the "hostAttr" model instead of "hostObj", then the ns
member will look like this:
$info->{ns} = [
{
name => 'ns0.example.com',
addrs => [
type => 'v4',
addr => '10.0.0.1',
],
},
{
name => 'ns1.example.com',
addrs => [
type => 'v4',
addr => '10.0.0.2',
],
},
];
Note that there may be multiple members in the addrs
section and that the type
attribute is optional.
Host Information
The hash ref returned by host_info()
will usually look something like this:
$info = {
'crDate' => '2007-09-17T15:38:56.0Z',
'clID' => 'registrar-id',
'crID' => 'registrar-id',
'roid' => 'tld-12345',
'status' => [
'linked',
'serverDeleteProhibited',
],
'name' => 'ns0.example.tld',
'addrs' => [
{
'version' => 'v4',
'addr' => '10.0.0.1'
}
]
};
Note that hosts may have multiple addresses, and that version
is optional.
Contact Information
The hash ref returned by contact_info()
will usually look something like this:
$VAR1 = {
'id' => 'contact-id',
'postalInfo' => {
'int' => {
'name' => 'John Doe',
'org' => 'Example Inc.',
'addr' => {
'street' => [
'123 Example Dr.'
'Suite 100'
],
'city' => 'Dulles',
'sp' => 'VA',
'pc' => '20166-6503'
'cc' => 'US',
}
}
},
'clID' => 'registrar-id',
'roid' => 'CNIC-HA321983',
'status' => [
'linked',
'serverDeleteProhibited'
],
'voice' => '+1.7035555555x1234',
'fax' => '+1.7035555556',
'email' => 'jdoe@example.com',
'crDate' => '2007-09-23T03:51:29.0Z',
'upDate' => '1999-11-30T00:00:00.0Z'
};
There may be up to two members of the postalInfo
hash, corresponding to the int
and loc
internationalised and localised types.
Object Transfers
The EPP <transfer>
command suppots five different operations: query, request, cancel, approve, and reject. Net::EPP::Simple
makes these available using the following methods:
# For domain objects:
$epp->domain_transfer_query($domain);
$epp->domain_transfer_cancel($domain);
$epp->domain_transfer_request($domain, $authInfo, $period);
$epp->domain_transfer_approve($domain);
$epp->domain_transfer_reject($domain);
# For contact objects:
$epp->contact_transfer_query($contact);
$epp->contact_transfer_cancel($contact);
$epp->contact_transfer_request($contact, $authInfo);
$epp->contact_transfer_approve($contact);
$epp->contact_transfer_reject($contact);
Most of these methods will just set the value of $Net::EPP::Simple::Code
and return either true or false. However, the domain_transfer_request()
, domain_transfer_query()
, contact_transfer_request()
and contact_transfer_query()
methods will return a hash ref that looks like this:
my $trnData = {
'name' => 'example.tld',
'reID' => 'losing-registrar',
'acDate' => '2007-12-04T12:24:53.0Z',
'acID' => 'gaining-registrar',
'reDate' => '2007-11-29T12:24:53.0Z',
'trStatus' => 'pending'
};
Creating Objects
The following methods can be used to create a new object at the server:
$epp->create_domain($domain);
$epp->create_host($host);
$epp->create_contact($contact);
The argument for these methods is a hash ref of the same format as that returned by the info methods above. As a result, cloning an existing object is as simple as the following:
my $info = $epp->contact_info($contact);
# set a new contact ID to avoid clashing with the existing object
$info->{id} = $new_contact;
# randomize authInfo:
$info->{authInfo} = $random_string;
$epp->create_contact($info);
Net::EPP::Simple
will ignore object properties that it does not recognise, and those properties (such as server-managed status codes) that clients are not permitted to set.
Creating New Domains
When creating a new domain object, you may also specify a period
key, like so:
my $domain = {
'name' => 'example.tld',
'period' => 2,
'registrant' => 'contact-id',
'contacts' => {
'tech' => 'contact-id',
'admin' => 'contact-id',
'billing' => 'contact-id',
},
'status' => {
'clientTransferProhibited',
}
'ns' => {
'ns0.example.com',
'ns1.example.com',
},
};
$epp->create_domain($domain);
The period
key is assumed to be in years rather than months. Net::EPP::Simple
assumes the registry uses the host object model rather than the host attribute model.
Deleting Objects
The following methods can be used to delete an object at the server:
$epp->delete_domain($domain);
$epp->delete_host($host);
$epp->delete_contact($contact);
Each of these methods has the same profile. They will return one of the following:
undef in the case of an error (check
$Net::EPP::Simple::Error
and$Net::EPP::Simple::Code
).1 if the deletion request was accepted.
You may wish to check the value of $Net::EPP::Simple::Code to determine whether the response code was 1000 (OK) or 1001 (action pending).
Miscellaneous Methods
my $greeting = $epp->greeting;
Returns the a Net::EPP::Frame::Greeting
object representing the greeting returned by the server.
Overridden Methods From Net::EPP::Client
Net::EPP::Simple
overrides some methods inherited from Net::EPP::Client
. These are described below:
The request()
Method
Net::EPP::Simple
overrides this method so it can automatically populate the <clTRID>
element with a unique string. It then passes the frame back up to Net::EPP::Client
.
The get_frame()
Method
Net::EPP::Simple
overrides this method so it can catch timeouts and network errors. If such an error occurs it will return undef
.
Package Variables
$Net::EPP::Simple::Error
This variable contains an english text message explaining the last error to occur. This is may be due to invalid parameters being passed to a method, a network error, or an error response being returned by the server.
$Net::EPP::Simple::Message
This variable contains the contains the text content of the <msg>
element in the response frame for the last transaction.
$Net::EPP::Simple::Code
This variable contains the integer result code returned by the server for the last transaction. A successful transaction will always return an error code of 1999 or lower, for an unsuccessful transaction it will be 2000 or more. If there is an internal client error (due to invalid parameters being passed to a method, or a network error) then this will be set to 2400 (COMMAND_FAILED
). See Net::EPP::ResponseCodes for more information about thes codes.
AUTHOR
CentralNic Ltd (http://www.centralnic.com/).
COPYRIGHT
This module is (c) 2007 CentralNic Ltd. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
RFCs 4930 and RFC 4934, available from http://www.ietf.org/.
The CentralNic EPP site at http://www.centralnic.com/resellers/epp.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 318:
You forgot a '=back' before '=head1'