[mirror_ubuntu-zesty-kernel.git] / Documentation / isdn / README.diversion

The isdn diversion services are a supporting module working together with
the isdn4linux and the HiSax module for passive cards. 
Active cards, TAs and cards using a own or other driver than the HiSax 
module need to be adapted to the HL<->LL interface described in a separate 
document. The diversion services may be used with all cards supported by 
the HiSax driver.
The diversion kernel interface and controlling tool divertctrl were written
by Werner Cornelius (werner@isdn4linux.de or werner@titro.de) under the
GNU General Public License.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Table of contents
=================

1. Features of the i4l diversion services 
   (Or what can the i4l diversion services do for me)

2. Required hard- and software

3. Compiling, installing and loading/unloading the module  
   Tracing calling and diversion information 

4. Tracing calling and diversion information
 
5. Format of the divert device ASCII output
 

1. Features of the i4l diversion services 
   (Or what can the i4l diversion services do for me)

   The i4l diversion services offers call forwarding and logging normally 
   only supported by isdn phones. Incoming calls may be diverted 
   unconditionally (CFU), when not reachable (CFNR) or on busy condition 
   (CFB). 
   The diversions may be invoked statically in the providers exchange
   as normally done by isdn phones. In this case all incoming calls
   with a special (or all) service identifiers are forwarded if the 
   forwarding reason is met. Activated static services may also be 
   interrogated (queried).
   The i4l diversion services additionally offers a dynamic version of
   call forwarding which is not preprogrammed inside the providers exchange
   but dynamically activated by i4l.
   In this case all incoming calls are checked by rules that may be
   compared to the mechanism of ipfwadm or ipchains. If a given rule matches
   the checking process is finished and the rule matching will be applied
   to the call.
   The rules include primary and secondary service identifiers, called 
   number and subaddress, callers number and subaddress and whether the rule
   matches to all filtered calls or only those when all B-channel resources
   are exhausted.
   Actions that may be invoked by a rule are ignore, proceed, reject, 
   direct divert or delayed divert of a call.
   All incoming calls matching a rule except the ignore rule a reported and
   logged as ASCII via the proc filesystem (/proc/net/isdn/divert). If proceed
   is selected the call will be held in a proceeding state (without ringing)
   for a certain amount of time to let an external program or client decide
   how to handle the call. 
            

2. Required hard- and software
   
   For using the i4l diversion services the isdn line must be of a EURO/DSS1
   type. Additionally the i4l services only work together with the HiSax 
   driver for passive isdn cards. All HiSax supported cards may be used for
   the diversion purposes.
   The static diversion services require the provider having static services
   CFU, CFNR, CFB activated on an MSN-line. The static services may not be 
   used on a point-to-point connection. Further the static services are only
   available in some countries (for example germany). Countries requiring the 
   keypad protocol for activating static diversions (like the netherlands) are
   not supported but may use the tty devices for this purpose.
   The dynamic diversion services may be used in all countries if the provider
   enables the feature CF (call forwarding). This should work on both MSN- and
   point-to-point lines.
   To add and delete rules the additional divertctrl program is needed. This
   program is part of the isdn4kutils package.   

3. Compiling, installing and loading/unloading the module  
   Tracing calling and diversion information 


   To compile the i4l code with diversion support you need to say yes to the 
   DSS1 diversion services when selecting the i4l options in the kernel 
   config (menuconfig or config).
   After having properly activated a make modules and make modules_install all
   required modules will be correctly installed in the needed modules dirs.
   As the diversion services are currently not included in the scripts of most
   standard distributions you will have to add a "insmod dss1_divert" after
   having loaded the global isdn module.
   The module can be loaded without any command line parameters.
   If the module is actually loaded and active may be checked with a 
   "cat /proc/modules" or "ls /proc/net/isdn/divert". The divert file is 
   dynamically created by the diversion module and removed when the module is
   unloaded.


4. Tracing calling and diversion information
 
   You also may put a "cat /proc/net/isdn/divert" in the background with the
   output redirected to a file. Then all actions of the module are logged.
   The divert file in the proc system may be opened more than once, so in 
   conjunction with inetd and a small remote client on other machines inside
   your network incoming calls and reactions by the module may be shown on 
   every listening machine. 
   If a call is reported as proceeding an external program or client may 
   specify during a certain amount of time (normally 4 to 10 seconds) what
   to do with that call.      
   To unload the module all open files to the device in the proc system must
   be closed. Otherwise the module (and isdn.o) may not be unloaded. 

5. Format of the divert device ASCII output
 
   To be done later
Commit	Line	Data
1da177e4 LT	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