NAME
xringd - The Linux extended modem ring server
SYNOPSIS
xringd [ options ] [ modem_device_file ]
DESCRIPTION
The xringd Linux extended Ring server will listen on a modem device for
specific ring-delay patterns (sequences). Each sequence, when fully
recognised, will execute a command you have chosen (subject to usual
unix permissions). Delays are in fact delay ranges. Sequences and
commands are read from a a configuration file. xringd does not disturb
your other modem programs, not even your getty. It coexists with them.
xringd probes (asynchronously) for the actual RING signal on the serial
line.
OPTIONS
-a command_on_each_ring
Run this command on every ring. Use perhaps to replace your
boring phone ring.
-c config_file
Use an alternate configuration file. The default is
/etc/xringd.conf
-d Run in debug mode (no daemon - logging = 100). xringd does not
run as a daemon and produces log messages on standard error.
-h | -?
See a mini usage info
-i msecs-ignored
If consecutive rings have a time (in msec) distance less than
this one, they are taken as one. For countries where a ring
creates two sounds and modems that subsequently cause two
changes on the serial RI line. Use this option to make two near
RIs look as one to xringd. A value of 100-800 will most likely
be the most appropriate.
-l loglevel
Logging level. Default=1. Use 10+ for more info. When running as
daemon you can use -l 10 or 100 to get debug messages via
syslog(LOG_DEBUG, ...). 0 means NO logging at all.
-m modem_device_file
The modem device file (can also be given as the final argument).
-e Disables ECHO on modem device upon opening. This will avoid echo
races reported with some modems.
-n Performs only a syntax check of its configuration file. It
implies -d. Try this first when you write a new configuration
file. xringd does not become a daemon and produces log messages
on standard error.
-t init_time
After a reset (or the first time it is run), the time (in
seconds) to wait until rings are accepted. Default: 15
CONFIGURATION FILE
The configuration file consists of lines of the following format:
R secs[-secs] [ R secs[-secs] ] ... : command
Each line is related to a sequence(pattern) that can be potentially
matched. The command at the end gets executed if the sequence was fully
matched. A full match is found if the delays between the rings are
within the delay ranges given in the configuration line of a sequence.
A full match will also reset the state machine. It will start accepting
new rings as when run the first time. R means ring and it should
always be the first symbol in a sequence.
Comment lines start with a ‘‘#’’ symbol at the beginning of the line.
Empty lines are ignored.
Note that command lines options can also be included in the config
file. A line should start with the ’-’ of an option. See example
below. Options -c and -n are ignored in the config file. Options in
the configuration file take precedence over the ones in the command
line.
EXAMPLE CONFIGURATION
# xringd configuration file -- sample
#
-a /usr/local/audio/bin/play /usr/local/lib/sounds/ring.au
-l 100
#
# 2 rings 10-16 sec apart followed by 30 secs silence
R 10-16 R 30 : /etc/ppp/ppp.start office1
# 3 rings 10-20 sec apart followed by 20 secs silence
R 10-20 R 10-20 R 20 : /etc/ppp/ppp.start office2
# 2 nearish rings then 1 ring after 20-26 secs, silence for 30 secs
R 1-5 R 20-26 R 30 : /usr/local/bin/turn-heater on
FILES
/etc/xringd.conf
The default configuration file.
/dev/modem
The default modem device used.
SIGNALS
The following signals have the specified effect when sent to the xringd
process.
SIGINT, SIGTERM
Clean exit the server.
SIGUSR1
"Simulates" a RING as if it came from the modem.
SIGHUP Restart the internal machine ignoring any current state. Reread
the config file. Close and reopen the modem device. If a syntax
error is found in a line all the following lines are ignored. So
when you restart, make sure you look at the log for any reported
errors. A better way is to always "parse" your config file with
"xringd -n" to check its syntax first.
NOTES
At the moment, xringd is device dependent on Linux kernel 1.3.48+ and
serial devices that support the TIOCMIWAIT, TIOCGICOUNT ioctl(2) calls.
These were added by the same author to the Linux kernel so that a
process can wait on a modem DCD,RI,DSR,CTS change on a serial port and
can also read a kernel count of the interrupts on each one of these 4
lines. RI was used for this program. (Other possibilities exist in
using this ioctl for instrumentation projects.) Note that these ioctls
are only implemented for 16xx0 uarts now (Jan96).
You have to use a proper serial cable for this to work. A cable with
all pins properly connected to your modem (especially the RI line for
this program!) and serial port will save you any trouble. Internal
modems should normally work.
If you activate a program which uses the modem after ringd it should
normally flush the input buffer. In many cases you will have a few
"RING" strings in your serial tty buffer that will most likely confuse
a dialup script (eg. chat).
The richness of the ring-delay pattern "language" is not great.
However, you certainly have many possibilities. Beware of overlaps
though, and always have something that will "unlock" any current
sequence (eq. 4 consecutive rings that safely exit from any current
state).
If someone calls in while you are on the delay phase of your "pattern"
then you are obviously out of luck.
Only tone dialing phones allow quick dial that can meet short timing
restrictions possibly imposed by your configuration file. Make sure you
use the redial button on the calling phone if there is one - you will
be able to "dial" in about a second. Pulse dialers may introduce
unexpected delays. If they are your only choice, use longer delays and
wider delay ranges.
It was reported by a user that the "rings" you hear on the calling
handset do not directly correspond to the ones actually heard on the
receiving end. In the tests done with xringd in a few countries, the
number of rings remained the same on calling and called set. Just leave
each one of the rings you hear on the calling end to "settle" (do not
break them before they finish). A delay between a ring heard on the
caller set and the equivalent one on the called one was noticed but
causes no problem for xringd. Feel free to send me your comments on
this.
Many getty-like programs may be configured to pick up the phone on the
first ring. Obviously, this will make xringd minimally useful. Make
your getty to reply after 2-4 rings so that you have many possibilities
open for xringd.
pppd (and probably some other programs) like to hold a tty in exclusive
mode. Make sure you start xringd before such programs, otherwise it
won’t be allowed to open the modem device. Also, when such a program
closes it may leave the line hung up. You need to restart (kill -HUP)
xringd in such a case. It does not make sense to run xringd on a line
which is permanently used for PPP/SLIP - such a line never "rings"!
Spurious interrupts (and thus pseudo-RINGs) may occur during modem
switch on/off; run xringd after your modem is switched on.
It is highly recommended - for security reasons - to make the
configuration file inaccessible (even for read) to anything but xringd.
Treat it as a shadow-password-like file. It is very easy for anyone to
call your number and activate a command, if they know a RING-delay
sequence "password". So try not to disarm your home-alarm via it. You
have been warned!
AUTHOR
Angelo Haritsis (ah@doc.ic.ac.uk).