root/freepbx/branches/2.1/INSTALL

###
Installing freePBX

### 
Important Warning!
freePBX _will_ overwrite any exisiting asterisk configurations you may have. This project attempts
to manage as much of asterisk as it can, and this means lots of automatically generated dialplans.
Please visit both the Documentation wiki (http://www.aussievoip.com.au/wiki/freePBX) and the Dev
wiki (http://www.freepbx.org/wiki) for instructions, hints and tips. As a rule of thumb, any 
existing sip, iax, or extensions files can be copied to the same name with _custom.conf appended,
and things will continue to work as before.


###
freePBX has several requirements, including the following packages (names may vary based on distro):

        libxml2
        libxml2-devel
        libtiff
        libtiff-devel
        lame
        httpd (or Apache2)
        mysql (or mysql-client)
        mysql-devel (or libmysqlclient10-dev)
        mysql-server
        php (or php4) 
        (on debian, also install libapache2-mod-php4)
        php4-pear (if pear is not included with your php)
        php-mysql
        (on SUSE, also install php4-gettext and php4-session)
        php-gd
        openssl
        openssl-devel (or libssl-dev)
        kernel-devel (or linux-source)
        perl
        perl-CPAN
        bison
        ncurses-devel (or libncurses5-dev)
        audiofile-devel (or libaudiofile-devel)
        curl
        sox

### Install these Perl modules:
        
        perl -MCPAN -e "install Net::Telnet"
        
        perl -MCPAN -e "install IPC::Signal"
        
        perl -MCPAN -e "install Proc::WaitStat"

###
Mime-contruct is needed to generate emails with fax file attachments:


        - download the latest mime-construct from http://search.cpan.org/~rosch/
        - install it

###
Download asterisk-perl from http://asterisk.gnuinter.net and install it
        
###
freePBX requires the following changes to php and apache for uploading new MOH files:


        - vi +482 /etc/php.ini  (or /etc/php4/apache2/php.ini)
                upload_max_filesize=20M
        - vi +14 /etc/httpd/conf.d/php.conf (if you have it)
                LimitRequestBody 20000000

###
Download the latest freePBX files:

        - download the latest freePBX tarball to /usr/src
        - tar -zxvf freepbx<version>.tar.gz

###
Getting Asterisk and Zaptel from SVN or download the latest Asterisk and Zaptel source archives
(freePBX uses the v2.0 branch)

        - cd /usr/src
        - svn checkout http://svn.digium.com/svn/asterisk/branches/1.2 asterisk-1.2
        - svn checkout http://svn.digium.com/svn/zaptel/branches/1.2 zaptel-1.2
        - svn checkout http://svn.digium.com/svn/libpri/branches/1.2 libpri-1.2

###
For TDM zap devices (FXO/FXS):

        - cd /usr/src/zaptel
        - make && make install

        If you will be using a Digium telephony card that supports T1/E1 signaling do this step as well:
        - cd /usr/src/libpri
        - make && make install
        
###
Patching Asterisk with softfax/spandsp.

        - Download the latest spandsp files from http://www.soft-switch.org
        - cd /usr/src/spandsp-xxx
        - ./configure
        - make && make install

        The spandsp libraries are installed to /usr/local/lib.  Therefore /usr/local/lib must be added to the LD_LIBRARY_PATH environment variable of the user that starts the asterisk process. To be safe, also add it to /etc/ld.so.conf and run ldconfig.

        Copy the following files (from soft-switch.org) to /usr/src/asterisk/apps/ :

        - cp app_rxfax.c /usr/src/asterisk/apps/
        - cp app_txfax.c /usr/src/asterisk/apps/
        - cp apps_makefile.patch /usr/src/asterisk/apps/

        - cd /usr/src/asterisk/apps
        - patch < apps_makefile.patch

                
###
Create a group and non-root user:

        - groupadd asterisk
        - useradd -c "asterisk PBX" -d /var/lib/asterisk -g asterisk asterisk
        
        
###
Building Asterisk and configuring it to run as a non-root user

        - mkdir /var/run/asterisk
        - cd /usr/src/asterisk
        - make clean && make && make install

###
Get and build cdr_mysql module for asterisk

        - cd /usr/src/asterisk-addons
        - perl -p -i.bak -e 's/CFLAGS.*D_GNU_SOURCE/CFLAGS+=-D_GNU_SOURCE\nCFLAGS+=-DMYSQL_LOGUNIQUEID/' Makefile
        - make clean && make && make install
        
###
Install asterisk-sounds

        - cd /usr/src/asterisk-sounds
        - make install
        
###
Setting up MySQL for CDR and freePBX web interface

        - /usr/bin/mysql_install_db
        - /etc/init.d/mysqld start (or /etc/init.d/mysql start) 

        - mysqladmin -u root password 'db_root_pwd'
        - mysqladmin create asteriskcdrdb -p
        - mysql --user=root --password=db_root_pwd asteriskcdrdb < /usr/src/freepbx<version>/SQL/cdr_mysql_table.sql
        
        - mysqladmin create asterisk -p
        - mysql --user root -p asterisk < /usr/src/freepbx<version>/SQL/newinstall.sql

        
###
Grant access to these two databases you just created

**Note the default mysql username/password is asteriskuser/amp109.  
**If you change either of these, you will be prompted for them while running ./install below

        - mysql --user root -p

                mysql> GRANT ALL PRIVILEGES ON asteriskcdrdb.* TO asteriskuser@localhost IDENTIFIED BY 'amp109';
                Query OK, 0 rows affected (0.00 sec)

                mysql> GRANT ALL PRIVILEGES ON asterisk.* TO asteriskuser@localhost IDENTIFIED BY 'amp109';
                Query OK, 0 rows affected (0.00 sec)
                
                mysql> quit

###
Run the "install" script to install all the freePBX files:  

        - /usr/src/freePBX/install_amp
        
###
Configure zaptel driver:

        a. Edit /etc/zaptel.conf to reflect installed Digium telephony card(s).
        
        Only the parameters/values relevant to a TDM400P with 4 FXO modules are included below:

        fxsks=1-4
        loadzone=us
        defaultzone=us

        Only the parameters/values relevant to a TE110P (T1 configuration) are included below:
        
        span=1,1,0,esf,b8zs
        bchan=1-23
        dchan=24
        loadzone=us
        defaultzone=us

        b. ztcfg -v

                        Zaptel Configuration
                        ======================
                        
                        1 channels configured.
        
        If you get a warning about unable to open master device /dev/zap/ctl, that's ok.  It's a result
        of the zaptel module(s) not loaded yet.

        Detailed information with regard to Asterisk's configuration files can be found here:
        http://voip-info.org/wiki-Asterisk+config+files

###
Configure zapata module in asterisk config.

        - edit /etc/asterisk/zapata.conf to reflect installed digium interfaces (see zapata.conf.template)

        Only the parameters/values relevant to a TDM400P with 4 FXO modules are included below:

        [channels]
        language=en
        #include zapata_additional.conf
        context=from-pstn
        signalling=fxs_ks
        faxdetect=incoming
        usecallerid=yes
        callerid=asreceived
        echocancel=yes
        callprogress=no
        busydetect=no
        echocancelwhenbridged=no
        echotraining=800
        group=0
        channel=1-4


        Only the parameters/values relevant to a TE110P (T1 configuration) are included below:

        [channels]
        language=en
        #include zapata_additional.conf
        context=from-pstn
        switchtype=national
        pridialplan=national
        signalling=pri_cpe
        faxdetect=incoming
        usecallerid=yes
        echocancel=yes
        callerid=asreceived
        echocancelwhenbridged=no
        echotraining=800
        group=0
        channel=1-23


        Note: if your configuration is using zap channels as FXS endpoints, zapata.conf must
        contain the following line in order to provision these endpoints in freePBX's Extensions admin:
        #include zapata_additional.conf

        Detailed information with regard to Asterisk's configuration files can be found here:
        http://voip-info.org/wiki-Asterisk+config+files

###
httpd (Apache) configuration

        - Edit /etc/httpd/conf/httpd.conf (or /etc/apache2/apache2.conf) so that:

                User asterisk
                Group asterisk
                
###
Chown the PHP session.save_path directory:

        - chown asterisk /var/lib/php/session

                
###
Amportal Control Script

        FreePBX's amportal control script starts, stops or kills services in the freePBX environment, and sets permissions on directories/files in the
        freePBX environment:

        [root@pbx root]# amportal
        
        ----------AMP Control Script-----------
        Usage: amportal start|stop|kill|chown
        start: Starts Asterisk and Flash Operator Panel server
        stop: Gracefully stops Asterisk and the FOP server
        kill: Kills Asterisk and the FOP server
        chown: Sets appropriate permissions on files
        
        The amportal script is the recommended way to stop and start asterisk:
        
        [root@pbx root]# /usr/sbin/amportal stop
        [root@pbx root]# /usr/sbin/amportal start

###
Auto Start

        The module/driver that you load at boot time depends upon whether you are using a
        TDM400P or TE110P. The wcfxs module should be loaded for the former and the wcte11xp
        module should be loaded for the latter.

        The following scripts are for RedHat and derivatives that use an rc.local:
        
        Edit /etc/rc.d/rc.local to include the following for the TDM400P:
        #!/bin/sh
        #
        # This script will be executed *after* all the other init scripts.
        # You can put your own initialization stuff in here if you don't
        # want to do the full Sys V style init stuff.
        touch /var/lock/subsys/local
        echo Loading wcfxs
        /sbin/modprobe wcfxs
        /usr/sbin/amportal start

        Edit /etc/rc.d/rc.local to include the following for the TE110P:

        #!/bin/sh
        #
        # This script will be executed *after* all the other init scripts.
        # You can put your own initialization stuff in here if you don't
        # want to do the full Sys V style init stuff.
        touch /var/lock/subsys/local
        echo Loading wcte11xp
        /sbin/modprobe wcte11xp
        /usr/sbin/amportal start

        For Debian and others (?), you'll have to add startup script(s) to /etc/init.d and link them
        to the appropriate rc?.d runlevel.

        
        Also ensure that mysql and apache are set to start at bootup. For RedHat-based systems do the following:
        
        - chkconfig --level 3 httpd on
        - chkconfig --level 3 mysqld on

###
Start everything (or reboot and it should start automagically):

        - As root run:

                service httpd restart
                (or /etc/init.d/apache2 restart)

        - As root run:

                amportal start

        - Point your browser to:

                http://[ip address]  (default login is admin/admin)

If you notice any errors or updates that are needed to this document, please e-mail:
info@coalescentsystems.ca