Difference between revisions of "Freeside:Documentation:FAQ"

From Freeside
Jump to: navigation, search
(add FAQ about perl modules)
(Does Freeside support PayPal?)
 
(78 intermediate revisions by 19 users not shown)
Line 1: Line 1:
 
= General Questions =
 
= General Questions =
  
;Q. What is Freeside's license?
+
== What is Freeside's license? ==
:Freeside is licensed under the terms of the [http://www.gnu.org/copyleft/gpl.html GNU General Public License (GPL)] as published by the Free Software Foundation; either version 2, or (at your option) any later version.
+
:As of Freeside 1.7.3, Freeside is licensed under the [http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License (AGPL)], version three or later.  Prior versions were licensed under the terms of the [http://www.gnu.org/copyleft/gpl.html GNU General Public License (GPL)], version two or later.
  
;Q. What databases are supported by Freeside?
+
:At your option, the '''client side''' of the self-service component (all files in <code>fs_selfservice</code>) may also be licensed under the [http://www.gnu.org/copyleft/gpl.html GNU General Public License (GPL)], version three or later.
:[http://www.postgresql.org PostgreSQL] 7.x/8.x is supported.
 
  
:<nowiki>MySQL</nowiki> is <b>not currently supported</b>. Developers interested in maintaining the :<nowiki>MySQL</nowiki> port are welcome to ask on the -devel mailing list.
+
== What databases are supported by Freeside? ==
 +
:[http://www.postgresql.org PostgreSQL] 8.x+ is recommended.
  
:''Note: the above only applies to the database used by the Freeside software itself.  Freeside can integrate with RADIUS and other servers running <nowiki>MySQL</nowiki> (any version) or any other database.''
+
:[http://www.mysql.com MySQL]/[http://www.mariadb.com MariaDB] v5+ is also supported again starting in Freeside v3.4.  Sponsors or contributions for ongoing maintenance of the MySQL/MariaDB support are welcome.
 +
 
 +
:''Note: the above only applies to the database used by the Freeside software itself.  Freeside can integrate with RADIUS and other servers running a different database than the backend.''
 +
 
 +
== How does Freeside compare to A2Billing? ==
 +
 
 +
Despite both projects doing "asterisk billing", they're actually more complimentary than overlapping.  A2billing is an Asterisk-based soft-switch optimized for offering telephony services (specifically calling card, callback and wholesale services), while Freeside is a back-office customer database and customer portal with CDR processing, invoicing, taxation, reports, credit card processing, trouble ticketing, and so on.
 +
 
 +
== Is there documentation elsewhere? ==
 +
 
 +
All documentation is in the wiki.  Please help us improve it, that's why it is in a wiki!
  
 
= Installation Questions =
 
= Installation Questions =
  
;Q. Using <nowiki>DBD::Pg 1.40</nowiki>, I receive an <code>Use of uninitialized value in die</code> or <code>syntax error at or near "$1"</code> error when running freeside-setup or after upgrading <nowiki>DBD::Pg</nowiki>
+
== How do I avoid "<code>Badly formed sub country data</code>" errors from freeside-setup? ==
:<nowiki>DBD::Pg 1.40</nowiki> has a grave bug (http://rt.cpan.org/NoAuth/Bug.html?id=12004) which causes these errors.  Please use 1.41 or later (1.32 is also okay).
 
 
 
;Q. Running freeside-setup errors out <nowiki>with:</nowiki> <code>Badly formed sub country data</code>
 
 
:Before running freeside-setup, run:
 
:Before running freeside-setup, run:
 
     <code>export LANG=C</code> <i>(sh, bash, zsh, etc. shells)</i>
 
     <code>export LANG=C</code> <i>(sh, bash, zsh, etc. shells)</i>
 
     <code>setenv LANG C</code> <i>(csh or tcsh shell)</i>
 
     <code>setenv LANG C</code> <i>(csh or tcsh shell)</i>
  
;Q. Using <nowiki>Apache::ASP</nowiki>, the information entered in forms is getting lost.  What is wrong?
+
== I'm trying to run Freeside on a <nowiki>VirtualHost</nowiki>, and I get "not running uid freeside" errors. ==
:try adding: <code>PerlSetVar RequestBinaryRead Off</code> to your apache config file.
 
 
 
;Q. Is mod_perl version 2 (1.99) (and its associated Apache 2.x) officially supported by Freeside?
 
:mod_perl version 2 is supported starting with Freeside v1.7.2. 
 
 
 
;Q. I'm running Red Hat 9 and it comes with Apache 2 / mod_perl 1.99 installed already!  How do I downgrade? </b>
 
:These days, [http://www.apachetoolbox.com/ ApacheToolbox] is probably your best bet.  Pointers to a well-maintained source of Apache 1 RPMs for RH9 (or any Fedora versions too, in fact) would be appreciated.
 
 
 
;Q. I'm trying to run Freeside on a <nowiki>VirtualHost</nowiki>, and I get "not running uid freeside" errors.
 
 
:Your mod_perl-enabled Apache instance must run as user "freeside."  This means that the entire server instance must be running as user "freeside," which is accomplished through a server-level <code>User freeside</code> directive.  You ''cannot'' just put <code>User freeside</code> within a <code>VirtualHost</code> block (try running <code>ps -auxwww</code> and you'll see that the apache processes are owned by the server-level specified user, not the virtual host-level specified user).
 
:Your mod_perl-enabled Apache instance must run as user "freeside."  This means that the entire server instance must be running as user "freeside," which is accomplished through a server-level <code>User freeside</code> directive.  You ''cannot'' just put <code>User freeside</code> within a <code>VirtualHost</code> block (try running <code>ps -auxwww</code> and you'll see that the apache processes are owned by the server-level specified user, not the virtual host-level specified user).
  
Line 37: Line 35:
 
:The recommended configuration is to run a '''separate''', mod_perl-enabled Apache instance on a private, firewalled backend server, '''not''' on a public webserver.
 
:The recommended configuration is to run a '''separate''', mod_perl-enabled Apache instance on a private, firewalled backend server, '''not''' on a public webserver.
  
;Q. My Apache logs say (or a command says): <code>Can't locate <SomeModule>.pm in @INC (...)</code>
+
== My Apache logs say (or a command says): <code>Can't locate <SomeModule>.pm in @INC (...)</code> ==
:Install the Perl module the error references.  If the module is not listed in the [[Freeside:1.7:Documentation:Installation#Perl_modules|installation instructions]], edit the documentation and add it.
+
:Install the Perl module the error references.  If the module is not listed in the [[Freeside:1.9:Documentation:Installation#Perl_modules|installation instructions]], edit the documentation and add it.
  
;Q. After installing mod_perl, my Apache logs <nowiki>say:</nowiki> [error] Can't locate Apache.pm in @INC (...)
+
== After installing mod_perl, my Apache logs <nowiki>say:</nowiki> [error] Can't locate Apache.pm in @INC (...) ==
 
:Install Apache::Request
 
:Install Apache::Request
  
;Q. After installing mod_perl, my Apache logs <nowiki>say:</nowiki> "Can't locate mod_perl.pm in @INC" (...)
+
== After installing mod_perl, my Apache logs <nowiki>say:</nowiki> "Can't locate mod_perl.pm in @INC" (...) ==
 
:Include the path to mod_perl.pm by editing apachectl and specifying it.
 
:Include the path to mod_perl.pm by editing apachectl and specifying it.
 
:An example is below (adjust to your needs):
 
:An example is below (adjust to your needs):
Line 53: Line 51:
 
</pre>
 
</pre>
  
;Q. When building software prererquisites for Freeside, which combinations are known to break/fail?</b>
+
== "Host Key Verification Failed" errors, how do I resolve these? ==
:Any: DBD::Pg 1.32 with DBI 1.42 fails "make test". DBI 1.41 is ok''Update: Test failures are harmless, DBI::Pg 1.32 works fine with DBI 1.42.''
+
 
 +
:This error occurs when freeside tries an unattended login via ssh.  The .ssh/known_hosts file on the freeside host must contain entries for the target host(s).  You must ssh into the target host as users root and freeside using the IP or hostname/fqdn specified in the export and/or server commands (passwd, sign-up, self-service).  You cannot have an IP based entry in the known_hosts file and then use a hostname for the exports etc., the verification will fail. Or you can change the sshd_config file directive <nowiki>IgnoreUserKnownHosts</nowiki> from no to yes.  But caution, this will expose your system to security threats if your keys are compromised.
 +
 
 +
== I cannot add a user account.  I see <nowiki>Error:</nowiki> Can't find svc_acct.domsvc in svc_domain.svcnum.  What do I do? ==
 +
:Follow the directions in docs/admin.html exactly.  You have failed to "Add your own domain."  Create a package containing a svc_domain service.  Sell it to yourself.  Provision it with your domain.  Edit the service definition for the svc_acct service and set it to Default or Fixed and your domain.  ''Note: Freeside-setup in 1.7.X and later will have added the first domain already.''
 +
 
 +
== What's causing this error running the self-service client and server? ==
 +
:<pre>Magic number checking on storable file failed at ../../lib/Storable.pm (autosplit into ../../lib/auto/Storable/fd_retrieve.al) line 349, at ...</pre>
 +
:* Mismatched versions of Storable.
 +
:** http://search.cpan.org/perldoc/Storable#files
 +
:** <code>perl -MStorable -e 'print $Storable::VERSION,"\n";'</code> <!-- ivan #freeside -->
 +
:* Something's not running as freeside.
 +
:** Eg, the signup server script panics != freeside, returning 0 bytes of input back. Version appears <code>undef</code>, and doesn't match.
 +
:* The remote machine is not in the known hosts file <!-- http://www.freeside.biz/pipermail/freeside-users/2005-October/004795.html -->
 +
:** <code>ssh-keygen -F <em>hostname</em></code> no output means it's not foundDoes <b><em>not</em></b> verify known key compares.
 +
:* The ssh key used is either passphrase protected, or the key is not running in ssh-agent <!-- http://www.freeside.biz/pipermail/freeside-users/2005-October/004795.html -->
 +
:* Known or suspected issue with FreeBSD + Storable. Try FileCache instead. <!-- http://www.freeside.biz/pipermail/freeside-users/2005-October/004795.html -->
 +
 
 +
== I can't add the first service definition - the "Please wait, Server processing job..." popup comes up and nothing happens. ==
 +
:Make sure freeside-queued is running.
 +
 
 +
 
 +
= VMware appliance questions =
 +
 
 +
== What is the login for the VMware appliance? ==
 +
:For both the web interface and shell access:
 +
:Username: guest
 +
:Password: guest
 +
 
 +
== What is the root password for the VMware  appliance? ==
 +
:The guest user has sudo access
 +
 
 +
== How do I run the VMware appliance on ESX/ESXi/Server/VSphere ==
 +
:The stock demo is meant to be used with Player, Workstation or Fusion.
 +
 
 +
:However, you should be able to convert the disk type with VMware Converter or the command-line vmkfstools to a type recognized by ESX/ESXi/Server/VSphere.
  
:<nowiki>FreeBSD</nowiki> ports sometimes has trouble with perl and modules:
+
:Unfortunately, due to the way VMware disks work, we had to make a choice between a compressed image that would be small enough for people to use on their desktops or a large image compatible with ESX/ESXi/Server/VSphere/etc.
# <nowiki>IPC::ShareLite</nowiki> (used in selfservice for 1.5.x) may coredump.  Reported on <nowiki>FreeBSD</nowiki> 4 and 5 with various perl versions.  <i>Update: as of 1.5.7, "selfservice_server-session_module" configuration value can be set to "<nowiki>Cache::FileCache</nowiki>"  instead and <nowiki>IPC::ShareLite</nowiki> will not be necessary.</i>
 
# <nowiki>Storable</nowiki> may be broken due to the new "-D64bitint" flag that is compiled into perl.  Reported on <nowiki>FreeBSD</nowiki> 4.10 and perl 5.8.4.
 
  
;Q. "Host Key Verification Failed" errors, how do I resolve these?
+
= Upgrade Questions =
  
:This error occurs when freeside tries an unattended login via ssh.  The .ssh/known_hosts file on the freeside host must contain entries for the target host(s).  You must ssh into the target host as users root and freeside using the IP or hostname/fqdn specified in the export and/or server commands (passwd, sign-up, self-service).  You cannot have an IP based entry in the known_hosts file and then use a hostname for the exports etc., the verification will fail. Or you can change the sshd_config file directive <nowiki>IgnoreUserKnownHosts</nowiki> from no to yes.  But caution, this will expose your system to security threats if your keys are compromised.
+
== "Ticketing Main" / "RT at a glance" is empty ==
  
;Q. I cannot add a user account.  I see <nowiki>Error:</nowiki> Can't find svc_acct.domsvc in svc_domain.svcnum.  What do I do?
+
: Click the "Edit" button on the right, then click "Reset to defaults".
:Follow the directions in docs/admin.html exactly.  You have failed to "Add your own domain."  Create a package containing a svc_domain service.  Sell it to yourself. Provision it with your domain. Edit the service definition for the svc_acct service and set it to Default or Fixed and your domain.  ''Note: Freeside-setup in 1.7.X will have added the first domain already.''
+
: If nothing happens and it is still blank, run this command from the 1.7->1.9 upgrade and then try again:
 +
<pre>su freeside -c '/opt/rt3/sbin/rt-setup-database --action insert --datadir rt/etc/upgrade/3.5.1'</pre>
  
 
= Misc Questions =
 
= Misc Questions =
 +
 +
== freeside-daily warnings ==
  
 
;Q. freeside-daily emits warnings like:
 
;Q. freeside-daily emits warnings like:
Line 76: Line 110:
 
::No. These messages are harmless.
 
::No. These messages are harmless.
  
;Q. Isn't it insecure to use rsync?
+
;Q. freeside-daily emits warnings like:
:Sometimes.  But in the case of freeside, it uses rsync over ssh, so this is not a problem here. 
+
<pre>
 
+
    Use of uninitialized value in pattern match (m//) at /usr/share/perl5/Mail/Internet.pm line 535.
;Q. What's the purpose of the Session Server?
+
    Use of uninitialized value in sprintf at /usr/share/perl5/Mail/Internet.pm line 540.
:It records sessions (ie. login + logout, etc), so that the database can tell who is logged on at any given time. These days, most folks use a RADIUS server such as [http://www.freeradius.org/ FreeRADIUS] which includes an SQL session database instead of using the Freeside session server.
+
</pre>
 +
:;Should I be concerned?
 +
::No.
  
;Q. What's the purpose of the Self-Service Server and how does it work?
+
== What's the purpose of the Self-Service Server and how does it work? ==
 
:The Self-Service server is run on a separate, public box.  The Freeside server connects to it via SSH.  When a user comes to the Self-Service Server, he logs in and his username and password are authenticated against a Service (svc_acct) in a Package that is active for his Freeside customer record.  The Self-Service Server then gets a session ID which it uses in communicating with the Freeside server for purposes of working on this user's customer record.
 
:The Self-Service server is run on a separate, public box.  The Freeside server connects to it via SSH.  When a user comes to the Self-Service Server, he logs in and his username and password are authenticated against a Service (svc_acct) in a Package that is active for his Freeside customer record.  The Self-Service Server then gets a session ID which it uses in communicating with the Freeside server for purposes of working on this user's customer record.
  
 
:It is intended to provide, out of the box, a way to have users sign up for a package and cancel that package.  Recent additions have begun to make it possible also to add packages to an existing user and list those packages that user has purchased.  The Self-Service Server system comes with some ready-made CGIs that handle the most basic of these tasks for you.  The main thing to realize about it is that the customer must have a Package with a Service of type account set up with a username and password so that he may log in.
 
:It is intended to provide, out of the box, a way to have users sign up for a package and cancel that package.  Recent additions have begun to make it possible also to add packages to an existing user and list those packages that user has purchased.  The Self-Service Server system comes with some ready-made CGIs that handle the most basic of these tasks for you.  The main thing to realize about it is that the customer must have a Package with a Service of type account set up with a username and password so that he may log in.
  
;Q. Using Cisco NAS devices, RADIUS session history does not show IP addresses, and search by IP address does not work.  What's wrong?
+
:Current additions have also added additional capabilities including a web services and PHP API, an example VoIP-focused implementation with voicemail, CDRs, etc. in addition to the usual selfservice features.
 +
 
 +
== Using Cisco NAS devices, RADIUS session history does not show IP addresses, and search by IP address does not work.  What's wrong? ==
 
:Use the "<code>aaa accounting delay-start</code>" command on Cisco NAS devices to instruct them to report IP addresses to RADIUS.
 
:Use the "<code>aaa accounting delay-start</code>" command on Cisco NAS devices to instruct them to report IP addresses to RADIUS.
 +
 +
== HTML invoices have extra characters (typically boxes or diamond-shaped question marks).  What is the cause and how do I fix this? ==
 +
:Remove the Apache configuration directive <code>AddDefaultCharset UTF-8</code> from your configuration.  Note that on current Debian installs (4.0/etch) this may have been added as a default in /etc/apache2/conf.d/charset</code>.
 +
 +
== Why are some packages unavailable as a ''first package'' for a new customer? ==
 +
:Packages with no svc_acct or svc_phone services are ignored.  Add the customer without a first package, then use "Order New Package" on the customer view page.
 +
:Packages with more than one svc_acct or svc_phone service with quantity 1 need one of them set as the default service (it's a radio button during setup/configuring the package)
 +
:For signups, you can choose svc_acct (the default) or svc_phone by changing the <b>signup_server-service</b> configuration option.
 +
 +
== Is Freeside PCI Compliant? ==
 +
: It can be, but that mostly depends on how you set yours up individually.  What hardware you use, where your server is, who you allow access, how do any of your programs interact with freeside, and via what networks and protocols.  You need to setup and use [[Freeside:1.9:Documentation:Administration:Encrypted_Credit_Cards|encrypted credit cards]].
 +
: Freeside gives the tools necessary for its part, but much of PCI compliance is in your infrastructure.
 +
 +
== Does Freeside support PayPal? ==
 +
: PayPal Payflow Pro (their real merchant account product, acquired from Verisign) is supported and has been for ages.  This uses Business::OnlinePayment::PayflowPro.         
 +
 +
: PayPal redirection of the end-user browser is supported as of version 3.2
 +
 +
: PayPal DoDirectPayment (Business::OnlinePayment::PayPal) is not yet supported because of a bug in the Business::OnlinePayment::PayPal module.  See <https://rt.cpan.org/Public/Bug/Display.html?id=25259>.  This is possibly simple to fix, but I'm not aware of anyone that's tried and verified the module works properly with Freeside.
  
 
= Configuration Questions =
 
= Configuration Questions =
  
;Q. How do I set a minimum UID/GID?
+
== How do I set a minimum UID/GID? ==
 
:Edit /usr/local/etc/freeside/counters.[datasource]/svc_acct.uid .  This is Freeside-wide, not specific to any export driver.
 
:Edit /usr/local/etc/freeside/counters.[datasource]/svc_acct.uid .  This is Freeside-wide, not specific to any export driver.
  
;Q. How do I enable a second address (service/shipping address) in an existing database?</b>
+
== How do I setup prepaid packages? ==
:For 1.7.X, freeside-upgrade should enable shipping addresses automatically.
+
:Minimum verison 1.5.8 is required.
 +
 
 +
:To create a package with one hour of '''usage''', set "seconds" in the service definition to "default" and "3600", OR, use prepaid cards with the desired duration.  You also need to a usage-capable export setup (currently sqlradius, sqlradius_withdomain or radiator), and you need to make sure "freeside-sqlradius-radacctd" is running (uncomment the section that starts it in your init script).
 +
 
 +
:To create a pacakge with one week of '''availability''', set the package definition to the "Prepaid, flat rate" price plan, and set the Recurring fee frequence to "weekly".
 +
 
 +
:These can be used separately or together.
 +
 
 +
== How do I limit the type of credit-cards displayed on the sign-up form (and elsewhere)? ==
 +
 
 +
:* Go to the Configuration -> Settings page
 +
:* Click on Edit Configuration
 +
:* Click on the Billing section
 +
:* Edit the "card-types" configuration value  (make sure not to edit the cvv2-save configuration value by accident)
 +
:* On the Freeside machine, run "/etc/init.d/freeside restart"
 +
 
 +
== How do I reduce the width of HTML invoices (printing with IE8)? ==
 +
 
 +
:* Go to the Configuration -> Settings page
 +
:* Click on Edit Configuration
 +
:* Click on the Billing section
 +
:* Edit the "invoice_html" configuration value.
 +
:* About 13 lines down, edit the line that looks like this and change the <code>WIDTH=</code> to <code>625</code>:
 +
<pre>
 +
  <table class="invoice" bgcolor="#ffffff" WIDTH=768 CELLSPACING=8><tr><td>
 +
</pre>
 +
 
 +
= Really Old Questions =
 +
 
 +
== Is mod_perl version 2 (and 1.99) (and its associated Apache 2.x) officially supported by Freeside? ==
 +
:mod_perl version 2 (and 1.99) are supported.  Set APACHE_VERSION in the Makefile as appropriate.
 +
 
 +
== Using <nowiki>DBD::Pg 1.40</nowiki>, I receive an <code>Use of uninitialized value in die</code> or <code>syntax error at or near "$1"</code> error when running freeside-setup or after upgrading <nowiki>DBD::Pg</nowiki> ==
 +
:<nowiki>DBD::Pg 1.40</nowiki> has a grave bug (http://rt.cpan.org/NoAuth/Bug.html?id=12004) which causes these errors.  Please use 1.41 or later (1.32 is also okay).
 +
 
 +
== When building software prererquisites for Freeside, which combinations are known to break/fail? ==
 +
:Any: DBD::Pg 1.32 with DBI 1.42 fails "make test".  DBI 1.41 is ok.  ''Update: Test failures are harmless, DBI::Pg 1.32 works fine with DBI 1.42.''
 +
 
 +
:<nowiki>FreeBSD</nowiki> ports sometimes has trouble with perl and modules:
 +
# <nowiki>IPC::ShareLite</nowiki> (used in selfservice for 1.5.x) may coredump.  Reported on <nowiki>FreeBSD</nowiki> 4 and 5 with various perl versions.  <i>Update: as of 1.5.7, "selfservice_server-session_module" configuration value can be set to "<nowiki>Cache::FileCache</nowiki>"  instead and <nowiki>IPC::ShareLite</nowiki> will not be necessary.</i>
 +
# <nowiki>Storable</nowiki> may be broken due to the new "-D64bitint" flag that is compiled into perl.  Reported on <nowiki>FreeBSD</nowiki> 4.10 and perl 5.8.4.
 +
 
 +
== What's the purpose of the Session Server? ==
 +
:It records sessions (ie. login + logout, etc), so that the database can tell who is logged on at any given time.  These days, most folks use a RADIUS server such as [http://www.freeradius.org/ FreeRADIUS] which includes an SQL session database instead of using the Freeside session server.
 +
 
 +
== How do I enable a second address (service/shipping address) in an existing database? ==
 +
:For 1.7.X and later, freeside-upgrade should enable shipping addresses automatically.
  
 
:For older versions, apply the following changes to your database:
 
:For older versions, apply the following changes to your database:
Line 134: Line 237:
 
:And run <code>bin/dbdef-create</code> <i>username</i>.
 
:And run <code>bin/dbdef-create</code> <i>username</i>.
  
;Q. How do I setup prepaid packages?
+
== What should I do if a question in this section actually helped? ==
:Minimum verison 1.5.8 is required.
 
  
:To create a package with one hour of '''usage''', set "seconds" in the service definition to "default" and "3600", OR, use prepaid cards with the desired durationYou also need to a usage-capable export setup (currently sqlradius, sqlradius_withdomain or radiator), and you need to make sure "freeside-sqlradius-radacctd" is running (uncomment the section that starts it in your init script).
+
: Upgrade.  :)
 
 
:To create a pacakge with one week of '''availability''', set the package definition to the "Prepaid, flat rate" price plan, and set the Recurring fee frequence to "weekly".
 
 
 
:These can be used separately or together.
 
 
 
;Q. How do I limit the type of credit-cards displayed on the sign-up form (and elsewhere)?
 
 
 
:* Go to the Configuration -> Settings page
 
:* Click on Edit Configuration
 
:* Click on the Billing section
 
:* Edit the "card-types" configuration value  (make sure not to edit the cvv2-save configuration value by accident)
 
:* On the Freeside machine, run "/etc/init.d/freeside restart"
 

Latest revision as of 20:13, 20 January 2015

Contents

General Questions

What is Freeside's license?

As of Freeside 1.7.3, Freeside is licensed under the GNU Affero General Public License (AGPL), version three or later. Prior versions were licensed under the terms of the GNU General Public License (GPL), version two or later.
At your option, the client side of the self-service component (all files in fs_selfservice) may also be licensed under the GNU General Public License (GPL), version three or later.

What databases are supported by Freeside?

PostgreSQL 8.x+ is recommended.
MySQL/MariaDB v5+ is also supported again starting in Freeside v3.4. Sponsors or contributions for ongoing maintenance of the MySQL/MariaDB support are welcome.
Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running a different database than the backend.

How does Freeside compare to A2Billing?

Despite both projects doing "asterisk billing", they're actually more complimentary than overlapping. A2billing is an Asterisk-based soft-switch optimized for offering telephony services (specifically calling card, callback and wholesale services), while Freeside is a back-office customer database and customer portal with CDR processing, invoicing, taxation, reports, credit card processing, trouble ticketing, and so on.

Is there documentation elsewhere?

All documentation is in the wiki. Please help us improve it, that's why it is in a wiki!

Installation Questions

How do I avoid "Badly formed sub country data" errors from freeside-setup?

Before running freeside-setup, run:
   export LANG=C (sh, bash, zsh, etc. shells)
   setenv LANG C (csh or tcsh shell)

I'm trying to run Freeside on a VirtualHost, and I get "not running uid freeside" errors.

Your mod_perl-enabled Apache instance must run as user "freeside." This means that the entire server instance must be running as user "freeside," which is accomplished through a server-level User freeside directive. You cannot just put User freeside within a VirtualHost block (try running ps -auxwww and you'll see that the apache processes are owned by the server-level specified user, not the virtual host-level specified user).
Since "scripts" run under mod_perl are run in-process by the embedded perl interpreter and are not executed in a separate process as CGI scripts, you cannot use suEXEC to obtain a different username in VirtualHost context.
The recommended configuration is to run a separate, mod_perl-enabled Apache instance on a private, firewalled backend server, not on a public webserver.

My Apache logs say (or a command says): Can't locate <SomeModule>.pm in @INC (...)

Install the Perl module the error references. If the module is not listed in the installation instructions, edit the documentation and add it.

After installing mod_perl, my Apache logs say: [error] Can't locate Apache.pm in @INC (...)

Install Apache::Request

After installing mod_perl, my Apache logs say: "Can't locate mod_perl.pm in @INC" (...)

Include the path to mod_perl.pm by editing apachectl and specifying it.
An example is below (adjust to your needs):
-- near the top of apachectl --
PERL5LIB=$PERL5LIB:/more/paths/to/search:/directory/of/mod_perl:/even/more/places
export PERL5LIB
-- end of apachectl modifications --

"Host Key Verification Failed" errors, how do I resolve these?

This error occurs when freeside tries an unattended login via ssh. The .ssh/known_hosts file on the freeside host must contain entries for the target host(s). You must ssh into the target host as users root and freeside using the IP or hostname/fqdn specified in the export and/or server commands (passwd, sign-up, self-service). You cannot have an IP based entry in the known_hosts file and then use a hostname for the exports etc., the verification will fail. Or you can change the sshd_config file directive IgnoreUserKnownHosts from no to yes. But caution, this will expose your system to security threats if your keys are compromised.

I cannot add a user account. I see Error: Can't find svc_acct.domsvc in svc_domain.svcnum. What do I do?

Follow the directions in docs/admin.html exactly. You have failed to "Add your own domain." Create a package containing a svc_domain service. Sell it to yourself. Provision it with your domain. Edit the service definition for the svc_acct service and set it to Default or Fixed and your domain. Note: Freeside-setup in 1.7.X and later will have added the first domain already.

What's causing this error running the self-service client and server?

Magic number checking on storable file failed at ../../lib/Storable.pm (autosplit into ../../lib/auto/Storable/fd_retrieve.al) line 349, at ...
  • Mismatched versions of Storable.
  • Something's not running as freeside.
    • Eg, the signup server script panics != freeside, returning 0 bytes of input back. Version appears undef, and doesn't match.
  • The remote machine is not in the known hosts file
    • ssh-keygen -F hostname no output means it's not found. Does not verify known key compares.
  • The ssh key used is either passphrase protected, or the key is not running in ssh-agent
  • Known or suspected issue with FreeBSD + Storable. Try FileCache instead.

I can't add the first service definition - the "Please wait, Server processing job..." popup comes up and nothing happens.

Make sure freeside-queued is running.


VMware appliance questions

What is the login for the VMware appliance?

For both the web interface and shell access:
Username: guest
Password: guest

What is the root password for the VMware appliance?

The guest user has sudo access

How do I run the VMware appliance on ESX/ESXi/Server/VSphere

The stock demo is meant to be used with Player, Workstation or Fusion.
However, you should be able to convert the disk type with VMware Converter or the command-line vmkfstools to a type recognized by ESX/ESXi/Server/VSphere.
Unfortunately, due to the way VMware disks work, we had to make a choice between a compressed image that would be small enough for people to use on their desktops or a large image compatible with ESX/ESXi/Server/VSphere/etc.

Upgrade Questions

"Ticketing Main" / "RT at a glance" is empty

Click the "Edit" button on the right, then click "Reset to defaults".
If nothing happens and it is still blank, run this command from the 1.7->1.9 upgrade and then try again:
su freeside -c '/opt/rt3/sbin/rt-setup-database --action insert --datadir rt/etc/upgrade/3.5.1'

Misc Questions

freeside-daily warnings

Q. freeside-daily emits warnings like
     WARNING:  Skipping "pg_group" --- only table or database owner can VACUUM it
Should I be concerned?
No. These messages are harmless.
Q. freeside-daily emits warnings like
     Use of uninitialized value in pattern match (m//) at /usr/share/perl5/Mail/Internet.pm line 535.
     Use of uninitialized value in sprintf at /usr/share/perl5/Mail/Internet.pm line 540.
Should I be concerned?
No.

What's the purpose of the Self-Service Server and how does it work?

The Self-Service server is run on a separate, public box. The Freeside server connects to it via SSH. When a user comes to the Self-Service Server, he logs in and his username and password are authenticated against a Service (svc_acct) in a Package that is active for his Freeside customer record. The Self-Service Server then gets a session ID which it uses in communicating with the Freeside server for purposes of working on this user's customer record.
It is intended to provide, out of the box, a way to have users sign up for a package and cancel that package. Recent additions have begun to make it possible also to add packages to an existing user and list those packages that user has purchased. The Self-Service Server system comes with some ready-made CGIs that handle the most basic of these tasks for you. The main thing to realize about it is that the customer must have a Package with a Service of type account set up with a username and password so that he may log in.
Current additions have also added additional capabilities including a web services and PHP API, an example VoIP-focused implementation with voicemail, CDRs, etc. in addition to the usual selfservice features.

Using Cisco NAS devices, RADIUS session history does not show IP addresses, and search by IP address does not work. What's wrong?

Use the "aaa accounting delay-start" command on Cisco NAS devices to instruct them to report IP addresses to RADIUS.

HTML invoices have extra characters (typically boxes or diamond-shaped question marks). What is the cause and how do I fix this?

Remove the Apache configuration directive AddDefaultCharset UTF-8 from your configuration. Note that on current Debian installs (4.0/etch) this may have been added as a default in /etc/apache2/conf.d/charset</code>.

Why are some packages unavailable as a first package for a new customer?

Packages with no svc_acct or svc_phone services are ignored. Add the customer without a first package, then use "Order New Package" on the customer view page.
Packages with more than one svc_acct or svc_phone service with quantity 1 need one of them set as the default service (it's a radio button during setup/configuring the package)
For signups, you can choose svc_acct (the default) or svc_phone by changing the signup_server-service configuration option.

Is Freeside PCI Compliant?

It can be, but that mostly depends on how you set yours up individually. What hardware you use, where your server is, who you allow access, how do any of your programs interact with freeside, and via what networks and protocols. You need to setup and use encrypted credit cards.
Freeside gives the tools necessary for its part, but much of PCI compliance is in your infrastructure.

Does Freeside support PayPal?

PayPal Payflow Pro (their real merchant account product, acquired from Verisign) is supported and has been for ages. This uses Business::OnlinePayment::PayflowPro.
PayPal redirection of the end-user browser is supported as of version 3.2
PayPal DoDirectPayment (Business::OnlinePayment::PayPal) is not yet supported because of a bug in the Business::OnlinePayment::PayPal module. See <https://rt.cpan.org/Public/Bug/Display.html?id=25259>. This is possibly simple to fix, but I'm not aware of anyone that's tried and verified the module works properly with Freeside.

Configuration Questions

How do I set a minimum UID/GID?

Edit /usr/local/etc/freeside/counters.[datasource]/svc_acct.uid . This is Freeside-wide, not specific to any export driver.

How do I setup prepaid packages?

Minimum verison 1.5.8 is required.
To create a package with one hour of usage, set "seconds" in the service definition to "default" and "3600", OR, use prepaid cards with the desired duration. You also need to a usage-capable export setup (currently sqlradius, sqlradius_withdomain or radiator), and you need to make sure "freeside-sqlradius-radacctd" is running (uncomment the section that starts it in your init script).
To create a pacakge with one week of availability, set the package definition to the "Prepaid, flat rate" price plan, and set the Recurring fee frequence to "weekly".
These can be used separately or together.

How do I limit the type of credit-cards displayed on the sign-up form (and elsewhere)?

  • Go to the Configuration -> Settings page
  • Click on Edit Configuration
  • Click on the Billing section
  • Edit the "card-types" configuration value (make sure not to edit the cvv2-save configuration value by accident)
  • On the Freeside machine, run "/etc/init.d/freeside restart"

How do I reduce the width of HTML invoices (printing with IE8)?

  • Go to the Configuration -> Settings page
  • Click on Edit Configuration
  • Click on the Billing section
  • Edit the "invoice_html" configuration value.
  • About 13 lines down, edit the line that looks like this and change the WIDTH= to 625:
  <table class="invoice" bgcolor="#ffffff" WIDTH=768 CELLSPACING=8><tr><td>

Really Old Questions

Is mod_perl version 2 (and 1.99) (and its associated Apache 2.x) officially supported by Freeside?

mod_perl version 2 (and 1.99) are supported. Set APACHE_VERSION in the Makefile as appropriate.

Using DBD::Pg 1.40, I receive an Use of uninitialized value in die or syntax error at or near "$1" error when running freeside-setup or after upgrading DBD::Pg

DBD::Pg 1.40 has a grave bug (http://rt.cpan.org/NoAuth/Bug.html?id=12004) which causes these errors. Please use 1.41 or later (1.32 is also okay).

When building software prererquisites for Freeside, which combinations are known to break/fail?

Any: DBD::Pg 1.32 with DBI 1.42 fails "make test". DBI 1.41 is ok. Update: Test failures are harmless, DBI::Pg 1.32 works fine with DBI 1.42.
FreeBSD ports sometimes has trouble with perl and modules:
  1. IPC::ShareLite (used in selfservice for 1.5.x) may coredump. Reported on FreeBSD 4 and 5 with various perl versions. Update: as of 1.5.7, "selfservice_server-session_module" configuration value can be set to "Cache::FileCache" instead and IPC::ShareLite will not be necessary.
  2. Storable may be broken due to the new "-D64bitint" flag that is compiled into perl. Reported on FreeBSD 4.10 and perl 5.8.4.

What's the purpose of the Session Server?

It records sessions (ie. login + logout, etc), so that the database can tell who is logged on at any given time. These days, most folks use a RADIUS server such as FreeRADIUS which includes an SQL session database instead of using the Freeside session server.

How do I enable a second address (service/shipping address) in an existing database?

For 1.7.X and later, freeside-upgrade should enable shipping addresses automatically.
For older versions, apply the following changes to your database:
     ALTER TABLE cust_main ADD COLUMN ship_last varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_first varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_company varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_address1 varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_address2 varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_city varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_county varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_state varchar(80) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_zip varchar(10) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_country char(2) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_daytime varchar(20) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_night varchar(20) NULL;
     ALTER TABLE cust_main ADD COLUMN ship_fax varchar(12) NULL;
     CREATE INDEX cust_main4s ON cust_main ( ship_last );
     CREATE INDEX cust_main5s ON cust_main ( ship_company );
     ALTER TABLE h_cust_main ADD COLUMN ship_last varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_first varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_company varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_address1 varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_address2 varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_city varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_county varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_state varchar(80) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_zip varchar(10) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_country char(2) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_daytime varchar(20) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_night varchar(20) NULL;
     ALTER TABLE h_cust_main ADD COLUMN ship_fax varchar(12) NULL;
     CREATE INDEX h_cust_main4s ON h_cust_main ( ship_last );
     CREATE INDEX h_cust_main5s ON h_cust_main ( ship_company );
And run bin/dbdef-create username.

What should I do if a question in this section actually helped?

Upgrade.  :)