These instructions were derived from the official Freeside installation documentation but have been updated to help provide an error-free installation.
These instructions have only been tested with Debian 10.
I try to keep this documentation up to date but we all need to keep the lights on so if you find this useful I would much appreciate it if you could leave a donation.
Table of Contents
Prep the system for Install
Install Debian 9 on your server using a single filesystem for all files and only choose the ssh server option when prompted for task selection.
These steps will get apt configured and install a few packages to help smooth out the process
Add Freeside Apt Repositories
Edit /etc/apt/sources.list.d/freeside.list and add the following entries:
deb [trusted=yes] http://pkg.freeside.biz/freeside-buster/ ./
deb [trusted=yes] http://pkg.freeside.biz/freeside4-stretch-testing/ ./
Update apt and system
sudo apt update; sudo apt upgrade
Install some preliminary packages
sudo apt install exim4- exim4-base- exim4-config- exim4-daemon-light- fdutils- hotplug- ppp- pppconfig- pppoe- pppoeconf- tasksel- tasksel-data- task-ssh-server- doc-debian- debian-faq- ibritish- procmail- mutt- inetutils-inetd- task-english- adduser diffutils grep gzip hostname less lftp lsof nano nmap nvi passwd procps psmisc rsync screen openssh-client openssh-server strace sudo tar telnet traceroute zsh ssmtp
Install Missing Perl Library
libparams-classify-perl still needs to be installed and held at 0.013-5.3 but is not in the official Freeside Buster repository. Follow these steps to download it from my server, install it, and then hold it in place so it doesn’t get squashed during upgrades.
wget https://www.spectrumbt.net/support_files/libparams-classify-perl_0.013-5.3_all.deb
sudo dpkg -i libparams-classify-perl_0.013-5.3_all.deb
sudo apt-mark hold libparams-classify-perl
Install and Bootstrap Freeside
Now that the system is prepared we are ready to install the actual Freeside software and bootstrap the initial users
Install Freeside
sudo apt install freeside freeside-lib freeside-webui liblocale-subcountry-perl=1.63-1 libev-perl- texlive-fonts-recommended-doc- texlive-latex-base-doc- texlive-latex-extra-doc- texlive-latex-recommended-doc- texlive-pictures-doc- texlive-pstricks-doc-
note: If errors are encountered about package versions use apt-cache to determine the proper version number of the package and make the necessary adjustments.
Create the database user
sudo -u postgres createuser -d freeside
Create the freeside database
sudo -u freeside createdb -E UTF8 freeside
Initialize the freeside database
(replace the domain example.com with your companies domain. This will be used as the initial domain for the system and Ticketing)
sudo -u freeside freeside-setup -d example.com
Initialize the RT tables
sudo su freeside -c '/opt/rt3/sbin/rt-setup-database --action schema; /opt/rt3/sbin/rt-setup-database --action coredata; /opt/rt3/sbin/rt-setup-database --action insert --datafile /opt/rt3/etc/initialdata'
When prompted for a password just press enter
Create the Freeside system users
Create a shell script fsusers.sh
vi fsusers.sh
Paste this in the file and save
#!/bin/bash
for u in fs_queue fs_daily fs_selfservice fs_api; do
printf "Creating user $u\n"
freeside-adduser -g 1 $u
printf "\n"
done
Run the script as the freeside user
chmod +x fsusers.sh; sudo -u freeside ./fsusers.sh
Create your user
(Use a temporary password and reset it to your secure password in the UI as this will be in plain text and could be hacked later on)
sudo -u freeside freeside-adduser -g 1 username password
Configure Apache
The user and group Apache runs as needs to be changed to the freeside user as well as enabling the Freeside configuration files and a few modules.
sudo sed -i 's/APACHE_RUN_USER=www-data/APACHE_RUN_USER=freeside/' /etc/apache2/envvars
sudo sed -i 's/APACHE_RUN_GROUP=www-data/APACHE_RUN_GROUP=freeside/' /etc/apache2/envvars
sudo a2enconf freeside-base2.4 freeside-rt
sudo a2dismod mpm_event
sudo a2enmod mpm_prefork rewrite perl ssl
sudo a2ensite default-ssl
sudo chown freeside /var/lock/apache2
Redirect insecure connections to https
Add rewrite directives
sudo vi /etc/apache2/sites-available/000-default.conf
Paste the following directives above the closing VirtualHost directive </VirtualHost>
RewriteEngine on
RewriteCond %{SERVER_PORT} ^80$
RewriteCond %{REMOTE_ADDR} !^127.0.0.1$
RewriteCond %{REMOTE_ADDR} !^\:\:1$
RewriteRule ^/(.*)$ https://%{SERVER_NAME}/ [L,R]
Start up freeside and restart apache
sudo /etc/init.d/freeside start
sudo systemctl restart apache2
Extra modifications for PCI Compliance
If you will be processing credit cards then you will have to go through the process of being and maintaining PCI Compliance.
In most cases, you can prevent any PCI issues with the Freeside backend server by keeping it locked away behind a firewall and only allowing access via IP filters or VPN, which is the preferred method.
However, if you need to have the Freeside backend UI available to the world at large, here are a few modifications that can help you pass a PCI Scan.
Valid SSL Certificate
By default, Apache has a self-signed SSL certificate that while it is secure it is not acceptable for use when it comes to PCI Compliance.
You can solve this by purchasing an SSL Certificate from a valid source or using LetsEncrypt which will provide you with one at no cost.
Change Apache's Behavior
Apache will give out a lot of information that can be used to determine if a site is vulnerable to attack and which one would have the most impact. You can help make an attackers job much harder by making a few modifications to Apache.
Modify security.conf
In your favorite editor open /etc/apache2/conf-available/security.conf and set the following directives:
ServerTokens Prod
ServerSignature Off
Scroll to the bottom of the file and add the following:
# Add Security Headers
<IfModule mod_headers.c>
# Protect against XSS attacks
Header set X-XSS-Protection "1; mode=block"
Header set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
</IfModule>
Save and close the file, then enable mod_headers and restart apache
sudo a2enmod headers
sudo systemctl restart apache2
Prevent showing files at the root level
Though Freeside disables indexing for the freeside directory the root is still left open and this will cause a PCI Scan to fail.
This is easily remedied by adding a couple of directives to the main apache configuration file.
- Open /etc/apache2/apache2.conf
- Find the Directory entry for /
- Add -Indexes to the Options
- Find the Directory entry for /var/www
- In the Options change Indexes to -Indexes
- Save and close the file
- Restart apache (see commands above)
Thank You
A big thank you goes to the Freeside team for creating this software and the initial Documentation as well as the freeside-users mailing list for providing additional information that helped create this document.