Course12:Basic - PBX - initial Configuration

From innovaphone-wiki

Jump to: navigation, search

This book explains the initial configuration of a PBX.


Installing the PBX

The PBX software is integral part of the link_intern.png gateways firmware. So there is no need to "install" it, as it is already there. However, in order to use it, it must be licensed and configured properly.

While working through this book, we will configure a PBX scenario step-by-step. To begin with, load the start configurations on to the devices now by clicking on PBX_-_initial_Configuration_Lesson.

As already known from Topic 2, uploading and refresh of the involved devices may take up to 5 minutes - so please stay patient. Your devices page should look something like this then:

screenshot.png devices page when devices are online

The PBX will be configured on the IP411LEFT then. Later on, a standby PBX will be installed. Use your IP411RIGHT for this.


Without a proper license installed, the PBX will not work. It will show up and allow configuration but phones will not be able to register. Details on licensing works is discussed in a separate book.

In this course, we will work without licenses, using the so-called test mode. This mode can be turned screenshot.png on and screenshot.png off for any device that needs licenses in General / License. When in test mode, the device is fully licensed with no limits. However, the test mode will automatically be turned of and the device rebooted after 8 hours.

In real life however, you will use real licenses of course. They are screenshot.png uploaded to the device in the General / License tab of the user interface.

PBX Modes

Single Master PBX

In a simple case, a PBX is running on a screenshot.png single gateway device. VoIP devices involved register to this PBX. This single PBX is know as the master.

To setup a PBX as master, you need to set the PBX Mode property in the PBX / Config / General tab to Master.


To ensure maximum availability, a PBX can have a duplicate, known as standby. This is a gateway device that can take over the role of the master should it fail for whatever reason. In normal operation, a standby PBX does not accept any registrations and does nothing except monitoring the PBX it is a standby for. This is done by screenshot.png registering to the active PBX.

When the active PBX fails, the standby will consider the PBX lost. In this case, the standby takes over. It will start to accept registrations and thus screenshot.png become the active PBX. It will go back to standby mode as soon as the master is available again.

A standby doesn't need to be a physical duplicate of the master PBX. The only requirement is that the standby can handle as much registrations and object definitions as the failing master had, so it is able to take over. In other words, an IP811 may well stand in for an IP411.

Master / Slave

There may be several reasons to use multiple PBXs in a customer installation:

  • load balancing
  • enhanced availability for remote locations
  • scaling
In this case, individual PBXs are setup in a screenshot.png tree-like structure with one being the master. All others are known as slave. Although the PBXs form a tree, the extensions registered to those PBXs do not. In other words, any extension can be registered to any of the PBXs.

In this course, we will discuss single master / master standby scenarios only.

Registration Strategies

When a VoIP client tries to register with its PBX, it may or may not have configured the IP address of the PBX. If not, the client can try gatekeeper discovery. This allows the client to find any PBX in the local network with zero configuration. Discovery is also available in SIP, however it is rarely implemented in SIP clients (innovaphone SIP does it). However, discovery works with UDP based protocols such as H.323/RAS or SIP over UDP only. If TCP based protocols are used such as H.323/TCP, H.323/TLS, TSIP or SIPS, discovery is not possible.

If discovery is not used or cannot identify the PBX, the PBXs IP address has to be made known to the client, e.g. by fixed configuration or by DHCP. To address fail over scenarios, the address of the standby PBX (known as alternate gatekeeper) may be configured.

When a registration has completed successfully, the client will continue to probe the PBX continuously by sending registration refreshes continuously (sometimes referred to as lightweight registration). When the active PBX fails, it will not answer to the registration refreshes. This allows the client to detect a PBX failure.

In that case, the registration is removed and the client starts trying to re-establish it. When there is no PBX IP address known, the client restarts discovery. If the PBX's IP address is known but no alternate, this address is continuously retried. If both primary and alternate are known, both are tried alternating.

If the primary PBX IP address is not configured and there is an alternate PBX IP address, then first gatekeeper discovery is tried and if it fails the alternate is tried.

PBX Failover

A standby PBX detects the availability of the PBX it stands in for by maintaining a registration to it. When the active PBX fails, the standby takes over. That is, it will start to accept registrations and thus become the active PBX. However, it will still try to re-register with its PBX.

Likewise, the other PBX clients will detect their failing registrations and will try to re-establish their registrations. This will succeed with the standby PBX now.

When the standby successfully re-establishes its registration with the PBX it stands in for, it will terminate all registrations it has and go to passive mode. The clients will re-start their normal registration procedures and will now be accepted by the original PBX again.

Shared PBX Properties

Some of the PBX configuration properties must be shared by all PBX instances (master, standbys and slaves). They are configured (amongst others) in the PBX / Config / General tab and need to be consistent through all PBXs in a system.

System Name

Identifies the PBX instances that belong to the same PBX installation. This allows to operate multiple PBXs in the same network. In H.323, this is used as the gatekeeper id. Even in a single master installation with no standby, this is required in order not to interfere with possible 3rd party VoIP entities. You should always use a meaningful name here.

Next to the System Name field, there is the Use as domain check-mark. If this is ticked, then the System Name assumes an important relevance for VoIP calls which leave the system (e.g. federation). Even if we will not expose our training PBX to the internet, you should always prepare your installation for doing so. So please have the mark checked! For now, simply make it a habit to screenshot.png use the customers email domain name as System Name. In this course, we use

Don't forget to confirm your entry with OK at the bottom of the window. Upon confirmation, you will see a red Reset required link appearing below the window. This happens when changing any settings which influence the system behaviour. So please reset the device - and refresh the page when the gateway is back in service.

PBX Password

PBX instances share a number of encrypted data, most notably user passwords. Such data is communicated in encrypted form between PBXs, so they all need to share an encryption secret (password), known as the PBX password.

The PBX password is used to authenticate a standby to the PBX it stands in for too.

It is screenshot.png set in PBX / Config / Security. In this course, use pwd.

Instance specific Properties

Each PBX instance has a number of fish-help.png properties that may be configured individually in the PBX / Config / General tab. Most of them influence the handling of calls that flow through this particular PBX instance.

PBX Name

To begin with, most of the default configuration will be fine as is. There is only one property for now that should be set explicitly, the PBX Name.
It should be a short name that identifies the physical location of this PBX. So, master is not a good idea, headquarter probably is!

For this course, we use - as a reminiscence to our headquarters - the name pbx-Sindelfingen.

Don't forget to confirm your entry and execute a possibly required reset!


When you have configured a DNS name (FQDN) in your DNS server for your PBX, you can enter it in to the DNS field. This is not really required as long as you do not intend to allow external access to your PBX. As we don't do this in this course, please leave the field empty.

Prefix for Intl/Ntl/Subscriber

In certain situations, the PBX needs to map numbers sent as International, National and Subscriber type of number. To this, it needs top know the various prefixes as well as the subscriber numbers of the trunk line used. As we will in this course use a (simulated wink) trunk line in Sindelfingen, Germany, the values shall be 000 for Intl, 00 for Ntl and 0 for Subscriber.

These are the dial prefixes users will need to call a destination of the type in question (e.g. to call an international number +49 (7031) 73009, the user would need to dial 0 (trunk access code) + 0 (leave your own area code) + 0 (leave your own country) -> 00049703173009).

While in many installations these values will be shared by all locations (and thus PBXs), they may differ across locations (e.g. if we have locations in several countries).

Device Name

At this point you may notice that your browser shows YourName: (empty) as title for the browser tab.

When working with innovaphone devices, you will soon have many browser tabs open for various devices. And - as they look so similar - you will easily get confused.

Fortunately, there is an easy fix for this: simply set the Device Name to a meaningful value for each device. This is done in General / Admin.

So set the Device Name property of your IP411LEFT to Your-First-Name: pbx-Sindelfingen now. Hit F5 (or whatever key your browser needs to refresh the tab) then to see the effect.

Required PBX Objects

A common error is failure to configure the required PBX node objects properly.

Each PBX in the PBX tree must have a corresponding fish-help.png PBX type object entry in the PBX / Objects object list. This is true even if there is only a single master. Configuring an object for a PBX may be confusing sometimes, so make a habit to configure the object for each PBX you set up right away.

The Name

In this course, as we are dealing with a single master only, the "PBX tree" is quite simple - it consists of this one master only wink. So the bottom line is: we need to configure a PBX type object on the master PBX for the master PBX. And it's Long Name (and Name) must be the same as the PBX Name in PBX / Config / General: pbx-Sindelfingen.

In the screenshot.png PBX object config the (short) Name needs to match the PBX Name in the screenshot.png Configuration / PBX / General tab.

The Parent PBX

For the master's PXB object, the Parent PBX must be the Name of the master itself, while the Parent Node must be root.

As we do not cover multi-node or multi-PBX setups in this course, you will never use anything but root as Parent Node. Also, for nodes that represent a PBX (as the ones we discuss here), you must never configure root as the parent PBX!

The Number

Any PBX object must have a number. Unfortunately, use of this number is not that obvious for nodes representing a PBX. So for now, make a habit and use numbers that are unlikely to be needed elsewhere ever, e.g. #002 etc.


There are various issues to consider regarding the security of a PBX, especially if it is accessible from the public internet. These will be covered in one of the advanced training modules.

IP Filter

However, in any case, you should set the fish-help.png IP-Filter property for authenticated and unauthenticated registrations in the PBX / Config / Filter tab to make sure endpoints register only from within networks you are expecting them to do so!

In this course, we will limit access to our own training network, so Addr in IP-Filter (registration without authentication) will be something like 172.31.xx.0 and the Mask


In some installations, users will only have restricted access to phone numbers. For example, a site administrator could decide to inhibit calls to premium rate numbers. This can be done by defining one or more fish-help.png Call-Filter in PBX / Config / Filter and assigning those filters to individual users. By default, two filters are defined, normal and unknown. The normal filter is used as a standard if not defined otherwise for a particular user, the unknown filter is used for extensions which are not yet fully booked in to the system (we'll come back to this topic later).

For now, you can leave the normal filter as is and define the unknown filter so that calls to the trunk line are impossible (that is, as our trunk line access code is 0, set to 0->nok).

Adding Users

In order to use a phone with a PBX, you need to create a fish-help.png user object in the PBX / Objects tab.

We will see how to configure such user objects in the course of the next chapters.

User Object Properties

The user object is one of the most generic of the PBX object types, so most of its properties are actually fish-help.png common properties shared by most objects. As all other objects are, it is created using the screenshot.png New link next to the object type drop down in the PBX / Objects tab.

The screenshot.png minimal configuration for a user consist of
  • the Long Name
  • the Name
  • the Node
  • the PBX
  • at least one entry in the Devices list
Setting those correctly is sufficient to register a phone to this user object. However, in reality you would probably want to assign a Number (a.k.a. extension) to the user, so you can call the user by dialling a number, although this is not strictly required.

Unless you intend to allow this user to register from arbitrary phones (hot desking), you should actually remove the automatic entry in the Devices list. It will be set later.

Also, you should check the E-mail check mark.

Finally, no object should be left with no Password for security reasons. So make a habit and assign one to every User object you create.

So we end up with a slightly modified screenshot.png recommended configuration.

Now go ahead and create a user with the following properties:

Long Name
John Doe
Node root
PBX pbx-Sindelfingen

How to set all these Names

So what exactly is a Name and a Long Name? The Name is a property you can use to call a user. Technically, you can call an extension using the destinations Name property just like you can using the destinations Number property. In contrast, the Long Name is what is displayed at the remote end when a user does a call. The Long Name must be unique system wide. So if you want a name to be displayed with a call that is not unique, you can use the Display Name property, which overrides the Long Name then and does not need to be unique!

You may ask yourself the question how you should set all these properties for objects you create. Here is a simple rule of thumb:
  • set the Name to the user's shortest email address leaving away the domain part (so if the user has an email of, then set Name to joe)
  • set the Long Name to the user's full name (e.g. Joe Satriani). Make sure the name is unique, if not so, add a department number etc. (e.g. Joe Satriani, Sales)
  • if you don't like the Long Name to be used as the display name, set a display name of your choice. Otherwise leave it empty


User objects (to be more precise: all objects) must not have similar extensions. So if you try to add an object and assign a Number which is already allocated to another object, the PBX will deny it. However, it will search for the next best free number and suggest it for use. So if you try to save the new object again, it will be created with the extension number found and suggested.

As phone numbers generally can be dialled digit-by-digit (overlapped sending), this also implies that one extension must not be a prefix of another. In other words: if you have an object with extension 9, then you cannot have another with e.g. 95, as 9 is a prefix of 95. The two extensions are considered similar (despite not equal).


In certain situations (e.g. when mailing an incoming fax to the user), the PBX needs to know the users email address. You can enter this to the E-Mail field. However, if you follow our recommendation to use the local part of the user's email address for the Name property, you can simply tick the check-mark next to the user's name just in front of the E-Mail field. This will tell the PBX to always use whatever is in the user's Name field as email address (the domain part is taken from the PBX's System Name field as we have ticked the Use as Domain check-mark before).


Another important property of a user object is the fish-help.png Device property. It consist of a list of pairs, the Hardware Id and the Name. If you create a new user object, the first device entry is created automatically. The Hardware Id of the object is set equal to the aforementioned mandatory attribute Name.

What's left

Within this course, as no multi-pbx or multi-node scenarios will be covered, the Node will always be root and the PBX will always be the Name of the node entry representing your single master PBX.

What a User Object is

It is important to understand that a user is not a phone. A user basically represents an extension (which is linked to a user, hence the object's name).

The PBX manages objects that an endpoint can register with. Such an endpoint might be a phone of course. However, more than one endpoint can register with the same PBX (e.g. User) object. If this does happen, it is said that there are multiple registrations for the object.

In addition to objects phones (or others) can register with, the PBX manages so-called Devices. Zero or more Devices can be configured for a PBX object. If there is no Device defined for the PBX object, no endpoint can register. So, more precisely, endpoints do not register with PBX objects, they register with Devices defined for PBX objects.

A fish-help.png Device has a number of properties. For now, we only look at one: the Hardware Id. This is the name that an endpoint must provide (possibly along with a password) to register with the Device and hence the PBX object.

Linking a Telephone to a User Object

Registering with a name

In order to use a phone, it needs to register with the PBX, more precisely, it needs to register with a Device defined for a PBX object. When the PBX receives a registration it will try to match the provided identification with one of the Hardware-Id values of an existing object. If there is a match, the registration is accepted (after potential verification of an associated password).

In fact, when an endpoint registers with a PBX object, it needs to present one of the Hardware Ids present in the Devices list as registering name. Although multiple registrations are possible using the same Hardware Id, it is best practice to screenshot.png define different Hardware Ids for different registrations (that is, registering endpoints). This way, you can screenshot.png distinguish the different registrations in the Device column of the PBX's PBX / Registrations tab. Please note that Hardware Ids must be unique in your entire PBX (as they are used to identify an object during registration). The Name however does not need to be (that is, the Name in the Device list. The one in the general part needs to be unique).

Registering with a number

Sometimes, endpoints will use an extension number instead of a name to register. So as an alternative, the registration may convey the Number of an existing PBX object. In this case, the PBX behaves like if the registration came in presenting the Name of the PBX object as registration name. In other words, to allow a registration with the PBX object's Name or Number, there must be a Device entry in the object that screenshot.png has its Name as Hardware Id.

While both methods work fine, there is a problem with both of it: in order to register a phone, it needs to receive a specific configuration (either name or number). This practically requires an administrator or advanced user to get the phone in hands and do the necessary configuration.

User Passwords

In a real life environment, user objects (more precisely: all objects) which shall allow an endpoint to register with, should have a password assigned for security reasons.

The user/object password is not used only for device registrations. User passwords are also used by normal end users to login to their web UI (that is, myPBX). This of course implies that users will change their password once in a while. If their standard hard phone is registered using the user password this will result in a non-functional phone, as long as the password is not changed in the device too.

You should thus make it a habit not to register phones using the user password. There are 2 methods to do so.

Use the device certificate

Each innovaphone hardware IP-phone has a built-in certificate. This can be used to verify its identity to other devices. This allows us to configure a Device in a PBX user object that allows a registration from a single device exclusively.

To do so, you would create a Device entry whose Hardware Id is screenshot.png equal to the serial number of the phone and whose TLS only check-mark is ticked.

Use the PBX password

To fix this issue, the other option is to screenshot.png tick on the Admin Pwd check-mark next to the respective Devices entry. If this is done, registrations do require the PBX password (as defined in PBX / Config / Security) instead of the user/object password. You would then configure the phone to use the PBX password to register. This option is especially useful for 3rd party devices which do not have a certificate.

Allowing personal ad hoc Registrations

To allow users to register other phones using their own password (e.g. to do an ad-hoc login on another telephone), you would add screenshot.png another Devices entry with Admin Pwd not checked. As an administrator, you should carefully decide if or if not to create such an entry. As you do not have control over the registration password (the user defines it), it presents a security risk!

To practice, configure all three variations as entries in the Devices list of the PBX User object John Doe. Use john.doe for the entry allowing ad-hoc registrations and john-doe-3rd-party for the entry allowing 3rd party phone registrations. Allow your IP111 to register based on the certificate.

Registrations without Password

In many installations, this may be a non-issue if the No of Regs w/o Pwd property in the PBX / Config / General tab is set to a value larger than 0 (which is the default, 1).

This property instructs the PBX to allow n (by default 1) registrations per PBX object to register without any password at all. This comes handy as the administrator does not have to deal with registration passwords for most of the telephones.

However, this obviously presents a security risk.

We therefore do not recommend to allow registrations without password. So please set this property to 0!

Setting Phones to send their Certificate

As discussed before, phones (at least innovaphone hard-phones) can send their identity in a secure fashion during registration. However, this requires use of a TLS based protocol and this in turn disables gatekeeper discovery.

So we need two settings on the phones to make registrations based on certificates possible:
  • the phones need to know the address of their PBX (that is, the gatekeeper)
  • the phones need to be configured to use a TLS based protocol

For backward compatibility, phones use UDP based H.323 and gatekeeper discovery by default.

Settings on the Phone

We could do these screenshot.png two settings on the phone (let's say the IP111) directly in Phone / User-1 / General. And we may have to do this for some phones (e.g. 3rd party phones). But fortunately, these parameters can also be set via DHCP vendor options.

To do so, we set the DHCP vendor options Primary Gatekeeper and VoIP Protocol in IP4 / ETH0 / DHCP-Server. screenshot.png The Primary Gatekeeper is the IP address of our IP411LEFT and VoIP Protocol is H.323/TLS.

Whenever you change DHCP options, you need to push them to all DHCP clients (otherwise they would be changed only after the current DHCP lease expires). You can do this by screenshot.png clicking on the Renew button on the bottom of this page.

In this case, we also changed the VoIP Protocol and this needs a reset on the phone. To make it effective, you need to power cycle e.g. your IP222. So it is important that you set these DHCP options before you roll out your phones.

Certificate Registration for Interfaces

We have seen how the phone can be registered to the PBX with no password based on its certificate. This can be done for interfaces too!

The device interface will behave similarly to a phone and send its serial number as registration name to the PBX when configured with no Name for the Internal Registration. However, to be able to distinguish the individual interfaces of the device, it will append the interface name to it. This will look like this in the PBX syslog:

20160122-183002 GK 0 REGISTER-IN(,H323=00903340007e-TEL1

Therefore, you need to configure the serial number followed by the interface name as Hardware Id in the Devices list of the PBX object to allow registration.

screenshot.png Certificate based Registration of Interfaces


In larger installations, it is clearly undesirable to have an administrator touch each phone in order to do the required configuration. Rather, the phones should be usable with zero configuration on the phone or using a procedure which just any end-user can do.

Using the Hardware-ID

innovaphone telephones feature a so-called "hardware registration" configuration. When not configured otherwise, a phone will use its serial number (which is the MAC address, e.g 009033280075).

As we have seen before, you could create an user object and screenshot.png add an entry to the Devices list with this registration name appearing as one of the Hardware-Id values in the Devices list.

If the PBX property No of Regs w/o Pwd. is set to a value greater then 0, the phone would then be able to register with this user object without any extra configuration on the phone.

If this property is set to 0 (which is the recommended configuration) however, the phone must identify itself to the PBX. This can be done using either a password (requires to touch the phone configuration which we want to avoid entirely) or H.323/TLS to provide the certificate to the PBX.

This allows an administrator to send out a phone to the end-user and pre-configure its Hardware-Id into the target user's PBX object. The only thing the end-user needs to do is to attach the phone to the LAN.

Dealing with unknown Registrations

When configuring the hardware-id into the PBX object properties, the administrator still needs to know the serial number of each users phone. This can be tricky if not impossible at all in a larger installation e.g. if the administrator does not install the phones personally.

To help here, the PBX features the ability to accept unknown registrations. For security reasons, this mode (Unknown Registrations) needs to be enabled explicitly in the PBX / Config / General settings.

If this option is enabled and a device tries to register with the PBX and there is no matching PBX object, then the device will be registered anyway and screenshot.png show up in the PBX / Registrations list.

The administrator now has the option to copy the registration name from the list and paste it into an Hardware Id entry in the Device list of the appropriate (user) object.

The other option is to screenshot.png click on the Long Name field of the registration and create a new User object in the PBX that has the proper Hardware-Id already set.

Be sure to turn off the unknown registrations when you are done. Otherwise, anyone will be able to register with your PBX!

Restricting Unknown Registrations to known Devices

It is possible to limit this function to incoming registrations from known devices. This adds a certain level of security. To do so, you need to tick the screenshot.png With PBX Pwd only check-mark.

Despite its name, the check-mark allows unknown registrations both from devices presenting a valid certificate as well as those presenting the PBX password.

For the PBX password method, the phones to be deployed must be screenshot.png configured with the PBX password as Authorization/Password in Phone / User-1. This has to be done by the administrator before, as end-users obviously should not know the PBX password.

For the certificate method, no preparation is required, as any phone already has a valid certificate installed.

Zero Configuration Deployment

When deploying many phones at a time, it can be tedious to relate entries in the registration screen to phones that are being deployed and thus to their appropriate PBX objects.

So when a phone registers as an unknown registration and the user then dials an existing extension (or more precisely, places a call to an existing object) and the object currently has no registrations and there is no entry in its Devices list (or the only entry in the list is identical to the object's Name), then the PBX will write the identification that came along with the unknown registration into a new entry in the Devices list. It will then terminate the unknown registration.

The endpoint that had the unknown registration will try to re-establish its registration and this time, the PBX will find a match between the identification provided and a user entry and will accept the registration on behalf of this object.

This allows users which receive a new phone (either during deployment or as a replacement) to simply attach the phone to the network and call their own extension and they are done. If users don't know their extensions (i.e. during a new deployment when the numbering plan is new or has changed), they can call by just typing their own name or selecting their own entry from the systems user directory.

TLS only/PBX Pwd

When the phone was registered with the admin password, the PBX will set the PBX Pwd check-mark for the added Devices entry. When the phone was registered with TLS and a valid certificate, the PBX will set the TLS only check-mark.

To practice, please
  • configure the PBX to allow unknown registrations from known devices
  • add a new user with Number 13, Long Name Richard Roe, Name richard.roe and Password pwd
  • call extension 13 on your IP222

Your IP222 should now register as Richard Roe.

Personal tools