README.DECnet

Note: This document describes the installation of DECnet support on Linux.
Currently it supports releases derived from Debian and Fedora. Note that only
a (very) limited number of distributions have been tested.

The kit may be obtained by:

    git clone https://github.com/JohnForecast/LinuxDECnet

This release is a continuation of the Raspbian DECnet kit available at:

    git clone https://github.com/JohnForecast/RaspbianDECnet

Kernel 6.0.x was the last release which included source code for a DECnet
implementation. The RaspbianDECnet kit relied on the availability of this
kernel code so could not be installed on kernel 6.1.x or later.


Distributions tested:

Minimum kernel supported:       4.18.0
Maximum kernel supported:       6.12.34

Tested distributions:

Debian 10, kernel 4.19.0 on x86_64 (ESXi 6.7u3 VM)
Debian 11, kernel 5.10.0 on x86_64 (ESXi 6.7u3 VM)
RaspiOS 2023-02-21, kernel 6.0.19 on aarch64 (Raspberry Pi 3)
RaspiOS 2023-05-03, kernel 6.1.21 on aarch64 (Raspberry Pi 4B 8GB)
Debian 12, kernel 6.1.0 on x86_64 (ESXi 6.7u3 VM)
Fedora 38, kernel 6.4.15 on x86_64 (ESXi 6.7u3 VM)
Fedora 38, kernel 6.2.9 on aarch64 (Raspberry Pi 4B, 8GB)
Fedora 38, kernel 6.5.5 on x86_64 (ESXi 6.7u3 VM)
Rocky Linux 9, kernel 5.14.0 on x86_64 (ESXi 6.7u3 VM) [with backport]
AlmaLinux 8.8, kernel 4.18.0 on x86_64 (ESXi 6.7u3)
Ubuntu 18.0.4, kernel 5.4.0 on x86_64 (ESXi 6.7u3)
RaspiOS 2023-10-10, kernel 6.1.0 on aarch64 (Raspberry Pi 4B 8GB)
Ubuntu 23.10, kernel 6.5.0 on x86_64 (ESXi 6.7u3 VM)
Dietpi 8.22.3, kernel 6.1.21 on arm7l (Raspberry Pi Zero 2 W)
RaspiOS 2024-03-12, kernel 6.6.20 on aarch64 (Raspberry Pi 5 8GB)
RaspiOS 2024-11-19, kernel 6.6.62 on aarch64 (Raspberry Pi 5 8GB)
RaspiOS 2025-05-13, kernel 6.12.34 on aarch64 (Raspberry Pi 5 8GB)
RaspiOS 2025-12-04, kernel 6.12.47 on aarch64 (Raspberry Pi 4 1GB)

Changes from RaspbianDECnet:

  - Designed to be built as an external module

        Simplifies and speeds up the installation procedure. We no longer
        need to rebuild the kernel as part of the installation. For a low
        end system like the Raspberry Pi this really speeds up the
        installation.

  - Can only be built as an ethernet endnode

        This substantially simplifies the kernel code. The routing code
        in RaspbianDECnet was never supported.

  - Minimize use of Linux kernel frameworks

        Most of the problems with keeping RaspbianDECnet running between Linux
        versions were changes to the kernel framework APIs. RaspbianDECnet
        used the Destination Cache, Neighbour structures, flow idn
        infrastructure and the routing infrastructure. LinuxDECnet does not
        use any of these frameworks.

NOTE:

    Both RaspianDECnet and LinuxDECnet contain 2 implementations of the CTERM protocol;
    dnlogin is the primary implementation and sethost contains a different implementation.
    I will no longer fix bugs in the sethost CTERM implementation. sethost may still be
    used for connecting to RSTS and TOPS-20 via their private protocols (the RSX private
    protocol is not implemented) but dnlogin should be the preferred mechanism for CTERM.
    

Installation:

In order to bring up DECnet on Linux you will need to compile and install an
external module implementing the core DECnet protocols along with all the
userland applications.

NOTE: Make sure that the currently running kernel has an associated kernel
      development package (kernel-headers on debian, raspberrypi-kernel-headers
      on Raspbian and RaspiOS and kernel-devel on fedora) available for
      installation otherwise the script below will fail.

The build and installation can be automated by downloading the
BuildAndInstall.sh script, making it executable and running it inside a
newly created work directory. You must be running as root to execute this
script.

By default, BuildAndInstall.sh will download, build and install a decnet
kernel module (decnet3.ko) and DECnet utilities tailored for the system it is
running on. If you try to run BuildAndInstall.sh a second time, it will notice
that an existing build is already present and offer to clean and rebuild the
software or re-install the existing binaries.

BuildAndInstall.sh will detect if the system uses systemd and offer to install
scripts to change the MAC address of the ethernet/wi-fi adapter and start
DECnet on boot.


Command Line Overrides:

Several overrides may be used to control the operation of BuildAndInstall.sh.
These overrides would be placed on the command line prior to invoking
BuildAndInstall.sh:

        OVERRIDES ./BuildAndInstall.sh

or

        sudo OVERRIDES ./BuildAndInstall.sh

    1. If your system uses a kernel which was installed outside of the package
       manager mechanism, you must load the linux headers for this kernel
       using this same mechanism and include "HAVE_HEADERS=1" as an override.

    2. If, for any reason, you need BuildAndInstall.sh to avoid installing
       packages you can install the packages manually and include
       "HAVE_PACKAGES=1" as an override.


Notes:

    1. Library locations

        The location of 64-bit static and dynamic libraries seems to be left
        to the individual distributions:

        In order to have a single installation, "/sbin/ldconfig -p" will
        be issued to obtain the entries in the ld.so cache. If any entries
        are in /lib64 then we will use that directory otherwise we will use
        /lib. 32-bit systems will continue to use /lib.


    2. Upgrading from RaspianDECnet to LinuxDECnet

        Dues to the above change it is possible that, after installing
        LinuxDECnet, libraries will exist in both /lib and /lib64. It is
        unclear what the priority order would be so I would suggest deleting
        the following libraries from /lib:

                /lib/libdnet.a
                /lib/libdnet_daemon.so
                /lib/libdnet_daemon.so.2
                /lib/libdnet_daemon.so.2.43.1
                /lib/libdnet-dap.a
                /lib/libdnet-dap.so
                /lib/libdnet-dap.so.2
                /lib/libdnet-dap.so.46.0
                /lib/libdnet.so
                /lib/libdnet.so.2
                /lib/libdnet.so.2.43.2
                /lib/librms.a
                /lib/librms.so
                /lib/librms/so.2
                /lib/librms/so.2.43.0
                /lib/libvaxdata.a

        You may also want to delete the kernel module:

                /lib/modules/`uname -a`/kernel/net/decnet/decnet.ko
        or      /lib/modules/`uname -a`/kernel/net/decnet/decnet.ko.xz

        and remove your startup scripts or convert them to use the new kernel
        modulee which is located at:

                /lib/modules/`uname -a`/extra/decnet3.ko.xz


    3. SELinux

        DECnet does not operate correctly if SELinux is in the enforcing mode
        (dnetd will not be able to access sockets and incoming connections
        will fail). DECnet will operate correctly if SELinux is in permissive
        mode or disabled. If someone comes up with a suitable policy
        configuration to allow DECnet to run with SELinux in the enforcing
        mode, I would be open to including it in the installation procedure
        but, given the lack of modern security features (e.g. encryption)
        it is not clear to me that it is a worthwhile effort.

        If the decnet3 module is loaded but dnetd is not running this is
        likely the problem. Use "sestatus" to determine the current status
        of SELinux.


    4. Secure Boot

        If your system uses or requires Secure Boot, it must be disabled
        otherwise loading the DECnet kernel module will be rejected. For
        example, Rocky Linux 9 does this when run from ESXi 6.7.

        If the decnet3 module does not load and dnetd complains about files
        in /proc/net being missing this is likely the problem. The solution
        is machine (EFI) dependent.


    5. Backports

        Some distributions backport code from newer kernels to their
        currently supported kernel. In most cases this does not affect the
        DECnet code but sometimes it does and it requires source code
        changes to fix. I will keep a list here of those backports which
        can be supported with simple code changes:

        1. Rocky Linux 9 (backport of per-cpu network memory allocation)

            In LinuxDECnet/kernel/dnet.c there are 2 references to
            'decnet_memory_per_cpu_fw_alloc' which are conditionalized on
            kernel version 6.0.0 or above. Change these conditionals to
            kernel version 5.14.0 (or whatever you are running) and
            re-install using the "Clean and rebuild using existing tree"
            option.


Kernel module versions

    The current version can be obtained from:

        cat /proc/net/decnet_revision

    The kernel module version number is updated when the DECnet kernel module
    has been changed:

    3.0.0       Original release

    3.0.1       /proc/net/decnet_neigh includes the next hop MAC address

    3.0.2       Kernel hang fixed when scanning the node database for an
                entry needing deletions.

    3.0.3       Fixed hang seen on Raspberry Pi Bookworm reboot requests.

    3.0.4       Verify the destination address of unicast messages is the
                node address of this node.

    3.0.5       Fix bugs found when trying to transfer large files to VMS

    3.0.6       More bugs found when transferring large files to VMS

    3.0.7       Fix data corruption bug when receiving segmented packets

    3.0.8       Fix inbound handling of data packets with the intra-ethernet
                bit set

    3.0.9       Fix handling of inbound link service messages when the
                remote system uses segment or message flow control

    3.0.10      Remove timeout check when trying to allocate a node entry

    3.0.11      Fix cross-channel ack handling. If an interrupt/link service
                message was received and the only ack present was a cross-
                channel one (for the data channel), the ack would be applied
                to the interrupt/link service channel.

    3.0.12      Fix kernel memory allocations which could result in a
                system hang. Fix initial allocation of the loopback nexthop
                cache entry so that we get a clean result from running the
                lock dependency checker. Switch to using trylocks in timer
                callbacks. Allow the DECnet module to be built if the kernel
                does not include support for 802.11.

    3.0.13      Second pass at fixing kernel locking and memory allocation
                problems.

    3.0.14      Reduce timer interval from 500 mSec to 200 mSec. Require RTT
                estimate to be at least 1 timer tick. Remove pad byte from
                all transmitted long routing headers. Respond correctly to
                incoming messages which do not map to a valid socket.
                Reduce initial round-trip estimate to 3 seconds (from 5).

    3.0.15      The logic for decrementing the flow control count for message
                and segment flow control was inverted (this code came from
                the orginal DECnet on Linux from the late '90's). If NSP data
                messsages fit into a single data link packet (like most cases
                for DEC protocols) everything would work correctly. Larger
                messages would eventually result in a hung logical link or
                data overrun issues.

    3.0.16      Correctly compute the remote segment size based on the
                SEGSIZE parameter in the connect initiate message rather
                than assuming that if the remote system is on the same
                ethernet that it will use maximum size packet.

    3.0.17      Stop matching incoming packets against links in the CN state
                which is entered when we receive a DC(NO_LINK) message. This
                means that we will correctly send back our own DC(NO_LINK)
                response when we receive any further traffic on the link
                rather than just drop traffic which causes the link to
                remain active.

    3.0.18      Fix parsing of incoming link service messages so that
                SEND/DONT_SEND are processed when the remote system uses
                message or segment flow control.

    3.0.19	Fix macro and routine names which changed in kernel
		6.15.0 and 6.16.0.

    3.0.20	Validate object name length when connecting.

    3.0.21	Filter out incoming packets addressed to the "All Routers"
		multicast address. These can be received when the ethernet
		device is running in promiscuous mode such as when used as
		part of a bridge or running tcpdump or smilar tools.

    3.0.22	Slightly improve the performance of 3.0.21 by only allowing
		routing control messages which are addressed to the
		"All Endnodes" multicast address, rather than filtering
		out the "All Routers" address for all message types.

    3.0.23	Fix off-by-1 error when checking if the retransmit count
		has been exceeded. Fix the "tryhard" implementation to
		manipulate the next hop address according to the routing
		spec. Add the missing calls to "tryhard" when transmitting
		data and interrupt/link service messages.

    3.0.24	Simplify the next-hop cache so there can only be a single
		entry for each node address.

    3.0.25	Minor code optimization for checking when to use "tryhard"
		on transmit calls.

    3.0.26	Convert the garbage collection routines for node and
		next hop caches to use a work queue ratrher than run
		directly from the timer callback.

    3.0.27	Make sure that a connection exits the DiscNotify state
		when all message transmissions are finished.

    3.0.28	Miscellaneous fixes for computing nexthop block size.

    3.0.29	Fixed a locking problem introduced by 3.0.26

    3.0.30	Make sure that an inbound socket buffer is linear before
		trying to trim() it.

    3.0.31	Support talking to NSP 3.2 hosts (Phase III).

    3.0.32	Fix dn_bind()/dn_connect() due to a parameter type
		change in kernel 6.19.


Changes from previous Linux DECnet release:


    3/19/26

    Update "ncp" to allow it to communicate with Phase III hosts (NICE
    version 2).

    Update user code revision to 3.20


    3/12/26

    Update README.Bridging to fix a race condition where DECnetMAC.service
    may run before the bridge was active. If this happens, decnet3.service
    will fail because it does not see a valid DECnet MAC address.\


    2/17/26

    Add support to "ncp" to display remote event logging information.

    Update user code version to 3.19


    7/30/25

    "sethost" used the "termio" interface for accessing terminals. Change
    it to use the "termios" interface which is almost compatible; needed
    changes to put the terminal in "raw" mode.

    Update user code version to 3.18


    7/30/25

    Change type "bool" to "bool_t" in dnet_daemon.c since "bool" is now a
    reserved keywoprd in C23.

    Update user code version to 3.17


    7/26/25

    Fix computation of the remote segment size.


    7/22/25

    Fix segment and message flow control issues - see 3.0.15 description
    above.


    7/21/25

    Increase the number of buffer in fal from 8 to 32. This allows more
    larger buffers to be sent on the network, improving network performance.

    Update user code version to 3.16


    7/21/25

    Miscellaneous fixes - see 3.0.14 description above.


    4/8/25

    More fixes for kernel locking and memory allocation problems.


    4/6/25

    Various fixes for kernel memory allocation problems.


    4/2/25

    Fix "ordering cycle" error from systemd if kdump is enabled.


    3/7/25

    Fix compiler warning in dneigh.c about trying to read 1024 bytes into
    a 128 byte buffer.

    Update user code version to 3.15


    02/19/25

    ctermd changes:
        1. No longer claim to be a VMS system. Uses the next value after
           "Unix-dni" (193).

        2. No longer set up ^Y as an interrupt character just like ^C.

    Update user code version to 3.14


    02/18/25

    There was an incorrect length field in message enabling escape
    recognition. Most client seem to ignore this error but "set host"
    on RSX-11M+ disconnected the logical link.

    Update user code version to 3.13


    10/22/24

    Second pass at support for kernel version 6.10 and later.


    10/14/24

    Changes to allow ther DECnet kernel module to be built for kernel
    version 6.11 and later.


    7/17/24

    Rename the "node" command to "dnnode" to avoid a conflict with a
    file in the node.js package.

    Update user code version to 3.12


    7/10/24

    Increase the fal buffer size to the maximum allowed (65535).

    Update user code version to 3.11


    7/9/24

    Add support for Stream_LF format files in fal. In order to make this
    work fal must claim to support DAP 7.x.x. This support is mostly
    reverse engineered since no known copy of the DAP 7.x.x spec exists.

    Update user code version to 3.10


    7/9/24

    Fix bug in fal which failed to return a creation Date/Time descriptor
    when creating a new file and the client requested it. Not all clients
    make that request.

    Update user code version to 3.9


    6/27/24

    Enable dapfs after fixing multiple build issues

    Update user code version to 3.8


    6/4/24

    Update the ncp manpage to include loop commands.


    5/31/24

    Permanently disable building dapfs. It has not been tested or even
    built for the last 5 years.


    5/29/24

    Fix the "LOOP NODE" command so that if the target node is specified
    by name, pass the name in the NICE request so that the executor can
    perform the name ==> address mapping.

    Update user code version to 3.7


    5/28/24

    Add support for "loop" command to both NCP and DNETNML. NCP supports
    "LOOP NODE", "LOOP CIRCUIT" and "LOOP LINE" so these function can be
    used in commands issued to remote systems (e.g. VMS, RSX etc) while
    DNETNML only supports "LOOP LINE".

    Update user code version to 3.6


    5/8/24

    Add line cost to the circuit characteristics response from dnetnml. It is
    currently hard-wired to 3 but it would be easy to make it settable if
    required.

    Update user code version to 3.5


    5/4/24

    Change default setting for the MIRROR object to not require
    user authentication.


    5/3/24

    Remove timeout check when allocating a node entry


    5/2/24

    Fix handling of inbound link service messages when the remote system
    uses segment or message flow control. The result was that all such
    messages were discarded and the logical link would hang. The most common
    case would be communicating with RSX systems.


    4/12/24

    Fix handling of data packets with the intra-ethernet bit set in the route
    header. The result of this was inbound connections would always use the
    designated router for all outbound messages resulting in very low
    performance.


    4/11/24

    dnlogin changes:
        1. Change OS type in the BindAccept response so that it no longer
           claims to be VMS. Use a unique value after "Unix-dni".

        2. Fix Start-Read with the "formatting" flag set so that it no longer
           causes input lines to be overwritten.

    Update user code version to 3.4.


    4/10/24

    Fix dnlogin so that character echoing obeys the current setting of the
    NORMAL-ECHO characteristics (fixes double echoing of characters). Update
    user code version to 3.3.


    12/30/23

    Fix message reassembly bug which would lead to data corruption


    12/28/23

    More bug fixes for ack handling and message retransmission


    12/21/23

    Let retransmitted messages participate in computing the round trip delay.


    12/20/23

    Clean up data message retransmission logic.

    Don't use data message with delayed ACKs in computing round trip time.

    Clean up processing of inbound linkservice messages (previously they
    were simply discarded).


    12/16/23

    This code and PyDECnet chose the same OS type code for DAP (192). Change
    this code to use 193 to make sure there is no possible conflict. Update
    user code version to 3.2.


    12/11/23

    Check the destination address of unicast messages.


    12/10/23

    Add document about using bridging with Network Manager


    11/29/23

    Fix connection logic in sendvmsmail which would mess with OpenVMS V7.3
    login.


    11/19/23

    Request device notifier callbacks. Handle NETDEV_UNREGISTER callback
    which is sent on reboot requests and release the lock on the ethernet or
    wireless device. This fixes a hang seen on the Raspberry Pi Bookworm
    release during reboots.


    11/15/23

    Fix CPU hang when scanning for a node database entry to delete.
    Clean up NCP/NICE protocol exchange


    10/27/23

    Change HWaddress to Next-hop in dneigh output
    Fix dnetstat so that it correctly fills in the "Dir" field


    10/26/23

    Fix number of issues in ncp when talking to NML in pyDECnet


    9/30/2023

    Figured out how to programatically determine where 64-bit shared
    libraries are stored. The location is not standardized across
    distributions and sometimes is different between a base distribution
    and derived distributions.


    8/24/2023

    Verified that AlmaLinux and RockyLinux (Both RHEL/Centos clones) work
    correctly.


    9/18/2023

    Added installation support for Fedora distributions. X86_64 only for now.
    BuldAndInstall.sh is back at the top level of the directory hierarchy.

    Started cleanup of removing unneeded/unwanted components from the
    installation (e.g. dnetinfo is no longer needed since this release only
    provides end-node support and dneigh is sufficient for this case).


    9/9/2023

    Cleaned up the logic which decides whether received messages are read to
    the end-of-message flag (SOCK_SEQPACKET and interrupt messages for any
    socket type).

    Added a subset ncp implementation which supports all the functions
    provided by the local nml. It also supports the "tell" command so that
    these requests may be directed to remote systems.

    BuildandInstall.sh has been moved to a "debian" directory to allow for
    the possibility of supporting other distributions.


    7/22/2023

    These changes are relative to the last RaspbianDECnet release:

        Fix read handling for SEQPACKET sockets if the remote system sends
        a message longer than the receive size

        Added additional parameter when loading the DECnet kernel module:

            dn_ifname="dev"             sets the interface to be used

        Note that dn_ifname and dn_nodeaddr are now required.

        LinuxDECnet uses the newer version of nml which used to be called
        nml2 and the older version is no longer available. It also defaults
        to the newer version of fal which used to be called fal2. The older
        version is still available as fal-old.

        The kernel DECnet module now implements node counters and nml
        supports reading and zeroing node counters.

        All version numbers have moved to 3.x and the DECnet module is
        called decnet3.ko so it can co-exist with the older version.