Help for Integrators

From Askozia Handbook
Jump to: navigation, search


Contents

The Integrator Panel

The Integrator Panel provides additional configuration possibilities which are not available in the web interface. In this way you communicate directly with Asterisk and can directly edit its configuration files. You get access to the Integrator Panel by pushing escape (esc) in any point in the web interface. The Integrator Panel is divided into four sections: Console, Asterisk Manager Interface, Configuration Files and Beta Features.

The Integrator Panel


Console

With the console you communicate directly with the underlying Linux operating system. You can also use SSH (Secure Shell) if you will be spending significant time in the console. Due to the high number of scenarios you can use the console for we just give a couple of practical examples here.

Enter the command ps to list all running processes.

$ ps
PID USER       VSZ STAT COMMAND
1 root      1360 S    init       
2 root         0 SW<![CDATA[<]]>  [kthreadd]
3 root         0 SW<![CDATA[<]]>  [ksoftirqd/0]
4 root         0 SW<![CDATA[<]]>  [events/0]
5 root         0 SW<![CDATA[<]]>  [khelper]
9 root         0 SW<![CDATA[<]]>  [async/mgr]

free shows the memory usage.

$ free
           total         used         free       shared      buffers
Mem:       382716        27984        354732     0           596
Swap:           0            0             0
Total:     382716        27984        354732

uptime shows the uptime and the average load of the system.

$ uptime
15:54:42 up  1:30, load average: 12.00, 7.00, 4.00


Asterisk Manager Interface

The Asterisk Manager Interface (AMI) is a powerful tool for communicating with Asterisk. Understand that this section is a brief insight of the capabilities of the AMI. More Information can be found in the Asterisk documentation.

help lists all commands of the AMI. To narrow down the search for a specific command enter "help" followed by a keyword. This lists all related commands with a description. The command help core for example, lists all commands containing the word "core".

core abort shutdown - Cancel a running shutdown
core restart gracefully - Restart Asterisk gracefully
core restart now - Restart Asterisk immediately
core restart when convenient - Restart Asterisk at empty call volume
core set debug channel - Enable/disable debugging on a channel
core set {debug

You can also put "help" in front of every command to get a description of the command. If you enter help sip show peers this leads to the following output:

sage: sip show peers [like <![CDATA[<pattern>]]]>
	  Lists all known SIP peers.
	  Optional regular expression pattern is used to filter the peer list.

The command sip show peers from the last example lists all known SIP peers. In this case there are four SIP peers (three phones and one provider). The phones 105, 109 and the provider are registered, phone 108 is offline.

Name/username              Host            Dyn Nat ACL Port     Status     
105/xxxxxxxx               xxx.xx.xx.xxx    D   N      xxxxx    OK (24 ms) 
108                        (Unspecified)    D   N      xxxx     UNKNOWN    
109/xxxxxxxx               xxx.xx.xx.xxx    D   N      xxxxx    OK (12 ms) 
SIP-PROVIDER-91306662834c  xxx.xx.xx.x          N      xxxx     OK (20 ms) 
4 sip peers [Monitored: 3 online, 1 offline Unmonitored: 0 online, 0 offline]


Configuration Files

As an experienced Asterisk user you can edit the Configuration Files directly. Choose your desired configuration file and click on edit. Two modes for editing are available: Append and override. If you choose append, your additions will be written at the end of the configuration file. If you choose override, all text in the configuration file will be overwritten with your changes.

Asterisk Configuration Files

If you, for example, would like to make an application available under the extension "0099" which is echoing everything the caller says: You can achieve that by entering the following code in the configuration file "extensions.conf". Use the "Append" mode for this.

[internal](+)
exten => 0099,1,Answer()
exten => 0099,2,Echo()
exten => 0099,3,Hangup()

If you, for example, would like to automatically load all Asterisk modules by default, enter the following code in the configuration file "modules.conf" whereas using the "Override" mode.

[modules]
autoload=yes


Beta Features

Beta Features are hidden features which are not yet complete or stable enough to appear in the web interface. If you would like to provide feedback, visit our forums on [1].


Linux console

Alternatively to the integrator panel, the Linux console can be accessed through the console menu of AskoziaPBX immediately after starting the phone system. Enter '9' and confirm by pressing 'Enter'.

Askozia console options

Further information about the console menu of AskoziaPBX are provided in the Askozia Console and Console Options sections within the Getting Started with AskoziaPBX menu.


Import configuration via console

Follow the steps below, to import a config.xml file through the console.

1. After connecting a monitor, start the PBX and wait for the console menu to appear.
2. Enter '9' to access the Linux console.
3. Enter the following command.

 ls / dev / sd *

4. Connect the hard drive that contains the XML configuration to the USB port. 5. Enter the following command.

 ls / dev / sd *

6. Note which drive is added (for example, sdc1). 7. Enter the following command.

 mkdir / usb

8. Enter the following command.

 mount -r / dev / sdc1 / usb /

9. Enter the following command.

 remount mount -r -w / cf /

10. Enter the following command.

 cp -r /usb/backup-path-and-name.xml /cf/conf/config.xml

11. Enter the following command.

 reboot

At this point, the desired configuration should have been successfully imported and applied.


Accessing AskoziaPBX through SSH

In many situations, it may be useful to access the system through SSH. Depending on the operating system, whence this should be done, different steps are required.


SSH on Unix-based systems

First, a terminal window needs to be opened. The connection is then established by means of the following command.


ssh root@[Askozia-IP-address]

A password is required. Enter the password of the web interface to access the Linux console of AskoziaPBX.

In order to access the Asterisk console, an additional command is required as shown below.


asterisk -r

Zugriff auf die Asterisk Konsole


SSH on Windows

At first, a terminal program needs to be downloaded and installed. In this example, the program PuTTY is used. Under session, the IP address of the target system is entered as host name. The default SSH port is 22.

PuTTY, session configuration, assigning IP address


Manual Attributes

Manual Attributes can be used in different contexts. The attributes defined are only valid in their contexts. For this reason there are different locations in the web interface where you can define manual attributes. You find these in the Advanced Settings of the different telephone and provider types. When defined in this context they are only valid for this particular phone or this particular provider.

To define manual attributes for a global (system-wide) context for all phones and providers of a certain technology, these attributes need to be defined in the SIP, IAX or Analog/ISDN settings of the Advanced menu. These attributes are valid in the Asterisk [general] context and overwrite all existing manual attributes for the respective technology.

Manual Attributes

To, for example, set the User Agent field for SIP messages globally, enter useragent = myText in the text box for manual attributes and click Save.

useragent = myPBX

You can find an overview of all existing manual attributes in the documentation of Asterisk.


Manual Dialplan Incoming/Outgoing

Manual Dialplans can be used in different contexts. Each dialplan is only valid within its context. For this reason there are different locations in the web interface where you can define manual dialplans. You find these in the Advanced Settings of the different telephone and provider types. When defined in this context they are only valid for this particular phone or this particular provider.


Blocking outgoing numbers

To block numbers, such as special service numbers, the following commands have to be entered in the Manual Dialplan Outgoing of the desired phones or providers. The following screenshot shows blocked 0800 and 0900 numbers and those, starting with 01. The commands can be modified at the marked positions for different numbers.

Blocking special service numbers

Configuring 00.+, blocks all international prefixes.

Blocking international numbers


Exception for blocked numbers

Blocked numbers in a provider account cannot be called from all internal phones via this provider. If exceptions for single phones are required, the following command has to be entered in the Manual Dialplan Outgoing of the desired phone account.

Exception for blocked numbers


Codecs

A codec defines how audio and video data is transported over a network and the quality of the data. If the speech quality is too low or it drops out or sounds robotic it might make sense to try a different codec. A common reason is insufficient bandwidth of the internet connection.

We differentiate between compressed and uncompressed data. Furthermore, we differentiate between lossless and lossy compression.

A codec is always a compromise between used bandwidth, required computational power for the compression of voice data and the speech quality. Wideband codecs make voice transmission in hi-fi Quality possible. This is not supported by all types of telephones, though. Narrowband codecs allow voice transmission even using poor bandwidth. Consequently, speech quality suffers. We recommend a bandwidth of 100 kBit/s in both directions.

Audio Codecs

AskoziaPBX supports a variety of free and licensed codecs.

MOS (Mean Opinion Score) is a measurement method for comparing codecs. A representative group evaluates how close speech quality of the codecs is to the human original. The scale is 1 (bad quality) to 5 (best quality). Everything better than 4 meets the speech quality of the conventional telephone network.

Codec Bandwidth MOS-Score Quality
G.711u-law 155 kBit/s 4,3 good (USA and Japan)
G.711A-law 180 kBit/s 4,4 very good (Europe)
GSM 60-90 kBit/s 3,8 satisfying
G.722 180 kBit/s 4,5 very good
G.723.1 60 kBit/s 3,8 satisfying
G.726 (AAL2) 100 kBit/s 3,8 satisfying
G.726 (RFC3551) 120 kBit/s 3,8 satisfying
G.729 70 kBit/s 3,92 satisfying
iLBC 80 kBit/s 4 satisfying
SpeeX 60-120 kBit/s 4 satisfying
ADPCM 16-64 kBit/s - -
16 bit Signed Linear PCM 64 kBit/s 4 satisfying
LPC10 2,4 kBit/S - -
Codec Overview

In the following table you can see how long it takes to translate one codec into another one and for which codecs the translation works in general. The unit of measure is microseconds. The longer this takes, the more it contributes to the round-trip times in a conversation. Conversations start to become awkward with more than 200 milliseconds of round-trip time.

Translation times between formats (in microseconds) for one second of data
Source Format (Rows) Destination Format (Columns)

	g723 gsm ulaw alaw g726aal2 adpcm slin lpc10 g729 speex ilbc g726 g722 slin16
g723     -    -    -     -      -     -     -     -   -   -      -     -     -      -
 gsm     -    -  3000  3000   7999  3000  2000  9999  -     -    -  6999  4999  10998
ulaw     -  5999   -   1000   6998  1999   999  8998  -     -    -  5998  3998   9997
alaw     -  5001     1     -  6000  1001     1  8000  -     -    -  5000  3000   8999
g726aal2 -  9999  5999  5999     -  5999  4999 12998  -     -    -  9998  7998  13997
adpcm    -  6000  2000  2000  6999     -  1000  8999  -     -    -  5999  3999   9998
slin     -  5000  1000  1000  5999  1000     -  7999  -     -    -  4999  2999   8998
lpc10    - 10999  6999  6999 11998  6999  5999     -  -     -    - 10998  8998  14997
g729     -     -     -     -     -     -     -     -  -     -    -     -     -      -
speex    -     -     -     -     -     -     -     -  -     -    -     -     -      -
ilbc     -     -     -           -     -     -     -  -     -    -     -     -      -
g726     - 10000  6000  6000 10999  6000  5000 12999  -     -    -     -  7999  13998
g722     -  8999  4999  4999  9998  4999  3999 11998  -     -    -  8998     -   5999
slin16   - 13999  9999  9999 14998  9999  8999 16998  -     -    - 13998  5000      -

Using drag-and-drop you can enable or disable codecs. Blue highlighted codecs are active, red highlighted disabled. The order of the codecs is also the priority in which they are used.

Audio codecs

Video Codecs

H.261 (from 1988) is the codec for digital compression and decompression of video signals. Originally developed for video telephony via ISDN lines. H.261 was the first digital video standard codec. H.263 (from 1995) and H.264 (from 2001) are based on H.261.

All standards are optimized for low data transfer rates and little movements within the images. Constant data transfer rates are not defined. H.264, as the newest standard, can also handle high resolution image data.

Using drag-and-drop you can enable or disable codecs. Blue highlighted codecs are active, red highlighted disabled. The order of the codecs is also the priority in which they are used.

Video codecs


How to integrate custom voice prompts

To use additional voice prompts with AskoziaPBX which are not included in the standard software, please perform the following steps.

We assume that you have already downloaded your desired voice prompts in an Asterisk conform file format. An overview of Asterisk voice prompts can be found here. If you want to use your own voice prompts, please note that the file names have to be identical to the Asterisk sounds.

Download page for audio prompts


Connect to AskoziaPBX via a SFTP program (i.e. Fugu or WinSCP) and open the directory of you storage.

User: root

Password: "you chosen web interface password"


Go to Storage -> usbdisk1 -> askoziaPBX -> media

AskoziaPBX folder directory


In folder sounds you find the languages. Create a new folder, named custom1, custom2 or custom3.

Media folder - custom1


Copy your voice prompts into the new folder. Please make sure that directory tree, file names, and file formats are equal to the other languages.

Soundfiles


To use the new prompts, choose i.e. "Custom1" for phones and/or providers in the AskoziaPBX web interface.

Set language


Click Save to finish the configuration.


Provider-specific configurations

1&1

1&1 is a German VoIP trunking provider that distributes inbound phone calls between several servers. Therefore, calls can arrive from different IP-addresses to your AskoziaPBX. In order to avoid these calls from unknown IP addresses being rejected, all respective server IP-addresses have to be entered into the AskoziaPBX web interface.

In order to enter the addresses, open Askozia’s web interface and go to the provider account settings of 1&1. Select "Advanced options" and enter the addresses in "Multiple Hosts" as shown below.

Part of the 1&1 server list


Callcentrix

To configure Callcentrix, enter the commands below into the Manual Attributes text field of the Advanced Options of the provider account.

progressinband=yes
session-timers=refuse
disallowed_methods=UPDATE
Manual attributes for Callcentrix configuration


Deutsche Telekom IP


Deutsche Telekom ISDN

Deutsche Telekom is a provider of ISDN connections in Germany. In order to use their ISDN connections with AskoziaPBX, the following configurations need to be done. It is assumed that the configuration of the ISDN provider ports has been successfully done, as outlined in ISDN Phone and Provider Ports.

After creation of the ISDN provider account, the following steps must be followed.

First, configure the basic settings. Bear in mind the correct assignment of the hardware port or port group.

General settings

Then have the incoming dialing patterns, as seen in the image are assigned.

Call forwarding

Please configure the next outbound caller ID. This can be done in the provider account or in the phone accounts. It is important that the number format is entered correctly.

Caller ID

For the regional settings, please proceed as follows.

Regional settings


Easybell

The German-language video below introduces Easybell, a VoIP provider based in Berlin, Germany. Furthermore, an Easybell SIP trunk is configured with AskoziaPBX and the Easybell customer portal is introduced.

Easybell Business Voice

The following video shows in German how AskoziaPBX is configured with an Easybell Business Voice connection.


A1 Telekom Austria

If a provider account for A1 Telekom Austria is set in AskoziaPBX, it must be ensured that the following two points are met.

  • Echo-Canceling has to be deactivated in the port settings of the beroNet card
  • The switching type must be set to National Type 1
A1 Telekom configuration


CallControl

This section explains how to set up CallControl with AskoziaPBX. CallControl is a third-party CTI (Computer Telephony Integration) software for Mac OS X with Asterisk that allows you to dial phone numbers from your desktop. Information about the CallControl software itself can be found on www.callcontrol.us.

Setting up CallControl

CallControl with AskoziaPBX can be set up according to the following steps.

1. Open the Askozia web-interface in your web browser and click on "Open admin interface".

2. In the menu on the left side, click on "Advanced" and subsequently on "Manager".

3. Activate the check box "Make AMI available from the outside".

Activating Asterisk Manager Interface (AMI)

4. Click on the green "add" button on the right-hand side below the header "Asterisk Manager Interface".

5. Specify the following configurations.

  • Username: Choose a CallControl username, such as cti1, and write it down.
  • Secret: Choose a CallControl password and write it down.
  • Deny Network: 0.0.0.0 / 0.0.0.0
  • Permit Network: State network and netmask of your computer.
  • Read: Turn on the following check boxes: agent, call, user, verbose.
  • Write: Turn on the following check boxes: agent, call, originate.
Adding a CallControl user account in AskoziaPBX

6. Click on the "Save" button.

7. Click "Save" once more in the "Manager" screen.


Determining phone extension and context

Now you need to find out the extension and the context of the phone to be used with CallControl. For this purpose, follow the steps listed below.

1. Make sure that you are still in the AskoziaPBX admin interface.

2. In the menu on the left-hand side, click on "Accounts" and subsequently on "Phones". A list of the phones registered with AskoziaPBX will appear.

3. Click on the number of your extension, which is "101" in the present example, and write it down.

Example for SIP phone accounts list

4. The web interface will present you all options to configure this phone. However, these are not important at this point. Instead, click into the address bar of your web browser to see the complete address of the website you are visiting right now.

Web browser address bar while being on the SIP phone account

5. Select and copy the part of the address behind "uniqids=". This part normally starts with "SIP-PHONE-<some id>"

6. This is the "context of your phone". Write it down to set it as the context in the CallControl preferences.

At this point, you gathered all information to setup CallControl with AskoziaPBX.


Configuring CallControl

Before configuring CallControl for AskoziaPBX, please make sure you finished setting up AskoziaPBX for CTI integration as explained in the previous subsections. If you have finished the setup, follow the next steps to configure CallControl for AskoziaPBX.

1. Open "CallControl"

2. Click on "Preferences..." in the "CallControl" menu

3. Open the tab "General" and set the following preferences:

  • Hostname: Enter IP or host name of your AskoziaPBX system.
  • Port: Enter 5038.
  • Username: Enter the username you have set up previously for Asterisk Manager Interface (AMI)
  • Password: Enter the password (called "secret" in the Asterisk environment) you have set up previously for this user.
  • CRAM MD5 Auth: Enable.
  • Asterisk Channel: Specify "SIP/extension", for example "SIP/101"
  • Dialout Context: Enter the context of your phone as described in the previous subsection.
  • Dialin Extension: Specify the extension number, for example "101".
  • Dialin Context: Enter "internal".
CallControl, general preferences

4. Open the "Phone" tab and set the following preferences.

  • Caller ID: Enter the "extension number", for example "101".
  • FXO Prefix: Enter "3".

5. Set up the other options like "Dialing Prefix", "Country Code", etc. based on your requirements.

6. Finish the configuration by closing the preferences and restart CallControl.


Softphone configuration

Juggler

This section explains the steps that are necessary to set up and connect a Juggler soft phone with AskoziaPBX.

1. First, a new account needs to be set up in Juggler. Open the Proxy settings and enter your data. Save your configuration.

Creating an account in Juggler


2. Second, a soft phone account needs to be set up in Askozia's web interface. Save your configuration.

Creating an account in Askozia


3. After saving the new phone account in Askozia's web interface, it will be listed in the overview as shown below. The green light indicates that the connection between AskoziaPBX and Juggler has been established successfully.

Askozia web interface, successfully connected with Juggler


4. The established connection also is indicated in Juggler, by means of the green WiFi symbol.

Juggler, successfully connected with AskoziaPBX


5. In Juggler, a new contact can be added by right-clicking on Contacts.

Juggler contacts overview


6. Enter and save the contact data. Most importantly, the bottom part of the configuration needs to be completed, and Activated needs to be set to Yes.

Creating a new contact in Juggler


7. After saving your changes, your new contact will be listed in the Jugglers contact overview. The busy lamp field (BLF) shows the contact status. In this example, the BLF is green and indicates that the contact is available.

Juggler, contact is available


8. The BLF turns red, if the contact is having a phone call.

Juggler, contact is unavailable


9. A contact not being registered, is indicated by a clock symbol in the BLF, as shown for John in this example.

Juggler, contact not registered


10. If a contact tries to call another person, his BLF turns red and marks him as unavailable, as shown for Phil in this example.

If a contact receives a call by another person but does not yet answer, his BLF turns orange, such as for John in this example.

Below this contact, a yellow field appears showing the caller. By clicking on this field, you can pick up the call.

Juggler, call pick-up


11. After picking up the call, the conversation gets established and your status display gets updated.

Juggler, a call is established
Juggler, status during phone call


TAPI

There is no TAPI interface included in AskoziaPBX, but it's possible to use several third party Asterisk TAPI interfaces.


How to integrate Phone Suite TAPI for Asterisk

To connect an AskoziaPBX with Phone Suite TAPI, please follow the steps below.

Create a new account in the AskoziaPBX web interface Advanced -> Manager -> Asterisk Manager Interface.

Phone Suite configuration - Askozia Webinterface


Install Phone Suite and start the application. Click configuration to enter the setup.

Phone Suite configuration setup


Create a new TAPI-Line and open its setup.

New TAPI-Line


Enter the information like shown in the picture. And when done, restart the AskoziaPBX.

Entering data


Open Integrator Panel -> AMI and enter manager reload

Enter manager reload into the Integrator Panel


Choose the desired telephone and copy its context.

Get the SIP-ID of the desired telephone


Enter the telephones data into the TAPI cofiguration.

Enter the data into the TAPI


After a reboot, Phone Suite TAPI will connect to AskoziaPBX.

To initiate a call via Outlook, open a business card and click Call -> Desired number

Initiate a call


Door intercom systems

Baudisch Intercom

Baudisch Intercom is a German manufacturer of door intercom systems, located in Wäschenbeuren. The following German-language video introduces Baudisch Intercom as a company and its product portfolio as well as the configuration of an IP door intercom system with AskoziaPBX. The remainer of this section explains how to setup Baudisch Intercom door intercom systems and camera modules with AskoziaPBX.


Baudisch SIP intercom system

To set up a Baudisch SIP intercom system, you must first configure the network settings correctly. The SIP module can have the following default IP addresses ex factory.

  • 192.168.0.105
  • 192.168.1.200
Baudisch SIP intercom system, network settings

1. Configure a phone with the number 5000 within AskoziaPBX.

Baudisch SIP intercom system, SIP-phones

2. Configure a call group that will be called from the intercom system (when the doorbell is rung).

Baudisch SIP intercom system, editing call groups
Baudisch SIP intercom system, displaying call groups

3. Click "Quick Start" to do a quick configuration.

Baudisch SIP intercom system, main menu

4. Configure the required modules (ringing, function modules) and change the device's password if necessary.

Baudisch SIP intercom system, quick start

5. Set up a number for the central phone (or switchboard). This number (in this example, 5001) is dialed on demand from the door intercom system.

Baudisch SIP intercom system, central phone

6. Set up a number for the doorbell. This number (in this example, 5001) is dialed on demand from the intercom system .

Baudisch SIP intercom system, call destination

7. Enter the SIP data of the previously established SIP phone (5000) in the door intercom system.

Baudisch SIP intercom system, SIP data


Baudisch CAM-Modul

In order to set up a Baudisch Intercom CAM module, you must first configure the network settings accordingly. The CAM module may have the following default IP addresses ex factory.

  • 192.168.0.180
  • 192.168.0.185
  • 192.168.1.220

1. Click on "Configuration" to configure the CAM module.

Baudisch CAM intercom system, menu

2. Define a general fixed IP address for the module and login data if necessary.

Baudisch CAM intercom system, CAM module configuration, part 1
Baudisch CAM intercom system, CAM module configuration, part 2

3. You can now access the camera of the CAM module directly via the web interface. To use the camera image with a telephone, use the following URLs:

Baudisch CAM intercom system, Snom display
Baudisch CAM intercom system, Snom configuration
Baudisch CAM intercom system, Gigaset display
Baudisch CAM intercom system, Gigaset configuration

These URLs can be stored either in the local phone book of the respective phone or as doorbell image if the phone directly supports door intercom systems.


How to disable notice messages in log files

To disable notice messages in the log files, please perform the steps below.

  • Open the Integrator panel in AskoziaPBX. (press esc)
  • Open the tab Configuration files and choose logger.conf.
  • Activate override and delete notice from line syslog.local0….
  • Click save
Manipulation of "logger.conf"
  • Switch to the AMI tab and enter the command reload logger.
reload logger

No notice messages will not appear in the logs anymore.


Debugging interface cards

This section shows which steps are necessary to debug interface cards of different technologies.

DAHDI cards

Analog ports

Section in progress.

ISDN ports

State of the ISDN port is gray

ISDN port remains indicated gray

It is checked whether the LED on the card will turn green. If this is the case, the card is temporally synchronized. This condition indicates a configuration problem.

Either the same cards have been recognised twice or proper configuration of the card by the system has failed. In this case, it is recommended to manually delete the existing port cards from the AskoziaPBX web interface and subsequently re-initialize the card by restarting AskoziaPBX. Bear in mind that ISDN connections are only properly detected and accordingly represented by the LED, if a provider has been created for the respective port.

The following command checks which DAHDI cards have been detected.

Console: dahdi_scan

Console, detected DAHDI cards

In this image, the ISDN card and its individual ports has been recognised. If the card is properly recognized by DAHDI, the following command lists the main DAHDI configurations.

Console: cat /etc/dahdi/system.conf

Console, DAHDI configuration listing

Variables without assigned values are checked in the web interface of AskoziaPBX. Use the following command to get more information.

Console: cat /etc/asterisk/chan_dahdi.conf

Console, DAHDI channel configuration listing

This file contains the actual channel configuration. Again, the output is checked for missing values ​and anomalies are checked accordingly though the AskoziaPBX web interface.


State of ISDN port ist red

ISDN port is indicated red

There is no physical connection between the NTBA and card port. This can be checked by using the command Console: pri show spans. On the picture below, the ISDN line is indicated as "down", i.e. not connected.

Asterisk Manager Interface, ISDN "down"

By using the command Console: pri show span 2, further information may be accessed (in this case, for port 2). In case of an interrupted line, the following output is shown.

Asterisk Manager Interface, ISDN channel details in case of "down"

If a physical connection is established, "pri show spans" leads to the following output.

Asterisk Manager Interface, ISDN "up"

The detail view now shows the following output.

Asterisk Manager Interface, ISDN channel details in case of "up"


Port of ISDN card is yellow

ISDN port is indicated yellow

The card is recognized and a provider was established. Either the connection type of the port is incorrect (PTP, PTMP) or the port is not synchronized. To synchronize the connection, it helps in most cases to simply initiate an outgoing call through this port.


Port of the ISDN card is green but incoming/outgoing calls are not possible

ISDN ports are indicated green

It is necessary to check whether the outgoing number is set correctly. Most providers do not allow outgoing calls with a falsely set outgoing number. This needs to be checked in "Provider account" -> "Caller options" -> "Outgoing Caller ID". Additionally, the "Type of Number" in "Provider account" -> "Regional settings" has to be set to "unknown" in both cases.

If incoming calls are not possible, the cause is usually a problem with the incoming dial patterns. The provider is to be checked by means of a single empty field, causing him to catch all incoming calls at first and forward them to one phone as explained in the Incoming Extensions section of the Accounts chapter. As soon as this works, you should enter the head number of the port and check the log entries.

Log message, incoming call could not be assigned to an internal telephone

The previous image shows that the incoming call could not be assigned to an internal telephone. This can be fixed by entering the number received from the logs into the incoming dial patterns, thus making the number available from the outside. For ISDN, there are only finite possibilities for a correct outgoing number.

Example:

An ISDN connection is given with the following number block:

  • 053318042181
  • 053318042182
  • ...
  • 053318042189

In this case, the following possibilities for outgoing caller IDs exist for the number 053318042182.

  • 053318042182
  • 53318042182
  • 4953318042182
  • 004953318042182
  • 8042182
  • 2

If these variants have been tested, "TON (local)" can be checked. It is not to be confused with the TON of the dialled number!

Provider account, regional settings, type of number (local)

"TON (local)" is now to be set to the different possibilities. For each case, the aforementioned telephone number formats are to be tested.


beroNet gateway cards

In order to debug active cards from beroNet, a tunnel to the internal IP address of the card must be created first. This is done as described in the following sections, depending on the used operating system.


Access from Windows

At first, a terminal program needs to be downloaded and installed. In this example, the program PuTTY is used. Under session, the IP address of the target system is entered as host name. The default SSH port is 22.

PuTTY, session configuration, assigning IP address

Next, switch to the menu item SSH -> Tunnels and enter 8888 as source port. In addition, a destination is specified. The destination is made of the internal IP address of the card and the standard beroNet HTTP port 80.

If only one card is mounted, its IP address is 10.1.0.2 and consequently the destination is 10.1.0.2:80. For two cards being mounted, the destination is 10.1.0.2:80 for the first card, and 10.2.0.2:80 for the second card. For additional cards, the IP address increases according to the same pattern.

Clicking on Add applies the input data.

PuTTY, SSH tunnels configuration

Now, switch to the menu item Window and enter the value 20000 for scrollback.

PuTTY, window configuration

Thereafter, a name can be assigned to the configured session and it can be stored for possible future connections by clicking on Save. Clicking on Open starts the session.

PuTTY, session configuration, assigning session name

It is possible that PuTTY ejects a warning at this point. This happens if a different safety key has been saved for the selected host in a previous session. Please make sure that the connected device is the correct one and respond to the message accordingly. The message is an indication of a possible man-in-the-middle attack and should be carefully examined in order to avoid possible damage.

PuTTY, security alert

A console window will open, asking you to log in as user root with the administrator password of AskoziaPBX.

PuTTY console, root login to beroNet gateway card

The connection to the beroNet gateway card has been established at this point and it can now be used.


Access from Unix-based systems

Open a terminal program, such as Terminal for Mac OSX.

The following command establishes the connection to the beroNet gateway card.

ssh root@[IP.der.Askozia.PBX] -L8888:10.1.0.2:80

8888 is the source port. In addition, a destination is specified. The destination is made of the internal IP address of the card and the standard beroNet HTTP port 80.

If only one card is mounted, its IP address is 10.1.0.2 and consequently the destination is 10.1.0.2:80. For two cards being mounted, the destination is 10.1.0.2:80 for the first card, and 10.2.0.2:80 for the second card. For additional cards, the IP address increases according to the same pattern.

You will then be asked to enter the administrator password of AskoziaPBX.

Terminal, root login to beroNet gateway card

The connection to the beroNet gateway card has been established at this point and it can now be used.


The web interface of beroNet gateway cards

After enabling access to the beroNet gateway card, open a browser window and access the card's web interface by entering localhost:8888. The login data are as follows.

Username: admin

Password: admin

beroNet interface cards, login screen

Under Management, the connection ports of the card are listed. Link L1 shows whether each port has a physical connection. L2 Link indicates if the port is synchronized.

beroNet interface cards, Management tab

Under Hardware, all ports and their configurations are listed.

beroNet interface cards, Hardware tab

All existing dial plans are listed at Dialplan.

beroNet interface cards, Dialplan tab

After the configuration of the card has been changed, a button indicates what effect the changes will cause.

  • Yellow: By clicking on "activate", the changes will be activated without further consequences.
  • Orange: By clicking on "activate", the call will be suspended.
  • Red: The card needs to be restarted. All conversations are interrupted.
beroNet interface cards, button for activating configuration changes

By changing the API password and deleting the registered hosts under Preferences, ,

In case the beroNet card is to be configured manually, AskoziaPBX can be prevented from automatically re-provisioning it later, by changing the API password and deleting the registered hosts under Preferences.

beroNet interface cards, Preferences tab

In order to configure the beroNet card through AskoziaPBX without the card being restarted after each change, the restart can be prevented with the following command in the integrator panel.

touch /tmp/BERONETNOCONFIGURE
Console, prevent beroNet card restart

The previous configuration can be reversed reversed by:

rm /tmp/BERONETNOCONFIGURE

Under Management -> Dialplan Debug, a log recording can be generated. For this purpose, in order to perform the test case, click on Start Dialplan Debugging. Another window opens, showing the call flow.

beroNet interface cards, dialplan debugging


Dial plan examples

Below are some call case examples. The call flows are to be read from bottom to top.

The first example shows the call flow of an outgoing call between an internal SIP telephone and an ISDN provider.

  • Yellow text indicates the SIP channel of the conversation. Starting from the bottom, a request for a call is sent from participant 101 (Zoiper) to the ISDN provider.
  • Red text indicates processes in the corresponding dial plan and shows the assignment to the required ISDN provider.
  • Black text shows the sequences on the ISDN side. First, a call request is displayed by SETUP. Subsequently, CONNECT indicates that the connection has been established. Finally, DISCONNECT indicates the end of the conversation, in particular by hanging up as indicated by Normal Clearing. Afterwards, the SIP channel is terminated by a Bye.
  • At the end, call details are written into a card-internal call detail record (Gray text) and the process is finished.
beroNet interface cards, dialplan debug, first example

The second example shows an incoming call on an ISDN port.

  • SETUP indicates the entry of the call at port 1 for internal number 321321, with the incoming caller ID 05331900989800.
  • The red D INCOMING refers to the used internal dial plan.
  • Subsequently, an INVITE sent to the SIP phone is 'confirmed by OK.
  • CONNECT indicates the establishment of the audio connection.
  • At the end of the phone conversation, the SIP phone hangs up and ends the call, as indicated by BYE.
  • Now, the ISDN channel is cleared, which is represented by release.
  • Finally, the call details are written to the card-internal call detail record.
beroNet interface cards, dialplan debug, second example


Introduction to dial plans

AskoziaPBX is based on Asterisk and works with dial plans. Dial plans consist of single command lines which are used to control call processes. To get an understanding of dial plans, this section introduces their basic concepts. This should serve as a base and make it possible to read and understand dial plans by means of further documentation.

The Asterisk dial plan is stored within extensions.conf. For AskoziaPBX, it can be accessed and edited through the integrator panel.


Structure

Dial plans consist of single contexts. Each context includes the command lines, which are sort by extensions and' priorities. A simple example might look like this:

[101/internal]

exten => 101,1,NoOp(Nothing happens hier yet)
exten => 101,2,Set(CALLERID(num)=123456)
exten => 101,3,Set(CALLERID(name)=for 101)
exten => 101,n,Answer()

This example shows a context [101/internal], which is responsible for internal calls that are incoming through the internal extension 101. The names of the contexts are always set in square brackets and are written above a command block. The single command lines always begin with exten => and thus can be clearly identified and distinguished. Depending on the available operating window, a command line may also run over multiple lines of text. Behind "exten =>", 101 is defined. This is the extension to which these commands relate. Depending on the context, a dialing pattern may be entered here as well. More on that later. The consecutively numbered from top to bottom is the priority number and serves as a further assignment of the commands within the context. The fourth command line shows the priority n. It is important to know that the first command line in a context must always be a 1. The ongoing priorities can be replaced by n and subsequently be automatically incremented by Asterisk. This simplifies development in complex processes. Behind the priority, the actual command is written. There are countless different commands, which contain the most diverse requirements and variables. Listing them all is beyond the scope of this introduction. Below, sources are linked, which offer detailed documentation for this topic. For the prior example, the following would happen.

  • A call comes in to the internal number 101 from another internal telephone.
  • Priority 1: 'NoOp' is a command that nothing executes yet but can be used to output variables. This can be done by writing the variable name within the round brackets.
  • Priority 2: Set defines or changes a variable. In this case, the number of the incoming caller ID, CallerID (num), is set to' 123456 '.
  • Priority 3: Another set command. Here, the name of the incoming caller ID, CallerID (name), is set to for 101.
  • Priority 4: Here set to n, answers the channel and lets the phone ring that is assigned to extension 101.
  • The display of the ringing phone with extension 101 displays: "123456 for 101".


Contexts

Additionally to a context for general dial plan settings, there are different contexts for each device such as telephones or faxes, for each provider, and for internal applications. Different transmission technologies such as analog, ISDN, SIP and IAX require different contexts. The call direction is crucial. A phone requires different contexts for incoming and outgoing calls. Internal calls are treated differently than external calls. It is important to know that contexts always serve as "interface" between Asterisk and a "participant" such as devices and provider. As an example, let phone A call phone B . This connection is not just established right away. It will follow the following procedures:

  • phoneA sends a request through the context [phoneA/intern] to Asterisk
  • Asterisk "brokers" the request of the context [phoneB/incoming] to phoneB

Thus, the connection is as established as follows.

phoneA -> [phoneA/internal] -> Asterisk -> [phoneB/incoming] -> phoneB

The connection remains this way. Asterisk keeps control for the whole duration of the call.

The "communication" within a dial plan is done within the contexts. Through commands such as Goto ([[context|]extension|]priority), a conversation can be passed from one context to another. This is interesting, for example, in case of a call transfer. When passing through Goto, not only the desired context is specified as destination, but the exact entry point. This is done by specifying the extension and the priority.


Extensions

The extensions are used to assign the commands to the target participants. The initial example relates to the extension 101. Thus, if a request for a call setup for the extension 101 is registered in the context, this request is directed into the first priority of the extension 101 and the underlying dial plan is processed sequentially. It should be noted that not only sequences of numbers are valid as extension. For example, the configured dial patterns play an important role for outgoing calls through different providers. They are always marked with a _ in the function of the extension with a , as shown in the following example.

exten & # X3D;.> _0X, 1, NoOp ()

Here, the NoOp command would be executed if a 0, followed by any amount of numbers between 0-9 (X.) would be elected.


Priorities

The priorities are considered further "addressing" within the dial plans. They are either numbered consecutively from top to bottom, or carried out with a "n". In this case, Asterisk numbers automatically from top to bottom. This has the great advantage that in case of subsequent changes in the dial plan, not all priorities have to be manually adjusted. The disadvantage is that the unique identification of entry points becomes difficult. In the example, Goto ([[context|]extension|]priority), a clear priority must be given in order to be able to execute the command correctly. This possibility does not apply if the priorities with are given as "n". In this case, Asterisk provides the ability to label priorities. For example, a priority can be performed as follows.

[101/intern]
exten => 101,n(label),NoOp()

If you now want jump to that location from a different context, the Goto command would look as shown below.

Goto([[101/intern|]101|]n(label))


Logical workflows

A dial plan's logic is assembled from the different commands offered by Asterisk. After the addressing of a sequence by context, extension, and priority, the subsequent operation is performed. This can be a simple command like NoOp() or Goto(). However, it can also be a composite of different conditions and dependencies of different variables.

exten => GotoIF($["${door_status}"="1"]?CLOSE_DOOR:OPEN_DOOR)

The meaning of the previous line is as follows.

  • It is a dependency of the variable ${door_status}
  • If ${door_status} = 1, then go to CLOSE_DOOR
  • If ${door_status} <> 1, then go to OPEN_DOOR

In this way, also much longer and more complex instructions can be composed.

A very good documentation for various Asterisk commands and the correct syntax is provided on VoIP-info.org.

Dial plans can appear very demanding for untrained users. It should always be considered that only the entire construct of dial plan is large and complex. This construct, however, consists of many small parts which, if observed individually, are logically comprehensible and quite understandable.


Network tracing with AskoziaPBX

As from version 4.0.3, AskoziaPBX supports the direct creation of network traces (recordings), which can be analysed by means of programs such as Wireshark [Wireshark]. These traces can help to read data packets which are received from or sent to AskoziaPBX. By means of these data packets, more complex problems in the network transmission can be traced. This section explains how such traces are created and how the data can be further processed.

Creating network traces

In order to create network traces with AskoziaPBX, AskoziaPBX needs to be accessed via SSH. For this purpose, please proceed as explained in Accessing AskoziaPBX via SSH. Afterwards, the record can be started by the following command.

tcpdump -i eth0 -w /storage/usbdisk1/askoziapbx/wireshark_trace_DATE.pcap


Starting network tracing

Now, reproduce the steps leading to the problem that you want to analyse, such as interrupted conversations or routing not leading to the correct target.

Subsequently, the recording is stopped by using the key combination ctrl + c.

Stopping network tracing

The created trace is automatically saved under the chosen file name on the data storage of AskoziaPBX. Run a memory backup to access the data. The created files can be found within the AskoziaPBX folder.

AskoziaPBX storage folder

Please note that, with respect to size and frequency of the recordings, the memory of AskoziaPBX will be utilised. Therefore, we recommend to remove traces from the memory backup and re-upload the adjusted backup to AskoziaPBX.


Analysing the traces with Wireshark

The recorded traces have the file extension *.pcap and can be opened with the program Wireshark directly by double-clicking. The program's main window is divided into three areas. The upper third contains the collection of recorded network packets. In the center, the packet marked above is represented with its respective information. The information of the packages that have been selected in the central part is shown in the bottom part at bit-level.

Wireshark, main window

All protocols are listed, that have been sent and received through the network interface of AskoziaPBX during the recording period. This allows, for example, to understand call sequences precisely. The filter function allows you to display only the desired protocol types. This way it is possible, for example, to limit the display to the SIP protocol.

Wireshark, filtered output listing only SIP connections

Describing the full functionality of Wireshark, would be beyond the scope of this tutorial. Further information can be found through the following links.

Official Wireshark homepage - https://www.wireshark.org/

Official Wireshark wiki - https://wiki.wireshark.org/

Online Nutzer-Dokumentation - https://www.wireshark.org/docs/wsug_html_chunked/


SIP traces

SIP traces are recordings of the SIP traffic that takes place between the parties of a VoIP call. SIP packages that control the course of the connection are sent back and forth between the participants. These traces allow to analyse the course of a call and in case of an error check for the cause. In order to obtain the SIP traces, the following steps need to be performed.

First, establish a SSH connection and open the Asterisk console.

In order to be able to read the new SIP packages, the log level of AskoziaPBX has increased and the SIP debugging starts. This is done by using the following commands.

core set debug 3

core set verbose 3

sip set debug on


If the log levels are adapted, a call can be initiated. You can see the complete course of the call. The SIP packages are clearly recognisable. An example of such SIP packages can be seen in the figure below.

SIP trace example

This is an Invite package. Invite packages are sent by the party that wishes to initiate a call. The following information is included within this SIP package.

1 - The sender of the package (in this example, the number is 4953122436750 of the domain [username]@sipconnect.sipgate.de) 2 - The recipient of the package (in this example, 0511656114@sipconnect.sipgate.de) 3 - The status code of the current SIP package (here: Invite) 4 - A list of SIP used headers 5 - The used codecs that are allowed by the PBX for this subscriber


Below, a list of configurations within the Askozia web interface and their impact in the SIP package are shown.

Here, the caller ID of the caller has been adjusted. As a result, the adjusted caller ID can be seen within the invite package.

AskoziaPBX, caller ID options
SIP trace example with adjusted caller ID

In the web interface of AskoziaPBX, under "Accounts" -> "Provider" -> "Advanced Settings" (of the chosen provider), individual SIP headers are enabled or disabled. Only the active headers are inserted into the SIP packages.

AskoziaPBX, SIP header options
SIP trace example showing only active headers

In the following image, "From User" is manipulated in the advanced settings of the provider. This is necessary to authenticate with some providers.

AskoziaPBX, "from user" setting
SIP trace, "from user" example

The "From Domain" can also be manipulated as shown below. This setting is also required by some providers to ensure authentication and connection.

AskoziaPBX, "from domain" setting
SIP trace, "from domain" example

The checkbox "Disable From User" replaces the user name by the caller ID. This is also required by some providers.

AskoziaPBX, disabling "from user"
SIP trace example, "from user" being replaced by caller ID
Personal tools
Namespaces

Variants
Actions
Navigation
Getting Started
AskoziaPBX
Call Flow Editor
PRI
CTI
Tools