Provided by: xringd_1.20-27build1_amd64 bug

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)