Merge pull request #32 from Len-PGH/master

added content and edits

source/accounts.rst

@@ -17,3 +17,4 @@ In the **Accounts** menu you have access to devices, extensions, gateways and us
 
   extensions_ivr/extensions.rst
   gateway_inbound_outbound/gateway1.rst
+  applications_optional/xmpp.rst

source/domains.rst → source/advanced.rst

@@ -17,6 +17,6 @@ the multi-tenant domain side menu to configure and allow secure administration f
   :maxdepth: 3
   :glob:
 
-  domains/domains.rst
+  advanced/domains.rst
   advanced/upgrade.rst
 

source/advanced/fail2ban.rst

@@ -0,0 +1,231 @@
+##########
+Fail2Ban
+##########
+
+|
+
+| For information about Fail2Ban on FreeSWITCH, http://wiki.freeswitch.org/wiki/Fail2ban see their wiki
+
+| **Logs**
+| This will log FusionPBX authentication failures to syslog (AUTH_LOG). This file can be in different places depending on how rsyslog, or syslog is configured.
+| **Ubuntu**
+| /var/log/auth.log
+
+| **Examples**
+| **GUI Login**
+
+| incorrect username
+
+::
+
+ Feb  1 11:35:11 your_hostname FusionPBX: [w.x.y.z] authentication failed for login_username
+ 
+
+| incorrect password
+ 
+::
+ 
+ Feb  1 12:07:27 your_hostname FusionPBX: [w.x.y.z] authentication failed for superadmin
+
+
+| **Provisioning**
+| Created from the code in /fusionpbx/mod/provision/index.php Please doublecheck this!
+
+::
+
+ Feb  1 12:07:27 your_hostname FusionPBX: [w.x.y.z] provision attempt bad password for AA:BB:CC:DD:EE:FF
+
+| **Setting up Fail2Ban**
+| **RegEx**
+| You can test the regex with fail2ban-regex
+
+::
+
+ '[hostname] FusionPBX: \[<HOST>\] authentication failed'
+
+|
+
+| **Configuration**
+| **Jail Options**
+
+| Every jail can be customized by tuning the following options:
+
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| Name                  | Default               |                                Description                                                                                        |
++=======================+=======================+===================================================================================================================================+
+| filter                | Campground            | Name of the filter to be used by the jail to detect matches. Each single match by a filter increments the counter within the jail |
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| logpath               | /var/log/messages     | Path to the log file which is provided to the filter                                                                              |
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| maxretry              | 3                     | Number of matches (i.e. value of the counter) which triggers ban action on the IP.                                                |
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| findtime              | 600 sec               | The counter is set to zero if no match is found within "findtime" seconds.                                                        |
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| bantime               | 600 sec               | Duration (in seconds) for IP to be banned for.                                                                                    |
++-----------------------+-----------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+
+
+|
+
+| **Filter Rules**
+| vim /etc/fail2ban/filter.d/fusionpbx.conf
+
+::
+
+ # Fail2Ban configuration file
+ #
+ # Author: soapee01
+ #
+ 
+ [Definition]
+ 
+ # Option:  failregex
+ # Notes.:  regex to match the password failures messages in the logfile. The
+ #          host must be matched by a group named "host". The tag "<HOST>" can
+ #          be used for standard IP/hostname matching and is only an alias for
+ #          (?:::f{4,6}:)?(?P<host>[\w\-.^_]+)
+ # Values:  TEXT
+ #
+ #failregex = [hostname] FusionPBX: \[<HOST>\] authentication failed
+ #[hostname] variable doesn't seem to work in every case. Do this instead:
+ failregex = .* FusionPBX: \[<HOST>\] authentication failed for
+           = .* FusionPBX: \[<HOST>\] provision attempt bad password for
+ 
+ # Option:  ignoreregex
+ # Notes.:  regex to ignore. If this regex matches, the line is ignored.
+ # Values:  TEXT
+ #
+ ignoreregex =
+
+
+| add the following to /etc/fail2ban/jail.local
+
+::
+
+ [fusionpbx]
+ 
+ enabled  = true
+ port     = 80,443
+ protocol = tcp
+ filter   = fusionpbx
+ logpath  = /var/log/auth.log
+ action   = iptables-allports[name=fusionpbx, protocol=all]
+ #          sendmail-whois[name=FusionPBX, dest=root, [email protected]] #no smtp server installed
+
+
+| Add /etc/fail2ban/filter.d/freeswitch.conf with the contents:
+
+::
+
+ # Fail2Ban configuration file
+ #
+ # Author: Rupa SChomaker (first two regex)
+ 
+ [Definition]
+ 
+ # Option:  failregex
+ # Notes.:  regex to match the password failures messages in the logfile. The
+ #          host must be matched by a group named "host". The tag "<HOST>" can
+ #          be used for standard IP/hostname matching and is only an alias for
+ #          (?:::f{4,6}:)?(?P<host>[\w\-.^_]+)
+ # Values:  TEXT
+ #
+ failregex = \[WARNING\] sofia_reg.c:\d+ SIP auth failure \(REGISTER\) on sofia profile \'\w+\' for \[.*\] from ip <HOST>
+             \[WARNING\] sofia_reg.c:\d+ SIP auth failure \(INVITE\) on sofia profile \'\w+\' for \[.*\] from ip <HOST>
+             \[WARNING\] sofia_reg.c:\d+ SIP auth challenge \(REGISTER\) on sofia profile \'\w+\' for \[.*\] from ip <HOST>
+ 
+ # Option:  ignoreregex
+ # Notes.:  regex to ignore. If this regex matches, the line is ignored.
+ # Values:  TEXT
+ #
+ ignoreregex =
+
+
+| Modify /etc/fail2ban/jail.conf. Add the following make sure the freeswitch.log file path is correct.
+
+::
+
+ [freeswitch-tcp]
+ 
+ enabled  = true
+ port     = 5060,5061,5080,5081
+ protocol = tcp
+ filter   = freeswitch
+ logpath  = /usr/local/freeswitch/log/freeswitch.log
+ action   = iptables-allports[name=freeswitch-tcp, protocol=all]
+            sendmail-whois[name=FreeSwitch, dest=root, [email protected]]
+ 
+ [freeswitch-udp]
+ 
+ enabled  = true
+ port     = 5060,5061,5080,5081
+ protocol = udp
+ filter   = freeswitch
+ logpath  = /usr/local/freeswitch/log/freeswitch/freeswitch.log
+ action   = iptables-allports[name=freeswitch-udp, protocol=all]
+            sendmail-whois[name=FreeSwitch, dest=root, [email protected]]
+
+
+| /var/log/fail2ban.log will log this after 3 missed logins.
+
+::
+
+ 2011-02-01 12:32:18,151 fail2ban.actions: WARNING [fusionpbx] Ban 192.168.100.1
+ 
+
+| hostname # iptables -n -L fail2ban-fusionpbx
+
+::
+
+ Chain fail2ban-fusionpbx (1 referecnes)
+ target    prot opt source        destination
+ DROP      all  --  192.168.100.1 anywhere
+ RETURN    all  --  anywhere      anywhere
+
+
+| **Important**
+| **You can easily ban yourself, including current active ssh connections.**
+| **To unban:**
+
+::
+
+ hostname # iptables -n -D fail2ban-fusionpbx 1
+
+| **Keep yourself from getting banned.**
+| add to /etc/fail2ban/jail.local
+
+::
+
+ [DEFAULT]
+ 
+ # "ignoreip" can be an IP address, a CIDR mask or a DNS host
+ ignoreip = 127.0.0.1 192.168.0.99
+ bantime  = 600
+ maxretry = 3
+
+
+| **Errors**
+| If you're seeing something like this in your fail2ban logfile:
+
+::
+ 
+ 2011-02-27 14:11:42,326 fail2ban.actions.action: ERROR  iptables -N fail2ban-freeswitch-tcp
+
+
+| add the time.sleep(0.1) to /usr/bin/fail2ban-client
+
+::
+
+ def __processCmd(self, cmd, showRet = True):
+ beautifier = Beautifier()
+ for c in cmd:
+ '''time.sleep(0.1)'''
+ beautifier.setInputCmd(c)
+
+| or
+
+::
+
+ sed -i -e s,beautifier\.setInputCmd\(c\),'time.sleep\(0\.1\)\n\t\t\tbeautifier.setInputCmd\(c\)', /usr/bin/fail2ban-client
+
+| http://www.fail2ban.org/wiki/index.php/Fail2ban_talk:Community_Portal#fail2ban.action.action_ERROR_on_startup

source/advanced/freeswitch.rst

@@ -0,0 +1,356 @@
+###################
+Freeswitch install
+###################
+
+|
+
+| **Upgrade Move Source**
+
+::
+
+ mv /usr/src/freeswitch freeswitch-version
+
+| **Git Release**
+
+::
+
+ cd /usr/src
+ git clone -b v1.4 https://freeswitch.org/stash/scm/fs/freeswitch.git
+ cd freeswitch
+ ./bootstrap.sh
+
+| or
+
+| **Git Head**
+
+::
+
+ cd /usr/src
+ git clone https://freeswitch.org/stash/scm/fs/freeswitch.git
+ cd freeswitch
+ ./bootstrap.sh
+
+| or
+
+| **files.freeswitch.org**
+
+::
+
+ cd /usr/src
+ wget http://files.freeswitch.org/freeswitch-1.4.26.zip
+ unzip freeswitch-1.4.26.zip
+ cd freeswitch-1.4.26
+ 
+ 1.4.x is considered EOL use the steps below for 1.6.x
+ 
+ cd /usr/src
+ wget http://files.freeswitch.org/freeswitch-1.6.6.zip
+ unzip freeswitch-1.6.6.zip
+ cd freeswitch-1.6.6
+
+| **Ubuntu Dependencies**
+
+::
+
+ apt-get install autoconf automake devscripts gawk g++ git-core libjpeg-dev libncurses5-dev libtool make python-dev gawk pkg-config libtiff-dev libperl-dev libgdbm-dev libdb-dev gettext libssl-dev libcurl4-openssl-dev libpcre3-dev libspeex-dev libspeexdsp-dev libsqlite3-dev libedit-dev libldns-dev libpq-dev memcached libmemcached-dev
+
+| **Debian Dependencies**
+
+::
+
+ apt-get install autoconf automake devscripts gawk g++ git-core libjpeg-dev libncurses5-dev libtool libtool-bin make python-dev gawk pkg-config libtiff5-dev libperl-dev libgdbm-dev libdb-dev gettext libssl-dev libcurl4-openssl-dev libpcre3-dev libspeex-dev libspeexdsp-dev libsqlite3-dev libedit-dev libldns-dev libpq-dev memcached libmemcached-dev
+
+| **CentOS**
+
+::
+
+ yum install git gcc-c++ autoconf automake libtool wget python ncurses-devel zlib-devel libjpeg-devel openssl-devel e2fsprogs-devel sqlite-devel libcurl-devel pcre-devel speex-devel ldns-devel libedit-devel libmemcached-devel
+
+| Configure services to auto start
+
+::
+
+ chkconfig --add memcached && chkconfig --levels 33 memcached on
+ chkconfig --add freeswitch && chkconfig --levels 35 freeswitch on
+
+| **modules.conf**
+
+| uncomment the FreeSWITCH modules that are needed.
+
+::
+
+ mod_avmd
+ mod_callcenter
+ mod_memcache
+ mod_cidlookup
+ mod_curl
+
+| Used for MP3 support
+
+::
+
+ mod_shout
+
+| **Postgres driver**
+
+::
+
+ ./configure --enable-core-pgsql-support
+
+| **Run Make**
+
+::
+
+ make
+
+| **Remove FreeSWITCH files**
+
+| This step is only needed for a FreeSWITCH upgrade. 
+| Once it has been confirmed that the compile was successful then remove files from previous version of FreeSWITCH
+ 
+::
+ 
+ rm -rf /usr/local/freeswitch/{lib,mod,bin}/*
+ 
+
+| **Install**
+
+::
+
+ make install
+
+| **File Permissions**
+
+| Set the file permissions instructions may vary based on the OS and install directory.
+
+
+| Debian and Ubuntu
+
+::
+
+ chown -R www-data:www-data /usr/local/freeswitch
+ 
+ 
+
+
+| CentOS or Other Unix operating systems
+| (need make sure that the web server has access to IVR recordings, Fax, and Voicemail)
+
+::
+
+ adduser --disabled-password  --quiet --system --home /usr/local/freeswitch --gecos "FreeSWITCH Voice Platform" --ingroup daemon freeswitch
+ chown -R freeswitch:daemon /usr/local/freeswitch/ 
+ chmod -R o-rwx /usr/local/freeswitch/
+
+
+| **Install Sound Files**
+
+| Run this on new installs.
+
+::
+
+ cd /usr/src/freeswitch
+ make sounds-install moh-install
+ make hd-sounds-install hd-moh-install
+ make cd-sounds-install cd-moh-install
+
+**Startup Script**
+
+| Run on new install only. Create the file '/etc/init.d/freeswitch' with the following code:
+
+::
+
+ #!/bin/bash
+ ### BEGIN INIT INFO
+ # Provides:          freeswitch
+ # Required-Start:    $local_fs $remote_fs
+ # Required-Stop:     $local_fs $remote_fs
+ # Default-Start:     2 3 4 5
+ # Default-Stop:      0 1 6
+ # Description:       Freeswitch debian init script.
+ # Author:            Matthew Williams
+ #
+ ### END INIT INFO
+ # Do NOT "set -e"
+ 
+ # PATH should only include /usr/* if it runs after the mountnfs.sh script
+ PATH=/sbin:/usr/sbin:/bin:/usr/bin:/usr/local/bin
+ DESC="Freeswitch"
+ NAME=freeswitch
+ DAEMON=/usr/local/freeswitch/bin/$NAME
+ DAEMON_ARGS="-nc -nonat -reincarnate"
+ PIDFILE=/usr/local/freeswitch/run/$NAME.pid
+ SCRIPTNAME=/etc/init.d/$NAME
+
+ FS_USER=www-data #freeswitch
+ FS_GROUP=www-data #daemon
+
+ # Exit if the package is not installed
+ [ -x "$DAEMON" ] || exit 0
+ 
+ # Read configuration variable file if it is present
+ [ -r /etc/default/$NAME ] && . /etc/default/$NAME
+ 
+ # Load the VERBOSE setting and other rcS variables
+ . /lib/init/vars.sh
+ 
+ # Define LSB log_* functions.
+ # Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
+ . /lib/lsb/init-functions
+ 
+ #
+ # Function that sets ulimit values for the daemon
+ #
+ do_setlimits() {
+        ulimit -c unlimited
+        ulimit -d unlimited
+        ulimit -f unlimited
+        ulimit -i unlimited
+        ulimit -n 999999
+        ulimit -q unlimited
+        ulimit -u unlimited
+        ulimit -v unlimited
+        ulimit -x unlimited
+        ulimit -s 240
+        ulimit -l unlimited
+        return 0
+ }
+
+ #
+ # Function that starts the daemon/service
+ #
+ do_start()
+ {
+    # Set user to run as
+        if [ $FS_USER ] ; then
+      DAEMON_ARGS="`echo $DAEMON_ARGS` -u $FS_USER"
+        fi
+    # Set group to run as
+        if [ $FS_GROUP ] ; then
+          DAEMON_ARGS="`echo $DAEMON_ARGS` -g $FS_GROUP"
+        fi
+
+        # Return
+        #   0 if daemon has been started
+        #   1 if daemon was already running
+        #   2 if daemon could not be started
+        start-stop-daemon --start --quiet --pidfile $PIDFILE --exec $DAEMON --test > /dev/null -- \
+                || return 1
+        do_setlimits
+        start-stop-daemon --start --quiet --pidfile $PIDFILE --exec $DAEMON --background -- \
+                $DAEMON_ARGS \
+                || return 2
+        # Add code here, if necessary, that waits for the process to be ready
+        # to handle requests from services started subsequently which depend
+        # on this one.  As a last resort, sleep for some time.
+ }
+ 
+ #
+ # Function that stops the daemon/service
+ #
+ do_stop()
+ {
+        # Return
+        #   0 if daemon has been stopped
+        #   1 if daemon was already stopped
+        #   2 if daemon could not be stopped
+        #   other if a failure occurred
+        start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --pidfile $PIDFILE --name $NAME
+        RETVAL="$?"
+        [ "$RETVAL" = 2 ] && return 2
+        # Wait for children to finish too if this is a daemon that forks
+        # and if the daemon is only ever run from this initscript.
+        # If the above conditions are not satisfied then add some other code
+        # that waits for the process to drop all resources that could be
+        # needed by services started subsequently.  A last resort is to
+        # sleep for some time.
+        start-stop-daemon --stop --quiet --oknodo --retry=0/30/KILL/5 --exec $DAEMON
+        [ "$?" = 2 ] && return 2
+        # Many daemons don't delete their pidfiles when they exit.
+        rm -f $PIDFILE
+        return "$RETVAL"
+ }
+ 
+ #
+ # Function that sends a SIGHUP to the daemon/service
+ #
+ do_reload() {
+        #
+        # If the daemon can reload its configuration without
+        # restarting (for example, when it is sent a SIGHUP),
+        # then implement that here.
+        #
+        start-stop-daemon --stop --signal 1 --quiet --pidfile $PIDFILE --name $NAME
+        return 0
+ }
+ 
+ case "$1" in
+  start)
+        [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"
+        do_start
+        case "$?" in
+                0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
+                2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
+        esac
+        ;;
+  stop)
+        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"
+        do_stop
+        case "$?" in
+                0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
+                2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
+        esac
+        ;;
+  status)
+       status_of_proc -p $PIDFILE $DAEMON $NAME && exit 0 || exit $?
+       ;;
+  #reload|force-reload)
+        #
+        # If do_reload() is not implemented then leave this commented out
+        # and leave 'force-reload' as an alias for 'restart'.
+        #
+        #log_daemon_msg "Reloading $DESC" "$NAME"
+        #do_reload
+        #log_end_msg $?
+        #;;
+  restart|force-reload)
+        #
+        # If the "reload" option is implemented then remove the
+        # 'force-reload' alias
+        #
+        log_daemon_msg "Restarting $DESC" "$NAME"
+        do_stop
+        case "$?" in
+          0|1)
+                do_start
+                case "$?" in
+                        0) log_end_msg 0 ;;
+                        1) log_end_msg 1 ;; # Old process is still running
+                        *) log_end_msg 1 ;; # Failed to start
+                esac
+                ;;
+          *)
+                # Failed to stop
+                log_end_msg 1
+                ;;
+        esac
+        ;;
+  *)
+        #echo "Usage: $SCRIPTNAME {start|stop|restart|reload|force-reload}" >&2
+        echo "Usage: $SCRIPTNAME {start|stop|restart|force-reload}" >&2
+        exit 3
+        ;;
+ esac
+ 
+ exit 0
+
+
+Make the script executable and make it auto start on system boot:
+
+::
+
+ chmod +x /etc/init.d/freeswitch
+ update-rc.d freeswitch defaults
+
+|
+ 

source/phones.rst → source/applications.rst

@@ -15,6 +15,6 @@ In the **Applications** menu (Apps) section you will find Call Block, Call Broad
   :glob:
 
 
-  phones/phones.rst
-  phones/recordings.rst
+  applications/ivr.rst
+  applications/recordings.rst
   

source/applications_optional/xmpp.rst

@@ -0,0 +1,155 @@
+############
+XMPP Manager
+############
+
+|
+
+.. image:: ../_static/images/fusionpbx_xmpp.jpg
+        :scale: 85%
+
+|
+
+| XMPP Manager is an optional menu item.  In order to have the option for XMPP Manager there are a few step to take to enble XMPP.
+
+|
+
+.. image:: ../_static/images/fusionpbx_xmpp1.jpg
+        :scale: 85%
+
+|
+
+**XMPP Profile**
+
+| FusionPBX menu.
+
+| Accounts -> XMPP manager.
+
+| Click the
+
+.. image:: ../_static/images/plus.png
+        :scale: 75%
+        
+| on the right to create a profile.         
+
+| In this example we will setup Google Talk and by creating a profile called gtalk. 
+
+::
+
+ Profile Name: gtalk
+ Username: [email protected] (use your account)
+ Password: use the correct password
+ Auto-Login: yes
+ XMPP Server: talk.google.com
+
+|
+
+.. image:: ../_static/images/fusionpbx_xmpp2.jpg
+        :scale: 85%
+
+
+| Two approaches can be used for the next part.
+
+| **Option 1.**
+
+| Lets say my gmail number was 13051231234. This approach will send the inbound calls to the inbound routes with a destination number that is the default extension number that is set.
+
+::
+
+ Default extension: 13051231234
+ Advanced -> Context: public
+
+
+| **Option 2.**
+
+| On a single tenant system. This will send the call to extension 1001 in the default context.
+
+::
+
+ Default extension: 1001
+ Advanced -> Context: default
+
+| **Option 3.**
+
+| On a single tenant system. This will send the call to extension 1001 in the multi-tenant domain name.
+
+::
+
+ Default extension: 1001
+ Advanced -> Context: your.domain.com
+
+| Save the settings and restart the module. Restart the 'XMPP' module from Advanced -> Modules page. 
+Go back to Accounts -> XMPP if the status says **'AUTHORIZED'** then you are ready to go.
+| **Note** If you are not getting AUTHORIZED you might need to goto the google account settings and choose "Allow less secure apps: ON" under the Sign-in & security section.
+
+|
+
+.. image:: ../_static/images/fusionpbx_xmpp5.jpg
+        :scale: 85%
+
+|
+
+| **Outbound Routes**
+
+| For this example we will use 11 digit dialing.
+
+::
+
+ Gateway: XMPP
+ Dialplan Expression: 11 digits
+ Description: Google Talk
+ Press Save
+
+| If your XMPP profile is named something other than gtalk edit the outbound route you just created.
+Bridge statement should look like: dingaling/gtalk/[email protected] replace gtalk with the profile name you chose and then save it.
+
+|
+
+
+
+############
+Enable XMPP
+############
+
+
+|
+
+| XMPP manager is used to configure client side XMPP profiles. It can be used as a client to register to make and receive call with Google Talk or other XMPP servers.
+
+|
+
+| **GIT Manually add XMPP**
+|
+| After version 3.8 XMPP is optional.  To add XMPP do the following
+
+| Goto command line
+
+::
+
+ cd /tmp
+ git clone https://github.com/fusionpbx/fusionpbx-apps.git 
+ cd fusionpbx-apps/
+ mv xmpp/ /var/www/fusionpbx/app/
+ cd /var/www/fusionpbx/app
+ chown www-data:www-data -R xmpp/
+
+
+
+Goto Fusionpbx GUI
+
+| Goto the GUI and click advanced > menu manager > edit icon > click "Restore Defaults" at top right
+|
+
+| Then goto Advanced > Upgrade
+click Schema, Data Types, and Permission Defaults then click execute
+
+|
+| Click status > sip status > Flush Memcache
+
+|
+| Log out then back in
+
+|
+| You should now have XMPP Manager under Accounts
+
+|
+

source/index.rst

@@ -75,9 +75,12 @@ Getting Started
     getting_started.rst
     accounts.rst
     dialplan.rst
-    phones.rst
-    domains.rst
+    applications.rst
+    advanced.rst
     manual.rst
+    advanced/fail2ban.rst
+    advanced/freeswitch.rst
+    testimonials.rst
     contributing.rst
     doc_guide.rst
 

source/testimonials.rst

@@ -0,0 +1,4 @@
+#############
+Testimonials
+#############
+