| blob | dcd14151eb9bcb49bce3040b9545bd968fb65589 |
1 README for the ISDN-subsystem
3 1. Preface
5 1.1 Introduction
7 This README describes how to set up and how to use the different parts
8 of the ISDN-subsystem.
10 For using the ISDN-subsystem, some additional userlevel programs are
11 necessary. Those programs and some contributed utilities are available
12 at
14 ftp.franken.de
16 /pub/isdn4linux/isdn4k-utils-<VersionNumber>.tar.gz
19 We also have set up a mailing-list:
21 The isdn4linux-project originates in Germany, and therefore by historical
22 reasons, the mailing-list's primary language is german. However mails
23 written in english have been welcome all the time.
25 to subscribe: write a email to majordomo@hub-wue.franken.de,
26 Subject irrelevant, in the message body:
27 subscribe isdn4linux <your_email_address>
29 To write to the mailing-list, write to isdn4linux@hub-wue.franken.de
31 This mailinglist is bidirectionally gated to the newsgroup
33 de.alt.comm.isdn4linux
35 There is also a well maintained FAQ (both english and german) available
36 at ftp.franken.de in /pub/isdn4linux/FAQ/
37 This FAQ is also available at http://www.lrz-muenchen.de/~ui161ab/www/isdn/
39 1.1 Technical details
41 In the following Text, the terms MSN and EAZ are used.
43 MSN is the abbreviation for (M)ultiple(S)ubscriber(N)umber, and applies
44 to Euro(EDSS1)-type lines. Usually it is simply the phone number.
46 EAZ is the abbreviation of (E)ndgeraete(A)uswahl(Z)iffer and
47 applies to German 1TR6-type lines. This is a one-digit string,
48 simply appended to the base phone number
50 The internal handling is nearly identical, so replace the appropriate
51 term to that one, which applies to your local ISDN-environment.
53 When the link-level-module isdn.o is loaded, it supports up to 16
54 low-level-modules with up to 64 channels. (The number 64 is arbitrarily
55 chosen and can be configured at compile-time --ISDN_MAX in isdn.h).
56 A low-level-driver can register itself through an interface (which is
57 defined in isdnif.h) and gets assigned a slot.
58 The following char-devices are made available for each channel:
60 A raw-control-device with the following functions:
61 write: raw D-channel-messages (format: depends on driver).
62 read: raw D-channel-messages (format: depends on driver).
63 ioctl: depends on driver, i.e. for the ICN-driver, the base-address of
64 the ports and the shared memory on the card can be set and read
65 also the boot-code and the protocol software can be loaded into
66 the card.
68 O N L Y !!! for debugging (no locking against other devices):
69 One raw-data-device with the following functions:
70 write: data to B-channel.
71 read: data from B-channel.
73 In addition the following devices are made available:
75 128 tty-devices (64 cuix and 64 ttyIx) with integrated modem-emulator:
76 The functionality is almost the same as that of a serial device
77 (the line-discs are handled by the kernel), which lets you run
78 SLIP, CSLIP and asynchronous PPP through the devices. We have tested
79 Seyon, minicom, CSLIP (uri-dip) PPP and mgetty (compiled with NO_FAX),
80 XCept.
82 The modem-emulation supports the following:
83 1.3.1 Commands:
85 ATA Answer incoming call.
86 ATD<No.> Dial, the number may contain:
87 [0-9] and [,#.*WPT-S]
88 the latter are ignored until 'S'.
89 The 'S' must precede the number, if
90 the line is a SPV (German 1TR6).
91 ATE0 Echo off.
92 ATE1 Echo on (default).
93 ATH Hang-up.
94 ATH1 Off hook (ignored).
95 ATH0 Hang-up.
96 ATI Return "ISDN for Linux...".
97 ATI0 "
98 ATI1 "
99 ATI2 Report of last connection.
100 ATO On line (data mode).
101 ATQ0 Enable result codes (default).
102 ATQ1 Disable result codes (default).
103 ATSx=y Set register x to y.
104 ATSx? Show contents of register x.
105 ATV0 Numeric responses.
106 ATV1 English responses (default).
107 ATZ Load registers and EAZ/MSN from Profile.
108 AT&Bx Set Send-Packet-size to x (max. 4000)
109 The real packet-size may be limited by the
110 low-level-driver used. e.g. the HiSax-Module-
111 limit is 2000. You will get NO Error-Message,
112 if you set it to higher values, because at the
113 time of giving this command the corresponding
114 driver may not be selected (see "Automatic
115 Assignment") however the size of outgoing packets
116 will be limited correctly.
117 AT&D0 Ignore DTR
118 AT&D2 DTR-low-edge: Hang up and return to
119 command mode (default).
120 AT&D3 Same as AT&D2 but also resets all registers.
121 AT&Ex Set the EAZ/MSN for this channel to x.
122 AT&F Reset all registers and profile to "factory-defaults"
123 AT&Rx Select V.110 bitrate adaption.
124 This command enables V.110 protocol with 9600 baud
125 (x=9600), 19200 baud (x=19200) or 38400 baud
126 (x=38400). A value of x=0 disables V.110 switching
127 back to default X.75. This command sets the following
128 Registers:
129 Reg 14 (Layer-2 protocol):
130 x = 0: 0
131 x = 9600: 7
132 x = 19200: 8
133 x = 38400: 9
134 Reg 18.2 = 1
135 Reg 19 (Additional Service Indicator):
136 x = 0: 0
137 x = 9600: 197
138 x = 19200: 199
139 x = 38400: 198
140 Note on value in Reg 19:
141 There is _NO_ common convention for 38400 baud.
142 The value 198 is choosen arbitrarily. Users
143 _MUST_ negotiate this value before establishing
144 a connection.
145 AT&Sx Set window-size (x = 1..8) (not yet implemented)
146 AT&V Show all settings.
147 AT&W0 Write registers and EAZ/MSN to profile. See also
148 iprofd (5.c in this README).
149 AT&X0 BTX-mode and T.70-mode off (default)
150 AT&X1 BTX-mode on. (S13.1=1, S13.5=0 S14=0, S16=7, S18=7, S19=0)
151 AT&X2 T.70-mode on. (S13.1=1, S13.5=1, S14=0, S16=7, S18=7, S19=0)
152 AT+Rx Resume a suspended call with CallID x (x = 1,2,3...)
153 AT+Sx Suspend a call with CallID x (x = 1,2,3...)
155 For voice-mode commands refer to README.audio
157 1.3.2 Escape sequence:
158 During a connection, the emulation reacts just like
159 a normal modem to the escape sequence <DELAY>+++<DELAY>.
160 (The escape character - default '+' - can be set in the
161 register 2).
162 The DELAY must at least be 1.5 seconds long and delay
163 between the escape characters must not exceed 0.5 seconds.
165 1.3.3 Registers:
167 Nr. Default Description
168 0 0 Answer on ring number.
169 (no auto-answer if S0=0).
170 1 0 Count of rings.
171 2 43 Escape character.
172 (a value >= 128 disables the escape sequence).
173 3 13 Carriage return character (ASCII).
174 4 10 Line feed character (ASCII).
175 5 8 Backspace character (ASCII).
176 6 3 Delay in seconds before dialing.
177 7 60 Wait for carrier.
178 8 2 Pause time for comma (ignored)
179 9 6 Carrier detect time (ignored)
180 10 7 Carrier loss to disconnect time (ignored).
181 11 70 Touch tone timing (ignored).
182 12 69 Bit coded register:
183 Bit 0: 0 = Suppress response messages.
184 1 = Show response messages.
185 Bit 1: 0 = English response messages.
186 1 = Numeric response messages.
187 Bit 2: 0 = Echo off.
188 1 = Echo on.
189 Bit 3 0 = DCD always on.
190 1 = DCD follows carrier.
191 Bit 4 0 = CTS follows RTS
192 1 = Ignore RTS, CTS always on.
193 Bit 5 0 = return to command mode on DTR low.
194 1 = Same as 0 but also resets all
195 registers.
196 See also register 13, bit 2
197 Bit 6 0 = DSR always on.
198 1 = DSR only on if channel is available.
199 Bit 7 0 = Cisco-PPP-flag-hack off (default).
200 1 = Cisco-PPP-flag-hack on.
201 13 0 Bit coded register:
202 Bit 0: 0 = Use delayed tty-send-algorithm
203 1 = Direct tty-send.
204 Bit 1: 0 = T.70 protocol (Only for BTX!) off
205 1 = T.70 protocol (Only for BTX!) on
206 Bit 2: 0 = Don't hangup on DTR low.
207 1 = Hangup on DTR low.
208 Bit 3: 0 = Standard response messages
209 1 = Extended response messages
210 Bit 4: 0 = CALLER NUMBER before every RING.
211 1 = CALLER NUMBER after first RING.
212 Bit 5: 0 = T.70 extended protocol off
213 1 = T.70 extended protocol on
214 Bit 6: 0 = Special RUNG Message off
215 1 = Special RUNG Message on
216 "RUNG" is delivered on a ttyI, if
217 an incoming call happened (RING) and
218 the remote party hung up before any
219 local ATA was given.
220 Bit 7: 0 = Don't show display messages from net
221 1 = Show display messages from net
222 (S12 Bit 1 must be 0 too)
223 14 0 Layer-2 protocol:
224 0 = X75/LAPB with I-frames
225 1 = X75/LAPB with UI-frames
226 2 = X75/LAPB with BUI-frames
227 3 = HDLC
228 4 = Transparent (audio)
229 7 = V.110, 9600 baud
230 8 = V.110, 19200 baud
231 9 = V.110, 38400 baud
232 10 = Analog Modem (only if hardware supports this)
233 11 = Fax G3 (only if hardware supports this)
234 15 0 Layer-3 protocol:
235 0 = transparent
236 1 = transparent with audio features (e.g. DSP)
237 2 = Fax G3 (S14 has to be set to 11)
238 16 250 Send-Packet-size/16
239 17 8 Window-size (not yet implemented)
240 18 4 Bit coded register, Service-Octet-1 to accept,
241 or to be used on dialout:
242 Bit 0: Service 1 (audio) when set.
243 Bit 1: Service 5 (BTX) when set.
244 Bit 2: Service 7 (data) when set.
245 Note: It is possible to set more than one
246 bit. In this case, on incoming calls
247 the selected services are accepted,
248 and if the service is "audio", the
249 Layer-2-protocol is automatically
250 changed to 4 regardless of the setting
251 of register 14. On outgoing calls,
252 the most significant 1-bit is chosen to
253 select the outgoing service octet.
254 19 0 Service-Octet-2
255 20 0 Bit coded register (readonly)
256 Service-Octet-1 of last call.
257 Bit mapping is the same as register 18
258 21 0 Bit coded register (readonly)
259 Set on incoming call (during RING) to
260 octet 3 of calling party number IE (Numbering plan)
261 See section 4.5.10 of ITU Q.931
262 22 0 Bit coded register (readonly)
263 Set on incoming call (during RING) to
264 octet 3a of calling party number IE (Screening info)
265 See section 4.5.10 of ITU Q.931
266 23 0 Bit coded register:
267 Bit 0: 0 = Add CPN to RING message off
268 1 = Add CPN to RING message on
270 Last but not least a (at the moment fairly primitive) device to request
271 the line-status (/dev/isdninfo) is made available.
273 Automatic assignment of devices to lines:
275 All inactive physical lines are listening to all EAZs for incoming
276 calls and are NOT assigned to a specific tty or network interface.
277 When an incoming call is detected, the driver looks first for a network
278 interface and then for an opened tty which:
280 1. is configured for the same EAZ.
281 2. has the same protocol settings for the B-channel.
282 3. (only for network interfaces if the security flag is set)
283 contains the caller number in its access list.
284 4. Either the channel is not bound exclusively to another Net-interface, or
285 it is bound AND the other checks apply to exactly this interface.
286 (For usage of the bind-features, refer to the isdnctrl-man-page)
288 Only when a matching interface or tty is found is the call accepted
289 and the "connection" between the low-level-layer and the link-level-layer
290 is established and kept until the end of the connection.
291 In all other cases no connection is established. Isdn4linux can be
292 configured to either do NOTHING in this case (which is useful, if
293 other, external devices with the same EAZ/MSN are connected to the bus)
294 or to reject the call actively. (isdnctrl busreject ...)
296 For an outgoing call, the inactive physical lines are searched.
297 The call is placed on the first physical line, which supports the
298 requested protocols for the B-channel. If a net-interface, however
299 is pre-bound to a channel, this channel is used directly.
301 This makes it possible to configure several network interfaces and ttys
302 for one EAZ, if the network interfaces are set to secure operation.
303 If an incoming call matches one network interface, it gets connected to it.
304 If another incoming call for the same EAZ arrives, which does not match
305 a network interface, the first tty gets a "RING" and so on.
306 As soon as voice gets supported (with the availability of the Diehl-driver),
307 the service-identifier will be evaluated in addition.
309 2 System prerequisites:
311 ATTENTION!
313 Always use the latest module utilities. The current version is
314 named in Documentation/Changes. Some old versions of insmod
315 are not capable of setting the driver-Ids correctly.
317 3. Lowlevel-driver configuration.
319 Configuration depends on how the drivers are built. See the
320 README.<yourDriver> for information on driver-specific setup.
322 4. Device-inodes
324 The major and minor numbers and their names are described in
325 Documentation/devices.txt. The major numbers are:
327 43 for the ISDN-tty's.
328 44 for the ISDN-callout-tty's.
329 45 for control/info/debug devices.
331 5. Application
333 a) For some card-types, firmware has to be loaded into the cards, before
334 proceeding with device-independent setup. See README.<yourDriver>
335 for how to do that.
337 b) If you only intend to use ttys, you are nearly ready now.
339 c) If you want to have really permanent "Modem"-settings on disk, you
340 can start the daemon iprofd. Give it a path to a file at the command-
341 line. It will store the profile-settings in this file every time
342 an AT&W0 is performed on any ISDN-tty. If the file already exists,
343 all profiles are initialized from this file. If you want to unload
344 any of the modules, kill iprofd first.
346 d) For networking, continue: Create an interface:
347 isdnctrl addif isdn0
349 e) Set the EAZ (or MSN for Euro-ISDN):
350 isdnctrl eaz isdn0 2
352 (For 1TR6 a single digit is allowed, for Euro-ISDN the number is your
353 real MSN e.g.: Phone-Number)
355 f) Set the number for outgoing calls on the interface:
356 isdnctrl addphone isdn0 out 1234567
357 ... (this can be executed more than once, all assigned numbers are
358 tried in order)
359 and the number(s) for incoming calls:
360 isdnctrl addphone isdn0 in 1234567
362 g) Set the timeout for hang-up:
363 isdnctrl huptimeout isdn0 <timeout_in_seconds>
365 h) additionally you may activate charge-hang-up (= Hang up before
366 next charge-info, this only works, if your isdn-provider transmits
367 the charge-info during and after the connection):
368 isdnctrl chargehup isdn0 on
370 i) Set the dial mode of the interface:
371 isdnctrl dialmode isdn0 auto
372 "off" means that you (or the system) cannot make any connection
373 (neither incoming or outgoing connections are possible). Use
374 this if you want to be sure that no connections will be made.
375 "auto" means that the interface is in auto-dial mode, and will
376 attempt to make a connection whenever a network data packet needs
377 the interface's link. Note that this can cause unexpected dialouts,
378 and lead to a high phone bill! Some daemons or other pc's that use
379 this interface can cause this.
380 Incoming connections are also possible.
381 "manual" is a dial mode created to prevent the unexpected dialouts.
382 In this mode, the interface will never make any connections on its
383 own. You must explicitly initiate a connection with "isdnctrl dial
384 isdn0". However, after an idle time of no traffic as configured for
385 the huptimeout value with isdnctrl, the connection _will_ be ended.
386 If you don't want any automatic hangup, set the huptimeout value to 0.
387 "manual" is the default.
389 j) Setup the interface with ifconfig as usual, and set a route to it.
391 k) (optional) If you run X11 and have Tcl/Tk-wish version 4.0, you can use
392 the script tools/tcltk/isdnmon. You can add actions for line-status
393 changes. See the comments at the beginning of the script for how to
394 do that. There are other tty-based tools in the tools-subdirectory
395 contributed by Michael Knigge (imon), Volker Götz (imontty) and
396 Andreas Kool (isdnmon).
398 l) For initial testing, you can set the verbose-level to 2 (default: 0).
399 Then all incoming calls are logged, even if they are not addressed
400 to one of the configured net-interfaces:
401 isdnctrl verbose 2
403 Now you are ready! A ping to the set address should now result in an
404 automatic dial-out (look at syslog kernel-messages).
405 The phone numbers and EAZs can be assigned at any time with isdnctrl.
406 You can add as many interfaces as you like with addif following the
407 directions above. Of course, there may be some limitations. But we have
408 tested as many as 20 interfaces without any problem. However, if you
409 don't give an interface name to addif, the kernel will assign a name
410 which starts with "eth". The number of "eth"-interfaces is limited by
411 the kernel.
413 5. Additional options for isdnctrl:
415 "isdnctrl secure <InterfaceName> on"
416 Only incoming calls, for which the caller-id is listed in the access
417 list of the interface are accepted. You can add caller-id's With the
418 command "isdnctrl addphone <InterfaceName> in <caller-id>"
419 Euro-ISDN does not transmit the leading '0' of the caller-id for an
420 incoming call, therefore you should configure it accordingly.
421 If the real number for the dialout e.g. is "09311234567" the number
422 to configure here is "9311234567". The pattern-match function
423 works similar to the shell mechanism.
425 ? one arbitrary digit
426 * zero or arbitrary many digits
427 [123] one of the digits in the list
428 [1-5] one digit between '1' and '5'
429 a '^' as the first character in a list inverts the list
432 "isdnctrl secure <InterfaceName> off"
433 Switch off secure operation (default).
435 "isdnctrl ihup <InterfaceName> [on|off]"
436 Switch the hang-up-timer for incoming calls on or off.
438 "isdnctrl eaz <InterfaceName>"
439 Returns the EAZ of an interface.
441 "isdnctrl delphone <InterfaceName> in|out <number>"
442 Deletes a number from one of the access-lists of the interface.
444 "isdnctrl delif <InterfaceName>"
445 Removes the interface (and possible slaves) from the kernel.
446 (You have to unregister it with "ifconfig <InterfaceName> down" before).
448 "isdnctrl callback <InterfaceName> [on|off]"
449 Switches an interface to callback-mode. In this mode, an incoming call
450 will be rejected and after this the remote-station will be called. If
451 you test this feature by using ping, some routers will re-dial very
452 quickly, so that the callback from isdn4linux may not be recognized.
453 In this case use ping with the option -i <sec> to increase the interval
454 between echo-packets.
456 "isdnctrl cbdelay <InterfaceName> [seconds]"
457 Sets the delay (default 5 sec) between an incoming call and start of
458 dialing when callback is enabled.
460 "isdnctrl cbhup <InterfaceName> [on|off]"
461 This enables (default) or disables an active hangup (reject) when getting an
462 incoming call for an interface which is configured for callback.
464 "isdnctrl encap <InterfaceName> <EncapType>"
465 Selects the type of packet-encapsulation. The encapsulation can be changed
466 only while an interface is down.
468 At the moment the following values are supported:
470 rawip (Default) Selects raw-IP-encapsulation. This means, MAC-headers
471 are stripped off.
472 ip IP with type-field. Same as IP but the type-field of the MAC-header
473 is preserved.
474 x25iface X.25 interface encapsulation (first byte semantics as defined in
475 ../networking/x25-iface.txt). Use this for running the linux
476 X.25 network protocol stack (AF_X25 sockets) on top of isdn.
477 cisco-h A special-mode for communicating with a Cisco, which is configured
478 to do "hdlc"
479 ethernet No stripping. Packets are sent with full MAC-header.
480 The Ethernet-address of the interface is faked, from its
481 IP-address: fc:fc:i1:i2:i3:i4, where i1-4 are the IP-addr.-values.
482 syncppp Synchronous PPP
484 uihdlc HDLC with UI-frame-header (for use with DOS ISPA, option -h1)
487 NOTE: x25iface encapsulation is currently experimental. Please
488 read README.x25 for further details
491 Watching packets, using standard-tcpdump will fail for all encapsulations
492 except ethernet because tcpdump does not know how to handle packets
493 without MAC-header. A patch for tcpdump is included in the utility-package
494 mentioned above.
496 "isdnctrl l2_prot <InterfaceName> <L2-ProtocolName>"
497 Selects a layer-2-protocol.
498 (With the ICN-driver and the HiSax-driver, "x75i" and "hdlc" is available.
499 With other drivers, "x75ui", "x75bui", "x25dte", "x25dce" may be
500 possible too. See README.x25 for x25 related l2 protocols.)
502 isdnctrl l3_prot <InterfaceName> <L3-ProtocolName>
503 The same for layer-3. (At the moment only "trans" is allowed)
505 "isdnctrl list <InterfaceName>"
506 Shows all parameters of an interface and the charge-info.
507 Try "all" as the interface name.
509 "isdnctrl hangup <InterfaceName>"
510 Forces hangup of an interface.
512 "isdnctrl bind <InterfaceName> <DriverId>,<ChannelNumber> [exclusive]"
513 If you are using more than one ISDN card, it is sometimes necessary to
514 dial out using a specific card or even preserve a specific channel for
515 dialout of a specific net-interface. This can be done with the above
516 command. Replace <DriverId> by whatever you assigned while loading the
517 module. The <ChannelNumber> is counted from zero. The upper limit
518 depends on the card used. At the moment no card supports more than
519 2 channels, so the upper limit is one.
521 "isdnctrl unbind <InterfaceName>"
522 unbinds a previously bound interface.
524 "isdnctrl busreject <DriverId> on|off"
525 If switched on, isdn4linux replies a REJECT to incoming calls, it
526 cannot match to any configured interface.
527 If switched off, nothing happens in this case.
528 You normally should NOT enable this feature, if the ISDN adapter is not
529 the only device connected to the S0-bus. Otherwise it could happen that
530 isdn4linux rejects an incoming call, which belongs to another device on
531 the bus.
533 "isdnctrl addslave <InterfaceName> <SlaveName>
534 Creates a slave interface for channel-bundling. Slave interfaces are
535 not seen by the kernel, but their ISDN-part can be configured with
536 isdnctrl as usual. (Phone numbers, EAZ/MSN, timeouts etc.) If more
537 than two channels are to be bundled, feel free to create as many as you
538 want. InterfaceName must be a real interface, NOT a slave. Slave interfaces
539 start dialing, if the master interface resp. the previous slave interface
540 has a load of more than 7000 cps. They hangup if the load goes under 7000
541 cps, according to their "huptimeout"-parameter.
543 "isdnctrl sdelay <InterfaceName> secs."
544 This sets the minimum time an Interface has to be fully loaded, until
545 it sends a dial-request to its slave.
547 "isdnctrl dial <InterfaceName>"
548 Forces an interface to start dialing even if no packets are to be
549 transferred.
551 "isdnctrl mapping <DriverId> MSN0,MSN1,MSN2,...MSN9"
552 This installs a mapping table for EAZ<->MSN-mapping for a single line.
553 Missing MSN's have to be given as "-" or can be omitted, if at the end
554 of the commandline.
555 With this command, it's now possible to have an interface listening to
556 mixed 1TR6- and Euro-Type lines. In this case, the interface has to be
557 configured to a 1TR6-type EAZ (one digit). The mapping is also valid
558 for tty-emulation. Seen from the interface/tty-level the mapping
559 CAN be used, however it's possible to use single tty's/interfaces with
560 real MSN's (more digits) also, in which case the mapping will be ignored.
561 Here is an example:
563 You have a 1TR6-type line with base-nr. 1234567 and a Euro-line with
564 MSN's 987654, 987655 and 987656. The DriverId for the Euro-line is "EURO".
566 isdnctrl mapping EURO -,987654,987655,987656,-,987655
567 ...
568 isdnctrl eaz isdn0 1 # listen on 12345671(1tr6) and 987654(euro)
569 ...
570 isdnctrl eaz isdn1 4 # listen on 12345674(1tr6) only.
571 ...
572 isdnctrl eaz isdn2 987654 # listen on 987654(euro) only.
574 Same scheme is used with AT&E... at the tty's.
576 6. If you want to write a new low-level-driver, you are welcome.
577 The interface to the link-level-module is described in the file INTERFACE.
578 If the interface should be expanded for any reason, don't do it
579 on your own, send me a mail containing the proposed changes and
580 some reasoning about them.
581 If other drivers will not be affected, I will include the changes
582 in the next release.
583 For developers only, there is a second mailing-list. Write to me
584 (fritz@wuemaus.franken.de), if you want to join that list.
586 Have fun!
588 -Fritz