Freeside:2.1:Documentation:Self-Service Installation

Introduction

It is recommended to run the self-service interface on a public web server, not the backend Freeside server. The Freeside server will open an SSH connection to one or more web servers to process signups and self-service requests.

Backend setup

Go to Configuration -> Settings and click on Edit Configuration

Find and setup the following:

• Set the signup_server-default_agentnum configuration value to a default agent number (i.e. 1).
• Set the signup_server-default_refnum configuration value to a default advertising source (i.e. 1).
• Set the signup_server-payby configuration value to the acceptable payment types for signups.
• Set the signup_server-realtime configuration value to run billing for signups immediately.

Prerequisites

API access (Perl, PHP, XML-RPC)

• Perl
• SSH
• Storable 3rd_party_software/Perl
• SOAP::Lite for access from PHP or via the SOAP or XML-RPC APIs

Signup and self-service pages

In addition to the above:

• A web server that can execute CGIs, such as Apache. SSL is highly recommended.
• Text::Template
• Business::CreditCard
• HTTP::BrowserDetect
• HTML::Parser
• Tie::IxHash
• HTML::Widgets::SelectLayers
• TimeDate (CPAN: "install Date::Format")
• Number::Format

Installing FS::SelfService

• Copy the fs_selfservice/FS-SelfService directory to the public web server
• perl Makefile.PL
• make install
• mkdir /usr/local/freeside; chown freeside /usr/local/freeside
• touch /usr/local/freeside/selfservice_socket; chown freeside /usr/local/freeside/selfservice_socket

• chmod 600 /usr/local/freeside/selfservice_socket

OR

• chown freeside:your-www-group /usr/local/freeside/selfservice_socket; chmod 660 /usr/local/freeside/selfservice_socket

Installing web interface

• Copy the fs_selfservice/FS-SelfService/cgi/ directory into the web server's document space.
• Enable CGI execution for files with the `.cgi' extenstion. With Apache, for example:

 #directory where selfservice .cgi scripts and .html templates are located
 <Directory /var/www/selfservice>
 AddHandler cgi-script .cgi
 Options +ExecCGI
 </Directory>

• Use suEXEC or suidperl

OR

• As per above, chown freeside:your-www-group /usr/local/freeside/selfservice_socket; chmod 660 /usr/local/freeside/selfservice_socket

• Optionally, customize the .html templates.
• Useful "entry points" to link to are:
  • signup.cgi - Signup
  • selfservice.cgi - Customer self-service
  • agent.cgi - Reseller interface
  • passwd.cgi - Simple password-changin ginterface
  • promocode.html - Promotional code pre-signup
  • regcode.html - Registration code pre-signup
  • stateselect.html - State selection pre-signup

SSH setup

• On your backend Freeside server, generate SSH keys for the "freeside" user with ssh-keygen. Either use a passphrase-less key, or arrange for ssh-agent to provide keys to freeside-selfservice-server
• Add a "freeside" user to the public web server
• Append the contents of /home/freeside/.ssh/id_rsa.pub (or id_dsa.pub) on your freeside machine to the /home/freeside/.ssh/authorized_keys file on the public web server.
• As the freeside user, ensure you can SSH from your freeside machine to the public web server, without being prompted for a password.

Daemon setup

• Run an instance of freeside-selfservice-server user machine on the Freeside machine for each external machine.
  • user is an employee username.
  • machine is the name or IP of the public web server.

Alternative API access

An alternative method for accessing the XML-RPC self-service API is available. This method is suitable for situations where running the self-service API on the backend in an "embedded" fashion is desirable. It uses fewer resources and is suitable for situations requiring high performance.

• Turn on the selfservice-xmlrpc config option (in the self-service section).
• Install the POE and SOAP::Lite perl modules.
• /etc/init.d/freeside restart
• The server runs on port 8080 and answers requests with any path.
• In client code, use FS.ClientAPI_XMLRPC.methodname instead of FS.SelfService.XMLRPC.methodname. i.e. in freeside.class.php or biz/freeside/SelfService.java

Optional

• You can install the files in the fs_selfservice/FS-SelfService/cgi/ directory multiple places in your web server's document space, and customize the .html templates differently for each. You can set the agentnum used for each signup by editing signup.html and including a hidden field with the agentnum:

 <INPUT TYPE="hidden" NAME="agentnum" VALUE="3">

• When linking to signup.cgi, you can include a referring custnum in the URL as follows: http://public.web.server/path/signup.cgi?ref=1542

• If you create a /usr/local/freeside/ieak.template file on the external machine, it will be sent to IE users with MIME type application/x-Internet-signup. This file will be processed with Text::Template with the variables listed below available. (an example file is included as fs_selfservice/FS-SelfService/ieak.template) See the section on internet settings files in the IEAK documentation for more information. Also see Internet Explorer Prompts to Download Files in the Microsoft Knowledge Base if you have difficulty with IE prompting to download the signup's .ins file instead of processing it.

• Variable substitutions available in ieak.template and success.html:
  • $ac - area code of selected POP
  • $exch - exchange of selected POP
  • $loc - local part of selected POP
  • $username
  • $password
  • $email_name - first and last name
  • $pkg - package name