Documentation/isdn/README.diversion

   1 The isdn diversion services are a supporting module working together with
   2 the isdn4linux and the HiSax module for passive cards.
   3 Active cards, TAs and cards using a own or other driver than the HiSax
   4 module need to be adapted to the HL<->LL interface described in a separate
   5 document. The diversion services may be used with all cards supported by
   6 the HiSax driver.
   7 The diversion kernel interface and controlling tool divertctrl were written
   8 by Werner Cornelius (werner@isdn4linux.de or werner@titro.de) under the
   9 GNU General Public License.
  10
  11     This program is free software; you can redistribute it and/or modify
  12     it under the terms of the GNU General Public License as published by
  13     the Free Software Foundation; either version 2 of the License, or
  14     (at your option) any later version.
  15
  16     This program is distributed in the hope that it will be useful,
  17     but WITHOUT ANY WARRANTY; without even the implied warranty of
  18     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19     GNU General Public License for more details.
  20
  21     You should have received a copy of the GNU General Public License
  22     along with this program; if not, write to the Free Software
  23     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24
  25 Table of contents
  26 =================
  27
  28 1. Features of the i4l diversion services
  29    (Or what can the i4l diversion services do for me)
  30
  31 2. Required hard- and software
  32
  33 3. Compiling, installing and loading/unloading the module
  34    Tracing calling and diversion information
  35
  36 4. Tracing calling and diversion information
  37
  38 5. Format of the divert device ASCII output
  39
  40
  41 1. Features of the i4l diversion services
  42    (Or what can the i4l diversion services do for me)
  43
  44    The i4l diversion services offers call forwarding and logging normally
  45    only supported by isdn phones. Incoming calls may be diverted
  46    unconditionally (CFU), when not reachable (CFNR) or on busy condition
  47    (CFB).
  48    The diversions may be invoked statically in the providers exchange
  49    as normally done by isdn phones. In this case all incoming calls
  50    with a special (or all) service identifiers are forwarded if the
  51    forwarding reason is met. Activated static services may also be
  52    interrogated (queried).
  53    The i4l diversion services additionally offers a dynamic version of
  54    call forwarding which is not preprogrammed inside the providers exchange
  55    but dynamically activated by i4l.
  56    In this case all incoming calls are checked by rules that may be
  57    compared to the mechanism of ipfwadm or ipchains. If a given rule matches
  58    the checking process is finished and the rule matching will be applied
  59    to the call.
  60    The rules include primary and secondary service identifiers, called
  61    number and subaddress, callers number and subaddress and whether the rule
  62    matches to all filtered calls or only those when all B-channel resources
  63    are exhausted.
  64    Actions that may be invoked by a rule are ignore, proceed, reject,
  65    direct divert or delayed divert of a call.
  66    All incoming calls matching a rule except the ignore rule a reported and
  67    logged as ASCII via the proc filesystem (/proc/net/isdn/divert). If proceed
  68    is selected the call will be held in a proceeding state (without ringing)
  69    for a certain amount of time to let an external program or client decide
  70    how to handle the call.
  71
  72
  73 2. Required hard- and software
  74
  75    For using the i4l diversion services the isdn line must be of a EURO/DSS1
  76    type. Additionally the i4l services only work together with the HiSax
  77    driver for passive isdn cards. All HiSax supported cards may be used for
  78    the diversion purposes.
  79    The static diversion services require the provider having static services
  80    CFU, CFNR, CFB activated on an MSN-line. The static services may not be
  81    used on a point-to-point connection. Further the static services are only
  82    available in some countries (for example germany). Countries requiring the
  83    keypad protocol for activating static diversions (like the netherlands) are
  84    not supported but may use the tty devices for this purpose.
  85    The dynamic diversion services may be used in all countries if the provider
  86    enables the feature CF (call forwarding). This should work on both MSN- and
  87    point-to-point lines.
  88    To add and delete rules the additional divertctrl program is needed. This
  89    program is part of the isdn4kutils package.
  90
  91 3. Compiling, installing and loading/unloading the module
  92    Tracing calling and diversion information
  93
  94
  95    To compile the i4l code with diversion support you need to say yes to the
  96    DSS1 diversion services when selecting the i4l options in the kernel
  97    config (menuconfig or config).
  98    After having properly activated a make modules and make modules_install all
  99    required modules will be correctly installed in the needed modules dirs.
 100    As the diversion services are currently not included in the scripts of most
 101    standard distributions you will have to add a "insmod dss1_divert" after
 102    having loaded the global isdn module.
 103    The module can be loaded without any command line parameters.
 104    If the module is actually loaded and active may be checked with a
 105    "cat /proc/modules" or "ls /proc/net/isdn/divert". The divert file is
 106    dynamically created by the diversion module and removed when the module is
 107    unloaded.
 108
 109
 110 4. Tracing calling and diversion information
 111
 112    You also may put a "cat /proc/net/isdn/divert" in the background with the
 113    output redirected to a file. Then all actions of the module are logged.
 114    The divert file in the proc system may be opened more than once, so in
 115    conjunction with inetd and a small remote client on other machines inside
 116    your network incoming calls and reactions by the module may be shown on
 117    every listening machine.
 118    If a call is reported as proceeding an external program or client may
 119    specify during a certain amount of time (normally 4 to 10 seconds) what
 120    to do with that call.
 121    To unload the module all open files to the device in the proc system must
 122    be closed. Otherwise the module (and isdn.o) may not be unloaded.
 123
 124 5. Format of the divert device ASCII output
 125
 126    To be done later
 127