Net::EPP::Simple - a simple EPP client interface for the most common jobs.
#!/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}); }
This module provides a high level interface to EPP. 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.
The constructor for Net::EPP::Simple has the same general form as the one for Net::EPP::Client, but with the following exceptions:
Net::EPP::Simple
Unless otherwise set, port defaults to 700
port
Unless the no_ssl parameter is set, SSL is always on
no_ssl
You can use the user and pass parameters to supply authentication information.
user
pass
You can use the newPW parameter to specify a new password.
newPW
The login_security parameter can be used to force the use of the Login Security Extension (see RFC8807). Net::EPP::Simple will automatically use this extension if the server supports it, but clients may wish to force this behaviour to prevent downgrade attacks.
login_security
The appname parameter can be used to specify the value of the <app<gt> element in the Login Security extension (if used). Unless specified, the name and current version of Net::EPP::Simple will be used.
appname
<app<gt
The timeout parameter controls how long the client waits for a response from the server before returning an error.
timeout
if debug is set, Net::EPP::Simple will output verbose debugging information on STDERR, including all frames sent to and received from the server.
debug
STDERR
reconnect can be used to disable automatic reconnection (it is enabled by default). Before sending a frame to the server, Net::EPP::Simple will send a <hello> to check that the connection is up, if not, it will try to reconnect, aborting after the nth time, where n is the value of reconnect (the default is 3).
reconnect
<hello>
login can be used to disable automatic logins. If you set it to 0, you can manually log in using the $epp->_login() method.
login
0
$epp->_login()
objects is a reference to an array of the EPP object schema URIs that the client requires.
objects
stdobj is a flag saying the client only requires the standard EPP contact-1.0, domain-1.0, and host-1.0 schemas.
stdobj
contact-1.0
domain-1.0
host-1.0
If neither objects nor stdobj is specified then the client will echo the server's object schema list.
extensions is a reference to an array of the EPP extension schema URIs that the client requires.
extensions
stdext is a flag saying the client only requires the standard EPP secDNS-1.1 DNSSEC extension schema.
stdext
secDNS-1.1
If neither extensions nor stdext is specified then the client will echo the server's extension schema list.
The lang parameter can be used to specify the language. The default is "en".
lang
en
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.
$epp->{greeting}
<login>
If the login fails, the constructor will return undef and set $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.
undef
$Net::EPP::Simple::Error
$Net::EPP::Simple::Code
RFC 5730 requires that all EPP instances must be protected using "mutual, strong client-server authentication". In practice, this means that both client and server must present an SSL certificate, and that they must both verify the certificate of their peer.
Net::EPP::Simple will verify the certificate presented by a server if the verify, and either ca_file or ca_path are passed to the constructor:
verify
ca_file
ca_path
my $epp = Net::EPP::Simple->new( host => 'epp.nic.tld', user => 'my-id', pass => 'my-password', verify => 1, ca_file => '/etc/pki/tls/certs/ca-bundle.crt', ca_path => '/etc/pki/tls/certs', );
Net::EPP::Simple will fail to connect to the server if the certificate is not valid.
You can disable SSL certificate verification by omitting the verify argument or setting it to undef. This is strongly discouraged, particularly in production environments.
You can restrict the ciphers that you will use to connect to the server by passing a ciphers parameter to the constructor. This is a colon- separated list of cipher names and aliases. See http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS for further details. As an example, the following cipher list is suggested for clients who wish to ensure high-security connections to servers:
ciphers
HIGH:!ADH:!MEDIUM:!LOW:!SSLv2:!EXP
If you are connecting to an EPP server which requires a client certificate, you can configure Net::EPP::Simple to use one as follows:
my $epp = Net::EPP::Simple->new( host => 'epp.nic.tld', user => 'my-id', pass => 'my-password', key => '/path/to/my.key', cert => '/path/to/my.crt', passphrase => 'foobar123', );
key is the filename of the private key, cert is the filename of the certificate. If the private key is encrypted, the passphrase parameter will be used to decrypt it.
key
cert
passphrase
Net::EPP::Simple supports the use of a simple configuration file. To use this feature, you need to install the Config::Simple module.
When starting up, Net::EPP::Simple will look for $HOME/.net-epp-simple-rc. This file is an ini-style configuration file.
$HOME/.net-epp-simple-rc
You can specify default options for all EPP servers using the [default] section:
[default]
[default] default=epp.nic.tld debug=1
You can specify options for for specific EPP servers by giving each EPP server its own section:
[epp.nic.tld] user=abc123 pass=foo2bar port=777 ssl=0
This means that when you write a script that uses Net::EPP::Simple, you can do the following:
# config file has a default server: my $epp = Net::EPP::Simple->new; # config file has connection options for this EPP server: my $epp = Net::EPP:Simple->new('host' => 'epp.nic.tld');
Any parameters provided to the constructor will override those in the config file.
You can do a simple <check> request for an object like so:
<check>
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.
1
my $info = $epp->domain_info($domain, $authInfo, $follow);
This method constructs an <info> frame and sends it to the server, then parses the response into a simple hash ref. If there is an error, this method will return undef, and you can then check $Net::EPP::Simple::Error and $Net::EPP::Simple::Code.
<info>
If $authInfo is defined, it will be sent to the server as per RFC 5731, Section 3.1.2.
$authInfo
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).
$follow
host_info()
contact_info()
my $info = $epp->host_info($host);
my $info = $epp->contact_info($contact, $authInfo, $roid);
If $authInfo is defined, it will be sent to the server as per RFC RFC 5733, Section 3.1.2.
If the $roid parameter to host_info() is set, then the roid attribute will be set on the <authInfo> element.
$roid
roid
<authInfo>
The hash ref returned by domain_info() will usually look something like this:
domain_info()
$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' => '2011-01-18T11:08:03.0Z', 'ns' => [ 'ns0.example.com', 'ns1.example.com', ], 'crDate' => '2011-02-16T12:06:31.0Z', 'exDate' => '2011-02-16T12:06:31.0Z', 'crID' => 'registrar-id', 'upDate' => '2011-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 Host Attribute model instead of the Host Object model, then the ns member will look like this:
contacts
ns
$info->{ns} = [ { name => 'ns0.example.com', addrs => [ version => 'v4', addr => '10.0.0.1', ], }, { name => 'ns1.example.com', addrs => [ version => 'v4', addr => '10.0.0.2', ], }, ];
Note that there may be multiple members in the addrs section and that the version attribute is optional.
addrs
version
The hash ref returned by host_info() will usually look something like this:
$info = { 'crDate' => '2011-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.
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' => '20116-6503' 'cc' => 'US', } } }, 'clID' => 'registrar-id', 'roid' => 'CNIC-HA321983', 'status' => [ 'linked', 'serverDeleteProhibited' ], 'voice' => '+1.7035555555x1234', 'fax' => '+1.7035555556', 'email' => 'jdoe@example.com', 'crDate' => '2011-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.
postalInfo
int
loc
The EPP <transfer> command suppots five different operations: query, request, cancel, approve, and reject. Net::EPP::Simple makes these available using the following methods:
<transfer>
# 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:
domain_transfer_request()
domain_transfer_query()
contact_transfer_request()
contact_transfer_query()
my $trnData = { 'name' => 'example.tld', 'reID' => 'losing-registrar', 'acDate' => '2011-12-04T12:24:53.0Z', 'acID' => 'gaining-registrar', 'reDate' => '2011-11-29T12:24:53.0Z', 'trStatus' => 'pending' };
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.
When creating a new domain object, you may also specify a period key, like so:
period
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.
my $host = { name => 'ns1.example.tld', addrs => [ { ip => '123.45.67.89', version => 'v4' }, { ip => '98.76.54.32', version => 'v4' }, ], }; $epp->create_host($host);
The following methods can be used to update an object at the server:
$epp->update_domain($domain); $epp->update_host($host); $epp->update_contact($contact);
1 if the update 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).
Use update_domain() method to update domains' data.
The update info parameter may look like: $update_info = { name => $domain, chg => { registrant => $new_registrant_id, authInfo => $new_domain_password, }, add => { # DNS info with "hostObj" or "hostAttr" model, see create_domain() ns => [ ns1.example.com ns2.example.com ], contacts => { tech => 'contact-id', billing => 'contact-id', admin => 'contact-id', },
# Status info, simple form: status => [ qw/ clientUpdateProhibited clientHold / ], # Status info may be in more detailed form: # status => { # clientUpdateProbhibited => 'Avoid accidental change', # clientHold => 'This domain is not delegated', # }, }, rem => { ns => [ ... ], contacts => { tech => 'old_tech_id', billing => 'old_billing_id', admin => 'old_admin_id', }, status => [ qw/ clientTransferProhibited ... / ], }, }
All fields except 'name' in $update_info hash are optional.
Use update_contact() method to update contact's data.
The $update_info for contacts may look like this:
$update_info = { id => $contact_id, add => { status => [ qw/ clientDeleteProhibited / ], # OR # status => { # clientDeleteProhibited => 'Avoid accidental removal', # }, }, rem => { status => [ qw/ clientUpdateProhibited / ], }, chg => { postalInfo => { int => { name => 'John Doe', org => 'Example Inc.', addr => { street => [ '123 Example Dr.' 'Suite 100' ], city => 'Dulles', sp => 'VA', pc => '20116-6503' cc => 'US', }, }, }, voice => '+1.7035555555x1234', fax => '+1.7035555556', email => 'jdoe@example.com', authInfo => 'new-contact-password', }, }
All fields except 'id' in $update_info hash are optional.
Use update_host() method to update EPP hosts.
The $update_info for hosts may look like this:
$update_info = { name => 'ns1.example.com', add => { status => [ qw/ clientDeleteProhibited / ], # OR # status => { # clientDeleteProhibited => 'Avoid accidental removal', # },
addrs => [ { ip => '123.45.67.89', version => 'v4' }, { ip => '98.76.54.32', version => 'v4' }, ], }, rem => { status => [ qw/ clientUpdateProhibited / ], addrs => [ { ip => '1.2.3.4', version => 'v4' }, { ip => '5.6.7.8', version => 'v4' }, ], }, chg => { name => 'ns2.example.com', }, }
All fields except first 'name' in $update_info hash are optional.
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);
1 if the deletion request was accepted.
You can extend the validity period of the domain object by issuing a renew_domain() command.
my $result = $epp->renew_domain({ name => 'example.com', cur_exp_date => '2011-02-05', # current expiration date period => 2, # prolongation period in years });
Return value is 1 on success and undef on error. In the case of error $Net::EPP::Simple::Error contains the appropriate error message.
my $greeting = $epp->greeting;
Returns the a Net::EPP::Frame::Greeting object representing the greeting returned by the server.
$epp->ping;
Checks that the connection is up by sending a <hello> to the server. Returns false if no response is received.
Net::EPP::Simple overrides some methods inherited from Net::EPP::Client. These are described below:
request()
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.
<clTRID>
get_frame()
Net::EPP::Simple overrides this method so it can catch timeouts and network errors. If such an error occurs it will return undef.
$connected = $epp->connected;
Returns a boolean if Net::EPP::Simple has a connection to the server. Note that this connection might have dropped, use ping() to test it.
ping()
$authenticated = $epp->authenticated;
Returns a boolean if Net::EPP::Simple has successfully authenticated with the server.
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.
This variable contains the contains the text content of the <msg> element in the response frame for the last transaction.
<msg>
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 2011 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.
COMMAND_FAILED
To install Net::EPP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::EPP
CPAN shell
perl -MCPAN -e shell install Net::EPP
For more information on module installation, please visit the detailed CPAN module installation guide.