%:Usage instructions  -  ATM on Linux, release 0.59
%:-------------------------------------------------
%:
%:

For updates of ATM on Linux, please check the Web page at  
http://ica1www.epfl.ch/linux-atm/ 

%:         WARNING
%:

This is experimental software. There are known major bugs and certainly 
even many more yet unknown problems. Internal and external interfaces are 
far from being stable. In fact, they change daily. Use at your own risk.


Installation
============

In order to install this package, you need 

  - the package itself  
    ftp://lrcftp.epfl.ch/pub/linux/atm/dist/atm-0.59.tar.gz  
  - the Linux kernel, version 2.2.9, e.g. from  
    ftp://ftp.kernel.org/pub/linux/kernel/v2.2/linux-2.2.9.tar.gz  
  - Perl, version 4 or 5 
  - if you want memory debugging: MPR version 1.6, e.g. from  
    ftp://sunsite.unc.edu/pub/Linux/devel/lang/c/mpr-1.6.tar.gz  


The source tree
---------------

First, create a directory in which the linux/ kernel source directory and 
the ATM on Linux distribution directory (atm/) should be created, and put 
all the files listed above there. Then extract the ATM on Linux 
distribution:

tar xfz atm-0.59.tar.gz

and the kernel source:

tar xfz linux-2.2.9.tar.gz

Finally, you can extract the ATM-related patches:

cd linux
patch -s -p1 <../atm/atm.patch

The distribution installs into the following directories:

  atm/  Documentation in ASCII format, kernel patch, top-level Makefile, 
    and distribution scripts 
  atm/sigd/  UNI 3.0, UNI 3.1, and UNI 4.0 signaling demon: atmsigd 
  atm/saal/  Signaling AAL library (SSCOP, SSCF, and SAAL) 
  atm/qgen/  Q.2931-style message handling 
  atm/ilmid/  ILMI address registration demon: ilmid 
  atm/maint/  ATM maintenance programs: atmaddr, atmdiag, atmdump, atmtcp, 
    esi, sonetdiag, saaldump, and zntune 
  atm/test/  Test programs: align, aping, aread, awrite, br, bw, isp, 
    ttcp_atm, window 
  atm/arpd/  ATMARP tools and demon: atmarp, atmarpd 
  atm/led/  LAN Emulation demon: zeppelin 
  atm/lane/  LAN Emulation servers: bus, lecs, les 
  atm/mpoad/  Multi-Protocol Over ATM demon: mpcd 
  atm/aqd/  Arequipa demon: aqpvc, arequipad 
  atm/debug/  Debugging tools: aqtest, delay, ed, encopy, endump, svctor, 
    zndump, and znth 
  atm/lib/  Libraries for applications and demons 
  atm/doc/  Documentation in LaTeX and conversion tools 
  atm/man/  Miscellaneous man pages 
  atm/extra/  Extra packages (tcpdump and ans) 
  atm/config/  Configuration file examples 
  atm/switch/  Switch fabric control (under construction) 


Kernel configuration
--------------------

Now, change links (if necessary) and do the usual  make config ,  make 
menuconfig , or  make xconfig . First, enable

Prompt for development and/or incomplete code/drivers
  (CONFIG_EXPERIMENTAL)

You should find the following new options:

Asynchronous Transfer Mode (ATM, EXPERIMENTAL) (CONFIG_ATM)
  Use "new" skb structure (CONFIG_ATM_SKB)
  Classical IP over ATM (CONFIG_ATM_CLIP)
    Do NOT send ICMP if no neighbour (CONFIG_ATM_CLIP_NO_ICMP)
  LAN Emulation (LANE) support (CONFIG_ATM_LANE)
  Multi-Protocol Over ATM (MPOA) support (CONFIG_ATM_MPOA)
ATM over TCP (CONFIG_ATM_TCP)
Efficient Networks ENI155P (CONFIG_ATM_ENI)
  Enable extended debugging (CONFIG_ATM_ENI_DEBUG)
  Fine-tune burst settings (CONFIG_ATM_ENI_TUNE_BURST)
    Enable 16W TX bursts (discouraged) (CONFIG_ATM_ENI_BURST_TX_16W)
    Enable 8W TX bursts (recommended) (CONFIG_ATM_ENI_BURST_TX_8W)
    Enable 4W TX bursts (optional) (CONFIG_ATM_ENI_BURST_TX_4W)
    Enable 2W TX bursts (optional) (CONFIG_ATM_ENI_BURST_TX_2W)
    Enable 16W RX bursts (discouraged) (CONFIG_ATM_ENI_BURST_RX_16W)
    Enable 8W RX bursts (discouraged) (CONFIG_ATM_ENI_BURST_RX_8W)
    Enable 4W RX bursts (recommended) (CONFIG_ATM_ENI_BURST_RX_4W)
    Enable 2W RX bursts (optional) (CONFIG_ATM_ENI_BURST_RX_2W)
ZeitNet ZN1221/ZN1225 (CONFIG_ATM_ZATM)
  Enable extended debugging (CONFIG_ATM_ZATM_DEBUG)
  Enable usec resolution timestamps (CONFIG_ATM_ZATM_EXACT_TS)
IDT 77201 (NICStAR) (CONFIG_ATM_NICSTAR)

The burst settings of the ENI driver can be fine-tuned. This may be 
necessary if the default settings lead to buffer overruns in the PCI 
chipset. See the on-line help on CONFIG_ATM_ENI_TUNE_BURST for a detailed 
discussion of the implications of changing the burst settings.

Note that the file drivers/atm/nicstar.h contains a few configurable 
settings for the IDT 77201 driver.

Some drivers can also be used with certain compatible cards. The latest 
information about compatible cards can be found at  
http://ica1www.epfl.ch/linux-atm/info.html 

Then build your kernel and reboot.


Driver messages
---------------

If you've configured the ENI155p-MF driver, you should see two lines like 
these: 

eni(itf 0): rev.0,base=0xff400000,irq=10,mem=512kB (00-20-EA-00-07-56)
eni(itf 0): FPGA,MMF

 (512kB for the -C version, 2048kB for the -S version.)

If you've configured the ZN1221/ZN1225 driver, you will get something like 

zatm(itf 0): rev.3,base=0xf800,irq=11,mem=128kB,MMF (00-20-D4-10-2A-80)
zatm(itf 0): uPD98401 0.5 at 30.024 MHz
zatm(itf 0): 16 shapers, 32 pools, 2048 RX, 3958 VCs

 Note that your board needs to be at least at revision level 3 if you want 
to use it in a Triton-based system.

Note that if you've configured only the ATM over TCP driver, there are no 
messages at startup, because ATM over TCP devices are created later using 
the atmtcp command.


Memory debugging
----------------

If you want to enable debugging for options for memory allocations, you 
need to install MPR before compiling the ATM tools. Extract mpr-1.6.tar.gz 
into a directory at the same level as linux and atm. Then do:

cd mpr-1.6
./configure x86-linux
make
install -c -m 0644 libmpr.a /usr/lib
install -c -m 0755 mpr mprcc mprhi mprlk mprsz /usr/local/bin
install -c -m 0755 mprfl mprnm mprpc mprdem mprmap /usr/local/bin

Detection of some general mis-use of  malloc  and  free  is automatically 
performed if the program was compiled with MPR present. Tracing of 
allocations is enabled by setting  MPRPC  and  MPRFI . See mpr.doc in the 
MPR distribution for details.

Only little run-time overhead is incurred if memory debugging is included, 
but those environment variables are not set.


ATM tools
---------

Now, as the final step, configure and build the ATM tools. Configuration is 
only necessary if your switch uses UNI 3.1 or 4.0, or if it has certain 
bugs. The configuration options are at the beginning of atm/Rules.make.

Then, build the ATM tools with:

cd ../atm
make depend
make
make install

make install will install executables in the directory /usr/local/bin and 
/usr/local/sbin, respectively. Libraries and header files are installed in 
/usr/lib and /usr/include, respectively. Man pages are installed in 
/usr/local/man.


Extra packages
--------------

Some programs are based on large packages that are already distributed 
outside of the ATM context. For such packages, only patches are contained 
in the ATM on Linux distribution. The complete packages can be obtained 
either from the original source (described in atm/extra/extra.html) or from  
ftp://lrcftp.epfl.ch/pub/linux/atm/extra/ .

The packages are automatically downloaded, patched, and built by running  
make <package_name>  in the atm/extra/ directory (requires that the Lynx 
Web browser is installed).

Currently, the following extra packages are available: 

  tcpdump  dumps network traffic (enhanced for ATM) 
  ans  ATM name server (based on named 4.9.5) 

Note that text2atm automatically uses ANS if available, so ans only needs 
to be installed on systems providing name server functionality or if 
ATM-aware maintenance tools (nslookup, etc.) are needed.

A script hosts2ans.pl to convert a /etc/hosts.atm file to ANS zone files is 
provided in atm/extra/. Its use is described at the beginning of the file.


Device setup
============

This section describes device-specific configuration operations, and 
general diagnostic procedures at the ATM or SONET level. Please see the 
adapter documentation for details on hardware installation and diagnosis.


ATM over TCP setup
------------------

If you have no real ATM hardware, you can still exercise the API by using 
the ATM over TCP "driver". It emulates ATM devices which are directly wired 
to remote devices (i.e. there is no VPI/VCI swapping).

To establish one (bidirectional) "wire", become root on both systems (or 
run both sides on the same system to create two connected "interfaces") and 
run the following command on one of them (let's call it "a"):

  a# atmtcp -l  

Then, on the other system ("b"), run

  b# atmtcp -c <ip_address_of_a>  

Both atmtcps will report on their progress and the kernel should display a 
message like

atmtcp (itf 1): ready

on each system. Note that atmtcp keeps running and that it must not be 
interrupted.

Multiple "wires" can be attached to the same machine by specifying a port 
number (default is 8401). Note that no AAL processing is performed. It is 
therefore not possible to receive data using a different AAL (e.g. AAL0) 
than the one with which the data was sent.


ZN1221/ZN1225 tuning
--------------------

The ZeitNet ZN1221 and ZN1225 adapters use pre-allocated pools of free 
memory buffers for receiving. Whenever a VC with a certain maximum SDU size 
is opened for receiving, the corresponding pool is filled with free buffers 
by the device driver. The adapter removes buffers while it receives data. 
When the number of remaining buffers falls below a certain threshold, the 
device driver replenishes the pool again.

The lower and the upper limits for the number of free buffers, and the 
threshold for adapting to a new data offset (see below for details), can be 
set using the zntune program. Usage:

  zntune [-l <low_water>] [-h <high_water>] [-t <threshold>] <itf> [<pool>] 
 

The changes are applied to all pools if no pool number is specified. Pool 2 
stores 64 bytes packets, pool 3 stores 128 bytes packets, etc. Pools 0 and 
1 are currently unused.

The current settings and some usage statistics can be obtained by invoking 
zntune without specifying new parameters:

  zntune [-z] <itf> [<pool>]  

The "Size" column shows the buffer size in Bytes. The "Ref" column shows 
the number of open VCs using that pool. The "Alarm" column shows how many 
times the number of free buffers has fallen below the low-water mark since 
the counters were reset. Similarly, the "Under" column shows how many times 
an incoming PDU had to be discarded because the corresponding pool was 
empty.

The columns "Offs", "NxOf", "Count" and "Thres" show the alignment adaption 
status. "Offs" is the offset of user data the driver currently expects in 
incoming PDUs. For single-copy, receive buffers are aligned accordingly so 
that data is received at page boundaries. "NxOf" is the user data offset of 
the most recently received PDU, where the offset differs from the currently 
assumed offset. "Count" is the number of PDUs that have been received in 
sequence with an offset of "NxOf". Finally, "Thres" is the threshold value 
"Count" has to reach for "NxOf" to become the new current offset.

Use the  -z  option to reset the "Alarm" and "Under" counters.


Files in /proc/atm
------------------

Some status information about the ATM subsystem can be obtained through 
files in /proc/atm. /proc/atm/arp contains information specific to 
Classical IP over ATM, see section "CLIP".

/proc/atm/devices lists all active ATM devices. For each device, the 
interface number, the type label, the end system identifier (ESI), and 
statistics are shown. The statistics correspond to the ones available via 
atmdiag.

Individual ATM devices may register entries of the form  <type>:<number>  
(e.g.  eni:0 ) which contain device-specific information.

/proc/atm/pvc and /proc/atm/svc list all PVC and SVC sockets. For both 
types of sockets, the interface, VPI and VCI numbers are shown. For PVCs, 
this is followed by the AAL and the traffic class and the selected PCR for 
the receive and the transmit direction. For SVCs, the SVC state and the 
address of the remote party are shown. SVCs with the interface number 999 
are used for special control purposes as indicated in the "State" column.


ATM diagnostics
---------------

Various counters of the ATM device drivers can be queried with the atmdiag 
program. See the corresponding man page for details.


SONET diagnostics
-----------------

The SONET diagnostics tool can be used to monitor link performance and to 
simulate errors. In order to get current SONET statistics, run it with the 
ATM interface number as the argument, e.g.

% sonetdiag 0

The counters can be reset with the  -z  option:

# sonetdiag -z 0

The following network failures can be simulated:*

  *  Some adapters may only support a subset of this.

   sbip   insert section errors (B1) 
   lbip   insert line errors (B2) 
   pbip   insert path errors (B3) 
   frame   force (RX) frame loss 
   los   insert loss of signal 
   lais   insert line alarm indication signal 
   pais   insert path alarm indication signal 
   hcs   insert header checksum errors 

A failure is enabled by adding the corresponding keyword on the command 
line. The failure is cleared by prefixing the keyword with a minus sign, 
e.g.

a# sonetdiag -z 0 >/dev/null
b# sonetdiag -z 0 >/dev/null
a# sonetdiag 0 los
a# sonetdiag 0 -los
b# sonetdiag 0 | grep BIP
Section BIP errors:      56200
Line BIP errors:           342
Path BIP errors:           152
a# sonetdiag 0 | grep FEBE
Line FEBE:                 342
Path FEBE:                 152

If any diagnostic error insertions are active, their keywords are shown 
when sonetdiag is used to obtain statistics. Note that some error 
insertions may be automatically switched off by the hardware.


Native ATM PVCs
===============

PVCs can be used for machines that are either connected back to back or via 
a switch. In the latter case, the cell forwarding has to be manually set up 
at the switch.


Traffic tools
-------------

aread/awrite and br/bw are simple programs to access the ATM API. awrite 
sends the text string passed as its second argument in an AAL5 PDU. aread 
receives one AAL5 PDU and displays it in hex. Both programs also display 
the return values of the corresponding system calls and the current values 
of errno.

bw either sends its standard input or a stream of blocks containing 
arbitrary data (if a number is passed as its fourth argument) in 8 kB AAL5 
PDUs. br receives AAL5 PDUs and writes them to standard output.

The first argument of aread, awrite, br and bw is always the PVC address, 
i.e. the ATM interface number, the VPI and the VCI number, with a dot 
between elements. The interface number can be omitted if it is zero. 
Example:

% awrite 1.0.42 hi

Note that some adapters only support VPI == 0. Also, the VCI range may be 
limited, e.g 0 to 1023. The interface number can be obtained from the 
initialization message the driver printed during startup. atm0 is interface 
0, atm1 is interface 1, etc. If the system is equipped with a real ATM 
adapter (e.g. not only atmtcp), that adapter is normally at atm0.

aping receives and sends small AAL5 PDUs on a PVC. It expects that messages 
it sends are either echoed back or that a similar program on the other side 
generates a stream of messages. aping reports an error if no messages are 
received for too long. aping is invoked by specifying the PVC, like aread.

For "real" tests, you should use the modified version of ttcp that comes 
with this package. The original is on  ftp://ftp.sgi.com/sgi/src/ttcp . The 
following options have been added:

   -a   use native ATM instead of UDP/TCP. The address must be in the 
    format  [<itf>.]<vpi>.<vci>  for PVCs, or a valid ATM end system 
    address for SVCs. 
   -P <num>   use a CBR connection with a peak cell rate of <num> cells per 
    second. Default is to use UBR. 
   -C   disable (UDP) checksums 
   -Q <atm_address>   establish an Arequipa connection to the specified ATM 
    destination. On the receiver,  -Q <any_word>  enables acceptance of 
    incoming Arequipa connections. 

Example:

%a ttcp_atm -r -a -s 0.90
%b ttcp_atm -t -a -s 0.90


Direct cell access
------------------

On adapters where the device driver supports access to raw cells ("AAL0"), 
individual cells can be composed and received with the atmdump program.

Man page: atmdump.8

Example: 

a% sleep 10; date | ./atmdump -t 1 -c 0.51
b% ./atmdump 0.51
825079645.192480: VPI=0 VCI=51, GFC=0x0, CLP=1, Data SDU 1 (PTI 1)
   46 72 69 20 46 65 62 20 32 33 20 31 32 3a 34 37 
   3a 32 35 20 47 4d 54 20 31 39 39 36 0a 00 00 00 
   00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 




Signaling
=========


ATM hosts file
--------------

Because ATM addresses are inconvenient to use, most ATM tools also accept 
names instead of numeric addresses. The mapping between names and numbers 
is defined in the file /etc/hosts.atm. The structure of this file is 
similar to the /etc/hosts file:

<numeric_address> <name(s)>

e.g.

47.0005.80FFE1000000F21A26D8.0020EA000EE0.00 pc2-a.fqdn pc2-a
47.0005.80FFE1000000F21A26D8.0020D4102A80.00 pc3-a.fqdn pc3-a

The numeric address can be specified in any of the formats described in 
[1]. The numeric address(es) of a Linux system can be determined with the 
command  atmaddr -n  (see also section "Manual address configuration").

Many ATM tools also attempt to find the corresponding name when displaying 
an address. When translating from the numeric form to a name, the first 
applicable name in the file is used.

In addition to ATM addresses for SVCs, also PVC addresses can be stored in 
/etc/hosts.atm. If different address types are stored under the same name, 
the first suitable one will be chosen, i.e. if an application explicitly 
requests only SVC addresses, any PVC addresses will be ignored.


ANS
---

If you have access to the ATM Name Service (ANS, e.g because you've 
installed the ANS extension), you can use it instead of or in addition to 
the hosts file by specifying the host that runs ANS in the /etc/resolv.conf 
file.

For performing reverse lookups of E.164 addresses, the list of telephony 
country codes needs to be known. That list can be obtained from  
http://www.itu.ch/itudoc/itu-t/lists/  the file has a name of the form 
tf_cc_e_*.rtf The script atm/lib/rtf2e164_cc.pl can be used to create the 
E.164 county codes table, e.g.

perl rtf2e164_cc.pl <tf_cc_e_13130.rtf >/etc/e164_cc


Signaling demon
---------------

Man pages: atmsigd.8, atmsigd.conf.4

Note that atmsigd's support for point-to-multipoint is very limited: only 
operation as a single leaf of a point-to-multipoint tree works.

By default, atmsigd is configured to conform to UNI 3.0. It can be compiled 
for UNI 3.1 by changing the  STANDARDS=  line at the beginning of 
atm/Rules.make, and running  make clean; make  in atm/qgen and atm/sigd (in 
this order).

Note that atmsigd is configured to be paranoid. If it detects unusual 
problems, it frequently terminates. This will (obviously) change in the 
future.

atmsigd also looks for a configuration file at the location specified with 
the  -c  option. The default location is /etc/atmsigd.conf.


ILMI demon
----------

ILMI provides a mechanism for automatic address configuration. If there is 
no switch or if the switch doesn't support ILMI, the ATM addresses must be 
configured manually (see section "Manual address configuration"). Note that 
the ILMI demon should not be used on interfaces where addresses are 
manually configured.

The ILMI demon is started as follows:

  # ilmid [-b] [-d] [-i <local_ip>] [-l <logfile>] [-u <uni_version>] [-v] 
    [-x] [<itf>]  

   -b   background. Run in a forked child process after initializing. 
   -d   enables debugging output. By default, ilmid is very quiet. 
   -i <local_ip>   IP address to tell switch when asked for one. Can be in 
    either dotted decimal or textual format. By default, ilmid uses some 
    heuristics to select a local IP address. 
   -l <logfile>   write diagnostic messages to the specified file instead 
    of to standard error. The special name  syslog  is used to send 
    diagnostics to the system logger. 
   -q <qos>   configures the ILMI VC to use the specified quality of 
    service. By default, UBR at link speed is used on the ILMI VC. 
   -u <uni_version>   set UNI version. Possible values are  3.0 ,  3.1 , 
    and  4.0 . The dot can be omitted. The default value depends on how 
    ilmid was compiled. Typically, it is  3.0 . 
   -v   enables extensive debugging output. 
   -x   disable inclusion of variable bindings in the ColdstartTrap. Some 
    switches (e.g. the LS100) only work if this option is set. 

If no interface number is specified, ilmid serves interface 0. You can 
check whether address registration was successful with the atmaddr command 
(see below).

The agent supports only the address registration procedures specified in 
section 5.8 of the ATM Forum's UNI 3.1 specification. These procedures 
involve the switch registering the network prefix on the host and the host 
registering the final ATM address back on the switch. The host accomplishes 
this by appending an ESI (End System Identifier) and a null selector byte 
to the network prefix registered by the switch. The ESI is the physical or 
MAC address of the ATM interface.


Manual address configuration
----------------------------

If your switch doesn't support ILMI, you have to set the ATM address 
manually on the switch and on the PC(s). On the Linux side, make sure that 
ilmid doesn't interfere, then use the atmaddr command to set the 
address(es).

Man pages: atmaddr.8

Manual configuration of ATM addresses on the switch depends on the brand. 
On a Fore ASX-200, it can be done with the following command:

  conf nsap route new <nsap_addr> 152 <port> <vpi>  

e.g.



conf nsap route new 47000580ffe1000000f21510650020ea000ee000 152 1a2 0
                    |<---- NSAP prefix ----->||<--ESI--->|^^
                                                          SEL



The entire NSAP address always has to have a length of 40 digits. Note that 
you can also use addresses with a different prefix and an ESI that doesn't 
correspond to any ESI your adapters have. The value of the selector byte 
(SEL) is ignored.


Running two ATM NICs back-to-back
---------------------------------

It is also possible to run with two ATM NICs connected back-to-back, and no 
switch in between*. This is great for simple test environments.

  *  This section was written by Richard Jones  rjones@imcl.com . Comments 
    should be directed to me as well as to Werner.

First, if you're using UTP or STP-5, you need a suitable cable. Our 
experience with standard 100Base-T back-to-back cables was not good. It 
appears that the pin-out they use is different. After some false starts, we 
found that the following cable works:

RJ45                            RJ45
   1        ------------        7
   2        ------------        8

   7        ------------        1
   8        ------------        2

Pins 3, 4, 5, 6 unconnected.

You can also make up a loopback cable with 1 - 7 and 2 - 8 connected for 
ultra-cheap setups.

Here we have two machines called "virgil" and "nestor". Substitute your own 
names as necessary.

One side of the ATM connection needs to use the network version of atmsigd 
and the other side should use the normal user version. So here on nestor we 
start atmsigd with:

atmsigd -b -m network

and on virgil with:

atmsigd -b

Without a switch, you won't be able to use ILMI. Instead, create a 
/etc/hosts.atm file containing two dummy addresses. Our ATM hosts file 
contains:

47.0005.80FFE1000000F21A26D8.0020EA000EE0.00    nestor-atm
47.0005.80FFE1000000F21A26D8.0020D4102A80.00    virgil-atm

These are completely spurious addresses, of course, but as long as you're 
not connected to a public or private ATM network, I don't think it matters. 
To set the address correctly in the driver, we use:

atmaddr -a virgil-atm

on virgil, and:

atmaddr -a nestor-atm

on nestor. Now start atmarpd on both machines in the normal way. Now you 
(should) have a working ATM set-up. To get IP over ATM and Arequipa 
working, just follow the instructions in section "IP over ATM".


Q.2931 message dumper
---------------------

The Q.2931 message compiler also generates a pretty-printer for Q.2931 
messages. The executable is called q.dump is stored in the qgen directory. 
Note that it is not copied elsewhere by  make install 

q.dump expects a sequence of whitespace-separated hex bytes at standard 
input and outputs the message structure if the message can be parsed.

Example:

% echo 09 03 80 00 05 5A 80 00 06 08 80 00 02 81 83 00 48 \
  00 00 08 | ./q.dump
_pdsc = 9 "Q.2931 user-network call/connection control message"
_cr_len = 3
call_ref = 8388613 (0x800005)
msg_type = 0x5a "RELEASE COMPLETE"
_ext = 1
_flag = 0 "instruction field not significant"
_action_ind = 0 "clear call"
msg_len = 6 (0x6)
  _ie_id = 0x08 "Cause"
    _ext = 1
    cause_cs = 0 "ITU-T standardized"
    _flag = 0 "instruction field not significant"
    _action_ind = 0 "clear call"
    _ie_len = 2 (0x2)
      _ext = 1
      location = 1 "private network serving the local user"
      _ext = 1
      cause = 3 "no route to destination"


IP over ATM
===========

IP over ATM is supported with Classical IP over ATM (CLIP, defined in 
RFC1577 [2]), LAN Emulation (LANE, defined in [3] and [4]) and 
Multi-Protocol Over ATM (MPOA, client only, defined in [5]).


CLIP
----

A demon process is used to generate and answer ARP queries. The actual 
kernel part maintains a small lookup table only containing partial 
information.

Man pages: atmarpd.8, atmarp.8

atmsigd and ilmid must already be running when atmarpd is started. Use the  
-b  option to make sure they're properly synchronized, e.g.

#!/bin/sh
atmsigd -b
ilmid -b
atmarpd -b
...

works, but

#!/bin/sh
atmsigd &
ilmid &
atmarpd &
...

frequently doesn't (yet).

The atmarp program is used to configure ATMARP. First, you have to start 
atmsigd, ilmid, and atmarpd, then create an IP interface and configure it:

  # atmarp -c <interface_name>
     # ifconfig atm0 <local_address> <possibly_more_options> up
      

e.g.

# atmarp -c atm0
# ifconfig atm0 10.0.0.3 up

If only PVCs will be used, they can now be created with a command like

# atmarp -s 10.0.0.4 0.0.70

NULL encapsulation is used if the  null  keywords is specified. Note that 
ARP requires LLC/SNAP encapsulation. NULL encapsulation can therefore only 
be used for PVCs.

When using SVCs, some additional configuration work may be necessary. If 
the machine is acting as the ATMARP server on that LIS, no additional 
configuration is required. Otherwise, the ATM address of the ATMARP server 
has to be configured. This is done by creating an entry for the network 
address with the option  arpsrv  set, e.g.

# atmarp -s \
  10.0.0.0 47.0005.80.ffe100.0000.f215.1065.0020EA000756.00 \
  arpsrv

Note that the ATMARP server currently has to be started and configured 
before any clients are configured.

The kernel ATMARP table can be read via /proc/atm/arp. The table used by 
atmarpd is regularly printed on standard error if atmarpd is started with 
the  -d  option. If atmarpd is invoked without  -d , the table is written 
to the file atmarpd.table in the dump directory (by default /var/run; can 
be changed with  -D ), and it can be read with  atmarp -a .


LAN Emulation
-------------

Besides Classical IP over ATM, LAN Emulation (LANE) can be used to carry IP 
over ATM. LANE emulates the characteristics of legacy LAN technology, such 
as support for broadcasts. LANE server support is described in 
atm/lane/USAGE.

Man pages: bus.8, lecs.8, les.8, and zeppelin.8

If you plan to run more than one LANE clients, LANE service or LANE clients 
and LANE service, you need to specify different local ATM addresses for 
each demon. Since all the LANE demons use similar service access points 
(SAPs) they need different ATM addresses to differentiate between 
connections.

Just as with CLIP, the LANE client consists of two parts: a demon process 
called zeppelin which takes care of the LANE protocol and kernel part which 
contains LANE ARP cache.

atmsigd and ilmid must already be running when zeppelin is started. When 
zeppelin starts, the kernel creates a new interface which can then be 
configured:

  # zeppelin <possibly_more_options> &
     # ifconfig lec0 <local_address> <possibly_more_options> up
      

In the example below, two LANE clients are started. The first client uses 
default interface  lec0 , default listen address and tries to join the 
default ELAN. The other LANE client gets interface  lec2  assigned to it, 
binds to local address  mybox3 , tries to join ELAN called  myelan  and 
will bridge packets between ELAN and Ethernet segments. Address  mybox3  is 
defined in /etc/hosts.atm. Rest of the bridging can be configured by 
reading the Bridging mini-HOWTO. [6]

# zeppelin &
# ifconfig lec0 10.1.1.42 netmask 255.255.255.0 \
                          broadcast 10.1.1.255 up
#
# zeppelin -i 2 -l mybox3 -n myelan -p &
# ifconfig lec2 10.1.2.42 netmask 255.255.255.0 \
                          broadcast 10.1.2.255 up

By default, zeppelin uses interface  lec0 , binds to local ATM address 
using selector byte value 0, tries to contact LECS using Well-Known LECS 
address, joins the default ELAN as defined by the LECS, accepts the MTU 
size as defined by the LES and will not act as an proxy LEC. These 
parameters can be tailored with command line options which are defined in 
zeppelin.8.

zeppelin will automatically join any ELANs which use higher MTU than the 
default MTU of 1516 bytes. The MTU of the LANE interface will adjust itself 
according to the MTU of the current ELAN.

The state of the LANE ARP cache entries can be monitored through 
/proc/atm/lec. For each entry the MAC and ATM addresses and status is 
listed. If the entry has an active connection, the connection identifiers 
are also listed.

The LANE service (lecs.8, les.8 and bus.8) is configured using 
configuration files. The configuration file syntax is listed on the 
respective manual pages.

A more detailed description of Linux LANE services is discussed in Marko 
Kiiskilae's Master's Thesis. [7]


MPOA
----

The Linux MPOA client continues the tradition of user space - kernel 
divided ATM services. The demon process called mpcd processes MPOA control 
packets while the kernel holds MPOA ingress and egress caches and does the 
packet forwarding.

Man page: mpcd.8

atmsigd and ilmid must already be running when mpcd is started. Since MPOA 
detects IP layer flows from LANE traffic, you need to have zeppelin running 
before MPOA can function. However, the order in which zeppelin and mpcd is 
started is not fixed. You can kill any of the demons at your will and 
restart it later without need to restart the other demon. The easiest way 
to disable MPOA is to kill the running mpcd.

Below is the example from Section "LAN Emulation" which starts two LANE 
clients. The configuration has been augmented with two MPOA clients which 
the LANE clients will serve.

# zeppelin &
# ifconfig lec0 10.1.1.42 netmask 255.255.255.0 \
                          broadcast 10.1.1.255 up
# mpcd -s mybox1 -l mybox2 &
#
# zeppelin -i 2 -l mybox3 -n myelan -p &
# ifconfig lec2 10.1.2.42 netmask 255.255.255.0 \
                          broadcast 10.1.2.255 up
# mpcd -i 2 -s mybox4 -l mybox5 &

The MPOA demon needs two different local ATM addresses which it uses when 
initiating and receiving data and control connections. The addresses can be 
the same as with e.g. zeppelin but must be different among other mpcd 
demons. By default, mpcd does not retrieve configuration information from 
the LECS. The necessary command line options and an example of using LECS 
are shown on the mpcd manual page. The manual page also lists the rest of 
the available options.

The contents of MPOA ingress and egress caches can be monitored through 
/proc/atm/mpc file.

The Linux MPOA client also supports CBR traffic class for shortcuts SVCs 
instead of default UBR. The QoS specifications for future shortcuts can be 
set and modified using /proc/atm/mpc.

# echo add 130.230.54.146 tx=80000,1600 rx=tx > /proc/atm/mpc
#             # generate enough traffic to trigger a shortcut
# cat /proc/atm/mpc 
QoS entries for shortcuts:
IP address
  TX:max_pcr pcr     min_pcr max_cdv max_sdu
  RX:max_pcr pcr     min_pcr max_cdv max_sdu
130.230.54.146  
     80000   0       0       0       1600   
     80000   0       0       0       1600   

Interface 2:

Ingress Entries:
IP address      State     Holding time  Packets fwded  VPI VCI
130.230.4.3     invalid   1160          0           
130.230.54.146  resolved  542           151            0   109
...

The shortcut to IP address  130.230.54.146  was established with the 
parameters shown above. There also exist patches which extend the flow 
detection to fully support layer 4 flows. The layer 4 flows are expressed 
as a 5 tuple (proto, local addr, local port, remote addr, remote port) and 
they identify application to application flows. If you are interested, see  
ftp://sunsite.tut.fi/pub/Local/linux-atm/mpoa/  for the latest patch.


References
==========

  [1]  Almesberger, Werner.  Linux ATM API,  
    ftp://lrcftp.epfl.ch/pub/linux/atm/api/ , July 1996. 
  [2]  Laubach, Mark.  Classical IP and ARP over ATM, RFC1577, January 
    1994. 
  [6]  Cole, Christopher.  Bridging mini-Howto,  
    http://metalab.unc.edu/LDP/HOWTO/mini/Bridge.html , September 1998. 
  [7]  Kiiskilae, Marko.  Implementation of LAN Emulation Over ATM in 
    Linux,  ftp://sunsite.tut.fi/pub/Local/linux-atm/misc/ , October 1996. 
  [3]  ATM Forum.  LAN Emulation Over ATM - Version 1.0, February 1996. 
  [4]  ATM Forum.  LAN Emulation Over ATM - Version 2 - LUNI Specification, 
    July 1997. 
  [5]  ATM Forum.  Multi-Protocol Over ATM - Version 1.0, July 1997. 
