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.