opensrs perl client manua.d - Technical Documentationpolarsys.ca/docs/opensrs/srsClientDoc.pdf ·...

OpenSRS v2.57 Perl Client Manual

July 22, 2002

[email protected] Perl Client Manual v2.53 of 29

DOCUMENT CONTENTS

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

2 SYSTEM OVERVIEW................................................................................................5

2.1 PURPOSE OF OPENSRS .........................................................................................................52.2 PROCESS FLOW......................................................................................................................5

3 RESELLER CLIENT LIBRARY (RCL) ......................................................................6

3.1 PROCESS FLOW .....................................................................................................................63.2 WEB INTERFACES ...................................................................................................................6

3.2.1 Reseller Web Interface (RWI)........................................................................................63.2.2 Manage Web Interface (MWI) .......................................................................................73.2.3 Conversion Web Interface (CWI)...................................................................................8

3.3 RESELLER CLIENT MODULE.....................................................................................................83.4 INSTALLATION.........................................................................................................................8

3.4.1 Requirements ................................................................................................................93.4.2 Installing modules..........................................................................................................93.4.3 Installing CGIs ...............................................................................................................93.4.4 Configuration File ........................................................................................................103.4.5 Testing Your Installation..............................................................................................15

3.5 UPGRADING .........................................................................................................................163.6 CUSTOMIZING.......................................................................................................................16

4 RESELLER CLIENT APPLICATION PROGRAMMING INTERFACE (RCAPI).....17

4.1 OVERVIEW ...........................................................................................................................174.2 FUNCTIONS ..........................................................................................................................174.3 TEMPLATES..........................................................................................................................18

4.3.1 manage.cgi..................................................................................................................194.3.2 reg_system.cgi ............................................................................................................204.3.3 reg_system.name.cgi ..................................................................................................214.3.4 register.cgi...................................................................................................................22

mailto:[email protected]


4.4 CREDIT CARD NOTES............................................................................................................224.5 RETURN AND ERROR CODES .................................................................................................234.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......................................................................................................................288.2 FINDING CONTRACTORS TO SET IT UP .....................................................................................288.3 FORGOTTEN PASSWORDS .....................................................................................................288.4 LICENSES.............................................................................................................................28


1 Revisions

April 18, 2002• Removed information for the regsystem.us.cgi

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

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) andexpanded 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 OpenSRSOpenSRS is a cooperative SLD (second level domain name) registration service managed byTucows 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 orNSI affiliated to register domain names at wholesale rates.

OpenSRS also allows purchasing of digital certificate key codes. The key codes are used tocomplete 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 lookand feel of the interface, and tailor the system to meet your needs. The client library isprovided as a working model that can be used as is, enhanced for your particular needs, orreplaced entirely with your own application.

2.2 Process flowThe 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 theReseller 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 andtransparent multilingual registrations.

3 Reseller Client Library (RCL)

3.1 Process FlowAction (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/valuepairs.

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

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

3.2 Web InterfacesSeveral CGI scripts are supplied with the Reseller Client Library (RCL). These scripts arewritten in Perl and implement a web-based interface to the OpenSRS system. You can usethese 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 theReseller 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.cgiThis script implements the full functionality available through the OpenSRS system. It is therecommended way of allowing your clients to register domains through your network. Clientsmay also purchase a digital certificate key code through this interface.

The script includes several convenient functions, including a domain lookup tool, a credit cardchecksum validation routine, mail notification and thank you notes that can be customized andsent to the client.

Reseller Client Library (RCL)


This script supports immediate processing as well as queuing of orders for later review andprocessing. 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 chooseto 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 registerand transfers also support this new feature.

If you call this program directly without arguments (e.g. /cgi-bin/reg_system.cgi), it willdisplay 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.cgiThis is a "lite" version of reg_system.cgi. It is intended to show the bare necessities forregistering a domain with OpenSRS. As such, it offers very limited functionality. It does notuse the OpenSRS Registration Management system, does not support the queuing of ordersfor later review, and does not handle e-mail notification for you. Digital certificates cannot bepurchased through this interface.

**WARNING** If you place this script in a publicly accessible area it is possible that userscould register domains using your account balance without your knowledge. Please restrictaccess 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 registerand transfers also support this new feature.

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

3.2.2 Manage Web Interface (MWI)manage.cgiThis script supports various domain management functions. It can be used directly by yourclients to:

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




If you call this program directly without arguments (e.g. /cgi-bin/manage.cgi), it will displaythe 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 setauto-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 bythe OpenSRS system.

3.2.3 Conversion Web Interface (CWI)RACE.cgi

This is an interface for demonstrating RACE (Row-based ASCII Compatible Encoding), and itcan be used to verify RACE conversions. As all the other interfaces, this interface’s encodingtype 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 truerepresentations of what gets stored in both the OpenSRS system and the Registry databaseand Zone files. This tool also serves to help end-users convert their native language names totheir RACE equivalent to facilitate whois lookups. For any support issues surroundingmultilingual names, we ask that resellers communicate with Tucows/OpenSRS using the RACEconverted name. The use of RACE conversion has been dictated by Verisign Global RegistryServices Inc. and is based on an Internet Draft presented to the IETF (Internet EngineeringTask 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 ModuleThe Reseller Client module, XML_Client.pm, allows you to talk with the back end OpenSRSservers. If you are planning to write your own web interface, or expand the functionality ofthe 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. Namesregistered in this fashion without sending through the Character Encoding type would not be recognizedas multilingual names.


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



3.4.1 RequirementsThe following must be present on your system before you begin installation of the clientlibrary. Some of these modules may already be present on your system – if so, simply skipthem 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 ItemPerl 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 encryptionmethod selected in OpenSRS.conf)Crypt::CBCDigest::MD5HTML::TemplateMD5MIME:Base64StorableUnicode::MapUnicode::StringXML::Parser

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

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

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 modulesFollow the specific installation instructions contained for each Perl module in the order theyappear in the above table.

3.4.3 Installing CGIs1) Unpack tar ball into some base directory.


http://search.cpan.org/



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 andprivate 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 FileThe client library uses a configuration file, OpenSRS.conf, which must be modified to workproperly on your system.

**WARNING** In order to protect the security of your username and private key, ensure thatthe 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 todefine the configuration values.

Here is a description of the variable names:

Variable Name DescriptionUSERNAME This is your reseller username.

PRIVATE_KEY Your private key.

ADMIN_EMAIL The e-mail address where you would likeadministrative 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 notneed to change this if you unpacked the tar ball asdescribed under Installation.




Variable Name DescriptionPATH_TEMPLATES Location of the OpenSRS templates. You should not

need to change this if you unpacked the tar ball asdescribed under Installation.

MLDNS ConfigurationMLDNS 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). Aglobal variable $UNIVERSAL_ENCODING_TYPE has been added to the OpenSRS.conf.

OpenSRS Behavior ConfigurationThis configuration is specified in the %OPENSRS hash. Most of the fields refer to machinenames 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 setupyour installation and test it thoroughly before switching over to the live environment (see thesection "3.4.5 Testing Your Installation"). When you are ready to change to the liveenvironment, modify the HOST and PORT values accordingly.

Key Name Descriptioncrypt_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 domainsearch. Allowed values are 0|1, where 0 = False (don't dosimilar lookups), and 1 = True (do similar lookups).

REMOTE_HOST Hostname of the OpenSRS server. Initially, this should beset to horizon.opensrs.net to allow you to connect to thetest system.

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

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




Key Name DescriptionREMOTE_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 byOpenSRS. This should only include the domains that youare authorized to register. If you enter domains for whichyou are not authorized, they will not work.

RELATED_TLDS Defines what TLDs to treat as "related" for the purpose ofthe 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 thedomain being searched.

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

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

TLDS_SUPPORTING_LOCKING Regular-expression-style matching of TLDs which supportdomain locking. If a reseller wants to prevent somedomains from being lockable on a TLD basis, he canremove them from this regex.

Example:

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

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

Key Name DescriptionDebug Whether to allow debugging. Allowed values are 0|1,

where 0 = No, 1 = Yes.

custom_tech_contact Whether to allow custom technical contactinformation. 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.




Key Name DescriptionAllowed 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-mailaddress defined in ADMIN_EMAIL. Allowed values are0|1, where 0 = No, 1 = Yes.

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

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

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

Within each key, the specific behavior for that domainis 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 isoccurring (i.e. an explanation that they are about tobe redirected).

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



Flags for manage.cgi




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



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

allow_domain_locking Whether to offer domain locking features at all through themanage interface. If disabled, no locking functionality willbe visible.

Valid values: 0,1

Example:allow_domain_locking => 1,

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

Name Description%CA_LEGAL_TYPES Hash for .CA domain legal types

%CA_LANGUAGE_TYPES

Hash for .CA domain language types

%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 configurationThe configuration for renewals in specified in the %RENEW hash.

Name Descriptiondebug Whether to allow debugging. Allowed values are 0|1,





Name Description

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

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

Variable Name DescriptionMAIL_TYPE Type of mail. Allowed values are 'sendmail', and

'smtp'. The 'sendmail' value is recommended forUnix based systems, while 'smtp' is recommendedfor 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 passto sendmail (or other MTA). This is only needed if youare using a MAIL_TYPE of 'sendmail'.

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

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

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

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

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

Primary Hostname : ns1.domaindirect.com




Secondary Hostname: ns2.domaindirect.com

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

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

3.5 UpgradingThis release of the Reseller Client Library uses the XCP protocol to communicate with theOpenSRS Reseller Agent (server). The CGIs included with the previous client library will nolonger 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 thingsyou can do:

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

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

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

3.6 CustomizingThe 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 youwish, you can modify the scripts to customize the look and feel of the interface so that itmatches your site. You may also choose to extend the scripts to include functionalityparticular 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). Ifyou intend to write your own scripts or extend the functionality of the existing library, be sureto familiarize yourself with the existing code, and carefully review the section “5 Writing yourown client”.


Reseller Client Application Programming Interface (RCAPI)


4 Reseller Client Application ProgrammingInterface (RCAPI)

4.1 OverviewIf you wish to interface directly with the Reseller Client module, you will need to familiarizeyourself with the Reseller Client API.

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

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

4.2 FunctionsThis 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 anyassociated data is passed via a reference to a hash structure. The details of this hashstructure are documented in the XML Client Protocol (XCP). For more information on the XCPmessage format, read the OpenSRS Client Protocol Specification document.




The server attempts to execute the command, and returns a reply indicating success orfailure. On success, the server also returns any data that resulted from the action that wasexecuted.

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 thatcontains the XCP action you wish toexecute.

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

4.3 TemplatesTemplates 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 templatesdefine the appearance in the browser; these files end in .html. E-mail templates define whate-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 HTMLpage 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




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 aredependent on these values.

Templates are used with the print_form function, which accepts the name of a template anda 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 calledlogin.html.

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

Template Name Descriptionbase.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.html

Manage nameservers page.

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




Template Name Descriptionmanage_subuser.html Manage sub-user page.

modify_contact.html Form to edit contact information.

modify_nameservers.html

Page for modifying nameservers.

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

Thank you page after a batch transfer, displaysthe batch transfer ID.

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

confirm_purchase_webcert.html

Confirmation page for Digital Certificate order.


main_menu.html Main menu and navigation help page.

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

order.html Domain registration form for single orders.




Template Name Descriptionorder_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 profilebelow.

setup_profile_ca.html Page for setting up .ca domain managementprofile below.

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

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

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

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

verify.html Registration verification page, showing all detail ofrequested registration. Displayed before order iscommitted.

verify_ca.html Registration verification page, showing all detail ofrequested .ca registration. Displayed before orderis committed.

Note: Calling the reg_system.cgi when “action=bulk_transfer&gtld=.ca” will produce a pagerequesting 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 inthe $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 temporaryCGI and may be removed from the distribution at any time.

Template Name Description




Template Name Descriptionbase.html HTML template


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

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, aswell as a tracking number.

Verify_order.html Registration verification page, showing all detail ofrequested registration. Displayed before order iscommitted.

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 Descriptiondo_register.html Message displayed after registration.


main_menu.html Main menu page, allowing new registrations, ortransfers.

register.html Registration form based on existing profile.

register_new.html Registration form.

4.4 Credit Card NotesUpon a successful registration or transfer, the template message.txt (see above) is sent tothe 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 tomessage.txt:

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




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 CodesOpenSRS uses HTTP style error codes.

Code Number Description200+ Success300+ Temporary Failure400+ Error500+ Server error

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

4.6 Batch OrdersBatch 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 toreg_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 toreg_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 toreg_system.cgi:

action=bulk_transfer.

Example:

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




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

5 Writing your own client

If you wish to write your own client, either in Perl or some other programming language, werecommend that you examine and familiarize yourself with the supplied Reseller ClientLibrary. Also read the OpenSRS Client Protocol Specification document, which discussesissues 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 asynchronousregistries. Asynchronous registries are those that do not provide a real-time response to arequested action. For example, the .uk registry operated by Nominet is asynchronousbecause 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 foran 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 isasynchronous will not give you a real time success or failure response. Instead, you will begiven a message that the action has been sent, and is awaiting processing by the remoteregistry. At some later point, you will be able to see the actual results of your action (e.g. ifyou 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 tothe RCL, you need to be aware of the asynchronous nature of some requests. See the



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


7 Windows Platform

The client library has not been specifically tested on the Windows platform. Some have notedproblems 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 thestandard Crypt::Blowfish module, Crypt::Blowfish_PP requires no compilation.

8 Technical Support

8.1 Getting helpSee the support FAQ at:

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

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

If the FAQ does not answer your question, send an e-mail to [email protected]. Whensending support requests, make sure to use ASCII text, and don't forget to include youraccount name.

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


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

8.4 LicensesThe client license is posted on the OpenSRS website at:

http://www.opensrs.org/client-license.shtml




http://www.opensrs.org/client-license.shtml

Technical Support)



opensrs perl client manua.d - Technical Documentationpolarsys.ca/docs/opensrs/srsClientDoc.pdf ·...

Documents

Transcript of opensrs perl client manua.d - Technical Documentationpolarsys.ca/docs/opensrs/srsClientDoc.pdf ·...