FreePBX is often referred to as a GUI to manage Asterisk configuration files. This misconception leads to confusion when Asterisk knowledgeable users begin to dig into a FreePBX system and find so many things that look foreign or different from what they are used to.
FreePBX is a sophisticated PBX Framework that transforms a LAMPA System (Linux, Apache, MySQL, PHP, Asterisk) into a world class PBX. Asterisk is a great tool just as PHP or gcc are great interpreters and compilers. But without sophisticated business logic and data structures they will not do a lot for you. FreePBX provides this application layer on top of the LAMPA foundation to deliver this. This next series of articles will take a walk through the different components of FreePBX and discuss how and why things are done the way they are.
We will briefly step up to a birds eye view of the system and then spend the rest of this week’s article exploring what is up with all these FreePBX Users (AMPUSER) vs. devices vs. extensions.
[img_assist|nid=4134|desc=|link=popup|align=center|width=640|height=412]
Figure 1
Figure 1 illustrates an architectural view of the overall system. We will defer the long architectural discussion for another day and focus in on some of the FreePBX Core Dialplan Objects and a minor discussion on one of the FreePBX Core Application Library components used by these FreePBX extensions.
[img_assist|nid=4135d|desc=|link=popup|align=center|width=640|height=154]
Figure 2
Figure 2 highlights the AMPUSER and DEVICES Astdb objects that we will be talking about for the rest of this article.
If you are familiar with Asterisk, you may likely equate a phone’s extension with an extension number in some Asterisk context that is directly associated with a specific Endpoint, for example a SIP phone.. An example may look like:
[internal]
exten => 2002,1,Dial(sip/2002,${RINGTIME},${DIALOPTIONS})
exten => 2002,2,Voicemail(2002)
This is where FreePBX takes a diversion and separates this extension into at least 3 chunks of information.
- FreePBX User (AMPUSER)
This is the user, identified by their internal extension number.
- FreePBX Device (DEVICE)
This is the FreePBX Device number that is uniquely associated with some physical Endpoint such as a SIP phone, zap FXS channel, etc.
- Endpoint configuration
This is the actual Endpoint configuration. In the case of a SIP End Point this would be the information written into sip_additional.conf for example, and ultimately the Endpoint’s provisioning file or nonvolatile memory.
If you are like the majority of users, you are only familiar with the Extension GUI page for configuring an extension. Under the hood everything is always running in what is referred to as the deviceanduser mode. In this mode, FreePBX extensions are actually separated into the FreePBX user and the specific devices that a user can be attached to. This allows a single user to have multiple devices with the same phone number. It also allows a single device to be used by multiple users in a hot desk style environment, where a user logs into the device resulting in it becoming their phone.
The FreePBX DEVICE and AMPUSER Objects
As shown in Figure 2 FreePBX uses objects stored in the native Asterisk database, Astdb, to manage many of its internal features and in this case, the FreePBX Users and Devices.
DEVICE
Each EndPoint, regardless of the technology type, is stored in a unique FreePBX Device object. This is one of the simpler objects currently containing 4 vital fields:
dial:
How to contact the associated Endpoint. E.g. SIP/2212
type:
A device can be fixed or adhoc. A fixed device is permanently assigned to a single user. An adhoc device is available to be logged into by different users such as the hot desk example.
user:
The user that a fixed device is assigned to, or the user that an adhoc device is currently assigned to.
emergency_cid:
The CallerID associated with this device, vs. with a user, to be used when a call is placed on an emergency route. This allows a physical device to supply a CallerID associated with its physical location vs. a user’s CallerID which may be from a different country.
This DEVICE object provides the bridge between the specific technology (e.g. Endpoint SIP/2212) and the user that is currently associated with that device. It also provides an insulation layer that allows a different End Point to be easily substituted for another without any change to the rest of the system.
If your particular device is 320, you can see the details of that device by going to the Asterisk CLI and typing database show DEVICE/320.
End Point Identity
The Device information is fine for the FreePBX system to contact the device, however FreePBX needs a way to associate an End Point with a Device when the End Point is initiating the call. This is done by configuring the CallerID of the End Point to the Device number. For SIP, IAX and Zap devices, this is automatically handled by FreePBX. If you configure a SIP extension or device, you should see the resulting callerid = device <num> in the sip_additional.conf configuration, for example.
FreePBX User (AMPUSER)
Since FreePBX grew up in its youth as AMP (Asterisk Management Portal), it still possesses much of its heritage under the hood with naming conventions. The AMPUSER object represents the FreePBX user and can contain a wealth of information about that user depending on which modules and features may be enabled for them. The AMPUSER object associates a user/extension with its corresponding device(s) at any point in time.
Some of the core attributes of the AMPUSER object are:
cidname:
The Display Name associated with this user, used for internal calling only.
cidnum:
The extension number to be displayed with this user on internal calls. Usually the same as the user’s number unless they are masquerading their internal caller id.
outboundcid:
CallerID information (“Name” <num>) to be used for external calls (usually to the PSTN)
device:
All devices that are currently associated with this user. For example, if the user had devices 1320 and 2722 then the entry would be "1320&2722"
password:
A password this user would use to logon to an adhoc device
ringtimer:
Number of seconds to ring this user before failing over to voicemail or Call Forward Unavailable. (Set to 0 when using the system default.)
voicemail:
The voicemail context of this user, or novm if no voicemail
recording:
Recording settings whether or not to automatically record inbound/outbound calls or disallow them, or allow On Demand recording.
These fields provide the vitals to manage the given FreePBX user/extension and associate it with any number of devices. There are many other attributes that control features such as FollowMe or VmX Locater™ and others. If your particular user/extension number is 320 you can see all these settings by typing database show AMPUSER/320 at the CLI.
Many core functions and AGI scripts depend on this information to make the PBX function and deliver the rich set of features that are provided. We will look at one in particular to understand how the link is made when an Endpoint originates a call.
macro-user-callerid
When the End Point makes a call, it appears in FreePBX within the proper context that is configured with just its configured CallerID, that of the DEVICE previously discussed. In order to associate that device with the proper user, one of the first things that is done in the dialplan is to call Macro(user-callerid). One of the main things that this function does is to lookup the current identify of this End Point and associate it with the configured user’s identity (proper CallerID, etc.) so that the normal channel variables are properly configured. Doing this assures the proper internal and outbound CallerIDs are used and any other configurations for this user are known.
Calling a user’s extension
There is a bit more involved when you call a user which is beyond the scope of this part of our tour since it can involve many steps depending on what features the user may have enabled. At the basic level, calling a user results in FreePBX looking up all the associated devices that are defined in the user’s AMPUSER object. It then rings all of the associated End Points for those devices by looking up the dial field in each of those DEVICE objects.
Summary
We’ll wrap up this week and try to pick this up soon by exploring other corners under the FreePBX hood to see how more of the system works. We hope you find this interesting and useful. Tell us what you think or what other parts of the system you may wish to hear more about next.