Configuration


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


The configuration file is 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 permisions. 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 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. They are:

/etc/asterisk/sip.conf
callevents=yes

It will send hold/unhold events to FOP2.

For Freepbx add the entry into /etc/asterisk/sip_general_custom.conf or via the SIP settings on the web UI on the latest version.)

/etc/asterisk/queues.conf
[testqueue]
eventwhencalled=yes

It 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 editting the preferences.js file, or each use can set its own language opening the preferences pane in the FOP2 UI.
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 websockets 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 paremeter is the master password. If you set it, you can login as any extension defined using this password (appart 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 adviced.
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 in the asterisk console "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 attendand/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 extenstion 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

Eg:
monitor_filename=g${DEST_EXTENSION}-${UNIQUEID}
monitor_format (2.10)
Format to use when recarding 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 notificatios 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 featurs 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

The default FOP2 configuration uses the #exec directive to configure users and buttons for a FreePBX based system. If you use FreePBX, then you do not need to configure anything else and you can skip this section. Static users will be overriden with the #exec line that is set as the very last line in fop2.cfg 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. Since version 2.10 you can tweak and manage configurations using the FreePBX module, available for download from the Download page.

In order to load the panel, a login is mandatory. You login as an extension, and that extension will become the origing extension for dials, transfers and spy sessions.

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 stoping call recording
  • spy: for launching spy or whisper sessions
  • transfer: for performing transfers and transfers to voicemail
  • transferexternali (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 inititate 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 brakets. 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
[tennant_1]
master_key=nosecrets
user=100:1234:all
user=101:1234:all
buttonfile=tenant01_buttons.cfg

[tennant_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 "tennant_1" context by using the following URL: http://192.168.0.10/fop2/?context=tennant_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.