                    Linux DECnet Networking Layer Information
                   ===========================================

1) Other documentation....

   o Project Home Pages
       http://www.sucs.swan.ac.uk/~rohan/DECnet/index.html - Kernel info
       http://linux.dreamtime.org/decnet/                  - Userland tools

   o FTP sites
       ftp://ftp.sucs.swan.ac.uk/pub/Linux/DECnet/
                - Swansea University Computer Society DECnet Archive
                  (contains kernel patches and info)
                - Mirror of userland tools on ftp.dreamtime.org

        ftp://ftp.dreamtime.org/pub/linux/decnet/
                - Patrick Caulfield's archive of userland tools and
                  Eduardo Serrat's kernel patches

2) Configuring the kernel

Be sure to turn on the following options:

    CONFIG_DECNET (obviously)
    CONFIG_PROCFS (to see what's going on)
    CONFIG_SYSCTL (for easy configuration)

if you want to try out router support (not properly debugged and not
complete yet), you'll need the following options as well...

    CONFIG_DECNET_RAW (to receive routing packets)
    CONFIG_DECNET_ROUTER (to be able to add/delete routes)
    CONFIG_NETLINK (to allow rtnetlink)
    CONFIG_RTNETLINK (for communication with the kernel routing layer)

3) Command line options

The kernel command line takes options looking like the following:

    decnet=1,2,1

the first two numbers are the node address 1,2 = 1.2 (yes, you must use
commas when specifying them). The third number is the level number for routers
and is optional. It is probably a good idea to set the DECnet address on boot
like this rather than trying to do it later.

There are also equivalent options for modules. The node address and type can
also be set through the /proc/sys/net/decnet/ files, as can other system
parameters.

Currently the only supported device is ethernet. You'll have to set the
ethernet address of your ethernet card according to the DECnet address
of the node in order for it to be recognised (and thus appear in
/proc/net/decnet_dev). There is a utility available at the above
FTP sites called dn2ethaddr which can compute the correct ethernet
address to use. The address can be set by ifconfig either before at
at the time the device is brought up. If you are using RedHat you can
add the line:

    MACADDR=AA:00:04:00:03:04

or something similar, to /etc/sysconfig/network-scripts/ifcfg-eth0 or
wherever your network card's configuration lives.

You will also need to set /proc/sys/net/decnet/default_device to the
device you want DECnet to route packets out of when no specific route
is available. Usually this will be eth0, for example:

    echo -n "eth0" >/proc/sys/net/decnet/default_device

There is a list of what the other files under /proc/sys/net/decnet/ do
on the kernel patch web site (shown above).

4) How can I tell if its working ?

Here is a quick guide of what to look for in order to know if your DECnet
kernel subsystem is working.

   - Is the node address set (see /proc/sys/net/decnet/node_address)
   - Is the node of the correct type (see /proc/sys/net/decnet/node_type)
   - Is the Ethernet MAC address of each Ethernet card set to match
     the DECnet address. If in doubt use the dn2ethaddr utility available
     at the ftp archive.
   - If the previous two steps are satisfied, and the Ethernet card is up,
     you should find that it is listed in /proc/net/decnet_dev and also
     that it appears as a directory in /proc/sys/net/decnet/conf/. The
     loopback device (lo) should also appear and is required to communicate
     within a node.
   - If you have any DECnet routers on your network, they should appear
     in /proc/net/decnet_neigh, otherwise this file will only contain the
     entry for the node itself (if it doesn't check to see if lo is up).
   - If you want to send to any node which is not listed in the
     /proc/net/decnet_neigh file, you'll need to set the default device
     to point to an Ethernet card with connection to a router. This is
     again done with the /proc/sys/net/decnet/default_device file.
   - Try starting a simple server and client, like the dnping/dnmirror
     over the loopback interface. With luck they should communicate.
     For this step and those after, you'll need the DECnet library
     which can be obtained from the above ftp sites as well as the
     actual utilities themselves.
   - If this seems to work, then try talking to a node on your local
     network, and see if you can obtain the same results.
   - At this point you are on your own... :-)

5) How to send a bug report

If you've found a bug and want to report it, then there are several things
you can do to help me work out exactly what it is that is wrong. Useful
information (a lot of which is essential) includes:

 - What kernel version are you running ?
 - What version of the patch are you running ?
 - How far though the above set of tests can you get ?
 - What is in the /proc/decnet* files and /proc/sys/net/decnet/* files ?
 - Which services are you running ?
 - Which client caused the problem ?
 - How much data was being transfered ?
 - Was the network congested ?
 - If there was a kernel panic, please run the output through ksymoops
   before sending it to me, otherwise its _useless_.
 - How can the problem be reproduced ?
 - Can you use tcpdump to get a trace ? (N.B. Most (all?) versions of 
   tcpdump don't understand how to dump DECnet properly, so including
   the hex listing of the packet contents is essential, usually the -x flag.
   You may also need to increase the length grabbed with the -s flag)

6) Mailing list

If you are keen to get involved in development, or want to ask questions
about configuration, or even just report bugs, then there is a mailing
list that you can join: send mail to majordomo@dreamtime.org with

subscribe linux-decnet

as the body of the message.

7) Legal Info

The Linux DECnet project team have placed their code under the GPL. The
software is provided "as is" and without warranty express or implied.
DECnet is a trademark of Compaq. This software is not a product of
Compaq. We acknowledge the help of people at Compaq in providing extra
documentation above and beyond what was previously publicly available.

Steve Whitehouse <SteveW@ACM.org>

