Administrator Guide: Communication Server 4

Goal of the document and intended audience

This document describes the configuration steps for installing the Communication Server.

Intended audience: installation and service delivery teams

Changes since the Communication Server 4 module

Based on Asterisk 13

Upgrade from Asterisk 11.

Ansible role replaces module

This https://git.escaux.com/ansible-roles/communication-server[Communication Server Ansible role]] is now the supported way of installing and (re)configuring the Communication Server 4 debian packages.

Dependencies and minimal required versions

The installation of the Communication Server module is only supported on Baseline 4.

Dependencies

Software and hardware

The Communication Server role is included in other roles and ultimately in playbooks. To check the version included in a playbook/role, you can run git submodule.

The Communication Server role is only supported on Baseline 4.0.0+. This implies that you require hardware that is supported by Baseline 4.0.0+.

Mandatory Modules

Modules are deprecated.

Mandatory Resources

To correctly use music-on-hold you need both of these resources:

MusicOnHold >= 1.6
MusicOnHoldSelector >= 1.1

If you already have installed the Communication Server module without upgrading these resources, you have to restart the SOP before music-on-hold will work.

Minimal versions of optional modules

Modules are deprecated.

Minimal versions of resources and resource compatibility

N/A

Minimal versions of actions and action compatibility

Migration task

The task MigrateActionsToCommunicationServer in its version 4.0.0 can be used (

not yet released) to upgrade all actions to the minimal version listed below. Note that this is a tool for internal use only.

Important note: here, we only list the minimal version compatible with CS4. It is often NOT the best available version. Please check the version included in the template you use or the latest GD version and if they are above the minimal listed, use them instead.

Variables names are now case-sensitive

Starting with asterisk 12, all variable evaluation, whether done in the dialplan or internally, is now case-sensitive. This has the potential to break not only a lot of actions but also your callflows. The MigrateActionsToCommunicationServer might be updated to check for case issues in the future.

Reference: https://wiki.asterisk.org/wiki/display/AST/Case+Sensitivity

Validated actions

STARTAPPLICATION 3.2.0
SetVar 1.2.0
Hangup 1.3
Ring 1.1.0
Progress 1.0.0
ManageHangupHandlers 1.0.0
If 1.6.0
Redirect 1.6.1
CallInterface 1.11.0
PrintMessage 1.0.0
GetCallQualityStatistics 1.0.0
Return 1.0.1
SplitString 1.0.1
CallDevices 1.26.1
Subscribe 1.2.0
Hangup 1.5.1
JsonParse 1.0.0
SetPresenceState 1.1.0
PlayTones 1.0.0
Wait 1.3
Answer 1.1
PlayVariable 1.1
Echo 1.0
PlayVariable 1.3.0
ReceiveIM 3.2.1
SendIM 3.0.3
ManageAggregatedPresence 2.1.2
RemoveRealtimePeer 1.0.0
SetVar 1.02

Incompatible actions

AddToConference < 2.0.0

Configuration - using debconf in Ansible Role

As the previous Communication Server 3 and since there is no module anymore, debconf is used to configure Communication Server.

The debconf parameter are now configured in the Ansible role using YAML syntax, as document here, in the role README.

Every parameter defined in escaux-asterisk.templates is available.

Release notes

Version installed

Use dpkg on the SOP, the CS version is included in the escaux-asterisk package version.

# dpkg-query --show escaux-asterisk
escaux-asterisk    1:13.18.0-cs4.1.0

--# Version included in a role/playbook

In the Communication Server role, the version is defined in defaults/main.yml

In parent role/playbook, you can use git submodule to get the CS role version, which by convention corresponds to the CS version.

webrtc-gateway-roles$ git submodule
-263e576eb0cd47ceee7f29c55487f743bf7dac42 software/dependencies/apply-changes
-5378c6b7b16846ffaefada3baca9eac1e0d7e6d6 software/dependencies/apt-dev-sources
 e7f163b78384d7cd90366faa38d044aa21ed3838 software/dependencies/communication-server (4.1.0)
-83ebcd43bf4b484ee269912dc1a52d7b425a5e98 software/dependencies/mariadb
-2cef10e0197b5a47389bc45d31e0bd8f94aa4046 software/dependencies/music-and-sounds
 27ac1e3c316c209d4de9fbdfe6ffbc001409462b software/dependencies/webrtc-api (2.3.0)

Start/Stop/Restart

The correct and supported method to control Communication Server start, stop and restart is now to use service asterisk <start|stop|restart>*. Using the asterisk console to do that is not recommended and might not even work correctly in some cases.

Never start asterisk manually by running the binary /usr/sbin/asterisk or /usr/sbin/asterisk -c as root. It will be started without the correct system parameters (e.g. max number of files) and without any defense.

Systemd

In baseline4, the init system is systemd. It is used to start/stop but also monitor and restart in case of a crash, taking over the role of safetynet. Safetynet is not used anymore.

This means that the stop command of asterisk will also disable the automatic restart, while the start command will re-enable it, without any other operation needed. This should avoid any operational mistake in forgetting to re-activate/de-activate safetynet.

In case the asterisk process exits or is killed, the init system will now immediately detect it and restart it.

Communication Server status

Systemd provides a nice status view for asterisk:

root@00000000:~# service asterisk status
* escaux-asterisk.service - Communication Server
   Loaded: loaded (/lib/systemd/system/escaux-asterisk.service; enabled; vendor preset: enabled)
   Active: active (running) since Thu 2017-12-14 11:40:21 UTC; 21h ago
  Process: 30509 ExecReload=/usr/sbin/asterisk/asterisk -rx core reload (code=exited, status=203/EXEC)
 Main PID: 12705 (asterisk)
   CGroup: /system.slice/escaux-asterisk.service
           `-12705 /usr/sbin/asterisk -g -f -U asterisk

Dec 14 11:40:21 00000000 systemd[1]: Stopped Communication Server.
Dec 14 11:40:21 00000000 systemd[1]: Started Communication Server.

Note the time since last restart (21h ago) or the last log lines shown.

Syslog

After a crash of asterisk, it will now be restarted immediately by the init system. The syslog will show:

Dec 15 09:49:33 00000000 systemd[1]: escaux-asterisk.service: Unit entered failed state.
Dec 15 09:49:33 00000000 systemd[1]: escaux-asterisk.service: Failed with result 'signal'.
Dec 15 09:49:35 00000000 systemd[1]: escaux-asterisk.service: Service hold-off time over, scheduling restart.