Freeside - User contributions [en]

Freeside:2.3:Documentation:Installation

2012-11-18T22:44:16Z

Builder: /* Common modules not common but necessary on CentOS/RedHat */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== Common modules not common but necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]
* [http://search.cpan.org/dist/IPC::Run::SafeHandles IPC::Run::SafeHandles]
* [http://search.cpan.org/dist/DateTime::Set DateTime::Set]
* [http://search.cpan.org/dist/POE POE]
* [http://search.cpan.org/dist/Sys::SigAction Sys::SigAction]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:2.3:Documentation:Installation

2012-11-18T22:43:52Z

Builder: /* Common modules not common but necessary on CentOS/RedHat */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== Common modules not common but necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]
* [http://search.cpan.org/dist/IPC::Run::SafeHandles IPC::Run::SafeHandles]
* [http://search.cpan.org/dist/DateTime::Set DateTime::Set]
* [http://search.cpan.org/dist/POE POE]
* [http://search.cpan.org/dist/POE Sys::SigAction Sys::SigAction]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:2.3:Documentation:Installation

2012-11-18T22:30:19Z

Builder: /* Common modules not common but necessary on CentOS/RedHat */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== Common modules not common but necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]
* [http://search.cpan.org/dist/IPC::Run::SafeHandles IPC::Run::SafeHandles]
* [http://search.cpan.org/dist/DateTime::Set DateTime::Set]
* [http://search.cpan.org/dist/POE POE]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:2.3:Documentation:Installation

2012-11-18T21:22:24Z

Builder: /* Common modules not common but necessary on CentOS/RedHat */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== Common modules not common but necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]
* [http://search.cpan.org/dist/IPC::Run::SafeHandles IPC::Run::SafeHandles]
* [http://search.cpan.org/dist/DateTime::Set DateTime::Set]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:2.3:Documentation:Installation

2012-11-18T20:58:16Z

Builder: /* necessary on CentOS/RedHat */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== Common modules not common but necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:2.3:Documentation:Installation

2012-11-18T20:57:13Z

Builder: /* Common modules */

== Introduction ==

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

== Prerequisites ==

=== Packages ===

* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl]
** If compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v8.1 or later recommended).
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

''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.''

* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

=== Perl modules ===

==== Popular modules ====

These modules are included in most distributions.


* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
** [http://search.cpan.org/dist/URI URI]
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
* [http://search.cpan.org/dist/DateManip Date::Manip]

==== Common modules ====

These modules are included in many distributions.


* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
* [http://search.cpan.org/dist/DateTime DateTime]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
* [http://search.cpan.org/dist/Number-Format Number::Format]
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
* [http://search.cpan.org/dist/Text-Template Text::Template]

===== necessary on CentOS/RedHat =====
* [http://search.cpan.org/dist/HTML::TableExtract HTML::TableExtract]
* [http://search.cpan.org/dist/HTML::ElementTable HTML::ElementTable]
* [http://search.cpan.org/dist/IO::Scalar IO::Scalar]
* [http://search.cpan.org/dist/Geo::GoogleEarth::Pluggable Geo::GoogleEarth::Pluggable]
* [http://search.cpan.org/dist/XML::LibXML XML::LibXML]
* [http://search.cpan.org/dist/XML::LibXML::LazyBuilder XML::LibXML::LazyBuilder]
* [http://search.cpan.org/dist/Geo::Coder::Googlev3 Geo::Coder::Googlev3]
* [http://search.cpan.org/dist/GD::Barcode GD::Barcode]
* [http://search.cpan.org/dist/Net::OpenSSH Net::OpenSSH]
* [http://search.cpan.org/dist/Net::SNMP Net::SNMP]
* [http://search.cpan.org/dist/SOAP::Lite SOAP::Lite]
* [http://search.cpan.org/dist/XML::Simple XML::Simple]
* [http://search.cpan.org/dist/Date::Simple Date::Simple]

==== Additional modules ====



* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
* [http://search.cpan.org/dist/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
* [http://search.cpan.org/dist/JSON JSON]
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
* [http://search.cpan.org/dist/Time-Duration Time::Duration]

==== Optional modules ====

* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''

==== Note on missing modules ====

Prerequisites missing from the documentation? Please add them.

== Download Freeside ==
* Get the source from one of the normal places
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous git]
* Uncompress the tarball

== Installation ==

=== System User ===
* Add the user and group `freeside' to your system.
=== Database User ===
* Allow the freeside user full access to the freeside database.
with Postgresql:
<pre>
[ as postgres/pgsql user ]
$ createuser -P freeside
Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
</pre>
or with MySQL:
<pre>
$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</pre>
=== Database Access ===
*Edit the top-level Makefile:
** Configure the DATASOURCE to your DBI data source
*** Set the DB_TYPE (Pg or mysql)
*** See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
** Set DB_PASSWORD to the freeside database user's password.

=== Database ===
* Add the freeside database to your database engine:
with Postgres:
<pre>
$ su freeside
$ createdb -E UTF8 freeside
</pre>
or with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside
</pre>

=== Perl Modules ===
* Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules
</pre>
=== Basic configuration Files ===
* Create the necessary configuration files:
<pre>
$ su
# make create-config
</pre>

=== Invoice Typesetting ===
* If you are using typeset invoices, install fslongtable.sty:
<pre>
$ su
# make install-texmf
</pre>

=== Apache & Web GUI ===
* Configuration
** Enable mod_perl
** Run as <code>User freeside</code>
*** If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a '''separate''' iteration of Apache as the freeside user.

* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.

* To install the web interface, run:
<pre>
$ su
# make install-docs
</pre>

* Edit the Makefile and set <code>APACHE_VERSION</code> to '''1''' (mod_perl v1.XX), '''1.99''' (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or '''2''' (mod_perl v2 proper and prereleases 1.999_22 and later).

* Edit the Makefile and set <code>APACHE_CONF</code> to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)

* To install the apache configs, run:
<pre>
$ su
# make install-apache
</pre>

''Note: Do not attempt to restart Apache (httpd) yet.''

=== Initialize Data ===
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
<pre>
$ su freeside
$ freeside-setup -d example.com
</pre>

=== Additional System Users ===
* Create the Freeside system users:
<pre>
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
</pre>

=== Create Freeside Users ===
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
<pre>
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:
</pre>
Additional users can be added using the same command or from the web interface.

=== Queue Daemon ===

* freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)

=== RT ===
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.

<pre>
su freeside
psql freeside
delete from conf where name = 'ticket_system';
</pre>

=== Finalize ===
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.

* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Freeside:1.9:Documentation:Administration

2010-10-13T00:52:44Z

Builder: /* Manually setting next invoice number sequence */

= Exports (provisioning) =

'''Exports''' allow you to provision services to remote machines, databases and APIs. Some exports, such as ''sqlradius'' and ''sqlradius_withdomain'', enable a feed for retrieving rating/usage data.

Exports can be added and edited under
: Configuration -> Provisioning, services and packages -> View/edit exports

Most exports place jobs in the job queue for new, modified or deleted services. Jobs are run by [[Freeside:1.9:Documentation:Developer/bin/freeside-queued|freeside-queued]]. This daemon needs to be running before exports are acted upon.

Some exports use SSH, SCP or SFTP to communicate with external machines. See the documentation on [[Freeside:1.9:Documentation:Administration:SSH_Keys|SSH keys]].

Click on ''Add a new export'' to create a new export. Select exports from the dropdown to show more information on each export, including available options, setup and usage.

Exports are activated by associating them with one or more '''service definitions'''.

Following is a list of which exports can be associated with each type of service.

==svc_acct==
* [[Freeside:1.9:Documentation:Administration:acct_plesk.pm|acct_plesk.pm]]: Real-time export to Plesk managed mail service
* acct_sql.pm: Real-time export of accounts to SQL databases .
* artera_turbo.pm:
* bsdshell.pm:
* [[Freeside:1.9:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* communigate_pro_singledomain.pm:
* cpanel.pm: Real-time export to Cpanel control panel.
* cp.pm: Real-time export to Critical Path Account Provisioning Protocol
* cyrus.pm: Real-time export to Cyrus IMAP server
* everyone_net.pm: Real-time export to Everyone.net outsourced mail service
* infostreet.pm: Real-time export to InfoStreet streetSmartAPI
* [[Freeside:1.9:Documentation:Administration:ldap.pm|ldap.pm]]: Real-time export to LDAP
* passwdfile.pm:
* radiator.pm: Real-time export to RADIATOR
* shellcommands.pm:
* shellcommands_withdomain.pm: Real-time export via remote SSH (vpopmail, ISPMan)
* sqlmail.pm: Real-time export to SQL-backed mail server
* sqlradius.pm: Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS)
* sqlradius_withdomain.pm: Real-time export to SQL-backed RADIUS (FreeRADIUS, ICRADIUS) with realms
* sysvshell.pm:
* textradius.pm:
* vpopmail.pm: Real-time export to vpopmail text files

==svc_domain==
* bind.pm: Batch export to BIND named
* bind_slave.pm: Batch export to slave BIND named
* [[Freeside:1.9:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* domain_shellcommands.pm: Run remote commands via SSH, for domains (qmail, ISPMan).
* domain_sql.pm: Real time export of domains to SQL databases .
* http.pm: Send an HTTP or HTTPS GET or POST request
* [[Freeside:1.9:Documentation:Administration:opensrs.pm|opensrs.pm]]: OpenSRS integration
* sqlmail.pm: Real-time export to SQL-backed mail server

==svc_forward==
* artera_turbo.pm:
* [[Freeside:1.9:Documentation:Administration:communigate_pro.pm|communigate_pro.pm]]: Real-time export to a CommuniGate Pro mail server
* forward_shellcommands.pm: Run remote commands via SSH, for forwards
* postfix.pm: Postfix text files
* sqlmail.pm: Real-time export to SQL-backed mail server

==svc_www==
* apache.pm: Export an Apache httpd.conf file snippet.
* [[Freeside:1.9:Documentation:Administration:www_plesk.pm|www_plesk.pm]]: Real-time export to Plesk managed hosting service
* www_shellcommands.pm: Run remote commands via SSH, for virtual web sites (directory maintenance, FrontPage, ISPMan)

==svc_broadband==
* nas_wrapper.pm: A meta-export that triggers other svc_broadband exports.
* [[Freeside:1.9:Documentation:Administration:prizm.pm|prizm.pm]]: Real-time export to Northbound Interface
* router.pm: Send a command to a router.
* snmp.pm: Sends SNMP SETs to an SNMP agent.
* trango.pm: Sends SNMP SETs to a Trango AP.

==svc_phone==
* globalpops_voip.pm:
* grandstream.pm: Grandstream phone and ATA provisioning. This [http://www.freeside.biz/blog/?p=11 blog article] is a start at documentation.
* indosoft.pm:
* internal_diddb.pm:
* netsapiens.pm:
* phone_shellcommands.pm:
* phone_sqlradius.pm:
* thirdlane.pm:
* vitelity.pm:

==svc_external==
* artera_turbo.pm:

= Services =

== Accounts (svc_acct) ==

* [[Freeside:1.9:Documentation:Administration:svc_acct:_password_encoding|Password encoding in 1.9]]

== Domains (svc_domain) ==

== Forwards (svc_forward) ==

== Hosting (svc_www) ==

== Broadband (svc_broadband) ==

== Phone (svc_phone) ==

== External (svc_external) ==

= Packages =

{{Freeside:1.9:Documentation:Administration:pkg_category}}

== Price Plans ==

=== Common price plans ===

* flat
* subscription
* prorate
* sqlradacct_hour
* voip_cdr
* prepaid

=== Wholesale price plans ===

* bulk

* [[Freeside:1.9:Documentation:Administration:Packages:Price_Plans:agent | agent]]
* [[Freeside:1.9:Documentation:Administration:Packages:Price_Plans:cdr_termination |
cdr_termination ]]

=== Other price plans ===

* flat_delayed
* flat_introrate
* prorate_delayed

* base_delayed
* base_rate

* sql_external
* sql_generic

=== Price plans of questionable functionality ===

* flat_comission_cust
* flat_comission_pkg
* flat_comission

* voip_sqlradacct

* sesmon_hour
* sesmon_minute

== Misc ==

* Some notes on [[Freeside:1.9:Documentation:Administration:Upselling | Upselling]]

= Resellers =

= Employees =

== Employees ==

Go to Configuration -> Employees -> Employees to view the existing employees and add new ones. It is highly recommended to add a separate account for each person rather than using role accounts.

* To add a new employee, click on "Add an employee"
* Or to edit an existing group, click on the employee number or name in the list of employees.
* Enter or edit the username, password and name. If editing an existing employee and no password change is desired, the password fields can be left blank.
* Check the "Disable employee" box to disable this employee.
* In the "Employee groups" section, mark or unmark checkboxes to indicate the access groups for this employee.

== Employee groups and access control ==

To setup employee access control or agent/reseller virtualization, you need to setup employee groups. Go to Configuration -> Employees -> Employee groups to view the existing groups and add new ones. The system starts with a "Superuser" group which has access to all functionality for the first agent.

* To add a new group, click on "Add an employee group"
* Or to edit an existing group, click on the group number or name in the list of groups.
* Enter or edit the group name.
* In the "Group limited to these agent(s)" section, mark checkboxes next to the agents this employee group should be able to see. Employees in this group will only see customers of the selected agents in the system and reports.
* In the "Group access rights" section, mark or unmark checkboxes to indicate the access rights this employee group should have. Rights marked with an "*" are global rights which provide access to global data which is shared among all agents. Their use is not recommended for groups which are limited to a subset of agents.
* After adding a new group, don't forget to go back and add or edit employees to place them into the new group.

= Billing =

== Billing events ==
Billing events are the primary mechanism to implement your business rules. Rules such as resend invoices, retry cards, suspend or cancel accounts for non-payment, etc. are all handled by billing events.

At a high level, follow the following steps to create billing events:
* Add a new Billing Event (Configuration > Billing > Billing events)
* Name the event
* Choose the type of event:
** Package - Packages and associated dates (Including Commissions)
** Invoice - Invoice status and dates
** Customer - Customer Balances and Information
** Batch Payment - Batch payment results
** Statement - Send statement
* Choose whether to apply to one or all agents
* Choose the frequency for the system to check and see if the event should run.
* Choose appropriate filters.
* Choose appropriate actions.

The form is dynamic so changing the type of event will change the available filters and actions.

== Daily and Monthly Scripts ==
* The freeside-daily script should be run daily to bill customers and run invoice collection events.
** Typically, this is accomplished with an entry in the freeside user's crontab such as: <pre>0 0 * * * /usr/local/bin/freeside-daily</pre>
** If running freeside-daily manually, ensure the <code>TZ</code> variable is set to your timezone with a command such as: <pre>TZ="US/Pacific" freeside-daily fs_daily</pre>
* If any monthly events are enabled, the freeside-monthly script should be run monthly.
* Invoice events can also be used to implement agent-virtualized invoices. (add more info)

== Invoices ==

=== Typeset (LaTeX) invoice templates ===

==== Prerequisites ====

* Almost all distributions include the necessary prerequisites listed here, manual installation is practically never necessary.
* Install [http://www.ghostscript.com/ Ghostscript] (gs)
* Install [http://www.tug.org/tetex/ teTeX] or [http://www.tug.org/texlive/ TeX Live]
* Ensure that the <code>pslatex</code>, <code>dvips</code>, and <code>pdflatex</code> command line utilities were installed

==== Logo setup ====

The <em title="Encapsulated Postscript">EPS</em> logo is for PDF and printed invoices.

* For best results, save a '''vector format''' logo in EPS (Encapsulated PostScript) format.
** Your graphic artist can create vector image from a bitmap (tracing etc).
** Converting a bitmap such as a JPG can work (the bigger the better), but it may render in lower quality, blurry or with the "jaggies" (especially when actually printed, not just viewed as a PDF)
* Resize the logo to 90pt X 36pt: <code>epsffit -c 0 0 90 36 yourlogo.eps >logo.eps</code>
* Upload the resized logo as the <code>logo.eps</code> configuration option.
* Problems? Try <code>bin/strip-eps <oldlogo.eps >trynewlogo.eps</code>

The <em title="Portable Network Graphic">PNG</em> logo is for emailed and online invoices.

Freeside ships with a logo of 92 x 62. Any logo close to this size should work with the default HTML template.

{{Freeside:1.9:Documentation:Administration:invoice_layout}}

=== HTML invoice templates ===

* Convert your logo to PNG format and upload it as the <code>logo.png</code> configuration option.
{{Freeside:1.9:Documentation:Administration:invoice_templates|format=html}}

=== Plaintext invoice templates ===

* See the Text::Template documentation for details on the substitution language.
* You must call the invoice_lines() function at least once - pass it a number of lines, and it returns a list of array references, each of two elements: a service description column, and a price column. Alternatively, call invoice_lines() with no arguments, and pagination will be disabled - all invoice line items will print on one page, with no padding (recommended for email invoices).
* Descriptions of variables are available in [[Freeside:1.9:Documentation:Template:invoice_html|invoice_html]]

=== Misc ===

==== Manually setting next invoice number sequence ====

* With PostgreSQL, to number invoices starting at 5000: <pre>SELECT SETVAL(cust_bill_invnum_seq, 4999);</pre>
* With MySQL you must change the auto_increment value for the cust_bill table. For example, to number invoices starting at 5000:
<pre>
[root@system ~]# mysql freeside -u root -p
Enter password:
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 289
Server version: 5.0.77 Source distribution

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> ALTER TABLE cust_bill AUTO_INCREMENT = 5000;
Query OK, 1 row affected (0.03 sec)
Records: 1 Duplicates: 0 Warnings: 0

mysql> quit
Bye
[root@system ~]#
</pre>

== Payment Receipts ==

The [[Freeside:1.9:Documentation:Template:payment_receipt_email|payment_receipt_email]] template is used for manually applied payments.

== Credit cards and Electronic checks ==
* [[Freeside:1.9:Documentation:Administration:Real-time_Processing | Real-time credit card and electronic check processing]]
* [[Freeside:1.9:Documentation:Administration:Batch_Processing | Batch credit card and electronic check processing]]
* Credit card expiration alerts: Customize the ''alerter_template'' configuration option and run <code>freeside-expiration-alerter</code> daily.
* Credit card decline alerts: Customize the ''declinetemplate'' configuration option and set the ''emaildecline'' configuration option.

= Misc =

* Setting up [[Freeside:1.9:Documentation:Administration:Encrypted Credit Cards | Encrypted Credit Cards]]
* Setting up [[Freeside:1.9:Documentation:Administration:Texas Tax | Texas Tax]]
* Setting up [[Freeside:1.9:Documentation:Administration:VoIP | VoIP]]

* Setting up [[Freeside:1.9:Documentation:Administration:Commission|Commissions and Referrals]]
* Need to print to Windows printers? Follow steps 1-4 of [http://iharder.sourceforge.net/current/macosx/winmacprinter/ Share Your Windows Printer].
* Setting up [[Freeside:1.9:Documentation:Administration:Slony | Slony replication and failover]]
* Using a non-standard [[Freeside:1.9:Documentation:Administration:PostgreSQL_Schema | PostgreSQL Schema]]

{{ContextSensitiveHelp}}