Howto configure isdnutils
=========================

For the latest info on the debian isdnutils package, see:
http://people.debian.org/~paul/isdnutils/

See also README.Debian

Example versions of the configuration files mentioned below (those that
exist in /etc/isdn/) can be created via the `isdnconfig' menu-driven
utility.

If what you want is simply a connection to the internet, jump to the
"ISDN ppp daemon" section below!


the naming system
-----------------
/dev/ttyI0      isdn modem emulation device. Note that the user interface
                emulates a modem (it understands AT commands); this emulation
                doesn't mean you can use it to call an analog modem.
/dev/cui0       isdn modem emulation device : old form. don't use (obsolete).
/dev/ippp0      synchronous ppp device
ippp0           isdn network device. This name is used if you transfer with
                syncPPP encapsulation (the usual for internet connections).
                This is "connected" to /dev/ippp0 by the ipppd daemon.
                If you have multiple ippp devices, assign the one you want to
                have the default route to 'ippp0', this is what is expected by
                the default scripts.
isdn0           isdn network device. This name is used with rawIP network
                connections (to other linux systems for example, preferable
                to syncPPP).

see also : ttyI(4)


ISDN kernel modules
-------------------

 - The default debian kernel has ISDN support, so no reason to recompile your
   kernel just for ISDN.
 - In the 2.2.xx range of kernels, use at least 2.2.12; below that,
   no guarantees of a working system; above that, it keeps getting
   better (so get the highest 2.2.x version!).
 - Configure lilo to pass the right options to the kernel if you have configured
   the ISDN drivers statically, i.e. not as modules:
   E.g. in /etc/lilo.conf : append="hisax=3,2,10,0xd80,0,line0"

If you use modules (preferable):

 - Use modconf, select the modules "isdn" and "hisax" with the right
   options. In case you have a card not supported by hisax, you won't be able
   to use the "hisax" driver; check the kernel docs.

 - The hisax docs are included with isdnutils as
   /usr/share/doc/isdnutils/README.HiSax ; for other ISDN kernel docs you will
   have to install the appropriate kernel-doc-2.2.xx package and see the
   /usr/share/doc/kernel-doc-2.2.xx/Documentation/isdn/ directory.

 - You can look what modconf did:
   /etc/modules should have the lines
        isdn
        hisax type=3 protocol=2 io=0x180 irq=15 id=line0
   If you want kerneld to load the modules (not recommended),
   you don't need the /etc/modules entry, but additional entries
   in /etc/conf.modules:
        options hisax type=3 protocol=2 io=0x180 irq=15 id=line0
        alias ippp0 isdn
        alias char-major-43 hisax
        alias char-major-44 hisax
        alias char-major-45 hisax


ISDNLOG
-------

Isdnlog is a tool to keep a log of all ISDN calls. It also allows you
to start specific programs upon certain events, such as an incoming
call.

One isdnlog may be started per ISDN card. The corresponding config file
with a number of examples, which needs to be edited before isdnlog will
be activated, is found in:

    /etc/isdn/isdnlog.DEVICE

DEVICE can be isdnctrl0, isdnctrl2, ...

A special case is using two ISDN cards, where one of the cards is connected
"wrong": its receiving line is connected to what is usually the transmit line.
This means it can listen to what other ISDN equipment is sending out, e.g.
which number is being dialled. This way you can monitor the outgoing calls from
the other equipment as well. This is called running isdnlog is "dual" mode, and
is done with the -2 option (see the isdnlog(8) manpage for futher info on this
option).


ISDN network device
-------------------

isdnconfig will create example files with lots of comments, which need to
be edited before the configuration will be used:

    /etc/isdn/device.DEVICE

The most important places that need to be edited are marked with XXX_

DEVICE can be isdn0, isdn1 ... (used for rawip devices)
or ippp0, ippp1, ippp2 ... (used for ippp devices).
See also: isdnctrl(8) ifconfig(8) route(8)
          and any book about unix networking for ifconfig/route details
          (or the networking howto)
ippp0 should be the interface that is the default route; if not, you need to
edit the device.xxx file(s).

If using ipmasq, the stuff should work pretty much out of the box, if you tell
ipmasq that ippp0 is the external interface.


ISDN ppp daemon, or: internet connection
---------------

For this, the ipppd package must also be installed!

->-------------

Step by step guide for making a connection to the internet:

 1. Get the hardware recognized by linux (modconf and friends)

 2. use isdnconfig to
 	
 	a) create at least /etc/isdn/isdnlog.isdnctrl0 (needed to get
 	   messages from your S0-Bus) and edit isdn.conf and isdnlog.isdnctrl0
	   to your needs and fire up '/etc/init.d/isdnutils start'
 	   call yourself with a phone and check /var/log/isdn/isdnlog
	   NOTE: this is not necessary for just an internet connection!

 	b) create /etc/isdn/device.ippp0 and /etc/isdn/ipppd.ippp0
	   the first file is for phone numbers, routing and firewalling
 	   stuff, the latter for options which the ipppd is called with.
 	   (note: the debian version of the ipppd ignores /etc/ppp/(i)options)

 3. Set up /etc/ppp/pap-secrets or /etc/ppp/chap-secrets

 4. Edit /etc/isdn/device.ippp0 and /etc/isdn/ipppd.ippp0, paying special
    attention to the places marked with _XXX . Most people won't need to
    change anything else.

 5. If you don't have a flatrate and money matters set dialmode in
    /etc/isdn/device.ippp0 to manual and connect to the internet via
    'isdnctrl dial ippp0'. Use 'isdnctrl hangup ippp0' to disconnect.
    Otherwise you can rely on autodial and huptimeout.

 6. (for network "gurus") The default route is set in device.ippp0 to ippp0,
    and also in /etc/ppp/ip-up.d/00-ipppd and /etc/ppp/ip-down.d/99-ipppd .
    So if you don't want this, either don't use ippp0 as an interface (nothing
    makes you start with 0!) or edit all three files.

-<-------------

isdnconfig will create example files with lots of comments, which need to
be edited before ipppd will be started:

    /etc/isdn/ipppd.DEVICE

The most important place that needs to be edited is marked with XXX_
You will also need to add an entry to /etc/ppp/pap-secrets or
/etc/ppp/chap-secrets.

DEVICE can be ippp0, ippp1 ...
Note: there is no connection between the network device "ipppX" and the
real device /dev/ipppX, unless you create a pppbind with isdnctrl.
Default in debian is to create pppbinds and let one ipppd handle one
connection (in theory one ipppd process can handle many ipppX devices, but
that generally is confusing).

The ipppd does not support ioptions.<tty>. And this setup will neither
read /etc/ppp/options nor ioptions. Put the whole configuration into
/etc/isdn/ipppd.DEVICE !

Ipppd will run the /etc/ppp/ip-up script when a connection is made and will run
the /etc/ppp/ip-down script when a connection goes down. If you have the ppp
package installed (as is recommended), those scripts will run each of the
scripts in the /etc/ppp/ip-up.d/ and /etc/ppp/ip-down.d/ directories. Isdnutils
will have put a script into each of these directories; this can be useful for
setting the default route (if you have dynamic IP numbers). You can also do
other things; read the comments in /etc/ppp/ip-up and /etc/ppp/ip-down, and
also in the /etc/ppp/ip-up.d/00-ipppd and /etc/ppp/ip-down.d/99-ipppd scripts.

For MPPP (channel bundling), see /usr/share/doc/ipppd/README.MPPP .

see also : ipppd(8)


ISDN ttyI devices
-----------------

You can use these devices with any program like normal modem devices
ttyS (e.g. uucp, minicom, pppd). With pppd you can create asynchronous
ppp connections (that's nonsense with isdn, but you can do that).

Note, however, that you CANNOT connect with analog modems! The ttyI
devices only resemble normal modem devices in the way you use the AT
commands.

The first two devices ttyI0 and ttyI1 belong to your first isdn card,
the next two devices to the next card etc. And after that it starts
again with the first card. If you only have one isdn card, all devices
are used with that card. If you have two cards, the devices 0,1,4,5,8,9
... are used by the first card, the devices 2,3,6,7,10,11 ... are used
by the second card. [PS: this apparently isn't valid any more, but I
only have one card, so can't check this]

A device is not bound to a channel. You can use several device at the
same time (e.g. have vboxgetty waiting for incoming calls on 5 devices,
and use two devices with minicom at the same time).

FIXME Ubuntu: point users to example in /etc/event.d/ttyI0

/etc/inittab is not relevant anymore

To allow dialins to your system via X.75, you could add an entry to
/etc/inittab such as the following:

I0:2345:respawn:/sbin/mgetty -D -m '"" ATZ OK AT&Eyourmsnhere OK AT&B512 OK' -s 38400 ttyI0

The given speed 38400 is only a placeholder, comms will always be at
64kb/s.


ISDN modem emulation
--------------------

With iprofd you can store your ttyI modem settings with AT&W as if it
were a modem. isdnconf will create an empty file (or use "touch
/etc/isdn/iprofd.data"). Do not change this file when iprofd is running!

see also : iprofd(8)

However, I personally recommend forgetting about this and use the
"modem init string" feature of whatever package you use to access the
/dev/ttyIx devices.


ISDN voice box
--------------

FIXME Ubuntu: point users to example in /etc/event.d/ttyI1

/etc/inittab is not relevant anymore

Edit /etc/inittab to activate vboxgetty. example for ttyI1
(assuming ttyI0 is in use for X.75, although there is no need
to use the ttyI devices in ascending order):

    I1:2345:respawn:/usr/sbin/vboxgetty -d /dev/ttyI1

Read the documentation that comes with isdnvbox for more info.
Also see the /var/spool/vbox/USER/vbox.conf file.
