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).

                                                                                                       XRINGD(8)