root/freepbx/trunk/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