OpenSRS v2.57 Perl Client Manual - PDF

Document Sample
OpenSRS v2.57 Perl Client Manual - PDF Powered By Docstoc
					OpenSRS v2.57 Perl Client Manual




       July 22, 2002
DOCUMENT CONTENTS




1 REVISIONS................................................................................................................4

2 SYSTEM OVERVIEW ................................................................................................5
  2.1     PURPOSE OF OPENSRS .........................................................................................................5
  2.2     PROCESS FLOW ......................................................................................................................5
3 RESELLER CLIENT LIBRARY (RCL) ......................................................................6
  3.1 PROCESS FLOW .....................................................................................................................6
  3.2 WEB INTERFACES ...................................................................................................................6
    3.2.1 Reseller Web Interface (RWI)........................................................................................6
    3.2.2 Manage Web Interface (MWI) .......................................................................................7
    3.2.3 Conversion Web Interface (CWI)...................................................................................8
  3.3 RESELLER CLIENT MODULE .....................................................................................................8
  3.4 INSTALLATION .........................................................................................................................8
    3.4.1 Requirements ................................................................................................................9
    3.4.2 Installing modules..........................................................................................................9
    3.4.3 Installing CGIs ...............................................................................................................9
    3.4.4 Configuration File ........................................................................................................10
    3.4.5 Testing Your Installation ..............................................................................................15
  3.5 UPGRADING .........................................................................................................................16
  3.6 CUSTOMIZING .......................................................................................................................16
4 RESELLER CLIENT APPLICATION PROGRAMMING INTERFACE (RCAPI).....17
  4.1 OVERVIEW ...........................................................................................................................17
  4.2 FUNCTIONS ..........................................................................................................................17
  4.3 TEMPLATES ..........................................................................................................................18
    4.3.1 manage.cgi..................................................................................................................19
    4.3.2 reg_system.cgi ............................................................................................................20
    4.3.3 reg_system.name.cgi ..................................................................................................21
    4.3.4 register.cgi...................................................................................................................22

support@opensrs.org                                   Perl Client Manual v2.53                                                Page 2 of 29
  4.4    CREDIT CARD NOTES............................................................................................................22
  4.5    RETURN AND ERROR CODES .................................................................................................23
  4.6    BATCH ORDERS ...................................................................................................................23
5 WRITING YOUR OWN CLIENT ..............................................................................25

6 SPECIAL CONSIDERATIONS FOR ASYNCH REGISTRIES ................................25

7 WINDOWS PLATFORM ..........................................................................................27

8 TECHNICAL SUPPORT ..........................................................................................28
  8.1    GETTING HELP ......................................................................................................................28
  8.2    FINDING CONTRACTORS TO SET IT UP .....................................................................................28
  8.3    FORGOTTEN PASSWORDS .....................................................................................................28
  8.4    LICENSES.............................................................................................................................28




support@opensrs.org                                   Perl Client Manual v2.53                                                  Page 3 of 29
1 Revisions
April 18, 2002
      • Removed information for the regsystem.us.cgi

March 21, 2002
     • Added information for domain locking to %opensrs and %manage configuration
     hashes.

March 1, 2002
     • Updated template information for reg_system.us.

February 27, 2002
     • Added template information for reg_system.us.

January 22, 2002
   • Added .ca transfer and registration information to reg_system.cgi

August 16, 2001
   • Corrected faulty reference in the RCL Customizing section (page 16).

July 5, 2001
      • Updated the Requirements section to include information for Windows 98 users (re:
      Crypt::CBC and necessary modules)

June 19, 2001
     • Updated the Requirements section to include new version of Perl (v5.005_03) and
     expanded on module information for Crypt::Blowfish_PP and XML::Parser.
     • Added warning to the Configuration File section Expanded the Index

January 25, 2001
     • Added config file options for .tv post lookup behavior
     • Added config file options for .CA domains
     • Added config file options for MLDNS
     • Added config file options for renewals
2 System Overview
2.1 Purpose of OpenSRS
OpenSRS is a cooperative SLD (second level domain name) registration service managed by
Tucows Inc. At the time of this writing, OpenSRS supports registrations for the following:

                    •   .com, .net and .org,
                    •   portions of the .uk namespace (namely .co.uk , .org.uk)
                    •   .ca
                    •   Multilingual .com, .net and .org (any language supported by UTF-8)

It is a completely open system designed to allow domain name resellers that are not ICANN or
NSI affiliated to register domain names at wholesale rates.

OpenSRS also allows purchasing of digital certificate key codes. The key codes are used to
complete the purchase of a digital certificate outside of the OpenSRS system.

The Reseller Client Library (RCL) is a set of Perl scripts that provide full access to OpenSRS,
and can be configured to integrate with your business systems. You can customize the look
and feel of the interface, and tailor the system to meet your needs. The client library is
provided as a working model that can be used as is, enhanced for your particular needs, or
replaced entirely with your own application.



2.2 Process flow
The Reseller Client Library (RCL) communicates with a Reseller Agent (server back-end),
which runs the OpenSRS application.

The client and agent communicate using TCP/IP and require authentication from both the
Reseller and the Registrant.

All transactions (except domain lookups) are encrypted and authenticated.

The encoding type of all interfaces is set to UTF-8 in order to provide seamless and
transparent multilingual registrations.
3 Reseller Client Library (RCL)
3.1 Process Flow
Action (command) requests are passed from the Reseller Client to the Reseller Agent (server).
Any additional information that is required for the action is specified using a hash of key/value
pairs.

The Reseller Agent attempts to execute the command, and returns a response code indicating
success or failure. On success, the agent also returns any data that resulted from the action
that was executed.

Each transaction requires the reseller and registrant to authenticate. Once a registrant has
successfully logged in, they are issued a cookie to be stored in their browser. From this point
on, further authentication only requires the cookie.



3.2 Web Interfaces
Several CGI scripts are supplied with the Reseller Client Library (RCL). These scripts are
written in Perl and implement a web-based interface to the OpenSRS system. You can use
these scripts as is, modify them to suit your site's look and feel, or replace them entirely.

If you choose to write your own web interface, you will need to familiarize yourself with the
Reseller Client module, XML_Client.pm, which is described in section 3.3.

Descriptions of the CGI scripts follow.



3.2.1     Reseller Web Interface (RWI)
reg_system.cgi
This script implements the full functionality available through the OpenSRS system. It is the
recommended way of allowing your clients to register domains through your network. Clients
may also purchase a digital certificate key code through this interface.

The script includes several convenient functions, including a domain lookup tool, a credit card
checksum validation routine, mail notification and thank you notes that can be customized and
sent to the client.
                                                                          Reseller Client Library (RCL)

This script supports immediate processing as well as queuing of orders for later review and
processing. These features offer you flexibility in how you process orders from your clients.
For example, if your business process does not support real-time payments, you might choose
to queue orders, so that you can review and confirm payments before committing the orders.

Users can set the auto-renew option when registering or transferring domains. Bulk register
and transfers also support this new feature.

If you call this program directly without arguments (e.g. /cgi-bin/reg_system.cgi), it will
display the main page, which allows a user to search for a domain, upgrade a 3rd or 4th level
.ca domain, transfer a domain, or purchase a digital certificate.


register.cgi
This is a "lite" version of reg_system.cgi. It is intended to show the bare necessities for
registering a domain with OpenSRS. As such, it offers very limited functionality. It does not
use the OpenSRS Registration Management system, does not support the queuing of orders
for later review, and does not handle e-mail notification for you. Digital certificates cannot be
purchased through this interface.

**WARNING** If you place this script in a publicly accessible area it is possible that users
could register domains using your account balance without your knowledge. Please restrict
access to this CGI if you have your configuration file pointing to the live OpenSRS server.

Users can set the auto-renew option when registering or transferring domains. Bulk register
and transfers also support this new feature.


renew.cgi
This script allows you to log in as a user and renew a domain. It demonstrates the use of the
get_domain, renew_domain and modify_domain APIs.



3.2.2     Manage Web Interface (MWI)
manage.cgi
This script supports various domain management functions. It can be used directly by your
clients to:

                      • change the nameservers for their domain
                      • create a subuser with specified privileges to administer various aspects
                      of their domain
                      • modify contact information
                      • create or modify nameservers based on their domain (e.g.,
                      dns1.theirdomain.com)




support@opensrs.org                     Perl Client Manual v2.53                           Page 7 of 29
                                                                              Reseller Client Library (RCL)

If you call this program directly without arguments (e.g. /cgi-bin/manage.cgi), it will display
the main page, which allows a user to login and manage a domain.

The manage.cgi script has the following features related to renewals:

The user will receive a banner with a link to a list of domains up for renewal in 60 days
(configurable from OpenSRS.conf) and a link to the list of domains past expiration date.

These links take the user to pages where renewable domains are listed and users can then set
auto-renew flags and/or renew domains. Please note that if you set a domain to be auto-
renewable more that 30 days before its expiration date, it will automatically be renewed by
the OpenSRS system.



3.2.3     Conversion Web Interface (CWI)
RACE.cgi
This is an interface for demonstrating RACE (Row-based ASCII Compatible Encoding), and it
can be used to verify RACE conversions. As all the other interfaces, this interface’s encoding
type is set to ‘UTF-8’

Currently each multilingual name converted to its RACE equivalent is prefixed by bq--(**)1.
An example of a RACE converted name could look something like the following:

                 bq--3ch5auvi.com

This RACE converted name, along with the language encoding type, are the true
representations of what gets stored in both the OpenSRS system and the Registry database
and Zone files. This tool also serves to help end-users convert their native language names to
their RACE equivalent to facilitate whois lookups. For any support issues surrounding
multilingual names, we ask that resellers communicate with Tucows/OpenSRS using the RACE
converted name. The use of RACE conversion has been dictated by Verisign Global Registry
Services Inc. and is based on an Internet Draft presented to the IETF (Internet Engineering
Task Force). A copy of this draft can be found at the following link:

http://search.ietf.org/internet-drafts/draft-ietf-idn-race-03.txt



3.3 Reseller Client Module
The Reseller Client module, XML_Client.pm, allows you to talk with the back end OpenSRS
servers. If you are planning to write your own web interface, or expand the functionality of
the included CGI scripts, you will need to familiarize yourself with the client module API.

3.4 Installation
1
  As this is currently a test bed it is important to note that this prefix may change at any time. Names
registered in this fashion without sending through the Character Encoding type would not be recognized
as multilingual names.

support@opensrs.org                      Perl Client Manual v2.53                              Page 8 of 29
                                                                         Reseller Client Library (RCL)




3.4.1     Requirements
The following must be present on your system before you begin installation of the client
library. Some of these modules may already be present on your system – if so, simply skip
them and move on to the next module on the list.

The Perl modules can be found by searching CPAN at http://search.cpan.org/.



                Software             Item
                Perl                 Perl 5.6 (if you wish to use RACE) or 5.005_03 or later

                                     Note: Perl 5.6 is the recommended version.

                Perl Modules         Crypt::Blowfish or Crypt::DES (depending on encryption
                                     method selected in OpenSRS.conf)
                                     Crypt::CBC
                                     Digest::MD5
                                     HTML::Template
                                     MD5
                                     MIME:Base64
                                     Storable
                                     Unicode::Map
                                     Unicode::String
                                     XML::Parser

                Web Server           Web server that allows CGI execution (e.g. Apache)


Note: Problems may be encountered when installing on RAQ3 servers – if you receive
WARN_DEPRECATION and/or WARN_COMPATABILITY errors, simply comment out the lines and
continue.


Note: If you are using Windows 98, you must have the following modules installed:
Crypt::Blowfish, Expat Storable and HTML::Template.



3.4.2     Installing modules
Follow the specific installation instructions contained for each Perl module in the order they
appear in the above table.



3.4.3     Installing CGIs
1) Unpack tar ball into some base directory.

support@opensrs.org                   Perl Client Manual v2.53                            Page 9 of 29
                                                                          Reseller Client Library (RCL)


2) Copy the configuration file etc/OpenSRS.conf to the desired base install location (i.e.
BASE_INSTALL_DIR).

3) Edit the OpenSRS.conf file per your system configuration, inserting your username and
private key where indicated. See the "Configuration File" section below for more information.

4) Copy the CGI scripts to the desired location on your web server. (i.e. cgi-bin)

5) Edit the path to your PERL5 binary in the CGI scripts.

6) Edit the path to your OpenSRS.conf in each of the CGI scripts.

7) Copy logo.gif (or a logo of your choice) to the same directory as your CGIs.



3.4.4     Configuration File
The client library uses a configuration file, OpenSRS.conf, which must be modified to work
properly on your system.

**WARNING** In order to protect the security of your username and private key, ensure that
the OpenSRS.conf file is NOT in the document path of your web server.

In the current implementation, the configuration file is a Perl file, and variables are used to
define the configuration values.

Here is a description of the variable names:




                Variable Name           Description
                USERNAME                This is your reseller username.

                PRIVATE_KEY             Your private key.

                ADMIN_EMAIL             The e-mail address where you would like
                                        administrative e-mails sent.

                PATH_SOURCE             Full path to the location of the OpenSRS source code.
                                        (Do not include the trailing slash.)

                PATH_LIB                Location of the OpenSRS libraries. You should not
                                        need to change this if you unpacked the tar ball as
                                        described under Installation.



support@opensrs.org                    Perl Client Manual v2.53                           Page 10 of 29
                                                                         Reseller Client Library (RCL)

                  Variable Name         Description
                  PATH_TEMPLATES        Location of the OpenSRS templates. You should not
                                        need to change this if you unpacked the tar ball as
                                        described under Installation.



MLDNS Configuration
MLDNS registrations have been made transparent with respect to regular ASCII registrations.
Essentially a domain name can have encoding type “” (ASCII) or “UTF-8”(Everything else). A
global variable $UNIVERSAL_ENCODING_TYPE has been added to the OpenSRS.conf.


OpenSRS Behavior Configuration
This configuration is specified in the %OPENSRS hash. Most of the fields refer to machine
names and ports that tell the client how to contact the OpenSRS server.

Initially, these hostnames point to the OpenSRS test environment. This allows you to setup
your installation and test it thoroughly before switching over to the live environment (see the
section "3.4.5 Testing Your Installation"). When you are ready to change to the live
environment, modify the HOST and PORT values accordingly.



Key Name                           Description
crypt_type                         This is the type of encryption you wish to use. Allowed
                                   values are DES, Blowfish or Blowfish_PP.

Username                           Your username (previously defined).

private_key                        Your private key (previously defined).

lookup_all_tlds                    Flag to look up similar available domains during a domain
                                   search. Allowed values are 0|1, where 0 = False (don't do
                                   similar lookups), and 1 = True (do similar lookups).

REMOTE_HOST                        Hostname of the OpenSRS server. Initially, this should be
                                   set to horizon.opensrs.net to allow you to connect to the
                                   test system.

                                   Eventually, once you are an approved reseller, you will able
                                   to connect to the live system, at rr-n1-tor.opensrs.net.

                                   Note: If you are not an approved reseller, any attempts to
                                   connect to the live system will be rejected.




support@opensrs.org                   Perl Client Manual v2.53                           Page 11 of 29
                                                                       Reseller Client Library (RCL)

Key Name                         Description
REMOTE_PORT                      Port of the OpenSRS server. This should be set to 55000
                                 for both test and live systems.

OPENSRS_TLDS_REGEX               A regular expression that lists the domains serviced by
                                 OpenSRS. This should only include the domains that you
                                 are authorized to register. If you enter domains for which
                                 you are not authorized, they will not work.

RELATED_TLDS                     Defines what TLDs to treat as "related" for the purpose of
                                 the lookup_all_tlds flag.

                                 You can also specify SLDs in here (e.g. "co.com",
                                 "net.com", "web.com") and these will be prefixed with the
                                 domain being searched.

                                 Note: Be careful when registering a mix of domains when
                                 the different TLDs have different period year restrictions.

UNIVERSAL_ENCODING_TYPE          This is a constant needed for RACE conversion. The value
                                 should always be " UTF-8".

TLDS_SUPPORTING_LOCKING          Regular-expression-style matching of TLDs which support
                                 domain locking. If a reseller wants to prevent some
                                 domains from being lockable on a TLD basis, he can
                                 remove them from this regex.

                                 Example:

                                 TLDS_SUPPORTING_LOCKING => '\.(com|net|org|info|biz)$',



Flags for reg_system.cgi
This configuration is specified in the %REG_SYSTEM hash. This configuration hash allows you to
customize the behavior of the reg_system.cgi script.



                Key Name               Description
                Debug                  Whether to allow debugging. Allowed values are 0|1,
                                       where 0 = No, 1 = Yes.

                custom_tech_contact    Whether to allow custom technical contact
                                       information. Allowed values are 0|1, where 0 = No, 1
                                       = Yes.

                custom_nameservers     Whether to allow custom nameserver information.
                                       Allowed values are 0|1, where 0 = No, 1 = Yes.

support@opensrs.org                   Perl Client Manual v2.53                         Page 12 of 29
                                                                        Reseller Client Library (RCL)

                Key Name               Description
                                       Allowed values are 0|1, where 0 = No, 1 = Yes.

                F_VERIFY_CC            Whether to verify credit card numbers as being valid.
                                       Allowed values are 0|1, where 0 = No, 1 = Yes.

                F_SEND_ORDERS          Whether to send a copy of all orders to the e-mail
                                       address defined in ADMIN_EMAIL. Allowed values are
                                       0|1, where 0 = No, 1 = Yes.

                F_SEND_THANKYOU        Whether to send a "thank you" e-mail to the customer
                                       for domain purchases. Allowed values are 0|1, where
                                       0 = No, 1 = Yes.

                                       Note: Digital certificate purchases will always send an
                                       e-mail to the customer with the key code(s).

                post_lookup            This hash defines post lookup behavior. Each key in
                                       this hash corresponds to a domain (typically a TLD).

                                       Within each key, the specific behavior for that domain
                                       is defined.

                                       Possible values are:

                                       sub - name of subroutine that handles the process.

                                       url - URL to which the user will be conditionally re-
                                       directed, depending on the logic in sub.

                                       template - the template used to show the user what is
                                       occurring (i.e. an explanation that they are about to
                                       be redirected).


Flags for register.cgi
This configuration is specified in the %REGISTER hash. This configuration hash allows you to
customize the behavior of the register.cgi script.



                Key Name               Description
                Debug                  Whether to allow debugging. Allowed values are 0|1,
                                       where 0 = No, 1 = Yes.



Flags for manage.cgi

support@opensrs.org                  Perl Client Manual v2.53                           Page 13 of 29
                                                                        Reseller Client Library (RCL)

This configuration is specified in the %MANAGE hash. This configuration hash allows you to
customize the behavior of the manage.cgi script.

Key Name                          Description
Debug                             Whether to allow debugging. Allowed values are 0|1,
                                  where 0 = No, 1 = Yes.

notice_days                       Show expire notice in manage.cgi when this many days or
                                  less are left until expiry for the domain.

allow_domain_locking              Whether to offer domain locking features at all through the
                                  manage interface. If disabled, no locking functionality will
                                  be visible.

                                  Valid values: 0,1

                                  Example:
                                  allow_domain_locking => 1,



Flags .CA domains
This configuration is specified in the following data elements:

                Name                     Description
                %CA_LEGAL_TYPES          Hash for .CA domain legal types

                %CA_LANGUAGE_TYPE Hash for .CA domain language types
                S

                %CA_NATIONALITIES        Hash for .CA domain nationalities

                @CA_EXTRA_FIELDS         Array for .CA domain extra fields

                $CA_PREREG_PERIOD        Flag indicating status of .CA preregistration period.
                                         Allowed values are 0|1, where 1 = period enabled, 0
                                         = period disabled. Note: Set this to 0 once the pre-
                                         registration period is over.




Flags: Renewals configuration
The configuration for renewals in specified in the %RENEW hash.

                Name                    Description
                debug                   Whether to allow debugging. Allowed values are 0|1,
                                        where 0 = No, 1 = Yes.

support@opensrs.org                   Perl Client Manual v2.53                          Page 14 of 29
                                                                        Reseller Client Library (RCL)

                 Name                   Description

                 capability             Defines which TLDs are eligible for being renewed.
                                        Allowed values are 0|1, where 0 = No, 1 = Yes.



Mail Delivery Configuration
This configuration allows you to define how mail is handled.

                 Variable Name          Description
                 MAIL_TYPE              Type of mail. Allowed values are 'sendmail', and
                                        'smtp'. The 'sendmail' value is recommended for
                                        Unix based systems, while 'smtp' is recommended
                                        for Win32 servers.

                                        If you do not have sendmail (or an equivalent MTA)
                                        on your system, use 'smtp'.

                 MAILPROG               Set this to the path and arguments you wish to pass
                                        to sendmail (or other MTA). This is only needed if you
                                        are using a MAIL_TYPE of 'sendmail'.

                 LOCALHOST              Fully qualified domain name of the machine from
                                        which you are sending mail. This is only needed if you
                                        are using a MAIL_TYPE of 'smtp'.

                 SMTP_SERVER            Fully qualified domain name of the SMTP server you
                                        are using. This is only needed if you are using a
                                        MAIL_TYPE of 'sendmail'.

                 SMTP_PORT              The port to use for SMTP. This is only needed if you
                                        are using a MAIL_TYPE of 'sendmail'.




3.4.5      Testing Your Installation
A Perl script, verify_install.cgi, has been included to help you verify whether your
installation is correct. It examines your system for the required Perl modules and attempts to
connect to the OpenSRS server with your username and private key. It can be run from a
shell script or through your web browser as a CGI.

When testing your application using the OpenSRS test environment, be sure to use the
following nameserver information:

        Primary Hostname : ns1.domaindirect.com

support@opensrs.org                    Perl Client Manual v2.53                         Page 15 of 29
                                                                         Reseller Client Library (RCL)

       Secondary Hostname: ns2.domaindirect.com

The test environment connects to a Registry server with very limited information about
current domains and hosts. This means that most otherwise valid nameservers will be
rejected, while domains that are not available in the real world (because they are already
registered) could show up as available in the test environment.

Once you have been approved and are accessing the live system, all valid nameservers will be
recognized, and accurate information will be returned on which domains are available.



3.5 Upgrading
This release of the Reseller Client Library uses the XCP protocol to communicate with the
OpenSRS Reseller Agent (server). The CGIs included with the previous client library will no
longer work with the new RCL because they use a deprecated API.

If you have created your own CGI's that use the previous client library, there are two things
you can do:

Modify your CGIs to use the new XCP protocol. This requires changes to how you call the
send_cmd function. You may also need to change some code behavior to handle new
responses from the server when dealing with asynchronous registries. Look at the CGIs we
have included with this release for examples. See also the OpenSRS Client Protocol
Specification document for full details on the XCP protocol.

Use the CGIs we have included with this release, and modify them as needed to support your
own custom features and particular look and feel.

It is recommended that you install the new RCL into a separate directory and preserve your
existing system, which was based on the previous client library. You can continue to use your
existing system for some time while you work on integrating the new RCL.



3.6 Customizing
The Reseller Client Library (RCL) is provided as a working model, which can be used as is,
enhanced for your particular needs, or replaced entirely with your own application. If you
wish, you can modify the scripts to customize the look and feel of the interface so that it
matches your site. You may also choose to extend the scripts to include functionality
particular to your system (e.g. real-time credit card processing).

If you wish to modify the look and feel of the scripts, read the “Templates” section (below). If
you intend to write your own scripts or extend the functionality of the existing library, be sure
to familiarize yourself with the existing code, and carefully review the section “5 Writing your
own client”.




support@opensrs.org                   Perl Client Manual v2.53                           Page 16 of 29
                                               Reseller Client Application Programming Interface (RCAPI)




4 Reseller Client Application Programming
    Interface (RCAPI)


4.1 Overview
If you wish to interface directly with the Reseller Client module, you will need to familiarize
yourself with the Reseller Client API.

The Reseller Client issues "action" requests to a Reseller Agent running on the OpenSRS
server. The server responds with an appropriate reply. These action requests are sent using
the send_cmd function in XML_Client.pm.

The XML Client Protocol (XCP) defines the supported action set. See the description of the
XCP in the OpenSRS Client Protocol Specification document for more information.



4.2 Functions
This section describes the commands that are available through the Reseller Client Library
(RCL).

                send_cmd
                (
                  hashref
                )


Purpose:
Action (command) requests are passed from the Reseller Client to the Reseller Agent (server)
through the send_cmd method of the OpenSRS object. The specific command and any
associated data is passed via a reference to a hash structure. The details of this hash
structure are documented in the XML Client Protocol (XCP). For more information on the XCP
message format, read the OpenSRS Client Protocol Specification document.



support@opensrs.org                    Perl Client Manual v2.53                            Page 17 of 29
                                              Reseller Client Application Programming Interface (RCAPI)

The server attempts to execute the command, and returns a reply indicating success or
failure. On success, the server also returns any data that resulted from the action that was
executed.


Parameters:
The following parameters are used with the send_cmd method:

                Key Name          Type (Perl)         Description
                hashref           hash (reference) A reference to a hash structure that
                                                   contains the XCP action you wish to
                                                   execute.




Return Values:
The command returns a hash structure that contains error/success codes, as well as any
additional data returned by the action that was executed. The contents of this hash are
stored in the XCP response message format, and are interpreted according to the action that
was requested. Specific details can be found in the XCP documentation in the OpenSRS Client
Protocol Specification document.


4.3 Templates
Templates are used to customize the appearance (look and feel) of the client.

There are two types of templates: HTML templates and e-mail templates. HTML templates
define the appearance in the browser; these files end in .html. E-mail templates define what
e-mails will look like; these files end in .txt.

The templates contain placeholders for real data. The placeholders are specified with {{}}
brackets. The name within the placeholder refers to a variable name within the Perl scripts.
At runtime, the Perl scripts substitute relevant data into these placeholders; before the HTML
page is displayed or the e-mail is sent to the user.

                Example:

                To: {{mailto}}
                From: {{mailfrom}}
                Subject: Registration Request for {{domain}}



In the above example, the placeholders will be substituted at runtime, as follows:




                Placeholder           Variable

support@opensrs.org                   Perl Client Manual v2.53                            Page 18 of 29
                                              Reseller Client Application Programming Interface (RCAPI)

                Placeholder           Variable
                {{mailto}}            replaced with contents of $mailto

                {{mailfrom}}          replaced with contents of $mailfrom

                {{domain}}            replaced with contents of $domain




You should not edit the values inside the {{}} brackets, because the CGI scripts are
dependent on these values.

Templates are used with the print_form function, which accepts the name of a template and
a reference to a hash that represents the key/values to put into that template.

example:

        print_form("$path_templates/login.html",\%HTML);

where %HTML is a hash containing the key/value pairs to replace in the template called
login.html.



4.3.1     manage.cgi
The following templates are associated with the manage.cgi script, and are found in the
BASE_INSTALL_DIR/templates/manage directory:



                Template Name            Description
                base.html                Base menu page.

                change_ownership.html Change Ownership of Domain form.

                change_password.html Change Password for Domain Management form.

                error.html               Generic error page.

                login.html               Initial login page to manage.cgi.

                main_menu.html           Navigation help page.

                manage_nameservers.h Manage nameservers page.
                tml

                manage_profile.html      Profile Management page with links to other options.



support@opensrs.org                   Perl Client Manual v2.53                            Page 19 of 29
                                              Reseller Client Application Programming Interface (RCAPI)

                Template Name            Description
                manage_subuser.html      Manage sub-user page.

                modify_contact.html      Form to edit contact information.

                modify_nameservers.ht Page for modifying nameservers.
                ml

                view_domains.html        Page showing domains managed by registrant.




4.3.2     reg_system.cgi
The following templates are associated with the reg_system.cgi script, and are found in the
$BASE_INSTALL_DIR/templates/reg_system directory:



                Template Name               Description
                avail.html                  Page saying that the domain is available, with
                                            option to reserve or continue searching.

                base.html                   Base menu page.

                batch_order.html            Domain registration form for batch orders.

                batch_order_ca.html         .ca domain registration form for batch orders.

                batch_transfer_thankyou.h Thank you page after a batch transfer, displays
                tml                       the batch transfer ID.

                cert_thanks.html            Thank you page after a certificate order, displays
                                            the order ID and the key code(s).

                confirm_purchase_webcert Confirmation page for Digital Certificate order.
                .html

                error.html                  Generic error page.

                main_menu.html              Main menu and navigation help page.

                message.txt                 E-mail that is sent when a registration request is
                                            made.

                order.html                  Domain registration form for single orders.



support@opensrs.org                   Perl Client Manual v2.53                            Page 20 of 29
                                                Reseller Client Application Programming Interface (RCAPI)

                Template Name                 Description
                order_ca.html                 .ca domain registration form for single orders.

                purchase_webcert.html         Digital certificate order form.

                setup_profile.html            Page for setting up domain management profile
                                              below.

                setup_profile_ca.html         Page for setting up .ca domain management
                                              profile below.

                taken.html                    Page that is displayed when a domain is already
                                              taken. Provides option to search another domain.

                thankyou.html                 "Thank you" page. Displayed after a registration,
                                              showing the current status of the registration, as
                                              well as a tracking number.

                thankyou.txt                  E-mail that is sent out when a Registration
                                              Request is submitted.

                transfer_ca.html              .ca domain transfer form for single orders.

                verify.html                   Registration verification page, showing all detail of
                                              requested registration. Displayed before order is
                                              committed.

                verify_ca.html                Registration verification page, showing all detail of
                                              requested .ca registration. Displayed before order
                                              is committed.


Note: Calling the reg_system.cgi when “action=bulk_transfer&gtld=.ca” will produce a page
requesting only the information that is required to transfer a .ca domain.



4.3.3     reg_system.name.cgi
The following templates are associated with the reg_system.name.cgi script, and are found in
the $BASE_INSTALL_DIR/templates/reg_system.name directory:

Note: This CGI is for the pre-registration of ‘.name’ addresses only. As such it is a temporary
CGI and may be removed from the distribution at any time.



                Template Name                 Description


support@opensrs.org                     Perl Client Manual v2.53                            Page 21 of 29
                                              Reseller Client Application Programming Interface (RCAPI)

                Template Name               Description
                base.html                   HTML template

                error.html                  Generic error page.

                main_menu.html              Main page displayed when CGI is run (Search
                                            page).

                add_order.html              Domain registration form for single orders.

                thankyou.html               "Thank you" page. Displayed after a registration,
                                            showing the current status of the registration, as
                                            well as a tracking number.

                Verify_order.html           Registration verification page, showing all detail of
                                            requested registration. Displayed before order is
                                            committed.



4.3.4     register.cgi
The following templates are associated with the register.cgi script, and are found in the
$BASE_INSTALL_DIR/templates/register directory:


                Template Name            Description
                do_register.html         Message displayed after registration.

                error.html               Generic error page.

                main_menu.html           Main menu page, allowing new registrations, or
                                         transfers.

                register.html            Registration form based on existing profile.

                register_new.html        Registration form.



4.4 Credit Card Notes
Upon a successful registration or transfer, the template message.txt (see above) is sent to
the administrator (this behavior is configurable in the configuration file).

By default, for security reasons, the template does not contain customer payment information
(credit card number, etc.). If you wish to include this information, add the following section to
message.txt:

                ----------------------------------------------------------------------


support@opensrs.org                   Perl Client Manual v2.53                            Page 22 of 29
                                              Reseller Client Application Programming Interface (RCAPI)

                Payment Information:
                ----------------------------------------------------------------------

                Card Type:      {{p_cc_type}}
                Card #:         {{p_cc_num}}
                Exp Date:       {{p_cc_exp_mon}}/{{p_cc_exp_yr}}



4.5 Return and Error Codes
OpenSRS uses HTTP style error codes.

                Code Number                           Description
                200+                                  Success
                300+                                  Temporary Failure
                400+                                  Error
                500+                                  Server error


See the OpenSRS Client Protocol Specification document for a full list of error codes.



4.6 Batch Orders
Batch orders allow you to quickly order many separate domains using one set of contact info.

                You may order domains in a batch by adding the following argument to
                reg_system.cgi:

                action=bulk_order.

                Example:

http://www.domain.com/cgi-bin/reg_system.cgi?action=bulk_order

                ---

                You may order .ca domains in a batch by adding the following argument to
                reg_system.cgi:

                action=bulk_order_ca.

                Example:


http://www.domain.com/cgi-bin/reg_system.cgi?action=bulk_order_ca

                You may order transfer of domains in a batch by adding the following argument to
                reg_system.cgi:

                action=bulk_transfer.

                Example:

http://www.domain.com/cgi-bin/reg_system.cgi?action=bulk_transfer



support@opensrs.org                   Perl Client Manual v2.53                            Page 23 of 29
                              Reseller Client Application Programming Interface (RCAPI)




support@opensrs.org   Perl Client Manual v2.53                            Page 24 of 29
5 Writing your own client
If you wish to write your own client, either in Perl or some other programming language, we
recommend that you examine and familiarize yourself with the supplied Reseller Client
Library. Also read the OpenSRS Client Protocol Specification document, which discusses
issues such as data exchange, handshaking, and encryption.




6 Special considerations for Asynch Registries
The Reseller Client Library (RCL) also supports the registration of domains in asynchronous
registries. Asynchronous registries are those that do not provide a real-time response to a
requested action. For example, the .uk registry operated by Nominet is asynchronous
because it is an e-mail-based system. Any registry request (e.g. new domain registration,
domain modification, and so on), must be submitted by e-mail, and the system must wait for
an e-mail response indicating success or failure.

The OpenSRS system shields the complexity of the asynchronous e-mail processing from you.
However, you still need to be aware of it, because operations (actions) on a registry that is
asynchronous will not give you a real time success or failure response. Instead, you will be
given a message that the action has been sent, and is awaiting processing by the remote
registry. At some later point, you will be able to see the actual results of your action (e.g. if
you make modifications to a domain, you won't see them until some time has elapsed).

This messaging is built into the supplied CGI scripts. If you are writing your own front end to
the RCL, you need to be aware of the asynchronous nature of some requests. See the
                                            Reseller Client Application Programming Interface (RCAPI)

OpenSRS Client Protocol Specification document for more information on which action
requests can be affected by asynchronous behaviour.




support@opensrs.org                 Perl Client Manual v2.53                            Page 26 of 29
7 Windows Platform
The client library has not been specifically tested on the Windows platform. Some have noted
problems compiling the ciphers. If you are unable to compile Crypt::DES or Crypt::Blowfish,
try Crypt::Blowfish_PP (an implementation written in Pure Perl). While slower than the
standard Crypt::Blowfish module, Crypt::Blowfish_PP requires no compilation.
8 Technical Support
8.1 Getting help
See the support FAQ at:

http://www.opensrs.org/Support_FAQ.shtml

The FAQ addresses common technical support questions about OpenSRS sent to the technical
support team.

If the FAQ does not answer your question, send an e-mail to support@opensrs.org. When
sending support requests, make sure to use ASCII text, and don't forget to include your
account name.




8.2 Finding contractors to set it up
Please read the support FAQ at:

http://www.opensrs.org/Support_FAQ.shtml



8.3 Forgotten Passwords
If one of your customers forgets their password, you can login to your reseller
administration area, select "View Active Domains" from the main menu, and click on that
customer's domain to see the record. There is an option on that page for you to have the
username/password sent to the admin contact for that domain. As the reseller, you do not
have the ability to directly change information in the domain name record. But your client
may grant you access as a "sub-user", which will allow you to make modifications on their
behalf (granting of subusers can be done from the manage.cgi web interface).



8.4 Licenses
The client license is posted on the OpenSRS website at:

http://www.opensrs.org/client-license.shtml
                                                 Technical Support)




support@opensrs.org   Perl Client Manual v2.53        Page 29 of 29