xringd - The Linux extended modem ring server
] [ modem_device_file
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
(asynchronously) for the actual RING signal on the serial line.
- -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
- Run in debug mode (no daemon - logging = 100).
xringd does not run as a daemon and produces log messages on
- -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
- Disables ECHO on modem device upon opening. This will avoid
echo races reported with some modems.
- 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
- -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
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
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.
# xringd configuration file -- sample
-a /usr/local/audio/bin/play /usr/local/lib/sounds/ring.au
# 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
- The default configuration file.
- The default modem device used.
The following signals have the specified effect when sent to the xringd
- SIGINT, SIGTERM
- Clean exit the server.
- "Simulates" a RING as if it came from the
- 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.
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
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
If you activate a program which uses the modem after ringd it should normally
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
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!
Angelo Haritsis (email@example.com).