FusionPBX Internal Server Architecture

Now that I am working with some friends, I have been asked to teach them how to deal with the command line to do some basic troubleshooting. To accomplish this, I believe the first step is the understanding of the main elements of a FusionPBX server and how they interact with them. So here it is.

Please note that this article is agnostic of having a stand-alone server or a cluster deployment.

The Big Picture

A FusionPBX deployment usually depends on four daemons:

• Apache or NGINX+PHP: whose main function is to display the HTML frontend, the one that we know as FusionPBX UI. Some other auxiliary PHP script run here as well.
• Memcached: the main function is to save direct queries to the database, as consequence the PBX performance will improve.
• MariaDB or PostgreSQL: this is the place where all the data is stored. This article is assuming this deployment has everything stored in a database, other deployments may use SQLite and use an independent local database.
• FreeSWITCH: the one that gives the support to the SIP and RTP protocols.

The following diagram shows them.

There is a fifth element who is not a daemon. The Lua scripts which I will write about them later.

The HTTP Server

Whatever is your preference, Apache or NGINX+PHP-FPM, the HTTP server is the one that displays the PHP part of FusionPBX. Each time you create an extension, modify an IVR or set up a DID, the HTTP server (well the PHP scripts), will interact with the FusionPBX database and flush the Memcached if necessary. If you need to do some other management actions, such as reloading a module, monitoring a call or watching who is registered, the PHP scripts will interact directly with the FreeSWITCH daemon to ask this kind of information.

The Database Server

The database, MariaDB or PostgreSQL, is where all your data lives. A common database deployment will create two databases: fusionpbx and freeswitch. The fusionpbx database is where all the juicy information resides: extension, IVR's, ring-roups, CDR and much more elements. On the other hand, the freeswitch database holds the live operation information; when an extension registers to the FreeSWITCH daemon, a new record in the freeswitch database is added/updated, when a new call is connected, some records in the same database are updated as well. This will drive to the thought of why a freeswitch database, the answer is easy. The freeswitch database is the angular stone for a load-balanced or a high availability cluster.

The Memcached Server

Memcached function in this kind of deployment is not to share information but to speed it up. Each time an element is accessed by the XML Handler (read below), a copy of the element is stored in order to save future database queries. A Memcached server will always server the requested object faster than a database, and even if theMemcachedd does not have the requested object, you only wasted few mili-seconds. Having a Memcached is optional, but it really helps the speed.

Some LUA scripts may use the Memcached server to store volatile information as well.

The XML Handler and Supporting Scripts

Before explaining the FreeSWITCH, it is important to explain what is the XML Handler and the suppporting scripts. FusionPBX is not the only PHP, it includes as well a set of LUA scripts. Many of them are just helping in the call flow, for example, the black list application or the call screen one. But there are others that are much more important than that, those that gives life to the XML Handler.

The XML Handler is a FreeSWITCH internal element that as the same says, it deals with the XML. FreeSWITCh internals need all the information in XML format. When you install a vanilla FreeSWITCH server, without FusionPBX, you will see many examples of dialplans. If you open one of those files, you will see that everythign is in XML. Therefore, the XML Handler is the bridge between the database and the XML that the FreeSWITCH needs.

When a registration event happens, the FreeSWITCh daemon send a request to the XML Handler for information about a given extension. The XML Handler will not take the authorization task, it only sends data in the correct format. The XML Handler will connect to the fusionpbx database and query for the extension data. After getting the answer from the database server, the XML Handler will format the given data and sends it back to the FreeSWITCH daemon. Then, the FreeSWITCH daemon will make the call about letting or not the extension finish the registration process.

It is not a must that the XML Hander is written in Lua or to be local scripts. There are many other ways to write one (other languages or remote XML Handler scheme), but the Lua language has always been the preference because of the run-time speed. If you were thinking how the XML Handler relates to the database and how to speed it up: yes, the XML Handler may call the Memcached daemon before the database to see if the information is there.

One advantage of using the XML Handler is that you do not need to send reloadxml signals each time you modify something. FreeSWITCH will not remember data if you are using an external XML Handler. This is very handy if you are writing dynamic systems that needs to get different dialplans based on external conditions.

The FreeSWITCH Daemon

The FreeSWITCH daemon is the one who gives life to the PBX system. Thing on it as the heart of the VoIP deployment. The FreeSWITCH daemon will deal with the SIP and RTP handling, but that is not all the functions; one of its more popular functions is the event handler. The event handler is the way the FusionPBX PHP scripts, or any other external software, communicate with the PBX and send some orders. When you ask the FusionPBX Web UI to display the current calls, the PHP scripts connect to the FreeSWITCH daemon and ask for the current calls. The Event Handler will send the information and the PHP scripts will format in a beautiful way for you.

Each time an event happen, for example, a registration, a call, a new call queued, the FreeSWITCH daemon will store the operation data into the freeswitch database. This information is considered volatile, but very handy if you need to write something that manipulates information or that gives a comprensive information about the FreeSWITCH daemon status.

With this brief overview, I think now we are clear how the elements work. I will write later who they interact when someone register or a call is placed.

Good luck!