Provided by: xringd_1.20-25_i386 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)