Freeside:3:Documentation:Administration:opensrs.pm

Using Freeside's OpenSRS Domain Registration Export

Introduction

As of June, 2009, Freeside CVS includes an export to perform common operations on domains using the Tucows OpenSRS domain registration service.

The export, domreg_opensrs, uses the Net::OpenSRS module from CPAN. (This uses OpenSRS in a simple, robust way, but does not make use of advanced features like auto-renewal, whois privacy, etc.)

Setup

Common Preparation

Setting up the export is similar to setting up any of Freeside's exports.

• Make sure you have a reseller account at OpenSRS.

• Log into OpenSRS and enter your IP address under "Add IPs for Script/API Access" in the Profile Management section of the site. If you haven't already done so, select "Generate New Private Key" and save the key for later. You'll paste it into the export configuration. (If you're intending to use the OpenSRS test system for testing your setup and switch to the live system later, you'll need to generate a separate key in each system.)

• Make sure you have Net::OpenSRS and its prerequisites installed

perl -MNet::OpenSRS -e 'print $Net::OpenSRS::VERSION'

• Patch Net::OpenSRS if necessary. Net::OpenSRS uses XML::Simple, which can use several XML parsers. At least one of these, probably SAX/Expat throws an exception parsing the response from OpenSRS when renewing a domain as the response does not meet strict XML standards. Net::OpenSRS 0.03 will include a fix for this problem. If you're using an earlier version, apply this patch:

--- OpenSRS.pm.orig	2006-04-08 22:26:22.000000000 +0000
+++ OpenSRS.pm	2009-06-14 22:07:32.000000000 +0000
@@ -1159,7 +1159,10 @@
     my $struct;
     if ( $res->is_success ) {
         $self->debug("HTTP result: " . $res->status_line);
-        eval { $struct = XML::Simple::XMLin( $res->content); };
+	my $rslt = $res->content;
+	# OpenSRS renew response triggers parser error due to spaces in element name
+	$rslt =~ s/registration expiration date/registration_expiration_date/g;
+        eval { $struct = XML::Simple::XMLin( $rslt ); };
 
         if ($self->debug_level > 1) {
             $self->debug("\nOpenSRS Response XML:\n" . '-' x 30);

• Make sure your LWP::UserAgent can make HTTPS connections. (You have the Crypt::SSLeay or the IO::Socket::SSL module installed.) You'll need this for your Business::OnlinePayment modules too.

• Log into Freeside, select "Configuration / Provisioning and services / Exports" in the menu, and "Add a new export" using domreg_opensrs, and configure the export.

Configuration

Many of the export's configuration options are required for Net::OpenSRS, so reading the documentation for that module may help in understanding the options.

• The "Export host" must be the OpenSRS test or live gateway. Use one of the preset buttons in the description to get the right value.

• Type in your OpenSRS reseller name.

• Paste the OpenSRS private key.

• Type in the password you'll use to manage the domains at https://manage.opensrs.net/ (This is a limitation of Net::OpenSRS: all domains are registered under the same set of credentials, and the user name is the same as your reseller user name.)

• Enter a master domain that all other domains will be associated with at OpenSRS. (Net::OpenSRS uses this to associate all domains together.) This domain should be registered at OpenSRS with the user name and password you entered above.

• Enter a Net::OpenSRS debug level. Set this to zero for production use, and 3 for testing. Debugging messages are written to the Apache server logs.

• Select the top-level domains you want to allow the export to try to manage. The export does not implement all the business rules to successfully register domains in .ca, and several other TLDs.

• Click "Apply changes"

New Setup

If you have no existing svc_domain service representing domain registrations that you wish to handle with OpenSRS:

• Configure a service using svc_domain and associate the export with it. Or, modify an existing service to use the export.

• Place the new svc_domain service in a package.

Conversion

If you already have a svc_domain service that you use for domain registrations, you can add the OpenSRS export to the exports used for that service. Configure the export as above before adding it to the service.

Adding will take a few minutes if you have a sizable number of domains, as Freeside will be exporting all the domains. The export will not attempt to register or transfer any of your existing domains as they're probably already in the state you want.

Use

New Domain

Once the export is set up and associated with a svc_domain service, Freeside will give you additional options when you provision the svc_domain. The "Add Domain" screen will let you choose to register the domain at OpenSRS, transfer it to OpenSRS, or just add the domain to Freeside. The last choice is useful if the client has the domain registered somewhere else and does not want you to handle the registration for them. The export does not check if the domain is already registered, so you need to ask the client if it is a new domain and choose register or transfer as appropriate.

When a domain is registered, the customer contact information is used for the owner, admin, and billing contacts of the domain. OpenSRS requires a first and last name, street address, city, state and ZIP code, and a phone number and email address. The export uses the first invoicing email address.

View Domain

There are additional operations you can perform at the "View Domain" screen. The screen shows the registration status of the domain. This can include:

• An error message to say that Net::OpenSRS is not installed.
• An error message indicating that OpenSRS cannot be contacted and the status of the domain cannot be determined.
• "Not registered" if the domain is not registered anywhere.
• "Transfer to OpenSRS" if the domain is not registered through your OpenSRS reseller account.
• The current expiration date of the registration if the domain is registered through your account.

Depending on the status, a set of appropriate operations are displayed:

• Register the domain at OpenSRS.
• Transfer the domain to OpenSRS.
• Renew the registration. (This is displayed even if the domain is registered for the maximum term.)
• Revoke the registration. (This is displayed even if the domain has been registered longer than the grace period during which revocation is allowed.)

Click on the link to select the desired operation.

Once the operation has been attempted, you will see the result in the "View Domain" screen. If you have OpenSRS set to queue requests, then the operation will not be performed until you log into OpenSRS and tell it to perform the queued operation. (This is useful for testing, but you'll probably want to set OpenSRS for immediate processing in production.)

Transfers

Telling Freeside to transfer the domain just files a transfer request, causing OpenSRS to send the domain admin contact an email asking them to confirm the transfer. (It does not, and cannot, perform an unauthorized transfer.) Be sure to let them know where to get the required auth code to authorize the transfer.