<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<article id="ATM-Linux-HOWTO">

<articleinfo>
	<title>ATM on Linux HOWTO</title>

	<author>
		<firstname>Paul</firstname>
		<surname>Schroeder</surname>
		<othername role=mi>B</othername>
		<affiliation>
			<orgname>IBM Corporation</orgname>
			<address><email>paulsch@us.ibm.com</email></address>
		</affiliation>
	</author>

	<abstract>
<para>
This document describes how to install, setup, and configure the necessary
drivers and tools to support ATM networking under Linux.
</para>

<para>
For the latest information, please check the
<citetitle>ATM on Linux</citetitle>
<ulink url="http://linux-atm.sourceforge.net/">home page</ulink>.
</para>
	</abstract>

	<releaseinfo>
ATM support for Linux is currently in pre-alpha stage. There is an experimental release, which supports raw ATM connections (PVCs and SVCs),
IP over ATM, LAN emulation, MPOA, Arequipa, and some other goodies. 
	</releaseinfo>

	<pubdate>2001-10-18</pubdate>
	<revhistory>
		<revision>
			<revnumber>2.4.0</revnumber>
			<date>2001-10-18</date>
			<authorinitials>PBS</authorinitials>
			<revremark>
				Converted from LaTeX to DocBook along with some
				other additions and changes.
			</revremark>
		</revision>
	</revhistory>

</articleinfo>

<sect1 id="Introduction">
<title>Introduction</title>

<sect2 id="Introduction.Acknowledgements">
<title>Acknowledgements and Thanks</title>

<para>
This document is largely derived from the
<citetitle>Usage Instructions</citetitle> document that was included with the
<emphasis>ATM on Linux</emphasis> distribution up until version 0.79.  That
previous document was written by Werner Almesberger
<email>wa@almsesberger.net</email> while he was at the
<ulink url="http://icawww.epfl.ch/">Institute for computer Communications and Applications (ICA)</ulink>.
</para>

<para>
The section
<link linkend="Signaling.Running-Two-ATM-NICs-Back-to-Back" endterm="Signaling.Back-to-Back.title"></link>
was primarily written by Richard Jones <email>rjones@imcl.com</email>.
</para>

</sect2>

<sect2 id="Introduction.Copyright">
<title>Copyright</title>

<para>
Copyright 2001 IBM Corporation
</para>

<para>
Permission is granted to copy, distribute and/or modify this document under the
terms of the
<ulink url="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation License</ulink>, Version 1.1 or any later
version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license can be found at
<ulink url="http://www.gnu.org/copyleft/fdl.html">http://www.gnu.org/copyleft/fdl.html</ulink>.
</para>

<para>
A large portion of this document is derived from the
<citetitle>Usage Instructions</citetitle> included with the
<emphasis>ATM on Linux</emphasis> distribution up to version 0.79
which was released under the
BSD License, GNU General Public License (GPL), and GNU Lesser General
Public License (LGPL).
</para>

</sect2>

<sect2 id="Introduction.Mailing-List">
<title>Mailing List</title>

<para>
There is also a mailing list on which to discuss ATM on Linux.  If you have any
comments, questions, suggestions, or would just like to get involved, please
join the list.  You can <emphasis>subscribe</emphasis> and
<emphasis>unsubscribe</emphasis> to it at
<ulink url="http://lists.sourceforge.net/lists/listinfo/linux-atm-general">http://lists.sourceforge.net/lists/listinfo/linux-atm-general</ulink>.
</para>

<para>
The mailing list is archived at
<ulink url="http://www.geocrawler.com/lists/3/SourceForge/6487/0/">http://www.geocrawler.com/lists/3/SourceForge/6487/0/</ulink>. 
</para>
</sect2>

<sect2 id="Introduction.CVS-Access">
<title>CVS Access</title>

<para>
Users are encouraged to continue to use the releases instead of automatically
assuming they should grab the latest version out of CVS. However,
if you like living on the edge, here is how to do it.
</para>

<para>
First, log in anonymously: 

<informalexample><screen>
% cvs -d:pserver:anonymous@cvs.linux-atm.sourceforge.net.:/cvsroot/linux-atm login
</screen></informalexample>

Just hit return when prompted for a password. Then, checkout the repository: 

<informalexample><screen>
% cvs -z6 -d:pserver:anonymous@cvs.linux-atm.sourceforge.net.:/cvsroot/linux-atm co -P linux-atm
</screen></informalexample>

You may also specify a branch to check out specifically: 
<informalexample><screen>
% cvs -z6 -d:pserver:anonymous@cvs.linux-atm.sourceforge.net.:/cvsroot/linux-atm co -r V2_5_0 linux-atm
</screen></informalexample>

In either case, this will create a directory called "linux-atm" with the latest sources in it. When working inside this directory you will not need to
specify the '-d' option to CVS. For instance, you could just do 
<informalexample><screen>
% cvs -z6 up -d
</screen></informalexample>

To grab any changes that have been put in the repository (the '-d' option in
the above example is to the &quot;up&quot; sub-command and is different than the
'-d' used to specify the CVS root directory) 
</para>

<para>
After you have checked out the source tree, you will need to run the
<application>autotools</application> script in the top level directory before
you can configure, build, and install from that source tree:

<informalexample><screen>
# ./autotools 
Running aclocal...
Running autoconf...
Running autoheader...
Running automake...
automake: configure.in: installing `./install-sh'
automake: configure.in: installing `./mkinstalldirs'
automake: configure.in: installing `./missing'
configure.in: 26: required file `./ltconfig' not found
automake: Makefile.am: installing `./INSTALL'
automake: configure.in: installing `src/lane/ylwrap'
Finished...  Now run './configure' and 'make'...
</screen></informalexample>

</para>

<para>

If you wish to
create a tarred, gzipped distribution file or a RPM distribution file, run
<userinput>make dist</userinput> or <userinput>make rpm</userinput>
respectively.  The tarred, gzipped file will be placed in the top level of
the source tree and the RPM file will be placed in the
<filename class=directory>src/extra/RPMS</filename> directory.
</para>

<para>
The CVS archive may also be browsed on the web at:
<ulink url="http://cvs.linux-atm.sourceforge.net/cgi-bin/viewcvs.cgi/linux-atm/linux-atm/">http://cvs.linux-atm.sourceforge.net/cgi-bin/viewcvs.cgi/linux-atm/linux-atm/</ulink>.
</para>

<para>
Finally, if you would like to receive email including every diff that is committed to the repository as they go in, there is a mailing list called
&quot;linux-atm-commits&quot;:
<ulink url="http://lists.sourceforge.net/lists/listinfo/linux-atm-commits">http://lists.sourceforge.net/lists/listinfo/linux-atm-commits</ulink>.
</para>

<para>
This mailing list should be treated as receive-only. NO discussion or questions are allowed (even of patches which are sent through that list). All
discussion should be kept on the linux-atm-general mailing list. 
</para>

</sect2>


</sect1>


<sect1 id="Installation">
<title>Installation</title>

<para>
In order to install this package, you'll need

<itemizedlist>
	<listitem>
		<para>the package itself from <ulink url="http://linux-atm.sourceforge.net/dist.php">http://linux-atm.sourceforge.net/dist.php</ulink></para>
	</listitem>
	<listitem>
		<para>the Linux kernel, version 2.4.x, e.g. from <ulink url="ftp://ftp.kernel.org/pub/linux/kernel/v2.4/">ftp://ftp.kernel.org/pub/linux/kernel/v2.4/</ulink></para>
	</listitem>
	<listitem>
		<para>Perl, version 4 or 5</para>
	</listitem>
	<listitem>
		<para>if you want memory debugging: MPR, e.g. from <ulink url="ftp://ibiblio.org/pub/Linux/devel/lang/c/">ftp://ibiblio.org/pub/Linux/devel/lang/c/</ulink></para>
	</listitem>
</itemizedlist>

</para>

<sect2 id="Installation.The-Binary-RPMs">
<title>The Binary RPMs</title>

<para>
If you do not wish to futz with extracting and building the source yourself, the
ATM tools are also distributed in RPM format.  The RPM can be installed as
follows:

<informalexample><screen>
rpm -ivh <replaceable>linux-atm-x.x.x-x.rpm</replaceable>
</screen></informalexample>
</para>

</sect2>

<sect2 id="Installation.The-source-tree">
<title>The Source Tree</title>

<para>
First, extract the ATM on Linux distribution:

<informalexample><screen>
tar xzvf <replaceable>linux-atm-x.x.x.tar.gz</replaceable>
</screen></informalexample>

When extracted the distribution will create the
<filename class=directory>linux-atm-x.x.x/</filename> directory
with several sub-directories.
The following sub-directories are of note:

<variablelist>
	<varlistentry><term><filename class=directory>doc/</filename></term>
		<listitem>
			<para>Documentation (including this HOWTO) in SGML DocBook format</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/sigd/</filename></term>
		<listitem>
			<para>UNI 3.0, UNI 3.1, and UNI 4.0 signaling demon: <application>atmsigd</application></para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/saal/</filename></term>
		<listitem>
			<para>Signaling AAL library (SSCOP, SSCF, and SAAL)</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/qgen/</filename></term>
		<listitem>
			<para>Q.2931-style message handling</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/ilmid/</filename></term>
		<listitem>
			<para>ILMI address registration demon: <application>ilmid</application></para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/maint/</filename></term>
		<listitem>
<para>
ATM maintenance programs: <application>atmaddr</application>,
<application>atmdiag</application>, <application>atmdump</application>,
<application>atmloop</application>, <application>atmtcp</application>,
<application>enitune</application>, <application>esi</application>,
<application>sonetdiag</application>, <application>saaldump</application>, and
<application>zntune</application>
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/test/</filename></term>
		<listitem>
<para>
Test programs: <application>align</application>,
<application>aping</application>, <application>aread</application>,
<application>awrite</application>, <application>br</application>,
<application>bw</application>, <application>isp</application>,
<application>ttcp_atm</application>, <application>window</application>
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/arpd/</filename></term>
		<listitem>
<para>
ATMARP tools and demon: <application>atmarp</application>,
<application>atmarpd</application>
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/led/</filename></term>
		<listitem>
			<para>LAN Emulation demon: <application>zeppelin</application></para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/lane/</filename></term>
		<listitem>
<para>
LAN Emulation servers: <application>bus</application>,
<application>lecs</application>, <application>les</application>
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/mpoad/</filename></term>
		<listitem>
			<para>Multi-Protocol Over ATM demon: <application>mpcd</application></para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/debug/</filename></term>
		<listitem>
<para>
Debugging tools: <application>delay</application>,
<application>ed</application>, <application>encopy</application>,
<application>endump</application>,
<application>svctor</application>, <application>zndump</application>, and
<application>znth</application>
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/lib/</filename></term>
		<listitem>
			<para>Libraries for applications and demons</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/man/</filename></term>
		<listitem>
			<para>Miscellaneous man pages</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/extra/</filename></term>
		<listitem>
<para>
Extra packages and RPM spec files.
</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/config/</filename></term>
		<listitem>
			<para>Configuration and rc file examples</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><filename class=directory>src/switch/</filename></term>
		<listitem>
			<para>Switch fabric control (under construction)</para>
		</listitem>
	</varlistentry>
</variablelist>

</para>

</sect2>

<sect2 id="Installation.Kernel-Configuration">
<title>Kernel Configuration</title>

<para>
<note>
<title>NOTE</title>
<para>
If you are not familiar with building and installing a new kernel, please see
the
<ulink url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html"><citetitle>The Linux Kernel HOWTO</citetitle></ulink>
</para>
</note>
</para>

<para>
After unpacking the kernel distribution,
do the usual <command>make config</command>,
<command>make menuconfig</command>, or <command>make xconfig</command> in the
top-level of your Linux kernel source tree.
First, enable
<screen>
Prompt for development and/or incomplete code/drivers
  (CONFIG_EXPERIMENTAL)
</screen>

You should then be able to find the following options:

<screen>
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)
  Use suni PHY driver (155Mbps) (CONFIG_ATM_NICSTAR_USE_SUNI)
  Use IDT77015 PHY driver (25Mbps) (CONFIG_ATM_NICSTAR_USE_IDT77105)
Madge Ambassador (Collage PCI 155 Server) (CONFIG_ATM_AMBASSADOR)
  Enable debugging messages (CONFIG_ATM_AMBASSADOR_DEBUG)
Madge Horizon [Ultra] (Collage PCI 25 and Collage PCI 155 Client)
  Enable debugging messages (CONFIG_ATM_HORIZON_DEBUG)
Interphase ATM PCI x575/x525/x531 (CONFIG_ATM_IA)
  Enable debugging messages (CONFIG_ATM_IA_DEBUG)
</screen>
</para>

<para>
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.
</para>

<para>
Note that the file <filename class=headerfile>drivers/atm/nicstar.h</filename> contains a few
configurable settings for the IDT 77201 driver.
</para>

<para>
Some drivers can also be used with certain compatible cards. The latest
information about compatible cards can be found at
<citetitle>ATM on Linux</citetitle>
<ulink url="http://linux-atm.sourceforge.net/info.php">information</ulink>
page.
</para>

<para>
Then build your kernel and reboot.
</para>

</sect2>

<sect2 id="Installation.Driver-Messages">
<title>Driver Messages</title>

<para>
If you've configured the ENI155p-MF driver, you should see two lines like
these (512kB for the -C version, 2048kB for the -S version.):
<informalexample><screen>
eni(itf 0): rev.0,base=0xff400000,irq=10,mem=512kB (00-20-EA-00-07-56)
eni(itf 0): FPGA,MMF
</screen></informalexample>
</para>

<para>
If you've configured the ZN1221/ZN1225 driver, you will get something like:
<informalexample><screen>
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
</screen></informalexample>
Note that your board needs to be at least at revision level 3 if you want
to use it in a Triton-based system.
</para>

<para>
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 <command>atmtcp</command> command.
</para>

</sect2>

<sect2 id="Installation.Memory-Debugging">
<title>Memory Debugging</title>

<para>
If you want to enable debugging for options for memory allocations, you
need to install MPR before compiling the ATM tools.
</para>

<para>
If you chose to download the binary RPM package, you can install MPR like so:
<informalexample><screen>
rpm -ivh <replaceable>mpr-x.x-x.rpm</replaceable>
</screen></informalexample>
</para>

<para>
If you chose to download the source, extract
<filename>mpr-x.x.tar.gz</filename> like so:
<informalexample><screen>
tar xzvf <replaceable>mpr-x.x.tar.gz</replaceable>
</screen></informalexample>

Then do:
<informalexample><screen>
cd <replaceable>mpr-x.x</replaceable>
./configure x86-linux
make
make install
</screen></informalexample>
</para>

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

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

</sect2>

<sect2 id="Installation.ATM-Tools">
<title>ATM Tools</title>

<para>
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 selected by passing the appropriate options to
the <command>./configure</command> script in the linux-atm distribution.

<note><title>NOTE</title>
<para>
Issue <command>./configure --help</command> from the top-level directory of the
linux-atm distribution to view all possible options.
</para>
</note>
</para>

<para>
The ATM tools are built with the following commands:
<informalexample><screen>
cd <replaceable>linux-atm-x.x.x</replaceable>
./configure
make
make install
</screen></informalexample>

Unless otherwise specified when invoking <command>./configure</command>,
<command>make install</command> will install executables in the directory
<filename class=directory>/usr/local/bin</filename> and
<filename class=directory>/usr/local/sbin</filename>,
respectively.
Configuration files (except for <filename>hosts.atm</filename> which is
installed in <filename class=directory>/etc</filename>) are installed in
<filename class=directory>/usr/local/etc</filename>.
Libraries and header files are installed in
<filename class=directory>/usr/local/lib</filename> and
<filename class=directory>/usr/local/include</filename>,
respectively. Man pages are installed in
<filename class=directory>/usr/local/man</filename>.
</para>

</sect2>

<sect2 id="Installation.Extra-Packages">
<title>Extra Packages</title>

<para>
Some programs are based on large packages that are already distributed
outside of the ATM context. For some packages, patches are contained
in the ATM on Linux distribution.  They are contained in the
<filename class=directory>src/extra</filename> directory of the ATM on Linux
distribution.
</para>

<para>
Currently, the following extra packages are available:

<variablelist>
	<varlistentry><term><application><ulink url="http://www.tcpdump.org/">tcpdump</ulink></application></term>
		<listitem>
			<para>dumps network traffic (enhanced for ATM)</para>
		</listitem>
	</varlistentry>

	<varlistentry><term><application>ANS</application></term>
		<listitem>
			<para>ATM name server (based on <application>named</application> 4.9.5)</para>
		</listitem>
	</varlistentry>
</variablelist>
</para>

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

<para>
A script <application>hosts2ans.pl</application> to convert a 
<filename>/etc/hosts.atm</filename> file to
ANS zone files are provided in the
<filename class=directory>src/extra/ANS/</filename> directory.
Its use is described at the beginning of the file.
</para>

</sect2>

</sect1>


<sect1 id="Device-Setup">
<title>Device Setup</title>

<para>
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.
</para>

<sect2 id="Device-Setup.ATM-Over-TCP-Setup">
<title>ATM Over TCP Setup</title>

<para>
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).
</para>

<para>
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''):

<informalexample><screen>
# atmtcp virtual listen
</screen></informalexample>

Then, on the other system (``b''), run

<informalexample><screen>
# atmtcp virtual connect <replaceable>address_of_a</replaceable>
</screen></informalexample>
</para>

<para>
Both <command>atmtcp</command>s will report on their progress and the kernel
should display messages like:

<informalexample><screen>
Link 0: virtual interface 2
Link 1: incoming ATMTCP connection from 127.0.0.1
</screen></informalexample>

and

<informalexample><screen>
Link 0: virtual interface 3
Link 1: ATMTCP connection to localhost
</screen></informalexample>

on the two systems. Note that <command>atmtcp</command> keeps running and that interrupting
it breaks the virtual wire.
</para>

<para>
Multiple ``wires'' can be attached to the same machine by specifying a
port number (default is 2812). 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.
</para>

</sect2>

<sect2 id="Device-Setup.ZN1221-ZN1225-Tuning">
<title>ZN1221/ZN1225 Tuning</title>

<para>
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.
</para>

<para>
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 <application>zntune</application> program. Usage:

<cmdsynopsis>
	<command>zntune</command>
	<arg choice=Opt>-l <replaceable>low_water</replaceable></arg>
	<arg choice=Opt>-h <replaceable>high_water</replaceable></arg>
	<arg choice=Opt>-t <replaceable>threshold</replaceable></arg>
	<arg choice=plain><replaceable>itf</replaceable></arg>
	<arg choice=Opt><replaceable>pool</replaceable></arg>
</cmdsynopsis>

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.
</para>

<para>
The current settings and some usage statistics can be obtained by invoking
<command>zntune</command> without specifying new parameters:

<cmdsynopsis>
	<command>zntune</command>
	<arg choice=Opt>-z</arg>
	<arg choice=plain><replaceable>itf</replaceable></arg>
	<arg choice=Opt><replaceable>pool</replaceable></arg>
</cmdsynopsis>
</para>

<para>
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.
</para>

<para>
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.
</para>

<para>
Use the <parameter class=command>-z</parameter> option to reset the ``Alarm''
and ``Under'' counters.
</para>

</sect2>

<sect2 id="Device-Setup.Files-in-proc-net-atm">
<title>Files in <filename class=directory>/proc/net/atm/</filename></title>

<para>
Some status information about the ATM subsystem can be obtained through files
in <filename class=directory>/proc/net/atm/</filename>. 
The file <filename>/proc/net/atm/arp</filename> contains information
specific to Classical IP over ATM, see section
<link linkend="IP-Over-ATM.CLIP" endterm="IP-Over-ATM.CLIP.title"></link>.
</para>

<para>
All active ATM devices are listed in <filename>/proc/net/atm/devices</filename>.
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
<application>atmdiag</application>.
</para>

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

<para>
The files <filename>/proc/net/atm/pvc</filename> and 
<filename>/proc/net/atm/svc</filename> 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.
</para>

<para>
Furthermore, <filename>/proc/net/atm/vc</filename> shows buffer sizes and
additional internal information for all ATM sockets.
</para>

</sect2>

<sect2 id="Device-Setup.ATM-Diagnostics">
<title>ATM Diagnostics</title>

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

</sect2>

<sect2 id="Device-Setup.SONET-Diagnostics">
<title>SONET Diagnostics</title>

<para>
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.

<informalexample><screen>
% sonetdiag 0
</screen></informalexample>
</para>

<para>
The counters can be reset with the <parameter class=command>-z</parameter>
option:

<informalexample><screen>
# sonetdiag -z 0
</screen></informalexample>
</para>

<para>
The following network failures can be simulated:<footnote>
<para>
Some adapters may only support a subset of this.
</para>
</footnote>

<variablelist>
	<varlistentry><term><errorcode>sbip</errorcode></term>
		<listitem>
			<para>insert section errors (B1)</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>lbip</errorcode></term>
		<listitem>
			<para>insert line errors (B2)</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>pbip</errorcode></term>
		<listitem>
			<para>insert path errors (B3)</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>frame</errorcode></term>
		<listitem>
			<para>force (RX) frame loss</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>los</errorcode></term>
		<listitem>
			<para>insert loss of signal</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>lais</errorcode></term>
		<listitem>
			<para>insert line alarm indication signal</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>pais</errorcode></term>
		<listitem>
			<para>insert path alarm indication signal</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><errorcode>hcs</errorcode></term>
		<listitem>
			<para>insert header checksum errors</para>
		</listitem>
	</varlistentry>
</variablelist>
</para>

<para>
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.

<informalexample><screen>
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
</screen></informalexample>
</para>

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

</sect2>

</sect1>

<sect1 id="Native-ATM-PVCs">
<title>Native ATM PVCs</title>

<para>
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.
</para>

<sect2 id="Native-ATM-PVCs.Traffic-Tools">
<title>Traffic Tools</title>

<para>
<application>aread</application>/<application>awrite</application> and
<application>br</application>/<application>bw</application> are simple programs
to access the ATM API.  <application>awrite</application> sends the text string
passed as its second argument in an AAL5 PDU.  <application>aread</application>
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
<errorcode>errno</errorcode>.
</para>

<para>
<application>bw</application> 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.  <application>br</application> receives AAL5 PDUs and writes them
to standard output.
</para>

<para>
The first argument of <application>aread</application>,
<application>awrite</application>, <application>br</application> and
<application>bw</application> 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:

<informalexample><screen>
% awrite 1.0.42 hi
</screen></informalexample>
</para>

<para>
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. <interfacename>atm0</interfacename>
is interface 0, <interfacename>atm1</interfacename> is interface 1, etc. If the
system is equipped with a real
ATM adapter (e.g. not only <application>atmtcp</application>),
that adapter is normally at <interfacename>atm0</interfacename>.
</para>

<para>
<application>aping</application> 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.  <application>aping</application>
reports an error if no messages are received for too long.
<application>aping</application> is invoked by
specifying the PVC, like <application>aread</application>.
</para>

<para>
For "real" tests, you should use the modified version of
<application>ttcp</application> that
comes with this package. The original is available at
<ulink url="ftp://ftp.sgi.com/sgi/src/ttcp/">ftp://ftp.sgi.com/sgi/src/ttcp/</ulink>.
The following options have been added:


<variablelist>
	<varlistentry><term><parameter class=command>-a</parameter></term>
		<listitem>
<para>
use native ATM instead of UDP/TCP. The address must be in
the format
<parameter class=command>[<replaceable class=option>itf.</replaceable>]vpi.vci</parameter>
for PVCs, or a
valid ATM end system address for SVCs.
</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><parameter class=command>-P</parameter> <replaceable>num</replaceable></term>
		<listitem>
<para>use a CBR connection with a peak cell rate of
<replaceable>num</replaceable> cells per second. Default is to use UBR.
</para>
		</listitem>
	</varlistentry>
	<varlistentry><term><parameter class=command>-C</parameter></term>
		<listitem>
			<para>disable (UDP) checksums</para>
		</listitem>
	</varlistentry>
</variablelist>

Example:
<informalexample><screen>
%a ttcp_atm -r -a -s 0.90
%b ttcp_atm -t -a -s 0.90
</screen></informalexample>
</para>

</sect2>

<sect2 id="Native-ATM-PVCs.Direct-Cell-Access">
<title>Direct Cell Access</title>

<para>
On adapters where the device driver supports access to raw cells (``AAL0''),
individual cells can be composed and received with the
<application>atmdump</application> program.

Here is an example:
<informalexample><screen>
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 
</screen></informalexample>
</para>

</sect2>

</sect1>


<sect1 id="Signaling">
<title>Signaling</title>

<sect2 id="Signaling.ATM-Hosts-File">
<title>ATM Hosts File</title>

<para>
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 <filename>/etc/hosts.atm</filename>.
The structure of
this file is similar to the <filename>/etc/hosts</filename> file:

<informalexample><screen>
<replaceable>numeric_address</replaceable> <replaceable>name(s)</replaceable>
</screen></informalexample>

e.g.

<informalexample><screen>
47.0005.80FFE1000000F21A26D8.0020EA000EE0.00 pc2-a.fqdn pc2-a
47.0005.80FFE1000000F21A26D8.0020D4102A80.00 pc3-a.fqdn pc3-a
</screen></informalexample>
</para>

<para>
The numeric address can be specified in any of the formats described
in [<xref linkend="api">].
The numeric address(es) of a Linux system can be
determined with the command <command>atmaddr <option>-n</option></command>
(see also section
<link linkend="Signaling.Manual-Address-Configuration" endterm="Signaling.Manual-Address-Configuration.title"></link>).
</para>

<para>
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.
</para>

<para>
In addition to ATM addresses for SVCs, also PVC addresses can be stored in
<filename>/etc/hosts.atm</filename>.
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.
</para>

</sect2>

<sect2 id="Signaling.ANS">
<title>ANS</title>

<para>
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
<filename>/etc/resolv.conf</filename> file.
</para>

<para>
For performing reverse lookups of E.164 addresses, the list of telephony
country codes needs to be known. That list can be obtained from the
<ulink url="http://www.itu.org/">International Telecommunications Union</ulink>.
The
<ulink url="http://www.itu.int/itudoc/itu-t/ob-lists/icc/e164_717.html"><citetitle>List of ITU-T Recommendation E.164 Assigned Country Codes</citetitle></ulink>
is currently available in PDF and Word document formats.
<note>
<title>NOTE</title>
<para>
Should the URL become out of date, the document should easily be found by
searching for the document's title at the ITU web site.
</para>
</note>
</para>

<para>
The script
<command>src/lib/pdf2e164_cc.pl</command> in the atm-linux distribution can
be used to create the E.164 county codes table with the PDF version
of the country code list, e.g.

<informalexample><screen>
perl pdf2e164_cc.pl <replaceable>e164_xxx.pdf</replaceable> &gt;/etc/e164_cc
</screen></informalexample>

It should be noted that <application>pdftotext</application> needs to be
available in order to run the script above.  It can be obtained with
<ulink url="http://www.foolabs.com/xpdf/"><application>xpdf</application></ulink>.
</para>

</sect2>

<sect2 id="Signaling.Signaling-Demon">
<title>Signaling Demon</title>

<para>
Man pages:
<citerefentry><refentrytitle>atmsigd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry><refentrytitle>atmsigd.conf</refentrytitle><manvolnum>4</manvolnum></citerefentry>
</para>

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

<para>
By default, <application>atmsigd</application> is configured to conform to
dynamically configure the UNI version. It can be
compiled for UNI 3.0, 3.1, or 4.0 specifically by passing the
<parameter class=command>--with-uni=VERSION</parameter> to the
<command>./configure</command> script in the top-level directory of the
linux-atm source distribution.
</para>

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

<para>
<application>atmsigd</application> also looks for a configuration file at the
location specified
with the <parameter class=command>-c</parameter> option.
The default location is <filename>/usr/local/etc/atmsigd.conf</filename>.
</para>
</sect2>

<sect2 id="Signaling.ILMI-Demon">
<title>ILMI Demon</title>

<para>
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
<link linkend="Signaling.Manual-Address-Configuration" endterm="Signaling.Manual-Address-Configuration.title"></link>).
Note that the ILMI
demon should not be used on interfaces where addresses are manually
configured.
</para>

<para>
The ILMI demon is started as follows:

<cmdsynopsis>
	<command>ilmid</command>
	<arg choice=Opt>-b</arg>
	<arg choice=Opt>-d</arg>
	<arg choice=Opt>-i <replaceable>local_ip</replaceable></arg>
	<arg choice=Opt>-l <replaceable>log_file</replaceable></arg>
	<arg choice=Opt>-q <replaceable>qos</replaceable></arg>
	<arg choice=Opt>-u <replaceable>uni_version</replaceable></arg>
	<arg choice=Opt>-v</arg>
	<arg choice=Opt>-x</arg>
	<arg choice=Opt><replaceable>itf</replaceable></arg>
</cmdsynopsis>

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

</para>

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

<para>
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.
</para>
</sect2>

<sect2 id="Signaling.Manual-Address-Configuration">
<title id="Signaling.Manual-Address-Configuration.title">Manual Address Configuration</title>

<para>
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
<application>ilmid</application> doesn't interfere, then use the
<command>atmaddr</command> command to set
the address(es).
</para>

<para>
Man pages:
<citerefentry><refentrytitle>atmaddr</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

<para>
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:

<informalexample><screen>
conf nsap route new <replaceable>nsap_addr</replaceable> 152 <replaceable>port</replaceable> <replaceable>vpi</replaceable>
</screen></informalexample>

e.g.

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

<para>
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.
</para>

</sect2>

<sect2 id="Signaling.Running-Two-ATM-NICs-Back-to-Back">
<title id="Signaling.Back-to-Back.title">Running Two ATM NICs Back-to-Back</title>

<para>
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.
</para>

<para>
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:

<informalexample><screen>
RJ45                            RJ45
   1        ------------        7
   2        ------------        8

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

Pins 3, 4, 5, 6 unconnected.
</screen></informalexample>

A better way to illustrate this may be to show the proper color
schemes for the RJ45 connectors at each end of the back-to-back cable.
The first connector should use the following scheme:

<informalexample><screen>
RJ45-1
   1 - Brown
   2 - White/Brown
   3 - Unconnected
   4 - Unconnected
   5 - Unconnected
   6 - Unconnected
   7 - Orange
   8 - White/Orange
</screen></informalexample>

And the second connector should use this scheme:

<informalexample><screen>
RJ45-2
   1 - Orange
   2 - White/Orange
   3 - Unconnected
   4 - Unconnected
   5 - Unconnected
   6 - Unconnected
   7 - Brown
   8 - White/Brown
</screen></informalexample>

</para>

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

<para>
Here we have two machines called ``virgil'' and ``nestor''.
Substitute your own names as necessary.
</para>

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

<informalexample><screen>
atmsigd -b -m network
</screen></informalexample>

and on virgil with:

<informalexample><screen>
atmsigd -b
</screen></informalexample>
</para>

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

<informalexample><screen>
47.0005.80FFE1000000F21A26D8.0020EA000EE0.00    nestor-atm
47.0005.80FFE1000000F21A26D8.0020D4102A80.00    virgil-atm
</screen></informalexample>
</para>

<para>
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:

<informalexample><screen>
atmaddr -a virgil-atm
</screen></informalexample>

on virgil, and:

<informalexample><screen>
atmaddr -a nestor-atm
</screen></informalexample>

on nestor. Now start <application>atmarpd</application> on both machines
in the normal way. Now you (should) have a working ATM set-up. To get
IP over ATM working, just follow the instructions in
section <link linkend="IP-Over-ATM" endterm="IP-Over-ATM.title"></link>.
</para>

</sect2>

<sect2 id="Signaling.Q-2931-Message-Dumper">
<title>Q.2931 Message Dumper</title>

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

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

Example:

<informalexample><screen>
% 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"
</screen></informalexample>

</para>

</sect2>

</sect1>


<sect1 id="IP-Over-ATM">
<title id="IP-Over-ATM.title">IP Over ATM</title>

<para>
IP over ATM is supported with Classical IP over ATM (CLIP, defined in
RFC1577 [<xref linkend="RFC1577">], LAN Emulation (LANE, defined in
[<xref linkend="lanev1">] and [<xref linkend="lanev2">])
and Multi-Protocol Over ATM (MPOA, client only, defined in
[<xref linkend="mpoav1">]).
</para>

<sect2 id="IP-Over-ATM.CLIP">
<title id="IP-Over-ATM.CLIP.title">CLIP</title>

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

<para>
Man pages:
<citerefentry><refentrytitle>atmarpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>atmarp</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

<para>
<application>atmsigd</application> and <application>ilmid</application>
must already be running when <application>atmarpd</application> is
started. Use the <parameter class=command>-b</parameter>
option to make sure they're properly synchronized,
e.g.

<informalexample><screen>
#!/bin/sh
atmsigd -b
ilmid -b
atmarpd -b
...
</screen></informalexample>

works, but

<informalexample><screen>
#!/bin/sh
atmsigd &amp;
ilmid &amp;
atmarpd &amp;
...
</screen></informalexample>

frequently doesn't (yet).
</para>

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

<informalexample><screen>
# atmarp -c <replaceable>interface_name</replaceable>
# ifconfig atm0 <replaceable>local_address</replaceable> <replaceable>possibly_more_options</replaceable> up
</screen></informalexample>

e.g.

<informalexample><screen>
# atmarp -c atm0
# ifconfig atm0 10.0.0.3 up
</screen></informalexample>
</para>

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

<informalexample><screen>
# atmarp -s 10.0.0.4 0.0.70
</screen></informalexample>
</para>

<para>
NULL encapsulation is used if the <parameter class=command>null</parameter>
keyword is specified.
Note that ARP requires LLC/SNAP encapsulation. NULL encapsulation can
therefore only be used for PVCs.
</para>

<para>
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 <parameter class=command>arpsrv</parameter>
set, e.g.

<informalexample><screen>
# atmarp -s \
  10.0.0.0 47.0005.80.ffe100.0000.f215.1065.0020EA000756.00 \
  arpsrv
</screen></informalexample>
</para>

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

<para>
The kernel ATMARP table can be read via \path{/proc/net/atm/arp}. The table
used by <application>atmarpd</application>
is regularly printed on standard error if <application>atmarpd</application>
is started with the <parameter class=command>-d</parameter> option.
If <application>atmarpd</application> is invoked without
<parameter class=command>-d</parameter>, the table is written to the file
<filename>atmarpd.table</filename> in the dump
directory (by default <filename class=directory>/var/run</filename>; can be
changed with <parameter class=command>-D</parameter>), and
it can be read with <command>atmarp -a</command>.
</para>

</sect2>

<sect2 id="IP-Over-ATM.LAN-Emulation">
<title id="IP-Over-ATM.LAN-Emulation.title">LAN Emulation</title>

<para>
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 the <filename>src/lane/USAGE</filename> file in the linux-atm 
distribution.
</para>

<para>
Man pages:
<citerefentry><refentrytitle>bus</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>lecs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>les</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and
<citerefentry><refentrytitle>zeppelin</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

<para>
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.
</para>

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

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

<informalexample><screen>
# zeppelin <replaceable>possibly_more_options</replaceable> &amp;
# ifconfig lec0 <replaceable>local_address</replaceable> <replaceable>possibly_more_options</replaceable> up
</screen></informalexample>
</para>

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

<informalexample><screen>
# zeppelin &amp;
# 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 &amp;
# ifconfig lec2 10.1.2.42 netmask 255.255.255.0 \
                          broadcast 10.1.2.255 up
</screen></informalexample>
</para>

<para>
By default, <application>zeppelin</application> uses interface
<interface>lec0</interface>, 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
<citerefentry><refentrytitle>zeppelin</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>

<para>
<application>zeppelin</application> 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.
</para>

<para>
The state of the LANE ARP cache entries can be monitored through
<filename>/proc/net/atm/lec</filename>.
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.
</para>

<para>
The LANE service (
<citerefentry><refentrytitle>lecs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>les</refentrytitle><manvolnum>8</manvolnum></citerefentry>, and
<citerefentry><refentrytitle>bus</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
is
configured using configuration files. The configuration file syntax is
listed on the respective manual pages.
</para>

<para>
A more detailed description of Linux LANE services is discussed in
Marko Kiiskil&auml;'s Master's Thesis
[<xref linkend="kiis">].


</para>

</sect2>

<sect2 id="IP-Over-ATM.MPOA">
<title id="IP-Over-ATM.MPOA.title">MPOA</title>

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

<para>
Man page:
<citerefentry><refentrytitle>mpcd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
</para>

<para>
<application>atmsigd</application> and <application>ilmid</application>
must already be running when
<application>mpcd</application> is started.
Since MPOA detects IP layer flows from LANE
traffic, you need to have <application>zeppelin</application>
running before MPOA can
function. However, the order in which <application>zeppelin</application>
and <application>mpcd</application>
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
<application>mpcd</application>.
</para>

<para>
Below is the example from Section
<link linkend="IP-Over-ATM.LAN-Emulation" endterm="IP-Over-ATM.LAN-Emulation.title"></link>
which starts two LANE
clients. The configuration has been augmented with two MPOA clients
which the LANE clients will serve.

<informalexample><screen>
# zeppelin &amp;
# ifconfig lec0 10.1.1.42 netmask 255.255.255.0 \
                          broadcast 10.1.1.255 up
# mpcd -s mybox1 -l mybox2 &amp;
#
# zeppelin -i 2 -l mybox3 -n myelan -p &amp;
# ifconfig lec2 10.1.2.42 netmask 255.255.255.0 \
                          broadcast 10.1.2.255 up
# mpcd -i 2 -s mybox4 -l mybox5 &amp;
</screen></informalexample>
</para>

<para>
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.
<application>zeppelin</application> but must be
different among other <application>mpcd</application> demons. By default,
<application>mpcd</application> does
not retrieve configuration information from the LECS. The necessary
command line options and an example of using LECS are shown on the
<application>mpcd</application> manual page.
The manual page also lists the rest of the available options.
</para>

<para>
The contents of MPOA ingress and egress caches can be monitored
through the <filename>/proc/net/atm/mpc</filename> file.
</para>

<para>
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
<filename>/proc/net/atm/mpc</filename>.

<informalexample><screen>
# echo add 130.230.54.146 tx=80000,1600 rx=tx > /proc/net/atm/mpc
#             # generate enough traffic to trigger a shortcut
# cat /proc/net/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
...
</screen></informalexample>

The shortcut to IP address <parameter class=command>130.230.54.146</parameter>
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
<ulink url="ftp://sunsite.tut.fi/pub/Local/linux-atm/mpoa/">ftp://sunsite.tut.fi/pub/Local/linux-atm/mpoa/</ulink>
for the latest
patch.
</para>

</sect2>

</sect1>

<bibliography id="Bibliography">
<title id="Bibliography.title">Bibliography</title>

<bibliodiv>
<title>References</title>

<biblioentry id="api" xreflabel="api">
	<title>Linux ATM API</title>
	<author>
		<firstname>Werner</firstname>
		<surname>Almesberger</surname>
	</author>
	<releaseinfo>
    		<ulink url="http://linux-atm.sourceforge.net/API/">http://linux-atm.sourceforge.net/API/</ulink>
	</releaseinfo>
	<pubdate>July 1996</pubdate>
</biblioentry>

<biblioentry id="RFC1577" xreflabel="RFC1577">
	<title>Classical IP and ARP over ATM (RFC1577)</title>
	<author>
		<firstname>Mark</firstname>
		<surname>Laubach</surname>
	</author>
	<pubdate>January 1994</pubdate>
</biblioentry>

<biblioentry id="lanev1" xreflabel="lanev1">
	<title>LAN Emulation Over ATM -- Version 1.0</title>
	<corpauthor>ATM Forum</corpauthor>
	<pubdate>February 1996</pubdate>
</biblioentry>

<biblioentry id="lanev2" xreflabel="lanev2">
	<title>LAN Emulation Over ATM -- Version 2 -- LUNI Specification</title>
	<corpauthor>ATM Forum</corpauthor>
	<pubdate>July 1997</pubdate>
</biblioentry>

<biblioentry id="mpoav1" xreflabel="mpoav1">
	<title>Multi-Protocol Over ATM -- Version 1.0</title>
	<corpauthor>ATM Forum</corpauthor>
	<pubdate>July 1997</pubdate>
</biblioentry>

<biblioentry id="bridge-howto" xreflabel="bridge-howto">
	<title>Bridging mini-Howto</title>
	<author>
		<firstname>Christopher</firstname>
		<surname>Cole</surname>
	</author>
	<releaseinfo>
		<ulink url="http://www.linuxdoc.org/HOWTO/mini/Bridge.html">http://www.linuxdoc.org/HOWTO/mini/Bridge.html</ulink>
	</releaseinfo>
	<pubdate>March, 2001</pubdate>
</biblioentry>

<biblioentry id="kiis" xreflabel="kiis">
        <title>Implementation of LAN Emulation Over ATM in Linux</title>
	<author>
                <firstname>Marko</firstname>
                <surname>Kiiskil&auml;</surname>
        </author>
	<releaseinfo>
		<ulink url="ftp://sunsite.tut.fi/pub/Local/linux-atm/misc/">ftp://sunsite.tut.fi/pub/Local/linux-atm/misc/</ulink>
	</releaseinfo>
	<pubdate>October 1996</pubdate>
</biblioentry>

</bibliodiv>

</bibliography>

</article>