Documentation/networking/decnet.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================================
   4 Linux DECnet Networking Layer Information
   5 =========================================
   6
   7 1. Other documentation....
   8 ==========================
   9
  10    - Project Home Pages
  11      - http://www.chygwyn.com/                             - Kernel info
  12      - http://linux-decnet.sourceforge.net/                - Userland tools
  13      - http://www.sourceforge.net/projects/linux-decnet/   - Status page
  14
  15 2. Configuring the kernel
  16 =========================
  17
  18 Be sure to turn on the following options:
  19
  20     - CONFIG_DECNET (obviously)
  21     - CONFIG_PROC_FS (to see what's going on)
  22     - CONFIG_SYSCTL (for easy configuration)
  23
  24 if you want to try out router support (not properly debugged yet)
  25 you'll need the following options as well...
  26
  27     - CONFIG_DECNET_ROUTER (to be able to add/delete routes)
  28     - CONFIG_NETFILTER (will be required for the DECnet routing daemon)
  29
  30 Don't turn on SIOCGIFCONF support for DECnet unless you are really sure
  31 that you need it, in general you won't and it can cause ifconfig to
  32 malfunction.
  33
  34 Run time configuration has changed slightly from the 2.4 system. If you
  35 want to configure an endnode, then the simplified procedure is as follows:
  36
  37  - Set the MAC address on your ethernet card before starting _any_ other
  38    network protocols.
  39
  40 As soon as your network card is brought into the UP state, DECnet should
  41 start working. If you need something more complicated or are unsure how
  42 to set the MAC address, see the next section. Also all configurations which
  43 worked with 2.4 will work under 2.5 with no change.
  44
  45 3. Command line options
  46 =======================
  47
  48 You can set a DECnet address on the kernel command line for compatibility
  49 with the 2.4 configuration procedure, but in general it's not needed any more.
  50 If you do st a DECnet address on the command line, it has only one purpose
  51 which is that its added to the addresses on the loopback device.
  52
  53 With 2.4 kernels, DECnet would only recognise addresses as local if they
  54 were added to the loopback device. In 2.5, any local interface address
  55 can be used to loop back to the local machine. Of course this does not
  56 prevent you adding further addresses to the loopback device if you
  57 want to.
  58
  59 N.B. Since the address list of an interface determines the addresses for
  60 which "hello" messages are sent, if you don't set an address on the loopback
  61 interface then you won't see any entries in /proc/net/neigh for the local
  62 host until such time as you start a connection. This doesn't affect the
  63 operation of the local communications in any other way though.
  64
  65 The kernel command line takes options looking like the following::
  66
  67     decnet.addr=1,2
  68
  69 the two numbers are the node address 1,2 = 1.2 For 2.2.xx kernels
  70 and early 2.3.xx kernels, you must use a comma when specifying the
  71 DECnet address like this. For more recent 2.3.xx kernels, you may
  72 use almost any character except space, although a `.` would be the most
  73 obvious choice :-)
  74
  75 There used to be a third number specifying the node type. This option
  76 has gone away in favour of a per interface node type. This is now set
  77 using /proc/sys/net/decnet/conf/<dev>/forwarding. This file can be
  78 set with a single digit, 0=EndNode, 1=L1 Router and  2=L2 Router.
  79
  80 There are also equivalent options for modules. The node address can
  81 also be set through the /proc/sys/net/decnet/ files, as can other system
  82 parameters.
  83
  84 Currently the only supported devices are ethernet and ip_gre. The
  85 ethernet address of your ethernet card has to be set according to the DECnet
  86 address of the node in order for it to be autoconfigured (and then appear in
  87 /proc/net/decnet_dev). There is a utility available at the above
  88 FTP sites called dn2ethaddr which can compute the correct ethernet
  89 address to use. The address can be set by ifconfig either before or
  90 at the time the device is brought up. If you are using RedHat you can
  91 add the line::
  92
  93     MACADDR=AA:00:04:00:03:04
  94
  95 or something similar, to /etc/sysconfig/network-scripts/ifcfg-eth0 or
  96 wherever your network card's configuration lives. Setting the MAC address
  97 of your ethernet card to an address starting with "hi-ord" will cause a
  98 DECnet address which matches to be added to the interface (which you can
  99 verify with iproute2).
 100
 101 The default device for routing can be set through the /proc filesystem
 102 by setting /proc/sys/net/decnet/default_device to the
 103 device you want DECnet to route packets out of when no specific route
 104 is available. Usually this will be eth0, for example::
 105
 106     echo -n "eth0" >/proc/sys/net/decnet/default_device
 107
 108 If you don't set the default device, then it will default to the first
 109 ethernet card which has been autoconfigured as described above. You can
 110 confirm that by looking in the default_device file of course.
 111
 112 There is a list of what the other files under /proc/sys/net/decnet/ do
 113 on the kernel patch web site (shown above).
 114
 115 4. Run time kernel configuration
 116 ================================
 117
 118
 119 This is either done through the sysctl/proc interface (see the kernel web
 120 pages for details on what the various options do) or through the iproute2
 121 package in the same way as IPv4/6 configuration is performed.
 122
 123 Documentation for iproute2 is included with the package, although there is
 124 as yet no specific section on DECnet, most of the features apply to both
 125 IP and DECnet, albeit with DECnet addresses instead of IP addresses and
 126 a reduced functionality.
 127
 128 If you want to configure a DECnet router you'll need the iproute2 package
 129 since its the _only_ way to add and delete routes currently. Eventually
 130 there will be a routing daemon to send and receive routing messages for
 131 each interface and update the kernel routing tables accordingly. The
 132 routing daemon will use netfilter to listen to routing packets, and
 133 rtnetlink to update the kernels routing tables.
 134
 135 The DECnet raw socket layer has been removed since it was there purely
 136 for use by the routing daemon which will now use netfilter (a much cleaner
 137 and more generic solution) instead.
 138
 139 5. How can I tell if its working?
 140 =================================
 141
 142 Here is a quick guide of what to look for in order to know if your DECnet
 143 kernel subsystem is working.
 144
 145    - Is the node address set (see /proc/sys/net/decnet/node_address)
 146    - Is the node of the correct type
 147      (see /proc/sys/net/decnet/conf/<dev>/forwarding)
 148    - Is the Ethernet MAC address of each Ethernet card set to match
 149      the DECnet address. If in doubt use the dn2ethaddr utility available
 150      at the ftp archive.
 151    - If the previous two steps are satisfied, and the Ethernet card is up,
 152      you should find that it is listed in /proc/net/decnet_dev and also
 153      that it appears as a directory in /proc/sys/net/decnet/conf/. The
 154      loopback device (lo) should also appear and is required to communicate
 155      within a node.
 156    - If you have any DECnet routers on your network, they should appear
 157      in /proc/net/decnet_neigh, otherwise this file will only contain the
 158      entry for the node itself (if it doesn't check to see if lo is up).
 159    - If you want to send to any node which is not listed in the
 160      /proc/net/decnet_neigh file, you'll need to set the default device
 161      to point to an Ethernet card with connection to a router. This is
 162      again done with the /proc/sys/net/decnet/default_device file.
 163    - Try starting a simple server and client, like the dnping/dnmirror
 164      over the loopback interface. With luck they should communicate.
 165      For this step and those after, you'll need the DECnet library
 166      which can be obtained from the above ftp sites as well as the
 167      actual utilities themselves.
 168    - If this seems to work, then try talking to a node on your local
 169      network, and see if you can obtain the same results.
 170    - At this point you are on your own... :-)
 171
 172 6. How to send a bug report
 173 ===========================
 174
 175 If you've found a bug and want to report it, then there are several things
 176 you can do to help me work out exactly what it is that is wrong. Useful
 177 information (_most_ of which _is_ _essential_) includes:
 178
 179  - What kernel version are you running ?
 180  - What version of the patch are you running ?
 181  - How far though the above set of tests can you get ?
 182  - What is in the /proc/decnet* files and /proc/sys/net/decnet/* files ?
 183  - Which services are you running ?
 184  - Which client caused the problem ?
 185  - How much data was being transferred ?
 186  - Was the network congested ?
 187  - How can the problem be reproduced ?
 188  - Can you use tcpdump to get a trace ? (N.B. Most (all?) versions of
 189    tcpdump don't understand how to dump DECnet properly, so including
 190    the hex listing of the packet contents is _essential_, usually the -x flag.
 191    You may also need to increase the length grabbed with the -s flag. The
 192    -e flag also provides very useful information (ethernet MAC addresses))
 193
 194 7. MAC FAQ
 195 ==========
 196
 197 A quick FAQ on ethernet MAC addresses to explain how Linux and DECnet
 198 interact and how to get the best performance from your hardware.
 199
 200 Ethernet cards are designed to normally only pass received network frames
 201 to a host computer when they are addressed to it, or to the broadcast address.
 202
 203 Linux has an interface which allows the setting of extra addresses for
 204 an ethernet card to listen to. If the ethernet card supports it, the
 205 filtering operation will be done in hardware, if not the extra unwanted packets
 206 received will be discarded by the host computer. In the latter case,
 207 significant processor time and bus bandwidth can be used up on a busy
 208 network (see the NAPI documentation for a longer explanation of these
 209 effects).
 210
 211 DECnet makes use of this interface to allow running DECnet on an ethernet
 212 card which has already been configured using TCP/IP (presumably using the
 213 built in MAC address of the card, as usual) and/or to allow multiple DECnet
 214 addresses on each physical interface. If you do this, be aware that if your
 215 ethernet card doesn't support perfect hashing in its MAC address filter
 216 then your computer will be doing more work than required. Some cards
 217 will simply set themselves into promiscuous mode in order to receive
 218 packets from the DECnet specified addresses. So if you have one of these
 219 cards its better to set the MAC address of the card as described above
 220 to gain the best efficiency. Better still is to use a card which supports
 221 NAPI as well.
 222
 223
 224 8. Mailing list
 225 ===============
 226
 227 If you are keen to get involved in development, or want to ask questions
 228 about configuration, or even just report bugs, then there is a mailing
 229 list that you can join, details are at:
 230
 231 http://sourceforge.net/mail/?group_id=4993
 232
 233 9. Legal Info
 234 =============
 235
 236 The Linux DECnet project team have placed their code under the GPL. The
 237 software is provided "as is" and without warranty express or implied.
 238 DECnet is a trademark of Compaq. This software is not a product of
 239 Compaq. We acknowledge the help of people at Compaq in providing extra
 240 documentation above and beyond what was previously publicly available.
 241
 242 Steve Whitehouse <SteveW@ACM.org>
 243