Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::EPP::Simple(3)   User Contributed Perl Documentation  Net::EPP::Simple(3)

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:

       o   Unless otherwise set, "port"	defaults to 700

       o   Unless the "no_ssl" parameter is set, SSL is	always on

       o   You can use the "user" and "pass" parameters	to supply
	   authentication information.

       o   The "timeout" parameter controls how	long the client	waits for a
	   response from the server before returning an	error.

       o   if "debug" is set, "Net::EPP::Simple" will output verbose debugging
	   information on "STDERR", including all frames sent to and received
	   from	the server.

       o   "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).

       o   "login" can be used to disable automatic logins. If you set it to
	   0, you can manually log in using the	"$epp-"_login()> method.

       o   "objects" is	a reference to an array	of the EPP object schema URIs
	   that	the client requires.

       o   "stdobj" is a flag saying the client	only requires the standard EPP
	   "contact-1.0", "domain-1.0",	and "host-1.0" schemas.

       o   If neither "objects"	nor "stdobj" is	specified then the client will
	   echo	the server's object schema list.

       o   "extensions"	is a reference to an array of the EPP extension	schema
	   URIs	that the client	requires.

       o   "stdext" is a flag saying the client	only requires the standard EPP
	   "secDNS-1.1"	DNSSEC extension schema.

       o   If neither "extensions" nor "stdext"	is specified then the client
	   will	echo the server's extension schema list.

       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.

   Client and Server SSL options
       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.

       Server Certificate Verification

       "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:

	       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.

       SSL Cipher Selection

       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:

	       HIGH:!ADH:!MEDIUM:!LOW:!SSLv2:!EXP

       Client Certificates

       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.

   Configuration File
       "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.

       Default Options

       You can specify default options for all EPP servers using the
       "[default]" section:

	       [default]
	       default=epp.nic.tld
	       debug=1

       Server Specific Options

       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.

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:

       o   "undef" in the case of an error (check $Net::EPP::Simple::Error and
	   $Net::EPP::Simple::Code).

       o   0 if	the object is already provisioned.

       o   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 5731,
       Section 3.1.2 and RFC 5733, 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' => '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 "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' => '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.

   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' => '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.

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' => '2011-12-04T12:24:53.0Z',
		 'acID'	=> 'gaining-registrar',
		 'reDate' => '2011-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.

   Creating Hosts
	   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);

Updating Objects
       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);

       Each of these methods has the same profile. They	will return one	of the
       following:

       o   undef in the	case of	an error (check	$Net::EPP::Simple::Error and
	   $Net::EPP::Simple::Code).

       o   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).

   Updating Domains
       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.

   Updating Contacts
       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.

   Updating Hosts
       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.

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:

       o   undef in the	case of	an error (check	$Net::EPP::Simple::Error and
	   $Net::EPP::Simple::Code).

       o   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).

Domain Renewal
       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.

Miscellaneous Methods
	       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.

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 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.

Author
       CentralNic Ltd (<http://www.centralnic.com/>).

Copyright
       This module is (c) 2016 CentralNic Ltd. This module is free software;
       you can redistribute it and/or modify it	under the same terms as	Perl
       itself.

SEE ALSO
       o   Net::EPP::Client

       o   Net::EPP::Frame

       o   Net::EPP::Proxy

       o   RFCs	5730 and RFC 4934, available from <http://www.ietf.org/>.

       o   The CentralNic EPP site at
	   <http://www.centralnic.com/registrars/epp>.

perl v5.32.0			  2016-04-06		   Net::EPP::Simple(3)

Name | Synopsis | Description | Constructor | Availability Checks | Retrieving Object Information | Object Transfers | Creating Objects | Updating Objects | Deleting Objects | Domain Renewal | Miscellaneous Methods | Overridden Methods From "Net::EPP::Client" | Package Variables | Author | Copyright | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::EPP::Simple&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help