Difference between revisions of "Freeside:2.1:Documentation:Self-Service Installation"

Latest revision as of 17:28, 30 December 2010

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
• Text::CSV_XS
• 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

Prepaid card signup without customer info

1. Create a template customer - the name/address/telephone numbers will be copied for any customers created via the signup interface (note: this doesn't support multi-agents yet)
2. In the global configuration settings, set signup_server-prepaid-template-custnum to the customer number of the newly created template customer
3. Ensure that prepaid cards are a valid payment method for the signup interface and generate some cards
4. Pass prepaid_shortform=1 to signup.cgi in the URL (e.g. signup.cgi?prepaid_shortform=1); the form which appears should not have billing information fields and should force the prepaid card payment method

Misc

• Wholesale package view: see selfservice_server-view-wholesale global configuration setting

• Restricting login to the self-service for particular services (accounts) only: see selfservice_server-login_svcpart global configuration setting

• If both settings are enabled, the wholesale package view will separate the add/delete/show of self-service accounts

• Viewing tickets and replying to them: this may change in future, but for now ensure that the fs_selfservice RT user has appropriate permissions (e.g. ReplyToTicket and ShowTicket) for all queues