Administration Guide

Hardware requirements

Overview

MiaRec solution has flexible architecture supporting various deployment scenarios depending on number of users and requirements to high availability and redundancy.

"All-in-one" configuration is recommended for up to 2,000 users.

The distributed configuration is recommended for more than 2,000 users (more details here).

All-in-one server

This article provides hardware recommendations for "all-in-one" setup, where all software components (recorder, database, web portal and storage) are deployed in a single server.

All-in-one architecture

"All-in-one" configuration is recommended for deployments up to 2,000 users. For larger deployments we recommend to use decoupled architecture (multiple servers).

Recommended hardware configuration for recording 10-50 users

Physical or virtual server with the following minimum hardware specification:

CPU Intel CPU dual-core or better. Frequency at least 2.0GHz.
Memory 4 GB or more
Storage 14.4 MB disk space per hour of recorded conversation in stereo MP3 format, 7.2 MB in mono format.

Network Interface Card (NIC) One NIC for active recording methods (SIPREC, Cisco Built-in-Bridge, Avaya DMCC)

Two NICs for passive recording method (packet sniffing) are required in the following cases:

  • MiaRec is installed on the same server, where DHCP and DNS services are running
  • MiaRec is installed in a virtual environment
  • Network switch doesn't support port mirroring and management traffic on the same port

In above mentioned cases one NIC will be used for packet sniffing (recording) and another for management.

In all other cases, two NICs for passive recording method are recommended, but not required.

OS Windows 7, 8, 10, Windows Server 2008, 2012 (64-bit) or Linux RedHat/Centos/Ubuntu (64-bit)

Recommended hardware configuration for recording 50-500 users

Physical or virtual server with the following minimum hardware specification:

CPU Intel CPU quad-core or better. Frequency at least 2.0GHz.
Memory 8 GB or more
Storage Separate disks for binaries and audio files. Operating system, MiaRec binaries and database files should be located on high speed disk (10,000 or 15,000 rpms). Audio files (MP3) should be stored on a separate disk (or disk array).

14.4 MB disk space per hour of recorded conversation in stereo MP3 format, 7.2 MB in mono format.

Network Interface Card (NIC) One NIC for active recording methods (SIPREC, Cisco Built-in-Bridge, Avaya DMCC)

Two NICs for passive recording method (packet sniffing) are required in the following cases:

  • MiaRec is installed on the same server, where DHCP and DNS services are running
  • MiaRec is installed in a virtual environment
  • Network switch doesn't support port mirroring and management traffic on the same port

In above mentioned cases one NIC will be used for packet sniffing (recording) and another for management.

In all other cases, two NICs for passive recording method are recommended, but not required.

OS Windows Server 2008, 2012 (64-bit) or Linux RedHat/Centos/Ubuntu (64-bit)

Recommended hardware configuration for recording 500-2,000 users

Physical or virtual server with the following minimum hardware specification:

CPU Intel CPU six-core or better. Frequency at least 2.3GHz.
Memory 16 GB or more
Storage - Two high speed disks (10,000 or 15,000 rpms) in RAID 1 configuration for storing operating system and program files. Disk space requirements - at least 72GB

  • Two SSD disks for storing database data files in RAID 1 configuration. Disk space requirements - at least 3GB for each 1M records

  • High capacity disk array (local or NAS/SAN) in RAID 5/6 configuration for storing audio mp3 files and, optionally, log files. Disk space requirements - 0.24 MB/minute of recording

Network Interface Card (NIC) One NIC for active recording methods (SIPREC, Cisco Built-in-Bridge, Avaya DMCC)

Two NICs for passive recording method (packet sniffing). One NIC will be used for packet sniffing (recording) and another for management.

OS Windows Server 2008, 2012 (64-bit) or Linux RedHat/Centos/Ubuntu (64-bit)

More than 2,000 users

For larger deployments we recommend to use decoupled architecture (multiple servers).

High availability and redundancy

MiaRec supports High Availability setup using advanced multi-master asynchronous replication between multiple "all-in-one" servers. More details about data replication

All-in-one architecture with replication

Decoupled architecture

With MiaRec decoupled architecture each software component (recorder engine, database, web portal, storage) is deployed on a dedicated server. Optionally, the components may be duplicated to achieve full redundancy and/or scalability.

Decoupled architecture is recommended for recording 2000 or more users.

The following diagram shows the extreme case when at least two copies of each component is deployed on own dedicated server (master/slave or multi-master) to achieve full redundancy.

Beside such extreme case, MiaRec supports other configuration with partial share of hardware resources by some of components. For example, for a small-scale deployments in a hosted environment we recommend to isolate a recording server from all other components as the minimum requirement. The rest of components may share hardware resources of the second server. Such two-server setup provides a good balance between security (isolation of a critical recording server) and cost (sharing of hardware resources by other components).

Nowadays a virtualization is a preferred deployment method for new software. In a virtual environment it is significantly cheap to spin up additional VMs and isolate components from each other to achieve reliability, security and scalability.

Decoupled architecture

Such architecture allows to achieve the following goals:

  • Redundancy: All components are duplicates to eliminate single-point-of-failure issue. Some of components support master/master, others support master/slave configuration with a floating ip-address mechanism.

  • Performance: The software components do not contend for the same server resources (CPU, Memory, I/O, etc.)

  • Scalability: Multiple recording and web servers could be deployed for load balancing purposes. Additional server could be easily added to the solution to cover customer grow. MiaRec software architecture provides almost linear scalability of individual components. For example, if the bottle-neck is a web portal, then you just need to spin up additional VM with web application.

  • Reliability: The components are isolated from each other. In a hosted environment, it is important to isolate recording servers from web servers in order to prevent potential disruption of service due to occasional spikes in web traffic. With such architecture, the issues with some of components are not propagated to other components. In worse case, you may have downtime or slowness of web portal, but the recording process would not suffer from such issues and you will not lose any recordings due to CPU/disk/network overload.

  • Security: In a hosted environment, it is important to keep recording and database servers in a private network isolated from end-user facing web servers. A potential breach of web server will not spread to other servers.

Hardware specification recommendations

Different components have different requirements to hardware. For example, MiaRec recording server benefits the most from multiple CPU cores and does not benefit at all from additional memory (for example, recording of 500 concurrent sessions consumes less than 1GB of memory, but requires 16-core CPU). The database server benefits the most from SSD disks with a high speed random access. The web portal doesn't benefit from SSD disks, but it benefits from additional memory.

Below you will find recommendations for hardware specification of each individual component.

Recording server hardware requirements

We recommend to one recording server (or virtual machine) for each 500 concurrently recorded sessions (equivalent to approximately 5,000 users in a Hosted PBX environment). MiaRec recording engine has exceptional performance and can record 1,000 and more concurrent session on a single server, but we recommend to keep average load on 500 concurrent sessions per server to have enough room for potential spikes in load.

When using audio file encryption, the recommendations are one server per each 250-300 concurrently recorded sessions.

Small server configuration (about 1,000 users per recorder server):

CPU 4 cores or more. Frequency at least 2.26GHz.
Memory 8 GB or more
Storage

  • 2 hard disks using RAID 1 for storing OS, binary files and log files. Minimum free disk space is 300GB (for log files).
  • 2 high speed hard disks (10K or 15K RPM) using RAID 1 for temporary storage of audio files for in-progress calls. Minimum free disk space is 300GB. (*)

Large server configuration (about 10,000 users per recorder server):

CPU 12 cores or more. Frequency at least 2.26GHz.
Memory 16 GB or more
Storage

  • 2 hard disks using RAID 1 for storing OS, binary files and log files. Minimum free disk space is 300GB (for log files).
  • 2 high speed hard disks (10K or 15K RPM) using RAID 1 for temporary storage of audio files for in-progress calls. Minimum free disk space is 300GB. (*)

(*) - For performance reasons it is recommended to store audio files for in-progress calls locally on the server. The audio file will be moved to the network attached storage at the end of each call.

Besides performance reasons, such solution provides also additional layer of protection from network failures. In case of network connection issues to the NAS, the recorder process may continue to record calls and store audio files locally till the connection to NAS server is recovered.

Database server requirements

One or two database servers (PostgreSQL) in master/slave configuration using floating ip failover mechanism.

CPU 2 cores or more. Frequency at least 2.26GHz.
Memory 16 GB or more
Storage Solid state drives (SSDs) using RAID 1 or RAID 10 with free space 3GB for each 1M records stored in database

Web application server requirements

One or more web application servers for load balancing and redundancy purposes.

Each of servers hosts web portal as well as worker processes for task manager. The task manager is used to execute various maintenance tasks like export, backup, replication, retention, etc. The workers on multiple web application servers form the pool of workers, i.e. the tasks are automatically distributed over multiple application servers for redundancy and load balancing purposes.

The recommended number of web servers depends on anticipated pages/s web requests load.

For a hosted PBX environment a rough estimate is one web server per each 5,000 users.

CPU 4 cores or more. Frequency at least 2.26GHz.
Memory 16 GB or more
Storage

2 hard disks using RAID 1 for storing OS, binary files and log files. Minimum free disk space is 150GB (for log files).

Web load balancer requirements

The web load balancer (HAProxy) is required when two or more web servers are deployed.

The load balancer server itself may be duplicated to eliminate single point of failure situation. Switchover between load balancing servers is implemented using floating ip mechanism.

CPU 2 cores. Frequency at least 3.00GHz.
Memory 4 GB
Storage Storage is not critical because HAProxy is mostly CPU consuming process (single thread). 64GB of disk storage for OS, application binary files and logs should be enough.

Message Broker server requirements

One or two servers in master/slave configuration for message queue system. The message queue system is used for internal communication between various components of MiaRec solution.

CPU 2 cores or more. Frequency at least 2.26GHz.
Memory 16 GB or more
Storage

  • 2 hard disks using RAID 1 for storing OS and binary files (64GB)
  • 2 high speed hard disks (10K or 15K RPM) using RAID 1 for persistent storage of messages with free space at least 64GB.

Network attached storage (NAS) for audio files

MiaRec stores audio files in compressed MP3 format. Default compression settings are 0.24MB/minute of recording.

Decoupled with GEO-redundancy

MiaRec supports advanced multi-master asynchronous application-level replication between datacenters. It is quite unique on the market because other vendors mostly support either master/slave or master/master synchronous or SAN-based replication (expensive and not suitable for GEO-redundancy).

More details about benefits of MiaRec replication.

Decoupled architecture

Disk space requirements

MiaRec supports following formats for audio files:

Format Size per minute Hours per TB
MP3 (stereo 32kbps) - default 0.24 MB/minute 72,818 hours/TB
MP3 (mono 16kbps) 0.12 MB/minute 146,636 hours/TB
WAV (stereo) 1.92 MB/minute 9,102 hours/TB
WAV (mono) 0.96 MB/minute 18,204 hours/TB

Format of audio file and MP3 bitrate settings are configurable.

Installation

Installation on Windows

Install MiaRec software

Installer for Windows operating system can be obtained from download page. The installer includes all required software (recorder, database, web server etc).

Step 1. Start MiaRec installer.

MiaRec_Installer_01.png

Step 2. Select destination folder

By default MiaRec is installed into C:\Program Files (on 32-bit system) or C:\Program Files (x86) (on 64-bit system). You can select different location for MiaRec files.

MiaRec_Installer_02.png

Step 3. Install WinPcap

MiaRec requires WinPcap network driver. If it is not available on your system, then install it now.

MiaRec_Installer_03.png

Winpcap_installer_01.png

Step 4. Select ports for Web server and database

If port 80 is busy by other application (for example, IIS), then select another port, for example, 8080.

MiaRec_Installer_04.png

Step 5. Proceed to installation process

MiaRec_Installer_05.png

Step 6. Open MiaRec web portal in browser

When installation finished, open MiaRec web portal in browser.

MiaRec_Installer_06.png

Configuring NIC for passive recording (port mirroring)

Note, the instructions in this document do not apply to active recording methods, like Cisco Built-in-Bridge, SIPREC, etc.

Usually, the same network interface adapter (NIC) can be used for both port mirroring traffic and regular access of the server from a network.

But in some cases it is recommended (or even required) to install a separate NIC, which will be used solely for port mirroring purposes. These cases are following:

  • More than 50 concurrent calls are recorded by MiaRec at the same time
  • The switch discard network packets on a port, which is used as a destination for port mirroring session
  • DHCP or DNS services are running on the same server, when MiaRec is running.

In these cases MiaRec should be connected to network switch with two NICs as shown on below diagram:

MiaRec Server with two NICs

  • The first NIC will be dedicated to port monitoring traffic
  • The second NIC will be used for a remote access of the server from other computers.

To prevent any conflicts with IP-addresses the first NIC should be switched to "stealth" mode with TCP/IP unbound from the card. You will need to open properties of NIC and disable IP stack and all other protocols (see below screenshot). This NIC will be used in listen mode only. No network packets will be sent from this NIC. That's why IP address is not necessary for it.

Listen-only configuration

Firewall configuration

Configuration of firewall consits of two steps:

  1. Open ports, which are used for accessing MiaRec from other computers on the network
  2. Enable packets pass-through for port mirroring traffic

Open ports for MiaRec

MiaRec uses following ports, which should be opened on firewall:

PortDescription
80 (TCP)

MiaRec Web-portal (HTTP protocol)

It is possible to change this port to other value during installation (for example, to 8080).

443 (TCP)

MiaRec Web-portal (HTTPS protocol)

 6554 (TCP)

Live monitoring (RTSP signaling).

If live monitoring is not used, then this port can be closed on firewall.

7000 - 7999 (UDP)

Live monitoring (RTP audio).

If live monitoring is not used, then these ports can be closed on firewall.

5070 (TCP)

Cisco SIP trunk recording signaling (SIP protocol) - for Cisco UCM only

20000 - 21999 (UDP)

Cisco SIP trunk recording media (RTP protocol)  - for Cisco UCM only

5080 (TCP, UDP)

SIPREC recording signaling (SIP protocol) - for SIPREC recording only

22000 - 23999 (UDP)

SIPREC recording media (RTP protocol) - for SIPREC recording only

Enable packets pass-through for port mirroring traffic (for passive recording only)

Important! This step is required only when passive recording is used (port mirroring).

MiaRec leverages port mirroring function on the switch. Some firewalls may block the network packets, which are mirrored to MiaRec server because they think that such traffic is malicious as it is not originally destined to that server (this is a traffic from IP Phone to IP PBX rather than to MiaRec server).

This may cause one of the following issues:

  • one-way audio (when only one side of conversation is recorded)
  • no audio is recorded at all (both sides of conversation are not recorded).

Windows Firewall (included into Windows XP, Vista, 7, 2003, 2008) doesn't have such problem. It passes through the mirrored network traffic to MiaRec server.

Other firewalls may block such traffic. Some of them has a configuration option, which allows to pass-through the traffic. Usually such option has name "Allow network bridged connections" or "Allow Internet sharing".

In worse case firewall doesn't have any option for passing through the network traffic and the only possible solution is to disable the firewall at all (or replace that firewall with other model). Usually, such firewalls are built-in to antivirus packages.

Step-by-step guides for some of known firewalls:

Firewall

AVG Internet Security

AVG Internet Security Firewall

AVG Internet Security Firewall blocks the network traffic from external Voip adapters/phones.

Because of this the call recording is not possible untill AVG Firewall is disabled.

MiaRec just doesn't see the network traffic, which is sent by Voip adapter/phone.

Unfortunately, this firewall has very basic configuration options* and there is no way to use it together with MiaRec.

* - this information is valid for AVG v.9.0.730 released on 1st of March 2010.

If you need to record calls, disable it or choose another firewall application.

Below screenshot shows how to disable AVG firewall.

Disable AVG Firewall

BitDefender Internet Security

BitDefender Internet Security Firewall

By default BitDefender Internet Security firewall blocks remote Voip traffic and prevents call recording capability.

In order to change this behavior, please, do following:

1) Open Settings of BitDefender Internet Security and choose "Firewall" from the left pane.

2) Click on "Advanced Settings" button (see below screenshot)

BitDefender Internet Security

3) Make sure that "Enable Internet Connection Sharing" is checked.

BitDefender Internet Security

4) Click OK button to save changes.

5) Reboot computer

Now MiaRec should be able to record your calls.

Should you have any problem or question, please, contact our technical support by e-mail or phone.

ESET Smart Security 4

ESET Smart Security 4

By default ESET Smart Security 4 firewall blocks remote Voip traffic and prevents call recording capability.

In order to change this behavior, please, do following:

1) Open Settings of ESET Smart Security 4 and choose "Setup" from the left pane.

2) Click on "Toggle Advanced mode" (see below screenshot)

ESET Smart Security

3) Click on "Personal firewall" in the left pane.

ESET Smart Security

4) Click on "Advanced Personal firewall setup..."

ESET Smart Security

5) On the left pane choose "IDS and advanced options" under "Personal firewall".

ESET Smart Security

6) Make sure that "Enable communication for bridged connections" is checked.

ESET Smart Security

7) Click OK button to save changes.

Now MiaRec should be able to record your calls.

Should you have any problem or question, please, contact our technical support by e-mail or phone.

Ansible-based installation on Linux

Installation on Linux using Ansible

Overview

MiaRec uses Ansible IT automation engine to deploy its software components on Linux system. This guide provides step-by-step instructions for both initial deployment as well as update of MiaRec software.

What is Ansible?

Ansible is an automation tool for provisioning, application deployment, and configuration management.

Ansible uses playbooks written in the YAML language for orchestration. For more information, see Ansible - Intro to Playbooks.

Compared with other server configuration management DevOps tools, Ansible doesn’t require agents to be installed on the managed servers. Instead, Ansible manages the IT infrastructure by using SSH protocol to communicate the managed resources. This dramatically simplifies the configuration of managed systems for two reasons—no process daemons need to run on the remote servers to communicate with a central controller and IT administrators aren’t required to manage or maintain agents on each managed node.

Ansible can communicate with multiple managed nodes at the same time. This allows to easily deploy various software components, like database, web server, recorder on multiple dedicated servers using a single command.

Comparing to manual installation commands, Ansible allows to build a completely reproducible server configuration. It is a good practice to test Ansible playbooks towards the staging environment and after verification apply the same configuration to the production environment.

Installation workflow

The following diagram shows the general workflow of an MiaRec installation using Ansible.

In the next chapters, each of these steps is described in details.

This guide refers to the following types of hosts:

  • Controller host, which runs the Ansible playbook
  • Target hosts, where Ansible installs MiaRec software components.

In simple scenarios, like "all-in-one" configuration when all MiaRec software components are deployed on a single host, the same host could be used for both Controller and Target roles, i.e. the Ansible playbook could be run to deploy MiaRec locally. The following diagram demonstrate a difference between these use cases: remote controller and local controller.

In more complex scenarios, like the deployment of MiaRec software components on multiple hosts, the Ansible playbook should be executed from a remote host. The following diagram shows how the remote controller host automatically deploys MiaRec on multiple servers.

1. Prepare controller host

When deploying MiaRec in "all-in-one" configuration on a single server, you can use the same host for both Controller and Target roles. In this case, the Ansible playbook will deploy MiaRec locally.

When deploying MiaRec on multiple servers, it is necessary to use a dedicated host for the Controller role.

Supported operating systems for the Controller host

MiaRec team officially supports the following operating system for the controller host:

  • Centos 7 64-bit
  • Centos 6 64-bit
  • Ubuntu Server 14.04 (Xenial Xerus) LTS 64-bit
  • Ubuntu Server 16.04 (Trusty Tahr) LTS 64-bit
  • Windows 10 with Bash on Ubuntu *

(*) - The Windows 10 machine could be used solely for the Controller role. If you need to install MiaRec software on Windows operating system, then check the guide Installation on Windows.

It is possible to run Ansible playbook from Mac OSX and other operating systems. The complete list of the supported OSs is available in the official Ansible documentation. The MiaRec team provides technical support for the above mentioned OSs only.

Install Ansible on Ubuntu

Install additional software packages and configure Network Time Protocol (NTP). Before you begin, we recommend upgrading your system packages and kernel.

Update package source lists:

sudo apt-get update

Upgrade the system packages and kernel:

sudo apt-get dist-upgrade

Reboot the host.

Install additional software packages if they were not installed during the operating system installation:

sudo apt-get install aptitude build-essential git ntp ntpdate openssh-server libssl-dev 

Install PIP (a tool for installing Python packages. Ansible is written in Python):

sudo apt-get install python-dev python-pip

Install Ansible using PIP:

sudo pip install ansible 

Verify Ansible version:

ansible --version

The output should be something like:

$ ansible --version
ansible 2.3.1.0
  config file = 
  configured module search path = Default w/o overrides
  python version = 2.7.12 (default, Nov 19 2016, 06:48:10) [GCC 5.4.0 20160609]

Verify that ansible version is 2.2+ or higher and python version is either 2.7 or 2.6. If the python version shows 3.x then the installation of Ansible is not correct. Contact the MiaRec representative for support.

Install Ansible on Centos 7

Install additional software packages and configure Network Time Protocol (NTP). Before you begin, we recommend upgrading your system packages and kernel.

Upgrade the system packages and kernel

sudo yum upgrade

Reboot the host.

Install additional software packages if they were not installed during the operating system installation:

sudo yum install git ntp ntpdate openssh-server openssl-devel python-devel libffi-devel '@Development Tools'

Download PIP installer script and run it (PIP is a tool for installing Python packages. Ansible is written in Python):

curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py"
sudo python get-pip.py

Install Ansible using PIP:

sudo pip install ansible 

Verify Ansible version:

ansible --version

The output should be something like:

$ ansible --version
ansible 2.3.1.0
  config file = 
  configured module search path = Default w/o overrides
  python version = 2.7.12 (default, Nov 19 2016, 06:48:10) [GCC 5.4.0 20160609]

Verify that ansible version is 2.2+ or higher and python version is either 2.7 or 2.6. If the python version shows 3.x then the installation of Ansible is not correct. Contact the MiaRec representative for support.

Install the MiaRec ansible scripts

Clone the latest stable release of the MiaRec-Ansible Git repository in the /opt/ansible-miarec directory:

git clone --recursive https://github.com/miarec/ansible-miarec /opt/ansible-miarec

2. Prepare target hosts

This section describes the installation and configuration of operating systems for the target host(s).

MiaRec team officially supports the following operating system for the controller host:

  • Centos/RedHat 6 64-bit
  • Centos/RedHat 7 64-bit
  • Ubuntu Server 14.04 LTS 64-bit
  • Ubuntu Server 16.04 LTS 64-bit

2.1. Configure the operating system (Ubuntu)

Install additional software packages and configure Network Time Protocol (NTP). Before you begin, we recommend upgrading your system packages and kernel.

Update package source lists:

sudo apt-get update

Upgrade the system packages and kernel:

sudo apt-get dist-upgrade

Reboot the host to use the new kernel.

Install additional software packages if they were not installed during the operating system installation:

sudo apt-get install aptitude ntp ntpdate openssh-server acl python

Configure Network Time Protocol (NTP) in /etc/ntp.conf to synchronize with a suitable time source and restart the service:

service ntp restart

2.1. Configure the operating system (RedHat/Centos)

Install additional software packages and configure Network Time Protocol (NTP). Before you begin, we recommend upgrading your system packages and kernel.

Upgrade the system packages and kernel

sudo yum upgrade

Reboot the host to use the new kernel.

Install additional software packages if they were not installed during the operating system installation:

sudo yum install ntp ntpdate openssh-server

Configure Network Time Protocol (NTP) in /etc/ntp.conf to synchronize with a suitable time source and start the service:

# On RedHat/Centos 7 (SystemD)
sudo systemctl enable ntpd.service
sudo systemctl start ntpd.service

2.2. Configured password-less access (optional, recommended)

Skip this step if the same host is used as a controller and target host.

Use the following instructions to setup password-less access from the Ansible controller to the target hosts.

3. Configure deployment

This section describes the configuration of MiaRec deployment. Such configuration should be done on the Ansible controller host.

3.1. Create inventory file (hosts)

The Ansible inventory file is an INI-formatted file that defines the hosts and groups of hosts upon which commands, modules, and tasks in playbooks operate.

Create the file /opt/ansible-miarec/hosts and add entries for every server you want to manage with Ansible (the Inventory File is highly configurable, see the Ansible documentation for more information):

vim /opt/ansible-miarec/hosts

Example 1. Local installation (all-in-one):

For local installation (when Ansible is running on the same host as MiaRec software), create the following hosts file:

[all]
; ---------------------------------
; All-in-one host
; Parameters:
;   - private_ip_address => ip address to access the host from other components (for example, web application needs to connecto to database)
; ---------------------------------

miarec ansible_connection=local private_ip_address=127.0.0.1


[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8


[recorder]
miarec

[screen]
miarec

[db]
miarec

[redis]
miarec

[web]
miarec

[celery]
miarec

[celerybeat]
miarec

Example 2. Remote installation via SSH (all-in-one):

If you are running Ansible playbook from the Controller host over SSH, create the following hosts file (replace 1.2.3.4 ip-address with the target host address):

[all]
; ---------------------------------
; All-in-one host
; Parameters:
;   - ansible_ssh_host => ip address to access the host using Ansible    
;   - ansible_root     => root account to login to server. Usually, 'root', but for Ubuntu it may be 'ubuntu'
;   - private_ip_address => ip address to access the host from other components (for example, web application needs to connecto to database)
;                           For 'all-in-one' setup, the private_ip_address should be set to '127.0.0.1' as all communication is done internally
; ---------------------------------

miarec ansible_host=1.2.3.4 ansible_port=22 ansible_user=root private_ip_address=127.0.0.1


[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8


[recorder]
miarec

[screen]
miarec

[db]
miarec

[redis]
miarec

[web]
miarec

[celery]
miarec

[celerybeat]
miarec

Example 3. Remote installation via SSH to multiple hosts (decoupled architecture):

If you deploy MiaRec components on dedicated hosts, create the following hosts file (replace ip-adresses accordingly):

[all]

; ---------------------------------
; All hosts
; Parameters:
;   - ansible_ssh_host => ip address to access the host using Ansible
;   - ansible_root     => root account to login to server. Usually, 'root', but for Ubuntu it may be 'ubuntu'
;   - private_ip_address => ip address to access the host from other components (for example, web application needs to connecto to database)
;                           For 'all-in-one' setup, the private_ip_address should be set to '127.0.0.1' as all communication is done internally
; ---------------------------------

rec1.miarec  ansible_ssh_host=192.168.88.11  private_ip_address=192.168.88.11  ansible_user=root 
rec2.miarec  ansible_ssh_host=192.168.88.12  private_ip_address=192.168.88.12  ansible_user=root 
db.miarec    ansible_ssh_host=192.168.88.15  private_ip_address=192.168.88.15  ansible_user=root 
redis.miarec ansible_ssh_host=192.168.88.16  private_ip_address=192.168.88.16  ansible_user=root 
web1.miarec  ansible_ssh_host=192.168.88.21  private_ip_address=192.168.88.21  ansible_user=root 
web2.miarec  ansible_ssh_host=192.168.88.22  private_ip_address=192.168.88.22  ansible_user=root 


[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8


[recorder]
rec1.miarec
rec2.miarec

[screen]
rec1.miarec
rec2.miarec

[db]
db.miarec

[redis]
redis.miarec

[web]
web1.miarec
web2.miarec

[celery]
web1.miarec
web2.miarec

[celerybeat]
web1.miarec

In this example, we define two remote machines miarec1 and miarec2 and then place them into group miarec. Ansible playbook is executed against whole group.

Example 4. Remote installation to Amazon EC2 instance using SSH key (all-in-one):

The following example demonstrates how to deploy MiaRec to Amazon EC2 instances (Ubuntu) using SSH private key for connection.

[all]
; ---------------------------------
; All-in-one host
; Parameters:
;   - ansible_ssh_host => ip address to access the host using Ansible    
;   - ansible_root     => root account to login to server. Usually, 'root', but for Ubuntu it may be 'ubuntu'
;   - private_ip_address => ip address to access the host from other components (for example, web application needs to connecto to database)
;                           For 'all-in-one' setup, the private_ip_address should be set to '127.0.0.1' as all communication is done internally
; ---------------------------------

miarec ansible_host=1.2.3.4 ansible_port=22 ansible_user=ubuntu private_ip_address=127.0.0.1 ansible_ssh_private_key_file=~/.ssh/aws-key.pem 


[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8


[recorder]
miarec

[screen]
miarec

[db]
miarec

[redis]
miarec

[web]
miarec

[celery]
miarec

[celerybeat]
miarec

3.2 Edit the version info in the inventory file

The hosts file contains the version of to be installed packages.

You need to edit at least the following parameters:

  • miarecweb_version
  • miarec_version

You can find the latest MiaRec version info at Download page.

Example:

[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8

4. Run playbooks

MiaRec playbooks

MiaRec installation process is split on three playbooks:

  1. The prepare-hosts.yml Ansible foundation playbook installs the infrastructure services (PostgreSQL database, Redis, Apache web server, Python) and configures firewall (iptables). You need to run this playbook only once.

  2. The configure-firewall.yml playbook configures iptables firewall on target host(s). It is optional playbook, but for security reasons, it is recommended to run it. Alternatively, the firewall can be configured manually. You need to run this playbook when firewall rules change.

  3. The setup-miarec.yml playbook installs the MiaRec services, including web portal (miarecweb), recorder (miarec) and screen recording contoller (miarec_screen). Run this playbook for initial installation as well as for subsequent updates.

4.1. Run prepare-hosts.yml playbook to provision the server(s)

The playbook prepare-hosts.yml will install the required packages, like PostgreSQL database, Apache web server, Redis, Python, opens appropriate ports in firewall, etc. Normally you need to run this playbook only once when you prepare the system for MiaRec installation.

In case of remote installation, it is necessary to establish trust relationships between the controller and target machines. When speaking with remote machines, Ansible by default assumes you are using SSH keys. SSH keys are encouraged but password authentication can also be used where needed by supplying the option --ask-pass. You need to supply also the option --ask-sudo-pass if you are connecting to the remote server as non-root user.

When using password authentication, you can run the following command and you will prompted to enter the password for SSH connection:

ansible-playbook prepare-hosts.yml --ask-pass

When using password-less authentication (or when running Ansible locally on target host), you can simply run the following command:

ansible-playbook prepare-hosts.yml

Confirm satisfactory completion with zero items unreachable or failed:

PLAY RECAP ********************************************************************
...
miarec                :  ok=79   changed=42   unreachable=0    failed=0

4.2. Run configure-firewall.yml playbook to enable iptables on the server(s)

CAUTION! MiaRec installer uses iptables as a default firewall. It will be enabled automatically on the target system and other firewall software, if any, will be disabled. For example, on Centos 7, firewalld will be disabled. On Unbuntu 16.04, ufw will be disabled.

Alternatively, you can skip this step and configure firewall for MiaRec manually.

Run playbook:

ansible-playbook configure-firewall.yml

4.3. Run setup-miarec.yml playbook to install or update MiaRec software

The playbook setup-miarec.yml will install the MiaRec software components (recorder, web portal, etc.). You need to run this playbook during initial installation as well as during upgrade of MiaRec to the new version.

To install/update MiaRec, run the following command:

ansible-playbook setup-miarec.yml

Confirm satisfactory completion with zero items unreachable or failed:

PLAY RECAP ********************************************************************
...
miarec                :  ok=38   changed=25   unreachable=0    failed=0

5. Verify MiaRec operation

Use web browser to access MiaRec web portal. Navigate to Administration -> Maintenance -> System Log to check the errors.

Configure appropriate recording interface in Administration -> System -> Recording Interfaces and make a few test calls. Verify that calls are recorded.

It is recommended to reboot the target machine and verify all services are up and running after system reboot.

shutdown -r now
  • PostgreSQL database:

    service postgresql-9.5 status
    
  • Redis cache (use ping command. It should print PONG if success):

    redis-cli ping
    
  • Apache web server

    service httpd status
    
  • Celery task manager

    Centos 6 (init.d):

    service celeryd status
    

    Centos 7 (SystemD):

    systemctl status celeryd
    
  • Celery beat scheduler

    service celerybeat status
    
  • MiaRec recorder

    Centos 6 (Upstart):

    initctl status miarec
    

    Centos 7 (SystemD):

    systemctl status miarec
    
  • MiaRec scree recorder

    Centos 6 (Upstart):

    initctl status miarec_screen
    

    Centos 7 (SystemD):

    systemctl status miarec_screen
    

Update on Linux using Ansible

1. Update the MiaRec version info in the inventory file

On the Ansible controller machine, edit the version info in the inventory file /opt/ansible-miarec/hosts.

Example of this file:

[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
postgresql_version  = 9.5
python_version      = 3.6.3
redis_version       = 3.2.8

The latest MiaRec version info is available at Download page.

2. Run playbook

To update MiaRec, run the following command:

cd /opt/ansible-miarec

ansible-playbook setup-miarec.yml

When using password authentication, then add --ask-pass to the above command.

Confirm satisfactory completion with zero items unreachable or failed:

PLAY RECAP ********************************************************************
...
miarec                :  ok=38   changed=25   unreachable=0    failed=0

Installation on Linux using VMWare OVA template (for testing)

MiaRec OVA template is a pre-installed virtual machine with operating system (Centos 7.3 64-bit) and MiaRec call recording software.

This OVF template is ideal solution for trial. It is easy to import it into VMWare ESX/ESXi or VMWare Workstation.

Request URL to OVA template

Fill the download form to request URL to OVA template.

You need this URL for the next step.

Installation instructions for VMWare ESXi

Login to ESXi via VMWare vCenter Client.

From the menu select File -> Deploy OVF Template...

Inside the opened dialog enter the URL to OVA file, which you received from the MiaRec representative.

Choose a name for this VM, select the desirable disk format (we commend "Thin provisioning" for trial and "Thick provisioning" for production deployment) and click "Finish" to start deploying of the virtual machine.

Configure network for MiaRec VM

Assign static ip-address (if not using DHCP)

By default MiaRec virtual machine is configured to obtain own ip-address from DHCP server. If you would like to use static ip-address for MiaRec VM, then edit file /etc/sysconfig/network-scripts/ifcfg-ens33

vi /etc/sysconfig/network-scripts/ifcfg-ens33

Change BOOTPROTO=dhcp to BOOTPROTO=none and add the following lines to this file:

IPADDR=x.x.x.x
GATEWAY=y.y.y.y
DNS1=8.8.8.8
DNS2=8.8.4.4

Replace x.x.x.x and y.y.y.y with desired machine ip-address and gateway.

Restart network interface:

service network restart

Test the network connection:

ping 8.8.8.8

Update /etc/hostname and /etc/hosts

If you would like to access MiaRec web-portal via dns name rarther than ip-address, then edit files /etc/hostname and /etc/hosts.

Example of /etc/sysconfig/network

HOSTNAME=miarec.example.com

  Example of /etc/hosts

127.0.0.1               miarec.example.com localhost

Restart network:

service network restart

Restart MiaRec recorder service

If the network configuration is updated, then you need to restart miarec recorder service:

service miarec restart

Determining the MiaRec ip-address (when using DHCP)

Login to MiaRec virtual machine as root and execute:

ip a

It will show ip-address assigned to the first network interface.

Root access to OS

root password is miarec

MiaRec web portal access

You need to know the ip-address of virtual machine. It is pre-configured to use DHCP ip-address. If you are using static ip-addresses on your network, then you need to login to Centos with root password and edit network settings.

After that you can access MiaRec web-portal with URL http://VM-IP-ADDRESS

You will be asked to create the admin account when you first time access the web portal.

Trial license

You need to request 30-day trial license for MiaRec call recorder. Open MiaRec web-portal and go to menu Administration -> Maintenance -> License. Click on "Edit license" link and you will see "Computer Id" value. Send it to support@miarec.com to receive a trial license code.

Multi-tenant mode

Navigate to menu Administration -> Customization -> Multitenancy to enable multi-tenancy in MiaRec.

Deploying MiaRec on Amazon AWS (up to 2,000 users)

1. Network architecture

This guide provides step-by-step instructions for deployment of MiaRec call recording software on Amazon AWS.

MiaRec on AWS can leverage many of the services that are designed with High Availability. Depending on anticipated capacity, we recommend two types of HA architecture:

  • Basic HA with two EC2 instances in all-in-one configuration (*). Recommended for up to 2,000 subscribers.
  • Advanced HA with dedicated EC2 instances for each of components. Recommended for more than 2,000 subscribers.

(*) All-in-one configuration means recorder, database, web application and other components are hosted on the same virtual server.

This guide describes the Basic HA setup for recording of up to 2,000 subscribers. The recommended network architecture for MiaRec on AWS is shown in the following diagram.

Components:

  • Two EC2 instances (Virtual Servers) hosting MiaRec software in all-in-one configuration.

  • S3 (Cloud Storage) for long term storage of recorded audio/video files.

  • Route 53 service (Managed Cloud DNS) for DNS failover

High Availability characteristics:

  • Server Redundancy. In the proposed architecture, we have two independent MiaRec servers (EC2 instances). These instances are configured in Hot Standby mode. When the primary server fails, the secondary server is switched into operation. The instances are deployed in different Availability Zones (covered in this guide) or Regions.

  • Data Redundancy. Configuration and call metadata is stored in database. The recorded files are stored in file system. Database data is replicated asynchronously between two MiaRec instances. The audio/video files are uploaded to Amazon S3 storage, which provides replication and redundancy.

  • Auto Failover mechanism. Amazon Route 53 service monitors the health and performance of MiaRec instances. Using DNS failover, it can route the web traffic from an unhealthy instance to a healthy one. For SIPREC traffic, we recommend to use DNS SRV-based failover if the phone platform supports it (DNS SRV-based failover will minimize downtime). If DNS SRV is not supported by phone platform, then it is possible to use Router 53 DNS failover mechanism for SIPREC traffic.

Frequently asked questions:

Why not use DNS round-robin for web traffic load balancing?

Round Robin DNS works by responding to DNS requests with a list of potential IP addresses corresponding to several web servers that host identical resources. The DNS server returns a list of IP addresses in random order.

DNS round robin works the best for load balancing. Failover scenarios are not recommended due to how browsers handle multiple addresses. Modern browsers will choose one of IP addresses and if it cannot connect, the browser will try the next server. the process is user-transparent, and occurs only if the first server tried times out, and only for the first page requested from our site in any browser session. If one of the servers is down for long time, then 50% of users will receive its IP address the first in a list, they will experience high load time (about 3 minutes) for the first page. Older browsers (like IE7) do not support switching to the second IP address, i.e. 50% of users on old browsers will not be able to access the web server (many web-sites today do not support old web browsers, so, this fact probably can be ignored).

Another drawback of DNS round robin technique comes from how MiaRec replicates data between instances. DNS round robin works the best with stateless servers. In this guide, we build stateful MiaRec server, which includes database in the same machine. Data between machines is replicated asynchronously. Asynchronous replication has a lot of advantages comparing to synchronous replication, but there is the expected delay in data synchronization. For example, MiaRec synchronizes only the completed calls. The in-progress calls will be visible on of servers only. If using DNS round robin, then 50% of users will not be able to see in-progress calls.

DNS SRV vs DNS failover for SIPREC traffic

If the phone platform supports DNS SRV for SIPREC, then it should be used as a preferred method. With DNS SRV, the phone platform receives a list of IP-addresses with priorities. The IP-addresses will be tried in particular order depending on record priority/weight. If one of servers does not respond, then the second one will be tried automatically.

The phone platform determines that server is not available based on its SIP response. DNS SRV-based failover time is shorter than DNS failover. The Amazon Route 53 DNS failover uses health checks, which are good for web servers, but they cannot check health of SIP devices.

Depending of implementation, the phone platform can preemptively monitor each of IP-addresses using SIP keep alive mechanism (usually, send SIP OPTIONS message) and make failover time even shorter.

Why upload audio/video files to S3 instead of storing them locally on EC2 instance?

Short answer: costs and reliability.

According to official documentation "Amazon EBS volumes are designed for an annual failure rate (AFR) of between 0.1% - 0.2%, where failure refers to a complete or partial loss of the volume, depending on the size and performance of the volume." Amazon S3 is designed to deliver 99.999999999% durability (documentation).

Amazon EBS volume data is replicated across multiple servers in an Availability Zone. With Amazon S3 data is automatically distributed across a minimum of three physical facilities that are geographically separated by at least 10 kilometers within an AWS Region, and Amazon S3 can also automatically replicate data to any other AWS Region.

EBS costs are $0.10 per GB/month (US East Region, General Purpose SSD). S3 storage costs are $0.023 per GB/month (US East Region, first 50TB).

How to scale this architecture?

The architecture described supports vertical scaling, i.e. the EC2 instance can resized to larger CPU/memory values. You must stop your Amazon EBS–backed instance before you can change its instance type.

How big is a delay in synchronization between servers?

Data is replicated asynchronously. The replication process can be configured to start either by schedule or continuously. In the latter case, call recording metadata and file will be replicated as soon as call completes. Other configuration data, like users/groups/roles will be replicated as soon as the next recording is replicated or up to 1 minute after a change, if call traffic is low.

What happens if the primary server is down?

This is probably the most important question in this guide.

When the primary server is down, then failover mechanism is initiated. Amazon Route 53 service monitors the health and performance of MiaRec instances. If it detects that one the primary server is unhealthy, then DNS records are updated to point to the secondary server. The web traffic will be automatically loaded to the secondary server.

Failover for SIPREC traffic is managed independently of web traffic failover. The phone platform reds a list of IP addresses of recording servers from DNS SVR record. It automatically route SIPREC traffic to the secondary server if the primary server doesn't respond to SIP requests.

If the server is down completely, then both SIPREC and web traffic will be automatically routed to the second instance. This scenario is straight forward. But there is a potential situation when only one of software components experiences issues. For example, web server is not responding on the primary server, but recorder service is fully functioning. In this case, the failover occurs only for web traffic. Such loosely coupled architecture (independence in web and siprec failover events) has some pros and cons. Good thing in MiaRec architecture is it allows the recorder service to continue recording of calls even if other components, like database and web server are completely down. This guarantees that the most critical part of call recording platform is as robust as possible. If, for example, both servers experience problems with the web component, the recording process is not affected at all. In order to detect such enormous situations with partial failure, it is necessary to utilize monitoring tools like CloudWatch, Zabbix or similar.

How much data may be lost in case of primary server is down?

Data between servers is replicated asynchronously by schedule or continuously. In the later case, call metadata will be uploaded to other server as soon as call completes.

If there were in-progress call recordings on the primary server before it died, then such calls will be recorded only partially. If disk storage of the primary server is recovered later, then it is possible to recover the first portion of media for such in-progress calls. The replication process will be restored automatically after the server is alive again.

If the disk storage of the primary server is unrecoverable, then data for in-progress recordings as well as data of not-uploaded yet recordings is lost.

2. Create VPC

A virtual private cloud (VPC) is a virtual network that closely resembles a traditional network that you'd operate in your own data center, with the benefits of using the scalable infrastructure of Amazon Web Services (AWS). You have complete control over your virtual networking environment, including selection of your own IP address range, creation of subnets, and configuration of route tables and network gateways.

In this guide, we will create a dedicated VPC for MiaRec cluster.

Create VPC

To create a VPC:

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
  2. In the dashboard, choose Your VPC and click Create VPC button.
  3. Choose the name which will help you to identify it later in the console.
  4. We use 10.0.0.0/16 for the CIDR block and leave tenancy as default if we don't require dedicated hardware. For more information about IPv4 and IPv6 addressing, see IP Addressing in Your VPC
  5. Click Yes, Create.

MiaRec on AWS

Create subnets

Now let's create two subnets in different Availability Zones. We will deploy two MiaRec instances in different Availability Zones for redundancy. An Availability Zone is a logical data center in Amazon AWS. Each zone has redundant and separate power, networking and connectivity to reduce the likelihood of two zones failing simultaneously.

To create subnets:

  1. In the VPC Dashboard, choose Subnets and click Create Subnet button.
  2. Choose the name
  3. Associated this subnet with the previously created VPC.
  4. Select different different Availability Zones for each of subnets.
  5. We use 10.0.1.0/24 for one subnet and 10.0.2.0/24 for the second

MiaRec on AWS

MiaRec on AWS

In this example, we created two subnets:

Subnet name Availability Zone IPv4 CIDR block
miarec-public-10.0.1.0 us-east-1a 10.0.1.0/24
miarec-public-10.0.2.0 us-east-1b 10.0.2.0/24

Create Internet Gateway

Up to now all our subnets are private. We need to create Internet Gateway. An Internet gateway is a virtual router that connects a VPC to the Internet. An Internet gateway serves two purposes: to provide a target in your VPC route tables for Internet-routable traffic, and to perform network address translation (NAT) for instances that have been assigned public IPv4 addresses.

To create Internet Gateway:

  1. In the VPC Dashboard, choose Internet Gateways and click Create Internet Gateway button.
  2. Choose the name
  3. Click Yes, Create
  4. Select the newly created Internet Gateway from the list and click Attach to VPC to associate it with your MiaRec VPC.
  5. Click Yes, Attach

MiaRec on AWS

MiaRec on AWS

MiaRec on AWS

Associate subnets with Route Table

Now we need to associate the subnets with Route Table.

  1. Navigate to Route Tables in VPC Dashboard.
  2. Select the existing route table associated with your newly created VPC.
  3. Press the Subnet Associations tab on the bottom section. Click Edit.
  4. Select the subnets and click Save

MiaRec on AWS

MiaRec on AWS

Configure default gateway

We need to add a custom route table for destination 0.0.0.0/0 and Internet Gateway as a target. This will allow our machines to communicate to public Internet, for example, to download software updates.

  1. Navigate to Route Tables in VPC Dashboard.
  2. Select the existing route table associated with your newly created VPC.
  3. Press the Routes tab on the bottom section. Click Add another route
  4. Create Destination 0.0.0.0/0 with the newly created Internet Gateway as a Target.

MiaRec on AWS

Next step

3. Create EC2 instances

We are going to launch two EC2 instances and install MiaRec software on them. These two instances will be created in different Availability Zones for redundancy.

To create EC instance:

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2
  2. Select Instances in the left pane and click Launch Instance

Step 1. Choose an Amazon Machine Image (AMI)

Select Ubuntu Server 14.04 LTS, EBS General Purpose (SSD) Volume Type.

MiaRec supports the following operating systems:

  • Centos 6
  • Centos 7
  • Ubuntu Server 14.04 LTS
  • Ubuntu Server 16.04 LTS.

MiaRec on AWS

Step 2. Choose an Instance Type

Amazon EC2 provides a wide selection of instance types optimized to fit different use cases. Instances are virtual servers that can run applications. They have varying combinations of CPU, memory, storage, and networking capacity.

For MiaRec, we recommend Compute Optimized instances. Refer to the following table for instance type recommendations. These recommendations are based on average system usage (10 calls per day per user, 5 minutes average call duration). Actual hardware requirements may be differ in your case.

Max subscribers Instance Type vCPU Memory (GiB) Storage On-demand, Monthly * 1-Year Term, No Upfront, Monthly *
250 c4.large 2 3.75 GiB EBS only $72.00 $45.99
500 c4.xlarge 4 8 GiB EBS only $143.28 $91.98
1,000 c4.2xlarge 8 15 GiB EBS only $286.56 $183.96
2,000 c4.4xlarge 16 31 GiB EBS only $573.12 $367.92

(*) - The provided pricing as of data of article (Septempter, 2017) for US-East region, Linux host (Centos/Ubuntu/Amazon Linux).

More than 2,000 users? We recommend to use a decoupled architecture instead of all-in-one setup.

MiaRec on AWS

Step 3. Configure Instance Details

Choose separate subnets for each of two MiaRec instances. This will allow to deploy them in different Availability Zones for redundancy.

Shutdown behavior should be set to Stop.

We recommend to Enable termination protection as a protection from accidental deletion of server.

MiaRec on AWS

Step 4. Add Storage

Specify the desired disk storage size for EBS volume.

  • As a Volume Type select General Purpose SSD as a minimum. For high load, it is possible to select Provisioned IOPS SSD (it is more expensive, but provides guaranteed I/O performance).

Imporant!. Uncheck Delete on Termination. This will allow you to detach this EBS volume from EC2 instance and attach to new one, for example, with better hardware specs.

Disk storage will be used for:

  • OS and application files
  • Database data files, approximately 3GB per 1 million records in database
  • Application logs
  • Temporary location for audio files (before the files are uploaded to S3 for long term storage). 0.24 MB/minute in MP3 stereo format. We recommend to keep available disk space for at least 3 days of data. In case of issues in upload process to S3, it gives enough time to administrator to troubleshoot and fix issue. This will make the system less dependent on S3 availability.
Number of users Avg calls/day/user Avg duration Total minutes/day Storage/day Recommended EBS volume
50 10 5 min 75,000 min 18 GB 100 GB
100 10 5 min 150,000 min 36 GB 150 GB
250 10 5 min 375,000 min 90 GB 320 GB
500 10 5 min 750,000 min 180 GB 600 GB
1,000 10 5 min 1,500,000 min 360 GB 1,200 GB
2,000 10 5 min 3,000,000 min 720 GB 2,400 GB

MiaRec on AWS

Step 6. Configure Security Group

A security group is a set of firewall rules that control the traffic for your instance.

MiaRec application requires the following ports to be opened:

  • TCP 22 for SSH inbound connection
  • TCP 80 and 443 for web server
  • TCP 6554 and UDP 7000-7999 for live monitoring (optional)
  • TCP/UDP 5080 for SIPREC signaling and UDP 20000-23999 for RTP media (these port values can be changed in MiaRec web admin portal)

Important!. In the following example, SIPREC and RTP ports are opened to all sources (0.0.0.0/0). For security reasons, access to these ports should be limited to your phone only. Specify there the IP-addresses, from which your phone system sends SIPREC and RTP traffic.

MiaRec on AWS

Create SSH keys

When you launch an instance, you should specify the name of the key pair you plan to use to connect to the instance. You can use Amazon EC2 to create your key pair. Alternatively, you could use a third-party tool and then import the public key to Amazon EC2.

If you use Amazon to create your key pair, then you have to download the private key file (*.pem file) and store it in a secure and accessible location. You will use this key to access the instance via SSH.

MiaRec on AWS

Check status of running instances

Navigate to Instances section of EC2 Dashboard to see your new instance running.

MiaRec on AWS

Next step

4. Configure Elastic IP address

An Elastic IP address is a public IPv4 address, which is reachable from the Internet. An Elastic IP address is associated with your AWS account. With an Elastic IP address, you can mask the failure of an instance or software by rapidly remapping the address to another instance in your account.

We need to create an Elastip IP address for each MiaRec instance as both of them will be accessible from the Internet.

To allocate Elastic IP address:

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2
  2. Select Elastic IP address in the left pane and click Allocate new address
  3. Once the IP address is allocated, select it in a list and choose Associate address from Actions drop-down.
  4. Associate the IP address with EC2 instances.
  5. Repeat these steps for the second EC2 instance.

MiaRec on AWS

MiaRec on AWS

MiaRec on AWS

5. Install MiaRec software on EC2 instance

We will deploy MiaRec to Amazon EC2 instances using Ansible provisioning tool.

You need to follow the step-by-step instructions "Installation on Linux using Ansible" with a few additions described below.

You can run Ansible playbook from:

  • Any Linux host with Internet access (Ubuntu, Centos, Redhat). Mac OS X should work as well, but not tested by us.
  • Windows 10 with Linux subsystem
  • Another EC2 instance.

Copy SSH private key to Ansible Controller machine

You need to use previously created key to access the instance via SSH. Check Connecting to Your Linux Instance Using SSH for details.

Copy the private key to the Ansible Controller machine, for example, to ~/.ssh/aws-key.pem.

Use the chmod command to make sure that your private key file isn't publicly viewable:

chmod 400 ~/.ssh/aws-key.pem

Test SSH connection to EC2 instance:

ssh -i ~/.ssh/aws-miarec.pem ubuntu@34.235.2.126

If everything is ok, you should see the following message the first time you connect to it:

The authenticity of host '34.235.2.126 (34.235.2.126)' can't be established.
ECDSA key fingerprint is SHA256:uTU/hyG+7qy1Aq0CxliKekYDWXZI0EEAaPkmXuA9K9M.
Are you sure you want to continue connecting (yes/no)?

Enter yes. You should connect to the instance now and see Ubuntu welcome message like:

Welcome to Ubuntu 14.04.5 LTS (GNU/Linux 3.13.0-125-generic x86_64)

* Documentation:  https://help.ubuntu.com/

System information as of Fri Sep 22 01:32:04 UTC 2017

System load:  0.0                Processes:           103
Usage of /:   0.6% of 125.86GB   Users logged in:     0
Memory usage: 2%                 IP address for eth0: 10.0.1.65
Swap usage:   0%

Create Inventory file (/opt/ansible-miarec/hosts)

In the step [3. Configure deployment] of instructions, you will need to create hosts file. If you selected Ubuntu as OS for EC2 instance, then create the following file:

miarec1 ansible_ssh_host=1.1.1.1 ansible_ssh_private_key_file=~/.ssh/aws-key.pem ansible_port=22 ansible_user=ubuntu
miarec2 ansible_ssh_host=2.2.2.2 ansible_ssh_private_key_file=~/.ssh/aws-key.pem ansible_port=22 ansible_user=ubuntu

[miarec]
miarec1
miarec2

Where:

  • Two hosts are defined inside group miarec. Ansible playbook will be executed against all hosts in group. By default, installation will be done simultaneously.
  • Replace 1.1.1.1 and 2.2.2.2 with public ip-addresses of your EC2 instances (these should point to Elastic IP addresses created previously).
  • The parameter ansible_ssh_private_key specifies the location of SSH private key for connecting to EC2 instance (in our example, it is ~/.ssh/aws-key.pem).
  • The parameter ansible_user is set to ubuntu for Ubuntu system. For Centos, you need to set it to root.

Now, test Ansible connection to AWS using the command:

 ansible miarec -m shell -a "uname -a" 

This command will connect to all hosts in group miarec in inventory file and print the output of command uname -a.

You should see something like:

miarec1 | SUCCESS | rc=0 >>
Linux ip-10-0-1-65 3.13.0-125-generic #174-Ubuntu SMP Mon Jul 10 18:51:24 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux

miarec2 | SUCCESS | rc=0 >>
Linux ip-10-0-2-73 3.13.0-125-generic #174-Ubuntu SMP Mon Jul 10 18:51:24 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux

Deploy MiaRec to EC2 instances

Follow instructions to deploy MiaRec on EC2 instances using Ansible.

Verify MiaRec web portal and create admin account

Navigate in web browser to the Elastic IP address of each of MiaRec instances, like http://1.2.3.4.

When you access MiaRec web portal the first time, it will ask you to create admin account. You need to create unique accounts for these two servers, like "admin" and "admin2". This is necessary to prevent conflicts during synchronization between servers.

MiaRec on AWS

Next steps

6. Configure Route 53 DNS Failover for web traffic

Amazon Route 53 service monitors the health and performance of MiaRec instances. Using DNS failover, it can route the web traffic from an unhealthy instance to a healthy one.

Prerequisites:

  • Your domain name has to be managed by Amazon Route 53, otherwise it will not be possible to use DNS Failover. You can register new domain name for your MiaRec HA cluster or use existing one.

Create Hosted Zone

  1. Sign in to the AWS Management Console and open the Amazon Route 53 console at https://console.aws.amazon.com/route53/.
  2. In the navigation pane of the Route 53 console, choose Hosted zones, and then choose Create Hosted Zone.
  3. Enter the registered domain name into Domain Name. In this guide, we use domain miarecorder.com as an example.

MiaRec on AWS

Create A-records for MiaRec servers (miarec1 and miarec2)

We need to create DNS A-record for each of our MiaRec servers. In this example, we use "miarec1" and "miarec2", but you can name it whatever you want.

Name Type Alias TTL Value Routing Policy
miarec1 A No 300 x.x.x.x Simple
miarec2 A No 300 y.y.y.y Simple

Where:

  • x.x.x.x is the Elastic IP address (public) of the first MiaRec instance
  • y.y.y.y is the Elastic IP address (public) of the second MiaRec instance

To create A-records:

  1. In the navigation pane of the Route 53 console, choose Hosted zones, select the domain name, and then choose Create Record Set.
  2. Choose A - IPv4 address for Type.
  3. Enter Elastic IP address of the MiaRec EC2 instance into Value field.
  4. Choose Simple for Routing Policy
  5. A default TTL value is ok
  6. Repeat these steps for the second MiaRec EC2 instance.

MiaRec on AWS

Create Health checks for MiaRec web servers

For DNS Failover, we need to configure health checks for each of servers.

For each MiaRec instance:

  1. In the navigation pane of the Route 53 console, choose Hosted checks, select the domain name, and then choose Create health check.
  2. Choose a convenient name, like "miarec-www-primary" and "miarec-www-secondary".
  3. Choose Domain name from Specify endpoint by options.
  4. Choose HTTP for Protocol (this option should be HTTPS if HTTP is disabled)
  5. Enter the DNS name of the MiaRec EC2 instance, in our example, domain names are "miarec1.miarecorder.com" and "miarec2.miarecorder.com".
  6. Choose 80 for Port
  7. Enter "login" for Path (this health check will verify if login page is accessible).
  8. Keep other settings as default.
  9. Repeat these steps for the second MiaRec EC2 instance.

MiaRec on AWS

In a couple of minutes, you should be able to see health check report as shown in the following screenshot.

MiaRec on AWS

Create DNS A-record for web traffic (with failover)

Now, we are going to create DNS A-record, which will be used by end users for accessing MiaRec web portal, something like "recordings.mycompany.com". We will configure DNS Failover for this record. Amazon Route 53 services will route web traffic to the secondary server, when health check for the primary server returns error.

Create two records with the following settings:

Name Type Alias TTL Value Routing Policy Failover Record Type Set ID Health Check to Associate
recordings A No 60 x.x.x.x Failover Primary recordings-Primary miarec-www-primary
recordings A No 60 y.y.y.y Failover Secondary recordings-Secondary miarec-www-secondary

Where:

  • x.x.x.x is the Elastic IP address (public) of the first MiaRec instance
  • y.y.y.y is the Elastic IP address (public) of the second MiaRec instance

To create A-records with DNS Failover, repeat for each MiaRec instance:

  1. In the navigation pane of the Route 53 console, choose Hosted zones, select the domain name, and then choose Create Record Set.
  2. Choose A - IPv4 address for Type.
  3. Select 60 for TTL. Recommended value is between 30 to 60 seconds. Each client caches DNS records. In case of failover, the web browser may attempt to access the unhealthy instance until cache expires.
  4. Enter Elastic IP address of the MiaRec EC2 instance into Value field.
  5. Choose Failover for Routing Policy
  6. Choose Primary for the first instance and Secondary for the second instance for Failover Record Type
  7. Choose a convenient name for Set ID
  8. Associate this record to the corresponding health check, created previously.
  9. Repeat these steps for the second MiaRec EC2 instance.

Below screenshots, demonstrate configuration of Record Set for both MiaRec instances.

MiaRec on AWS

MiaRec on AWS

Test DNS failover

Navigate in web browser to http://recordings.yourdomain.com.

Login as administrator and navigate to Administration -> Maintenance -> Recording Servers. You should see the private IP address of this instance. This information allows you to determine on which instance you are now. The primary instance should be in a subnet 10.0.1.x and the secondary in 10.0.2.x.

MiaRec on AWS

Now, simulate failure using one of the following methods:

  • Stop Apache web server using SSH (on Ubuntu the command is sudo service apache2 stop, on Centos it is sudo service httpd stop).
  • Shutdown the server via SSH using command sudo shutdown -h now
  • Stop instance via Actions menu in Amazon EC2 Dashboard.

Try to access MiaRec web portal using web browser. It may take a few minutes for Amazon Route 53 to detect server failure (by default, it checks the server health every 30 seconds and requires at least 3 consecutive failures before the server is marked unhealthy). Once the server is marked unhealthy, the domain name http://recordings.yourdomain.com is automatically routed to the secondary MiaRec instance IP-address. If the TTL value is reasonably small (no more than 60 seconds), then failover should shortly after that.

Within 3-4 minutes, you should be able to access the MiaRec web portal again. Login as administrator and navigate Administration -> Maintenance -> Recording Servers to check on which instance you are now.

MiaRec on AWS

Now, restore the primary server and verify if web-traffic is routed back to it after 3-5 minutes.

7. Configure DNS SRV for SIPREC traffic

The SRV record is a Domain Name System (DNS) resource record that is used to identify servers that host specific services. Each of servers is assigned a priority and weight, which allows to use DNS SRV for failover, load balancing or both. In this guide, we use DNS SRV for failover purposes only. For load balancing, we recommend to use different architecture (decoupled).

To create DNS SRV records in Route 53:

  1. In the navigation pane of the Route 53 console, choose Hosted zones, select the domain name, and then choose Create Record Set.
  2. Choose SRV - Service locator for Type.
  3. Enter the following data into Value field:

    1 10 5080 miarec1.yourdomain.com
    2 10 5080 miarec2.yourdomain.com
    

    Here, we configure two servers with priority 1 and 2 correspondingly. In this configuration the phone platform will always use the miarec1.yourdomain.com server (priority 1) unless it is not healthy.

  4. A default TTL value is ok

  5. Choose Simple for Routing Policy

The following screenshot demonstrates the configuration of DNS SRV:

MiaRec on AWS

8. Configure SIPREC recording

Configure SIPREC recording interface in MiaRec

We need to configure public ip-address in each of MiaRec instances. MiaRec will advertise this ip-address to the phone platform in SDP media description info (ip-address and port on which it expects to receive RTP packets from the phone platform).

Navigate in MiaRec web portal to Administration -> System -> Recording Interfaces -> SIPREC -> Configure.

Configure the Elastic IP address in each of two MiaRec instances. See below screenshot for details:

MiaRec on AWS

Configure SIPREC recording interface in your phone platform

Refer to the corresponding documentation for your phone platform.

References:

Test recording

Make some test calls and locate the recordings in MiaRec web portal.

Test SIPREC failover

Simulate failure on the primary server (shutdown instance or stop "miarec" service) and verify if recording is switched over to the secondary instance.

9. Configure automatic file relocation to Amazon S3

1. Create an S3 bucket

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. Choose Create bucket.

    MiaRec on AWS

  3. In the Bucket name field, type a unique DNS-compliant name for your new bucket. (The example screen shot uses the bucket name miarec-s3-storage. You cannot use this name because S3 bucket names must be unique.) Create your own bucket name using the follow naming guidelines:

    • The name must be unique across all existing bucket names in Amazon S3.
    • After you create the bucket you cannot change the name, so choose wisely.
    • Choose a bucket name that reflects the objects in the bucket because the bucket name is visible in the URL that points to the objects that you're going to put in your bucket.

    For information about naming buckets, see Rules for Bucket Naming in the Amazon Simple Storage Service Developer Guide.

  4. For Region, choose the region where you want the bucket to reside. You can use the same region as you were using for VPC in previous steps.

    MiaRec on AWS

  5. At the step 3. Set permissions, make sure that public access is not granted.

    MiaRec on AWS

  6. Click Create bucket in the last screen.

2. Create policy that grants access to the S3 bucket

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane on the left, click Policies and then click Create Policy.

    MiaRec on AWS

  3. Next to Create Your Own Policy, click Select.

    MiaRec on AWS

  4. Copy the following access policy and paste it into the Policy Document field. And replace miarec-s3-storage with your bucket name).

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::miarec-s3-storage"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::miarec-s3-storage/*"
            ]
        }
    ]
    }
    

    MiaRec on AWS

3. Create IAM user

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane on the left, click Users and then click Add user.

    MiaRec on AWS

  3. On Details screen, choose User name and enable Proigrammatic access.

    MiaRec on AWS

  4. On Permissions screen, select Attach existing policies directly and then select the previously created policy from the list. Use the search box to find the policy by name.

    MiaRec on AWS

  5. Review the settings and click Create user.

    MiaRec on AWS

  6. On Complete screen, copy Access Key ID and Secret access Key and store them in secure place. We will use it for configuring storage target in MiaRec.

    MiaRec on AWS

4. Add Cross-Origin Resource Sharing (CORS) configuration to an S3 bucket

Cross-Origin Resource Sharing (CORS) allows client web applications that are loaded in one domain to interact with resources in another domain. This configuration is required for our setup because MiaRec web application is accessible using one domain (for example, https://recorder.example.com), but audio files are located at Amazon S3 domain (https://s3.amazonaws.com)

To add a CORS configuration to an S3 bucket:

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the Bucket name list, choose the name of the bucket that you want to create a bucket policy for.

    MiaRec on AWS

  3. Choose Permissions, and then choose CORS configuration.

    MiaRec on AWS

  4. Copy the following CORS configuration and paste it into the CORS configuration editor field:

    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
    </CORSConfiguration>
    

    MiaRec on AWS

  5. Choose Save.

5. Configure Storage Target in MiaRec

  1. Navigate in MiaRec web portal to Administration -> Storage -> Storage Targets and choose Add.

  2. Select Amazon S3 in Storage Target Type. Configure S3 Bucket, AWS Access Key ID and AWS Secret Access Key accordingly (as configured in the previous steps).

    MiaRec on AWS

6. Configure automatic file relocation to S3 storate target

  1. Navigate in MiaRec web portal to Administration -> Storage -> Relocate Recording files and choose Add job.

  2. Configure Storage Target. Change Mode to Incremental. Select scheduler setting Run this job to Continuously (optionally, you can configure a scheduled relocation, for example, at night).

    MiaRec on AWS

Make a few test calls and check status of this job. It is expected that files are automatically relocated to S3.

<a href="/files/doc-img/amazon_aws/job_relocate_files2.png">
  ![MiaRec on AWS](/files/doc-img/amazon_aws/job_relocate_files2.png){.lightbox}
</a>

Navigate to Amazon S3 console and verify that files are located there:

<a href="/files/doc-img/amazon_aws/s3_bucket_files.png">
  ![MiaRec on AWS](/files/doc-img/amazon_aws/s3_bucket_files.png){.lightbox}
</a>

10. Configure MiaRec replication

Documentation is in progress... Please, check later or contact our Support Team anytime.

11. Configure HTTPS for web server

Documentation is in progress... Please, check later or contact our Support Team anytime.

12. Configure CloudWatch monitoring

Documentation is in progress... Please, check later or contact our Support Team anytime.

13. Disaster recovery plan

Documentation is in progress... Please, check later or contact our Support Team anytime.

Manual installation on Linux (deprecated)

Installation on Linux (Centos/RedHat) manually (deprecated)

MiaRec solution consists of multiple components:

  • MiaRec Recorder
  • Database (PostgreSQL)
  • MiaRec Web portal

These components may be installed all on a single server or each on a dedicated server.

MiaRec Architecture

Install MiaRec Web portal

MiaRec web portal requires the following components:

  • PostgreSQL database
  • Apache web server
  • Python 3 (required for running web portal scripts)
  • Redis (high speed in-memory caching)
  • Celery (scheduler and background task manager)

See also: MiaRec Architecture

Install PostgreSQL

This guide provides instructions how to install PostgreSQL for MiaRec.

Preparing The System

Update system default applications:

yum update

Configure your YUM repository

Postgres is included into default repository of CentOS / Red Hat / Fedora, but its version is not up to date.

Locate and edit your distributions .repo file, located:

  • On Fedora: /etc/yum.repos.d/fedora.repo and /etc/yum.repos.d/fedora-updates.repo, [fedora] sections
  • On CentOS: /etc/yum.repos.d/CentOS-Base.repo, [base] and [updates] sections
  • On Red Hat: /etc/yum/pluginconf.d/rhnplugin.conf [main] section

To the section(s) identified above, you need to append a line (otherwise dependencies might resolve to the postgresql supplied by the base repository):

exclude=postgresql*

For example, on Centos 6 the .repo file should be:

[base]
name=CentOS-$releasever - Base
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=os&infra=$infra
#baseurl=http://mirror.centos.org/centos/$releasever/os/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6
exclude=postgresql*

#released updates
[updates]
name=CentOS-$releasever - Updates
mirrorlist=http://mirrorlist.centos.org/?release=$releasever&arch=$basearch&repo=updates&infra=$infra
#baseurl=http://mirror.centos.org/centos/$releasever/updates/$basearch/
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-CentOS-6
exclude=postgresql*

Install PGDG RPM file

A PGDG file is available for each distribution/architecture/database version combination. Browse http://yum.postgresql.org and find your correct RPM. For example, to install PostgreSQL 9.4 on CentOS 6 64-bit:

Centos 6:

yum localinstall http://yum.postgresql.org/9.4/redhat/rhel-6-x86_64/pgdg-centos94-9.4-2.noarch.rpm

Centos 7:

yum localinstall http://yum.postgresql.org/9.4/redhat/rhel-7-x86_64/pgdg-centos94-9.4-2.noarch.rpm

Install PostgreSQL database server and its extensions

yum install postgresql94-server postgresql94-contrib

Initialize data directory

After installing the packages, a database needs to be initialized and configured.

service postgresql-9.4 initdb

If the previous command did not work, try directly calling the setup binary, located in:

/usr/pgsql-9.4/bin/postgresql94-setup initdb

Configure start at boot up

chkconfig postgresql-9.4 on

Start PostgreSQL database service

service postgresql-9.4 start

Create MiaRec user and database

In this example we create user 'miarec' and database 'miarecdb'.

First, connect/login as root:

su - postgres
psql

This will open psql command-line interface.

Create user (replace 'password' with something more secure):

CREATE USER miarec PASSWORD 'password';

Create database:

CREATE DATABASE miarecdb WITH ENCODING 'UNICODE' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;
ALTER DATABASE miarecdb OWNER TO miarec;

Connect to "miarecdb" database:

\c miarecdb;

Install uuid-ossp and hstore extensions into "miarecdb" database:

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "hstore";

Enter \q to exit from psql command-line interface:

\q

Exit from postgres sudo:

exit

PostgreSQL Configuration

The postgresql server is using two main configuration files

  • /var/lib/pgsql/9.4/data/pg_hba.conf
  • /var/lib/pgsql/9.4/data/postgresql.conf

Edit pg_hba.conf

vi /var/lib/pgsql/9.4/data/pg_hba.conf

Change authentication method from ident to md5 for localhost connections.

Change:

host    all   all     127.0.0.1/32       ident

To:

host    all   all     127.0.0.1/32        md5

When other MiaRec components are deployed on dedicated servers, then you need to add their ip-addresses to trust group. For example:

host    all   all     192.168.0.10/32    md5      # allow access from 192.168.0.10
host    all   all     192.168.1.1/24     md5      # allow access from network 192.168.1.1/24

Edit postgresql.conf (optional)

vi /var/lib/pgsql/9.4/data/postgresql.conf

If other MiaRec components (like recorder and web portal) are deployed on dedicated servers, then you need to configure postgres to accept inbound network connections. Change:

listen_addresses = 'localhost'

to

listen_addresses = '*'

Restart PostgreSQL

service postgresql-9.4 restart

Install Python 3

1. Preparing The System

Update system default applications:

yum update

Install required packages for building python:

yum install openssl-devel sqlite-devel gcc wget

2. Build python 3 from source code

Download latest stable Python 3 source code files from https://www.python.org/downloads/source/. MiaRecWeb was tested with Python v.3.4

wget https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tgz

Extract source code:

tar -xzvf Python-3.*.tgz

Build Python binaries:

cd Python-3*
./configure --enable-shared
make

Option --enable-shared is necessary in order to create shared library *.so files, which will be used later when compiling Apache mod_wsgi module.

3. Install Python

Normally, one would use “make install”; however, in order not to override system defaults - replacing the Python already used by the system - we will use make altinstall.

make altinstall

This will install python into /usr/local/bin with name, which contains version, like /usr/local/bin/python3.4.

4. Add Python shared libraries to PATH

By default Python installed *.so files into /usr/local/lib On some RedHat-based systems this directory is not searched when loading shared libraries. To fix that, you need to edit file /etc/ld.so.conf. add line usr_local_lib.conf to the fiin directory /etc/ld.so.conf.d

vi /etc/ld.so.conf

Add the following line to that file:

/usr/local/lib

Run ldconfig:

ldconfig

Install Apache web server

Install Apache web server and required packages

yum install httpd httpd-devel openssl openssl-devel

Configure start at boot up

chkconfig httpd on

Start Apache web server

service httpd start

Install Redis cache

Download Redis from http://redis.io/download:

wget http://download.redis.io/releases/redis-3.0.0.tar.gz

Extract it and compile with:

tar -xzvf redis-3.0.0.tar.gz
cd redis-3.0.0
make

Install binaries:

make install

Create data directory for redis

This directory will work as data and working directory for your Redis instance:

mkdir -p /var/redis/6379

Create configuration file for redis

Create a directory where to store your Redis config files:

mkdir /etc/redis

Copy the template configuration file you'll find in the root directory of the Redis distribution into /etc/redis/ using the port number as name, for instance:

cp redis.conf /etc/redis/6379.conf

Edit this file, making sure to perform the following changes:

vi /etc/redis/6379.conf
  • Set daemonize to yes (by default it is set to no).
  • Set the pidfile to /var/run/redis_6379.pid (modify the port if needed).
  • Change the port accordingly. In our example it is not needed as the default port is already 6379.
  • Set your preferred loglevel.
  • Set the logfile to /var/log/redis_6379.log
  • Set the dir to /var/redis/6379 (very important step!)
  • Uncomment line # bind 127.0.0.1 (very important step for security reasons! With such settings redis will be accessible only from localhost. It will reject connections from outside network.)

Create init script for redis

  • Copy the init script that you'll find in the Redis distribution under the utils directory into /etc/init.d. We suggest calling it with the name of the port where you are running this instance of Redis. For example:

    cp utils/redis_init_script /etc/init.d/redis_6379
    
  • Edit the init script.

    vi /etc/init.d/redis_6379
    

    Add the following lines at the top of init script (below line #!/bin/sh):

    
    #!/bin/sh
    #
    # Simple Redis init.d script conceived to work on Linux systems
    # as it does use of the /proc filesystem.
    #
    # chkconfig:   - 85 15
    # description:  Redis is a persistent key-value database
    # processname: redis
    

    Make sure to modify REDIS_PORT accordingly to the port you are using. Both the pid file path and the configuration file name depend on the port number.

  • Finally add the new Redis init script to all the default runlevels using the following command:

    chkconfig --add redis_6379
    chkconfig redis_6379 on
    

You are done! Now you can try running your instance with:

/etc/init.d/redis_6379 start

Verify Redis installation

Make sure that everything is working as expected:

  • Try pinging your instance with redis-cli ping.
  • Do a test save with redis-cli save and check that the dump file is correctly stored into /var/redis/6379/ (you should find a file called dump.rdb).
  • Check that your Redis instance is correctly logging in the log file /var/log/redis_6379.log.
  • If it's a new machine where you can try it without problems make sure that after a reboot everything is still working.

Install MiaRec web application

1.1. Installed required packages

yum install postgresql94-devel gcc libffi-devel openssl-devel libxml2-devel libxslt-devel

1.2. Create python virtual environment

It is best practice to install MiaRec web application into a "virtual" Python environment in order to obtain isolation from any "system" packages you've got installed in your Python version. This can be done by using the virtualenv package. Using a virtualenv will also prevent MiaRec from globally installing versions of packages that are not compatible with your system Python.

Upgrade pip and setuptools to the latest version:

python3 -m pip install -U pip setuptools

On Centos 7 you may need to run python3.4 ... instead of python3 ...

Create virtual environment:

mkdir /var/www/miarec
python3 -m venv /var/www/miarec/pyenv

1.3. Install MiaRec web application

Fill the download form to request URL to MiaRec Web portal installation files.

Download MiaRec web application archive:

wget CONTACT_US_FOR_URL

Extract:

tar -xzvf miarecweb*.tar.gz

Move it to /var/www/miarec/app

mv miarecweb-*/ /var/www/miarec/app

Make sure that postgresql pg_config file is in PATH (it is required by psycopg2 python package). Execute in shell:

PATH=$PATH:/usr/pgsql-9.4/bin/

Activate virtual environment:

source /var/www/miarec/pyenv/bin/activate

Upgrade pip to the latest version:

pip install --upgrade pip

Install MiaRec web application into python environment:

pip install -e /var/www/miarec/app

Create log and cache directories for MiaRec web application:

mkdir /var/log/miarecweb
mkdir /var/www/miarec/cache

Make Apache an owner of these directories. So, it can create log and cache files there.

chown apache:apache /var/log/miarecweb
chown apache:apache /var/www/miarec/cache

2. Configure MiaRec web portal application

Create production.ini file from a sample file (production.ini.sample):

cp /var/www/miarec/app/production.ini.sample /var/www/miarec/production.ini

Edit production.ini file:

vi /var/www/miarec/production.ini

Change in this file the following parameters according to previously installed PostgreSQL and Redis:

  • DATABASE_HOST (use 127.0.0.1 if database is installed on the same host)
  • DATABASE_PORT (default is 5432)
  • DATABASE_NAME (should match to previously created database name, default is miarecdb)
  • DATABASE_USER (should match to previously created database user for miarec, default is miarec)
  • DATABASE_PASSWORD (should match to previously created database user password)
  • REDIS_HOST (use 127.0.0.1 if Redis is installed on the same host)
  • REDIS_PORT (default is 6379)

If Redis service is configured with non-default port (which is 6379), then replace 6379 with appropriate port number. If Redis service is running on a dedicated server, then replace 127.0.0.1 to appropriate ip-address.

3. Initialize MiaRec database layout

source /var/www/miarec/pyenv/bin/activate

alembic -c /var/www/miarec/production.ini upgrade head

4. Build and install Apache mod_wsgi module.

Download source code of mod_wsgi module from: https://github.com/GrahamDumpleton/mod_wsgi/releases

cd ~
wget https://github.com/GrahamDumpleton/mod_wsgi/archive/4.4.11.tar.gz

Activate previously created python virtual environment. This is necessary because CentOS has older Python version 2.7 and we need to build mod_wsgi for new python 3.4.

source /var/www/miarec/pyenv/bin/activate

Extract, build and install:

tar -xzvf 4.4.11.tar.gz
cd mod_wsgi*
./configure
make
make install

Disable SELinux because it causes Segmentation fault when Apache loads mod_wsgi module.

sed -i s/SELINUX=enforcing/SELINUX=disabled/g /etc/selinux/config

Reboot of server is required.

shutdown -r now

5. Edit Apache configuration file

Copy miarec.wsgi.sample into miarec.wsgi. This is a configuration for MiaRec WSGI application, which will be executed inside Apache web server.

cp /var/www/miarec/app/miarec.wsgi.sample /var/www/miarec/miarec.wsgi

Create miarec.conf file inside /etc/httpd/conf.d directory:

vi /etc/httpd/conf.d/miarec.conf

Content of this file:

Apache version 2.2 (for Centos 6):

LoadModule wsgi_module modules/mod_wsgi.so

WSGISocketPrefix run/wsgi

# Use only 1 Python sub-interpreter.  Multiple sub-interpreters
# play badly with C extensions.  See http://stackoverflow.com/a/10558360/209039
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On

WSGIDaemonProcess miarec user=apache group=apache python-path=/var/www/miarec/pyenv/lib/python3.4/site-packages
WSGIProcessGroup miarec

Alias /favicon.ico /var/www/miarec/app/miarecweb/static/favicon.ico
Alias /static /var/www/miarec/app/miarecweb/static

WSGIScriptAlias / /var/www/miarec/miarec.wsgi process-group=miarec

<Directory /var/www/miarec/app/miarecweb/static>
  AllowOverride None
  Order deny,allow
  Allow from all
</Directory>

<Directory /var/www/miarec>
  <Files miarec.wsgi>
      Order deny,allow
      Allow from all
  </Files>
</Directory>

Apache version 2.4 (for Centos 7):

LoadModule wsgi_module modules/mod_wsgi.so

WSGISocketPrefix run/wsgi

# Use only 1 Python sub-interpreter.  Multiple sub-interpreters
# play badly with C extensions.  See http://stackoverflow.com/a/10558360/209039
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On

WSGIDaemonProcess miarec user=apache group=apache python-path=/var/www/miarec/pyenv/lib/python3.4/site-packages
WSGIProcessGroup miarec

Alias /favicon.ico /var/www/miarec/app/miarecweb/static/favicon.ico
Alias /static /var/www/miarec/app/miarecweb/static

WSGIScriptAlias / /var/www/miarec/miarec.wsgi process-group=miarec

<Directory /var/www/miarec/app/miarecweb/static>
  AllowOverride None
  Require all granted
</Directory>

<Directory /var/www/miarec>
  <Files miarec.wsgi>
    Require all granted
  </Files>
</Directory>

Restart Apache:

service httpd restart

6. Access MiaRec web-portal with web-browser

Now you should be access MiaRec from web browser with URL http://ADDRESS

You may need to configure firewall exception rules on the server to allow inbound connections to the server on port 80.

7. Troubleshooting

If you receive "500 Internal Server Error" when accessing MiaRec web portal, then you can check Apache error log file:

less /var/log/httpd/error_log

Install Celery task manager

Celery is an asynchronous task queue/job queue system, which is used by MiaRec web portal for different tasks (long running tasks and/or periodic jobs).

Celery itself is already installed on your system when you deployed MiaRecWeb portal. The only missing part is to run Celery as a daemon.

There are two celery daemons:

  • Celery worker executes long-running jobs like call backup/restore, purge deleted records etc.
  • Celery scheduler manages periodic tasks. It loads job schedule configuration from MiaRec and initiates execution of these jobs by Celery worker at regular intervals.

The current document is based on official celery documentation.

1. Celery worker daemon (celeryd)

1.1. Create init.d startup script

Download default init.d script from celery Github repository:

cd ~
wget https://raw.githubusercontent.com/celery/celery/3.1/extra/generic-init.d/celeryd

Make it executable:

chmod +x celeryd

Move to /etc/init.d/

mv celeryd /etc/init.d/

1.2. Create celery worker configuration file

vi /etc/default/celeryd

Content of this file should be:

# Names of nodes to start
CELERYD_NODES="worker1"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/var/www/miarec/pyenv/bin/celery"

# App instance to use
CELERY_APP="miarecweb.celery_app"

# Where to chdir at start.
CELERYD_CHDIR="/var/www/miarec/pyenv"

# Extra command-line arguments to the worker
CELERYD_OPTS="--time-limit=300 -Ofair --concurrency=8 --ini-file=/var/www/miarec/production.ini"

# %N will be replaced with the first part of the nodename.
CELERYD_LOG_FILE="/var/log/miarec/celery/%N.log"
CELERYD_PID_FILE="/var/run/celery/%N.pid"

# Create log/pid dirs, if they don't already exist
CELERY_CREATE_DIRS=1

CELERYD_LOG_LEVEL="WARN"

CELERYD_USER="root"
CELERYD_GROUP="root"

1.3. Install this init.d script and configure it to start automatically during boot process

chkconfig --add celeryd
chkconfig celeryd on

1.5. Start celery

service celeryd start

2. Celery scheduler daemon (celerybeat)

2.1. Create init.d startup script for celery scheduler

Download default init.d script from celery Github repository:

cd ~
wget https://raw.githubusercontent.com/celery/celery/3.1/extra/generic-init.d/celerybeat

Make it executable:

chmod +x celerybeat

Move to /etc/init.d/

mv celerybeat /etc/init.d/

2.2. Create celery scheduler configuration file

vi /etc/default/celerybeat

Content of this file should be:

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/var/www/miarec/pyenv/bin/celery"

# App instance to use
CELERY_APP="miarecweb.celery_app"

# Where to chdir at start.
CELERYBEAT_CHDIR="/var/www/miarec/pyenv"

# Extra command-line arguments to the scheduler
CELERYBEAT_OPTS="-S miarecweb.jobs.scheduler.JobScheduler --ini-file /var/www/miarec/production.ini"

CELERYBEAT_LOG_FILE="/var/log/miarec/celery/beat.log"
CELERYBEAT_PID_FILE="/var/run/celery/beat.pid"

# Create log/pid dirs, if they don't already exist
CELERY_CREATE_DIRS=1

CELERYBEAT_LOG_LEVEL="WARN"

CELERYBEAT_USER="root"
CELERYBEAT_GROUP="root"

2.3. Install this init.d script and configure it to start automatically during boot process

chkconfig --add celerybeat
chkconfig celerybeat on

2.4. Start celery beat

service celerybeat start

2.5. Configure logrotate to automatically delete old logs

Create file /etc/logrotate.d/celery with the following content:

/var/log/miarec/celery/*.log {
    missingok
    notifempty
    compress
    delaycompress
    copytruncate
    daily
    dateext
    rotate 7
    size 10M
}

Install MiaRec Recorder

1. Install required packages

yum install libpcap

2. Download MiaRec installation files:

Fill the download form to request URL to MiaRec recorder installation files.

wget CONTACT_US_FOR_URL

Extract:

tar -xzvf miarec-*.tar.gz
cd miarec-*

3. Install MiaRec recorder

Copy binary file to /usr/local/bin/

cp miarec /usr/local/bin/

Copy configuration files to /etc/miarec/

mkdir /etc/miarec
cp miarec.ini /etc/miarec/
cp -r sqlconfig /etc/miarec/

Create /var/lib/miarec directory. It will be used as current directory when running MiaRec process. MiaRec process reads SOAP wsdl file from current directory and stores some temporary files there.

mkdir /var/lib/miarec
cp WebServices.wsdl /var/lib/miarec/

Create log directories

mkdir -p /var/log/miarec

Create directory for recording files

mkdir -p /var/miarec/recordings

4. Create startup script

There is a few variants of start-up scripts depending on OS and version:

5. Edit miarec.ini configuration file

vi /etc/miarec/miarec.ini

Change database connection settings (host, port, database, user, password). There are two places in INI files, where you need to edit database settings:

5.1. Module which loads configuration from database

#-----------------------------------------------------------------
#    SQLConfig
#-----------------------------------------------------------------
#  Loading configuration from SQL database
#-----------------------------------------------------------------
################################################################################
[SQLConfig]
################################################################################

#  Database Driver type.
#  Supported values: 
#    PostgreSQL
#-------------------------------------------------------------------------------
Driver=PostgreSQL
#-------------------------------------------------------------------------------


#  Host of database server
#-------------------------------------------------------------------------------
Host=127.0.0.1:5432
#-------------------------------------------------------------------------------


#  Database name
#-------------------------------------------------------------------------------
Database=miarecdb
#-------------------------------------------------------------------------------


#  Username and password for accessing database. Should have write permissions.
#-------------------------------------------------------------------------------
Username=miarec
Password=password
#-------------------------------------------------------------------------------

5.2. Module, which writes call detail records (CDRs) to database:

#-----------------------------------------------------------------
#  Configuration section for SQLCallsLog module. This module stores calls log into database
#  Supported call events:
#    start,connect,update,stop,stream_start,stream_stop
#-----------------------------------------------------------------
################################################################################
[SQLCallsLog]
################################################################################

#  Database Driver type.
#  Supported values: 
#    PostgreSQL
#-------------------------------------------------------------------------------
Driver=PostgreSQL
#-------------------------------------------------------------------------------


#  Host of database server
#-------------------------------------------------------------------------------
Host=127.0.0.1:5432
#-------------------------------------------------------------------------------


#  Database name
#-------------------------------------------------------------------------------
Database=miarecdb
#-------------------------------------------------------------------------------


#  Username and password for accessing database. Should have write permissions.
#-------------------------------------------------------------------------------
Username=miarec
Password=password
#-------------------------------------------------------------------------------

6. Restart MiaRec service

When using Upstart:

initctl stop miarec
initctl start miarec

When using init.d or SystemD:

service miarec restart

SystemD start-up script (Centos 7.x)

Create startup script miarec.service in directory /etc/systemd/system/

vi /etc/systemd/system/miarec.service

Content of this file:

[Unit]
Description=MiaRec
After=network.target

[Service]
Type=simple
WorkingDirectory=/var/lib/miarec
ExecStart=/usr/local/bin/miarec --pid /var/run/miarec.pid --core unlimited -c /etc/miarec/miarec.ini
Restart=always
User=root
Group=root
LimitNOFILE=10240
LimitFSIZE=infinity

[Install]
WantedBy=multi-user.target

It is important that WorkingDirectory setting points to directory, where WebServices.wsdl file is located.

Install this startup script:

systemctl enable miarec

Start MiaRec process

systemctl start miarec

Upstart start-up script (Centos 6.x)

Create file /etc/init/miarec.conf

vi /etc/init/miarec.conf

Content of this file:

description "MiaRec call recorder"
author      "MiaRec, Inc. www.miarec.com"

env EXEC=/usr/local/bin/miarec
env PIDFILE=/var/run/miarec.pid
env CONFFILE=/etc/miarec/miarec.ini

start on started sshd
stop on runlevel [!2345]

console output

# Increase open file descriptors limit
limit nofile 10240 10240

# Restart automatically proces in case of crash
respawn

# Stop respawn if it occured more than 10 times during 60 seconds period.
# This means serious problems
respawn limit 10 60

# Current working directory for MiaRec process
chdir /var/lib/miarec

# Enable core dumps for troubleshooting
limit core unlimited unlimited

instance miarec
exec $EXEC -c $CONFFILE --pid $PIDFILE

Reload Upstart configuration

initctl reload-configuration

Validate that miarec is in a list of processes:

initctl list

If you do not see there miarec then check errors in /var/log/messages

Start MiaRec process

initctl start miarec

Stop MiaRec process

initctl stop miarec

Restart MiaRec process

initctl stop miarec
initctl start miarec

Init.d start-up script

Note, this script doesn't support automatic respawn of process in case of abnormal exit (for example, due to app crash). We recommend using alternative methods which support respawn:

  • Upstart for RedHat/Centos 6.x
  • SystemD for RedHat/Centos 7.x

Create startup script miarec in directory /etc/init.d

vi /etc/init.d/miarec

Content of this file:

#!/bin/sh
#
# Startup sript for MiaRec call recorder
# 
# chkconfig: - 80 20
# description: MiaRec call recorder
# processname: miarec
# config: /etc/miarec.ini
#

EXEC=/usr/local/bin/miarec
PIDFILE=/var/run/miarec.pid
LOCKFILE=/var/lock/subsys/miarec
CONF=/etc/miarec/miarec.ini
CHDIR=/var/lib/miarec
RETVAL=0

# Source function library.
. /etc/rc.d/init.d/functions


start() {
        if [ -f $PIDFILE ]
        then
                RETVAL=1
                echo "$PIDFILE exists, process is already running or crashed" && failure
                echo
                return $RETVAL
        else
                echo "Staring MiaRec recorder..."
                cd $CHDIR
                ulimit -Hn 10240
                ulimit -Sn 10240
                $EXEC -c $CONF --pid $PIDFILE --core unlimited > /dev/null 2>&1 &
                RETVAL=$?
                [ $RETVAL -eq 0 ] && touch $LOCKFILE && success || failure
                echo
                return $RETVAL
        fi
}

stop() {
        echo "Stopping..."
        if [ ! -f $PIDFILE ]
        then
                RETVAL=1
                echo "$PIDFILE does not exist, process is not running" && warning
                echo
            return $RETVAL
        else
                PID=$(cat $PIDFILE)
                kill -TERM $PID
                rm -f $LOCKFILE
                echo "MiaRec stopped" && success
                echo
        fi
}


case "$1" in
        start)
                start
                ;;
        stop)
                stop
                ;;
        restart)
                stop
                start
                ;;
        *)
                echo "Please use start, stop or restart as first argument"
                RETVAL=2
                ;;
esac

exit $RETVAL

Make this script executable:

chmod +x /etc/init.d/miarec

Add it to autostart during boot:

chkconfig --add miarec
chkconfig miarec on

Install MiaRec Screen Recording Controller

1. Install required packages

yum install openssl

2. Prepare directories for MiaRec screen recorder controller application:

mkdir -p /opt/miarec_screen/log
mkdir -p /opt/miarec_screen/shared
mkdir -p /opt/miarec_screen/releases

3. Download MiaRec installation files into /opt/miarec_screen/releases:

Fill the download form to request URL to MiaRec Screen Recorder Controller installation files.

cd /opt/miarec_screen/releases

wget CONTACT_US_FOR_URL

Extract:

tar -xzvf miarec_screen-*.tar.gz

4. Create symlink to the new relase:

ln -s /opt/miarec_screen/releases/miarec_screen-<REPLACE-WITH-YOUR-VERSION>  /opt/miarec_screen/current 

Using the symlink allows to easily fallback to different version if necessary.

5. Create directory for storing of screen recording files

In this example, we use directory /var/miarec/screen_recordings You can choose other directory and configure it via Web admin portal (menu Administration -> Screen Recording -> Screen Recording Settings).

6. Edit miarec.ini configuration file

vi /opt/miarec_screen/current/miarec_screen.ini

Change database connection settings (host, port, database, user, password) and redis connection settings. Redis is used as a message broker between various MiaRec components

6.1. Module which loads configuration from database

################################################################################
[Database]
################################################################################

#  Database Driver type.
#  Supported values: 
#    PostgreSQL
#-------------------------------------------------------------------------------
Driver=PostgreSQL
#-------------------------------------------------------------------------------


#  Host of database server
#-------------------------------------------------------------------------------
Host=127.0.0.1:5432
#-------------------------------------------------------------------------------


#  Database name
#-------------------------------------------------------------------------------
Database=miarecdb
#-------------------------------------------------------------------------------


#  Username and password for accessing database. Should have write permissions.
#-------------------------------------------------------------------------------
Username=miarec
Password=password
#-------------------------------------------------------------------------------

6.2. Redis connection settings:

################################################################################
[RedisSubscriber]
################################################################################
#  Host of redis server
#-------------------------------------------------------------------------------
Host=localhost:6379
#-------------------------------------------------------------------------------

7. Create startup script

There is a few variants of start-up scripts depending on OS and version:

7.1 Upstart start-up script for RedHat/Centos 6 and Ubuntu 14.04 LTS

Create file /etc/init/miarec_screen.conf

vi /etc/init/miarec_screen.conf

Content of this file:

description "MiaRec screen recorder"
author      "MiaRec, Inc. www.miarec.com"

env EXEC=/opt/miarec_screen/current/miarec_screen
env PIDFILE=/var/run/miarec_screen.pid
env CONFFILE=/opt/miarec_screen/current/miarec_screen.ini

start on started sshd
stop on runlevel [!2345]

console output

# Increase open file descriptors limit
limit nofile 10240 10240

# Restart automatically proces in case of crash
respawn

# Stop respawn if it occured more than 10 times during 60 seconds period.
# This means serious problems
respawn limit 10 60

# Current working directory for MiaRec process
chdir /opt/miarec_screen/current

# Enable core dumps for troubleshooting
limit core unlimited unlimited

instance miarec
exec $EXEC -c $CONFFILE --pid $PIDFILE

Reload Upstart configuration

initctl reload-configuration

Validate that miarec is in a list of processes:

initctl list

If you do not see there miarec then check errors in /var/log/messages

Start MiaRec process

initctl start miarec_screen

Stop MiaRec process

initctl stop miarec_screen

Restart MiaRec process

initctl stop miarec_screen
initctl start miarec_screen

7.2 SystemD start-up script for RedHat/Centos 7

Create file /etc/systemd/system/miarec_screen.service

vi /etc/systemd/system/miarec_screen.service

Content of this file:

[Unit]
Description=MiaRec Screen Recorder
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/miarec_screen/current
ExecStart=/opt/miarec_screen/current/miarec_screen --pid /var/run/miarec_screen.pid --core unlimited -c /opt/miarec_screen/current/miarec_screen.ini
Restart=always
User=root
Group=root
LimitNOFILE=10240
LimitFSIZE=infinity

[Install]
WantedBy=multi-user.target

Install this startup script:

systemctl enable miarec_screen

Start MiaRec process

systemctl start miarec_screen

6. Restart MiaRec service

When using Upstart:

initctl stop miarec_screen
initctl start miarec_screen

When using init.d or SystemD:

service miarec_screen restart

Configure firewall

By default MiaRec uses the following ports, which should be added into firewall exclusion list.

Port Description
80 (tcp) MiaRec Web-portal (HTTP protocol)
443 (tcp) MiaRec Web-portal (HTTPS protocol). Requires installation of SSL certificate.
6554 (tcp) Live monitoring signaling (RTSP protocol)
7000 - 7999 (udp) Live monitoring media (RTP protocol)
5070 (tcp) Cisco SIP trunk recording signaling (SIP protocol)
20000 - 21999 (udp) Cisco SIP trunk recording media (RTP protocol)
5080 (tcp, udp) SIPREC recording signaling (SIP protocol)
22000 - 23999 (udp) SIPREC recording media (RTP protocol)

Instructions for iptables (Centos 6)

This document describes how to configure iptables.

Execute command iptables --line -vnL to see the current list of rule with line numbers. Example output:

[root@miarec ~]# iptables --line -vnL
Chain INPUT (policy ACCEPT 0 packets, 0 bytes)
num   pkts bytes target     prot opt in     out     source               destination         
1     3124 1264K ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           state RELATED,ESTABLISHED 
2        0     0 ACCEPT     icmp --  *      *       0.0.0.0/0            0.0.0.0/0           
3       11  3292 ACCEPT     all  --  lo     *       0.0.0.0/0            0.0.0.0/0           
4        0     0 ACCEPT     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           state NEW tcp dpt:22 
5       63  4881 REJECT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           reject-with icmp-host-prohibited 

Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
num   pkts bytes target     prot opt in     out     source               destination         
1        0     0 REJECT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           reject-with icmp-host-prohibited 

Chain OUTPUT (policy ACCEPT 2937 packets, 1212K bytes)
num   pkts bytes target     prot opt in     out     source               destination         

From this output we need to get the line number of the generic REJECT rule. In example above it is at line #5. We will need to add our exclusion rules just above this line.

  • Web-portal rule (port 80 tcp)

    iptables -I INPUT 5 -i eth0 -p tcp --dport 80 -m state --state NEW,ESTABLISHED -j ACCEPT
    
  • Live monitoring rules

    iptables -I INPUT 5 -i eth0 -p tcp --dport 6554 -m state --state NEW,ESTABLISHED -j ACCEPT
    iptables -I INPUT 5 -i eth0 -p udp --dport 7000:7999 -m state --state NEW,ESTABLISHED -j ACCEPT
    
  • Cisco SIP trunk recording interface rules

    iptables -I INPUT 5 -i eth0 -p udp --dport 5070 -m state --state NEW,ESTABLISHED -j ACCEPT
    iptables -I INPUT 5 -i eth0 -p tcp --dport 5070 -m state --state NEW,ESTABLISHED -j ACCEPT
    iptables -I INPUT 5 -i eth0 -p udp --dport 20000:21999 -m state --state NEW,ESTABLISHED -j ACCEPT
    
  • SIPREC recording interface rules

    iptables -I INPUT 5 -i eth0 -p udp --dport 5080 -m state --state NEW,ESTABLISHED -j ACCEPT
    iptables -I INPUT 5 -i eth0 -p tcp --dport 5080 -m state --state NEW,ESTABLISHED -j ACCEPT
    iptables -I INPUT 5 -i eth0 -p udp --dport 22000:23999 -m state --state NEW,ESTABLISHED -j ACCEPT
    
  • Save all rules into iptables configuration file

    service iptables save
    
  • Restart iptables service

    service iptables restart
    

Instructions for firewall-cmd (Centos 7)

  • Web-portal rule (port 80 tcp)

    firewall-cmd --permanent --zone=public --add-port=80/tcp
    
  • Live monitoring rules

    firewall-cmd --permanent --zone=public --add-port=6554/tcp
    firewall-cmd --permanent --zone=public --add-port=7000-7999/udp
    
  • Cisco SIP trunk recording interface rules

    firewall-cmd --permanent --zone=public --add-port=5070/udp
    firewall-cmd --permanent --zone=public --add-port=5070/tcp
    firewall-cmd --permanent --zone=public --add-port=20000-21999/udp
    
  • SIPREC recording interface rules

    firewall-cmd --permanent --zone=public --add-port=5080/udp
    firewall-cmd --permanent --zone=public --add-port=5080/tcp
    firewall-cmd --permanent --zone=public --add-port=22000-23999/udp
    
  • Reload firewall-cmd configuration

    firewall-cmd --reload
    

Verify services status

Reboot machine and check if all services are up and running:

shutdown -r now
  • PostgreSQL database:

    service postgresql-9.4 status
    
  • Redis cache (use ping command. It should print PONG if success):

    redis-cli ping
    
  • Apache web server

    service httpd status
    
  • Celery task manager

    Centos 6 (init.d):

    service celeryd status
    

    Centos 7 (SystemD):

    systemctl status celeryd
    
  • Celery beat scheduler

    service celerybeat status
    
  • MiaRec recorder

    Centos 6 (Upstart):

    initctl status miarec
    

    Centos 7 (SystemD):

    systemctl status miarec
    

Installation on Linux (Ubuntu) manually (deprecated)

MiaRec solution consists of multiple components:

  • MiaRec Recorder
  • Database (PostgreSQL)
  • MiaRec Web portal

These components may be installed all on a single server or each on a dedicated server.

MiaRec Architecture

Install MiaRec Web portal

MiaRec web portal requires the following components:

  • PostgreSQL database
  • Apache web server
  • Python 3 (required for running web portal scripts)
  • Redis (high speed in-memory caching)
  • Celery (scheduler and background task manager)

See also: MiaRec Architecture

Install PostgreSQL

This guide provides instructions how to install PostgreSQL for MiaRec.

Preparing The System

Update system default applications:

sudo apt-get update

Configure PostgreSQL Apt repository

These instructions are based on http://www.postgresql.org/download/linux/ubuntu/

Postgres is included into default repository of Ubuntu LTS, but its version is not up to date.

Create the file /etc/apt/sources.list.d/pgdg.list and add a line for the repository:

deb http://apt.postgresql.org/pub/repos/apt/ trusty-pgdg main

Import the repository signing key, and update the package lists:

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
sudo apt-key add -
sudo apt-get update

Then install the required version.

sudo apt-get install postgresql-9.4 postgresql-contrib-9.4

Create MiaRec user and database

The default database name and database user are postgres. Switch to postgres user to perform the following operations.

In this example we create user 'miarec' and database 'miarecdb'.

First, start psql command-line interface as postgres user:

sudo -u postgres psql postgres

Create user for MiaRec application:

CREATE USER miarec PASSWORD 'password';

Create MiaRec database:

CREATE DATABASE miarecdb WITH ENCODING 'UNICODE' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;
ALTER DATABASE miarecdb OWNER TO miarec;

Connect to "miarecdb" database:

\c miarecdb;

Install uuid-ossp and hstore extensions into "miarecdb" database:

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
CREATE EXTENSION IF NOT EXISTS "hstore";

Enter \q to exit from psql command-line interface:

\q

PostgreSQL Configuration

The postgresql server is using two main configuration files

  • /etc/postgresql/9.4/main/pg_hba.conf
  • /etc/postgresql/9.4/main/postgresql.conf

pg_hba.conf

Change authentication method from ident to md5 for localhost connections.

Change:

host    all   all     127.0.0.1/32       ident

To:

host    all   all     127.0.0.1/32        md5

When other MiaRec components are deployed on dedicated servers, then you need to add their ip-addresses to trust group. For example:

host    all   all     192.168.0.10/32    md5      # allow access from 192.168.0.10
host    all   all     192.168.1.1/24     md5      # allow access from network 192.168.1.1/24

postgresql.conf

If other MiaRec components (like recorder and web portal) are deployed on dedicated servers, then you need to configure postgres to accept network connections. Change:

listen_addresses = 'localhost'

to

listen_addresses = '*'

Restart PostgreSQL

service postgresql restart

Install Python

Install python 3 from default repository.

sudo apt-get install python3

Execute the following command and make sure that it is at lease version 3.4:

python3 --version

If it is older, then you need to install python 3 manually from sources.

Install Apache web server

Install Apache web server and required packages

sudo apt-get install apache2 apache2-dev openssl libssl-dev

Start Apache web server

sudo service apache2 start

Install Redis cache

Download Redis from http://redis.io/download:

wget http://download.redis.io/releases/redis-3.2.1.tar.gz

Extract it and compile with:

tar -xzvf redis-3.2.1.tar.gz
cd redis-3.2.1
make

Install binaries:

sudo make install

Create init script for redis

  • Create a directory where to store your Redis config files and your data:

    sudo mkdir /etc/redis
    sudo mkdir /var/redis
    
  • Copy the init script that you'll find in the Redis distribution under the utils directory into /etc/init.d. We suggest calling it with the name of the port where you are running this instance of Redis. For example:

    sudo cp utils/redis_init_script /etc/init.d/redis_6379
    
  • Edit the init script.

    sudo vim /etc/init.d/redis_6379
    

    Add the following lines at the top of init script (below line #!/bin/sh):

    #!/bin/sh
    #
    # Simple Redis init.d script conceived to work on Linux systems
    # as it does use of the /proc filesystem.
    #
    # chkconfig:   - 85 15
    # description:  Redis is a persistent key-value database
    #
    # processname: redis
    ### BEGIN INIT INFO
    # Provides: redis_6379
    # Required-Start:    $network $remote_fs $local_fs
    # Required-Stop:     $network $remote_fs $local_fs
    # Default-Start:     2 3 4 5
    # Default-Stop:      0 1 6
    # Short-Description: start and stop redis_6379
    # Description: Redis daemon
    ### END INIT INFO
    

    Make sure to modify REDIS_PORT accordingly to the port you are using. Both the pid file path and the configuration file name depend on the port number.

  • Copy the template configuration file you'll find in the root directory of the Redis distribution into /etc/redis/ using the port number as name, for instance:

    sudo cp redis.conf /etc/redis/6379.conf
    
  • Create a directory inside /var/redis that will work as data and working directory for this Redis instance:

    sudo mkdir /var/redis/6379
    
  • Edit the configuration file, making sure to perform the following changes:

    sudo vim /etc/redis/6379.conf
    
    • Set daemonize to yes (by default it is set to no).

      # By default Redis does not run as a daemon. Use 'yes' if you need it.
      # Note that Redis will write a pid file in /var/run/redis.pid when daemonized.
      
      daemonize yes
      
    • Set the pidfile to /var/run/redis_6379.pid (modify the port if needed).

      # If a pid file is specified, Redis writes it where specified at startup
      # and removes it at exit.
      #
      # When the server runs non daemonized, no pid file is created if none is
      # specified in the configuration. When the server is daemonized, the pid file
      # is used even if not specified, defaulting to "/var/run/redis.pid".
      #
      # Creating a pid file is best effort: if Redis is not able to create it
      # nothing bad happens, the server will start and run normally.
      
      pidfile /var/run/redis_6379.pid
      
    • Change the port accordingly. In our example it is not needed as the default port is already 6379.

      # Accept connections on the specified port, default is 6379 (IANA #815344).
      # If port 0 is specified Redis will not listen on a TCP socket.
      
      port 6379
      
    • Set your preferred loglevel.

      # Specify the server verbosity level.
      # This can be one of:
      # debug (a lot of information, useful for development/testing)
      # verbose (many rarely useful info, but not a mess like the debug level)
      # notice (moderately verbose, what you want in production probably)
      # warning (only very important / critical messages are logged)
      
      loglevel notice
      
    • Set the logfile to /var/log/redis_6379.log

      # Specify the log file name. Also the empty string can be used to force
      # Redis to log on the standard output. Note that if you use standard
      # output for logging but daemonize, logs will be sent to /dev/null
      
      logfile "/var/log/redis_6379.log"
      
    • Set the dir to /var/redis/6379

      # The working directory.
      #
      # The DB will be written inside this directory, with the filename specified
      # above using the 'dbfilename' configuration directive.
      #
      # The Append Only File will also be created inside this directory.
      #
      # Note that you must specify a directory here, not a file name.
      
      dir /var/redis/6379
      
    • Uncomment line # bind 127.0.0.1 (very important step for security reasons! With such settings redis will be accessible only from localhost. It will reject connections from outside network.)

      # ~~~ WARNING ~~~ If the computer running Redis is directly exposed to the
      # internet, binding to all the interfaces is dangerous and will expose the
      # instance to everybody on the internet. So by default we uncomment the
      # following bind directive, that will force Redis to listen only into
      # the IPv4 lookback interface address (this means Redis will be able to
      # accept connections only from clients running into the same computer it
      # is running).
      #
      # IF YOU ARE SURE YOU WANT YOUR INSTANCE TO LISTEN TO ALL THE INTERFACES
      # JUST COMMENT THE FOLLOWING LINE.
      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      
      bind 127.0.0.1
      
  • Finally add the new Redis init script to all the default runlevels using the following command:

    sudo update-rc.d redis_6379 defaults
    

You are done! Now you can try running your instance with:

sudo /etc/init.d/redis_6379 start

Make sure that everything is working as expected:

  • Try pinging your instance with redis-cli ping.
  • Do a test save with redis-cli save and check that the dump file is correctly stored into /var/redis/6379/ (you should find a file called dump.rdb).
  • Check that your Redis instance is correctly logging in the log file /var/log/redis_6379.log.
  • If it's a new machine where you can try it without problems make sure that after a reboot everything is still working.

Install MiaRec web application

1.1. Installed required packages

sudo apt-get install libpq-dev gcc libffi-dev libssl-dev python3-setuptools python3-dev

1.2. Create python virtual environment

It is best practice to install MiaRec web application into a "virtual" Python environment in order to obtain isolation from any "system" packages you've got installed in your Python version. This can be done by using the virtualenv package. Using a virtualenv will also prevent MiaRec from globally installing versions of packages that are not compatible with your system Python.

Install python pip package:

sudo apt-get install python3-pip

Install python venv package (modify python version in this command according to your python version, see output of python3 --version):

sudo apt-get install python3.4-venv

Create virtual environment:

sudo apt-get install python3-venv

sudo easy_install3 virtualenv

Create virtual environment:

mkdir /var/www/miarec
python3 -m venv /var/www/miarec/pyenv

1.3. Install MiaRec web application

Contact us (sales@miarec.com) to receive URL to MiaRec installation files.

Download MiaRec web application archive:

wget CONTACT_US_FOR_URL

Extract:

tar -xzvf miarecweb*.tar.gz

Move it to /var/www/miarec/app

mv miarecweb-*/ /var/www/miarec/app

Activate virtual environment:

sudo su
source /var/www/miarec/pyenv/bin/activate

Note, sudo su command is necessary because by default /var/www/ directory is not writable for non-root users in Ubuntu. We are going to install MiaRec web portal files into that directory. That's why you need to switch to root account now.

Upgrade pip to the latest version:

pip install --upgrade pip

Install MiaRec web application into python environment:

pip install -e /var/www/miarec/app

Create log and cache directories for MiaRec web application:

mkdir /var/log/miarecweb
mkdir /var/www/miarec/cache

Make Apache an owner of theses directory. So, it can create log and cache files there.

chown www-data:www-data /var/log/miarecweb
chown www-data:www-data /var/www/miarec/cache

2. Configure MiaRec web portal application

Copy production.ini file from a sample file:

cp /var/www/miarec/app/production.ini.sample /var/www/miarec/production.ini

Edit production.ini file:

vim /var/www/miarec/production.ini

Change in this file the following parameters according to previously installed PostgreSQL and Redis:

  • DATABASE_HOST (use 127.0.0.1 if database is installed on the same host)
  • DATABASE_PORT (default is 5432)
  • DATABASE_NAME (should match to previously created database name, default is miarecdb)
  • DATABASE_USER (should match to previously created database user for miarec, default is miarec)
  • DATABASE_PASSWORD (should match to previously created database user password)
  • REDIS_HOST (use 127.0.0.1 if Redis is installed on the same host)
  • REDIS_PORT (default is 6379)

If Redis service is configured with non-default port (which is 6379), then replace 6379 with appropriate port number. If Redis service is running on a dedicated server, then replace 127.0.0.1 to appropriate ip-address.

3. Initialize MiaRec database layout

source /var/www/miarec/pyenv/bin/activate

alembic -c /var/www/miarec/production.ini upgrade head

4. Install Apache mod_wsgi module.

sudo apt-get install libapache2-mod-wsgi-py3

Copy miarec.wsgi.sample into miarec.wsgi

cp /var/www/miarec/app/miarec.wsgi.sample /var/www/miarec/miarec.wsgi

5. Edit Apache configuration file

Create miarec.conf file inside /etc/apache2/sites-available directory:

vi /etc/apache2/sites-available/miarec.conf

Content of this file:

# Use only 1 Python sub-interpreter.  Multiple sub-interpreters
# play badly with C extensions.  See http://stackoverflow.com/a/10558360/209039
WSGIApplicationGroup %{GLOBAL}
WSGIPassAuthorization On

WSGIDaemonProcess miarec user=www-data group=www-data python-path=/var/www/miarec/pyenv/lib/python3.4/site-packages
WSGIScriptAlias / /var/www/miarec/miarec.wsgi process-group=miarec
WSGIProcessGroup miarec

<Directory /var/www/miarec/app>
  Require all granted
</Directory>

Disable a default site:

a2dissite 000-default

Enable miarec site:

a2ensite miarec

Restart Apache:

service apache2 reload

6. Access MiaRec web-portal with web-browser

Now you should be access MiaRec from web browser with URL http://

You may need to configure firewall exception rules on the server to allow inbound connections to the server on port 80.

Install Celery task manager

Celery is an asynchronous task queue/job queue system, which is used by MiaRec web portal for different tasks (long running tasks and/or periodic jobs).

Celery itself is already installed on your system when you deployed MiaRecWeb portal. The only missing part is to run Celery as a daemon.

There are two celery daemons:

  • Celery worker executes long-running jobs like call backup/restore, purge deleted records etc.
  • Celery scheduler manages periodic tasks. It loads job schedule configuration from MiaRec and initiates execution of these jobs by Celery worker at regular intervals.

The current document is based on official celery documentation.

1. Celery worker daemon (celeryd)

1.1. Create init.d startup script

Download default init.d script from celery Github repository:

cd ~
wget https://raw.githubusercontent.com/celery/celery/3.1/extra/generic-init.d/celeryd

Make it executable:

chmod +x celeryd

Move to /etc/init.d/

mv celeryd /etc/init.d/

1.2. Create celery worker configuration file

vi /etc/default/celeryd

Content of this file should be:

# Names of nodes to start
CELERYD_NODES="worker1"

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/var/www/miarec/pyenv/bin/celery"

# App instance to use
CELERY_APP="miarecweb.celery_app"

# Where to chdir at start.
CELERYD_CHDIR="/var/www/miarec/pyenv"

# Extra command-line arguments to the worker
CELERYD_OPTS="--time-limit=300 --concurrency=8 --ini-file=/var/www/miarec/production.ini"

# %N will be replaced with the first part of the nodename.
CELERYD_LOG_FILE="/var/log/miarec/celery/%N.log"
CELERYD_PID_FILE="/var/run/celery/%N.pid"

# Create log/pid dirs, if they don't already exist
CELERY_CREATE_DIRS=1

CELERYD_USER="root"
CELERYD_GROUP="root"

1.3. Install this init.d script and configure it to start automatically during boot process

update-rc.d celeryd defaults

1.4. Start celery

service celeryd start

2. Celery scheduler daemon (celerybeat)

2.1. Create init.d startup script for celery scheduler

Download default init.d script from celery Github repository:

cd ~
wget https://raw.githubusercontent.com/celery/celery/3.1/extra/generic-init.d/celerybeat

Make it executable:

chmod +x celerybeat

Move to /etc/init.d/

mv celerybeat /etc/init.d/

2.2. Create celery scheduler configuration file

vi /etc/default/celerybeat

Content of this file should be:

# Absolute or relative path to the 'celery' command:
CELERY_BIN="/var/www/miarec/pyenv/bin/celery"

# App instance to use
CELERY_APP="miarecweb.celery_app"

# Where to chdir at start.
CELERYBEAT_CHDIR="/var/www/miarec/pyenv"

# Extra command-line arguments to the scheduler
CELERYBEAT_OPTS="-S miarecweb.jobs.scheduler.JobScheduler --ini-file /var/www/miarec/production.ini"

CELERYBEAT_LOG_FILE="/var/log/miarec/celery/beat.log"
CELERYBEAT_PID_FILE="/var/run/celery/beat.pid"

# Create log/pid dirs, if they don't already exist
CELERY_CREATE_DIRS=1

CELERYBEAT_USER="root"
CELERYBEAT_GROUP="root"

2.3. Install this init.d script and configure it to start automatically during boot process

update-rc.d celerybeat defaults

2.4. Start celery beat

service celerybeat start

Install MiaRec Recorder

1. Install required packages

sudo apt-get install libpcap

2. Download MiaRec installation files:

Contact us (sales@miarec.com) to receive URL to MiaRec installation files.

wget CONTACT_US_FOR_URL

Extract:

tar -xzvf miarec-*.tar.gz
cd miarec*

3. Install MiaRec recorder

Copy binary file to /usr/local/bin/

cp miarec /usr/local/bin/

Copy configuration files to /etc/miarec/

mkdir /etc/miarec
cp miarec.ini /etc/miarec/
cp -r sqlconfig /etc/miarec/

Create /var/lib/miarec directory. It will be used as current directory when running MiaRec process. MiaRec process reads SOAP wsdl file from current directory and stores some temporary files there.

mkdir /var/lib/miarec
cp WebServices.wsdl /var/lib/miarec/

Create log directories

mkdir /var/log/miarec

Create directory for recording files

mkdir -p /var/miarec/recordings

4. Create startup script (Upstart)

Create file /etc/init/miarec.conf

vi /etc/init/miarec.conf

Content of this file:

description "MiaRec call recorder"
author      "MiaRec, Inc. www.miarec.com"

env EXEC=/usr/local/bin/miarec
env PIDFILE=/var/run/miarec.pid
env CONFFILE=/etc/miarec/miarec.ini

start on started sshd
stop on runlevel [!2345]

console output

# Restart automatically proces in case of crash
respawn

# Stop respawn if it occured more than 10 times during 60 seconds period.
# This means serious problems
respawn limit 10 60

# Current working directory for MiaRec process
chdir /var/lib/miarec

# Enable core dumps for troubleshooting
limit core unlimited unlimited

instance miarec
exec $EXEC -c $CONFFILE --pid $PIDFILE

Reload Upstart configuration

initctl reload-configuration

Validate that miarec is in a list of processes:

initctl list | grep miarec

If you do not see there miarec then check errors in /var/log/messages

Start MiaRec process

initctl start miarec

5. Edit miarec.ini configuration file

vi /etc/miarec/miarec.ini

Change database connection settings (host, port, database, user, password). There are two places in INI files, where you need to edit database settings:

5.1. Module which loads configuration from database

#-----------------------------------------------------------------
#    SQLConfig
#-----------------------------------------------------------------
#  Loading configuration from SQL database
#-----------------------------------------------------------------
################################################################################
[SQLConfig]
################################################################################

#  Database Driver type.
#  Supported values: 
#    PostgreSQL
#-------------------------------------------------------------------------------
Driver=PostgreSQL
#-------------------------------------------------------------------------------


#  Host of database server
#-------------------------------------------------------------------------------
Host=127.0.0.1:5432
#-------------------------------------------------------------------------------


#  Database name
#-------------------------------------------------------------------------------
Database=miarecdb
#-------------------------------------------------------------------------------


#  Username and password for accessing database. Should have write permissions.
#-------------------------------------------------------------------------------
Username=miarec
Password=password
#-------------------------------------------------------------------------------

5.2. Module, which writes call detail records (CDRs) to database:

#-----------------------------------------------------------------
#  Configuration section for SQLCallsLog module. This module stores calls log into database
#  Supported call events:
#    start,connect,update,stop,stream_start,stream_stop
#-----------------------------------------------------------------
################################################################################
[SQLCallsLog]
################################################################################

#  Database Driver type.
#  Supported values: 
#    PostgreSQL
#-------------------------------------------------------------------------------
Driver=PostgreSQL
#-------------------------------------------------------------------------------


#  Host of database server
#-------------------------------------------------------------------------------
Host=127.0.0.1:5432
#-------------------------------------------------------------------------------


#  Database name
#-------------------------------------------------------------------------------
Database=miarecdb
#-------------------------------------------------------------------------------


#  Username and password for accessing database. Should have write permissions.
#-------------------------------------------------------------------------------
Username=miarec
Password=password
#-------------------------------------------------------------------------------

6. Restart MiaRec service

initctl stop miarec
initctl start miarec

Configure firewall

By default MiaRec uses the following ports, which should be added into firewall exclusion list.

Port Description
80 (tcp) MiaRec Web-portal (HTTP protocol)
6554 (tcp) Live monitoring signaling (RTSP protocol)
7000 - 7999 (udp) Live monitoring media (RTP protocol)
5070 (tcp) Cisco SIP trunk recording signaling (SIP protocol)
20000 - 21999 (udp) Cisco SIP trunk recording media (RTP protocol)
5080 (tcp) SIPREC recording signaling (SIP protocol)
22000 - 23999 (udp) SIPREC recording media (RTP protocol)

This document describes how to configure iptables.

Execute command iptables --line -vnL to see the current list of rule with line numbers. Example output:

[root@miarec ~]# iptables --line -vnL
Chain INPUT (policy ACCEPT 0 packets, 0 bytes)
num   pkts bytes target     prot opt in     out     source               destination         
1     3124 1264K ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           state RELATED,ESTABLISHED 
2        0     0 ACCEPT     icmp --  *      *       0.0.0.0/0            0.0.0.0/0           
3       11  3292 ACCEPT     all  --  lo     *       0.0.0.0/0            0.0.0.0/0           
4        0     0 ACCEPT     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           state NEW tcp dpt:22 
5       63  4881 REJECT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           reject-with icmp-host-prohibited 

Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
num   pkts bytes target     prot opt in     out     source               destination         
1        0     0 REJECT     all  --  *      *       0.0.0.0/0            0.0.0.0/0           reject-with icmp-host-prohibited 

Chain OUTPUT (policy ACCEPT 2937 packets, 1212K bytes)
num   pkts bytes target     prot opt in     out     source               destination         

From this output we need to get the line number of the generic REJECT rule. In example above it is at line #5. We will need to add our exclusion rules just above this line.

Web-portal rule (port 80 tcp)

iptables -I INPUT 5 -i eth0 -p tcp --dport 80 -m state --state NEW,ESTABLISHED -j ACCEPT

Live monitoring rules

iptables -I INPUT 5 -i eth0 -p tcp --dport 6554 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -I INPUT 5 -i eth0 -p udp --dport 7000:7999 -m state --state NEW,ESTABLISHED -j ACCEPT

Cisco SIP trunk recording interface rules

iptables -I INPUT 5 -i eth0 -p udp --dport 5070 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -I INPUT 5 -i eth0 -p tcp --dport 5070 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -I INPUT 5 -i eth0 -p udp --dport 20000:21999 -m state --state NEW,ESTABLISHED -j ACCEPT

SIPREC recording interface rules

iptables -I INPUT 5 -i eth0 -p udp --dport 5080 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -I INPUT 5 -i eth0 -p tcp --dport 5080 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -I INPUT 5 -i eth0 -p udp --dport 22000:23999 -m state --state NEW,ESTABLISHED -j ACCEPT

Save all rules into iptables configuration file

service iptables save

Restart iptables service

service iptables restart

Update on Linux manually

Update MiaRec Web portal

Use these instructions only if MiaRec has been installed manually. For Ansible-based deployment, use the update instructions from here.

1. Download latest MiaRec web-portal files

Fill out Download form to get access to latest version of MiaRec.

wget URL_TO_MIARECWEB_FILES

Extract this archive

tar -xzvf miarecweb-*.tar.gz

2. Rename old MiaRec Web application files

It is recommended to rename the existing MiaRec web portal folder instead of removing it. This will allow you to restore old version if necessary.

mv /var/www/miarec/app /var/www/miarec/app-`date +"%m-%d-%Y"`

3. Install new version of MiaRec Web application

Move the extracted new files to /var/www/miarec/app

mv miarecweb-*/ /var/www/miarec/app

Clear cache (pre-compiled templates):

rm -rf /var/www/miarec/cache/*

4 Upgrade MiaRec database layout

Activate python virtual environment

source /var/www/miarec/pyenv/bin/activate

Make sure the development packages of libxml2 and libxslt are installed:

yum install libxml2-devel libxslt-devel

Install/update miarecweb application:

PATH=$PATH:/usr/pgsql-9.4/bin/
pip install -e /var/www/miarec/app

Run database migration script (alembic):

alembic -c /var/www/miarec/production.ini upgrade head

Tip: if execution of the database migration script takes more than 5 minutes, then probably some database tables are locked by other processes and the migration script waits till lock is released. To fix that issue, you need to stop other services, which are using MiaRec database.

Open another SSH window and execute the following commands:

service httpd stop

service celeryd stop

service celerybeat stop

5. Restart Apache and Celery services

service httpd restart

service celeryd restart

service celerybeat stop
service celerybeat start

Update MiaRec recorder files

Use these instructions only if MiaRec has been installed manually. For Ansible-based deployment, use the update instructions from here.

1. Download latest MiaRec recorder files

Fill out Download form to get access to latest version of MiaRec.

wget URL_TO_MIARECWEB_FILES

Extract this archive

tar -xzvf miarec-*.tar.gz

2. Rename old MiaRec recorder files

It is recommended to rename the existing MiaRec files instead of removing them. This will allow you to restore old version if necessary.

mv /etc/miarec/sqlconfig /etc/miarec/sqlconfig-`date +"%m-%d-%Y"`
mv /usr/local/bin/miarec /usr/local/bin/miarec-`date +"%m-%d-%Y"`
mv /var/lib/miarec/WebServices.wsdl /var/lib/miarec/WebServices.wsdl-`date +"%m-%d-%Y"`

You can safely remove these old files once upgrade is completed and functionality is tested.

3. Install new version of MiaRec files

Navigate to the extracted directory miarec-*

cd miarec-*

Copy new configuration files and MiaRec recorder binary to the corresponding locations:

cp -r sqlconfig /etc/miarec/
cp WebServices.wsdl /var/lib/miarec/
cp miarec /usr/local/bin/

4. Restart MiaRec recorder service

When using Upstart (Centos 6):

initctl stop miarec
initctl start miarec

When using init.d or SystemD (Centos 7):

service miarec restart

Post-installation tasks

Enable HTTPS for MiaRec Web portal

Setup free SSL certificate for MiaRec using Let's Encrypt (Ubuntu 14.04)

This tutorial describes how to setup a free TLS/SSL certificate from Let's Encrypt on MiaRec server based on Ubuntu 14.04 server running Apache as a web server.

SSL certificates are used within web servers to encrypt the traffic between the server and client, providing extra security for users accessing your application. Let’s Encrypt provides an easy way to obtain and install trusted certificates for free.

What is Let's Encrypt? Let’s Encrypt is a free, automated, and open certificate authority managed by the non-profit Internet Security Research Group (ISRG). Major sponsors are the Electronic Frontier Foundation (EFF), the Mozilla Foundation, OVH, Akamai, Google and Cisco Systems. See this page for more on ISRG sponsors.

Step 1 - Install Certbot on Ubuntu 14.04

What is Certbot? Certbot is an easy-to-use automatic client that fetches and deploys SSL/TLS certificates for webserver. Certbot was developed by EFF and others as a client for Let’s Encrypt. This client runs on Unix-based operating systems.

To install Certbot, you must first enable the PPA repository maintained by the Certbot team:

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot

Afterwards, update the package list to pick up the new repository's package information:

sudo apt-get update

And finally, install Certbot from the new repository with apt-get:

sudo apt-get install python-certbot-apache

Step 2 - Configure Apache to serve .well-known/acme-challenge directory

The Apache web server should be configured properly to allow serving of the files inside the /.well-known/acme-challenge directory. In this tutorial, we will use directory /var/www/html/.well-known as a location for the Certbot's temporary files.

What is a purpose of .well-known directory?

To obtain SSL certificate, the Certbot client creates a temporary file in ${webroot-path}/.well-known/acme-challenge directory. Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running certbot. An example request made to your web server would look like:

66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

Create file /etc/apache2/sites-available/letsencrypt-well-known.conf:

vim /etc/apache2/sites-available/letsencrypt-well-known.conf

Copy-paste the following content to that file:

For Apache 2.4:

<IfModule mod_proxy.c>
  ProxyPass /.well-known !
</IfModule>

Alias /.well-known/ "/var/www/html/.well-known/"

<Directory "/var/www/html/.well-known">
  Options None
  AllowOverride None
  Require all granted
</Directory>

<Location /.well-known/acme-challenge>
  Options None
  Require all granted
</Location>

Enable this configuration file:

sudo a2ensite letsencrypt-well-known.conf

Reload Apache:

sudo service apache2 reload

Step 4 - Obtain SSL certificates from Let's Encrypt server

Run the following command to obtain the certificate:

sudo certbot certonly --webroot -w /var/www/html/ -d miarec.example.com

Important! Replace miarec.example.com with your MiaRec server DNS name.

If everything goes well, then you should see the following message:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/miarec.example.com/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/miarec.example.com/privkey.pem
   Your cert will expire on 2017-12-26. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"

Note the location of the generated certificate files. In our example, it is /etc/letsencrypt/live/miarec.example.com/.

Step 4 - Install mod_ssl module for Apache

The mod_ssl module is available in apache2-common package. Execute the following command at a terminal prompt to enable the mod_ssl module:

sudo a2enmod ssl

Enable HTTPS for Apache:

sudo a2ensite default-ssl

Step 5 - Configure Apache to use new SSL certificates

Edit file /etc/apache2/sites-available/default-ssl.conf

vim /etc/apache2/sites-available/default-ssl.conf

Modify the parameters SSLCertificateFile, SSLCertificateKeyFile and SSLCertificateChainFile. They should point to the public, private and CA certificate files correspondingly.

Example of configuration (replace miarec.example.com with your domain):

#   Server Public Key:
SSLCertificateFile /etc/letsencrypt/live/miarec.example.com/cert.pem

#   Server Private Key:
SSLCertificateKeyFile /etc/letsencrypt/live/miarec.example.com/privkey.pem

#   Server Certificate Chain:
SSLCertificateChainFile /etc/letsencrypt/live/miarec.example.com/chain.pem

Enable this configuration file and load Apache:

sudo a2ensite default-ssl.conf
sudo service apache2 reload

Step 6 - Open port 443 on firewall

If you are using iptables on this machine, then execute the following commands:

iptables -I INPUT 5 -i eth0 -p tcp --dport 443 -m state --state NEW,ESTABLISHED -j ACCEPT

Save all rules into iptables configuration file:

service iptables save

Restart iptables service:

service iptables restart

If you are using ufw firewall, then execute the following commands:

sudo ufw allow https

Step 7 - Force HTTPS for all traffic except internal call event notification (recommended)

Create file /etc/apache2/sites-available/miarec-ssl.conf:

vim /etc/apache2/sites-available/miarec-ssl.conf

Copy/paste the following content into this file:

<VirtualHost *:80>
    RewriteEngine on
    RewriteCond %{HTTP_HOST}%{REQUEST_URI} !^127.0.0.1/notify
    RewriteRule ^/(.*) https://%{HTTP_HOST}/$1 [NC,R=301,L]
</VirtualHost>

Enable this configuration file and load Apache:

sudo a2ensite miarec-ssl.conf
sudo service apache2 reload

What is "127.0.0.1/notify" in the rewrite rule? MiaRec uses internally the HTTP protocol for sending call event notifications from recorder engine to a web portal. The above rewrite rule will force HTTPS for all web traffic except internal communication between recorder and web portal.

Step 9 - Configure cron to automatically renew the certificate.

Let’s Encrypt CA issues short-lived certificates (90 days). This tutorial shows how to automatically renew the certificates using cron.

Edit file /etc/crontab:

vi /etc/crontab

Insert the following line to the end of file:

27 5,21 * * * certbot renew --quiet --no-self-upgrade --post-hook "apachectl graceful"

The example above will run the renew sub-command at 05:27 and 21:27 daily. You can change time to other values. If the certificates are updated, then apache is gracefully restarted.

Setup free SSL certificate for MiaRec using Let's Encrypt (Centos 6/7)

This tutorial describes how to setup a free TLS/SSL certificate from Let's Encrypt on MiaRec server based on Centos 7 server running Apache as a web server.

SSL certificates are used within web servers to encrypt the traffic between the server and client, providing extra security for users accessing your application. Let’s Encrypt provides an easy way to obtain and install trusted certificates for free.

What is Let's Encrypt? Let’s Encrypt is a free, automated, and open certificate authority managed by the non-profit Internet Security Research Group (ISRG). Major sponsors are the Electronic Frontier Foundation (EFF), the Mozilla Foundation, OVH, Akamai, Google and Cisco Systems. See this page for more on ISRG sponsors.

Step 1 - Enable EPEL repository in Centos 6/7

To use Certbot (described below), you must first enable the EPEL (Extra Packages for Enterprise Linux) repository and enable EPEL optional channel.

yum install epel-release

What is EPEL? Extra Packages for Enterprise Linux (or EPEL) is a Fedora Special Interest Group that creates, maintains, and manages a high quality set of additional packages for Enterprise Linux, including, but not limited to, Red Hat Enterprise Linux (RHEL), CentOS and Scientific Linux (SL), Oracle Linux (OL).

Step 2 - Install Certbot

Install Certbot by running:

Centos 6:

cd /root
wget https://dl.eff.org/certbot-auto
chmod a+x certbot-aut

Centos 7:

yum install python-certbot-apache

What is Certbot? Certbot is an easy-to-use automatic client that fetches and deploys SSL/TLS certificates for webserver. Certbot was developed by EFF and others as a client for Let’s Encrypt. This client runs on Unix-based operating systems.

Step 3 - Configure Apache to serve .well-known/acme-challenge directory

The Apache web server should be configured properly to allow serving of the files inside the /.well-known/acme-challenge directory. In this tutorial, we will use directory /var/www/html/.well-known as a location for the Certbot's temporary files.

What is a purpose of .well-known directory?

To obtain SSL certificate, the Certbot client creates a temporary file in ${webroot-path}/.well-known/acme-challenge directory. Then the Let’s Encrypt validation server makes HTTP requests to validate that the DNS for each requested domain resolves to the server running certbot. An example request made to your web server would look like:

66.133.109.36 - - [05/Jan/2016:20:11:24 -0500] "GET /.well-known/acme-challenge/HGr8U1IeTW4kY_Z6UIyaakzOkyQgPr_7ArlLgtZE8SX HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

Create file /etc/httpd/conf.d/letsencrypt-well-known.conf:

vi /etc/httpd/conf.d/letsencrypt-well-known.conf

Copy-paste the following content to that file:

For Apache 2.4 (Centos 7):

<IfModule mod_proxy.c>
  ProxyPass /.well-known !
</IfModule>

Alias /.well-known/ "/var/www/html/.well-known/"

<Directory "/var/www/html/.well-known">
  Options None
  AllowOverride None
  Require all granted
</Directory>

<Location /.well-known/acme-challenge>
  Options None
  Require all granted
</Location>

For Apache 2.2 (Centos 6):

<IfModule mod_proxy.c>
  ProxyPass /.well-known !
</IfModule>

Alias /.well-known/ "/var/www/html/.well-known/"

<Directory "/var/www/html/.well-known">
  Options None
  Order allow,deny
  Allow from all
</Directory>

<Location /.well-known/acme-challenge>
  Options None
  Order allow,deny
  Allow from all
</Location>

Reload Apache:

service httpd reload

Step 4 - Obtain SSL certificates from Let's Encrypt server

Run the following command to obtain the certificate:

Centos 6:

certbot certonly --webroot -w /var/www/html/ -d miarec.example.com

Centos 7:

./certbot-auto certonly --webroot -w /var/www/html/ -d miarec.example.com

Important! Replace miarec.example.com with your MiaRec server DNS name.

If everything goes well, then you should see the following message:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/miarec.example.com/fullchain.pem. Your cert will
   expire on 2017-08-06. To obtain a new or tweaked version of this
   certificate in the future, simply run certbot again. To
   non-interactively renew *all* of your certificates, run "certbot
   renew"

Note the location of the generated certificate files. In our example, it is /etc/letsencrypt/live/miarec.example.com/.

Step 5 - Install mod_ssl module for Apache

yum install mod_ssl

The module will automatically be enabled during installation, and Apache will be able to start using an SSL certificate after it is restarted. You don't need to take any additional steps for mod_ssl to be ready for use.

Step 6 - Configure Apache to use new SSL certificates

Edit file /etc/httpd/conf.d/ssl.conf

vi /etc/httpd/conf.d/ssl.conf

Modify the parameters SSLCertificateFile, SSLCertificateKeyFile and SSLCertificateChainFile. They should point to the public, private and CA certificate files correspondingly.

Example of configuration (replace miarec.example.com with your domain):

#   Server Public Key:
SSLCertificateFile /etc/letsencrypt/live/miarec.example.com/cert.pem

#   Server Private Key:
SSLCertificateKeyFile /etc/letsencrypt/live/miarec.example.com/privkey.pem

#   Server Certificate Chain:
SSLCertificateChainFile /etc/letsencrypt/live/miarec.example.com/chain.pem

Step 7 - Open port 443 on firewall

Add exclusion rule to firewall:

iptables -I INPUT 5 -i eth0 -p tcp --dport 443 -m state --state NEW,ESTABLISHED -j ACCEPT

Save all rules into iptables configuration file:

service iptables save

Restart iptables service:

service iptables restart

Step 8 - Force HTTPS for all traffic except internal call event notification (recommended)

Create file /etc/httpd/conf.d/miarec-ssl.conf:

vi /etc/httpd/conf.d/miarec-ssl.conf

Copy/paste the following content into this file:

NameVirtualHost *:80
<VirtualHost *:80>
    RewriteEngine on
    RewriteCond %{HTTP_HOST}%{REQUEST_URI} !^127.0.0.1/notify
    RewriteRule ^/(.*) https://%{HTTP_HOST}/$1 [NC,R=301,L]
</VirtualHost>

Reload Apache:

service httpd reload

What is "127.0.0.1/notify" in the rewrite rule? MiaRec uses internally the HTTP protocol for sending call event notifications from recorder engine to a web portal. The above rewrite rule will force HTTPS for all web traffic except internal communication between recorder and web portal.

Step 9 - Configure cron to automatically renew the certificate.

Let’s Encrypt CA issues short-lived certificates (90 days). This tutorial shows how to automatically renew the certificates using cron.

Edit file /etc/crontab:

vi /etc/crontab

Insert the following line to the end of file:

Centos 6:

27 5,21 * * * /root/certbot-auto renew --quiet --no-self-upgrade --post-hook "apachectl graceful"

Centos 7:

27 5,21 * * * certbot renew --quiet --no-self-upgrade --post-hook "apachectl graceful"

The example above will run the renew sub-command at 05:27 and 21:27 daily. You can change time to other values. If the certificates are updated, then apache is gracefully restarted.

Reload crond service:

/etc/init.d/crond reload

Setup SSL certificate for MiaRec Web portal on Centos

In order to enable HTTPS (SSL) in MiaRec Web server, it is necessary to install SSL certificate. The certificate should be issued from a trusted Certificate Authority (like Verisign/Symantec, Comodo, GlobalSign, Digicert, GoDaddy etc).

The certificate is issued per domain name and can be used only with particular name. For example, if you install MiaRec on server and access it with address https://rec.my-company.com, then the SSL certificate should be issued to “rec.my-company.com” domain name.

Alternatively, the certificate can be self-signed. This means that instead of signing the certificate by Trusted Authority, you will sign it by your own certificate. In this case you will see in browser warning message that certificate is not trusted (means that it is not signed by trusted Certificate Authority), although the connection between client’s web-browser and MiaRec server will be secure and encrypted:

You can generate the self-signed certificate using the following command line:

openssl req -new -newkey rsa:2048 -days 3650 -nodes -x509 -keyout server.key -out server.crt

This command will generate key/certificate pair and then sign it.

Install mod_ssl module for Apache

yum install mod_ssl

The module will automatically be enabled during installation, and Apache will be able to start using an SSL certificate after it is restarted. You don't need to take any additional steps for mod_ssl to be ready for use.

Install SSL private key and certificate

Copy your SSL private key to directory:

/etc/pki/tls/private/

Copy your SSL certificate to directory:

/etc/pki/tls/certs/

In some case you may need to copy also intermediary certificate of the company, which signed your certificate. Check their official instructions for Apache server.

Edit Apache configuration file (ssl.conf)

Edit file /etc/httpd/conf.d/ssl.conf and make sure that:

  • SSLCertificateFile points to your certificate
  • SSLCertificateKeyFile points to your private certificate
  • SSLCertificateChainFile points to your certificate authority intermediary certificate (check your authority instructions)
#   Server Certificate:
SSLCertificateFile /etc/pki/tls/certs/miarec.example.com.crt

#   Server Private Key:
SSLCertificateKeyFile /etc/pki/tls/private/miarec.example.com.key

#   Server Certificate Chain:
SSLCertificateChainFile /etc/pki/tls/certs/CA.crt

Open port 443 on firewall

Add exclusion rule to firewall:

iptables -I INPUT 5 -i eth0 -p tcp --dport 443 -m state --state NEW,ESTABLISHED -j ACCEPT

Save all rules into iptables configuration file:

service iptables save

Restart iptables service:

service iptables restart

[Optional] Force HTTPS for all traffic except internal call events

Edit file /etc/httpd/conf.d/miarec.conf

You need to add the following lines to the end of this file:

NameVirtualHost *:80
<VirtualHost *:80>
    RewriteEngine on
    RewriteCond %{HTTP_HOST}%{REQUEST_URI} !^127.0.0.1/notify
    RewriteRule ^/(.*) https://%{HTTP_HOST}/$1 [NC,R=301,L]
</VirtualHost>

MiaRec uses internally HTTP protocol for sending call event notifications from recorder engine to a web portal. The above rewrite rule will force HTTPS for all web traffic except internal communication between recorder and web portal.

Restart Apache

service httpd restart

Phone system integration

Avaya call recording setup

Avaya TSAPI DMCC recording

1. Introduction

This article describes how to configure the MiaRec Call Recording System with the Avaya Application Enablement Services and Avaya Communication Manager to record incoming and outgoing phone calls using TSAPI and DMCC services.

MiaRec uses TSAPI interface from Avaya Aura Application Enablement Services (AES) to monitor skill groups and agent stations on Avaya Aura Communication Manager, and Device, Media, and Call Control (DMCC) interfaces to capture media associated with the monitored agents for call recording with the Multiple Registration method.

Avaya DMCC-based recording

Requirements:

  • Avaya Communication Manager v6.3.2 or higher
  • Avaya Application Enablement Services (AES) Server v6.3.1 or higher
  • TSAPI Basic License per each recorded extension and each monitored ACD Split / Hunt Group
  • DMCC Basic License for each recorded extension

2. Configure Avaya Communication Manager

This section presents configuration steps for the Avaya Communication Manager. It is assumed that an appropriate license file and authentication file have been installed on the server, and that login and password credentials are available.

The configuration and verification operations illustrated in this section were all performed using the Communication Manager System Administration Terminal (SAT).

The procedures include the following areas:

  • Verify license
  • Verify the status CTI link for TSAPI service
  • Administer system parameters features
  • Administer agent stations

2.1. Verify license

Log into the System Access Terminal (SAT) to verify that the Communication Manager license has proper permissions for features required for call recording. Use the "display system-parameters customer-options" command to verify that the Computer Telephony Adjunct Links customer option is set to "y" on Page 4. If this option is not set to "y", then contact Avaya sales team of business partner for a proper license file.

display system-parameters customer-options                      Page   4 of  12
                                OPTIONAL FEATURES

    Abbreviated Dialing Enhanced List? y           Audible Message Waiting? y
        Access Security Gateway (ASG)? y               Authorization Codes? y
        Analog Trunk Incoming Call ID? y                        CAS Branch? n
 A/D Grp/Sys List Dialing Start at 01? y                          CAS Main? n
Answer Supervision by Call Classifier? y                 Change COR by FAC? n
                                  ARS? y  Computer Telephony Adjunct Links? y
                 ARS/AAR Partitioning? y   Cvg Of Calls Redirected Off-net? y
          ARS/AAR Dialing without FAC? n                       DCS (Basic)? y
          ASAI Link Core Capabilities? y                 DCS Call Coverage? y
          ASAI Link Plus Capabilities? y                DCS with Rerouting? y
       Async. Transfer Mode (ATM) PNC? n
  Async. Transfer Mode (ATM) Trunking? n    Digital Loss Plan Modification? y
              ATM WAN Spare Processor? n                           DS1 MSP? y
                                 ATMS? y             DS1 Echo Cancellation? y
                  Attendant Vectoring? y

2.2. Verify the status of CTI link for TSAPI service

Log into the System Access Terminal (SAT) to enter the "status aesvcs cti-link" command. The link status should show no for maintenance busy (Mnt Busy), the Service State should indicate established and Version should be 6 or higher.

status aesvcs cti-link

                          AE SERVICES CTI LINK STATUS

CTI   Version  Mnt   AE Services      Service       Msgs     Msgs
Link           Busy  Server           State         Sent     Rcvd

1     7        no    aes              established   15       15

If the CTI link is not established, then follow instructions in chapter Administering Communication Manager for AE Services in document Application Enablement Services Administration and Maintenance Guide available at http://support.avaya.com

2.3. Administer agent stations

Use the "change station xxxxx" command, where xxxxx is the phone's extension, and change IP SoftPhone to "y", to allow a virtual IP softphone (DMCC) to be registered against the station. The MiaRec application will use the Multiple Registration feature of Communication Manager to register the DMCC-based recording device against the station.

change station 3001                                             Page   1 of   5
                                     STATION

Extension: 3001                          Lock Messages? n               BCC: 0
     Type: 9608                          Security Code: *                TN: 1
     Port: S00003                      Coverage Path 1:                 COR: 1
     Name: User Two                    Coverage Path 2:                 COS: 1
                                       Hunt-to Station:               Tests? y
STATION OPTIONS
                                           Time of Day Lock Table:
              Loss Group: 19         Personalized Ringing Pattern: 1
                                                 Message Lamp Ext: 3001
            Speakerphone: 2-way               Mute Button Enabled? y
        Display Language: english                  Button Modules: 0
 Survivable GK Node Name:
          Survivable COR: internal              Media Complex Ext:
   Survivable Trunk Dest? y                          IP SoftPhone? y

                                               IP Video Softphone? n
                              Short/Prefixed Registration Allowed: default

                                              Customizable Labels? y

2.4. Administer System Parameters Features

Enter the "change system-parameters features" command. Navigate to Page 5, and verify that Create Universal Call ID (UCID) has value “y”. If not, then set it to "y" and set UCID Network Node ID to an unassigned node ID.

change system-parameters features                               Page   5 of  17
                        FEATURE-RELATED SYSTEM PARAMETERS

SYSTEM PRINTER PARAMETERS
  Endpoint:               Lines Per Page: 60

SYSTEM-WIDE PARAMETERS
                                     Switch Name:
            Emergency Extension Forwarding (min): 10
          Enable Inter-Gateway Alternate Routing? n
Enable Dial Plan Transparency in Survivable Mode? n
                              COR to Use for DPT: station

MALICIOUS CALL TRACE PARAMETERS
               Apply MCT Warning Tone? n   MCT Voice Recorder Trunk Group:

SEND ALL CALLS OPTIONS
     Send All Calls Applies to: station    Auto Inspect on Send All Calls? n

UNIVERSAL CALL ID
     Create Universal Call ID (UCID)? y    UCID Network Node ID: 9999
     Copy UCID for Station Conference/Transfer? n

Navigate to Page 13, and set Send UCID to ASAI to "y". This parameter allows for the universal call ID to be sent to MiaRec call recording application.

change system-parameters features                               Page  13 of  17
                        FEATURE-RELATED SYSTEM PARAMETERS

 CALL CENTER MISCELLANEOUS
                         Clear Callr-info: next-call
        Allow Ringer-off with Auto-Answer? n

    Reporting for PC Non-Predictive Calls? n


  ASAI
            Copy ASAI UUI During Conference/Transfer? n
        Call Classification After Answer Supervision? n
                                   Send UCID to ASAI? y

2.5. Configure Service Observe

For the purposes of Multi Registration, service observe must be enabled for the COR to which the Target Stations will be assigned. Using the command "change cor 1" set both Can be Service Observed? and Can be a Service Observer? to "y".

change cor 1                                                    Page   1 of  23
                              CLASS OF RESTRICTION

               COR Number: 1
          COR Description:

                      FRL: 0                                APLT? y
  Can Be Service Observed? y           Calling Party Restriction: outward
Can Be A Service Observer? y            Called Party Restriction: none
        Time of Day Chart: 1       Forced Entry of Account Codes? n
         Priority Queuing? n                Direct Agent Calling? n
     Restriction Override: none       Facility Access Trunk Test? n
     Restricted Call List? n                 Can Change Coverage? n

            Access to MCT? y            Fully Restricted Service? n
Group II Category For MFC: 7            Hear VDN of Origin Annc.? n
         Send ANI for MFE? n             Add/Remove Agent Skills? n
            MF ANI Prefix:              Automatic Charge Display? n
Hear System Music on Hold? y   PASTE (Display PBX Data on Phone)? n
                        Can Be Picked Up By Directed Call Pickup? n
                                    Can Use Directed Call Pickup? n
                                    Group Controlled Restriction: inactive

3. Configure Avaya Application Enablement Services

This section provides the procedures for configuring Avaya Application Enablement Services. The procedures include the following areas:

  • Verify TSAPI and DMCC services licensing
  • Administer TSAPI link
  • Obtain Tlink name
  • Administer CTI user for MiaRec

3.1. Verify TSAPI and DMCC services licensing

Prior to any administration, verify that the TSAPI and DMCC services have been licensed properly. Open the AES OAM web interface by browsing to "https://ip-address-or-dns", where "ip-address-or-dns" is the IP address or DNS alias of the Appliation Enabledment Services server, and log in using the appropriate credentials (not shown).

Select Licensing -> WebLM Server Access in the left pane, to display the Web License Manager pop-up screen (not shown), and log in using the appropriate credentials.

Avaya AES WebLM Server Access

If the licenses are managed centrally on the System Manager, then select Services -> Licenses in the System Manager home screen. Otherwise, the Web License Manager screen is shown immediately.

Avaya System Manager Licenses

In the Web License Manager screen, select Application_Enablement under Licenses Products to display license capacity and current usage.

Verify that there are sufficient licenses for TSAPI Simultaneous Users and Device Media and Call Control, as shown below. Note that the TSAPI license is used for device monitoring, and the DMCC license is used for media recording.

MiaRec requires TSAPI Basic license for each monitored IP Phone, softphone and ACD Split (Hunt Group) and DMCC Basic license for each recorded IP phone and softphone.

If the TSAPI or DMCC service is not licensed, contact the Avaya sales team or business partner for a proper license file.

Avaya AES TSAPI licenses

3.2. Administer TSAPI link

To administer a TSAPI link, select AE Services -> TSAPI -> TSAPI Links from the left pan of the Management Console. The TSAPI Links screen is displayed, as shown below. If the TSAPI Link is not configured yet, then click Add Link to create one.

Avaya AES TSAPI Links

The Add TSAPI Links screen is displayed next.

The Link field is only local to the Application Enablement Services server, and may be set to any available number. For Switch Connection, select the relevant switch connection from the drob-down list. In this case, the existing switch connection "cm2" is selected. For Switch CTI Link Number, select the CTI Link number from Section 2.2. Make sure that ASAI Link Version is 6 or higher. Retain the default values in the remaining fields.

Avaya AES TSAPI Add Link

3.3. Verify Switch Connection PE/CLAN IPs

Select Communications Manager Interface -> Switch Connections from the left pane. The Switch Connections screen shows a listing of the existing switch connections.

Locate the connection name associated with the relevant Communication Manager, in this case "cm2", and click Edit PE/CLAN IPs button for the corresponding connection.

Avaya AES Switch Connections

In the Edit Processor Ethernet IP screen, verify that ip-address is configured for Communication Manager and Status is shown "In Use". If the ip-address is not configured, then use Add/Edit Name or IP button to configure it.

Avaya AES Switch Connections

Navigate back to the Switch Connections screen and verify that the Number of Active Connections is valid.

Avaya AES Switch Connections

3.4. Verify Switch Connection H.323 Gatekeeper

Select Communications Manager Interface -> Switch Connections from the left pane. The Switch Connections screen shows a listing of the existing switch connections.

Locate the connection name associated with the relevant Communication Manager, in this case "cm2", and click Edit H.323 Gatekeeper button for the corresponding connection.

Avaya AES Switch Connections

In the Edit H.323 Gatekeeper screen, verify that ip-address is configured for Communication Manager. If the ip-address is not configured yet, then use Add Name or IP button to configure it.

Avaya AES Switch Connections

3.5. Obtain Tlink name

Select Security -> Security Database -> Tlinks from the left pane. The Tlinks screen shows a listing of the Tlink names. Locate the Tlink Name associated with the switch connection to Avaya Communication Manager. A new TLink name is automatically generated for the TSAPI service. Locate the TLink name associated with the relevant switch connection, which would use the name of the switch connection as part of the Tlink name. Make a note of the associated Tlink name, to be used later for configuring the MiaRec server.

In this case, the associated Tlink name is "AVAYA#CM2#CSTA#AES"'. Note the use of the switch connection "CM2" from Section 3.2 as part of the Tlink name.

If Tlink doesn't exist, then follow instructions in AE Services Administration in document Application Enablement Services Administration and Maintenance Guide available at http://support.avaya.com

Avaya AES Tlinks

3.6. Administer CTI user for MiaRec

Select User Management -> Add User from the left pane, to display the Add User screen in the right pane.

Enter desired values for User Id, Common Name, Surname, User Password, and Confirm Password. Retain the default value of “None” for Avaya Role, and select “Yes” from the CT User drop-down list. Click on Apply at the bottom of the screen (not shown below). Make a note of the User Id and Password, to be used later for configuring the MiaRec server.

Avaya AES Add User

Next, you need to change the security level for the CTI User as it needs to have unrestricted access privileges.

Select Administration -> Security Database -> CTI Users -> List All Users from the left pane. Choose the previously created CTI user, and click Edit.

Avaya AES Edit CTI User

The Edit CTI User screen appears. Tick the Unrestricted Access box and Apply Changes at the bottom of the screen.

Avaya AES Edit CTI User

3.7. Configure DMCC port

On the AES Management Console navigate to Networking -> Ports to set the DMCC server port. Enable either Unencrypted Port or "Encrypted Port** or both as shown in the screen below. Note the port values to use in the following steps for MiaRec server configuration. Click Apply Changes button (not shown) at the bottom of the screen to complete the process.

Avaya AES DMCC ports

3.8. Enable Security Database

Select Security -> Security Database -> Control from the left pane, to display the SDB Control for DMCC and TSAPI screen in the right pane. Check Enable SDB for DMCC Service and Enable SDB TSAPI Service, JTAPI and Telephony Service, and click Apply Changes.

Avaya AES Enable SDB

3.8. Restart TSAPI and DMCC services

Select Maintenance -> Service Controller from the left pane, to display the Service Controller screen in the right pane. Check DMCC Service and TSAPI Service, and click Restart Service.

Avaya AES Restart Services

4. Configure MiaRec Call Recording System

This section presents configuration steps for MiaRec call recording system. It is assumed that MiaRec is already installed on the server. The procedures include the following areas:

  • Install AES TSAPI Client
  • Administer MiaRec TSAPI link to AES
  • Administer MiaRec DMCC link to AES

4.1. Install AES TSAPI Client

Download Application Enablement Services TSAPI Client from http://support.avaya.com

Install it on MiaRec server. During installation enter the IP address of the Avaya AES server in the Host Name or IP Address field, retaining the default port of 450 (see below screenshot). Click on Add to List and then Next to finish installation.

Avaya AES TSAPI Client install

4.2. Administer MiaRec DMCC settings

Navigate in the MiaRec web interface to Administration -> System -> Recording Interfaces and click Configure link for Avaya DMCC interface.

MiaRec DMCC settings

In the Configure Recording Interface (Avaya DMCC) screen, configure the following settings:

  • Option Enable should be checked
  • Option AES server should point to HOST:PORT of AES server, where the HOST is an ip-address or DNS name of the Application Enablement Services server and the PORT is DMCC port obtained in the Section 3.7. Configure DMCC port
  • Option Use SSL should be checked when Encrypted DMCC port is used for connection to AES server
  • Option DMCC login and "DMCC password** should be set to the credentials of CTI user created in Section 3.6. Administer CTI user for MiaRec.
  • Option SwitchName should be set the hostname of Communication Manager used to register DMCC virtual softphone against to
  • Retain default settings for other values

MiaRec DMCC settings

4.3. Administer MiaRec TSAPI settings

Navigate in the MiaRec web interface to Administration -> System -> Recording Interfaces and click Configure link for Avaya TSAPI interface.

MiaRec DMCC settings

In the Configure Recording Interface (Avaya TSAPI) screen, configure the following settings:

  • Option Enable should be checked
  • Option TSAPI Link should point to the obtained TLink in the Section 3.5. Obtain Tlink name.
  • Option TSAPI login and "TSAPI password** should be set to the credentials of CTI user created in Section 3.6. Administer CTI user for MiaRec.
  • Option Media Source should be set to DMCC
  • Option Monitored phones should list all recorded extensions, comma-separated. A range of extensions is supported, like 3000-3100, 5001, 5002
  • Option Monitored ACD Splits should list all ACDs, which the recorded users may login to. MiaRec monitors ACDs for login/logout events. A range value is supported, like 4900-49100, 55000, 56000
  • Option Ignore dialing phase could be enabled to avoid recording of initial dialing phase of the outgoing call scenario
  • Retain default settings for other values

MiaRec DMCC settings

5. Verification and Troubleshooting

This section provides the tests that can be performed to verify proper configuration of Avaya Communication Manager, Avaya Application Enablement Services and MiaRec call recording application.

5.1. Verify Avaya Communication Manager

On Avaya Communication Manager, verify the status of the administered CTI links by using the "status aesvcs cti-link" command. The link status should show "no" for maintenance busy (Mnt Busy) and the Service State should indicate "established".

status aesvcs cti-link

                          AE SERVICES CTI LINK STATUS

CTI   Version  Mnt   AE Services      Service       Msgs     Msgs
Link           Busy  Server           State         Sent     Rcvd

1     4        no    aes-server1      established   15       15

The "status aesvcs interface" command should indicate the interface is listening.

status aesvcs interface

                          AE SERVICES INTERFACE STATUS

Local Node        Enabled?  Number of     Status
                            Connections

procr             yes       1             listening

The "status aesvcs link" command will indicate the number of messages sent from, and received at the CLAN interface (or procr), to and from Avaya Application Enablement Services, including maintenance traffic.

status aesvcs link

                            AE SERVICES LINK STATUS

Srvr/  AE Services     Remote IP        Remote  Local Node      Msgs    Msgs
Link   Server                           Port                    Sent    Rcvd

01/01  aes-server1     10.0.0.25        43909   procr           224     209

Once the MiaRec call recording application is running, the "list monitored-station" command will show each station, which is monitored by MiaRec via TSAPI interface.

list monitored-station

                            MONITORED STATION

  Station     Association 1    Association 2    Association 3    Association 4
  Ext         CTI Link  CRV    CTI Link  CRV    CTI Link  CRV    CTI Link  CRV
  -------     -------------    -------------    -------------    -------------
32129          1          10
32130          1           9
32131          1          22
32132          1           7

5.2. Verify Avaya Application Enablement Services

On Application Enablement Services, verify the status of the switch connection by selecting Status -> Status and Control -> Switch Conn Summary from the left pane. Verify that the Conn State is “Talking” for the switch connection associated with Avaya Communication Manager, and that the Associations column reflects the total number of monitored skill groups and agent stations as configured previously.

Avaya AES Switch Connection Summary

Verify the status of the TSAPI link by selecting Status -> Status and Control -> TSAPI Service Summary from the left pane. Verify the Conn Status is “Talking” as shown below.

Avaya AES TSAPI Link Details

Verify the status of the CTI User by selecting Status -> Status and Control -> TSAPI Service Summary from the left pane. Click the User Status button (not shown below). The CTI User Status screen is displayed. Verify that an open session exists for the CTI user created for MiaRec as shown below. This verification step assumes that MiaRec application is configured properly and running.

Avaya AES CTI User Status

Verify the status of the DMCC link by selecting Status -> Status and Control -> DMCC Service Summary from the left pane. The DMCC Service Summary - Session Summary screen is displayed.

Verify the User column shows an active session with the MiaRec user name and that the # of Associated Devices column reflects the total number of configured DMCC devices.

Avaya AES CTI User Status

Click Device Summary link in the Status -> Status and Control -> DMCC Service Summary screen to see the list of currently registered DMCC devices.

Avaya AES CTI User Status

5.3. Verify TSAPI device monitoring status in MiaRec

Navigate in the MiaRec web interface to Administration -> System -> Recording Interfaces and click Status link for Avaya TSAPI interface.

MiaRec DMCC settings

In the Avaya TSAPI status screen, click View TSAPI monitored devices link for the appropriate recorder instance (the screenshot below shows one instance).

MiaRec DMCC settings

In the Avaya TSAPI monitored devices screen, verify status of the monitored devices. If any of devices shows failed state, then click on the extension link in that window to see the detailed error message.

MiaRec DMCC settings

The error message describes the actual reasons of failure. Read the message and apply appropriate corrections. For example, the message in the following screenshot says that device identifier (extension) is not valid. In this case, remove this extension from the Monitored Phones list in configuration.

MiaRec DMCC settings

If the Avaya TSAPI monitored devices screen shows none of devices (neither successfully monitored nor failed), then probably the TSAPI link connection is not established to AES server. In this case, navigate to Administration -> Maintenance -> System Log and check any error messages. The screenshot below shows that the TSAPI login/password is invalid. Make the appropriate corrections to the configuration.

MiaRec DMCC settings

5.4. Verify DMCC device registration status in MiaRec

Navigate in the MiaRec web interface to Administration -> System -> Recording Interfaces and click Status link for Avaya DMCC interface.

MiaRec DMCC settings

In the Avaya DMCC status screen, click View DNCC registered devices link for the appropriate recorder instance (the screenshot below shows one instance).

MiaRec DMCC settings

In the Avaya DMCC devices screen, verify status of the registered devices. If any of devices shows failed state, then click on the extension link in that window to see the detailed error message.

MiaRec DMCC settings

If the Avaya DMCC registered devices screen shows none of devices (neither successfully registered nor failed), then probably the DMCC connection is not established to the AES server. In this case, navigate to Administration -> Maintenance -> System Log and check any error messages. The screenshot below shows that the DMCC login/password is rejected. Make the appropriate corrections to the configuration.

MiaRec DMCC settings

5.5. Check MiaRec trace log

MiaRec provides detailed logging for troubleshooting purposes. Navigate to Administration -> Maintenance -> Troubleshooting to enable log in MiaRec.

More details about MiaRec recorder trace

6. Additional references

Avaya TSAPI passive recording

1. Introduction

This article describes how to configure the MiaRec Call Recording System with the Avaya Application Enablement Services and Avaya Communication Manager to record incoming and outgoing phone calls.

MiaRec uses port mirroring on a network switch to capture media associated with the recorded stations and TSAPI interface of Avaya Application Enablement Services (AES) to extract agent and call state information.

Requirements:

  • Avaya Communication Manager v6.3.2 or higher
  • Avaya Application Enablement Services (AES) Server v6.3.1 or higher
  • TSAPI Basic License per each recorded extension and each monitored ACD Split / Hunt Group
  • Network Switch with Port Mirroring support (see A list of Switches with port mirroring)
  • Server for MiaRec with two network adapters (see Recommended server)

2. Network Configuration

MiaRec uses port mirroring function on a network switch to capture voice packet related to the agents' IP phones and softphones. MiaRec server needs to have two Network Interface Cards (NICs), one of which is used for port mirroring (capturing voice) and another is used for regular network connection. The first NIC doesn't need to have TCP/IP stack enabled (see Network adapter configuration)

Port mirroring function has to be configured on a network switch in the following way:

  • Ports of the C-LAN and MedPro cards should be configured as sources for port mirroring session
  • MiaRec capturing port should be configured as a destination for port mirroring session

Recording calls on Avaya S8700 and G650

Below is an example of port mirroring configuration on Extreme Networks Summit X250e-24p network switch.

For other models please refer to Port Mirroring Configuration.

Assuming that:

  • C-LAN card is connected to Port 1 of the Summit X250e
  • MedPro card is connected to Port 2 of the Summit X250e
  • MiaRec capturing NIC is connected to Port 24 of the Summit X250e

In this case you need to execute following commands on the switch:

enable mirroring port 24
mirroring add port 1
mirroring add port 2

Save configuration into permanent memory (NVRAM) otherwise port mirroring settings will be lost after switch reboot:

save config

3. Configure Avaya Communication Manager

This section presents configuration steps for the Avaya Communication Manager. It is assumed that an appropriate license file and authentication file have been installed on the server, and that login and password credentials are available.

The configuration and verification operations illustrated in this section were all performed using the Communication Manager System Administration Terminal (SAT).

The procedures include the following areas:

  • Verify the status CTI link for TSAPI service
  • Disable RTP encryption
  • Enable RTCP reporting
  • Disable IP-IP Direct Audio (optional)
  • Administer System Parameters Features

3.1. Verify the status of CTI link for TSAPI service

Log into the System Access Terminal (SAT) to enter the "status aesvcs cti-link" command. The link status should show no for maintenance busy (Mnt Busy), the Service State should indicate established and Version should be 6 or higher.

status aesvcs cti-link

                          AE SERVICES CTI LINK STATUS

CTI   Version  Mnt   AE Services      Service       Msgs     Msgs
Link           Busy  Server           State         Sent     Rcvd

1     7        no    aes              established   15       15




If the CTI link is not established, then follow instructions in chapter Administering Communication Manager for AE Services in document Application Enablement Services Administration and Maintenance Guide available at http://support.avaya.com

3.2. Disable RTP encryption

Execute the "list ip-codec-set" command.

list ip-codec-set

                                IP CODEC SETS

Codec  Codec 1     Codec 2     Codec 3     Codec 4     Codec 5
Set

  1    G.711MU
  2    G.711MU
  3    G.711MU
  4    G.711MU
  5    G.711MU
  6    G.711MU
  7    G.711MU

For each of codec sets execute the "change ip-codec-set N" command, where N is an index of set (from 1 to 7 in above example).

For example, to edit the first codec set, execute the "change ip-codec-set 1" command and make certain that Media Encryption list contains only a single value "none". If other values are presented there (for example, "aes"), then remove all other values except "none" as shown below:

change ip-codec-set 1                                           Page   1 of   2

                          IP Codec Set

    Codec Set: 1

    Audio        Silence      Frames   Packet
    Codec        Suppression  Per Pkt  Size(ms)
 1: G.711MU           n         2        20
 2:
 3:
 4:
 5:
 6:
 7:


     Media Encryption
 1: none
 2: 
 3:

Repeat this step for all the remaining codec sets.

3.3. Enable RTCP reporting

Enter the "change ip-network-region N" command, where N is an existing network region used for the agents' ip phones and softphones. Make certain that the RTCP Reporting Enabled field is set to "y", as shown below. The RTCP packets are used by MiaRec to map IP addresses to agent extensions.

change ip-network-region 1                                      Page   1 of  19
                               IP NETWORK REGION
  Region: 1
Location:         Authoritative Domain: voip.example.com
    Name:
MEDIA PARAMETERS                Intra-region IP-IP Direct Audio: yes
      Codec Set: 1              Inter-region IP-IP Direct Audio: yes
   UDP Port Min: 2048                      IP Audio Hairpinning? y
   UDP Port Max: 3029
DIFFSERV/TOS PARAMETERS                  RTCP Reporting Enabled? y
 Call Control PHB Value: 34      RTCP MONITOR SERVER PARAMETERS
        Audio PHB Value: 46       Use Default Server Parameters? y
        Video PHB Value: 26

3.4. Disable IP-IP Direct Audio (optional)

You can skip this step if recording of internal calls between IP phones is not needed.

Avaya Communication Manager supports "shuffling" of the media streams, which allows two IP phones to send media directly between each other bypassing the media gateway. "Shuffling" (IP-IP Direct Audio) should be disabled when internal calls between IP phones need to be recorded. IP-IP Direct Audio can be disabled either for individual IP phones or for a whole ip network region.

To disable IP-IP Direct Audio for individual IP phone, enter the "change station xxxxx", where xxxxx is phone's extension and change "Direct IP-IP Audio Connections" to "n" on Page 2.

Parameter "IP Audio Harpinning" is recommended to set to "y". In this case MedPro board acts as a proxy without allocating of resources on TDM bus.

change station 51001                                            Page   2 of   5
                                     STATION
FEATURE OPTIONS
           LWC Reception: spe              Auto Select Any Idle Appearance? n
          LWC Activation? y                         Coverage Msg Retrieval? y
  LWC Log External Calls? n                                    Auto Answer: none
             CDR Privacy? n                               Data Restriction? n
   Redirect Notification? y                     Idle Appearance Preference? n
 Per Button Ring Control? n                   Bridged Idle Line Preference? n
   Bridged Call Alerting? n                       Restrict Last Appearance? y
  Active Station Ringing: single
                                                         EMU Login Allowed? n
        H.320 Conversion? n          Per Station CPN - Send Calling Number?
       Service Link Mode: as-needed
         Multimedia Mode: enhanced
    MWI Served User Type:                       Display Client Redirection? n
              AUDIX Name:                      Select Last Used Appearance? n
             IP Hoteling? n                      Coverage After Forwarding? s
                                                   Multimedia Early Answer? n
 Remote Softphone Emergency Calls: as-on-local Direct IP-IP Audio Connections? n
  Emergency Location Ext: 51001         Always Use? n IP Audio Hairpinning? y

To disable IP-IP Direct Audio for all IP phones inside the IP network region, enter the "change ip-network-region N" command, where N is an existing network region used for the agents' ip phones and softphones and change "Intra-region IP-IP Direct Audio" and "Inter-region IP-IP Direct Audio" to "no".

Parameter "IP Audio Hairpinning" is recommended to set to "y".

change ip-network-region 1                                      Page   1 of  19
                               IP NETWORK REGION
  Region: 1
Location:         Authoritative Domain: voip.example.com
    Name:
MEDIA PARAMETERS                Intra-region IP-IP Direct Audio: no
      Codec Set: 1              Inter-region IP-IP Direct Audio: no
   UDP Port Min: 2048                      IP Audio Hairpinning? y
   UDP Port Max: 3029
DIFFSERV/TOS PARAMETERS                  RTCP Reporting Enabled? y
 Call Control PHB Value: 34      RTCP MONITOR SERVER PARAMETERS
        Audio PHB Value: 46       Use Default Server Parameters? y
        Video PHB Value: 26

Alternatively, instead of changing "IP-IP Direct Audio" parameter, you can change port mirroring configuration and mirror each IP phone's port rather than CLAN and MedPro ports (see below network diagram).

Such configuration of port mirroring allows a recording of internal calls without changing of "IP-IP Direct Audio" parameter.

Record internal calls on Avaya network

3.5. Administer System Parameters Features

Enter the "change system-parameters features" command. Navigate to Page 5, and verify that Create Universal Call ID (UCID) has value “y”. If not, then set it to "y" and set UCID Network Node ID to an unassigned node ID.

change system-parameters features                               Page   5 of  17
                        FEATURE-RELATED SYSTEM PARAMETERS

SYSTEM PRINTER PARAMETERS
  Endpoint:               Lines Per Page: 60

SYSTEM-WIDE PARAMETERS
                                     Switch Name:
            Emergency Extension Forwarding (min): 10
          Enable Inter-Gateway Alternate Routing? n
Enable Dial Plan Transparency in Survivable Mode? n
                              COR to Use for DPT: station

MALICIOUS CALL TRACE PARAMETERS
               Apply MCT Warning Tone? n   MCT Voice Recorder Trunk Group:

SEND ALL CALLS OPTIONS
     Send All Calls Applies to: station    Auto Inspect on Send All Calls? n

UNIVERSAL CALL ID
     Create Universal Call ID (UCID)? y    UCID Network Node ID: 9999
     Copy UCID for Station Conference/Transfer? n

Navigate to Page 13, and set Send UCID to ASAI to "y". This parameter allows for the universal call ID to be sent to MiaRec call recording application.

change system-parameters features                               Page  13 of  17
                        FEATURE-RELATED SYSTEM PARAMETERS

 CALL CENTER MISCELLANEOUS
                         Clear Callr-info: next-call
        Allow Ringer-off with Auto-Answer? n

    Reporting for PC Non-Predictive Calls? n


  ASAI
            Copy ASAI UUI During Conference/Transfer? n
        Call Classification After Answer Supervision? n
                                   Send UCID to ASAI? y

4. Configure Avaya Application Enablement Services

This section provides the procedures for configuring Avaya Application Enablement Services. The procedures include the following areas:

  • Verify TSAPI service licensing
  • Administer TSAPI link
  • Obtain Tlink name
  • Administer CTI user for MiaRec

4.1. Verify TSAPI service licensing

Prior to any administration, verify that the TSAPI service has been licensed properly. Open the AES OAM web interface by browsing to "https://ip-address-or-dns", where "ip-address-or-dns" is the IP address or DNS alias of the Appliation Enabledment Services server, and log in using the appropriate credentials (not shown).

Select Licensing -> WebLM Server Access in the left pane, to display the Web License Manager pop-up screen (not shown), and log in using the appropriate credentials.

Avaya AES WebLM Server Access

If the licenses are managed centrally on the System Manager, then select Services -> Licenses in the System Manager home screen. Otherwise, the Web License Manager screen is shown immediately.

Avaya System Manager Licenses

In the Web License Manager screen, select Application_Enablement under Licenses Products to display license capacity and current usage

Make certain that a number of TSAPI Simultaneous Users (licenses) is enough. MiaRec requires TSAPI Basic license for each recorded IP Phone and softphone and for each monitored ACD Split (Hunt Group). If the TSAPI service is not licensed, contact the Avaya sales team or business partner for a proper license file.

Avaya AES TSAPI licenses

4.2. Administer TSAPI link

To administer a TSAPI link, select AE Services -> TSAPI -> TSAPI Links from the left pan of the Management Console. The TSAPI Links screen is displayed, as shown below. If the TSAPI Link is not configured yet, then click Add Link to create one.

Avaya AES TSAPI Links

The Add TSAPI Links screen is displayed next.

The Link field is only local to the Application Enablement Services server, and may be set to any available number. For Switch Connection, select the relevant switch connection from the drob-down list. In this case, the existing switch connection "cm2" is selected. For Switch CTI Link Number, select the CTI Link number from Section 3.1. Make sure that ASAI Link Version is 6 or higher. Retain the default values in the remaining fields.

Avaya AES TSAPI Add Link

4.3. Obtain Tlink name

Select Security -> Security Database -> Tlinks from the left pane. The Tlinks screen shows a listing of the Tlink names. Locate the Tlink Name associated with the switch connection to Avaya Communication Manager. A new TLink name is automatically generated for the TSAPI service. Locate the TLink name associated with the relevant switch connection, which would use the name of the switch connection as part of the Tlink name. Make a note of the associated Tlink name, to be used later for configuring the MiaRec server.

In this case, the associated Tlink name is "AVAYA#CM2#CSTA#AES"'. Note the use of the switch connection "CM2" from Section 4.2 as part of the Tlink name.

If Tlink doesn't exist, then follow instructions in AE Services Administration in document Application Enablement Services Administration and Maintenance Guide available at http://support.avaya.com

Avaya AES Tlinks

4.4. Administer CTI user for MiaRec

Select User Management -> Add User from the left pane, to display the Add User screen in the right pane.

Enter desired values for User Id, Common Name, Surname, User Password, and Confirm Password. Retain the default value of “None” for Avaya Role, and select “Yes” from the CT User drop-down list. Click on Apply at the bottom of the screen (not shown below). Make a note of the User Id and Password, to be used later for configuring the MiaRec server.

Avaya AES Add User

Next, you need to change the security level for the CTI User as it needs to have unrestricted access privileges.

Select Administration -> Security Database -> CTI Users -> List All Users from the left pane. Choose the previously created CTI user, and click Edit.

Avaya AES Edit CTI User

The Edit CTI User screen appears. Tick the Unrestricted Access box and Apply Changes at the bottom of the screen.

Avaya AES Edit CTI User

5. Configure MiaRec Call Recording System

This section presents configuration steps for MiaRec call recording system. It is assumed that MiaRec is already installed on the server. The procedures include the following areas:

  • Install AES TSAPI Client
  • Administer MiaRec TSAPI link to AES

5.1. Install AES TSAPI Client

Download Application Enablement Services TSAPI Client from http://support.avaya.com

Install it on MiaRec server. During installation enter the IP address of the Avaya AES server in the Host Name or IP Address field, retaining the default port of 450 (see below screenshot). Click on Add to List and then Next to finish installation.

Avaya AES TSAPI Client install

5.2. Administer MiaRec link to AES

6. Verification

This section provides the tests that can be performed to verify proper configuration of Avaya Communication Manager, Avaya Application Enablement Services and MiaRec call recording application.

6.1. Verify Avaya Communication Manager

On Avaya Communication Manager, verify the status of the administered CTI links by using the "status aesvcs cti-link" command. The link status should show "no" for maintenance busy (Mnt Busy) and the Service State should indicate "established".

status aesvcs cti-link

                          AE SERVICES CTI LINK STATUS

CTI   Version  Mnt   AE Services      Service       Msgs     Msgs
Link           Busy  Server           State         Sent     Rcvd

1     4        no    aes-server1      established   15       15

The "status aesvcs interface" command should indicate the interface is listening.

status aesvcs interface

                          AE SERVICES INTERFACE STATUS

Local Node        Enabled?  Number of     Status
                            Connections

procr             yes       1             listening

The "status aesvcs link" command will indicate the number of messages sent from, and received at the CLAN interface (or procr), to and from Avaya Application Enablement Services, including maintenance traffic.

status aesvcs link

                            AE SERVICES LINK STATUS

Srvr/  AE Services     Remote IP        Remote  Local Node      Msgs    Msgs
Link   Server                           Port                    Sent    Rcvd

01/01  aes-server1     10.0.0.25        43909   procr           224     209

Once the MiaRec call recording application is running, the "list monitored-station" command will show each station, which is monitored by MiaRec via TSAPI interface.

list monitored-station

                            MONITORED STATION

  Station     Association 1    Association 2    Association 3    Association 4
  Ext         CTI Link  CRV    CTI Link  CRV    CTI Link  CRV    CTI Link  CRV
  -------     -------------    -------------    -------------    -------------
32129          1          10
32130          1           9
32131          1          22
32132          1           7

6.2. Verify Avaya Application Enablement Services

On Application Enablement Services, verify the status of the switch connection by selecting Status -> Status and Control -> Switch Conn Summary from the left pane. Verify that the Conn State is “Talking” for the switch connection associated with Avaya Communication Manager, and that the Associations column reflects the total number of monitored skill groups and agent stations as configured previously.

Avaya AES Switch Connection Summary

Verify the status of the TSAPI link by selecting Status -> Status and Control -> TSAPI Service Summary from the left pane. Verify the Conn Status is “Talking” as shown below.

Avaya AES TSAPI Link Details

Verify the status of the CTI User by selecting Status -> Status and Control -> TSAPI Service Summary from the left pane. Click the User Status button (not shown below). The CTI User Status screen is displayed. Verify that an open session exists for the CTI user created for MiaRec as shown below. This verification step assumes that MiaRec application is configured properly and running.

Avaya AES CTI User Status

6.3. Verify TSAPI device monitoring status in MiaRec

Navigate in the MiaRec web interface to Administration -> System -> Recording Interfaces and click Status link for Avaya TSAPI interface.

MiaRec DMCC settings

In the Avaya TSAPI status screen, click View TSAPI monitored devices link for the appropriate recorder instance (the screenshot below shows one instance).

MiaRec DMCC settings

In the Avaya TSAPI monitored devices screen, verify status of the monitored devices. If any of devices shows failed state, then click on the extension link in that window to see the detailed error message.

MiaRec DMCC settings

The error message describes the actual reasons of failure. Read the message and apply appropriate corrections. For example, the message in the following screenshot says that device identifier (extension) is not valid. In this case, remove this extension from the Monitored Phones list in configuration.

MiaRec DMCC settings

If the Avaya TSAPI monitored devices screen shows none of devices (neither successfully monitored nor failed), then probably the TSAPI link connection is not established to AES server. In this case, navigate to Administration -> Maintenance -> System Log and check any error messages. The screenshot below shows that the TSAPI login/password is invalid. Make the appropriate corrections to the configuration.

MiaRec DMCC settings

6.4. Check MiaRec trace log

MiaRec provides detailed logging for troubleshooting purposes. Navigate to Administration -> Maintenance -> Troubleshooting to enable log in MiaRec.

More details about MiaRec recorder trace

7. Additional references

Broadsoft call recording setup

Broadsoft SIPREC recording

LDAP integration

Cisco call recording setup

Cisco active recording (Built-in-Bridge)

This guide describes the configuration procedures required for call recording on Cisco Unified Communication Manager (UCM) platform and phones that have Built-in-Bridge (BiB) capability.

Requirements

The features utilized in this method of recording require the following:

Overview

This guide describes the configuration procedures required for call recording on Cisco Unified Communication Manager (UCM) platform and phones that have Built-in-Bridge (BiB) capability.

How it works

The MiaRec call recording system utilizes Built-in-Bridge call monitoring and recording capability available in 3rd generation of Cisco phones. Cisco UCM establishes SIP trunk connections to MiaRec recording server and notifies the latter when call is started. Cisco IP phone relays RTP media directly to the recorder.

Record Calls on Cisco Unified Communications Manager - Network Diagram

Cisco phones supporting Built-in-Bridge feature

The following table lists Cisco IP phone models, which support Built-in-Bridge feature for call recording and monitoring.

Phone modelSupported protocols
Cisco 6901 not supported
Cisco 12 S not supported
Cisco 12 SP not supported
Cisco 30 SP+ not supported
Cisco 3905 not supported
Cisco 3911 not supported
Cisco 6901 not supported
Cisco 6911 SCCP, SIP
Cisco 6921 SCCP, SIP
Cisco 6941 SCCP, SIP
Cisco 6945 SCCP, SIP
Cisco 6961 SCCP, SIP
Cisco 7811 SIP
Cisco 7821 SIP
Cisco 7841 SIP
Cisco 7861 SIP
Cisco 7902 not supported
Cisco 7905 not supported
Cisco 7906 SCCP, SIP
Cisco 7910 not supported
Cisco 7911 SCCP, SIP
Cisco 7912 not supported
Cisco 7914 Sidecar SCCP
Cisco 7915 Sidecar SCCP, SIP
Cisco CKEM Sidecar SIP
Cisco 7920 not supported
Cisco 7921 SCCP
Cisco 7925 SCCP
Cisco 7926 SCCP
Cisco 7931 SCCP, SIP
Cisco 7935 not supported
Cisco 7936 not supported
Cisco 7937 SCCP
Cisco 7940 not supported
Cisco 7941 SCCP, SIP
Cisco 7941G-GE SCCP, SIP
Cisco 7942 SCCP, SIP
Cisco 7945 SCCP, SIP
Cisco 7960 not supported
Cisco 7961 SCCP, SIP
Cisco 7961G-GE SCCP, SIP
Cisco 7962 SCCP, SIP
Cisco 7965 SCCP, SIP
Cisco 7970 SCCP, SIP
Cisco 7971 SCCP, SIP
Cisco 7975 SCCP, SIP
Cisco 7985 SCCP, SIP
Cisco 8811 SIP
Cisco 8831 SIP
Cisco 8841 SIP
Cisco 8845 SIP
Cisco 8851 SIP
Cisco 8861 SIP
Cisco 8865 SIP
Cisco 8941 SCCP, SIP
Cisco 8945 SCCP, SIP
Cisco 8961 SIP
Cisco 9951 SIP
Cisco 9971 SIP
Cisco DX650 SIP
Cisco E20 not supported
Cisco EX60 not supported
Cisco EX90 not supported
Cisco CTS 500 not supported
Cisco CTS 500-32 not supported
Cisco ATA 186 not supported
Cisco ATA 187 not supported
Cisco ATA 188 not supported
Cisco IP Communicator SCCP, SIP
Cisco Jabber for Windows SCCP, SIP
Cisco Jabber for Mac SCCP, SIP
Cisco Jabber for iPad not supported
Cisco Jabber for Android not supported
Cisco Unified Personal Communicator not supported
Cisco VGC Phone not supported
VG224 not supported
VG248 not supported
CTI Port not supported
CTI Remote Device not supported
CTI Route Point not supported

Last table update: 2015/10/01

Identify phones that support Built-in-Bridge recording

Up to date list of phone models that support Built-in-Bridge recording may be received with the following instructions:

  1. Start Cisco Unified Reporting by choosing Cisco Unified Reporting in the Navigation menu in Cisco Unified Communications Manager Administration and clicking Go.
  2. Click System Reports in the navigation bar.
  3. In the list of reports that displays in the left column, click the Unified CM Phone Feature List option.
  4. Click the Generate a new report link to generate a new report, or click the Unified CM Phone Feature List link if a report already exists.
  5. To generate a report of all devices that support recording, choose these settings from the respective drop-down list boxes and click the Submit button:

    • Product: All
    • Feature: Record
  6. The List Features pane displays a list of all devices that support the recording feature. You can click on the Up and Down arrows next to the column headers (Product or Protocol) to sort the list.

Identify phones supporting built-in-bridge

Configure CUCM

Create SIP profile for recorder

Use the Device > Device Settings > SIP Profile menu option in Cisco Unified Communications Manager Administration to create SIP profile for recorder.

The following figure illustrates creating a SIP profile for the recorder.

Create SIP profile for recorder

Make sure that the Deliver Conference Bridge Identifier option is checked. When enabled it allows to deliver additional information (specifically, the b-number that identifies a conference bridge) to the recorder across the SIP trunk. If the check box is left unchecked, the far-end information for the remote conference remains empty. Check the Deliver Conference Bridge Identifier check box on the remote cluster SIP profile as well.

Create SIP profile for recorder 2

Checking this check box is not required for recording, but the conference bridge identifier helps to group multiple call segments belonging to the same conference into one interaction, like shown in below screenshot:

Group calls into interaction

Configure SIP OPTIONS Ping

In multi-server setup, it is recommended to enable SIP Options Ping feature for each recording server. In a single-server setup, this feature should be disabled (see details below).

  • Single-server setup - disable SIP OPTIONS Ping
  • Multi-server setup - enable SIP OPTIONS Ping

Cisco UCM starting from v.8.5(1) supports SIP OPTIONS Ping feature. Cisco UCM periodically sends a SIP OPTIONS (ping) message to each recording server to detect its availability. If the recording server is unavailable – indicated by either no response, response of “408 Request Timeout” response of “503 Service Unavailable”, Cisco UCM marks this recording server as unavailable. It skips that server in the round-robin or sequential list of recording servers. The SIP Options Ping feature allows to detect availability of the recording server earlier, without having to wait until a call is ready to be recorded.

However, in single-node deployments, SIP Options Ping is not recommended. Not only is it not helpful, but it can result in unnecessary failure recovery delays.

Create SIP OPTIONS Ping

Create SIP Trunk Security Profile

Create SIP Trunk Security Profile for each MiaRec recording server.

Use the System > Security > SIP Trunk Security Profile menu option in Cisco Unified Communications Manager Administration to create SIP Trunk Security profile for recorder.

  • Set Incoming Transport Type to TCP+UDP.
  • Set Outgoing Transport Type to TCP (this setting has to match the configuration of MiaRec). TCP is recommended.
  • Uncheck option Enable Digest Authentication
  • Set Device Security Mode parameter to Non Secure.

Create SIP Trunk Security Profile

Create a SIP Trunk that points to the recorder

Use the Device > Trunk menu option in Cisco Unified Communications Manager Administration to create SIP trunk that points to the recorder.

  • Ensure that the Media Termination Point Required check box is unchecked.
  • Select the Run On All Active Unified CM Nodes check box.

Create SIP Trunk

Make sure the SIP Privacy option is set to None, otherwise you will see in call details a text "Anonymous" instead of user's extension.

Create SIP Trunk

In SIP Information section configure:

  • Destination Address should point to ip-address or DNS name of the recorder server
  • Destination Port should match the port on which MiaRec recorder is listening for messages from CUCM (see configuration of MiaRec below)
  • Select the previously created SIP Trunk Security Profile for the recorder
  • Select the previously created SIP Profile for the recorder

Create SIP Trunk

Create recording profile

Use the Device > Device Settings > Recording Profile menu option in Cisco Unified Communications Manager Administration to create recording profile.

The following figure illustrates creating a recording profile.

Set Recording Destination Address to the directory number that associates the recorder with this recording profile. The only guideline for this number: it should be possible for UCM to route it to the SIP trunk where the recorder is defined. No user is going to directly call this number, this is internal to the system. Make sure it does not collide with your numbering plan. This is why the example shows '7777'.

Set Recording Calling Search Space to the CSS that includes partitions containing the user phones and the partition that you set up for the MiaRec SIP Trunk.

Create Recording Profile

Create a route group for the recorder(s)

Create a new Route Group

Use the Call Routing > Route/Hunt > Route Group menu option in Cisco Unified Communications Manager Administration to create a route group for the MiaRec SIP trunk:

  • Assign the previously created SIP trunk(s) to this route group at the Find Device to Add to Route Group pane. Select the desired SIP trunk(s) and click on the Add to Route Group button.
  • Set the Distribution Algorithm setting to Circular when using multiple recording servers with the shared database or to Top Down when using multiple recording servers with dedicated databases (i.e. each recorder communicates own database instance).

Reoute Pattern Configuration

Create a new route list

Select Call Routing > Route/Hunt > Route List menu item and click on the Add New button. If you already have one, simply select it from the list.

  • Select the appropriate Cisco Unified Communications Manager Group and click on the Save button.
  • Click on the Add Route Group button at the Route List Member Information panel.
  • Select the previously created route group at the Route Group setting, then click Save.
  • At the Route List Configuration page click on the Save button.

Create a new route pattern

Route Pattern should match to the Recording Destination Address in the previously created recording profile - Set Route partition to the partition that includes the user phones. - In Gateway/Route List select the route list of which the recorder is a member.

Reoute Pattern Configuration

Enable Built-in-Bridge for all phones (optional)

Built-in-Bridge setting can be enabled on per-phone basis or on system level (default to all phones).

Access the System > Service Parameters menu option in Cisco Unified Communications Manager Administration, select your CUCM server from the Server list and Cisco CallManager from the Service list:

Service Parameter Configuration

To enable Built-in-Bridge on system level change the option Clusterwide Parameters (Device - Phone) -> Builtin Bridge Enable to On:

Clusterwide Builtin Bridge Enable

Configure tones for recording (optional)

Set the service parameters for playing tone to True to allow tone to be played either to agent only, to customer only, or to both.

Use the System > Service Parameters menu option in Cisco Unified Communications Manager Administration to perform the necessary configuration.

Change corresponding options of group Clusterwide Parameters (Feature – Call Recording).

The following figure illustrates using service parameters to configure tones.

Play Recording Notification Tone

Codecs configuration

Codecs iLBC, iSAC, L16 and AAC-LD should be disabled for Recording-Enabled devices as they are not supported by MiaRec recording system at the moment.

Use the System > Service Parameters menu option in Cisco Unified Communications Manager Administration to perform the necessary configuration.

Change the following settings of group Clusterwide Parameters (System - Location and Region):

  • iLBC Codec Enabled to Enabled for All Devices Except Recording-Enabled Devices
  • iSAC Codec Enabled to Enabled for All Devices Except Recording-Enabled Devices
  • Default Intraregion Max Audio Bit Rate to 64 kbps (G.722, G.711)

Codecs Configuration

Disable 256kpbs wideband codec

Latest models of Cisco phones support high quality 256kbps wideband codec for phone-to-phone communications withing the same region. Unfortunately, this codec is not supported by Cisco Built-in-Bridge recording method and it should be disabled otherwise internal calls between users will not be recorded.

Navigate to the System > Region menu option in Cisco Unified Communications Manager Administration and change per-region setting Max Audio Bit Rate to either Use System Default or 64 kbps (G.722, G.711) as shown in below screenshot.

256kbps Codecs Configuration

Recording of conference calls

Recording of conference calls on Cisco platform has the following limitations:

  • Cisco UCM doesn't support re-negotiated of audio codecs for calls which are recorded with Built-in-Bridge method.
  • The Cisco Software Conference Bridge supports only G.711 and 256k wideband codecs.

The following call scenario may occur:

  • One user makes a call to another user. If these two users use Cisco phones, then G.722 wideband codec is chosen for such call.
  • Then one of users tries to create a 3-way conference and add the third user to the conference.
  • CUCM creates a software-based conference to mix audio from three users. The software-based conference doesn’t support G.722 codec.
  • CUCM needs to re-negotiate codec with each of users and change it from G.722 to G.711.
  • But CUCM cannot do that because such call is recorded with BiB method and codec is fixed for such call.
  • As a result a user, who tries to create a conference is dropped from a conference.

There are two workarounds for this situation:

  1. Disable G.722 codec for users, which are recorded with BiB method.

  2. Allocate codec transcoding resources on Cisco platform to automatically convert audio from one codec to another on-flight.

To disable G.722 codec, change the setting G.722 Codec Enabled to Enabled for All Devices Except Recording-Enabled Devices.

G.722 Codecs Configuration

Configure phones

Enable Built-in-Bridge on per-phone basis

Note, Built-in-Bridge option may be configured clusterwide for all phones.

Use the Device > Phone menu option in Cisco Unified Communications Manager Administration to enable Built-in-Bridge option.

The following figure illustrates turning on the IP phone Built-in-Bridge to allow monitoring or recording.

Enable Built-in-Bridge

Enable recording for a line appearance

Use the Device > Phone menu option in Cisco Unified Communications Manager Administration to configure line appearance of particular phone.

  • To enable recording of an agent, set the Recording Option in the line appearance of the agent to one of the following options:

    • Automatic Call Recording Enabled
    • Selective Call Recording Enabled
  • In the Recording Profile option select the previously created recording profile from the drop-down list box

The following figure illustrates enabling recording for a line appearance.

Line configuration

Configure MiaRec

In MiaRec web portal navigate to the Administration -> System Configuration -> Recording Interfaces menu.

Click Configure for Cisco Built-in-Bridge recording interface.

Recording interfaces

Inside the opened dialog change the following settings:

Option Description
Signaling UDP port and Signaling TCP port These port values should be set to the same values as configured in step Create a SIP Trunk that points to the recorder
Begin RTP port range and End RTP port range RTP port range should be set to values not conflicting to other recording interfaces or other networking applications running on the same host as MiaRec application. Make sure that the port range is large enough for anticipated number of concurrently recorded calls. One concurrent call requires two UDP ports for receiving media streams from agent's phone.
Public Ip-address Public IP address if MiaRec server is located behind NAT. Make sure that port forwarding is configured properly on your NAT router. If MiaRec server is not behind NAT, then leave this parameter empty.
No-Audio Begin Timeout This timeout value specifies how long to wait for the first RTP media packet before give up.
No-Audio Normal Timeout In case of RTP transmission stop, this timeout value specifies how long to want for RTP restoration before forcibly completing call recording.

Cisco active recording

Configure firewall

If firewall is running on MiaRec recording server, then add exclusion rules for the following ports as described in step Configure MiaRec:

  • Signaling UDP Port and Signaling TCP Port
  • Begin/End RTP port range (UDP)

Cisco TAPI integration

MiaRec call recording software uses Cisco TAPI interface in conjunction with Cisco SIP trunk-based active recording (Built-in-Bridge) to retrieve additional call metadata about recordings.

MiaRec integration with Cisco TAPI

MiaRec uses Cisco TAPI interface for the following tasks:

  • Retrieve the the remote party phone number/name on Cisco UCM before version 8.5.1.

    On older versions of Cisco UCM SIP trunk-based recording (Built-in-Bridge) doesn't pass the remote party phone number over SIP channel to the recorder. TAPI interface is used to retrieve such missing call information. On newer version of CUCM (starting from v.8.5.1) the remote party info is sent to the recorder over SIP channel and TAPI interface is not necessary for this case.

  • Retrieve Cisco partition information.

    The partition information is required in rare scenarios when different branches have overlapping extensions. For example, the same extension 123 is used in multiple remote offices. The partition information is used to identify user uniquely.

  • Retrieve accurate call direction for recordings.

    Due to limitation of Cisco SIP Trunk-based recording (Built-in-bridge), a call direction is not passed by CUCM to the recorder. MiaRec application can determine call direction automatically based on knowledge of near-end and far-end refci values. In some call scenarios such detection is not accurate. As a result incoming calls may be displayed in recorder as outgoing or vice versa. If your Cisco system suffers from such issue and call direction is critical, then TAPI interface allows to determine call direction accurately.

  • Automatically play recording announcement for any call scenarios, including inbound and outbound.

    Usually, a recording announcement is implemented for inbound call scenarios only. With MiaRec it is possible to play automatically recording announcement for outbound call scenarios as well.

Limitations

  • TAPI is supported in Windows version only. An alternative cross-platform JTAPI interface is in our roadmap.

  • MiaRec supports TAPI integration with Cisco UCM in conjunction with active recording (Built-in-Bridge) method only. Passive recording method (port mirroring) does not integrate with TAPI.

  • The maximum number of CTI-controlled devices per node varies by server class. As an example:

    • MCS-7825 and MCS-7835 servers support up to 800 CTI-controlled devices per node.
    • MCS-7845 servers support up to 2500 CTI-controlled devices per node.
  • CTIManager provides two advanced, clusterwide service parameters that are used in conjunction with the CTI Super Provider capability:

    • Maximum Devices Per Provider - This parameter specifies the maximum number of devices that a single CTI application can open. The default specifies 2000 devices.

    • Maximum Devices Per Node - This parameter specifies the maximum number of devices that all CTI applications can open on any CTIManager node in the Cisco Unified Communications Manager system. The default specifies 800 devices.

Configuration

Configuration of Cisco TAPI integration consists of the following steps:

  1. Create TAPI user in Cisco UCM Admin portal.

  2. Install and configure Cisco TAPI TSP driver on machine, where MiaRec software is running

  3. Verify Cisco TAPI driver configuration

  4. Enable Cisco TAPI interface in MiaRec configuration

Add TAPI user for MiaRec application

You must first create the application user who is capable of monitoring and, optionally, controlling phones.

Navigate in Cisco Unified CM Administration web portal to the menu User Management -> Application User and click Add New button to create new user account.

Add application user

In the list Available Devices select the devices, which state should be monitored by MiaRec and click arrow V to move such devices to the list Controlled Devices

Add application user

In the section Permissions Information click the Add to Access Control Group button to select permissions for application user.

Add application user

In the new pop-up window select the following required options:

  • Standard CTI Allow Control of All Devices
  • Standard CTI Allow Control of Phones supporting Connected Xfer and conf
  • Standard CTI Allow Control of Phones supporting Rollover Mode
  • Standard CTI Enabled

Other options are not required.

Add application user

Save the settings of new application user.

Configure Cisco TAPI TSP driver

The Cisco TAPI Service Provider (TSP) is a TAPI driver that is installed on the Windows server that allows communication of line events between MiaRec software and the Cisco UCM.

Download the TAPI driver

The installer for the client can be obtained from the Cisco Unified CM Administration portal using the following steps:

  1. Open Cisco Unified CM Administration portal in a web browser and log in with an administrator account.

  2. Once logged in, hover over the Application menu across the top of the site, and click the Plugins link.

  3. On the Find and List Plugins page, enter "Cisco TAPI" into the search field and click Find.

  4. The plugin list will load. Click the Download link on either 32-bit or 64-bit client depending on your operating system.

Download Cisco TAPI driver

Install the TAPI driver

Open the CiscoTSP.exe installer and follow instructions on screen. You will be asked for Cisco CallManager address and application user/password as created in previous steps.

Restart operating system is required after installation of Cisco TAPI driver.

[Optional] Modify Cisco TAPI configuration

To modify Cisco TAPI driver configuration use CiscoConfig.exe utility, which is installed with TAPI driver.

Start this utility and click Configure button.

Configure Cisco TAPI driver

The following screenshots demonstrate example of configuration.

Configure Cisco TAPI driver

Configure Cisco TAPI driver

Verify Cisco TAPI configuration

To verify the TSP operation on the machine where the TSP is installed, use the Microsoft Windows Phone Dialer Application.

Windows Phone Dialer

When the program is run, a dialog box displays that asks which line and address the user wants to use to connect. If there are no lines in the Line drop down list, then a problem may exist between the TSP and the Cisco Unified Communications Manager.

If lines are available, choose one of the lines, keep the Address set to zero (0) and click OK. Enter a Number to dial, and a call should be placed to that number.

If call is successful, you know that the TSP is operational on the machine where the TSP is installed. If problems are encountered with installation and setup of Remote TSP, this test represents a good way to verify whether the TSP is operating properly and that the problem is with the configuration and setup of Remote TSP.

Enable trace in Cisco TAPI driver.

Start CiscoConfig.exe utility and click the Trace tab.

Select Trace On check box and select:

  • TSP Trace to trace the TSP internal messages.
  • CTI Trace to trace the messages sent between CTI and TSP.
  • TSPI Trace to trace the requests and events that are sent between TSP and TAPI.

Select Error to just log errors in the TSP or Detailed to log internal messages for debugging purposes.

Set up a Directory that is the path for the trace log. For example, C:\CiscoTapiLog

No. of Files: Setting this to a value greater than or equal to 1 enables rolling log files. For example, a value of 10 will cause up to 10 log files to be used in a cyclic fashion. Max lines/file: specifies the maximum number of trace statements that will be written to each log file. For example, a value of 1000 will cause up to 1000 trace statements to be written to each log file.

Cisco TAPI Trace config

After Trace is enabled in Cisco TAPI driver, start the TAPI application (for example, Windows Phone Dialer) and then examine logs.

Enable Cisco TAPI interface in MiaRec

By default Cisco TAPI is disabled in MiaRec because it may increase startup time of application when TAPI driver is not configuration properly.

To enable Cisco TAPI interface in MiaRec, navigate to menu Administration -> System Configuration -> Recording Interfaces.

In the section Supplementary Interfaces locate the Cisco TAPI and click Configure button to enable Cisco TAPI.

MiaRec Enable Cisco TAPI

Troubleshooting

For troubleshooting purposes you may enable trace in MiaRec to examine Cisco TAPI messages received by MiaRec from CUCM.

Metaswitch call recording setup

This guide describes the configuration procedures required for MiaRec call recording software for interoperability with Metaswitch MetaSphere CFS and/or Perimeta SBC.

The MiaRec is a multi-tenant call recording platform that communicates with Metaswitch over the Session Initiation Protocol (SIP) interface and conforms to the SIP Recording (SIPREC) standard.

Metaswitch SIPREC configuration

This article explains how to set up MiaRec SIPREC call recording on the Metaswitch CFS platform.

Requirements:

  • MetaSwitch CFS v.9.0.10 or higher

SIPREC recording interface is supported in Metaswitch CFS starting from v.9.0.10

Service impact

The step to enable call recording on MetaSphere CFS, by modifying the global Application Servers object, requires you to disable this object briefly in order to make configuration changes. This means that any other services provided to MetaSphere CFS by Application Servers will be unavailable for a short period, typically no more than five minutes. It is recommended to do this step during a maintenance window or when call usage is low.

Apart from a brief outage in services provided to MetaSphere CFS by Application Servers, as described above, this procedure has no impact on service.

Network architecture

Metaswitch system uses the established SIPREC link to send call details (caller/called phone number, service provider id etc) and audio RTP stream to MiaRec recording server.

Metaswitch MiaRec Hosted Call Recording SIPREC

Step 1. Configure SIPREC recording interface in MiaRec

  1. Using MiaRec web portal, navigate to Administration -> System -> Recording Interfaces.

  2. Click Configure button for SIPREC interface

  3. Fill in the fields as follows:

    • Enable: checked (True)
    • Signaling UDP port: the desired port for SIP signaling. By default, MiaRec uses port 5080 for SIPREC, but you can change it to any other value.

    • Signaling TCP port: should be the same as UDP. Metaswitch CFS may send SIP packets towards to MiaRec using either UDP or TCP based on varios criteria, for example, it may choose TCP for large packets and UDP for smaller packets. So, both TCP and UDP listening ports should be enabled in MiaRec and both these ports should have the same value.

    • Public ip-address: specify the public ip-address of the MiaRec server if you use port forwarding for SIPREC traffic.

    • Use default values for other fields.

Update firewall settings. If you change SIPREC signaling port, then you need to update the firewall settings on the MiaRec server.

Step 2. Import the Remote Media Gateway Model used for the MiaRec recording server

  1. Download rmgm_Miarec_521149_9.3_v1.txt and save it to the MetaView User's home directory on the computer where you are running MetaView Explorer.

  2. Log in to MetaView Explorer.

  3. Select Object tree and views. Expand the tree until you can see the Network Element object corresponding to your MetaSphere CFS.

  4. Locate and expand the Controlled Networks object, then the Remote Media Gateway Models object below it.

  5. In the Import - file field, type the name of the Remote Media Gateway Model import file. Click apply to confirm your changes.

  6. Click on the import button to import the file.

The Import - status field should change to In progress and then to Succeeded to indicate that the configuration has been imported successfully.

If the status does not change to Succeeded, then look at the Import - log correlator field, and click on the go to log button next to this field to jump to the MetaView Explorer log viewer window, which shows a summary log describing the import action you have just taken. If there were problems with the import, you can follow the links within the log viewer to see the earlier logs relating to this problem. Take any action recommended by these logs and retry the import.

Step 3. Create the Configured SIP Binding

  1. In MetaView Explorer, select Object tree and views. Expand the tree until you can see the Network Element object corresponding to your MetaSphere CFS. Expand this object.

  2. Locate and expand the Controlled Networks object, then the Configured SIP Bindings object below it.

  3. Click on the add sub-component button and choose Configured SIP Binding.

  4. Fill in the fields as follows. Any fields not listed below can be left with their default values.

    • Name: fill in a name that will help you to associate this binding with the recording server. For example, "MiaRec recorder"
    • Usage: set to Application Server
    • Use DN for identification: set to True
    • SIP authentication required: set to False
    • IP address match required: set to True
    • Contact address scheme: set to IP address and port or Domain name SRV lookup (auto fail-over)
    • Contact IP address and Contact IP port: set to the address and port of the MiaRec recording server (if the "Contact address scheme" is "IP address and port")
    • Contact domain name: set to the DNS SRV domain name of the MiaRec recording servers (if the "Contact address scheme" is "DNS SRV")
    • Proxy IP address and Proxy IP port: set to the IP address and port used to communicate with the proxy, or leave blank if a proxy is not being used
    • Trusted: set to True
    • Media Gateway model: select the model that you imported earlier in this procedure
    • Maximum call appearances: set this to the maximum concurrent calls for the recording service. Enabling Call Recording on large numbers of lines will increase the resources used by the service, particularly Media Gateway resources. Ensure that you have enough capacity to handle the expected level of recorded calls. If the MiaRec recorder server is located in a separate network, make sure that appropriate bandwidth is available for the the anticipated recording data network traffic.
    • Poll peer device: set to True.
  5. Click apply to confirm your changes

Step 4. Create the Application Server

  1. In MetaView Explorer, navigate to Call Feature Server -> Call Services -> Global Application Servers.

  2. Click on the add sub-component button and choose Application Server.

  3. Fill in the fields as follows.

    • Directory number: select a free telephone number within one of the number ranges owned by the CFS
    • Configured SIP Binding: select the binding that you created in the previous step
    • Server type: select Recording and leave all the other values unselected
  4. Click apply to confirm your changes.

Step 5. Enable call recording service on MetaSphere CFS

This step requires you to disable the global Application Servers object briefly in order to make configuration changes. This means that any other services provided to MetaSphere CFS by Application Servers will be unavailable for a short period, typically no more than five minutes. If you are running this MOP on a live system, you are recommended to do this step during a maintenance window or when call usage is low.

  1. In MetaView Explorer, navigate to Call Feature Server -> Call Services -> Application Servers.

  2. Click on disable to disable the object so that you can modify it.

  3. Set Recording service support to Configured.

  4. Set Recording service - default subscribed setting and Recording service - default enabled setting according to the desired behavior.

  5. In Recording service - default server, select the Application Server that you added earlier in this procedure.

  6. Click apply to confirm your changes, then enable to re-enable the Application Servers object. Check that it becomes active and no alarms are shown.

Step 6. Enable recording individually for each user in Metaswitch CFS.

This step is not required if you have enabled Call Recording on all lines by default.

You can use either MetaView Web or MetaView Explorer for this step. Repeat it for each line that you will use for testing Call Recording.

  • If you are using MetaView Web:

    1. Search for the Business Group Line, MLHG, MADN or PBX DID Number using its directory number, or search for the PBX using its name.
    2. Go to the Configuration tab and expand the Advanced section to show the Recording Service fields.
    3. Ensure that the service is both subscribed and enabled, and that the server is set to the new server you added earlier in this procedure.
    4. Click apply to confirm your changes.
  • If you are using MetaView Explorer:

    1. Use the Find option on the left-hand menu to find the line.
    2. Then find the Application Servers child object below it. For a PBX DID Number, the equivalent child object is DID Number Call Services.
    3. Ensure that the service is both subscribed and enabled, and that the server is set to the new server you added earlier in this procedure.
    4. Click apply to confirm your changes.

Step 7. Disable media bypass in Perimeta SBC for all recorded users

Subscribers behind Perimeta that have call recording enabled should not be allowed to use SBC media bypass, as this has been found to cause problems in the media path (one-way or no-audio issue for some call scenarios, including attended call transfer, hold/resume and 3-party conference). To disable it, on the adjacency facing the subscriber, type 'call-media-policy' and then 'media-bypass-policy forbid'.

Step 8. Make a test call and verify the recording

Make a call to or from one of the test lines on which Call Recording has been enabled. Check the recording on the MiaRec recording server.

If recording is not available, use MetaView Service Assurance Server to confirm that the call is being handled correctly

Detailed procedure:

  1. Log in to the MetaView Service Assurance Server Web GUI.
  2. Click Search.
  3. On the Number tab, enter the number of the Business Group Line to or from which you made the test call.
  4. Find the call that you made to or from the test number, and check the MetaView Service Assurance Server output to confirm that a SIP INVITE message was sent from MetaSphere CFS to the MiaRec recording server for this call.

Known limitations

No RTP towards MiaRec when Perimeta SBC is placed between CFS and MiaRec servers.

If SIPREC traffic is routed through Perimeta SBC, then you may face with no RTP issue. RTP packets are not delievered by SBC to MiaRec.

By default, the NAT auto-detect feature is enabled on the Perimeta SBC. SBC typically will wait for the endpoint to send RTP traffic before it will begin sending any of its own. Since MiaRec recorder is just a collection point, both ends would sit waiting for RTP.

You need to build a new adjacency on the SBC specific for the MiaRec server like shown below:

adjacency sip MiaRecCallRecording
    adjacency-limits
      regs 0
      regs-rate sustain 0 per-second
    call-media-policy
      media-bypass-policy forbid
      repeat-sdp-on-200ok
    interop
      header-settings from rewrite host local port include
        # Effective value: host local port include
      preferred-transport udp
      message-manipulation
        edit-profiles inbound ""
        edit-profiles outbound ""
    adjacency-type preset-access
    privacy untrusted
    realm “Name associated with RTP Ports”
    service-address “Name associated with Service Network”
    signaling-local-port 5080
    signaling-peer “IP address of MiaRec”
    signaling-peer-port 5080
    statistics-setting detail
    default-interop-profile “Name of Blacklist Profile”
    deactivation-mode normal
    activate

SIP packets towards the MiaRec server are corrupted

Symptomps:

  • MiaRec responses to the INVITE message with the error "400 BadRequest".
  • The XML call metadata is not available in the received INVITE message on the MiaRec server side.

This issue may happen when SIPREC traffic is routed through a Cisco ISR router and port 5060 is chosen for SIPREC connection.

By default, Cisco ISR router activates SIP ALG helper for SIP traffic on port 5060. If you use that port, then router will modify SIP messages from Metaswitch CFS. Cisco ISR router doesn't support SIPREC protocol with a multipart body content and it simply removes SIPREC XML call metadata from the INVITE message by mistake. The simplest solution is to choose a non-standard port for SIPREC connection, for example, 5080. Cisco router activates SIP ALG only for traffic on port 5060. Alternatively, you can disable SIP ALG in Cisco ISR router.

MiaRec configuration for Metaswitch call recording

1. Configure SIPREC recording interface

In MiaRec web portal navigate to Administration -> System -> Recording interfaces.

  • Enable "SIPREC" recording interface
  • Disable all other recording interfaces if you do not use them

Recording interfaces

Click on Configure link for SIPREC interface.

  • Check Enable SIPREC recording
  • Change parameters Signaling UDP port and Signaling TCP port according to the port configuration in Metaswitch SBC. By default MiaRec is listening on port 5080 for both TCP and UDP signaling data.
  • If MiaRec server is located behind NAT, then specify Public Ip-address which is used by Metaswitch SBC to establish SIPREC connection. Make sure that port forwarding is configured properly on your NAT router. If MiaRec server and Metaswitch SBC are in the same network, then leave this parameter empty.
  • If necessary, change default values of UDP port range for RTP media packets. Edit parameters Begin RTP port range and End RTP port range. Make sure that the port range is large enough for anticipated number of concurrently recorded calls. One concurrent call requires one UDP port for single media stream recording and two UDP ports for dual media stream recording.

Make sure that firewall is configured properly and inbound connections on SIP signaling and RTP ports are permitted. See Firewall configuration

SIPREC interface

2. Configure multi-tenancy and extension settings

Navigate in MiaRec web portal to Administration -> System -> Advanced Settings.

  1. Check Enable multi-tenancy option.

    See also Understanding multi-tenancy

  2. Set Extension is ... to Metaswitch extension. This setting will allow to associate "MiaRec extension" to "Metaswitch user's extension". MiaRec matches call recordings to users based on extension.

Extension is Metaswitch extension

3. Create new tenant (customer)

Navigate in MiaRec web portal to Administration -> User management -> Tenants and click Add Tenant.

  • Set tenant name
  • Allocate licenses for this tenant

Add tenant

4. Create/edit role permissions

MiaRec supports role-based access control with granular permissions. You can create such roles as administrator, supervisor, agent, etc. See Understanding roles and permissions

5. Create users for web-access

Check also Automatic user provisioning

Inside Tenant account select Users tab and click Add user.

Add user

In Web access settings section specify Login and Password for this user.

Add user

Automatic user provisioning

MiaRec supports automatic provisioning of users based on call metadata information received in SIPREC message. If MiaRec receives call recording for unknown extension, then it can use call metadata from SIPREC message to automatically create user account within particular tenant account. Alternatively, you can create user accounts manually in MiaRec web portal.

Add tenant

In order to enable such functionality, it is necessary to configure Metaswitch System Name and Metaswitch Business Group for the tenant account. If such settings are specified, then MiaRec will associate call recordings with this tenant only when they match to System/Group name.

When Auto-provision users is enabled, then you can specify which default role will be assigned to newly created users and which group they will be placed in.

Add tenant

User authentication using Metaswitch CommPortal

MiaRec supports integration with Metaswitch CommPortal. The latter can be used to verify users' credentials. This means that the same login and password may be used for both CommPortal and MiaRec web portals.

Metaswitch CommPortal integration

Navigate to Administration -> User Authentication -> Metaswitch CommPortal Authentication and specify the CommPortal URL. You can optionally provide a test account/password and verify connection to CommPortal.

Metaswitch CommPortal integration

After that on each user's profile you need to change Authentication with to Metaswitch CommPortal.

Metaswitch CommPortal integration

Recording announcement service for Cisco

Overview

MiaRec has implemented a unique solution for automatic recording announcement for any call scenario on Cisco platform. Such scenarios include both inbound and outbound calls.

The uniqueness of such solution is that it supports outbound call scenarios, which are normally not routed trough IVR system. With MiaRec solution, the customers will hear pre-recorded announcement at the beginning of conversation. Configuration is very flexible and allows to exclude some call scenarios from automatic announcement playback. For example, when agent makes outgoing call to another agent, then announcement could be avoided.

The announcement message is recorded into audio file together with a conversation, which serves as a proof that both parties have been notified about recording.

How it works

The following diagram describes outbound call flow scenario, but it is valid for inbound call scenario as well.

  • MiaRec application monitors call events using TAPI interface to Cisco Unified Communications Manager.
  • When agent makes new call to customer (1), the Cisco UCM notifies MiaRec application about new call via TAPI (2).
  • Call recording is implemented using Cisco active recording method (Built-in-Bridge) shown on diagram as (3).
  • When call recording begins, MiaRec application sends a command to CUCM to play recording notification into communication channel (4).
  • Both agent and customer hear such notification.

Cisco recording announcement architecture

Requirements

  • Cisco UCM version 8.5.1 or newer (1)
  • Cisco IP phones supporting Built-in-Bridge (2)
  • TAPI interface to Cisco UCM

Notes:

  1. In order to implement recording announcement, MiaRec application uses Agent Greeting feature of Cisco Unified Communications Manager, which is available starting from version 8.5.1

  2. Built-in-Bridge feature is required in order to be able to play recording announcement into established communication channel

When recording announcement is played back

MiaRec plays recording announcement as a result of one of two events:

  • When call is connected
  • When recording is started

In the first case, a recording announcement will always be played back even if the call is not recorded. In the second case, a recording announcement will be played back only if such call is actually recorded. If recording is disabled for agent, then no announcement will be played back.

What scenarios are supported

MiaRec may play recording announcement for all possible call scenarios that involve Cisco IP Phone.

Additionally, MiaRec supports flexible filters, that allow exclusion of some call scenarios from recording announcement. For example, internal calls between agents usually do not require announcement.

Installation guide

MiaRec recording announcement solution for Cisco UCM consists of multiple components:

  • Controller. The controller application monitors call events and initiates playback of greeting when the pre-configured conditions match.
  • Player. The playe application is presented as a SIP Trunk in CUCM environment. It plays back the pre-recorded greeting message into the call session.
  • Recorder. The MiaRec recorder component records calls using Built-in-Bridge interface

Cisco recording announcement architecture

This guide describes configuration of the Controller and Player components.

Player - Configuration

The configuration of MiaRec recording announcement player is stored in text INI file SipPlayer.ini.

Section [Main]

Example of configuration:

[Main]

AudioFile=call-maybe-recorded.wav

AudioFile16KHz=call-maybe-recorded-16KHz.wav
  • Set AudioFile to the pre-recorded audio file for announcement message, something like "This call may be recorded". MiaRec comes with a sample audio file. You can use the sample file or record your own. The file format: mono, 8KHz, wav uncompressed.

  • Option AudioFile16KHz is similar to AudioFile, but for calls using high quality wideband codecs (G.722). The file format: mono, 16KHz, wav uncompressed.

Section [SIP]

The recording announcement player behaves as an auto-answering machine. It listens for inbound SIP connection from Cisco UCM, answers the call, plays back the announcement message and automatically hangs up. In the latter sections you will configure SIP Trunk in CUCM for player component.

In this section, you need to configure various SIP parameters for the player.

[SIP]

PortUDP=5060
PortTCP=5060

PortRtpMin = 30000
PortRtpMax = 31999
  • Options PortUDP and PortTCP specify the listening ports for SIP interface for UDP and TCP protocols respectively. Normally, TCP is used for SIP Trunk in CUCM environment. So, you only need to use PortTCP. Other protocol may be disabled by setting its value to 0. If a firewall is enabled, then you need to add these ports to the allowed list.

  • Options PortRtpMin and PortRtpMax specify the UDP port range for RTP packets. If a firewall is enabled, then you need to add this port range to the allowed list.

CUCM - SIP profile

Use the Device > Device Settings > SIP Profile menu option in Cisco Unified Communications Manager Administration to create SIP profile for MiaRec recording announcement player.

The following figure illustrates creating a SIP profile for the recorder.

Create SIP profile for recorder

CUCM - SIP Trunk Security Profile

Use the System > Security > SIP Trunk Security Profile menu option in Cisco Unified Communications Manager Administration to create SIP Trunk Security profile for MiaRec recording announcement player.

  • Set Incoming Transport Type to TCP+UDP.
  • Set Outgoing Transport Type to TCP (this setting has to match the configuration of MiaRec). TCP is recommended.
  • Uncheck option Enable Digest Authentication
  • Set Device Security Mode parameter to Non Secure.

Create SIP Trunk Security Profile

CUCM - SIP Trunk

Use the Device > Trunk menu option in Cisco Unified Communications Manager Administration to create SIP trunk that points to the MiaRec announcement player.

  • Set Device Pool to the same pool as used for phones themselves
  • Set Calling Search Space to the CSS that contains the user phones

In SIP Information section configure:

  • Destination Address should point to ip-address or DNS name of the MiaRec announcement player
  • Destination Port should match the port on which MiaRec announcement player is listening for messages from CUCM
  • Select the previously created SIP Trunk Security Profile for the announcement player
  • Select the previously created SIP Profile for the announcement player

Create SIP Trunk

CUCM - Route pattern

Use the Call Routing > Route/Hunt > Route Pattern menu option in Cisco Unified Communications Manager Administration to create a route pattern for the MiaRec announcement player SIP trunk:

  • Route Pattern should match to the directory number associated with MiaRec announcement player. This DN is used to reach the SIP Trunk of MiaRec announcement player. The latter will automatically answer incoming calls made to this DN and playback the recording announcement player. No user is going to directly call this number manually. Make sure it does not collide with your numbering plan. This is why the example shows '7777'.

  • Set Route partition to the partition that includes the user phones.

  • In Gateway/Route List select the SIP trunk that points to the announcement player

Reoute Pattern Configuration

Verify SIP Trunk configuration

If the MiaRec announcement player is running, then you should be able to dial from your phone the configured directory number (7777 in above example). You should hear the announcement message and then the call should hanghup automatically.

In the next steps, you will configure the controller component, which will automatically route calls to this directory number based on varios criteria, like "outbound only" or "matching phone prefix", etc.

CUCM - Built-in-Bridge (system level)

Built-in-Bridge setting can be enabled on per-phone basis or on system level (default to all phones).

Access the System > Service Parameters menu option in Cisco Unified Communications Manager Administration, select your CUCM server from the Server list and Cisco CallManager from the Service list:

Service Parameter Configuration

To enable Built-in-Bridge on system level change the option Clusterwide Parameters (Device - Phone) -> Builtin Bridge Enable to On:

Clusterwide Builtin Bridge Enable

CUCM - TAPI user

You must first create the application user who is capable of monitoring and controlling phones.

Navigate in Cisco Unified CM Administration web portal to the menu User Management -> Application User and click Add New button to create new user account.

Add application user

In the list Available Devices select the devices, which state should be monitored by MiaRec announcement controller and click arrow V to move such devices to the list Controlled Devices.

In case of Extension Mobility, you can use CTI Controlled Device Profiles instead of Controlled Devices list.

Add application user

In the section Permissions Information click the Add to Access Control Group button to select permissions for application user.

Add application user

In the new pop-up window select the following required options:

  • Standard CTI Allow Control of All Devices
  • Standard CTI Allow Control of Phones supporting Connected Xfer and conf
  • Standard CTI Allow Control of Phones supporting Rollover Mode
  • Standard CTI Enabled

Other options are not required.

Add application user

Save the settings of new application user.

Controller - Cisco TAPI TSP driver

The Cisco TAPI Service Provider (TSP) is a TAPI driver that is installed on the Windows server that allows communication of line events between MiaRec recording announcement controller and the Cisco UCM.

Download the TAPI driver

The installer for the client can be obtained from the Cisco Unified CM Administration portal using the following steps:

  1. Open Cisco Unified CM Administration portal in a web browser and log in with an administrator account.

  2. Once logged in, hover over the Application menu across the top of the site, and click the Plugins link.

  3. On the Find and List Plugins page, enter "Cisco TAPI" into the search field and click Find.

  4. The plugin list will load. Click the Download link on either 32-bit or 64-bit client depending on your operating system.

Download Cisco TAPI driver

Install the TAPI driver

Open the CiscoTSP.exe installer and follow instructions on screen. You will be asked for Cisco CallManager address and application user/password as created in previous steps.

Restart operating system is required after installation of Cisco TAPI driver.

[Optional] Modify Cisco TAPI configuration

To modify Cisco TAPI driver configuration use CiscoConfig.exe utility, which is installed with TAPI driver.

Start this utility and click Configure button.

Configure Cisco TAPI driver

The following screenshots demonstrate example of configuration.

Configure Cisco TAPI driver

Configure Cisco TAPI driver

Controller - Verify TAPI configuration

To verify the TSP operation on the machine where the TSP is installed, use the Microsoft Windows Phone Dialer Application.

Windows Phone Dialer

When the program is run, a dialog box displays that asks which line and address the user wants to use to connect. If there are no lines in the Line drop down list, then a problem may exist between the TSP and the Cisco Unified Communications Manager.

If lines are available, choose one of the lines, keep the Address set to zero (0) and click OK. Enter a Number to dial, and a call should be placed to that number.

If call is successful, you know that the TSP is operational on the machine where the TSP is installed. If problems are encountered with installation and setup of Remote TSP, this test represents a good way to verify whether the TSP is operating properly and that the problem is with the configuration and setup of Remote TSP.

Enable trace in Cisco TAPI driver.

Start CiscoConfig.exe utility and click the Trace tab.

Select Trace On check box and select:

  • TSP Trace to trace the TSP internal messages.
  • CTI Trace to trace the messages sent between CTI and TSP.
  • TSPI Trace to trace the requests and events that are sent between TSP and TAPI.

Select Error to just log errors in the TSP or Detailed to log internal messages for debugging purposes.

Set up a Directory that is the path for the trace log. For example, C:\CiscoTapiLog

No. of Files: Setting this to a value greater than or equal to 1 enables rolling log files. For example, a value of 10 will cause up to 10 log files to be used in a cyclic fashion. Max lines/file: specifies the maximum number of trace statements that will be written to each log file. For example, a value of 1000 will cause up to 1000 trace statements to be written to each log file.

Cisco TAPI Trace config

After Trace is enabled in Cisco TAPI driver, start the TAPI application (for example, Windows Phone Dialer) and then examine logs.

Controller - Configuration

The configuration of MiaRec recording announcement controller is stored in text INI file.

Section [Filters]

MiaRec supports selective recording announcement using advanced filters. For example, you can activate recording announcement only for outbound calls. Or only for calls matching particular phone prefix, etc.

The following section illustrates some of examples:

##############
[Filters]
##############

; ------------------------
; Example 1
; Play recording announcement for extension 203
; ------------------------
filter1 condition = caller-number = 203 OR called-number = 203
filter1 action = play

; ------------------------
; Example 2
; Play recording announcement for all calls between 2xx and 2xx
; ------------------------
filter2 condition = caller-number LIKE '2__' AND called-number = LIKE '2__'
filter2 action = play

; ------------------------
; Example 3
; Ignore all calls, where caller extension is 3 digits
; ------------------------
filter3 condition = caller-number LIKE '___'
filter3 action = ignore

default_action = play

User management

Understanding user roles and permissions

MiaRec software provides role-based access control feature with granular permissions. Each user account is associated with one role. And each role is configured with a set of permissions.

UserPermissions

Each role is associated with a set of permissions, which are granted to users of this role. Permissions include such privileges like "Configure System", "Configure Users", "Playback calls", "Delete calls" etc.

RolePermissions

By default the following roles are pre-created in MiaRec system, but administrator may create new roles or modify existing ones:

Root Administrator

Users of this role have unlimited access to system.

Administrator

Users of this role have a set of permissions as configured by Root Administrator. By default users of type Administrator can create/edit other user accounts.

Supervisor

Supervisor has access to call recordings, which are associated with users in his/her managed group(s). They cannot create/edit other user accounts.

Agent

Agents have access to own call recordings only.

Roles

Each user in MiaRec system should be assigned a role. The role defines what system resources are accessible by user and what operations are permitted on these resources.

List of roles

Navigate menu Administration -> Users Management -> Roles to see a list of available roles. During installation MiaRec automatically pre-creates a few roles. Administrator may create new roles or modify existing ones.

Role Access Level

Configure access scope

Access scope setting specifies which resources are accessible by user of such role.

Role Access Level

Access scope Description
SUPERUSER User with such role has unrestricted access to the system.
System User with such role has access to all resources on the system (users, groups, calls), but the operations are restricted by permissions. One exception from this rule is when multi-tenancy is enabled and user belongs to particular tenant account. In this case access is limited to tenant resources only.
Managed Groups User with such role has access only to resources within the managed groups. A list of managed groups is configured in user's profile. The group manager may see only users and their calls, for which he/she is a manager. Other users/calls are not visible to group manager.
User User with such role has access only to own call recordings.

Configure permissions

Permissions setting specifies what operations are permitted on the accessible resources. These operations include view, edit, delete, playback etc.

Role Permissionsl

Groups

Each user should belong to one of groups. Most of users are just members of their group, but some of users may be managers of groups. A single user may be a manager of multiple groups at the same time.

List of groups

Navigate menu Administration -> Users Management -> Groups to see a list of available groups. During installation MiaRec automatically pre-creates a few sample groups. Administrator may create new groups or edit existing ones.

Group List

View group

The group's profile page displays a list of all users, who are member of this group.

Group View

Edit group settings

Configuration of group includes the following options:

  • Group name
  • Timezone, which will be used by default for each user in this group. The timezone setting may be overridden on user's profile page.

Group Edit

Users

List of users

Navigate menu Administration -> Users Management -> Users to see a list of users. You can search users by name, group, role or extension.

Users List

View user

User's profile page

Add/edit user

Add/Edit User

Managed groups

If the user's role has access level "Group Manager", then you can configure which groups are managed by this user. The group manager has access only to users and their calls recordings, which belong to his managed groups. You may select one or more managed groups from a list.

Configure Managed Groups

Recording settings

If it is necessary to record such user, then you need to specify which extensions are assigned to this user. MiaRec uses the extensions configuration to automatically associate call recordings with users. One user may have more than one extension.

Configure Recording

Web access settings

If the user needs access to MiaRec web portal, then administrator may create login for him/her.

Configure Web Access

Associating calls with users

MiaRec automatically associates calls to users based on user's extension.

User with extension data

Administrator should configure extension on user's profile page. In below screenshot user "Roland Corry" is configured with extension "21311005005". When MiaRec recognizes a call with extension "21311005005", then such call is automatically associated with user "Roland Corry".

Such call association allows quick filtering of calls by user name. Also, this information is used when granting access to recordings. For example, supervisor will be able to view only call recordings, which are associated with users in his/her group.

User with extension data

What happens when MiaRec records call with unknown extension?

If MiaRec doesn't recognize extension for newly recorded call, then a default recording rule applies for the call. By default, MiaRec is configured to record such unknown calls, but this behavior may be changed by administrator (see section [Filters::OnCallStart] inside configuration file MiaRec.ini).

When call with unknown extension is recorded, then the column "User" will be empty (as shown in below screenshot).

User with extension data

Also, these calls are shown in panel "Not assigned to users" (visible only to administrators).

User with extension data

Administrator can manually assign the call to one of existing users. First, he needs to click on a call to display call details. Then he needs to click on button "Assign to user".

User with extension data

New page will be opened with the following options:

Extension

Administrator should decide whether to use phone number or optional phone name to associate calls to users.

Assign to User

The user to associate this call with.

Apply this rule to all similar calls

When checked, then other calls with the same extension will be automatically assigned to this user. Note, MiaRec will search only calls, which are not assigned yet to any of users.

User with extension data

Upon clicking the on "Save" button the recorded calls will be searched and automatically assigned to the selected user. Additionally, the selected extension will be automatically added to user (as shown in below screenshot).

User with extension data

Configuring LDAP integration

MiaRec supports LDAP (Active Directory) integration to accomplish two tasks:

  • LDAP authentication
  • LDAP user synchronization

LDAP authentication

Navigate to Administration -> System Configuration -> LDAP Integration to configure LDAP autentication.

LDAP integration

How it works

When user tries to login to MiaRec web portal, his/her login and password is verified on LDAP server. If login and password are accepted by LDAP server, then user is allowed to login to MiaRec web portal.

Such feature allows to manage users' passwords in one location only (on your LDAP server). MiaRec doesn't store user's passwords in own database in this scenario. If user's password is changed in LDAP server, then MiaRec will automatically accept such new password during login phase. Also, when user account is removed/deactivated in LDAP server, then such user will not be able to login to MiaRec web-portal too.

Please, note, MiaRec doesn't accept automatically login from any LDAP user in your system. It is required that user account has been previously created in MiaRec and appropriate access permissions have been granted to user. On user's profile page administrator may specify whether user's password should be stored locally (in encrypted one-way hash form) or LDAP authentication is enabled for such user.

LDAP user synchronization

When LDAP user synchronization is enabled, then MiaRec will automatically scan LDAP directory for new user accounts and create MiaRec users.

LDAP integration

How it works

First you need to create LDAP user synchronization job. This job may be started manually or by schedule (for example, every night).

If MiaRec detects new user account in LDAP server, then during synchronization the same account will be created in MiaRec. This newly created user will be added into pre-configured default user group and a default role will be assigned to user.

If LDAP database contains phone number for users, then such phone number will be automatically added as an extension to user.

When phone number is updated in LDAP server, then during synchronization such change will be applied to MiaRec user record also. For, example, when phone number in LDAP server is moved from one user to another, then MiaRec will move corresponding extension to new user too.

When phone number is removed from LDAP user account, but the same phone number is not assigned to any other users, then MiaRec will do nothing during synchronization. The extension will not be removed from user account. This is by design. It allows you to add extensions to MiaRec users manually on his/her profile page, and such manually created extensions will not be removed during synchronization if your LDAP server is missing phone number info.

Storage management

Audio settings

Navigate to Administration -> System Configuration -> Audio Settings to change audio format (stereo/mono), MP3 bitrate and other settings.

Audio settings

Backup and restore

Backup call recordings

Navigate to Administration -> Storage -> Export Recordings to create backup job. In version before March 2016, navigate to menu Administration -> Maintenance -> Backup Calls.

Backup job may be started manually or by schedule (for example, every night/week etc).

MiaRec Backup

Export to FTP server:

Export to FTP

Restore call recordings

Navigate to Administration -> Storage -> Import Recordings to create job. In version before March 2016, navigate to menu Administration -> Maintenance -> Restore Calls

Import calls

In "Edit Call Import Job" form specify the location of backup files and click on "Import now" button.

Import calls

Additional steps in case the backup files are located on network share

It is important to note, that backup files will be accessed by a program application running on MiaRec server rather than from the computer on which you open MiaRec web portal. This means that even if you can access backup files from your own computer, the same files may be unaccessible from MiaRec server.

If backup files are stored on a network share, then on Windows servers you should use correct UNC path like \server\dir, on Linux servers you should mount the network share to a local file system, for example, /mount/backup.

When using UNC path on Windows, take into account that such path will accessed by a process running as a Windows service application. By default service applications are running under credentials of LOCAL_SYSTEM user account. This is internal user account, which has no access to network. To solve this issue, you would need to change parameters of "MiaRec Celery" service and run it under credentials of some user account, which can access the backup network share.

The process of call importing will be started and the progress will be displayed on web-page.

Import calls

Location for audio files

Navigate to Administration -> System Configuration -> Storage to view/edit location of audio files and filename format.

MiaRec Storage Settings

Click on Edit Configuration to modify settings.

MiaRec Storage Settings

Audio File Name Format is a parametrized format of audio file name. This is very powerful way of configuring audio files location. Parameters are described in details in article File name format.

File name format

MiaRec supports flexible naming of audio files. It is possible to include date/time, ip-address, phone number and other call parameters into file name.

Example:

C:\Recordings\%{setup-time#%Y%m%d}\%{setup-time#%Y-%m-%d-%H%M%S}.mp3

In above example audio files are stored inside directory C:\Recordings\.

For each day a new sub-directory is created (for example, C:\Recordings\20110203\ for 3rd of February 2011). This is done with the help of parametrized string %{setup-time#%Y%m%d}, which is converted to date (read details about parametrized strings below).

The file name consists of a date and time of when a call is started, for example, 20110203104522.mp3.

If two or more calls are started at the same time, then MiaRec appends a unique number at the end of file name, for example, 20110203104522_2.mp3, 20110203104522_3.mp3 etc.

Parameters have the following format:

%{parameter-name} or
%{parameter-name#format-string}

where:

  • parameter-name is a name of call parameter (see Table 1)
  • #format-string is an optional format of call parameter (see Time formatting).

Examples:

  • %{caller-number}
  • %{setup-time#%Y%m%d}

Table 1. Supported parameters inside file path

ParameterDescription
%{call-id}Unique id of a call, which is assigned to each recorded call by MiaRec
%{parent-call-id}Id of a call, which is a parent to the current call. The meaning of this parameter depends on particular voip protocol. For example, for Avaya H.323 protocol, when call is put on hold and then retrieved from hold, the new audio file will be created. In this case %{parent-call-id} points to the very first call part.
%{protocol-call-id}

Id of a call, which is assigned by IP PBX.

This value is valid only for supported voip protocol (SIP, Skinny, H.323 and MGCP).

For example, for SIP protocol this value is retrieved from header "Call-ID" inside SIP INVITE message.

%{call-state}

Phase (state) of the call. It is a numeric value, one of:

  • 0 - Idle
  • 1 - Initiated. The first phase of a call: the caller sent invitation to the callee
  • 2 - Accepted. The callee received invitation and confirmed this
  • 3 - Alerting. The callee started ringing
  • 4 - Connected. The call was answered
  • 5 - Disconnecting. The call was initiated for disconnecting by one of  parties
  • 6 - Disconnected. The call was completed (disconnected)
  • 7 - Hold. The call was put on Hold
  • 8 - Transferred. The call was transferred to the third party
  • 9 - Deleted. The call was deleted from disk (see Recording filters)
%{record-state}

State of the audio recording. It is a numeric value, one of:

  • 10 - Active. Call is active at the moment and recording is in progress
  • 20 - Partial recording. Recording of call was stopped because of not enough licenses
  • 30 - Finished. Call is finished. Audio was recorded in full
  • 40 - Ignored. Call is ignored by recording filters.
%{voip-protocol}

Voip protocol of the call. It is a numeric value, one of:

  • 0 – Unknown (not recognized protocol). Call is recorded from RTP packets
  • 1 - SIP
  • 2 - H.323
  • 4 - SCCP (Cisco Skinny)
  • 5 - MGCP
  • 6 - Avaya (H.323 protocol with proprietary extensions)
  • 7 - Nortel UNISTIM
  • 8 - TAPI 
  • 9 - MGCP PRI Backhaul (it is used between Cisco CCM and Voice Gateway)
  • 10 - Alcatel (proprietary protocol used by Alcatel OmniPCX)
%{setup-time}
Time when call was established (when a called party received incoming call message). See Time formatting
%{alerting-time}
Time when phone started ringing on called party side. See Time formatting
%{connect-time}
Time when call was answered. See Time formatting
%{disconnect-time}
Time when call was disconnected. See Time formatting
%{duration}
Duration of voice part of a call in seconds. This is a difference beween %{connect-time} and %{disconnect-time}
%{total-duration}Total duration of a call in seconds. This is a difference beween %{setup-time} and %{disconnect-time}
%{filename}Name of audio file without full path (for example, 20110410104600.mp3)
%{filename-full}Full path to the file, including directory (for example, C:\Recordings\20110410104600.mp3)
%{filename-dir}Directory path to the file, excluding drive letter (for example, \Recordings\)

%{caller-number} or

%{callee-number}

Phone number of caller/callee

%{caller-name} or

%{callee-name}

Name of caller/callee. This parameter is protocol-dependent. For example, for SIP protocol name is extracted from "From" and "To" sip headers

%{caller-id} or

%{callee-id}

Id of a caller/callee. This paramter is protocol-dependent. For example, for SIP protocol it is SIP URI

%{caller-ip} or

%{callee-ip}

Ip-address of caller/callee

%{caller-port} or

%{callee-port}

Port of caller/callee

%{caller-mac} or

%{callee-mac}

Mac-address of caller/callee

%{transfer-from-number}

%{transfer-from-name}

%{transfer-from-id}

Name, number and id of party, from which the call was transferred. This parameter is available only for Skinny protocol.

%{transfer-to-number}

%{transfer-to-name}

%{transfer-to-id}

Name, number and id of party, to which the call was transferred. This parameter is available only for Skinny protocol.
%{sip-header-invite}

Value of specific SIP header inside INVITE message. The name of header is specified after hash (#) symbol.

Examples:

  • %{sip-header-invite#User-Agent}
  • %{sip-header-invite#X-My-header}
%{BroadWorks-userID}

Broadworks User ID

%{BroadWorks-groupID}

Broadwors Group ID

%{BroadWorks-serviceProviderID}

Broadworks Service Provider ID

%{MetaSwitch-recorderParty}Metaswitch CFS User Extension
%{MetaSwitch-userName}Metaswitch CFS User Name
%{MetaSwitch-businessGroup}Metaswitch CFS Business Group Name
%{MetaSwitch-systemName}Metaswitch CFS System Name
%{agent-id}Avaya Agent ID
%{agent-name}Avaya Agent Name
%{orig-caller-number}Originally Caller Number (if different from caller-number)
%{orig-caller-name}Originally Caller Name (if different from caller-name)
%{orig-callee-number}Originally Dialed Number (if different from callee-number)
%{orig-callee-name}Originally Dialed Name (if different from callee-name)

Example 1

C:\Recordings\%{setup-time#%Y%m%d%H%M%S}.mp3

%{setup-time#%Y%m%d%H%M%S} will be replaced with a date and time of when a call was started. For example, if a call was started on 1st of May 2007 at 10:56:34, it will be stored into directory ‘C:\Recordings’ with the filename ‘20070501105634.mp3’.

Note: If two or more calls were started at the same time, a unique decimal suffix will be added to every file name (expect the first one), like: ‘20070501105634_2.mp3’, ‘20070501105634_3.mp3’ etc.

Example 2

C:\Recordings\%{setup-time#%Y%m%d}\File.mp3

This example contains a parameterized string inside a directory path. This means that files will be stored into sub-directories with name %{setup-time#%Y%m%d} (which will be replaced by a date of a call, for example, ‘20070501’). If such directory doesn’t exist, it will be created automatically.

In this example calls will be grouped into directories by date, like:

Directories structure

For every new day a separate directory will be created (a directory is not created if no calls were recorded at that day).

Audio file names in this example will be File.mp3, File_2.mp3, File_3.mp3 and so on.

Example 3

C:\Recordings\%{caller-ip}\File.mp3


%{caller-ip} will be replaced with ip-address of a caller, for example 192.168.0.1.

Calls will be grouped into directories by caller ip-address, like:

Directories structure

Example 4

C:\Recordings\%{setup-time#%Y%m}\%{setup-time#%d}\%{caller-ip}\File.mp3

In this example multiple parameter replacements occur:

  • %{setup-time#%Y%m} will be replaced with a year and month of a call (YYYYMM). For 1st of May 2007 it will be 200705.
  • %{setup-time#%d} will be replaced with a day of a call (DD). For 1st of May 2007 it will be 01. 
  • %{caller-ip} will be replaced with an ip-address of a caller, for example 192.168.0.1.

Calls will be grouped into directories by months, then by days and then by callers' ip-addresses, like:

Directories structure

Read also:

Time formatting inside file name

All date/time parameters support a formatting attribute. Formatting attribute is specified after hash (#) symbol.

For example:

  • %{setup-time#%Y} will return year, like: 2011
  • %{setup-time#%m} will return month, like: 02
  • %{setup-time#%Y-%m} will return both year and month, like: 2011-02

Table 1. Formatting codes

CodeDescription
%aAbbreviated weekday name
%A Full weekday name
%bAbbreviated month name
%BFull month name
%dDay of month as decimal number (01 – 31)
%HHour in 24-hour format (00 – 23)
%IHour in 12-hour format (01 – 12)
%jDay of year as decimal number (001 – 366)
%mMonth as decimal number (01 – 12)
%MMinute as decimal number (00 – 59)
%pA.M./P.M. indicator for 12-hour clock
%SSecond as decimal number (00 – 59)
%UWeek of year as decimal number, with Sunday as first day of week (00 – 53)
%wWeekday as decimal number (0 – 6; Sunday is 0)
%WWeek of year as decimal number, with Monday as first day of week (00 – 53)
%yYear without century, as decimal number (00 – 99)
%YYear with century, as decimal number
%%Percent sign
%uMicroseconds as decimal number

 

Table 2. Examples of time formatting

Format stringResult
%Y-%m-%d2004-11-10
%H%M%S160201
%I%M%S040201
%d %b %Y, %A10 Nov 2004, Wednesday

Note, for all examples, we used the same date/time, which is “10th of November 2004 16:02:01”. This day is a Wednesday.

Read also:

Replication

MiaRec multi-master asynchronous replication

MiaRec solution implements data replication with the following characteristics:

  • Multi-master
  • One-way, two-way or N-way
  • Asynchronous
  • Application-level
  • GEO distributed
  • Continuous, manual or scheduled
  • Auto resume after network breakdown

This articles describes in details each of these characteristics and compares MiaRec solution with alternatives. The competitive solutions are built usually on file-storage based replication and have a number of weaknesses discussed below.

How it works

When recording of each individual call is completed, MiaRec pushes it into queue for automatic replication to other server(s) in a cluster. Such data replication may be started immediately upon call completion or scheduled to specific time of day (for example, at night).

Besides replication of call recordings, MiaRec replicates also user data in one-way or two-way directions. The updates to user data is automatically uploaded to other servers in a cluster.

Multi-master asynchronous replication

Replication architecture of MiaRec has the following characteristics:

  • Multi-master. Any of servers in a cluster can be used for recording tasks at any time. It is possible to use multiple recorders simultaneously for load balancing purposes.

  • Asynchronous replication. Data is replicated asynchronously. Data synchronization can be triggered by schedule (once per hour/day/week) or continuously upon each individual call completion. It works seamlessly in GEO-redundant architecture when datacenters are located too far from each other. In a contrast, other solution may use synchronous replication, which require low latency (less than 5ms) connection between datacenters, this is equal to maximum 100km distance between servers. With a synchronous replication, if a link between datacenters is down even for 1 second, the redundant server is removed from a cluster and manual re-synchronization is required between servers. Automatic restore of cluster is not possible by design with synchronous replication.

  • Application-level replication. MiaRec implements replication internally on application level. It has a few advantages: cost, easy management and selective replication. In a contrast, other solutions may use replication on database level or disk level (SAN). SAN replication is supported only in highly expensive enterprise SAN disk arrays. In both of these competitive solusions (database replication and SAN replication) the selective replication is not supported.

Multi-master vs master-slave replication

Multi-master replication (MiaRec) Master-slave replication (other vendors)
All servers run as master servers, thus you can record calls on any of servers at any time or even simultaneously to multiple servers.

This makes system highly flexible in a way that any operation can be processed in any server which enables better load balancing.

However, such flexibility brings the challenge of keeping servers consistent. A conflict occurs if more than one server tries to update the same object. In MiaRec we solved this issue with the following mechanisms:

  1. Careful design of database structure from scratch to address unique redundancy requirements. We do not use integer auto-incremental fields for IDs. Instead we use UUID all over the database to guarantee uniqueness through multiple servers.

  2. Replication is implemented on application level instead of database engine or disk-level. More about this later.

In master-slave replication, there is only one server in the system which is capable of recording data. All other replicating servers are called slaves and can only accept read-only requests.

In master-slave replication, the master server becomes overwhelmed and system suffers from scalability due to using a single server for write operations (call recording).

Setup of automatic fail-over mechanism can be tricky. When master server becomes unavailable, one of the slaves can be promoted as a master. When the master server is back, it usually stays in off-line mode and requires manual re-synchronization of servers to assure data consistency. Such synchronization process is quote time consuming and it is recommended to have at least 3 servers in a cluster (1 master and 2 slaves) in order to avoid single point of failure situations while master server is in off-line mode.

If such configuration is used in GEO-redundant setup, it may create too much burden to administration staff in case of frequent issues with connection between datacenters.

Asynchronous vs synchronous replication

Asynchronous replication (MiaRec) Synchronous replication (other vendors)
In asynchronous replication, an incoming request is processed and get committed on the receiving server without propagating it to other replicating servers simultaneously. Instead, committed request are deferred and sent to all other replicating servers asynchronously. Once replicating servers receive these deferred request, they process them and make themselves synchronized.

Asynchronous replication utilizes network resources intelligently, creates less traffic, and provides higher performance. Deferring multiple request and propagating them all as a big chunk of requests is much more efficient rather than to propagate each of them separately. Operation latency is reduced as opposed to synchronous replication because a server can go ahead and process a request without need to talk with other servers to commit it. It also provides better scalability since response time of a server is independent from the number of replicating servers, and generated network traffic is proportional to the number of replicating servers. Moveover, network latency introduced due to the geographical distance between replicating servers can be tolerated and hidden since requests are deferred and propagated asynchronously.

Additionally, asynchronous replication can be scheduled to execute during less busy hours, like at night or weekends.

In synchronous replication, incoming requests are propagated to and processed by all replicating servers immediately. The benefits of synchronous replication is to guarantee that data is consistent at all servers at any time.

While propagating requests and synchronizing servers, two-phase commit protocol is used. When a request comes in a sever, the same request is also forwarded immediately to all replicating servers. All servers have to process incoming request to see if it is OK to be committed, and have to inform the propagating server in this regard. If and only if all replicating servers inform that request can be committed, then second message is propagated to commit the request in all replicating servers. If any replicating server complains about the request, than abort message is propagated and all servers have to disregard the request.

Although it ensures that replicating servers are synchronized immediately when a request is committed and prevent consistencies may occur otherwise, it generates huge network traffic due to high number of sends and receives to decide to commit or abort. It increases processing latency which degrades operation performance since operation has to wait until all replicating servers have been synchronized. Scalability also suffers from increasing number of replicating metadata servers that tend to create exponentially growing network traffic and processing latency that ends up with longer response time.

Synchronous replication is not suitable for GEO-redundancy when distance between datacenters is more than 100km.

Application-level vs Storage array-based replication

Application-level replication (MiaRec) Storage array-based replication (other vendors)
MiaRec replication mechanism is based on knowledge of data. This allows it to selectively replicate only the necessary data. For example, administrator may enable continuous (as soon as possible) replication for call recording data and for the rest of data (like logs) schedule replication during off-hours (at night, for example).

Additionally, it is possible to set filtering criteria for replication. For example, replicate only call recordings of particular tenant(s) or group(s).

Having knowledge of data allows MiaRec application to resolve conflicts intelligently. For example, if the same user record is updated from multiple servers simultaneously, then administrator may decide to resolve conflicts automatically based on priorities or manually.

In a contrast to storage array-based replication (SAN), MiaRec replication mechanism supports any storage, like NAS, local, virtual environment. It doesn’t depend on hardware. It is possible to mix different storage types in the same clustomer, for example, replicate form local or NAS storage to SAN.

MiaRec application-level replication supports multi-master architecture, which is not possible with a storage array-based replication. As a result, utilization of hardware is much better due to using second storage in load balancing configuration. MiaRec supports also replication to multiple servers simultaneously.

Application-level replication is tolerant to temporary problems with a link between replicating servers. In case of problems with a link between datacenters, MiaRec replication process is postponed and automatically resumed when link is restored. No data loss occurs due to in this case.

Storage array-based replication is expensive. Usually it is available only in enterprise SAN disk arrays.

It doesn’t have knowledge of data that is stored on disk. As a result, it is not possible to configure selective replication. You need to replicate an entire SAN or nothing.

Storage array-based replication works only for a pair of SAN arrays of exactly the same vendor/model and size. It is not possible to mix SANs from different vendors or even different models of the same vendor.

SAN replication usually supports both asynchronous and synchronous replication, but the latter is not suitable in GEO-redundant environment because it works only for a distance up to 100km between datacenters.

When using SAN replication in asynchronous mode, it suffers from ineffectiveness of investments. One of SAN-arrays in a pair is used in passive mode most of the time until disaster occurs.

In case of DR, a switch from primary SAN to the secondary usually occurs automatically, but a reverse operation requires the manual intervention of human.

In case of problems with a link between datacenters, data on primary and secondary SAN arrays becomes inconsistent and requires manual re-synchronization, which is very time consuming.

Use cases for replication

MiaRec supports advanced replication mechanism between two or more MiaRec servers.

Such replication may be configured one-way or two-way. MiaRec server may play role of target (recipient) or source (sender) or both roles at the same time.

The following scenarios are supported:

Replication to backup storage

Replication to backup storage

Replication to centralized storage

Replication to centralized storage

Redundant recorder with BroadWorks SIPREC

Broadworks SIPREC redundant recorder

Redundant recorder with Cisco Built-in-Bridge

Cisco Built-in-Bridge redundant recorder

Upload call recordings from service provider to customer network

Upload of recordings to customers

Configuring target server (recipient)

Navigate to Administration -> Storage -> Replication to configure incoming replication token.

Click on Add token button to create secure token for incoming replication. This secure token will be used by sender server to upload data to this the target server.

The same target server may receive data from multiple source server. You will need to create token for each source server.

LDAP integration

For each incoming token you can specify unique location for uploaded audio files. It is recommended to upload audio files from multiple servers to dedicated location. This will allow you to distinguish uploaded call recordings from the locally recorded ones.

LDAP integration

Important! If the target machine is Linux, then you need to make sure that the web server process (Apache) has writing permissions on the the destination directory. For example, if you specified directory /var/miarec/replicated-recordings, then execute the following command:

Centos/RedHat:

chown apache:apache /var/miarec/replicated-recordings

Ubuntu:

chown www-data:www-data /var/miarec/replicated-recordings

Configuring replication server (sender)

Navigate to Administration -> Storage -> Replication on source (sender) replication server to create outgoing replication job.

LDAP integration

Use a secure replication token from a target server, which you create in previous step.

You may create multiple jobs and upload the same recordings to multiple target servers simultaneously.

Each replication job supports filtering criteria to limit which call recordings are uploaded to the target server. For example, you may configure replication for specific group of users only.

Full replication mode will upload all call recordings to target server everytime the job is started. It will gracefully skip upload process if the target server contains such recordings already.

Incremental replication mode remembers which records have been uploaded already to the target server and do not process them on next start. Such mode is useful when job is scheduled for periodic replication (every hour/day etc). It will work a lot faster than full replication mode because it will skip automatically previously uploaded recordings.

Replication job may be started manually or automatically by schedule. Schedule may be configured by time (for example every hour/day/week) or automatic continuous replication. With continuous replication call recordings are uploaded to the target server immediately upon call completion.

LDAP integration

Status of replication job is available on job page. For incremental replication mode MiaRec stores statistics of replicated calls per day.

Retention policy


Navigate to Administration -> Storage -> Retention Policies to add one or more retention policies.

You can create more than one retention policies. For example, one group of users will have retention period 3 years, while other groups will have retention period 7 years.

Click on "New Job" to create a retention policy job.

Retention policy

Inside job settings you can specify call filter criteria for this policy, for example, older than 180 days, limit to particular group of users etc.

Retention job may be started manually or automatically by schedule.

Retention policy

Result of retention job execution are displayed on job web-page.

Retention policy

Customization

Calls list layout

A list of visible columns is configurable.

Calls list layout

Navigate to Administration -> System Configuration -> Calls List Layout to specify which columns are visible.

Calls list layout

Click on Edit button for appropriate list to change visible columns and their orders.

You can drag-and-drop columns to change their order.

Calls list layout

Timezone settings

By default MiaRec uses timezone settings of the server on which is running.

Navigate to Administration -> System Configuration -> Date and Time Formats to change a default timezone value.

This timezone value will be used for all users as a default value. Additionally it is possible to specify unique timezone value for tenant, group or individual user. Navigate to tenant/group/user profile web-page to edit timezone value.

Calls list layout

Translate MiaRec to other language

MiaRec offers internationalization and localization of user interface. If you would like to edit existing translation or create translation for new language, you can use POEdit application or any other application supporting gettext *.po file format.

First, you need to contact MiaRec team and ask for *.po file for your language.

Once you have PO file, open it in POEdit application and translate english phrases to your language. When finished, send the PO file back to MiaRec team for inclusion into distributive.

You need to know a few formats, which are used in MiaRec to represent text:

  1. Text within ${ } brackets should be kept AS IS (not translated). These are placeholders, which will be replaced with appropriate values when displaying in UI. For example, text User ${name} may be displayed in UI as User David

    MiaRec multi-language

  2. Text starring with # (hash) symbol has special meaning. It doesn't not need to be translated word-by-word. It is used to distinguish words, which have the same writing, but different meaning. For example, word "from" may be used together with date value or as label for "caller party". In PO file you will find "# From [date]" and "# From [party]", which are both displayed in English as "From", but in other languages it may require different translations, for example, in Spanish they are translated to "desde" and "Llamador" correspondingly. Pay attention to notes in the right bottom corner of POEdit application.

    MiaRec multi-language

Maintenance

License

Navigate to menu Administration -> System Management -> License.

MiaRec License

Performance Monitoring

Control recording using soft keys on IP phones

Overview - Soft keys on IP phones

MiaRec integrates with various phone models to provide the following features:

  • On-demand recording Users may use their phones to switch on/off recording during an active call.

  • Pause/resume recording Users may use their phones to pause recording for a short period of time. For example, when processing credit card transactions over the phone, a user may pause recording before a customer says the credit card information. Such feature allows to comply with PCI requirements.

The following images display example of integration with Cisco 7900 and Polycom VVX series phones.

MiaRec phone services on Cisco phone

MiaRec phone services on Polycom VVX phone

Configure MiaRec phone services

This guide is for configuring phone services for Polycom VVX and Cisco/Linsys SPA phone models only. If you need to configure Cisco 7900 series phones, please, check the guide here.

MiaRec integrates with Polycom VVX and Cisco SPA series phones to provide the following features:

  • On-demand recording Users may use their phones to switch on/off recording for the current call.

  • Pause/resume recording Users may use their phones to pause recording for short period of time. For example, when processing credit card transactions over the phone, an agent may pause recording before a customer speaks the credit card information. Such features allows to comply with PCI requirements.

The following image shows example of integration with Polycom VVX series phones.

Polycom VVX400 phone:

MiaRec phone services on Polycom VVX phone

Cisco SPA504G phone:

MiaRec phone services on Cisco SPA504G phone

Supported models:

  • Polycom VVX 300, 400, 500, 600, 1500
  • Cisco SPA 300, 500 series

Configurations steps:

  1. Configure MiaRec phone services
  2. Configure "Login" and "PIN" attributes at the user profile
  3. Allow "Phone services" permissions at the role profile.
  4. Configure phone

Configure MiaRec phone services

Navigate in MiaRec web portal to Administration -> System -> Phone Services. Click Edit configuration button to open the settings page (see the following screenshot).

MiaRec Phone Services

Configure "Login" and "PIN" attributes at the user profile

Navigate in MiaRec web portal to Administration -> User Management -> Users and edit the corresponding user profiles. It is necessary to configure unique "Login" for each user. Users will need to provide their Login and PIN when they access the MiaRec services the first time from their phone.

MiaRec Phone Services

Allow "Phone services" permission at the role profile

Navigate in MiaRec web portal to Administration -> User Management -> Roles and edit the corresponding role profile.

MiaRec Phone Services

Configure phone

View active phone registration (sessions)

When user succesfully signs in to MiaRec phone services from his/her phone, the corresponding session is opened by MiaRec. An administrator may see all opened sessions using Web portal. Navigate to Administration -> System -> Phone services and click the link View active phone sessions:

MiaRec Phone Services

An administrator may terminate (delete) any active session from this screen. If the session is deleted, then the user will be required to signin again from his/her phone manually.

MiaRec Phone Services

Integration with Cisco SPA series phones

Cisco SPA series phones could be configured in a few ways:

  • Using phone's built-in web interface
  • Auto-provisioining of phone using HTTP, for example, in Broadworks or Metaswitch environment.

Option 1. Configure phone using built-in web interface

Open phone's built-in web interface and navigate to Administration -> Advanced Settings -> Phone.

  1. Change "Programmable Softkey Enable" to yes

  2. Insert the following text into PSK 1 field (or any other field if PSK 1 is already used).

    fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec
    

    Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

  3. Add psk1|1 to Connected Key List field.

    Before:

    conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;
    

    After:

    psk1|1;conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;
    

    A number after | symbol specifies a position of button (1st in our example). psk1 corresponds to PSK 1 field configured above.

MiaRec Phone Service on Cisco SPA series phone

For more detail about Custom Phone Keys you can check the Cisco Small Business SPA300 Series, SPA500 Series, and WIP310 IP Phone Administration Guide

Option 2. Configure phone using Metaswitch SIP provisioining server

You need to create Endpoint Pack Extension for Metaswitch. You can find the detailed instructions in Metaswitch Community. See the document [Cisco] Creating a Cisco pack extension.

MiaRec Phone Services

File metadata.yaml (example):

ID: cisco_SPA5xx_accredited  
PackVersion: 17  
Version: 1  
Position: End  
TemplatePositions:  
- Template: config.ftl  
  Position: End  

File templates/schema.yaml (example):

group_names:
  CustomParameters:
    display_name:
      default: Custom Parameters

settings:
  - name: custom_MiaRecPhoneServices_Button
    group_name: CustomParameters
    display_name: 
      default: MiaRecPhoneServices_Button
    syntax:
      type: Boolean
    default_value: false

File templates/config.ftl (example):

<flat-profile>  
${logger.log("MiaRec Phone Services soft key")}  
  <Programmable_Softkey_Enable ua="na">Yes</Programmable_Softkey_Enable>  
  <Connected_Key_List ua="na">psk16|1;${profile.AdvConnKeyList}</Connected_Key_List>  
  <PSK_16 ua="na">fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec</PSK_16>  
</flat-profile> 

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

Option 3. Configure phone using generic provisioining server (HTTP-based server)

If you are a service provider and provision phone using Broadworks, Metaswitch or home-grown HTTP based system, then you need to add the following customizations to your Cisco SPA phone configuration template. For more details check Cisco Small Business IP Telephony Devices Provisioning Guide

Example of Plain Text configuration:

Programmable_Softkey_Enable   "Yes" ;

Connected_Key_List                   "psk1|1;conf|3;xfer|4;toggle;bxfer;confLx;xferLx;park;phold;flash;" ;

PSK_1 "fnc=xml;url=http://{MIAREC_WEB_SERVER}/api/phone_services/cisco_spa/calls/active_call?login=$UID1;nme=MiaRec" ;

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and nme=MiaRec a soft key title. $UID1 will be substituted with the first line SIP Auth User ID. It should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users, field Login).

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate the hardware phone

Open in your web browser the same link as you configured in the Polycom configuration file, for example:

https://miarec.example.com/api/phone_services/cisco_spa/calls/active_call?login=123456

You should be able to see XML page like the following:

MiaRec Phone Services

Integration with Polycom VVX series phones

Edit Polycom XML configuration files on your provisioning server

You need to add the following settings to the XML configuration file:

<feature>
    <feature.enhancedFeatureKeys feature.enhancedFeatureKeys.enabled="1">
    </feature.enhancedFeatureKeys>
</feature>

<softkey
  softkey.1.label="MiaRec"
  softkey.1.action="https://{MIAREC_WEB_SERVER}/api/phone_services/polycom/calls/active_call?login={LOGIN}"
  softkey.1.enable="1"
  softkey.1.insert="0"
  softkey.1.precede="1"
  softkey.1.use.active="1"
  softkey.1.use.alerting="0"
  softkey.1.use.dialtone="0"
  softkey.1.use.hold="0"
  softkey.1.use.idle="0"
  softkey.1.use.proceeding="0"
  softkey.1.use.setup="0"
>
</softkey>

Where {MIAREC_WEB_SERVER} is your MiaRec web server address and {LOGIN} is an login of the particular user. Each user should have unique login. The login should match to the correponding configuration of user profile in MiaRec web portal (menu Administration -> User Management -> Users).

Below diagram shows how MiaRec phone services are integrated with Metaswitch platform:

MiaRec Phone Services

Troubleshooting

MiaRec System Log

Navigate in MiaRec web portal to Administration -> Maintenance -> System Log and check if there are any warnings/errors.

Use your web browser to simulate the hardware phone

Open in your web browser the same link as you configured in the Polycom configuration file, for example:

https://miarec.example.com/api/phone_services/polycom/calls/active_call?login=123456

You should be able to login to phone services and see the recording controls.

MiaRec Phone Services

Check Polycom phone logs

By default Polycom phone automatically uploads own log file to the provisioning system using FTP. Check that log file for any errors.

Softkey integration with Cisco 7900 series phones

Overview

MiaRec integrates with Cisco phone services to provide the following features:

  • On-demand recording Agents may use their Cisco phones to switch on/off recording for the current call.

  • Pause/resume recording Agents may use their Cisco phones to pause recording for short period of time. For example, when processing credit card transactions over the phone, an agent may pause recording before a customer says critical credit card information. Such features allows to comply with PCI requirements.

Control MiaRec recording from Cisco softphone

MiaRec phone services on Cisco phone

Control MiaRec recording from Cisco hardware phone

Requirements:

  • Cisco phone with XML phone services support

Create MiaRec IP Phone Service

Open Cisco Unified Communications Manager administration web portal.

  1. Select the Device - Device Settings - Phone Services menu item.

  2. Click on Add New

  3. Type in the Service Name: MiaRec (you may use different name here)

  4. Type in the Service Description: MiaRec Phone Service

  5. Type in the Service URL:

    http://0.0.0.0/cisco_phone_service/active_call?name=#DEVICENAME#
    

    Replace 0.0.0.0 with your MiaRec server ip-address. This URL should point to MiaRec web portal. If the web portal is running on port different from the default 80, then include port into URL, like http://1.2.3.4:8080/cisco_phone_service.... It is recommended to use direct ip-address instead of domain name because name resolution may not work from within Cisco IP phone.

    Alternatively, you can use the following URLs, which allow to control recording in one-click:

    URL Description
    http://0.0.0.0/cisco_phone_service/call/active_call/ondemand/keep?name=#DEVICENAME# Enable recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/ondemand/discard?name=#DEVICENAME# Disable recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/muting/mute?name=#DEVICENAME# Pause recording in one-click
    http://0.0.0.0/cisco_phone_service/call/active_call/muting/unmute?name=#DEVICENAME# Resume recording in one-click
  6. Check Enable option.

  7. Save it.

See below screenshot for details.

Create MiaRec IP Phone Service

Subscribe each phone to MiaRec phone service

Open Cisco Unified Communications Manager administration web portal.

  1. Select the Device - Phone menu item.

  2. Select the desired phone/device.

  3. Select Subscribe/Unsubscribe Services from the "Related links" dropdown list.

    Subscribe Cisco IP phone to MiaRec phone service

  4. In the new pop up window select MiaRec from the list box.

  5. Click the Next button.

    Subscribe Cisco IP phone to MiaRec phone service

  6. Click the Subscribe button.

    Subscribe Cisco IP phone to MiaRec phone service

  7. Verify that the phone subscribed to MiaRec phone service successfully and click the Save button. Then close this pop up window.

    Subscribe Cisco IP phone to MiaRec phone service

Now, after you save phone configuration and restart the phone, the MiaRec phone services should be available upon clicking the Services button on the phone.

[Optional] Use phone's line button for quick access to MiaRec phone services.

  1. Click the Modify Button Items in the Phone Configuration window

    Subscribe Cisco IP phone to MiaRec phone service

  2. Select the Add a new SURL from the list Unassigned Associated Items and click < button.

    Subscribe Cisco IP phone to MiaRec phone service

  3. If you receive the error Must Remove An Item From Associated List Before This Operation is Allowed., then select one of unnecessary items in the list Associated Items and click V button.

    Subscribe Cisco IP phone to MiaRec phone service

    Subscribe Cisco IP phone to MiaRec phone service

  4. Select the Add a new SURL in the list Associated Items and click button ^ as many times as necessary to move it to the correct position. For example, if the phone has only 4 line buttons, then position should be from 1 to 4, otherwise the button will not be visible.

    Subscribe Cisco IP phone to MiaRec phone service

  5. Click the Save button and close this pop up window.

  6. Click the newly created Add a new SURL link.

    Subscribe Cisco IP phone to MiaRec phone service

  7. Select MiaRec from the list box and click Save button two times.

    Subscribe Cisco IP phone to MiaRec phone service

  8. Verify that MiaRec is shown on the line button. Save the phone configuration and click Apply Config (depending on phone firmware it may be necessary to restart the phone to apply changes).

    Subscribe Cisco IP phone to MiaRec phone service

High availability

Overview

MiaRec implements a redundant, high availability architecture.

Below diagram show a network design of redundant recording in BroadWorks environment. Similar design applies to Cisco Built-in-Bridge recording interface, SIPREC recording interface for Metaswitch CFS, Metaswitch Perimeta SBC, Avaya SBC, Oracle/AcmePacket SBC.

Broadworks SIPREC redundant recorder

Supported features

  • Automatic fail over to the next available server in a cluster
  • Load balancing of recording traffic between multiple servers
  • More than 2 master servers in a cluster
  • Geographical redundancy
  • Replication of data may be continuous (immediately upon call completion) or by schedule (at night during low load hours).

How it works

A MiaRec cluster supports 2 and more servers. Any server in a cluster may receive recordings at any time. Upon call completion, audio files and call metadata is automatically uploaded/synchronized to other servers in a cluster.

This document describes implementation of redundancy for BroadWorks SIPREC and Cisco SIP Trunk built-in-bridge recording methods. Implementation of recording interface for these two platforms is based on similar principles with some variations.

Redundancy - new recordings

At the beginning of call recording, the phone system (Broadworks / Cisco UCM) sends SIP INVITE to the first available server in a cluster. If the primary server is down or its network is disconnected, it cannot respond to the SIP invitation. The usual SIP processing in this case is to deliver the invitation to the next recording server in the preference list.

Redundancy - in-progress recordings

If a recording server fails, all active recordings will be interrupted. If failure was caused by issues with network, then call recordings will be completed automatically by timeout (configurable). If failure was caused by hardware/software issue with recording process, then such recordings will remain in ACTIVE state till administrator manually mark them as completed. In both cases, the recording data will contain media from the beginning of call till the failure moment (unless there is issue with disk system).

MiaRec supports advanced architecture in order to achieve fault-tolerant architecture for in-progress calls. This architecture involves a dedicated recording server, which is configured in passive recording mode. Currently it is tested only for Cisco BiB protocol, but may work for SIPREC protocol with other phone platforms as well. The Cisco BiB network traffic, which is sent to the primary recording server, should be mirrored to a redundant server, which works in passive recording mode. This server records a copy of each call that is captured by the primary server. In case of the primary server failure in a middle of call, the redundant server has ability to continue recording of such call till the call disconnect. Such mechanism is based on architecture of Cisco Built-in-Bridge mechanism. Once media forking is activated, Cisco IP phone continues to send RTP packets to the primary recorder even if the latter is not reachable anymore. The phone doesn’t stop sending of RTP packets even if it receives “port is unreachable” ICMP error message. The redundant server continues to capture such RTP packets till call completes. This allows to achieve 100% redundancy for call recording.

Redundancy - completed recordings

After a recording is complete, MiaRec adds the call recording into queue for automatic replication to other server(s) in a cluster. Such data replication may be started immediately upon call completion or scheduled to specific time of day (for example, at night).

Geographical redundancy

MiaRec servers in a cluster may reside in different datacenter for geographical redundancy. There is no requirement for minimum latency between servers. It is only required that bandwidth between datacenters is enough to process data replication.

Data replication may configured as continuous (immediately upon call completion) or by schedule at specific time (for example, at night during low load hours).

Although there is no requirement to the 100% of availability of network link between datacenters. In case of unavailability of the target replication server, the replication process will be retried when network connection is restored.

The source replication server uses queue for data replication. The call recording is removed from queue only after successful replication. Overhead on queue is insignificant (it uses only a hundred of bytes per call recording in replication queue).

High availability for BroadWorks SIPREC recording

High availability and automatic failover for SIPREC interface is based on two technologies:

How it works

BroadWorks platform supports DNS SRV records for SIPREC interface. This allows building of the following configurations:

  • Multiple recording servers and split SIPREC traffic between them (load balancing)
  • Multiple recording servers with automatic failover from a primary server to a secondary one.
  • A combination of above two variants.

MiaRec supports automatic call replication between two or more recording servers. Audio file and call metadata is automatically uploaded to replication target server(s) upon call completion or by schedule (for example, at night).

Broadworks SIPREC redundant recorder

Example of DNS SVR records

# _service._proto.name. TTL class SRV priority weight port target.
_sip._tcp.example.com. 86400 IN SRV 10 40 5060 miarec1.example.com.
_sip._tcp.example.com. 86400 IN SRV 10 30 5060 miarec2.example.com.
_sip._tcp.example.com. 86400 IN SRV 10 30 5060 miarec3.example.com.
_sip._tcp.example.com. 86400 IN SRV 20 0  5060 miarec4.example.com.

The first three records share a priority of 10, so the weight field’s value will be used by BroadWorks to determine which recording server to contact. The sum of all three values is 100, so “miarec1” will be used 40% of the time. The remaining two hosts “miarec2” and “miarec3” will be used for 30% of requests each. If “miarec1” is unavailable, these two remaining servers will share the load equally, since they will each be selected 50% of the time.

If all three servers with a priority of 10 are unavailable, the records with the next lowest priority value will be chosen, which is “miarec4”. This might be a machine in another physical location, presumably not vulnerable to anything that would cause the first three servers to become unavailable.

Limitations:

  • The load balancing provided by SRV records is inherently limited, since the information is essentially static. Current load of servers is not taken into account.
  • In case of failover from one server to another, the currently active recordings on the failed server are interrupted. A new recording server will handle only new SIPREC requests.

Check also: MiaRec automatic replication

High availability for Cisco Built-in-bridge recording

High availability and automatic failover for Cisco active recording interface is based on the following technologies:

  • MiaRec automatic replication between multiple servers in a cluster
  • Multiple SIP Trunks or DNS SRV for automatic failover and/or load balancing
  • SIP OPTIONS Ping feature in Cisco UCM for fast detection of server unavailability

How it works

Cisco Built-in-Bridge redundant recorder

The recording server in Cisco UCM is configured as a SIP Trunk. Cisco UCM supports configuration of multiple SIP Trunks with automatic failover between them.

Additionally, Cisco UCM starting from v.8.5(1) supports SIP OPTIONS Ping feature. Cisco UCM periodically sends a SIP OPTIONS (ping) message to each recording server to detect its availability. If the recording server is unavailable – indicated by either no response, response of “408 Request Timeout” response of “503 Service Unavailable”, Cisco UCM marks this recording server as unavailable. If the recording server is available – indicated by any other responses other than “503” or “408”, Cisco UCM marks this recording server as available. Cisco UCM will send new INVITE only to “available” recording servers.

MiaRec supports automatic call replication between two or more recording servers. Audio file and call metadata is automatically uploaded to replication target server(s) upon call completion or by schedule (for example, at night).

Alternatively, instead of configuring multiple SIP Trunks in Cisco UCM it is possible to configure a single SIP Trunk pointing to DNS SRV records. The multiple recording servers are configured as SRV records. Such configuration allows to build automatic failover and load balancing configurations with multiple recording servers.

Example of DNS SRV records:

# _service._proto.name. TTL class SRV priority weight port target.
_sip._tcp.example.com. 86400 IN SRV 10 40 5060 miarec1.example.com.
_sip._tcp.example.com. 86400 IN SRV 10 30 5060 miarec2.example.com.
_sip._tcp.example.com. 86400 IN SRV 10 30 5060 miarec3.example.com.
_sip._tcp.example.com. 86400 IN SRV 20 0  5060 miarec4.example.com.

The first three records share a priority of 10, so the weight field’s value will be used by Cisco UCM to determine which recording server to contact. The sum of all three values is 100, so “miarec1” will be used 40% of the time. The remaining two hosts “miarec2” and “miarec3” will be used for 30% of requests each. If “miarec1” is unavailable, these two remaining servers will share the load equally, since they will each be selected 50% of the time.

If all three servers with priority 10 are unavailable, the records with the next lowest priority value will be chosen, which is “miarec4”. This might me a machine in another physical location, presumably not vulnerable to anything that would cause the first three servers to become unavailable.

Limitations:

  • Load balancing provided by SRV records is inherently limited, since the information is essentially static. Current load of servers is not taken into account.
  • In case of failover from one server to another, the currently active recordings on a failed server are interrupted. The new recording server will handle only new SIP requests.

Check also: MiaRec automatic replication

Multi-tenancy

Enable multi-tenancy in MiaRec

In MiaRec web portal navigate to Administration -> System Configuration -> Advanced Settings. Click on Edit settings and change Multitenancy settings from disabled to enabled.

Now you should be able to see Tenants configuration inside administration interface.

Understanding multi-tenancy

MiaRec supports multi-tenant configuration. Each tenant has own set of users, groups, roles, and extensions. Tenant users have access to data only within boundaries of own tenant account. Tenant's data is isolated from each other.

MiaRec provides self-service capability to tenants. For example, tenant administrator may reset own users' passwords, modify role permissions, move existing user into another group, etc.

Multi-tenancy.png

Frequently asked questions

  1. How call recordings are associated with tenant?

    Each tenant has a pre-configured set of extensions. MiaRec uses this data to automatically associate calls to users.

  2. Can tenant administrator change own extensions?

    No. The extensions are configured by system administrator. The tenant administrator may only re-allocate available extension from one user to another.

  3. Is it required to give tenants an access to admin interface?

    No, it is not required. It's possible to create tenant users with read-only access to MiaRec web-portal and skip creation of tenant administrator role.

Add tenant

To create a new tenant account navigate to Administration -> Users Management -> Tenants and complete the following steps:

  1. Create new tenant account
  2. Create at least one group. For example, "Users".
  3. Create at least one role with appropriate permissions. For example, "Agent role". Optionally, you may create tenant admin account who will be able to manage own tenant users (reset users passwords, edit role permissions, create new groups, etc).
  4. Create users and assign extensions to them.

Extension in MiaRec is a "phone number", "phone name" and/or "broadworks user ID". If you are using Broadworks platform, then it is recommended to enter your users' broadworks ID's as extensions. For other platforms it is recommended to use users phone number as an extension. Using of phone name is recommended in cases when multiple users share the same extension and only the phone name part is unique.

Tenant view

Speech Analytics

How it works - Speech Analytics

MiaRec automatically uploads the audio files to the cloud service for transcription.

Once transcription is completed, the results are shown in the call details.

The screenshot below shows:

  • Keywords. Automatically extracted keywords from the conversation
  • Transcript. Textual representation of the conversation

You can click on any of the keywords. The MiaRec Media Player will fast forward to the location of the keyword in the recording. it shows mark mark at that location If the same keyword appears multiple times in the conversation, then you can see multiple marks.

Additionally, when you playback the recording, the transcript is automatically highlighted at that position (see the yellow background in the following screenshot).

MiaRec Speech Analytics

You can use "Advanced Search" page to locate recording with a particular keyword or transcription text.

MiaRec Speech Analytics

The following screenshot shows how to search in transcript:

MiaRec Speech Analytics

Check also:

Configuration - Speech Analytics

First, you need to change the audio file format settings to increase transcription accuracy. Navigate to Administration -> Storage -> File format and apply the following changes:

  1. Enable "Stereo" format
  2. Disable "Automatic Gain Control (AGC) filter"
  3. Disable "Packet Loss Concealment (PLC) filter"
  4. Set "Mp3Bitrate" to "64kbps"

MiaRec Speech Analytics

Then, you need to configure speech recognition job in MiaRec. This job will automatically upload the pre-selected recordings to the cloud service for transcription and then retrieves back the transcription results.

Navigate to Administration -> Speech Analytics -> Speech Recognize Jobs, click "New Job".

MiaRec Speech Analytics

In the new window, you will be able to configure various parameters for voice-to-text recognition.

Particularly:

  • Language. Supported languages: UK English, US English, Australia English, Portuguese (Brazil), Spanish (Latin America).
  • Custom vocabulary (optional). For example, product names, competitor names, some business-specific terms.
  • Redaction of sensitive data from the transcript (credit card numbers, SSN numbers, etc.), optional.

You need to configure OAuth Bearer token as provided to you by MiaRec team.

MiaRec Speech Analytics

In the job configuration, you can limit what recordings are sent for transcription.

For example, you probably do not need to transcribe very short calls as they do not contain important data for analyze. Additionally, you can limit transcription to particular group/tenant/user, date range, etc. Actually, you can use any call attribute in the filtering criteria.

The transcribe job could be run manually or by schedule. The screenshot below shows how to run the job every 5 minutes.

MiaRec Speech Analytics

If you run the job manually, then you can see the progress of uploading process:

MiaRec Speech Analytics

It takes some time for the cloud service to complete transcription and return results. Usually, the results are available in a couple of minutes after upload.

You can check the status of the recently uploaded files via menu Administration -> Speech Analytics -> Speech Analytics Processed Records.

MiaRec Speech Analytics

After the status changes to "FINISHED", you can view the call details and transcription by clicking "View call" right on this page. Or you can open the call details from "Recordings" page as usual.

MiaRec Speech Analytics

The screenshot below shows the example of transcription.

Here you can see:

  • Keywords. Automatically extracted keywords from the conversation
  • Transcript. Textual representation of the conversation

You can click on any of keywords. The MiaRec Media Player will fast forward to the location of the keyword in the recording. it shows mark mark at that location If the same keyword appears multiple times in the conversation, then you can see multiple marks.

Additionally, when you playback the recording, the transcript is automatically highlighted at that position (see the yellow background in the following screenshot).

MiaRec Speech Analytics

Troubleshooting

Log files

MiaRec solution consists of multiple components. Most of these components have own log file location.

MiaRec component Location
Call recording service (MiaRec)
  • Log messages inside DB (accessible via web UI menu Administration -> System Management -> System Log)
  • If trace is enabled, the trace files are located in Data\log\trace (on Windows) or /var/log/miarec/trace (on Linux)
Web portal
  • Log messages inside DB (accessible via web UI menu Administration -> System Management -> System Log)
  • Apache service logs own messages into directory Data\log\apache (on Windows) or /var/log/httpd/ (on Linux)
Celery scheduler Log files are located in directory Data\log\celery (on Windows) or /var/log/celery/ (on Linux)
Redis (cache system) Log files are located in directory Data\log\redis (on Windows) or /var/log/redis_*/ (on Linux)

MiaRec recorder trace

MiaRec supports writing detailed trace information into text file. Such trace information may be useful during problem investigation.

Navigate to menu Administration -> Maintenance -> Troubleshooting and click Configure button at the Trace option.

MiaRec recorder trace

In the next configuration page you can specify:

  • Full path to the trace log file

  • Trace level depth (recommended log level for troubleshooting is 5)

  • Log rotation settings

MiaRec recorder trace

MiaRec Architecture

The MiaRec call recording solution consists of multiple components:

All these components may be deployed on a single server, in case of small size project, or distributed over multiple dedicated servers, optionally, with duplication/redundancy.

Below you can find a simplified as well as detailed diagram of MiaRec architecture.

Simplified diagram

MiaRec Architecture

Detailed diagram

MiaRec Architecture

Recording service

The Recording service is a major component of MiaRec solution.

It captures call recordings from phone system via passive (port mirroring) or active recording method (SIPREC, Cisco BIB, Avaya TSAPI+DMCC etc).

Voice data is stored in WAV/MP3 format on local file system or NAS/SAN.

Call metadata is stored in database and/or textual CSV files (for backup/fail-over purposes).

REST API is used for retrieving of real-time information about call recordings and changing of recorder's behavior, for example, trigger on-demand recording, pause/resume recording, reload configuration etc.

Live monitoring feature is based on RTSP protocol for streaming real-time audio to end user.

Recorder service notifies a web-portal about call events in real-time (call begin/finish) via REST API. Such notification is used to trigger some post-processing tasks like continuous call replication, grouping of multi-segment calls into single interaction etc.

Telnet CLI is used for troubleshooting and monitoring purposes.

Recorder service loads own configuration from MiaRec.ini file at first. From INI file it reads database connection settings (host, port, login etc) and then load configuration from database.

By design the recorder service is independent from other components. It doesn't depend on web-portal component at all. And it continues to record calls even if database is down. In this case, call metadata will be stored in textual CSV files, which may be imported into database when the latter is up again.

File storage

Audio files are stored either locally or on a network-based storage device.

Additionally, MiaRec supports two-phase file storage to improve performance and provide fault-tolerance. When call recordings starts, the recorder creates audio file on local disk array (usually high-speed). When call recording completes, audio file is moved automatically to long-term storage (network-based or high volume but low-speed disk array). If network-based storage is not available, file move operation will fail, but the audio file itself will be successfully stored on local disk array. Such architecture protects from occasional issues with network.

Two-phase file storage architecture is used also to improve performance during active recording phase. When call is in progress, the recorder flushes periodically data to disk by small portions. If there are hundreds of concurrent call recordings, then it causes high IOPS (input-output operations per second) on disk array. In this case, usage of local high-speed disk array is highly recommended. When call completes, its audio file is moved to long-term storage. Such move operation will trigger a single disk write operation per call. IOPS on long-term storage is significantly lower in this case.

Database

Database is used for storing call metadata, recorder configuration as well as web-portal data.

Web portal

Web portal provides access to call recordings to end-users.

Additionally, web portal implements REST API which may be used by third-party applications for accessing call recordings and other resources (like users, groups, roles etc).

Celery scheduler

Celery is a job scheduler and background task manager. It executes such jobs like backup, replication, ldap user synchronization etc.

Audio file encryption

File encryption overview

MiaRec provides rock-solid audio encryption functionality, ensuring all call recordings are securely stored in an encrypted format. MiaRec encryption functionality helps companies confidently adhere to the highest corporate security standards and comply with legal regulations, such as PCI-DSS, HIPAA, Dodd-Frank and Sarbanes-Oxley.

Some key features of MiaRec audio file encryption:

  • Administrator has control over who can playback (decrypt) the recordings
  • In a multi-tenant mode each tenant has own unique encryption key
  • Encryption is applied to backup data as well

MiaRec Audio File Encryption

Audio file encryption vs role-based access control

MiaRec role-based access control system provides protection of data from unauthorized access to the MiaRec web-portal. Everyone accessing the system must be an authenticated user with associated different set of permissions.

Audio file encryption provides additional layer of security over the role-based access control system in MiaRec. If encryption is enabled, then audio files are stored on a hard disk in encrypted format. This insures that even if unauthorized user gains physical access to the storage system, he has no ability to playback recordings since he doesn't know private encryption key.

Download of encrypted recordings

When user downloads individual call recording through MiaRec web portal, the file is decrypted on flight. The file is saved on user's computer in unencrypted form.

However, when user uses bulk download feature and downloads multiple call recordings in ZIP archive, then the downloaded files are retrieved in encrypted form. User cannot playback such call recordings unless he imports them into MiaRec system together with private encryption key.

Encryption for backups

Using of file encryption is beneficial for backup data as well. All recordings in backup archive can be encrypted.

Encryption in multi-tenant environment

In multi-tenant mode each tenant has own encryption key. Even if audio file from one tenant becomes available to another tenant, the latter could not playback it, because file is encrypted with different key.

Additionally, in a multi-tenant hosted environment MiaRec supports the following usage scenario: tenant may provide the service provider with the public encryption key only. The tenant doesn't require to disclose their own private key to the service provider. This means that nobody on the service provider side, even system administrators, would be able to playback tenants' call recordings. To playback such call recordings, they should be uploaded to tenant's private network and imported into local instance of MiaRec software.

Encryption algorithms

MiaRec encrypts every call recording with asymmetric encryption. For every recording MiaRec generates random AES encryption key. This symmetric encryption key is then encrypted using asymmetric encryption (one key for encryption - often referred to as the "public" key - and a different key for decryption - often referred to as the "private" key).

MiaRec uses Advanced Encryption Standard (AES) for symmetric encryption (256-bit key) and the Rivest-Shamir-Adleman (RSA) public key algorithm for asymmetric encryption (2,048-bit keys).

The details and theory behind asymmetric encryption method is beyond the scope of this article; however, a good primer is available at https://en.wikipedia.org/wiki/Public-key_cryptography. In short, public key is used for encrypting data and private key is used for decrypting it. Public key doesn't need to be stored securely. Anyone can access the public key, but no one can use the public key to decrypt the data that the public key encrypted. The only way users can decrypt data is with a private key.

User access to encryption keys

Administrators need to grant access to encryption key(s) to particular users before them can playback (decrypt) audio files. Note, administrator may grant access only to those encryption keys, which are granted to him. If administrator, even if he/she has role "Root administrator", has no access to encryption key, then he/she cannot grant access to other users for the same key.

MiaRec software never stores encryption keys in database in plain text for security reasons. Even if unauthorized party gains access to database files, he/she could not retrieve the private keys because they are stored in encrypted format. There is no way to gain user's private key without knowing the user's password.

Configuration check-list

Configure MiaRec audio file encryption as follows:

  1. Create new encryption key or use existing one for System or Tenant (in multi-tenant mode)

  2. Export/backup new encryption key and save it in secure place for recovery purposes

  3. Grant access to encryption key to authorized users

  4. Enable audio file encryption on System or Tenant profile.

Create new encryption key

MiaRec License

MiaRec License

Import encryption key

MiaRec License

MiaRec License

Export encryption key

MiaRec License

MiaRec License

MiaRec License

MiaRec License

Grant access to encryption key

MiaRec License

MiaRec License

Enable file encryption

MiaRec License

MiaRec License

MiaRec License

Backup encrypted files

An important aspect of any file encryption facility's design is that file data is never available in unencrypted form except to users that access the file via the encryption facility. This restriction particularly affects backup process, when data is exported to external storage.

MiaRec addresses this problem by keeping files in encrypted form during backup process. The backup utility don't have to be able to decrypt file data before backup.

It is safe to export encrypted files to backup archive. The backup archive may be imported back to the same system or to new system during recovery process. When importing data to new system, it is necessary to import old encryption key as well.

Upgrade from version 3.x

Upgrade from MiaRec version 3.x consists of the following steps:

  1. Backup recordings on version 3.x

  2. [Optional] Stop all MiaRec services and backup full directory C:\Program Files\MiaRec Business

  3. Uninstall version 3.x

  4. Install MiaRec version 5.x (download from here)

  5. Import recordings from backup

  6. Create users/groups/roles

  7. Assign previously recorded calls to users

Supported data migration during upgrade

During upgrade the following data will be migrated from old version to new one:

Non-supported data migration during upgrade

Data, which is not migrated from old version to new one:

Incompatibilities between v.5 and v.3

New version of MiaRec includes a lot of new features and improvements in usability and user experience. Below we will list only significant incompatibilities between new and old versions: