| blob | 7b17183e069cf701c31df3dc6996f3cf528aa35a |
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)
153 For voice-mode commands refer to README.audio
155 1.3.2 Escape sequence:
156 During a connection, the emulation reacts just like
157 a normal modem to the escape sequence <DELAY>+++<DELAY>.
158 (The escape character - default '+' - can be set in the
159 register 2).
160 The DELAY must at least be 1.5 seconds long and delay
161 between the escape characters must not exceed 0.5 seconds.
163 1.3.3 Registers:
165 Nr. Default Description
166 0 0 Answer on ring number.
167 (no auto-answer if S0=0).
168 1 0 Count of rings.
169 2 43 Escape character.
170 (a value >= 128 disables the escape sequence).
171 3 13 Carriage return character (ASCII).
172 4 10 Line feed character (ASCII).
173 5 8 Backspace character (ASCII).
174 6 3 Delay in seconds before dialing.
175 7 60 Wait for carrier.
176 8 2 Pause time for comma (ignored)
177 9 6 Carrier detect time (ignored)
178 10 7 Carrier loss to disconnect time (ignored).
179 11 70 Touch tone timing (ignored).
180 12 69 Bit coded register:
181 Bit 0: 0 = Suppress response messages.
182 1 = Show response messages.
183 Bit 1: 0 = English response messages.
184 1 = Numeric response messages.
185 Bit 2: 0 = Echo off.
186 1 = Echo on.
187 Bit 3 0 = DCD always on.
188 1 = DCD follows carrier.
189 Bit 4 0 = CTS follows RTS
190 1 = Ignore RTS, CTS always on.
191 Bit 5 0 = return to command mode on DTR low.
192 1 = Same as 0 but also resets all
193 registers.
194 See also register 13, bit 2
195 Bit 6 0 = DSR always on.
196 1 = DSR only on if channel is available.
197 Bit 7 0 = Cisco-PPP-flag-hack off (default).
198 1 = Cisco-PPP-flag-hack on.
199 13 0 Bit coded register:
200 Bit 0: 0 = Use delayed tty-send-algorithm
201 1 = Direct tty-send.
202 Bit 1: 0 = T.70 protocol (Only for BTX!) off
203 1 = T.70 protocol (Only for BTX!) on
204 Bit 2: 0 = Don't hangup on DTR low.
205 1 = Hangup on DTR low.
206 Bit 3: 0 = Standard response messages
207 1 = Extended response messages
208 Bit 4: 0 = CALLER NUMBER before every RING.
209 1 = CALLER NUMBER after first RING.
210 Bit 5: 0 = T.70 extended protocol off
211 1 = T.70 extended protocol on
212 Bit 6: 0 = Special RUNG Message off
213 1 = Special RUNG Message on
214 "RUNG" is delivered on a ttyI, if
215 an incoming call happened (RING) and
216 the remote party hung up before any
217 local ATA was given.
218 14 0 Layer-2 protocol:
219 0 = X75/LAPB with I-frames
220 1 = X75/LAPB with UI-frames
221 2 = X75/LAPB with BUI-frames
222 3 = HDLC
223 4 = Transparent (audio)
224 7 = V.110, 9600 baud
225 8 = V.110, 19200 baud
226 9 = V.110, 38400 baud
227 10 = Analog Modem (only if hardware supports this)
228 15 0 Layer-3 protocol: (at the moment always 0)
229 0 = transparent
230 16 250 Send-Packet-size/16
231 17 8 Window-size (not yet implemented)
232 18 4 Bit coded register, Service-Octet-1 to accept,
233 or to be used on dialout:
234 Bit 0: Service 1 (audio) when set.
235 Bit 1: Service 5 (BTX) when set.
236 Bit 2: Service 7 (data) when set.
237 Note: It is possible to set more than one
238 bit. In this case, on incoming calls
239 the selected services are accepted,
240 and if the service is "audio", the
241 Layer-2-protocol is automatically
242 changed to 4 regardless of the setting
243 of register 14. On outgoing calls,
244 the most significant 1-bit is chosen to
245 select the outgoing service octet.
246 19 0 Service-Octet-2
247 20 0 Bit coded register (readonly)
248 Service-Octet-1 of last call.
249 Bit mapping is the same as register 18
250 21 0 Bit coded register (readonly)
251 Set on incoming call (during RING) to
252 octet 3 of calling party number IE (Numbering plan)
253 See section 4.5.10 of ITU Q.931
254 22 0 Bit coded register (readonly)
255 Set on incoming call (during RING) to
256 octet 3a of calling party number IE (Screening info)
257 See section 4.5.10 of ITU Q.931
259 Last but not least a (at the moment fairly primitive) device to request
260 the line-status (/dev/isdninfo) is made available.
262 Automatic assignment of devices to lines:
264 All inactive physical lines are listening to all EAZs for incoming
265 calls and are NOT assigned to a specific tty or network interface.
266 When an incoming call is detected, the driver looks first for a network
267 interface and then for an opened tty which:
269 1. is configured for the same EAZ.
270 2. has the same protocol settings for the B-channel.
271 3. (only for network interfaces if the security flag is set)
272 contains the caller number in its access list.
273 4. Either the channel is not bound exclusively to another Net-interface, or
274 it is bound AND the other checks apply to exactly this interface.
275 (For usage of the bind-features, refer to the isdnctrl-man-page)
277 Only when a matching interface or tty is found is the call accepted
278 and the "connection" between the low-level-layer and the link-level-layer
279 is established and kept until the end of the connection.
280 In all other cases no connection is established. Isdn4linux can be
281 configured to either do NOTHING in this case (which is useful, if
282 other, external devices with the same EAZ/MSN are connected to the bus)
283 or to reject the call actively. (isdnctrl busreject ...)
285 For an outgoing call, the inactive physical lines are searched.
286 The call is placed on the first physical line, which supports the
287 requested protocols for the B-channel. If a net-interface, however
288 is pre-bound to a channel, this channel is used directly.
290 This makes it possible to configure several network interfaces and ttys
291 for one EAZ, if the network interfaces are set to secure operation.
292 If an incoming call matches one network interface, it gets connected to it.
293 If another incoming call for the same EAZ arrives, which does not match
294 a network interface, the first tty gets a "RING" and so on.
295 As soon as voice gets supported (with the availability of the Diehl-driver),
296 the service-identifier will be evaluated in addition.
298 2 System prerequisites:
300 ATTENTION!
302 Always use the latest module utilities. The current version is
303 named in Documentation/Changes. Some old versions of insmod
304 are not capable of setting the driver-Ids correctly.
306 3. Lowlevel-driver configuration.
308 Configuration depends on how the drivers are built. See the
309 README.<yourDriver> for information on driver-specific setup.
311 4. Device-inodes
313 The major and minor numbers and their names are described in
314 Documentation/devices.txt. The major numbers are:
316 43 for the ISDN-tty's.
317 44 for the ISDN-callout-tty's.
318 45 for control/info/debug devices.
320 5. Application
322 a) For some card-types, firmware has to be loaded into the cards, before
323 proceeding with device-independent setup. See README.<yourDriver>
324 for how to do that.
326 b) If you only intend to use ttys, you are nearly ready now.
328 c) If you want to have really permanent "Modem"-settings on disk, you
329 can start the daemon iprofd. Give it a path to a file at the command-
330 line. It will store the profile-settings in this file every time
331 an AT&W0 is performed on any ISDN-tty. If the file already exists,
332 all profiles are initialized from this file. If you want to unload
333 any of the modules, kill iprofd first.
335 d) For networking, continue: Create an interface:
336 isdnctrl addif isdn0
338 e) Set the EAZ (or MSN for Euro-ISDN):
339 isdnctrl eaz isdn0 2
341 (For 1TR6 a single digit is allowed, for Euro-ISDN the number is your
342 real MSN e.g.: Phone-Number)
344 f) Set the number for outgoing calls on the interface:
345 isdnctrl addphone isdn0 out 1234567
346 ... (this can be executed more than once, all assigned numbers are
347 tried in order)
348 and the number(s) for incoming calls:
349 isdnctrl addphone isdn0 in 1234567
351 g) Set the timeout for hang-up:
352 isdnctrl huptimeout isdn0 <timeout_in_seconds>
354 h) additionally you may activate charge-hang-up (= Hang up before
355 next charge-info, this only works, if your isdn-provider transmits
356 the charge-info during and after the connection):
357 isdnctrl chargehup isdn0 on
359 i) Set the dial mode of the interface:
360 isdnctrl dialmode isdn0 auto
361 "off" means that you (or the system) cannot make any connection
362 (neither incoming or outgoing connections are possible). Use
363 this if you want to be sure that no connections will be made.
364 "auto" means that the interface is in auto-dial mode, and will
365 attempt to make a connection whenever a network data packet needs
366 the interface's link. Note that this can cause unexpected dialouts,
367 and lead to a high phone bill! Some daemons or other pc's that use
368 this interface can cause this.
369 Incoming connections are also possible.
370 "manual" is a dial mode created to prevent the unexpected dialouts.
371 In this mode, the interface will never make any connections on its
372 own. You must explicitly initiate a connection with "isdnctrl dial
373 isdn0". However, after an idle time of no traffic as configured for
374 the huptimeout value with isdnctrl, the connection _will_ be ended.
375 If you don't want any automatic hangup, set the huptimeout value to 0.
376 "manual" is the default.
378 j) Setup the interface with ifconfig as usual, and set a route to it.
380 k) (optional) If you run X11 and have Tcl/Tk-wish version 4.0, you can use
381 the script tools/tcltk/isdnmon. You can add actions for line-status
382 changes. See the comments at the beginning of the script for how to
383 do that. There are other tty-based tools in the tools-subdirectory
384 contributed by Michael Knigge (imon), Volker Götz (imontty) and
385 Andreas Kool (isdnmon).
387 l) For initial testing, you can set the verbose-level to 2 (default: 0).
388 Then all incoming calls are logged, even if they are not addressed
389 to one of the configured net-interfaces:
390 isdnctrl verbose 2
392 Now you are ready! A ping to the set address should now result in an
393 automatic dial-out (look at syslog kernel-messages).
394 The phone numbers and EAZs can be assigned at any time with isdnctrl.
395 You can add as many interfaces as you like with addif following the
396 directions above. Of course, there may be some limitations. But we have
397 tested as many as 20 interfaces without any problem. However, if you
398 don't give an interface name to addif, the kernel will assign a name
399 which starts with "eth". The number of "eth"-interfaces is limited by
400 the kernel.
402 5. Additional options for isdnctrl:
404 "isdnctrl secure <InterfaceName> on"
405 Only incoming calls, for which the caller-id is listed in the access
406 list of the interface are accepted. You can add caller-id's With the
407 command "isdnctrl addphone <InterfaceName> in <caller-id>"
408 Euro-ISDN does not transmit the leading '0' of the caller-id for an
409 incoming call, therefore you should configure it accordingly.
410 If the real number for the dialout e.g. is "09311234567" the number
411 to configure here is "9311234567". The pattern-match function
412 works similar to the shell mechanism.
414 ? one arbitrary digit
415 * zero or arbitrary many digits
416 [123] one of the digits in the list
417 [1-5] one digit between '1' and '5'
418 a '^' as the first character in a list inverts the list
421 "isdnctrl secure <InterfaceName> off"
422 Switch off secure operation (default).
424 "isdnctrl ihup <InterfaceName> [on|off]"
425 Switch the hang-up-timer for incoming calls on or off.
427 "isdnctrl eaz <InterfaceName>"
428 Returns the EAZ of an interface.
430 "isdnctrl delphone <InterfaceName> in|out <number>"
431 Deletes a number from one of the access-lists of the interface.
433 "isdnctrl delif <InterfaceName>"
434 Removes the interface (and possible slaves) from the kernel.
435 (You have to unregister it with "ifconfig <InterfaceName> down" before).
437 "isdnctrl callback <InterfaceName> [on|off]"
438 Switches an interface to callback-mode. In this mode, an incoming call
439 will be rejected and after this the remote-station will be called. If
440 you test this feature by using ping, some routers will re-dial very
441 quickly, so that the callback from isdn4linux may not be recognized.
442 In this case use ping with the option -i <sec> to increase the interval
443 between echo-packets.
445 "isdnctrl cbdelay <InterfaceName> [seconds]"
446 Sets the delay (default 5 sec) between an incoming call and start of
447 dialing when callback is enabled.
449 "isdnctrl cbhup <InterfaceName> [on|off]"
450 This enables (default) or disables an active hangup (reject) when getting an
451 incoming call for an interface which is configured for callback.
453 "isdnctrl encap <InterfaceName> <EncapType>"
454 Selects the type of packet-encapsulation. The encapsulation can be changed
455 only while an interface is down.
457 At the moment the following values are supported:
459 rawip (Default) Selects raw-IP-encapsulation. This means, MAC-headers
460 are stripped off.
461 ip IP with type-field. Same as IP but the type-field of the MAC-header
462 is preserved.
463 x25iface X.25 interface encapsulation (first byte semantics as defined in
464 ../networking/x25-iface.txt). Use this for running the linux
465 X.25 network protocol stack (AF_X25 sockets) on top of isdn.
466 cisco-h A special-mode for communicating with a Cisco, which is configured
467 to do "hdlc"
468 ethernet No stripping. Packets are sent with full MAC-header.
469 The Ethernet-address of the interface is faked, from its
470 IP-address: fc:fc:i1:i2:i3:i4, where i1-4 are the IP-addr.-values.
471 syncppp Synchronous PPP
473 uihdlc HDLC with UI-frame-header (for use with DOS ISPA, option -h1)
476 NOTE: x25iface encapsulation is currently experimental. Please
477 read README.x25 for further details
480 Watching packets, using standard-tcpdump will fail for all encapsulations
481 except ethernet because tcpdump does not know how to handle packets
482 without MAC-header. A patch for tcpdump is included in the utility-package
483 mentioned above.
485 "isdnctrl l2_prot <InterfaceName> <L2-ProtocolName>"
486 Selects a layer-2-protocol.
487 (With the ICN-driver and the HiSax-driver, "x75i" and "hdlc" is available.
488 With other drivers, "x75ui", "x75bui", "x25dte", "x25dce" may be
489 possible too. See README.x25 for x25 related l2 protocols.)
491 isdnctrl l3_prot <InterfaceName> <L3-ProtocolName>
492 The same for layer-3. (At the moment only "trans" is allowed)
494 "isdnctrl list <InterfaceName>"
495 Shows all parameters of an interface and the charge-info.
496 Try "all" as the interface name.
498 "isdnctrl hangup <InterfaceName>"
499 Forces hangup of an interface.
501 "isdnctrl bind <InterfaceName> <DriverId>,<ChannelNumber> [exclusive]"
502 If you are using more than one ISDN card, it is sometimes necessary to
503 dial out using a specific card or even preserve a specific channel for
504 dialout of a specific net-interface. This can be done with the above
505 command. Replace <DriverId> by whatever you assigned while loading the
506 module. The <ChannelNumber> is counted from zero. The upper limit
507 depends on the card used. At the moment no card supports more than
508 2 channels, so the upper limit is one.
510 "isdnctrl unbind <InterfaceName>"
511 unbinds a previously bound interface.
513 "isdnctrl busreject <DriverId> on|off"
514 If switched on, isdn4linux replies a REJECT to incoming calls, it
515 cannot match to any configured interface.
516 If switched off, nothing happens in this case.
517 You normally should NOT enable this feature, if the ISDN adapter is not
518 the only device connected to the S0-bus. Otherwise it could happen that
519 isdn4linux rejects an incoming call, which belongs to another device on
520 the bus.
522 "isdnctrl addslave <InterfaceName> <SlaveName>
523 Creates a slave interface for channel-bundling. Slave interfaces are
524 not seen by the kernel, but their ISDN-part can be configured with
525 isdnctrl as usual. (Phone numbers, EAZ/MSN, timeouts etc.) If more
526 than two channels are to be bundled, feel free to create as many as you
527 want. InterfaceName must be a real interface, NOT a slave. Slave interfaces
528 start dialing, if the master interface resp. the previous slave interface
529 has a load of more than 7000 cps. They hangup if the load goes under 7000
530 cps, according to their "huptimeout"-parameter.
532 "isdnctrl sdelay <InterfaceName> secs."
533 This sets the minimum time an Interface has to be fully loaded, until
534 it sends a dial-request to its slave.
536 "isdnctrl dial <InterfaceName>"
537 Forces an interface to start dialing even if no packets are to be
538 transferred.
540 "isdnctrl mapping <DriverId> MSN0,MSN1,MSN2,...MSN9"
541 This installs a mapping table for EAZ<->MSN-mapping for a single line.
542 Missing MSN's have to be given as "-" or can be omitted, if at the end
543 of the commandline.
544 With this command, it's now possible to have an interface listening to
545 mixed 1TR6- and Euro-Type lines. In this case, the interface has to be
546 configured to a 1TR6-type EAZ (one digit). The mapping is also valid
547 for tty-emulation. Seen from the interface/tty-level the mapping
548 CAN be used, however it's possible to use single tty's/interfaces with
549 real MSN's (more digits) also, in which case the mapping will be ignored.
550 Here is an example:
552 You have a 1TR6-type line with base-nr. 1234567 and a Euro-line with
553 MSN's 987654, 987655 and 987656. The DriverId for the Euro-line is "EURO".
555 isdnctrl mapping EURO -,987654,987655,987656,-,987655
556 ...
557 isdnctrl eaz isdn0 1 # listen on 12345671(1tr6) and 987654(euro)
558 ...
559 isdnctrl eaz isdn1 4 # listen on 12345674(1tr6) only.
560 ...
561 isdnctrl eaz isdn2 987654 # listen on 987654(euro) only.
563 Same scheme is used with AT&E... at the tty's.
565 6. If you want to write a new low-level-driver, you are welcome.
566 The interface to the link-level-module is described in the file INTERFACE.
567 If the interface should be expanded for any reason, don't do it
568 on your own, send me a mail containing the proposed changes and
569 some reasoning about them.
570 If other drivers will not be affected, I will include the changes
571 in the next release.
572 For developers only, there is a second mailing-list. Write to me
573 (fritz@wuemaus.franken.de), if you want to join that list.
575 Have fun!
577 -Fritz