From SIPfoundry sipx, The Open Source SIP PBX for Linux - Calivia

Installing sipX 3.4 on Debian Sarge

Below is a step-by-step guide on how to install Debian Sarge as well as sipX 3.4.0 sipX Runtime and Build Dependencies.

The SIPfoundry site provides a list of features, sipX roadmap, screenshots, as well as an architecture discussion.

Note: You are encouraged to report bugs to the project's Jira Tracker.

For up-to-date information on new releases subscribe here.

Redundant High-Availability Installation

Introduced in release 3.2 the sipX PBX system implements a distributed system offering high-availability and fail-over redundancy for the entire sipX call control system. In release 3.2 a single instance of the Configuration Server (sipXconfig) manages two sipX servers. Under normal operating conditions the two servers load-balance using DNS SRV records, which doubles overall system performance. The registration and other state information is replicated and synchronized with the other server in real-time, so that from a user perspective the two servers look like one big system. Release 3.4 adds support for CDR recording, including HA support for CDR data collection.

Installation & configuration of a redundant system still requires some manual steps in release 3.2 / 3.4. We expect this to be fully automated and integrated into Config Server by the next release. Please consult the high-availability install & configuration guide if you want to use the high-availability / redundancy capabilities of sipX. A High-Availability Failure and Recovery Analysis is available too.

The Design Documentation provides additional information about how high-availability was implemented. Please post feedback and suggestions to the sipx-dev mailing list at sipx-dev@list.sipfoundry.org.

HW Requirements

For a reasonably performing system we recommend the following minimum configuration. This is a rough guide line for a production system. sipX can be installed on significantly older HW provided there is enough system memory available (>384MB). Media server performance profits from a dual CPU system.

• Pentium 4 or Xeon processor @ 1.8 GHz or higher (For a test system even a P III will work fine)
• Minimum of 512 MB of memory with sufficient swap space (1 GB RAM preferred)
• 18 GB to 36 GB disk recommended (dependent on required voicemail storage)

Install Debian Sarge

We chose a minimal text based install of Debian Sarge (3.1) without any additional packages (network install from a minimal CD). The example hostname chosen was sipx with the domain name domain.com. We chose not to configure the mail system (Exim) at this point.

Note re: kernel: By default Debian Sarge will use kernel 2.4.27. If you want a 2.6 kernel type linux26 at the initial boot prompt.

Once installed, login as root.

Verify Host and Domain Name Settings

The Debian installer by default sets up networking for DHCP. It is typically an advantage to assign a fixed IP address to a sipX system. In order to switch from a DHCP assigned IP address to a fixed IP address, comment out the existing iface line and add the settings for a fixed IP address as shown below.

# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
#iface eth0 inet dhcp
iface eth0 inet static
  address 192.168.5.177
  netmask 255.255.255.0
  gateway 192.168.5.1
  network 192.168.5.0
  broadcast 192.168.5.255

Add the hostname and domain to the /etc/hosts file. Make sure the IP address matches and also make sure that the hostname sipx is removed from the first line. The file /etc/hostname should already include the hostname sipx. Note that the file /etc/host.conf includes the order by which Debian resolves its hostname (order hosts,bind).

127.0.0.1       localhost.localdomain   localhost
192.168.5.177   sipx.domain.com sipx

search domain.com
nameserver 192.168.5.10
nameserver 192.168.5.5

Test hostname:

hostname                   (outputs your fully qualified name)
dnsdomainname -f           (outputs the fully qualified name)
dnsdomainname -d           (outputs the domain name)
dig -t A sipx.domain.com   (outputs the DNS response)

Setup DNS

By default sipX will install using a fully qualified host name (FQHN) and without using DNS SRV. Still, configuring DNS SRV for SIP is a good idea as this allows you to use SIP URLs that do not have to include the hostname of the sipX server.

In any case, make sure the machine is setup in DNS. This requires the editing of the configuration of your domain's DNS server and is critically important.

sipX can use DNS SRV records, which allows you to establish a SIP service for your domain. In addition, DNS SRV is a powerful mechanism for load balancing and fail over and is typically used for scalable and resilient Web server installations. See DNS man pages for additional information.

Please refer to the Fedora HowTo Documentation for a more detailed description of the required DNS setup.

Setup Debian apt Package Management

#deb file:///cdrom/ sarge main

deb http://mirrors.kernel.org/debian/ stable main non-free contrib
deb-src http://mirrors.kernel.org/debian/ stable main

deb http://security.debian.org/ stable/updates main contrib non-free

deb http://scm.calivia.com/pub/sipx/debian sarge 3.4

Note: The Debian build scripts are available from the Calivia repository.

sudo apt-get update

Optional: Install Sun JRE 1.5

If JRE is not installed here it will be automatically installed when installing sipxpbx. The Sun Java Runtime .deb packages are available from the Calivia Repository. (Manually Install Sun Java (JRE) 1.5)

sudo apt-get install sun-j2re1.5

Install sipX

The required .deb packages are available from the Calivia Repository. All necessary run-time dependencies are installed automatically.

sudo apt-get install sipxpbx sipxconfig

Package Configuration

PostgreSQL configuration:

• Accept the default directory for the PostgreSQL database: /var/lib/postgres/data
• Should data be purged: No (default)
• Locale: en_US
• Day/Month: US (pick as you like)

SSL self-signed certificate configuration (libsipxcommserver1):

• Enter data required to generate a self-signed certificate used by sipX. Manual creation of a self-signed certificate is no longer required. Run 'dpkg-reconfigure libsipxcommserver1' to re-create a self-signed certificate.

TFTP Server configuration:

• Server started by inetd <yes>

Java configuration (sipxconfig):

• Enter JAVA_PATH. On a stock Debian Sarge with Sun JRE 1.5, this is /usr/lib/j2re1.5-sun

Apache configuration (sipxpbx):

• Apache configuration file: /etc/apache2/httpd.conf - Accept package maintainer's version and answer "Y"

Note: If you see this error "psql: FATAL: IDENT authentication failed for user "postgres"" during setup of sipxconfig, ignore it. This is a bug in the config script.

Fixes for the Current Debian Post-Install Scripts

Stopping sipxpbx

/etc/init.d/sipxpbx stop

Postgres Database Initialization

/usr/bin/sipxconfig.sh --setup

Note: If you see this error "psql: FATAL: IDENT authentication failed for user "postgres"" during setup of sipxconfig, ignore it. This is a bug in the config script.

Generate a valid SSL certificate

ALPHA 3.2: The certificate that is generated during the install process fails to install properly. The script that generates the cert changed between release 3.0.1 and 3.2. You can generate it manually as follows:

mkdir $HOME/sslkeys
cd $HOME/sslkeys

/usr/bin/ssl-cert/gen-ssl-keys.sh 
  enter the data as requested (anything works):
     - CA Common Name (DNS name for CA): Enter anything but NOT the DNS name of your server
     - SIP domain name: The domain name of your installation
     - Full DNS name for the server: Enter fully qualified hostname of your sipX server

/usr/bin/ssl-cert/install-cert.sh

Configure TFTPD

TFTPD needs to be configured to serve the sipXconfig directory instead of the default one. Edit the inetd configuration and restart inetd.

# change this line
tftp dgram udp wait root /usr/sbin/in.tftpd /usr/sbin/in.tftpd -s /var/lib/tftpboot
# to this
tftp dgram udp wait root /usr/sbin/in.tftpd /usr/sbin/in.tftpd -s /var/sipxdata/configserver/phone/profile/tftproot/

/etc/init.d/inetd restart

Install sipX CallResolver

The CallResolver is the deamon that produces CDR records from the CSE (Call State Events) collected by the sipX proxy and stored in the Postgres database. It is written in Ruby and therefore requires Ruby to be installed.

Installing Ruby and Rubygems

apt-get install ruby irb rdoc libopenssl-ruby1.8

wget http://mirrors.kernel.org/debian/pool/main/libg/libgems-ruby/libgems-ruby1.8_0.9.0-2_all.deb
wget http://mirrors.kernel.org/debian/pool/main/libg/libgems-ruby/rubygems_0.9.0-2_all.deb
dpkg -i libgems-ruby1.8_0.9.0-2_all.deb rubygems_0.9.0-2_all.deb

gem install --no-rdoc activesupport actionpack actionmailer activerecord actionwebservice
gem install --no-rdoc postgres-pr
gem install --no-rdoc rake rails

Note: gems are installed from RubyForge and therefore the system requires an active network connection for this to succeed.

Installing the CallResolver

Install the sipx call resolver Ruby gem:

apt-get install sipxcallresolver
gem install -l /usr/share/sipxpbx/lib/sipxcallresolver-1.0.0.gem

The apt-get command installed the gem into /usr/share/sipxpbx/lib/sipxcallresolver-1.0.0.gem. It still needs to be installed into the Ruby system using the gem install -l command. The install directory for all the gems is /var/lib/gems/1.8/cache.

Debugging: List the gems that are installed on your system:

gem list

Initializing the CallResolver Database

The following script initializes the SIPXCDR database:

sipxcallresolver.sh --setup

Run sipxcallresolver.sh --configtest to test for proper configuration. CDR recording needs to be enabled first in ConfigServer for configtest to report a properly configured sytem. To do this go to System, General. Call Detail Records and enable CSE logging for proxy and authproxy.

Install the sipXconfig SOAP Interface Agent

The sipXconfig SOAP Web Services interface is written in Ruby. The respective gem needs to be installed manually still:

gem install file-tail
gem install -l /usr/share/sipxpbx/lib/sipXconfig-agent-1.0.0.gem

Start sipxpbx

Note: sipXpbx is started automatically after the installation completes

Start sipX manually (as root):

/etc/init.d/sipxpbx start

The post install script adds sipxpbx to the default run level. Therefore, sipxpbx will be started automatically at boot time. Make sure postgresql and tftpd are configured for automatic startup as well.

Login to the sipX Configuration Server Web Interface

Use your favorite browser from a different system with access to the sipX server and go to (after starting sipxpbx wait for up to 30 seconds for all deamons to start properly before trying to login, check for listening TCP port 8443 with 'netstat -lnt'):

http://sipx.domain.com

First, you are asked to define a password for the superadmin user. Once entered successfully, you should then login as user superadmin.

You are all done!

Troubleshooting

See SipX ConfigServer Troubleshooting.

Uninstalling sipX

apt-get remove --purge libsipxport2
apt-get remove --purge postgresql
rm -rf /etc/sipxpbx
rm -rf /var/sipxdata
rm -rf /var/log/sipxpbx
rm -rf /var/run/sipxpbx
rm -rf /var/lib/postgres/data

Some Useful Commands

The following commands are available to better support administration and troubleshooting tasks:

Checking start-up status of sipX’s services:

/etc/init.d/sipxpbx status

Checking sipX configuration:

/etc/init.d/sipxpbx configtest

This is a useful command whenever you modify the configuration files, and is run for you before sipX services are started. Any problems are displayed on standard error and logged to /var/log/messages. If this test is performed as part of starting the services, the startup is not affected by finding an error; the services will continue to start even if errors are found (but may not operate correctly).

Reset Superadmin password using the command line:

/usr/bin/sipxconfig.sh --database reset-superadmin