Description

FOP2 is a web based switchboard for the open source Asterisk© PBX. In order to use the software you must have a working Asterisk PBX.

Asterisk is a powerful and complex software. You won't find here instructions on setting up Asterisk itself here. If you are new to Asterisk and VoIP and want to get started, an easy and quick way is to install one Asterisk based Linux distribution like Elastix, PBXinaFlash, AsteriskNow, etc. Any of these distributions will install a complete Linux system with Asterisk and a web fronted for configuring it, and most probably with the original (and now deprecated) FOP version 1 bundled.

Once you have Asterisk working you can install FOP2 to get the best standalone switchboard available for it. Don't take our word for it. Download it and see it for yourself.


System Requirements

The software consists of two components, a server side daemon that runs in your server, and a web application that is served by your web server.

The server daemon will connect to the Asterisk Manager Interface over port tcp/5038 and will be the mediator between Asterisk and the web clients. On the other hand, Web clients (browsers) will connect to the FOP2 server via port tcp/4445 by default.

Note

If you try to connect with your web browser to your FOP2 server from outside your LAN, you will need to port forward port tcp/4445 in your router.

The server component runs on most of the 32bits and 64bits linux flavors available today.

You will have to get the correct tarball for your OS. If there is no package for your Linux distro, you can try with a similar package that uses the same glibc version. For example, the Debian packages can be used in Ubuntu. You can find out your glibc version by typing in the console:

/lib/libc.so.6

The response will be similar to this, the version number that you want to see is highlighted

GNU C Library stable release version 2.3.6, by Roland McGrath et al.
Copyright (C) 2005 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
Compiled by GNU CC version 3.4.4 20050721 (Red Hat 3.4.4-2).
Compiled on a Linux 2.4.20 system on 2005-11-03.
Available extensions:
        GNU libio by Per Bothner
        crypt add-on version 2.1 by Michael Glad and others
        linuxthreads-0.10 by Xavier Leroy
        The C stubs add-on version 2.1.2.
        BIND-8.2.3-T5B
        NIS(YP)/NIS+ NSS modules 0.19 by Thorsten Kukuk
        Glibc-2.0 compatibility add-on by Cristian Gafton 
        GNU Libidn by Simon Josefsson
        libthread_db work sponsored by Alpha Processor Inc
Thread-local storage support included.
For bug reporting instructions, please see:
<http://www.gnu.org/software/libc/bugs.html>.

The other component is the web application, consisting of mostly Javascript, HTML, CSS and a Flash component. As this is a web based application, you need a web server capable of serving those files, like Apache, Nginx, LightHTTPD, etc.

Some of the FOP2 features like the Visual Phonebook, the Call History report or the Recordings Interface, require support for PHP 5.1 or higher, and MySQL database installed.

Finally, your browser requires Adobe Flash Player version 9 or higher and Javascript enabled. Since version 2.20, FOP2 will try to use HTML5 websocket when available, so Flash is not a requirement anymore providing that your web browser supports websocket. Flash is still needed for listening to voicemails from the Voicemail Explorer though.

Server Requirements

  • 32 or 64 bits Linux Operating System
  • PHP 5.1 or above
  • MySQL Server 5 or above

Client Requirements

  • Modern Web Browser (IE8 or above, Google Chrome, Safari, Firefox)
  • Javascript enabled
  • Adobe Flash Player (for recording playback or lack of websocket support in browser)

Getting the software

You can download the software from http://www.fop2.com/download.php. It's a free download. FOP2 will work for up to 15 buttons in free/demo mode. If you want to unlock it and remove that limit so you can see any number of buttons on screen, you can purchase a license. You will get a code via email as soon as the PayPal payment is processed.

Licenses are quite inexpensive: with just one license you can get unlimited extensions/users.

Before downloading anything you need to determine what FOP2 version you should get to match your Linux distribution/platform. Just as a quick reminder: Trixbox, Elastix, PBX in a Flash and AsteriskNow are all based on Centos/Redhat.

Also, you must know if you have a 32 or 64 bit installation. To find that out you can run this command:

uname -a

If the output contains the strings i386 or i686, your need the 32 bits version. Otherwise you need the 64 bit version.

Then you can proceed to download the package from our servers, or get the files directly from your server command line using the wget command:

If you use a 32 bits Centos based Linux, run:

cd /usr/src
wget http://www.fop2.com/download/centos32 -O fop2.tgz

For a 64 bits Centos system run:

cd /usr/src
wget http://www.fop2.com/download/centos64 -O fop2.tgz

For a 32 bits Debian/Ubuntu system run:

cd /usr/src
wget http://www.fop2.com/download/debian32 -O fop2.tgz

For a 64 bits Debian/Ubuntu system run:

cd /usr/src
wget http://www.fop2.com/download/debian64 -O fop2.tgz

Note

Be sure to download the correct package for your Linux version. If your platform is not supported, please let us know, as we might be able to get a package for your platform too.


Installation

FOP2 is available in some distributions as an RPM package, and also available directly for download as a compressed tarball file from http://www.fop2.com/download.php.


Installing from RPM

Elastix includes FOP2 in its repositories. You can install FOP2 directly via the command line using YUM, or better yet, using the Web GUI to get the Add-on from there.


Installing from tarball

After downloading the proper package, you will have to extract it with the following command:

tar zxvf fop2.tgz

Change to the extracted FOP2 directory:

cd fop2

For the sake of simplicity, included in the tarball there is a Makefile that will install all required files for you with a single command, just type the following to install all server, client, configuration and initialization files:

make install

Note

If you use the FreePBX© or other trimmed down distributions, the make command might not be installed by default. In the case that the above command throws a command not found error, you will need to install the make utility and try again. (This is not needed if you do not receive any command not found errors). To install make run:

yum -y install make

The installation will copy the server files under /usr/local/fop2 and the web pages under /var/www/html/fop2, /var/www/fop2 or /srv/www/htdocs/fop2 depending on your distribution. It will also copy an init script for you.


FreePBX integration

For a complete FreePBX integration experience, we supply a script that updates your dialplan by modifying your current extensions_override_freepbx.conf and create a new file named extensions_override_fop2.conf file with the needed modifications.

What this script does is to write some dialplans that will override the FreePBX defaults to integrate the FOP2 presence box with the DND FreePBX featurecode, and the CallForward FreePBX Feature Codes with the CF note for FOP2 Buttons.

The script is located in /usr/local/fop2/generate_override_contexts.pl

You can execute it with the -write command line option to alter your dialplan directly, or perform a dry run by using the -print option:

/usr/local/fop2/generate_override_contexts.pl -write

The above command will try to do all the work for you. As it is an automated script, and the world is large and mostly unexplored, it might fail. In that case you can restore your original file that is saved with the name /etc/asteirsk/extensions_override_freepbx.conf.bak


Visual Phonebook

FreePBX / Thirdlane based installations:

Since FOP version 2.22 the visual phonebook tables will be created automatically for you, there is no need to create a new database or edit the config.php file, so you can skip this step.

Non FreePBX / Thirdlane based installations:

The make install command won't create the MySQL database and tables needed for the visual phonebook feature, they must be created manually. In order to do so, you must know the MySQL root password so you can create the database. If you do not know what your MySQL root password is you might want to try with default passwords like passw0rd, eLaStIx.2oo7 or just an empty password.

To create the database and tables over a Vanilla Asterisk installation without FreePBX or Thirdlane installed run:

cd /var/www/html/fop2
mysqladmin -u root -p create fop2
mysql -u root -p fop2 < mysql.db

You will also need to edit /var/www/html/fop2/config.php and set the proper MySQL credentials at the top of the file (the MySQL user in the $DBUSER variable and the password in $DBPASS.


Manager Credentials

Before starting the FOP2 service, some basic configuration is required in fop2.cfg and probably in /etc/asterisk/manager.conf, because the FOP2 daemon connects via TCP to the Asterisk Manager Interface (AMI) using a username and secret. The basic daemon config is covered here.

Once that the files are in place and the manager credentials configured you will have to start the service. There are a number of ways to do that. The best way is to use a proper init script for your distribution, another way is to start it from /etc/rc.local.

You can always check if the manager credentials are correctly configured, and also verify if your license is ok, by running the command:

/usr/local/fop2/fop2_server --test

The output from the above command for a successful installation and configuration should be similar to this:

Flash Operator Panel 2 - White Label Version.
Flash Operator Panel 2 - Valid License (7)

Connection to manager OK!

While badly configured manager credentials will return something like this instead:

Failed to connect to asterisk - localhost:5038
Error Message: Login Failed to Asterisk (bad auth) at localhost:5038. Check your manager credentials!

Avoiding Conflicts with FOP(1)

If you have the regular FOP installed and running, you will need to change the configuration for it a little bit, or disable it altogether if you do not plan to use it anymore.

To change FOP(1) configuration so you can have both versions running, edit the file op_server.cfg file that is installed in /var/www/html/panel in a regular FreePBX installation, and change the line that says:

;listen_port=4445

to:

listen_port=4444

To disable FOP(1) completely, you can edit /etc/amportal.conf and set FOPRUN=false. Then stop your currently running FOP process with the command:

/usr/sbin/amportal stop_fop

Copying files by hand

Note

You should only do this if you opt for not running the make install command as instructed earlier. If you typed make install and it finished with Done! then skip this step.

It is possible to install files manually instead of running make, and place them to suitable locations on your hard disk. For example, you can move the daemon files and configurations to /usr/local, and the web pages to a directory inside your webserver web root:

mv server /usr/local/fop2
mv html /var/www/html/fop2

Upgrading FOP2

If you want to upgrade a FOP2 installation with a new version, just install the new version over your current installation. Configuration files will be preserved, and the license will be automatically updated.

Do not revoke the license before upgrade. Do not remove any files either. Just install the new version over your existing install.

Remember that version upgrades are included free of charge for one year upon purchase. After that year you should purchase the Annual Software Maintenance if you want to upgrade your FOP2 version.


FOP2 Manager

Since FOP version 2.27 and up it is possible to use the FOP2Manager to configure users, buttons, groups, permissions and plugins, making it a breeze to have it working the way you like. The FOP2 Manager replaces the now obsolete FOP2Admin module for FreePBX. It has new features, a better interface and also works with other back ends like Thirdlane Manager or even vanilla Asterisk installations.

Note

The FOP2 Manager is bundled by default with FOP2 since version 2.28, so there is no need to do anything as it was already installed with the make install command. Skip this step if you have FOP2 2.28 or higher.


Installation

You can get the components from the download page.

After downloading the tarball and place it somewhere in your server, you have to extract it and move the files to /var/www/html/fop2/admin:

cd /usr/src
wget http://download.fop2.com/fop2manager-1.0.0.tgz
tar zxvf fop2manager-1.0.0.tgz
mv admin /var/www/html/fop2

If you use the FreePBX&copy©; distribution, you must install the php-mbstring extension and then restart the web service with these commands:

yum install php-mbstring
service httpd restart

Accessing the FOP2 Manager

Once FOP2Manager is installed, you can reach it pointing your browser to:

http://your.server/fop2/admin

If you use Elastix, the admin password to access the manager will be the same as the one you use in the Elastix admin web GUI. If you use FreePBX, then the credentials will be the same you use to access FreePBX itself.

Note

For vanilla Asterisk installations, you might want to edit the file /var/www/html/fop2/admin/config.php and change the default user and password to access it.


Managing the service

Once FOP2 is installed under a Debian/Ubuntu or RedHat/Centos based systems, a set of init scripts will be also copied and installed. Those scripts can be used to start, stop or restart the service.

Apart for the script themselves, there is also an OPTIONS file you should edit to pass extra command line parameters to FOP2 at startup. For example, if you want to enable debug, or set a specific NIC interface to bound the license to, you should edit that file and add the parameters there.

In Centos/RedHat systems the file is /etc/sysconfig/fop2 and the default content is:

OPTIONS="-d"

In Debian/Ubuntu systems the file isa /etc/default/fop2 and its content is:

OPTIONS="-d -p $PIDFILE"

Starting the service

In Centos/RedHat based systems you can do it with the command:

service fop2 start

In Debian or Ubuntu the correct command is:

/etc/init.d/fop2 start

Note

If you installed by copying files by hand, without installing an init script, you could start FOP2 by adding a line like the following at the end of /etc/rc.local:

/usr/local/fop2/fop2_server -d

Stopping the service

In Centos/RedHat based systems you can do it with the command:

service fop2 stop

In Debian or Ubuntu the correct command is:

/etc/init.d/fop2 stop

Command line usage

The service daemon can be started also by hand at the linux console. You can try by changing to fop2_server directory and running it from there, eg:

cd /usr/local/fop2
./fop2_server

The options and parameters for the daemon are the following:

Usage:
    fop2_server [options]

     Options:
       -?, --help
       -p, --pidfile
       -c, --confdir
       -l, --logdir
       -a, --audit
       -d, --daemon
       -v, --version
       -X, --debuglevel
       -r, --register
       -k, --revoke
      -rc, --code
      -rn, --name
       -i, --iface
       -t, --test
       --console
       --ctl

Options:
    --help  Print a brief help message and exits

    --pidfile
            Specify the pid file to use when running in daemon mode.
            Defaults to /var/run/op_panel.pid

    --confdir
            Specify where to look for the configuration files. If omitted,
            it will look for them in the same directory where op_server.pl
            resides

    --logdir
            If specified, will write the log files to that directory. If
            not, it will output to STDOUT and STDERR

    --daemon
            Run the server in daemon mode, detaching itself from the 
            console

    --version
            Display the version and exits

    --debuglevel
            Sets the debug level for the logs. It overrides the value 
            inside fop2.cfg

    --register
            Starts the registration process to unlock number of buttons.
            After purchasing you will receive a code via email that you 
            have to enter here to license the software.

    --reactivate
            When updating from old versions sometimes you might need to reactivate
            your license. This option will let you do just that.

    --upgrade
            You can upgrade your license to enable extra features. This options will
            show you what upgrades are available and it will let you enter upgrade
            codes purchased from http://www.fop2.com/buy.php

    --request
            Generates a license file request to register the product manually
            if your server does not have access to the Internet. You will have to
            email the text request to us via email.

    --revoke
            Revoke the license on a working machine so the code becomes available
            for registration on a new machine or different hardware.

    --code
            Register code to use for the registration process, to avoid being
            prompted for it. Good for batch registrations.

    --name
            Name to use in the registration process, to avoid being prompted

    --iface Interface to bind the license too. Default interface to use is
            is 'eth0'

    --test  Test and check Asterisk Manager Interface connection and
            credentials. If the test is successful, the AMI is accepting
            connections and the service ready to be started. If it fails, 
            you will have to check the correct AMI configuration in 
            fop2.conf and /etc/asterisk/manager.conf

    --console
            Enter console mode in a running FOP2 process

    --ctl
            Control file to manage the console. By default /var/run/fop2.ctl

Managing the license

FOP2 can be used on small systems without activation. The lite mode lets you use the panel showing up to 15 buttons of any kind on screen. Only the first 15 buttons defined in the button configuration file will be visible. You cannot bypass that limit by using groups, but you can disable some buttons using the FOP2 Manager if you do not need them.

Purchasing a license lets you unlock the number of buttons you can see. A licensed copy does not have any limit on the number of buttons it can display. Chat and Voicemail Explorer features also require a special license. For information about prices, please check here: http://www.fop2.com/buy.php

Once you buy a license, you will receive an automated email with an activation code. Save that code somewhere safe as you will be required it to enter it whenever you want to perform license actions.


Activating the license

To activate the license you need to know the activation code, and you have to chose a registration name. That name will appear in the FOP2 footer for non white labeled versions with the legend 'Licensed to XXXX'. White label versions won't display any footer

Note If you manage several boxes and licenses, it is wise to use a name that will help find or keep track of the activation codes in the future.

The command to activate the license is:

/usr/local/fop2/fop2_server --register

It will prompt for the activation code and then the registration name. If you want to pass that information in one pass, then you can try:

/usr/local/fop2/fop2_server --register --code XXXX --name YYYY

Where XXXX is the activation code and YYYY the name you want to assign to it

The license binds to the hardware MAC address of your eth0 NIC card by default. If your server does not have an eth0 interface but uses a different name for it, like em1, or venet0, then you must have the -i command line parameter to the fop2_server command, like this:

/usr/local/fop2/fop2_server --register -i em1

If you register like this, you must pass the same command line option to the init options file, usually located in /etc/sysconfig/fop2, so it looks something like this:

OPTIONS="-d -i em1"

Revoking the license

Some times you need to upgrade your hardware, change your network configuration, or move your virtual server. In those cases, your license will most probably break after the change. So, before doing anything to your installation, you must revoke your license with the command:

/usr/local/fop2/fop2_server --revoke

You will be prompted for your activation code. After entering it, and if everything works well, your activation code will be released so you can later use it to activate the software again after reinstalling/moving or changing your network configuration

Revokation only works on a valid licensed FOP2 copy, you cannot revoke an unregister/invalid license installation. To verify you have a valid license you can run:

/usr/local/fop2/fop2_server --test

Configuration Files Location

As mentioned before, FOP2 has two components: a server daemon and a web application. Files are placed in specific locations for both components.

FOP2 server location

The server is installed in /usr/local/fop2. It is not the standard location for applications in the diverse distro universe, but for the sake of simplicity we decided to settle with that location. So, if you installed from tarball using the make you will find the daemon and its configuration files under that directory. On the other hand, if you installed from tarball but copying files by hand, you might have placed the daemon files somewhere else.

Also, to keep things simple, all server config files will be placed under the same directory as the server binary itself, including the fop2.lic license file.

If you want to place config files somewhere else, you can always specify the directory for config files using the -c command line option. For the complete list of command line options for fop2_server check here.

Note

If you installed FOP2 from the Elastix Marketplace/RPM, the server configuration files are located in /etc/asterisk/fop2 instead of /usr/local/fop2

Web application location

The web client files are located under your web server web root, that changes depending your Linux distribution.

  • For Centos/Fedora the web application is installed under /var/www/html/fop2
  • For Ubuntu/Debian is under /var/www/fop2
  • For Suse is /srv/www/htdocs/fop2

The configuration file for the client side is js/presence.js, where you can set different global settings for the application itself. If you use a Centos based distribution, the full path of that file would be /var/www/html/fop2/js/presence.js.


Configuring the Server

The main server configuration file is /usr/local/fop2/fop2.cfg. The most important and required parameters for this file are the Asterisk Manager credentials. They should be correct as defined in Asterisk's manager configuration file, located at /etc/asterisk/manager.conf.

Below you will see the two files side by side so you can check how a correct configuration should look for both files.


/usr/local/fop2/fop2.cfg

[general]
; AMI definitions
manager_host = 127.0.0.1
manager_port = 5038
manager_user = fop2
manager_secret = fop222

/etc/asterisk/manager.conf

[general]
enabled = yes
port = 5038
bindaddr = 127.0.0.1

[fop2]
secret = fop222
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.0
read = all
write = all
writetimeout = 1000
eventfilter=!Event: RTCP*
eventfilter=!Event: VarSet
eventfilter=!Event: Cdr
eventfilter=!Event: ExtensionStatus
eventfilter=!Event: ChannelUpdate

FOP2 configuration files are very similar in format to regular asterisk .conf files, starting with a section name between brackets, and then a list of parameters and values assigned with equal signs.

In fop2.cfg, whitespace is ignored, and comments start with a semi-colon.

The Asterisk Manager must be enabled, and the manager user needs to have sufficient permissions. The above example shows the manager bind to the loopback interface on the Asterisk machine on port 5038, with access control defined to only allow connections from the same interface (127.0.0.1). There are also a set of write and read permissions.

As you can see, fop2.cfg should have the same user as defined in manager.conf with the correct secret.

If you have to modify Asterisk's /etc/asterisk/manager.conf to enable the service, you will need to restart Asterisk in order for the changes to take effect. If you change only the user, secret or ACL, an asterisk reload is enough.


Asterisk Configuration Recommendations

Besides enabling the manager (that is mandatory) there are other parameters in different asterisk .conf files that makes FOP2 receive meaningful and needed data from AMI.

To enable hold/unhold events/status to be monitored with FOP2, in /etc/asterisk/sip.conf you have to set:

callevents=yes

If you use FreePBX, you have to select Advanced SIP Settings and enable Call Events there. For older FreePBX versions (2.8 or older), you have to set the setting by hand in the file /etc/asterisk/sip_general_custom.conf

To enable information events on queue delivered calls:

/etc/asterisk/queues.conf

[testqueue]
eventwhencalled=yes

The above setting will send events related to queues and agents. If you monitor queues you must enable it for FOP2 to work at 100%.

In FreePBX you can set the parameter in the queue configuration page.


Testing the Manager Connection

To check if the connection between FOP2 and AMI is correct, you can run fop2_server from the linux console with the --test parameter, like:

/usr/local/fop2/fop2_server --test
Connection to manager OK!

If you get an error, check if AMI is enabled and started or if the host, user, secret and ACL are correct.


Additional fop2.conf parameters

language
For setting up the language for the server. Default is 'en' for english. Language files are easy to create/translate, look for all lang_*.cfg files in fop2 directory to see the language files available. It is important to set the language file also on the web application, as described here. Otherwise you might end up with a mixed lang setup. Since version 2.20, the language keyword on the server side is deprecated. You must set the language only in the client side by editing the preferences.js file, or each use can set its own language opening the preferences pane in the FOP2 UI. You should also set the language in //var/www/html/fop2/config.php for the PHP applications (Voicemail Explorer, Recordings Interface, Call History).
listen_port
This is the port fop2_server will bind to. Clients should be able to connect to this port in order to retrieve status information. Default value is 4445. If you do not need to change the port, you can leave this parameter commented out. To avoid issues with the client connection, try to leave the default configuration and not change this value unless you really mean it and know what you are doing.
restrict_host
Flash can be configured to NOT allow connections if the browser URI does not match the host defined here. You only need to set this if you want to restrict connections further. If you connect using IP address or hostname, this option must be commented out. Do not uncomment it unless you know what your are doing. Since version 2.20, if your browser supports HTML5 websocket it will use them instead of Flash xmlsockets. In this case, this parameter does not have any effect.
web_dir
This is the directory where FOP2 web pages are placed. It is needed only if the default bind port is changed or if you set restrict_host. Otherwise it can be left commented out.
master_key
In fop2 you have to define a list of extensions and password in order to login. This parameter is the master password. If you set it, you can login as any extension defined using this password (apart from the regular extension password). It is useful for system administrators so they do not have to remember every user password.
poll_interval
How many seconds between polling intervals. Normally you do not need to poll AMI for information. The status will be gathered at start time and then will be received in real time. This setting does not mean the time to wait for events to be displayed, as they will be received instantly no matter the value you set here. But sometimes state information in fop2 might be incorrect due to some factors and issues. That can be corrected when the poll is done. Also, if you access voicemail files with applications outside of asterisk, voicemail information might not be correct unless you poll asterisk again for message count information. Default value is 86400 (one day). Setting this value to less than 60 seconds is not advised.
poll_voicemail
If you use an external tool to check and remove voicemails, the counters and notifications will not reflect those changes. In that case you will want to set poll_voicemail to 1 and poll_interval to a shorter value. That will instruct the fop2_server to poll also for voicemail counters every poll_interval seconds.
monitor_ipaddress
Set this to 1 to track sip peer ip addresses on the display. When you mouse over a button label it will display their ip address.
blind_transfer (2.10)
If you use Asterisk 1.6.0 or 1.6.1 without the Atxfer manager feature, you need to set this parameter to 1 in order to force FOP2 into using standard Redirects (blind transfers) instead of attempting supervised transfers. To check if your Asterisk supports the Atxfer feature you can type this command: asterisk -rx 'manager show command atxfer'
supervised_transfer (2.10)
Force Asterisk 1.4 to use the Atxfer manager command. Standard Asterisk 1.4 does not include the feature, but there is a patch available to enable it. Elastix already includes the patch. So setting this parameter to 1 will force FOP2 to use the Atxfer command, making every transfer an attendant/supervised transfer.
force_parameter_delimiter (2.10)
Force parameter delimiter for manager commands to the character configured. Asterisk 1.6 requires the parameter to be a comma ,
use_agentlogin (2.10)
When adding or removing members to a queue, fop2 will default to AddQueueMember/RemoveQueueMember commands. If you set use_agentlogin to 1, together with the QueueChannel in a button definition set to an Agent number it will use AgentCallbackLogin and Agentlogoff instead.
monitor_filename (2.10)
Settings for modifying the recording filename used when you start recording a call from FOP2. Available variables are:
${UNIQUEID} = Unique Id of the call
${TIMESTAMP} = Unix Timestamp when the recording was initiated
${DEST_EXTENSION} = Target extension being monitored
${ORIG_EXTENSION} = Extension/User that started the recording (not the other leg)
${MBOX} = Mailbox of the extension/user that startend the recording (2.20)

; Date variables: 
; %Y 4 digits year
; %y 2 digits year
; %m 2 digits month
; %d 2 digits day
; %h 2 digits hour
; %i 2 digits minute
; %s 2 digits seconds

Example: monitor_filename=g${DEST_EXTENSION}-${UNIQUEID}
monitor_format (2.10)
Format to use when recording calls to disk.
monitor_mix(2.10)
Set to 1 if you want the two recording legs to be mixed on one file.
monitor_exec(2.20)
You can specify a script to be executed when the recording is finished. It will receive 3 parameters, the complete path and filename of the IN leg, the OUT leg and the final recording NAME. You should run soxmix in your script to join the recordings into one file.
notify_on_ringing(2.20)
Enable call notifications on state RINGING for the logged in user. If you want to disable notifications on ringing you can set this parameter to zero.
notify_on_connect(2.20)
Enable call notifications on AGENTCONNECT events. This event is fired when a call comes from a queue and eventwhencalled is set to in the queue configuration. Notifications on connect can pass also the call uniqueid to custom popups by means of the checkdir.php fie.
no_pickupmark(2.20)
Call pickup uses the pickupmark variable by default. In multi tenant systems this might lead to problems as you might end un picking up some other tenant call. In that case you might want to try to pickup the call by setting this parameter to one.
voicemail_path(2.20)
Path to your voicemail directory. You only need to set this if you have the Voicemail Explorer feature licensed. For voicemail to work the fop2 server must run on the same server as asterisk, or your voicemail directory must be network mounted.
save_chat_log(2.20)
By default IM chats are not logged/saved. If you uncomment the following parameter, all chats will be stored on the chatlog table inside the fop2settings.db sqlite database. It only applies if you have licensed the IM Chat feature.
spy_options(2.20)
Options to send to chan_spy when doing a Listen action. This global setting is overriden by the individual button spyoptions directive if set (in the button config). Asterisk 1.6.1 or higher has the option "d" that lets you switch spying modes using the keypad:
4 = spy mode
5 = whisper mode
6 = barge mode
whisper_options(2.20)
Options to send to chan_spy when doing a Whisper action. In Asterisk 1.6.1 or higher you can use B to enable barge (speak to both channels on a call).
#exec
It will execute the script specified after the parameter. FOP2 config parser will treat the output of that script as regular configuration data. This way you can, for example, query a database to configure users and passwords, or even buttons. If you reload it by sending a HUP signal to fop2_server, the scripts will be rerun and configuration refreshed.
buttonfile
File that stores the button configuration for the current context. The content and format of the button file is described in detail here.

Setting up users, passwords, permissions and groups

Note

The default FOP2 configuration uses the #exec directive to configure users and buttons based on information stored in a database managed by the FOP2Manager module. If you use Elastix, FreePBX, Thirdlane, PBXinaFlash, etc, then you do not need to configure anything else and you can skip this section. Just point your browser to http://your.server/fop2/admin.

Static users added in fop2.cfg will be overriden with the #exec command that is set as the very last line, and you will have troubles trying to log in.

If you want to do manual configuration as described below, then you have to comment the #exec line by adding a semi colon in front so it becomes ;#exec.

In order to load the panel, a login is mandatory. You login as an extension, and that extension will become the origin extension for actions like dial, transfer and spy sessions.

You can add users in /usr/local/fop2/fop2.cfg. The following is a sample list of users:

user=600:mysecret:dial,transfer,meetme
user=601:guessme:all
user=602:602:dial,transfer,spy,hangup,pickup,record:teamA

The format is:

user=[EXTENSION]:[SECRET]:[PERMISSIONS]:[GROUPS]

Permissions and Groups can be comma separated lists. The group is optional and it will only work if you define some groups as explained in the next section. The group feature was introduced in version 2.10.

The complete list of permissions is:

  • all: shortcut for specifying ALL permissions
  • dial: for performing dials and originate calls
  • hangup: for hanging up any call
  • meetme: for meetme actions (mute/unmute/lock)
  • pickup: for picking up ringing calls
  • record: for starting or stopping call recording
  • spy: for launching spy or whisper sessions
  • transfer: for performing transfers and transfers to voicemail
  • transferexternal (2.24): for performing transfers to external numbers
  • queuemanager (2.10): lets you add/remove/pause any queue member dynamically
  • queueagent (2.10): lets you add/remove/pause yourself to any queue
  • phonebook (2.10): lets you use the phonebook for adding/removing entries
  • hangupself (2.20): for hanging up only your own extension calls
  • recordself (2.20): for starting or stopping call recording on your own extension only
  • chat (2.20): grants permissions to initiate chat to other users
  • preferences (2.20): grants permissions to open up the personal preferences pane from the FOP2 UI
  • voicemailadmin (2.20): grants permission to open voicemail explorer for any extension
  • broadcast (2.27): grants permission to initiate broadcast chat or notes to extension groups

FOP2 Groups

Since FOP 2.10 it is possible to configure device groups. You can later assign groups to users to limit the extensions a user is allowed to view.

Group definitions are similar to user definitions, but you have to use the device name as in the buttons.cfg file to create them, for example:

group=queues:QUEUE/support,QUEUE/sales
group=TeamA:SIP/100,SIP/101,SIP/102,SIP/103,SIP/104
group=TeamB:SIP/200,SIP/201,SIP/202,SIP/203,SIP/204

The format is:

group=[NAME]:[DEVICES]

Those groups can be assigned to a user definition. If you do that, the user will be only allowed to see devices listed on that group.


FOP2 Contexts

If you need to have more than one view showing different groups of extensions or buttons (for multi tenant setups, call center groups, etc) you can use contexts.

You define a context by naming it between brackets. Just after the context you can define users, a button file, a specific master key, a specific web_dir, etc. This is a complete example:

/usr/local/fop2/fop2.cfg

[tenant_1]
master_key=nosecrets
user=100:1234:all
user=101:1234:all
buttonfile=tenant01_buttons.cfg

[tenant_2]
master_key=allsecrets
user=200:1234:all
user=201:1234:all
buttonfile=tenant02_buttons.cfg

You will have to configure each buttonfile with the appropiate group of extensions you want for each context.

To view the context you have to specify its name while loading the web page inside the GET request. For example, if you load the panel using an URL like http://192.168.0.10/fop2 to load the default context, then you can specify the "tenant_1" context by using the following URL: http://192.168.0.10/fop2/?context=tenant_1


Monitoring Multiple Asterisk Servers

In big setups or hosted environments you might have more than one asterisk machine that you need to monitor. You can run a separate fop2 instance in each server, or you can run fop2 in just one server monitoring several asterisk machines.

To start monitoring more than one server, you only need to configure a new set of manager_* parameters at the top of /usr/local/fop2/fop2.cfg, for example:

[general]
; Server 1
manager_host = 192.168.0.20
manager_port = 5038
manager_user = admin
manager_secret = amp111

; Server 2
manager_host = 192.168.0.30
manager_port = 5038
manager_user = admin
manager_secret = amp109

; Server 3 
manager_host = 192.168.0.40
manager_port = 5038
manager_user = admin
manager_secret = amp107

Later, on the button definition, you might want to specify the server. If you do not specify the server in the button definition the action you perform will be broadcasted to all servers.


Configuring Buttons

Besides the server configuration, it is important to configure the buttons you want to display, either for the default or general context, or for any other panel context you define.

Note

If you use Thirdlane/FreePBX and you have the FOP2 Manager installed you do not need to configure buttons via configuration files at all. They will be created for you, and you can configure them using the FOP2 Manager, so you can skip this chapter.

Button configuration is done on separate config files so they are easier to maintain and organize. In /usr/local/fop2/fop2.cfg you have to specify the buttonfile parameter, pointing to the file that will hold button definitions. For example:

/usr/local/fop2/fop2.cfg

...
user=100:1234:all
user=101:1234:all
buttonfile=buttons.cfg

Extension Buttons

This kind of buttons will represent a phone or extension. It will display two lines for each button and some specific information, like presence, pause state, etc.

/usr/local/fop2/buttons.cfg

[SIP/600]
type=extension
extension=600
context=from-internal
label=John Doe
mailbox=600@default
extenvoicemail=*600@default
channel=IAX2/600

[SIP/601]
type=extension
extension=601
context=from-internal
label=Mary Jones
mailbox=601@default
extenvoicemail=*601@from-internal

As you can see, button configuration starts with the device or channel name between brackets, followed by parameters=values.

The parameters are:

type
This parameters gives the identity to the button. The panel page has sections for each type. The buttons will be drawn in the corresponding section depending on its type. The possible types are: extension, queue, trunk and conference.
extension
The extension number to ring that phone. It will also be displayed as the 1st item in the button label.
context
The asterisk context where this extension is defined. Calls will be placed inside that context when transferring to, or originating a call.
label
The name to display in the web for that button. It will be drawn just after the extension number in the button label.
mailbox
The number and context for the voicemail mailbox as defined in asterisk's voicemail.conf. Expects the format exten@context
extenvoicemail
The extension and context to transfer calls directly to voicemail, with the format exten@context
channel
This parameter is optional. You can overflow channels into any extension, so if FOP2 detects activity with any of the channels in the list, it will count as activity for that extension/button. For example, if you have a local SIP channel for your extension, and an IAX extension when you are on the road, you can specify the 2nd IAX channel in the button. Calls made with any of the channels, iax or sip, will be displayed on the same button.
group (2.10)
You can set a group to any name you want. All extension buttons with the same group will be drawn on their own group section on the display. This only works for extensions. The group on a button definition is not related to a group defined in fop2.cfg for restricting user views. It is a visual way to organize or split extensions on their own panes.
queuechannel (2.10)
This channel/device will be used when adding/removing a member from a queue. If omitted FOP2 will use the channel defined between brackets. You can use this if you want to use Local/XXX@from-queue/n or if you want to use Agents (can be used together with use_agentlogin in fop2.cfg to use Agentlogin instead of AddQueueMember). Since version 2.20 you can pass a full list of options for the queue member, for example:
queuechannel=Local/620@from-queue/n|Penalty=1|MemberName=Nicolas|StateInterface=SIP/620
originatechannel (2.10)
This channel/device will be used when originating calls from this device. For example, if you want your calls to be auto answered and you are using FreePBX default 80 prefix for that, you can set this parameter to: Local/80{EXTEN}@from-internal.
queuecontext (2.10)
Context to match for queue members that use the Local/{EXTEN}@{CONTEXT}/n way. Since FreePBX 2.6, the context changed from "from-internal" to "from-queue". If using automatic configuration, the script will find out what to use by itself. If you do not use FreePBX and have a special context for adding queue members, you have to set that context name here.
privacy (2.10)
Lets you set privacy types for the buttons. Allowed types are:
  • clid: restricts callerid or dialed number display
  • monitor: prevents the device from being spied or monitored.
  • all: prevents both clid and monitor.
email (2.10)
You can set an email address per button. If set, you can then click on the presence icon for that button and be presented with the option to send an email to that extension.
external (2.20)
You can set an external number to transfer calls to using the "Transfer to External" button in the toolbar. The format is number[@context]. If no context is set, it will use the default context for that button.
spyoptions (2.20)
To specify individual options to pass to chanspy to modify its behavior, like for passing group restrictions (option g).
customastdb (2.20)
To specify an ASTDB entry to be queried for that particular extension. If set, an extra icon will be displayed on the button indicating that the value is set, and the contents of the entry will be visible on mouse over. It is normally used to show Call Forward settings for an extension.
cssclass (2.24)
It is possible to set an additional CSS class to a particular button, so you can change its appearance from the regular one, like changing its width, background color, font, or any other setting that can be set via CSS (overriding the normal css definition for the .extenbutton class defined in /var/www/html/fop2/css/operator.css)
tags (2.24)
You can add tags to buttons, separated by comma. Those tags will be matched/searched when you use the Filter box in the FOP2 UI. That way you could filter out buttons based on them (like showing all the "sales" extensions quickly, by typing that word/tag on the Filter box)

Queue Buttons

Similar to extension buttons, queue buttons use the same parameters with the difference that not only the type should be set to queue but also the name between brackets must be prefixed with "QUEUE/"

/usr/local/fop2/buttons.cfg

[QUEUE/101]
type=queue
label=Sales
extension=101
context=from-internal

[QUEUE/102]
type=queue
label=Support
extension=102
context=from-internal

Queue buttons do not accept mailbox or extenvoicemail parameters, as they only apply to extension buttons.


RingGroup Buttons

Similar to queue buttons, ring group buttons use the same parameters with the difference that not only the type should be set to ringgroup but also the name between brackets must be prefixed with "RINGGROUP/"

Note

Ring Group buttons are not capable of tracking Ring Group status, they are only used as a transfer target, so you can transfer calls to a RingGroup

Example:

/usr/local/fop2/buttons.cfg

[RINGGROUP/1600]
type=ringgroup
extension=1600
label=Sales

Ring Group buttons do not accept mailbox or extenvoicemail parameters, as they only apply to extension buttons.


Conference Buttons

As well as the queue buttons, conference buttons not only need to be defined as type conference, but also the name between brackets must have the "CONFERENCE/" prefix.

/usr/local/fop2/buttons.cfg

[CONFERENCE/1000]
type=conference
label=Main Conference
extension=1000
context=from-internal

Trunk Buttons

For trunks there are very little parameters to set. A trunk cannot be dialed, for that reason you do not need to specify extension nor context. Only the type "trunk" must be specified, together with the button label.

If you want to group channels in one button, you can overflow the channels listing one by one as the example below (you can add one by one or enumerate them using &):

/usr/local/fop2/buttons.cfg

[DAHDI/1]
type=trunk
label=DAHDI 1-4
channel=DAHDI/2
channel=DAHDI/3
channel=DAHDI/4&DAHDI/5&DAHDI/6

Park Button

The trunk button is fairly straightforward to setup: you must be sure to set the extension to your parking extension number, and if you do not use parking name spaces (Asterisk 1.6 and 1.8), use the "default" name for it, for example:

/usr/local/fop2/buttons.cfg

[PARK/default]
label=Park
type=park
extension=700
context=parkedcalls

Using #exec for automatic config

The #exec directive lets you specify a script to be run when FOP2 is started (or reloaded) and that outputs valid config data. Please do not remove the #, it is not a comment, in order for this directive to work the line must start with #exec

This way you can write a script that extracts configuration from a database, for example, and writes the appropriate config parameters from there.

Any output that is generated from a script will be interpreted, including other #exec directives. This is pretty powerful but also dangerous. You will have to be careful not to produce loops, and also that the output contains only valid configuration data

The automatic FreePBX/Thirdlane configurator is indeed a script that is run via an #exec directive in fop2.cfg and autobuttons.cfg

The following example will run a script that generates SIP buttons from 100 to 200:

/usr/local/fop2/fop2.cfg

buttonfile=automatic_buttons.cfg

/usr/local/fop2/automatic_buttons.cfg

#exec automatic_buttons.sh

/usr/local/fop2/automatic_buttons.sh

#/bin/bash
for EXTEN in `seq 100 200`
do
echo "[SIP/$EXTEN]"
echo "type=extension"
echo "extension=$EXTEN"
echo "context=from-internal"
echo "label=Extension"
echo "mailbox=$EXTEN@default"
echo
done

Automatic FOP2 Manager Configuration

Included in the distribution there are a couple of scripts to configure users and buttons automagically. To use them, just configure fop2 as follows:

/usr/local/fop2/fop2.cfg

..
..
#exec autoconfig-users.sh

Instead of setting up each user for FOP2, by using this script it will read asterisk's voicemail.conf file and generate users from there, with the same voicemail password and granting all permissions.

/usr/local/fop2/autobuttons.cfg

#exec autoconfig-buttons.sh

Finally, the button configuration will be read from FreePBX MySQL tables and populated for you.

Be careful as the automatic configuration does not configure the correct manager credentials, and it does not set up any databases or tables for the visual phonebook. It just setup users and buttons for FOP2.


Configuring the Web Client

Although it is not mandatory, you can do some configuration and tweaks on the web client.

Among the most important configurations you can set you have: the language to use on the client, whatever to use HTML5 websocket or not, and optionally the presence options.

Presence Options

The presence options are enumerated in the js/presence.js file, the default one is:

js/presence.js

var presence = new Object();

presence['']               = '';
presence['Do not Disturb'] = '#FF8A8A';
presence['Out to lunch']   = '#57BCD9';
presence['Break']          = '#6094DB';
presence['Meeting']        = '#CDD11B';

You can set any number of options and their hex colors, do not remove the first 2 lines as they are mandatory... the empty presence is the one for "available" state.

This feature lets you select one of the options you define, and it will flag your extension with that color and a tooltip with the text description when someone mouse overs the presence icon. This way a receptionist will get a hint about your availability to take calls without the need to ring your phone.

Global Settings

There are a couple of more options to set in presence.js, these are global options, some of them can be overridden by the user preferences as set in the preferences pane:

var showLines          = 2;
var notifyDuration     = 6;
var warnClose          = true;
var warnHangup         = true;
var dynamicLineDisplay = false;
var soundChat          = true;
var soundQueue         = true;
var soundRing          = true;
var displayQueue       = 'max'; // max or min
var pdateFormat        = 'ddd, HH:MM';
var disableVoicemail   = false; 
var language           = 'en';
var voicemailFormat    = 'wav';
var phonebookWidth     = 960;
var phonebookHeight    = 580;
var noExtenInLabel     = false;
var disableWebSocket   = false;
var enableDragTransfer = true; 
var startNotRegistered = false; 
var desktopNotify      = true;
var logoutUrl          = '';
var disablePresenceOther = false;
showLines
lets you select how many lines to display per button. You can reduce the number to 1, or increase it to 4. This setting is global and it will be applied to ALL extensions.
notifyDuration (2.10)
lets you set the time in seconds to display inbound call notifications. You can increase the time or disable notifications completely by setting it to zero.
warnClose (2.20)
set it to true to have a warning when leaving the fop2 page, or to false to disable the warning.
dynamicLineDisplay (2.20)
this display mode will hide inactive lines for buttons, saving screen space. The drawback is that the display will not be even as some buttons will be higher than others if they have active lines.
soundChat (2.20)
to enable or disable chat sounds.
soundQueue (2.20)
to enable or disable new queued calls sound.
soundRing (2.20)
to enable or disable the ringing sound.
displayQueue (2.20)
Type of queue button display, can be set to "max" or "min". "max" displays all agents and calls waiting in detail, while "min" shows just the agent and calls waiting count.
pdateFormat (2.20)
format for date on notes.
disableVoicemail (2.20)
to globally disable the voicemail explorer feature.
language (2.20)
to set the global language.
voicemailFormat (2.20)
the format for voicemail files, as configured in /etc/asterisk/voicemail.conf, set it to only one format if you have chosen more than one in the asterisk configuration.
phonebookWidth (2.26)
width in pixels for the phonebook/recordings window
phonebookHeight (2.26)
height in pixels for the phonebook/recordings window
noExtenInLabel (2.26)
Do not display the extension number on buttons
disableWebSocket (2.26)
Disable websocket and use directly Flash XMLSockets
enableDragTransfer (2.26)
Experimental feature to enable drag & drop transfers
startNotRegistered (2.26)
Show all extensions buttons as non registered at FOP2 start up
desktopNotify (2.26)
Enable or disable desktop notifications for new calls
logoutUrl (2.26)
URL to be redirected upon clicking the log out button
disablePresenceOther (2.27)
Disable the "Other" option in the presence selection drop down