HowTo install sipX 3.2 on Gentoo
From SIPfoundry sipx, The Open Source SIP PBX for Linux - Calivia
| Important note: emerging sipxpbx release 3.2 requires Apache 2.2. The new version 2.2 of the Apache server is still hard masked for Gentoo Linux. The following describes how to install it anyway. |
Installing Gentoo 2006.0
Installing Gentoo Linux can be done in a lot of different ways including a fully manual approach or using the newly released installer. The Gentoo installation manual is required reading before you start. A very crude Gentoo Linux installation summary is captured for your reference.
It is important to chose a fixed IP address and to make sure the newly installed system has a properly set host and domain name:
Hostname
Your machine NEEDS to have a fully qualified hostname. We propose to use sipx.yourdomain.com, however, you could use a different name. During the installation process you are asked to define a host and domain name for your system. The following files are configured during that step:
| Code: Set Hostname in /etc/conf.d/hostname |
HOSTNAME="sipx" |
| Code: Set Domainname in /etc/conf.d/domainname |
OVERRIDE=1 DNSDOMAIN="yourdomain.com" |
| Code: Set network parameters in /etc/conf.d/net |
config_eth0=( "192.168.1.177 netmask 255.255.255.0 brd 192.168.1.255" ) routes_eth0=( "default gw 192.168.1.1 |
| Code: Set Fully Qualified Domain Name in /etc/hosts |
127.0.0.1 localhost 192.168.1.177 sipx.yourdomain.com sipx |
Verify your host and domainname settings before proceeding:
| Code: Verify domain and host names |
domainname -f (outputs fully qualified name) domainname -d (outputs domain name) hostname (outputs hostname) |
DNS Setup
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. Both a Windows or Linux based DNS server can be used (please refer to the Windows Server manual for configuration instructions).
sipX uses 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.
| File: /etc/bind/pri/your-primary.zone |
sipx A ip.add.re.ss _sip._udp IN SRV 100 1 5060 sipx _sip._tcp IN SRV 200 1 5060 sipx _sips._tcp IN SRV 300 1 5060 sipx |
If DNS resolution of the sipx server hostname does not work properly, the following error will be experienced when you start sipXpbx:
sipXpbx: Check hostname sipXpbx: Hostname hostname is not qualified.
Check that DNS is working
| Code: Verify DNS name resolution using Linux |
ping sipx ping sipx.yourdomain.com # Install dig: emerge --ask net-dns/bind-tools dig -t A sipx.yourdomain.com dig -t SRV _sip._tcp.yourdomain.com dig -t SRV _sip._udp.yourdomain.com dig -t SRV _sips._tcp.yourdomain.com |
| Code: Verify DNS name resolution using Windows |
# Open a DOS Window ping sipx ping sipx.yourdomain.com nslookup >set q=srv _sip._tcp.yourdomain.com _sip._udp.yourdomain.com _sips._tcp.yourdomain.com |
USE Flags
The following USE flags are used. Adapt /etc/make.conf accordingly.
| File: USE flags in /etc/make.conf |
-alsa apache2 libwww postgres -doc -X -gnome -kde -qt -gtk java |
Note: "-alsa" disables building sipXmediaLib with local audio support. Local audio is not needed for a sipXpbx server. sipXmediaLib is also used with sipXphone, where local audio must be enabled.
Note: "-doc" disables building doxygen developer documentation.
Install Layman
Gentoo uses a program called Layman to manage portage tree overlays. If you do not yet have it installed, you will need to before you can setup the sipX overlay.
| Code: Install Layman |
emerge --ask app-portage/layman |
Be sure the follow the post-installation instructions to complete setup.
The sipX overlay is a Subversion overlay. To use it, you will also need to have Subversion installed.
| Code: Install Subversion |
emerge --ask subversion |
Setup the sipX Overlay
You can use Layman to install the sipX overlay on your system.
| Code: Install sipx Overlay |
layman -o file:///tmp/overlay.xml -a sipx |
Enable masked Apache 2.2
We need version 2.2 of Apache, but it is still hard masked and needs to be unmasked before we can emerge Subversion.
| File: /etc/portage/package.unmask - enable hard masked packages |
=net-www/apache-2.2.0-r2 =dev-libs/apr-util-1.2.2 =dev-libs/apr-1.2.2 |
| File: /etc/portage/package.keywords - enable masked packages |
=net-www/apache-2.2.0-r2 =dev-libs/apr-util-1.2.2 =dev-libs/apr-1.2.2 |
Emerge sipXpbx
Now you are ready to emerge the sipXpbx package. This will emerge all required packages. This can be a very long list, depending on what you already have installed on your machine.
SIPfoundry sipXpbx ebuilds version 3.2.0 are still masked.
| File: /etc/portage/package.keywords |
=net-misc/sipxportlib-3.2.0 ~x86 =net-misc/sipxtacklib-3.2.0 ~x86 =net-misc/sipxcommserverlib-3.2.0 ~x86 =net-misc/sipxmedialib-3.2.0 ~x86 =net-misc/sipxmediaadapterlib-3.2.0 ~x86 =net-misc/sipxcalllib-3.2.0 ~x86 =net-misc/sipxvxml-3.2.0 ~x86 =net-misc/sipxpublisher-3.2.0 ~x86 =net-misc/sipxproxy-3.2.0 ~x86 =net-misc/sipxregistry-3.2.0 ~x86 =net-misc/sipxconfig-3.2.0 ~x86 =net-misc/sipxpbx-3.2.0 ~x86 =www-apache/mod_cplusplus-1.5.2 ~x86 |
| Code: Emerge sipXpbx |
emerge -av =net-misc/sipxpbx-3.2.0 |
Create a self-signed SSL Server Key and Certificate
The sipX Configuration Server requires a digital certificate for authentication purposes. The following describes how to generate a self signed cert - the easiest way and for test purposes secure enough.
| Code: Generate valid SSL certificate |
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
|
Initialize and Configure the PostgreSQL Database
(See here when you upgrade from version 7.4.x to version 8.0).
The database can be initialized as follows (only if this is a brand new installation of PostgreSQL):
| Code: Initial Setup |
emerge --config dev-db/postgresql |
Start and add PostgreSQL to the default runlevel
In order to start Postgres anytime when the system is booted execute the following:
| Code: Start and add Postgres to the startup script |
/etc/init.d/postgresql start rc-update add postgresql default |
Create the sipXpbx SIPXCONFIG Database
The commands below to create the SIPXCONFIG database in PostgreSQL assume the database server is up and running.
| Code: Create PostgreSQL Database SIPXCONFIG |
/usr/bin/sipxconfig.sh --setup |
Update the Environment
Update the environment:
| Code: Update environment |
env-update && source /etc/profile |
Set Permissions for sipXconfig
| Code: fix permissions for sipXconfig |
emerge --config sipxconfig |
OpenBSD TFTP server
To provision your phones automatically via sipXpbx config server you need to setup a tftp server.
| Code: Emerge OpenBSD TFTP server |
emerge -av net-ftp/tftp-hpa |
Make sure the path is set to the config server tftproot directory before you start the tftp server.
| File: /etc/conf.d/in.tftpd |
# set tftproot to sipxconfig tftproot directory INTFTPD_PATH="/var/sipxdata/configserver/phone/profile/tftproot/" |
The Gentoo initscript will eventually check for in.tftpd and start it if ot is not already running. For now, make sure in.tftpd gets started at boot.
| Code: Start OpenBSD TFTP server |
/etc/init.d/in.tftpd start # add in.tftpd to the default runlevel rc-update add in.tftpd default |
Start sipXpbx
Optional: Using the Gentoo Start Script
The Gentoo start script takes care of the runtime dependency with postgresql and the configured TFTP server (if any). It will start both postgresql and in.tftpd (if configured to do so in /etc/conf.d/sipxpbx).
Note: Messages on startup are not yet finished. You will see less output by the script than with the original one.
| Code: Starting sipX |
# move the original script away for reference mv /etc/init.d/sipxpbx /etc/init.d/sipxpbx.orig # create links for the preliminary runscript and config file ln -s /usr/local/portage/net-misc/sipxpbx/files/conf.d/sipxpbx /etc/conf.d/sipxpbx ln -s /usr/local/portage/net-misc/sipxpbx/files/init.d/sipxpbx /etc/init.d/sipxpbx |
The sipXpbx start script will transform the configuration files in /etc/sipxpbx.
| Code: Start sipXpbx |
/etc/init.d/sipxpbx start |
There should be no errors reported during startup.
Login to the sipXconfig Web interface: Point your Web browser to http://sipx.yourdomain.com. Set a password for user superadmin and log in.
- Wait for all processes to start (up to 30s!), then access the web GUI
- Set the password for user superadmin
- Log in with user superadmin and the password you just set
Troubleshooting
- http://www.sipfoundry.org/sipXconfig/doc/manual/troubleshooting.html
- SipX_ConfigServer_Troubleshooting
Running unit tests
To run the 'make check' target, issue the following:
#env FEATURES=test ebuild name-of-ebuild-version.ebuild test, i.e. env FEATURES=test ebuild /usr/local/portage/net-misc/sipxportlib/sipxportlib-3.2.0.ebuild test
