umd.conf.7

multi-line Adjunct Communication Server

.TH "umd.conf" "8" "1999" "ACS Voice Response" "Open Source Telecom" 
.PP 
.SH NAME 
\fBumd.conf\fP - IVR server and utilities configuration file
.SH DESCRIPTION 
This file, normally found in \fI/etc/umd.conf\fP, holds configuration
paramaters that are used by the IVR server and also various utilities.
This file is parsed by the OST keydata functions, and is organized in
\fB[SECTIONS]\fP denoted with \fB[]\fP's.  Lines that are empty
or that start with \fB#\fP are ignored as comments.  Most entries are in
the format of \fBkeyword\fP=\fIvalue\fP.
.SH [PATHS]
This section specifies the location of key files and directories for the
IVR server and utility applications.
.TP
.B pidfile\fP=\fIprocess-id-file\fP
Pathname to hold the process id of the IVR server.  This can be used by
external utilities to signal or kill the server.
.TP
.B runfile\fP=\fImemory-map\fP
A memory mappable file that holds the running status for each IVR
telephony port.  This is dumped by \fBumdstat\fP.
.TP 
.B ctrlfile\fP=\fIfifo-commands\fP
A named pipe (fifo) used to send commands to the IVR server.  The commands
that may be sent to the IVR fifo are defined in \fBumdctrl\fP
.TP
.B scripts\fP=\fIscript-directory\fP
Base directory for IVR script files.
.TP
.B prompts\fP=\fIprompt-directory\fP
Base directory for IVR prompts and prompt libraries either distributed
with ACS or installed by related packages.  This should not be confused
with /fB/var/ACS/fP, where user recorded prompts and mailbox data may be
held.
.TP
.B lockfiles\fP=\fItty-access-lockfile...\fP
This optional feature may be used when IVR ports are sharing a telephone
line with modems managed under mgetty.  When the server starts, it will
wait for and assert each of the specified lockfiles before it will accept
any telephone calls.
.TP
.B libexec\fP=\fItgi-programs\fP
Execution directory for "libexec" script command and "Telephony Gateway
Interface" programs.
.TP
.B datafiles\fP=\fIworking-space\fP
Base directory for storage of dynamic data such as user recordings,
mailboxes, etc.  Usually set to \fI/var/ACS/fP.
.TP
.B schedule\fP=\fIschedule-file\fP
Path to the IVR scheduling file for script dispatch of incomming calls
based on line, time of day, day of week, etc.  This is normally set to
\fI/etc/umd.sched\fP.
.SH [THREADS]
This section is used to adjust the behavior of threads within the running
IVR server.  Scheduling priorities behave like "nice", where negative
values increase cpu priority.
.TP
.B priority\fP=\fIthread-priority\fP
Default priority adjustment for threads internally created by the IVR
server.  This assumes the main thread and any driver generated
callback threads already operates under the priority specified by umd at
the command line, or with nice.
.TP
.B scheduler\fP=\fIscheduler-priority\fP
Specify the thread priority adjustment for the IVR scheduler thread.  The
scheduler thread is used to periodically reload the \fI/etc/umd.sched\fP
file and evaluate where incoming calls will dispatch.  This thread can
usually operate at a much lower priority than other services. 
.TP
.B gateways\fP=\fIgateway-pool\fP
Specify the number of simultaneous "shell" invoked Telephony Gateway
Interface pooled processes available for concurrent execution.  This can
be any number up to the number of active telephony ports in the server.
Generally a number smaller than the port capacity is often recommended
both to control process loading and to limit total system resources needed
for simple applications.  Never set below "1" even if no "shell" commands
are used in your scripts.
.TP
.B stack\fP=\fIpages\fP
Request that all memory pages will be locked and specify the size of the
stack to use for "testing" to assure sufficient memory exists for future
stack needs, in 1K increments.
.TP
.B service\fP=\fIpriority\fP
Specify the priority level of a service/callback thread.  Service callback
threads are used in some of the platforms to monitor and dispatch
telephony events.  Generally you do want to make the service threads run
at a higher priority than the default.
.SH [LDAP]
In the future, ACS will use LDAP services to manage mailbox directories
and perhaps also for message stores.  This section simply identifies how
to communicate with the LDAP server.
.TP
.B config\fP=\fIconfig-path\fP
Specifies where the LDAP config file is stored.
.TP
.B context\fP=\fIcontext-string\fP
Specifies where on the LDAP tree to "root" and find all ACS related
entries.
.TP
.B servers\fP=\fIhostnames...\fP
Specifies which hosts (servers) to contact for all LDAP operations.
.SH [AUDIO]
This section controls various internal options related to buffering,
recording,  and playback of audio data.  Some of these options may be
server may only apply to specific IVR servers depending on the hardware
used.
.TP
.B buffers\fP=\fIbimpulse-size\fP
Specifies the "impulse" size of audio buffers.  Impulse sizes depend on
the hardware involved.  With the Pika, an impulse is a optimized DSP
buffer (returned by PK_AUDIO_BufferSize for the current codec) and
generally represents 120ms of audio data.  A larger buffer size means
that audio files will be streamed in multiple impulse intervals.  The
buffer size ultimately represents how large each read()/write() call will
be and how often i/o calls will be performed when streaming audio data.
For the Pika, a value of 8 represents 1 second.
.TP
.B frames\fP=\fIframe-count\fP
This specifies how many frames of "buffers" will be kept active in memory
for each streaming session.  Frames act as a "sliding window" with buffers
specifying the size of each frame.  This allows the realtime DSP subsystem
in a threaded system to keep recording input even while the disk i/o
thread is delayed while performing a read or write call.  Frames gaurentee
that audio performance will be smooth and real-time even when disk i/o may
lag.  A frame value of between 2 and 4 is generally considered acceptable.
.TP
.B min\fP=\fImin-impulses\fP
This specifies the minimum size of a newly recorded audio sample.  Any
recording that is shorter than this minimal size will be discarded.  This
value is specified in impulse size, just like for buffers.
.TP
.B trim\fP=\fItrim-size\fP
Trimming occurs on a newly recorded audio sample to try and remove a DTMF
tone from a DTMF key that may have been pressed to terminate recording.
Since DTMF detection is never immediate, part of the keypress would likely
otherwise end up as part of the recording.  Similarly, any noise from a
line drop will be trimmed.  As the value is specified in impulse frames, a
value of 1 trims 120ms from the end of the recorded sample on a Pika card.
Generally, trimming should be used for 120ms or less.
.TP
.B timer\fP=\fItimeout-seconds\fP
This is used as a default timeout value in the script interpreter where
a given command that requires some timeout (such as collect for digit
collection) is not provided any value.  This is also the default timeout
value to use when recording messages.
.TP
.B encoding\fP=\fIcodec\fP
Specify the default data encoding format to use for recording and/or
playback when no format is otherwise specified via the requested filetype 
extender, or a header (such as sun .au files have).  Valid encoding
formats include \fIlinear\P (pcm16), \fIpcm\fP (8 bit pcm), \fIg721\fP,
\fIg723\fP, \fIalaw\fP, and \fIulaw\fP.  The expected default is mu-law.
.TP
.B sampling\fP=\fIsampling-rate\fP
Specify the effective sampling rate to use when no sampling rate is
specified either via the requested filetype extender, or a header (such as
sun .au files have).  Valid sampling rates include 4khz, 6khz, 8khz, 
and 11khz.  The expected default is 8khz.
.SH [PHONE]
This section is used to hold values for Linux /dev/phone devices used by
the umd_phone server.  This holds a variety of parameters including the
range of devices that umd_phone should use, as well as common properties
that may be set for those devices.
.TP
.B prefix\fP=\fI/dev/phone\fP
Specify default prefix path for all "phone" devices.  This should normally
not be changed.
.TP
.B first\fP=\fIdevice-number\fP
Specify the first /dev/phone to use when allocating ports for the server.
Normally the first device used is /dev/phone0, but if you wish to reserve
the first port(s) for another application (such as a QuickNet phonejack
used on the same machine) then you can skip to a later device.
.TP
.B lines\fP=\fInumber-of-lines\fP
This specifies the total number of lines that the server should attempt
to initialize.  It is possible that less lines will be found and installed.
It is usually safe to set this number fairly high and let the server
auto-identify what ports are actually available.
.B wink\fP=\fIwink-duration\fP
Allows setting the /dev/phone wink duration to a value other than the
default of 360 milliseconds.  All values are in milliseconds.
.TP
.B depth\fP=\fIbuffers\fP
Specify the number of kernel buffers to apply per audio frame.  This value
is used for standard playback and recording.  The default value is 2.  A
high value will increase smoothness of audio, especially for generic
recording of messages and playback of audio prompts.
.SH [SCRIPT]
This section can generally be used to specify runtime "constants" that can
be changed without having to alter scripts.  These entries are parsed
whenever a script requests a \fB$keyword\fP option.  Things like the
number of digits used for extension numbers or mailboxes may typically
be specified here.
.SH SEE ALSO
.BR umd.sched (7) ,
.BR umdctrl (8) ,
.BR umdstat (8) ,
.BR umdstop (8)
.SH AUTHOR 
David Sugar ([e-mail])
.PP