Legacy documentation

Passive call recording setup

Note, these steps are required for passive recording (port mirroring) configuration only.

Ignore these steps when using active recording methods like Cisco Built-in-Bridge, SIPREC or Avaya DMCC.

What is port mirroring?

Port Mirroring, also known as SPAN (Switched Port Analyzer), is a method of monitoring network traffic. With port mirroring enabled, the switch sends a copy of all network packets seen on one port (or an entire VLAN) to another port, where the packet can be analyzed.

Port Mirroring function is supported by almost all enterprise-class switches (managed switches).

Port mirroring function is best described when comparing  regular switch and switch with port mirroring support.

Figure 1. Regular Switch

In Figure 1 you see network  the traffic sent between computers A and B.

The MAC table in the memory of the switch contains information on which port is connected to particular computer.

Switch knows that:

  • Port #1 (first on the left) is not connected.
  • Port #2 is connected to A
  • Port #3 is connected to B
  • Port #4 is connected to C
  • Port #5 is connected to D

When the switch receives a packet from A to B, it routers this packet to port #3 (because B is on port #3).

Other computers (C and D) do not see this network traffic. It is hidden from them.

Conclusion: With a regular switch the network traffic is visible only to computers, which directly participare in a communication. Other computers do not see the traffic, that is not destined for them.

Figure 2. Switch with Port Mirroring

In Figure 2 you see the similar scenario: the network traffic is sent between computers A and B.

But there is a small difference: this switch supports port mirroring function. And administrator has configured the switch to mirror to computer D all network packets, which are transmitted between computers A and B.

Computer D is a listener to the traffic. Computer D can be used for network logging or call recording if we have IP phones instead of computers A and B .

Conclusion: Port mirroing allows a particular computer to see the network traffic, which is normally hidden from it.

 

 

How Port Mirroring function is used for VoIP call recording?

 The image below illustrates the usual configuration of network, which enables call recording.

 

In this example, one of IP Phones makes a call to a remote phone outside of the local network (whether it is analog phone, cellular or another IP Phone).

Network traffic from IP Phone goes through network switch with port mirroring. The switch sends to MiaRec a copy of every network packet, sent or received by IP Phone.

By using intelligent packet capturing technology, MiaRec detects Voip-related packets inside the network traffic, decodes them and saves audio on a disk.

Virtual machine + passive recording

This document decribes requirements to virtual machine for passive recording method (port mirroring). If you are using active recording method (like SIPREC, Cisco Built-in-Bridge etc), then such requirements do not apply.

 

Passive recording is supported in virtual environment. Following virtualization products are supported:

Virtualization productSupported?
VMWare ESX/ESXiSupported
Microsoft Hyper-VSupported starting from version 2012

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

Enable packets pass-through for port mirroring traffic

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:

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.

How to configure port mirroring on different switches

This article contains step-by-step guides for port mirroring configuration on some network switch models.

Cisco Catalyst 2960 Series Switches

Cisco Catalyst 2940, 2950, 2955, 2960, 2970, 3550, 3560, 3750

This guide contains instructions for configuration of SPAN session (Port Mirroring) on Cisco Catalyst 2960 Series Switches.

read more

D-Link DES-3010

D-Link DES-3010

This guide contains instructions for configuration of Port Mirroring on D-Link DES-3010 Series switches.

read more

Dell PowerConnect 2700 Series

Dell PowerConnect 2700 Series

This guide contains instructions of how to configure Port Mirroring on Dell PowerConnect 2700 Series (2708/2716/2724/2748) switches.

read more

Netgear FS726T

Netgear FS726T

This guide contains instructions of how to configure Port Mirroring on Netgear FS726T switch.

read more

TP-LINK TL-SL2428WEB

TL-SL2428WEB

This guide contains instructions of how to configure Port Mirroring on TP-LINK TL-SL2428WEB switch.

This guide applies also to other models from TP-LINK Web Smart Switches series:

  • TP-LINK TL-SG2109WEB
  • TP-LINK TL-SG2216WEB
  • TP-LINK TL-SG2224WEB
  • TP-LINK TL-SL2210WEB
  • TP-LINK TL-SL2218WEB
  • TP-LINK TL-SL2453WEB
read more

Cisco Catalyst 2960 Series Switches

Name: 
Cisco Catalyst 2960 Series
Mirror Port Read-Only: 
No
Description: 

This guide contains instructions for configuration of SPAN session (Port Mirroring) on Cisco Catalyst 2960 Series Switches.

Image: 
Cisco Catalyst 2940, 2950, 2955, 2960, 2970, 3550, 3560, 3750

Lets assume MiaRec Server is connected to port 3. On the network diagram it is shown in a red color (Analysis port).

And port 5 is used for connecting to IP-PBX (if you have one) or uplink to WAN/Internet (if you do not have IP-PBX). On the network diagram it is shown in green color (Monitored port).

In this case you need to execute following command on the switch:

1. Enter configuration mode:

C2960# configure terminal

2. Create monitoring session and configure interface Fast Ethernet 0/5 as source port for that session:

C2960(config)# monitor session 1 source interface fastethernet 0/5

3. Configure interface Fast Ethernet 0/3 as destination port for session 1.

C2960(config)# monitor session 1 destination interface fastethernet 0/3

4. Check, if everything is configured correctly:

C2960# show monitor session 1

Session 1
---------
Source Ports:
 RX Only:       None
 TX Only:       None
 Both:           Fa0/5
Destination Ports: Fa0/3

Now a configuration is completed and you should be able to record calls with MiaRec Business.

Should you have any questions or issues, please, do not hesitate to contact our support team.

Caution! If you have inter-office calls (between local phones), then every phone's port should be set as a Source Port (Cisco Catalys 2960 switches supports monitoring of multiple ports).

You will need to execute command in point 2 (see above example) multile times for every port:

C2960# configure terminal

C2960(config)# monitor session 1 source interface fastethernet 0/6
C2960(config)# monitor session 1 source interface fastethernet 0/7
C2960(config)# monitor session 1 source interface fastethernet 0/8
C2960(config)# monitor session 1 source interface fastethernet 0/9
C2960(config)# monitor session 1 source interface fastethernet 0/10
C2960(config)# monitor session 1 destination interface fastethernet 0/3

That assumes you have 5 IP Phones and they are connected to ports 6, 7, 8, 9 and 10 on the switch and MiaRec server is connected to port 3.

See How to configure Port Mirroring in different call scenarios.

More detailed information about configuration of SPAN can be found on Cisco web-site:

Catalyst Switched Port Analyzer (SPAN) Configuration Example

D-Link DES-3010

Name: 
D-Link DES-3010
Mirror Port Read-Only: 
No
Description: 

This guide contains instructions for configuration of Port Mirroring on D-Link DES-3010 Series switches.

Image: 
D-Link DES-3010

In order to configure Port Mirroring feature, you need to open D-Link Embedded Web Interface (if you don't know how to do this, check a documentation of your device).

When you login on Web Interface, go to setting Administration->Port Mirroring.

You should see a page like on below screen-shot:

DES-3010 Configuration

Click on image to enlarge.

Configure Port Mirroring according to following instructions:

  • Target Port should be a port, where MiaRec Server is connected to. On the network diagram it is shown in red color (Analysis port).
  • Status should be enabled.
  • Source Port should be a port, where IP-PBX is connected to (if you have one) or uplink to WAN/Internet (if you do not have IP-PBX). On the network diagram it is shown in green color (Monitored port). Source port should be set into position Both.

Caution! If you have inter-office calls (between local phones), then every phone's port should be set as a Source Port (D-Link switch supports monitoring of multiple ports).

See How to configure Port Mirroring in different call scenarios.

Save changes on that page (click 'Apply' button).

If you need to change other settings of D-Link switch, do this now. When you finish, click on 'Save Changes' to write configuration into NV-RAM. If you do not do this last step, then all changes will be lost after reboot of a switch.

DES-3010 Configuration

Click on image to enlarge.

Now a configuration is completed and you should be able to record calls with MiaRec Business.

Should you have any questions or issues, please, do not hesitate to contact our support team.

Dell PowerConnect 2700 Series

Name: 
Dell PowerConnect 2700 Series
Mirror Port Read-Only: 
Yes
Description: 

This guide contains instructions of how to configure Port Mirroring on Dell PowerConnect 2700 Series (2708/2716/2724/2748) switches.

Image: 
Dell PowerConnect 2700 Series

The device is delivered from the factory in Unmanaged Mode. The device must be changed to Managed Mode before it can be configured. To change to Managed Mode, the device must be fully operational in Unmanaged Mode (Managed Mode LED has stopped blinking and is off).

Dell PowerConnect 2708 Front Panel

Click on image to enlarge

Once the Managed Mode LED has stopped blinking, press the Managed Mode button. The switch reboots and the Managed Mode LED blinks for approximately 90 seconds and stays lit. When the Managed Mode LED stays lit, the switch is ready to be configured. The default IP address is 192.168.2.1, the default User Name is 'admin', and the default password is left blank.

  1. Open a Web browser on your computer.
  2. Enter the Ethernet Switch IP address (the default IP address is 192.168.2.1)

The following login screen is displayed when the device is first connected:

Dell PowerConnect 2708 Web Login

The default User Name is 'admin', and the default password is left blank.

Click on Port Mirroring in the tree view.

You should see a page like on below screen-shot:

Dell PowerConnect 2708 Port Mirroring

Click on image to enlarge

Configure Port Mirroring according to following instructions:

  • Destination Port should be a port, where MiaRec Server is connected to. On the network diagram it is shown in red color (Analysis port).
  • Source Ports list. Add here the port, which is connected to IP-PBX (if you have one) or uplink to WAN/Internet (if you do not have IP-PBX). On the network diagram it is shown in green color (Monitored port). Type should be TX and RX.

Caution! If you have inter-office calls (between local phones), then every phone's port should be added to Source Ports list.

The PowerConnect 2700 series switches support up to 4 (four) source ports. If you have more than four phones and recording of inter-office calls is required, then you are suggested to choose another managed switch, which supports a desired number of mirrored source ports.

See How to configure Port Mirroring in different call scenarios.

Save changes on that page (click 'Apply Changes' button).

Now a configuration is completed and you should be able to record calls with MiaRec Business.

Should you have any questions or issues, please, do not hesitate to contact our support team.

Netgear FS726T

Name: 
Netgear FS726T
Mirror Port Read-Only: 
No
Description: 

This guide contains instructions of how to configure Port Mirroring on Netgear FS726T switch.

Image: 
Netgear FS726T

In order to configure Port Mirroring feature, you need to open Netgear Web-Based Management Interface (if you don't know how to do this, check a documentation of your device).

When you login on Web Interface, go to setting Switch->Monitor.

You should see a page like on below screen-shot:

Netgear Configuration

Configure Port Mirroring according to following instructions:

  • Sniffer Mode should be set to Both.
  • Sniffer Port should be a port, where MiaRec Server is connected to. On the network diagram it is shown in red color (Analysis port).
  • Source Port. Check the port, where IP-PBX is connected to (if you have one) or uplink to WAN/Internet (if you do not have IP-PBX). All other ports should be unchecked. On the network diagram it is shown in green color (Monitored port).

Caution! If you have inter-office calls (between local phones), then every phone's port should be checked as a Source Port (Netgear switch supports monitoring of multiple ports).

See How to configure Port Mirroring in different call scenarios.

Save changes on that page (click 'Apply' button).

Now a configuration is completed and you should be able to record calls with MiaRec Business.

Should you have any questions or issues, please, do not hesitate to contact our support team.

TP-LINK TL-SL2428WEB

Name: 
TP-LINK TL-SL2428WEB
Mirror Port Read-Only: 
No
Description: 

This guide contains instructions of how to configure Port Mirroring on TP-LINK TL-SL2428WEB switch.

This guide applies also to other models from TP-LINK Web Smart Switches series:

  • TP-LINK TL-SG2109WEB
  • TP-LINK TL-SG2216WEB
  • TP-LINK TL-SG2224WEB
  • TP-LINK TL-SL2210WEB
  • TP-LINK TL-SL2218WEB
  • TP-LINK TL-SL2453WEB
Image: 
TL-SL2428WEB

In order to configure Port Mirroring feature, you need to open TP-LINK Web-Based Management Interface (if you don't know how to do this, check a documentation of your device).

When you login on Web Interface, go to setting Port Mirroring.

You should see a page like on below screen-shot:

TP-LINK Configuration

 

Configure Port Mirroring according to following instructions:

  • Mirror Mode should be set to Both.
  • Mirror Port should be a port, where MiaRec Server is connected to. On the network diagram it is shown in red color (Analysis port).
  • Mirrored Port. Check the port, where IP-PBX is connected to (if you have one) or uplink to WAN/Internet (if you do not have IP-PBX). All other ports should be unchecked. On the network diagram it is shown in green color (Monitored port).

Caution! If you have inter-office calls (between local phones), then every phone's port should be checked as a Mirrored Port.

The TL-SL2428WEB switch supports up to 4 (four) mirrored ports. If you have more than four phones and recording of inter-office calls is required, then you are suggested to choose another managed switch, which supports a desired number of mirrored source ports.

See How to configure Port Mirroring in different call scenarios.

Save changes on that page (click 'Submit' button).

Now a configuration is completed and you should be able to record calls with MiaRec Business.

Should you have any questions or issues, please, do not hesitate to contact our support team.

Port Mirroring in complex call scenarios

This article gives some recommendations for "Port Mirroring" configuration on different types of voip network.

First of all it is necessary to decide, which calls is necessary to record.

There are three types of calls:

  • Outbound (local phone makes a call to the external phone)
  • Inbound (call is received from the external phone to the local phone)
  • Local or Internal (call is established between two local phones)

If recording of local calls is not necessary (or there are no such calls), then a configuration of "Port Mirroring" is very simple.

You need to mirror the port, where IP PBX is connected to (see Figure 1).

Recording of Inbound and Outbound calls only

Figure 1. Recording of Inbound and Outbound calls only

 

On Figure 1 it is shown that RTP audio traffic is sent from IP Phone to IP PBX. This traffic is mirrored to MiaRec server, where it is decoded.

This solution works for both inbound and outbound calls.

But it may not work for local calls. On most of IP PBX systems there is an optimization for network bandwidth usage: if the call is made between two local IP Phones, then RTP traffic is sent directly between phones without reaching of IP PBX (see Figure 2).

Recording of Inbound, Outbound and Local calls

Figure 2. Recording of Inbound, Outbound and Local calls

 

In order to record Local calls as well as Inbound and Outbound it is necessary to mirror every port, where IP Phones are connected to.

 

Recording calls on the second switch

If IP Phones are connected through multiple switches, then additional effort is necessary to make call recording works.

Configuration of "Port Mirroring" is easy if recording of local calls is not required.

In this case "Port Mirroring" is required only on the main switch (see Figure 3).

Recording calls on the second switch

Figure 3. Recording of calls on the second switch

 

In the case that recording of local calls is required, then there are three solutions:

1. Install additional network adapter into MiaRec server and connect multiple switches to it (see Figure 4)

MiaRec server with two network adapters

Figure 4. MiaRec server with two network adapters

 

 

2. Install a separate MiaRec server for the second switch (see Figure 5).

Two MiaRec servers

Figure 5. Two MiaRec servers

 

3. Use Remote SPAN (RSPAN) capability of Cisco Catalyst Switches (see Figure 6)

 

RSPAN configuration

Figure 6. RSPAN configuration


RSPAN allows you to monitor source ports that are spread all over a switched network, not only locally on a switch with SPAN. This feature appears in CatOS 5.3 in the Catalyst 6500/6000 Series Switches and is added in the Catalyst 4500/4000 Series Switches in CatOS 6.3 and later.

The functionality works exactly as a regular SPAN session. The traffic that is monitored by SPAN is not directly copied to the destination port, but flooded into a special RSPAN VLAN. The destination port can then be located anywhere in this RSPAN VLAN. There can even be several destination ports.

More about RSPAN (link to Cisco web-site) >>

 

 

Switches with port mirroring

Switches

This articles contains a list of some commonly used managed switches which support port mirroring (SPAN) function.

On this page:

Cisco

  Fast Ethernet ports Gigabit ports
Cisco Catalyst 2940 Series8 
Cisco Catalyst 2950 Series12, 24 or 48 
Cisco Catalyst 2955 Series12 

Cisco Catalyst 2960 Series

Configuration guide

8, 24 or 48 
Cisco Catalyst 3550 Series242
Cisco Catalyst 3560 Series8, 24 or 4824 or 48
Cisco Catalyst 3560-E Series 24 or 48
Cisco Catalyst 3750 Series24 or 48 16, 24 or 48
Cisco Catalyst 3750-E Series  24 or 48
Cisco Catalyst 4500 Series24 or 48 per slot24 or 48 per slot
Cisco Catalyst 4900 Series 48
Cisco Catalyst 6500 Seriesup to 96 per moduleup to 48 per module
Cisco Catalyst Express 500 Series248
Cisco Catalyst Express 520 Series8 or 241 or 2

D-Link

 Fast Ethernet portsGigabit ports
D-Link DES-13168 + 8 (PoE) 
D-Link DES-1228244
D-Link DES-1228P24 (PoE)4
D-Link DES-1252482
D-Link DES-3252P 48 (PoE)4
D-Link DGS-1210-10P 8 (PoE) + 2 (combo)
D-Link DGS-1210-16 12 + 4 (combo) 
D-Link DGS-1210-24 20 + 4 (combo) 
D-Link DES-1210-28242 + 2 (combo)
D-Link DGS-1210-48 44 + 4 (combo) 
D-Link DES-1210-52482 + 2 (combo)
D-Link DGS-1216T 16
D-Link DGS-1224T 24
D-Link DGS-1224TP 24 (PoE)
D-Link DGS-1248T 48

D-Link DES-3010GA

Configuration guide

81

D-Link DES-3010PA

Configuration guide

8 (PoE)1

D-Link DES-3010FA

Configuration guide

82
D-Link DES-3028244
D-Link DES-3028P24 (PoE)4
D-Link DES-3228PA24 (PoE)4
D-Link DES-3052484
D-Link DES-3052P48 (PoE)4
D-Link DES-3226L242
D-Link DES-3526242
D-Link DES-3550482
D-Link DGS-3200-10 8+2
D-Link DGS-3100-24 24
D-Link DGS-3100-24P 24 (PoE)
D-Link DGS-3100-48 48
D-Link DGS-3100-48P 48 (PoE)
D-Link DXS-3227 24
D-Link DXS-3227P 24 (PoE)
D-Link DXS-3250 48
D-Link DGS-3024 24
D-Link DGS-3224TGR 24
D-Link DGS-3048 48

Dell

 Fast Ethernet portsGigabit ports

Dell PowerConnect 2708 or 2808

Configuration guide

 8

Dell PowerConnect 2716 or 2816

Configuration guide

 16

Dell PowerConnect 2724 or 2824

Configuration guide

 24

Dell PowerConnect 2748 or 2848

Configuration guide

 48
Dell PowerConnect 3524242
Dell PowerConnect 3548482
Dell PowerConnect 5424 24
Dell PowerConnect 5448 48
Dell PowerConnect 6224 24
Dell PowerConnect 6248 48
Dell PowerConnect 5316M 16

HP

 Fast Ethernet portsGigabit ports
HP V1700-87 1
HP V1700-24222
HP V1810-8G 8
HP V1810-24G 24
HP V1900-8G 8
HP V1905 Series8 or 24 or 48 (optionally PoE)10 (PoE)
HP V1910 Series 16 or 24 or 24 (PoE) or 48
All L2/L3 Managed Switches  

Linksys

 Fast Ethernet portsGigabit ports
Linksys SLM2005 5
Linksys SLM2008 8
Linksys SLM2024 24
Linksys SLM2048 48
Linksys SLM224G242
Linksys SLM224G4PS24 (PoE)4
Linksys SLM224P24 (PoE)2
Linksys SLM248G482
Linksys SLM248G4PS48 (PoE)4
Linksys SLM248P48 (PoE)2
Linksys SFE2000244
Linksys SFE2000P24 (PoE)4
Linksys SFE2010482
Linksys SFE2010P48 (PoE) 
Linksys SGE2000 24
Linksys SGE2000P 24 (PoE)
Linksys SGE2010 48
Linksys SGE2010P 48 (PoE)

Netgear

 Fast Ethernet portsGigabit ports
Netgear FSM72624 

Netgear FS726T

Configuration guide

242
Netgear FS728TP24 (PoE)4
Netgear FS752TS484
Netgear FS752TPS48 (PoE)4
Netgear FSM7328S244
Netgear FSM7372S484
Netgear GS105E 5
Netgear GS108T or GS108T-200 8
Netgear GS716T or GS716T-200 16
Netgear GS724AT 24
Netgear GS724TP 24 (PoE)
Netgear GS748TR 48
Netgear GS748TP 48 (PoE)

TP-LINK

 Fast Ethernet portsGigabit ports

TP-LINK TL-SG2109WEB

Configuration guide

 9

TP-LINK TL-SL2210WEB

Configuration guide

82

TP-LINK TL-SG2216WEB

Configuration guide

 16

TP-LINK TL-SG2224WEB

Configuration guide

 24

TP-LINK TL-SL2218WEB

Configuration guide

162

TP-LINK TL-SL2428WEB

Configuration guide

244

TP-LINK TL-SL2452WEB

Configuration guide

484
TP-LINK TL-SG3109 9
TP-LINK TL-SL5428244
TP-LINK TL-SL5428E244
TP-LINK TL-SL3428244
TP-LINK TL-SG5426 26
TP-LINK TL-SL3452484

Manual installation (deprecated) on Linux

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

A manual installation is deprecated. Ansible-based installation is used now.

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:

sudo -u postgres psql postgres

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

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 bzip2-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.

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)

A manual installation is deprecated. Ansible-based installation is used now.

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 networking
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

Manual update on Linux (deprecated)

A manual installation is deprecated. Ansible-based installation is used now.

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

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:

Limitations

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.