Project DiaStar Server - Administrator's Guide V2.1
From ProjectDiaStar
Contents |
DiaStar™ Media Engine
The DiaStar™ Media Engine has already been installed as part of the ISO install, but for full operation some further configuration is needed.
You will need to install a DiaStar Media Engine license based on your required functionality (see Project DiaStar Server - Licenses).
License
Once you have obtained your DiaStar™ Media Engine license, copy it into the /usr/dialogic/data directory.
To install the license you need to connect to the DiaStar™ Media Engine Command Line Interpreter:
# telnet localhost
(user: root, password: public)
Once in the CLI, first make sure that the ipmedia subsystem is stopped:
CLI> conf system ipmedia stop
This may take a few minutes. When a confirmation message is seen, the license can be applied:
CLI> conf license activate <license_file_name.lic>
Configure
Further configuration depends on the type of system being built. Select the type of system you want to configure:
- Project DiaStar Server - ISDN Configuration
- Project DiaStar Server - SS7/SIGTRAN Configuration
- Project DiaStar Server - SIP and Multimedia Configuration
If the system used for the DiaStar Server will be also be used for Asterisk, make sure that the Asterisk dahdi_dummy driver is not installed. The DiaStar™ Media Engine also uses the system real time clock, but at a different clock speed. Remove it with:
# modprobe -r dahdi_dummy
If this is not done, the DiaStar™ Media Engine services will fail to start
Configuring the DiaStar™ Server
For correct operation of your DiaStar Server you need to create a config file. You will need to re-create this configuration file every time you install a new license. This includes the 4 port trial license.
The service tool is used to create the file /etc/diastar/diastar.conf and starts the service.
# service diastar config --<options>
Supported options:
- --isdn (mutually exclusive with --ss7)
- --ss7 or --ss7=<type><board-count> (mutually exclusive with --isdn)
- --sip
- --conf-parties=N
See Command Line Options for further details on these options.
Configuration File Generation Examples
Starting DiaStar with the standard 4 port trial license
This option will allow for four ports of IVVR and video conferencing:
# service diastar config --sip --conf-parties=4
SIP gateway / Multimedia server
# service diastar config --sip
ISDN gateway / SIP gateway & Multimedia server
# service diastar config --isdn --sip
SS7 gateway
# service diastar config --ss7
To generate configuration for SS7 dk devices a value should be added to the --ss7 option. This takes the form: <type><board-count> where type is E for E1 or T for T1 spans and board-count is the number of spans. For example:
# service diastar config --ss7=T3
would generate three boards: dkB1, dkB2, dkB3 each with 24 channels.
Note: The number of SS7 circuit groups found in the /usr/dialogic/SS7/config.txt file must match the number of dti E1 spans in the DiaStar config file. If you are using fewer circuit groups than spans, only channels on those accounted for in config.txt will open. Unwanted dti spans can be deleted or commented out in the DiaStar config file. You also need to adjust the "group" parameter to account for the dti channels that were eliminated. For example, "default=1-120" becomes "default=1-60" if 2 E1 spans are eliminated.
SIP Configuration
Once the --sip option has been used to create a DiaStar configuration file, some further adjustment of SIP parameters may be desired. Here is the default set of values that are generated:
[sip] ; Each subsection begins with a board name parameter. ; The name takes the form "iptBx" where x is 1..n board = iptB1 ; maxcalls sets the maximum number of concurrent calls. maxcalls = 30 ; bindaddr sets local IPv4 address. bindaddr = 192.219.17.119 ; bindaddr sets local port number [5060]. bindport = 5060
A single "virtual board" is set, which uses the eth0 device which is set to the IPv4 address specified. SIP signaling will be expected over UDP port 5060, and a maximum of 30 concurrent calls are possible.
The most common changes here is a change to the SIP port and an adjustment of maximum calls on that device. Note that maxcalls must not exceed the number of licensed SIP ports for the system or DiaStar will fail to start.
If a SIP registrar is used, the following parameters must be uncommented to register DiaStar with it:
; registraraddr is the IPv4 address of the Registrar. registraraddr = 192.168.20.15 ; registrarport is the SIP port number on the Registrar [5060]. registrarport = 5060 ; registrarttl is registration time-to-live period in seconds. registrarttl = 1800 ; register is used to define an entity to be registered. ; It has four comma seperated values: name,identity,password,realm ; Multiple entities may be registered by using separate lines. register = 1000,sip:1000@example.com,secret,diastar
All four parameters must be supplied for the register entry. They are defined as follows:
- name - SIP user name
- identity - full SIP URI for user name
- secret - password for SIP digest authentication
- realm - authentication realm
More information on DiaStar authentication can be found in section 4.23 here. The authorization parameters are sent only when challenged by the registrar and should be set to dummy values if authorization is not needed.
A SIP outbound proxy is often used in conjunction with a SIP registrar. Uncommenting and adjusting these lines will forward outbound SIP call requests to an outbound proxy server:
; proxyaddr is the IPv4 address of the proxy server. proxyaddr = 192.168.20.15 ; proxyport is the SIP port number on the proxy server [5060]. proxyport = 5060
SS7 Configuration
Most SS7 and SIGTRAN configuration is not directly done in the DiaStar config file. Instead, it is done as part of setting up the DiaStar Media Engine. See Project DiaStar_Server - SS7 Configuration
Video Conferencing Configuration
The --conf-parties=N option is used to generate configuration for a single N party conference. This shows all options and can be used as a base for customisation.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; The following section is used for conferences. ; This section is sub-divided with each subsection defining one virtual board. [conference] ; Each subsection begins with a board name parameter. ; The name takes the form "mcxBx" where x is 1..n board = mcxB1 ; The id parameter is a globally unique number used by the client to identify a ; conference. Multiple conferences may be defined under each board sub-section. ; Its value comprises of one or more integers that identify individual ; conferences to which subsequent parameters are applied. ; e.g. id = 1,2,3 or id = 1-4 id = 1 ; mode defines the how the conference is managed: adhoc | controlled. mode = adhoc ; max_parties defines the maximum number of parties in the conference. max_parties = 6 ; layout defines the number of tiles to display: 1,4,6 or 9. layout = 6 ; caption determines if the caller's id is overlaid on their image. caption = yes ; duration sets the time in milliseconds that the caption is displayed. Use ; 'infinite' without the quotes to display the caption for the entire call. duration = 20000 ; beep determines is a tone is played when a party joins/leaves a conf. beep = yes ; clamp_dtmf determines if dtmf digits are suppressed. clamp_dtmf = yes ; agc determines if automatic gain control should be used. agc = yes ; ec determines if echo cancellation should be used. ec = yes
Two conference modes are available - 'adhoc' and 'controlled'. The mode is set using the 'mode' parameter within a conference definition within the diastar.conf file. (see below)
An adhoc conference may be entered and exited at any time, by any participant. All conferees are equal participants.
A controlled conference has different roles for each conferee. The conference follows certain rules:
- Only one controller per conference is allowed
- A controlled conference must have a controller call active before other callers will be admitted
- A non-controller participant take one of two other roles: presenter or attendee
- Presenters (default) are full participants whose media are included in the conference output
- Attendees are like 'listen-only' audio conference participants. They receive the conference output but do not have their media included in it.
- A controller party must be established in order for presenters and attendees to be admitted to the conference
- The controller's video is shown only when no presenters are present. This allows the controller to play a image/video to the attendees while they wait for the presenter(s) to arrive. The controller's audio is always included in the mix and should be muted locally as necessary.
- When the controller call ends the conference itself ends and all other parties are automatically hung up
Remember that the DiaStar service must be restarted for changes to go into effect:
> service diastar restart
Custom Tone Detection
As part of the Call Progress Analysis feature DiaStar can detect single tones and dual tones, with optional cadences.
The tones are defined using templates that are read in from files stored in a dedicated directory, the default location being /etc/diastar/tones.d. DiaStar reads in all files with a .conf extension. Each file may define multiple templates defined by familiar ini file style syntax.
The section name uniquely identifies the a template and is used to identify the tone in CPA results.
Template parameters (vary depending on mode):
freq1 frequency 1 in Hz fq1dev frequency 1 deviation in Hz freq2 frequency 2 in Hz fq2dev frequency 2 deviation in Hz ontime tone-on time in milliseconds ontdev tone-on time deviation in milliseconds offtime tone-off time in milliseconds offtdev tone-off time deviation in milliseconds repcnt number of repetitions of the cadence
- Frequencies must be in the range 300Hz to 3k5Hz.
- Dual tones with frequency components closer than approximately 63Hz cannot be detected, for these cases a single tone definition should be used.
- The minimum ontime and offtime for cadence detection is 40ms on and 40ms off.
Example
; This file defines tone detector templates for use with DiaStar. ; ; Single tone [1kHz] freq1 = 1000 fq1dev = 20 ; Dual tone [C5A5] freq1 = 523 fq1dev = 20 freq2 = 794 fq2dev = 20 ; Single tone, cadenced. [1kHz-cadenced-500-500] freq1 = 1000 fq1dev = 20 ontime = 500 ontdev = 50 offtime = 500 offtdev = 50 ; Dual tone, cadenced [C5A5-cadenced-500-500] freq1 = 523 fq1dev = 20 freq2 = 794 fq2dev = 20 ontime = 500 ontdev = 50 offtime = 500 offtdev = 50
Media Files
DiaStar uses a special directory layout to manage media files. The base of the directory structure is /var/lib/diastar/media, which may be changed using the path parameter within the media section of the diastar.conf file:
[media] ; path defines the name of the base directory for media files. path = /var/lib/diastar/media
Each codec has its own directory and in the case of video codecs, directories for different formats/sizes. (Currently QCIF and CIF).
/var/lib/diastar/media/
`-- en_US
|-- h263
| |-- CIF
| |-- QCIF
| `-- SUB-QCIF
|-- mpv4-es
| |-- CIF
| |-- QCIF
| `-- SUB-QCIF
|-- jpeg
| |-- CIF
| |-- QCIF
| `-- SUB-QCIF
|-- pcma
|-- pcmu
`-- vox
VOX files must be encoded as: 8kHz, 16bit signed-linear pcm (equivalent to Asterisk's .sln format).
Here is an example of a directory structure for an application in US English called "pitching_demo" which contains video clips for H.263 and MPEG4 video and PCM audio:
/var/lib/diastar/media/en_US/h263/CIF/pitching_demo/main_menu_000.vid /var/lib/diastar/media/en_US/h263/QCIF/pitching_demo/main_menu_000.vid /var/lib/diastar/media/en_US/mpv4-es/CIF/pitching_demo/main_menu_000.vid /var/lib/diastar/media/en_US/mpv4-es/QCIF/pitching_demo/main_menu_000.vid /var/lib/diastar/media/en_US/vox/pitching_demo/main_menu_000.pcm
When playing a media file DiaStar will choose the file that most closely matches the codecs requested by the external SIP call.
Language support
The directory structure includes a language component. The default language is defined as en_US, which may be changed using the language parameter within the media section of the diastar.conf file:
;language defines the default language that is used when none has been specified by the client. Forms part of the file path. language = en_US
The default language is used when the Woomera client does not specify a language in a play/record request, in the case of Asterisk the channel driver will always pass the channel's language variable.
Media File Management
When running DiaStar as an appliance it may useful to provide users with remote access to the media files. It is recommended that such access is limited to authenticated users with file system access restricted to the media directories only. One possible solution to this to use WebDAV. Web-based Distributed Authoring and Versioning is a set of extensions to the Hypertext Transfer Protocol (HTTP) that allows computer-users to edit and manage files collaboratively on remote World Wide Web servers. Here are instructions for setting up WebDAV on an Apache Web Server.
Tools and Utilities
The following open source packages can be useful for working with audio and video media files - converting and editing raw media preparing it for use with DiaStar.
Audio tools
Video tools
The Tech Briefs section of the DiaStar Wiki contains further information on using various tools for multimedia production.
Running the DiaStar™ Server
The preferred method of running DiaStar is to use the service tool.
Using the service tool
# service diastar start # service diastar stop # service diastar restart # service diastar status
Alternatively, DiaStar can also be run from the command-line as either a console application or as a daemon. Console mode can be especially useful when debugging.
As a console application
# diastar --console --conf=diastar.conf
Additional examples:
# diastar --console -v --conf=diastar.conf # diastar --console -v --logdir=/var/log/diastar --conf=diastar.conf # diastar --console --probe --sip --conf=sip.conf
As a daemon
# diastar --conf=diastar.conf
Additional examples:
# diastar --verbose --logdir=/var/log/diastar--conf=diastar.conf # diastar
DiaStar Server Command Line Options
Command line options:
-h, --help Display this information.
--version Display this applications's version.
-v, --verbose Run with maximum logging.
-c, --console Run as a console application.
--log-dir Directory used to store log files.
--media-dir Base directory for media files.
-p, --probe Probe hardware and generate configuration data.
--isdn Generate configuration data for isdn devices (default).
--ss7 Generate configuration data for ss7 devices instead of isdn.
This option may also be used to generate configuration for
ss7 dk devices by appending a value to the --ss7 option.
This takes the form: <type><board-count> where type is E for E1
or T for T1 spans and board-count is the number of spans.
For example: --ss7=T3 would generate three boards: dkB1,
dkB2, dkB3 each with 24 channels.
--sip Generate configuration data for sip devices.
--conf-parties Generate configuration data for an N party conference.
--conf Full pathname of the configuration file.
--woomera-address IPv4 address that the server listens on.
--woomera-port Tcp port that the server listens on.
- Note, the options --isdn and --ss7 are mutually exclusive.
This information is also available in the man page. See: man diastar.
DiaStar™ Server Logging
The default DiaStar™ server log location is /var/log/diastar.
Multiple log files will be created and each capped at 2MB.
Note that the initial installation is done with logging set to "verbose".
If densities greater than 120 channels are being run, this should be changed in /etc/sysconfig/diastar by defining "verbose=no" and restarting the DiaStar™ service.
