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