Documentation

eSMDR monitors PBX systems through SMDR. Current systems can connect over the network with LAN SMDR; older systems can connect through a COM port. eSMDR runs either as a Windows service or as a console application for testing and debugging.

Incoming data can be stored in local files, sent over the network, or written to databases through ODBC. eSMDR can also forward the same stream to any number of call-accounting applications. It detects PBX faults such as digital trunk failures, CO line interruptions, and power failures, then notifies an administrator by email or SMS.

Reliability was a primary design goal. Its buffering mechanisms prevent data loss during failures of the local network, storage, or COM port.

Installation

Download the program archive and unpack it into any directory. All settings are stored in a single file, esmdr.ini. The file contains comments; the sections below describe its settings in more detail.

Configuration

PBX section

model

PBX model. Known models are TDA, TDE, NCP, LDK, and iPECS. Log parsing has been tested with these systems. TDE, NCP, LDK, and iPECS can connect over the network; older systems require a COM-port connection.

method

Connection method: TCP or COM.

countrycode

Telephone country code, such as 81 for Japan.

areacode

Local area code. If a city has several codes, use the one serving most of the connected CO lines. Do not include the domestic trunk prefix.

international

International access prefix. Usually 00; Japan uses 010.

longdistance

Domestic long-distance access prefix, such as 0 in Japan.

minlocal and maxlocal

Minimum and maximum number of digits in a local telephone number.

addchar

Digit inserted between the area code and a short local number. Leave empty when no padding is required.

[PBX]
model="TDE"
method="TCP"
countrycode="81"
areacode="3"
international="010"
longdistance="0"
minlocal=8
maxlocal=8
addchar=""

COM section

For a serial connection, match the COM-port settings configured in the PBX.

port

Computer port connected to the PBX.

baudrate

Port speed. For a TDA, see Maintenance Console menu 11.1, RS-232C.

bytesize

Word length: 7 or 8 bits.

parity

0 none, 1 odd, 2 even, 3 mark, or 4 space.

stopbits

0 for 1 bit, 1 for 1.5 bits, or 2 for 2 bits.

control

DTR, RTS, or XONXOFF. Use DTR for TDA.

[COM]
port="COM1"
baudrate=19200
bytesize=8
parity=0
stopbits=0
control="DTR"

TCP section

TDE, NCP, and newer LG systems only require a TCP section. For Panasonic, the IP address is the address used by Maintenance Console and may also be shown in the SVM card properties. Find the SMDR port and password in Maintenance Console menu 11.1, under SMDR Options. LG systems do not support authentication, so set login="".

[TCP]
ip="192.168.1.200"
port=2300
login="SMDR"
password="PCCSMDR"

LOG sections

Any number of sections whose names begin with LOG can write raw PBX output to files. eSMDR does not reformat this data. Keeping at least one raw log on a local disk is recommended.

When the destination is removable storage or a network path, the safe engine buffers data that cannot be written. Logs are flushed after the storage or network connection returns.

enabled

0 disables output; 1 enables it.

filename

Output filename. Relative paths start in the program directory; absolute paths are also accepted. Substitutions include %y year, %m month, %d day, %h hour, and %w weekday.

The file is not locked for reading, so calls can be viewed while eSMDR writes them.

[LOG]
enabled=1
filename="log\smdr-%y-%m.log"

TCPOUT sections

Sections beginning with TCPOUT forward unformatted SMDR data over TCP. This lets multiple loggers or accounting programs share one PBX connection. eSMDR can connect to another application as a client or emulate a PBX by accepting connections as a server.

enabled

0 disables TCP output; 1 enables it.

mode

client connects to a third-party application and is the default. server waits for applications to connect.

ip

In client mode, the address of the receiving application; use 127.0.0.1 on the same computer. In server mode, the interface to listen on; use * for every interface.

port

The receiving application’s port, or eSMDR’s listening port in server mode.

The safe engine is always active for TCP output, so each application receives buffered data after network interruptions or a late start.

[TCPOUT]
enabled=1
mode="client"
ip="127.0.0.1"
port=2301

SMDR section

The SMDR section describes how fixed-width call records are parsed.

date

Date format. The default is DD/MM/YY; separators and the order of the fields can be changed. For TDA, TDE, and NCP, see Maintenance Console menu 11.1.

format

Fixed-width record layout. The supplied configuration contains layouts for all three formats supported by newer Panasonic systems. Use D for date, T for time, E for extension, C for CO line, N for external number, R for ring time, d for call duration, A for account, c for status, and S for cost. Variable-width records are not supported.

incoming

One value or a comma-separated list identifying incoming calls.

did

Characters that mark the beginning of a DID number.

timesrc

PBX uses PBX time and is the default. computer uses the host computer’s time.

[SMDR]
date="DD/MM/YY"
format="DDDDDDDD TTTTTTT EEEEE CC NNNNNNNNNNNNNNNNNNNNNNNNN RRRR dddddddd AAAAAAAAAA ccc"
incoming="<I>"
did="<D>"
timesrc="PBX"

Format strings are supplied for Panasonic types A, B, and C, as well as LDK, iPECS, and iPECS MG. LG formats may need adjustment for extension length and the presence or absence of a status code.

REPLACE section

This section changes prefixes on parsed telephone numbers. For example, 815="00" replaces an initial 815 with 00. It does not affect raw LOG or TCPOUT output. Most such changes can be made in the PBX, so this section is rarely needed.

[REPLACE]
815="00"
0000="00"
015="00"
0572=""
057=""

CSV sections

Sections beginning with CSV write parsed calls to CSV files. Multiple sections are allowed.

enabled

Enables or disables output.

decimal

Decimal separator. English Excel uses a period and some localized versions use a comma. Omit this setting to use the operating-system locale.

separator

Field separator. Omit it to select the separator from the operating-system locale.

excelformat

Set to 1 to preserve leading zeroes when a file is opened in Excel. This may make the file incompatible with other applications.

filename

Filename template using the same substitutions as a LOG section.

[CSV]
enabled=1
decimal="."
separator=","
excelformat=0
filename="log\smdr-%y-%m.csv"

ODBC sections

Parsed calls can be written to databases through ODBC. First create a system DSN on the computer running eSMDR. On 64-bit Windows, use the 32-bit administrator at %windir%\sysWOW64\odbcad32.exe. The database server itself may be anywhere on the network. The safe engine protects records during connection failures.

enabled

0 disables output; 1 enables it.

dsn

Name of the system DSN.

login and password

Database credentials. Leave empty for Windows authentication. SQL Server authentication is recommended for eSMDR.

table

Destination database table.

fields

Destination fields.

values

Values in the same order as the fields. Substitutions are %Y year, %M month, %D day, %h hour, %m minute, %s second, %c status, %E extension, %C CO line, %r ring duration, %N external party name, %n external number, %T DID name, %t DID number, %d duration in seconds, %a account, %i direction (0 outgoing; otherwise incoming), and %F.%f cost.

sql

Server type: mssql2008, mssql for older versions, or mysql4 for MySQL 4 and newer. Omit it to use maximum-compatibility mode with other databases.

Any number of sections whose names begin with ODBC can be used.

[ODBC]
enabled=1
dsn="esmdr"
login=""
password=""
table="calls"
fields="pbxid, timeofcall, cd, ext, co, ring, dialnum, dialname, duration, accode, incoming, cost"
values="1, '%Y%M%D %h:%m:%s', '%c', '%E', '%C', %r, '%n', '%N', %d, '%a', %i, %F.%f"
sql="mssql2008"

See DBF output through ODBC for a Visual FoxPro DBF example.

EMAIL section

Beginning with version 0.5, eSMDR can send email notifications.

server

SMTP server DNS name.

port

SMTP port; the default is 25.

from

Sender name and address.

to

Default recipient. Multiple addresses may be separated by commas.

replyto

Reply address, useful when notifying a provider or PBX manufacturer.

organization

Your organization’s name.

cc

Addresses that receive a copy of every message.

username and password

Credentials when the SMTP server requires authentication.

[EMAIL]
server="smtp.domain.tld"
port=25
from="\"eSMDR MAIL SERVICE\" <esmdr@domain.tld>"
to="<admin@domain.tld>"
replyto=""
organization=""
cc="superadmin@domain.tld"
username=""
password=""

WATCHLOG section

WATCHLOG sends a daily summary confirming that logs are still being collected and faults monitored. A missing summary can indicate that the computer running eSMDR has stopped.

enabled

1 enables the summary; 0 disables it.

time

Time at which the summary is generated.

to

Optional recipient overriding the EMAIL section’s default.

[WATCHLOG]
enabled=1
time="03:30"
to="<admin@domain.tld>"

ALARM sections

PBX fault handling is supported for Panasonic KX-TDA, KX-TDE, and KX-NCP. Enable error-log printing in Maintenance Console menu 11.1 before configuring eSMDR. The simplest configuration emails every fault using the default EMAIL settings:

[ALARM]
email=1

Multiple ALARM sections can filter notifications by severity, error number, shelf, slot, and port.

email

1 sends a message; 0 does not.

level

MN for minor or MJ for major. Omit to process both.

errorcode

PBX error number.

shelftype

A space for a physical shelf or * for a virtual shelf.

shelf

Shelf number. TDE100/200 and NCP use 1; TDE600 may differ.

slot and port

Card slot and port number.

to

Recipient overriding the EMAIL section’s default.

template

UTF-8 text file. Its first line becomes the subject and the remainder becomes the body. Available substitutions are %M/%D/%Y %h:%m for date and time, %E error number, %T fault text, %L level, %V shelf type, %B shelf, %S slot, and %P port.

command

External command to run with the same substitutions. Prefix the command with cmd.exe /C when shell features such as redirection are required.

stop

Set to 1 to stop processing later ALARM sections after a match.

[ALARM2]
email=1
level="MN"
errorcode=10
shelftype=" "
shelf=1
slot=0
port=0
to="power_supply@domain.tld,admin@domain.tld"
template="alarm.txt"
command="cmd.exe /C echo %M/%D/%Y %h:%m ALM #%E %T %L %V%B%S%P >>errorlog%Y.txt"
stop=0

Every matching ALARM section is processed in order. This can send general notifications to the administrator, power faults to an electrical engineer, line failures to a provider, and major faults to PBX support.

WEB section

enabled

0 disables the web interface; 1 enables it.

ports

One or more comma-separated listening ports. A bare port listens on all interfaces; address-and-port notation such as 127.0.0.1:8080 restricts access to that interface.

maxcsvview

Maximum CSV file size loaded by the built-in table viewer, in KB. 80 is suitable for most systems. Increase it for a modern browser and fast computer, or reduce it if search and loading are slow.

adminpass

Initial password for the administrator, who can change service settings, monitor the PBX, and restart the service.

userpass

Initial password for a read-only user who can view non-secret settings and monitor the PBX.

The two passwords are required only for the first web-interface launch. eSMDR caches encrypted passwords; remove the plaintext settings from the INI file after a successful launch.

[WEB]
enabled=1
ports="8080"
maxcsvview=80
adminpass="noadmin"
userpass="nouser"

SERVICE section

This section normally needs no changes. To monitor multiple PBX systems, make a separate copy of eSMDR for each one and give each Windows service a unique name.

servicename

Unique internal service name on the computer.

servicedisplayname

Name displayed in Windows Services.

[SERVICE]
servicename="EsmdrService"
servicedisplayname="eSMDR READER"

Commands

esmdr -testemail

Creates and sends a test email using the configured settings.

esmdr -testemail queue

Creates a message, places it in the queue, and starts delivery. This is the closest test of normal operation.

esmdr -testalarm ALARM

Simulates a PBX fault handled by the named ALARM section.

esmdr -console

Connects to the PBX, collects logs, watches for faults, and prints calls and program events to the console. Always test the configuration in this mode before installing the service.

esmdr -install

Installs eSMDR as a Windows service. This is the normal operating mode.

esmdr -restart

Restarts the service to apply configuration changes. Do not use it to change the SERVICE section itself.

esmdr -remove

Removes the Windows service. Remove and reinstall the service when changing service parameters or updating the program.

esmdr -input <filename|pattern>

Processes saved PBX logs. This can populate a database with older calls. Standard wildcards are accepted; for example, esmdr -input *.log processes every .log file in the current directory.