NAME

Net::UKDomain::Nominet::Automaton - Module to build, encrypt and send requests to the Nominet automation system via email.

SYNOPSIS

use Net::UKDomain::Nominet::Automaton;
my $d = Net::UKDomain::Nominet::Automaton->new( keyid 	=> 'MYKEYID',
					passphrase 	=> 'HARDTOREMEMBER',
					tag 				=> 'ISPTAG',
					smtpserver	=> 'smtp.my.net',
					emailfrom		=> 'MyISP <domains@my.isp>',
					secring			=> '/path/to/secret/keyring',
					pubring			=> '/path/to/public/keyring',
					compat			=> 'PGP2',
					testemail		=> 'myown@email.here',
					);

my $domain = 'domain.sld.uk';

if ( ! $d->valid_domain($domain) ) {
	print "Invalid domain - " . $d->errstr;
	}

if ( ! $d->domain_available($domain) ) {
	print "Domain not available.";
	}

if ( ! $d->register($domain, $details) ) {
	print "Unable to issue register domain operation - ". $d->errstr;
	}

if ( ! $d->modify($domain, $details) ) {
	print "Unable to issue modify '$domain' operation - " . $d->errstr;
	}

if ( ! $d->query($domain) ) {
	print "Unable to issue query '$domain' operation - " . $d->errstr;
	}

if ( ! $d->renew($domain) ) {
	print "Unable to issue renew '$domain' operation - " . $d->errstr;
	}

if ( ! $d->release($domain, $othertag) ) {
	print "Unable to issue release '$domain' operation to '$othertag' - " . $d->errstr;
	}

if ( ! $d->delete($domain) ) {
	print "Unable to issue delete '$domain' operation - " . $d->errstr;
	}

DESCRIPTION

This module is designed to assist you automate operations used to interface with Nominet, the .UK domain registry.

The Nominet automaton system is an asyncronous process. Requests must be sent via email and replies are also returned via email.

The main operations will always return true if the message was sent successfully, otherwise the errstr will be populated.

It is recommended you have 'Automaton field options' set to 'Use new field set' via https://secure.nominet.org.uk/tags/manage-options.html

Further information on the Nominet automation system can be found here: http://www.nominet.org.uk/registrars/systems/auto/

USAGE

Net::UKDomain::Nominet::Automaton has the following object based interface. On failure, all methods will return undef and set the errstr object with a suitable message.

Net::UKDomain::Nominet::Automaton->new( %args )

Constructs a new Net::UKDomain::Nominet::Automaton instance and returns that object. Returns undef on failure.

%args can include:

KEYID

The PGP KeyID to the key used to sign messages to the Nominet automaton system.

(eg: ABC123E4)

PASSPHRASE

The PGP passphrase you originally used to generate your key.

TAG

Your Nominet Registrar TAG.

Note: You should be listed here: http://www.nominet.org.uk/registrars/becomeregistrar/taglist/

SMTPSERVER

The smtp server through which messages to the Nominet automaton system will be sent.

EMAILFROM

The email address from which messages to the Nominet automaton system should be sent.

Note: This email address is usually the same one that you use to log in here: https://secure.nominet.org.uk/

SECRING

The full path to the secret keyring file.

eg: /home/user/.gnupg/secring.gpg

PUBRING

The full path to the public keyring file.

eg: /home/user/.gnupg/pubring.gpg

COMPAT

The compatibility mode for Crypt::OpenPGP (PGP2, PGP5 or GnuPG)

PGP2 is the default, you do not usually need to adjust this.

TESTEMAIL

This is used for debugging only. Don't enable this on a live system.

Defining this will mean that all requests will be sent to the defined testemail address instead of to the Nominet automation system.

All arguements are required except COMPAT and TESTEMAIL. If COMPAT is not provided it will default to PGP2.

Net::UKDomain::Nominet::Automaton->valid_domain($domain);

Validates the domain for the .uk name space.

Net::UKDomain::Nominet::Automaton->domain_available($domain);

Checks whether the domain is available. Returns true if it is.

Net::UKDomain::Nominet::Automaton->register($domain, $details);

Sends a message to the Nominet Automaton to register the domain.

The %details hash should contain the details that the Nominet automation system requires for domain registration to be completed.

All details will be validated.

Note: A true result does not mean the domain was successfully registered, it simply means the request was successfully sent.

See: http://www.nominet.org.uk/registrars/systems/auto/request/

Net::UKDomain::Nominet::Automaton->modify($domain, $details);

Sends a message to the Automaton to modify the domain.

The %details hash should include only the fields you want to update. The fields need to be as per the Nominet Automaton standard fields.

See: http://www.nominet.org.uk/registrars/systems/auto/modify/

Net::UKDomain::Nominet::Automaton->release($domain, $tag);

Releases the domain to the given registrar TAG.

This is the means Nominet use to transfer the management of a domain from one member or regisrar to another.

See: http://www.nominet.org.uk/registrars/systems/auto/release/

Net::UKDomain::Nominet::Automaton->renew($domain);

Renews the given domain.

See: http://www.nominet.org.uk/registrars/systems/auto/renew/

Net::UKDomain::Nominet::Automaton->delete($domain);

Deletes the given domain.

See: http://www.nominet.org.uk/registrars/systems/auto/delete/

Net::UKDomain::Nominet::Automaton->query($domain|$details);

Sends a message to the automaton requesting a listing of all of the details associated with the domain or request.

The details will be returned by email.

This method now supports either $domain for regular modification or $details to modify accounts, contacts and nameservers.

See: http://www.nominet.org.uk/registrars/systems/auto/query/

Net::UKDomain::Nominet::Automaton->list($details);

Sends a message to the automaton requesting a list of domains.