Provided by: isdnutils-base_3.12.20071127-0ubuntu11_amd64 bug

NAME

       divertctrl - set/query ISDN diversion services for (E)DSS1 protocol

SYNOPSIS

       divertctrl [wait] command driverid ...

DESCRIPTION

       divertctrl  is  used  to  de/activate call diversions and query actual activated diversion
       rules.  The i4l diversion services only work  using  the  (E)DSS1  D-channel  protocol  in
       conjunction  with  the  HiSax  passive card driver. For using the services the global isdn
       drivers need to be compiled with support for the  diversion  services.   Additionally  the
       dss1_divert  module  has  to  be  loaded.  This  module  doesn't  require  nor support any
       parameters  at  load   time.    After   successfully   loading   the   module   an   entry
       /proc/net/isdn/divert  should appear in the filesystem. When called without any parameters
       the divertctrl program outputs a short help screen. Otherwise the first parameter needs to
       be  a  command followed by a valid driver id. The command may be preceeded by the optional
       wait keyword specifying the program to wait until the desired command could  be  completed
       or  failed  returning  the  result  via  the  exitcode. Otherwise the programm immediately
       returns after invoking the desired action which may not be completed at this moment.
        For some commands the value "-" may be used as a valid driver id specifying all available
       drivers.  The driver id is equivalent to the id parameter specified when loading the HiSax
       driver for a  particular  card.   All  further  parameters  are  command  dependant.   The
       divertctrl program may only be used with root access for security reasons.

       The diversion services for i4l may be used in two independant ways:

1. Static call diversion

       First  possibility  to  handle  diversions  of  incoming  calls is to use static diversion
       provided inside the providers exchange.  A static  diversion  once  activated  inside  the
       providers  exchange  requires  no interaction with i4l. The machine may even be shut down,
       but the diversion keeps active until it is explicitely deactivated.  The  divertctrl  tool
       allows  to  set/reset and query such static rules if the service is supported and has been
       subscribed at the providers side.  This services are only available in some countries like
       germany.  In  other countries (like the netherlands) keypad control is used to de/activate
       such static rules.  Static rules  may  be  set/reset  and  queried  independantly  by  MSN
       (multiple  subscriber  number),  basic service (telephony, digital data, ..) and diversion
       procedure. Three diversion procedures are defined in the ETSI specs and may be  used  with
       the i4l diversion services:

       CFU   (call   forward   unconditional)   is  a  procedure  diverting  all  incoming  calls
       unconditionally for the programmed MSN and basic service. The call will never be announced
       at your side until CFU is deactivated again.

       CFNR  (call  forward  not  reachable)  is a procedure diverting all incoming calls for the
       programmed MSN and basic service after locally signalling and waiting  a  certain  timeout
       period.  If the call is not answered during this timeout period it will be diverted to the
       new destination. The timeout period is fixed in the providers exchange and is  normally  3
       rings (about 12 to 15 seconds).

       CFB (call forward busy) is a procedure diverting all incoming calls for the programmed MSN
       and basic service when all local resources taking the call are exhausted and busy.

Commands for handling static call diversions

       activate driverid <cfu,cfnr,cfb> msn service destination

       Activate a static diversion for the given driver, msn and service diverting  the  call  to
       the  specified  destination. All parameters need to be supplied, no wildcards are allowed.
       Only one of the three diversion procedures cfu, cfnr, cfb must be supplied.  The value for
       the  service  may  be taken from the table of numeric codes of basic services. The value 0
       specifies all available/subscribed services.

       deactivate driverid <cfu,cfnr,cfb> msn service

       Deactivate a static diversion for the given driver, msn and service. All  parameters  need
       to  be supplied, no wildcards are allowed. Only one of the three diversion procedures cfu,
       cfnr, cfb must be supplied.  The value for the service may be  taken  from  the  table  of
       numeric codes of basic services. The value 0 specifies all available/subscribed services.

       interrogate driverid <cfu,cfnr,cfb> [msn] [service]

       Query  static  diversions  for  the  given  driver, msn and service. Only one of the three
       diversion procedures cfu, cfnr, cfb must be supplied. The msn and service  parameters  are
       optional.  The value for the service may be taken from the table of numeric codes of basic
       services. The value 0 specifies all available/subscribed services.  If msn and/or  service
       parameters  are  not  specified all matching diversions are reported via stdout. But it is
       advisable always to specify all parameters to keep the list  as  short  as  possible.  All
       known  providers exchanges refuse to return diversion lists longer than 256 bytes. In this
       case an empty response is generated by the exchange even if there are diversions active !

2. Dynamic call diversion

       Additionally the i4l diversion services offer a more flexible possibility to control  call
       forwarding.  Using the dynamic call diversion the user has the possibilty to specify rules
       for call forwarding by additional criterias. The reaction  to  an  incoming  call  may  be
       dependant  of MSN, basic service, caller id, local subaddress, caller subaddress and local
       resource (busy) state. The parameters may  be  specified  with  wildcards,  so  that  call
       criterias  may  be  grouped  to match.  Additionally the diversion actions may be supplied
       with a precise timeout value which is not dependant on any providers defaults. In order to
       work, the supplumentary service CD (call deflection) has to be available and subscribed at
       the providers exchange.  The dynamic diversion services  are  fully  handled  inside  your
       machine,  so  it  must  be  powered  up  and  activated  for the required purpose. After a
       successfull dynamic diversion (so called deflection) no local line resources are required.
       The lines are free for further incoming calls.

       Dynamic  Call  deflection  is  controlled by a rule chain the user has to supply using the
       divertctrl program. When an incoming call arrives, calling data is  compared  against  the
       rules  in the chain. If an incoming call matches a rule, this rule is taken to execute the
       desired action. All following rules are ignored.  If there is no rule match the  diversion
       services simply ignore the call.

Commands for handling dynamic call diversions

       flushrules [driverid]

       Flushes  (deletes)  all  rules  for  the selected driver. If no driverid is given or it is
       specified as wilcard - all rules for all drivers are removed.  It  is  advisable  to  call
       this command first when a complete new ruleset is to be generated, to avoid conflicts with
       previous set rules.

       appendrule driverid action msn si1 si2 callerid screen delay option destnumber

       This command appends a single rule at the end of the existing rule  chain.   If  the  call
       arrives  through  the desired driver, addresses the selected msn, si1, si2 and matches the
       desired callerid and option the specified action  is  executed.   A  value  of  -  may  be
       specified  for  the  driverid  to match the rule for all available drivers. The msn may be
       specified with a trailing - wildcard.  for example the value 123 only matches an  incoming
       call  to  msn  123,  but specifying 123- matches all msn starting with 123 followed by any
       digits or subaddresses which will not verified. If only - is specified  the  rule  matches
       all  msn  and  subaddresses.   If your isdn line supports subaddressing it is advisable to
       terminate all msn values with a - because the msn  check  includes  a  possibly  available
       subadress  which  then  may  be  reported as 123.456 for msn 123 with subaddresses 456 for
       example.  Subaddressing is a special DSS1 feature not  available  in  most  countries  and
       normally needs to be specially subscribed. So most people need not to think about it.  The
       value of si1 represents the numeric code of the desired and checked basic service for  the
       incoming  call.  This  value  may  be  selected  from  the table below or just the value 0
       specified for all services to match.  The value of si2 represents  an  additional  service
       indicator  for  high layer compatibilty and is only included for completeness. Just set it
       to 0 at the moment.  The callerid must match  the  number  of  the  caller  including  the
       subaddress if available. Again the special wildcard - may be used to match specific groups
       of numbers.  Additionally a simple value of 0 may be specified. In this case the rule will
       match  only calls coming in without a caller indentification. This will be the case if the
       caller originates from a network not supporting callerids or  the  caller  suppressed  the
       identification.  The option parameter may take the values 0 to 2 and specifies whether the
       rule applies only during special local busy states.  The value of 0 lets the rule be valid
       during  any  local  busy state. A value of 1 lets the rule only apply to incoming calls if
       the call is in a non waiting state.  A value of 2 applies te rule only to such calls which
       arrive  as  waiting.  This  is normally the case when all local resources (B-channels) are
       already in use.  If the rule criterias  mentioned  before  match  the  incoming  call,  no
       following rules will be checked and the desired action will be executed. The value for the
       parameter action is numeric and may take the values 0 to 5 at the moment.  A  value  of  0
       lets the call to be ignored. The call will not be reported through the ascii interface and
       not checked against any following rules.  A value of 1 will report the  call  through  the
       ascii  interface but no other action will take place. If the value 2 is specified the call
       will be reported through the ascii interface and actively put in a local proceeding state.
       This  means  that  the providers exchange is told, that your side needs more time to check
       whether the call may be handled and in which way this will be done.  This  value  only  is
       intended  for  use  with  local or remote client software watching the ascii interface and
       deciding what to do. No ringing signal is send to the caller until the decision  has  been
       made  or  a  timeout  (typically  5 to 15 seconds) occurs.  An example would be a software
       which announces the call to a user and requests the desired action. At the moment a client
       software  is  under  development,  but  still  not  available,  so  this value may only be
       intersting for programmers which want to write  their  own  client.   If  value  of  4  is
       specified  the call will be actively rejected.  The value of 5 is not primary an diversion
       function and allows an i4l network device to be started for  dialing  out  when  the  rule
       matches. The destination number parameter specifies the network device (for example ippp0)
       to e dialed. The incoming call itself is not accepted.  The values from 0-2  and  4  don't
       require  a  destination number to be specified, as the incoming call will not be deflected
       in this cases.  The last, but most interesting value for most people will be the value  3.
       Specifying  it,  will  let  the  call  to be deflected/diverted actively.  For this reason
       additional parameters are taken for interpretation. First of all destnumber specifies  the
       final number the call should be diverted to.  The parameter delay specifies after how many
       seconds the call will be diverted towards the new destination. A value of 0  deflects  the
       call  immediately  like  the  cfu in static diversons, any other value first announces the
       caller a ringing state until the time is elapsed and then the call will be  diverted  like
       in  static cfnr.  During the ringing phase every other device on your line may pick up the
       call of course.  The value of the parameter  screen  may  take  the  values  0  to  2  and
       specifies  if  the  diversion  is presented to the caller. A value of 0 denies to show the
       caller that and where the call has been deflected. Specifying a value of 1 only shows that
       the call has been diverted but doesn't show to which final destination this will happen. A
       value of 2 lets the caller know all information of the diversion (fact  of  diversion  and
       number diverted to).

       insertrule driverid action msn si1 si2 callerid screen delay option destnumber

       This command inserts a single rule at the beginning before the first already existing rule
       in the chain.  All parameters and descriptions are the same as for the appendrule command.

Numeric codes of basic services

         0  all services
         1  speech
         2  unrestricted digital information
         3  audio 3.1 kHz
         4  unrestricted digital info with tone announcements
         5  multirate
        32  telephony 3.1 kHz
        33  teletex
        34  telefax group 4 class 1
        35  videotex syntax based
        36  videotelephony
        37  telefax group 2/3
        38  telephony 7 kHz
        39  eurofiletransfer
        40  filetransfer and access management
        41  videoconference
        42  audio graphic conference

       When diversion of speech calls is desired  at  least  services  1,  2  and  32  should  be
       specified.

Interfacing to other programs

       The  /proc/net/isdn/divert  device  may  be  used  for  debug  purposes or interfacing the
       diversion services to other programs. It may be multiple opened. All operations as well as
       incoming  calls  may  be  watched  reading the ascii output of the interface. One possible
       application would be a remote client announcing and logging incoming calls  and  diversion
       actions inside the local network. Such logging service could be invoked via inetd.

BUGS

       With  some  commands  an  explicit driverid needs to be specified under certain conditions
       even if wildcards should be allowed. If you get a core dump using wildcards try to  use  a
       cmd line specifying a single interface.  This man page is still not complete.

AUTHOR

       Werner Cornelius <werner@isdn4linux.de or werner@isdn-development.de>