NABUD(8)

NAME
nabud - NABU Personal Computer server

SYNOPSIS
nabud [-c conf] [-d subsys] [-f] [-l logfile] [-u user] [-U umask]

DESCRIPTION
nabud is a server for NABU Personal Computers. The NABU Personal Computer is a Z80-based machine system sold briefly in Canada in the early 1980s that downloaded all of its software from participating cable TV networks using an external appliance called the “Adaptor”. The NABU was connected to the Adaptor using an RS422 serial interface running at 111,860 baud and sent requests to the Adaptor for indiviual segments of numbered images. The communication with the cable TV network was one-way, so the content was broadcast in a continuous “cycle”; the Adaptor simply waited for the requested packet to arrive, at which point it was relayed to the waiting NABU. The content was interleaved such that retrieving the next segment of a particular image did not incur an excessively long wait time. The Adaptor itself was relatively simple and did very little local processing beyond extremely basic packet filtering that could be achieved on a Motorola 6801 MCU. The serial interface was based around the Western Digital TR1863P UART.

nabud emulates the original Adaptor protocol and has the following features:

•   Serve pre-packetized “pak” files. These files can be unencrypted or encrypted using the NabuRetroNet scheme. This is the format used to vend the orginal NABU Network cycles from 1984.

•   Serve flat “nabu” files. These files are simply flat binaries that are loaded into a fixed memory location by the NABU ROM. They are packetized on-the-fly by nabud.

•   Flexible configuration model that allows up to 254 content “channels” from an arbitrary number of “sources”.

•   Serve an arbitrary number of NABU PCs, limited only by the number of serial ports you can connect to the server.

•   Serve an arbitrary number of simulated NABU PCs (for example, MAME) on the local machine or on your local network over TCP/IP.

•   Selection of per-connection alternative files (and a per-channel default file) to be served to the NABU when the NABU ROM requests image 000001 (the boot image).

•   A control program, nabuctl(1), that lets you get information about channels and connections, as well as list the contents if the NabuRetroNet “HomeBrew” channel and select different files to be loaded by the NABU.

•   Support for the NABU HCCA Application Communication Protocol. NHACP is a new protocol extension under active development that allows programs running on the NABU to access remote storage.

•   Support for the NabuRetroNet protocol extensions. These protocol extensions provide support for accessing remote storage and other features. nabud supports NabuRetroNet protocol extension version v2023.02.03.00.

•   Minimal privilege requirements. nabud requires the ability to open serial ports for reading and writing in order to communicate with NABU PCs. If only TCP/IP is used, nabud requires no special privileges.

•   Extremely portable implementation that relies mainly on standard POSIX and C99 interfaces and keeps external dependencies to a minimum.

nabud accepts the following options:

-c conf
    Specifies an alternative location for the nabud configuration file.

-d subsys
    Enables debugging messages for the specified subsystem. Multiple -d options can be specified. This option also implies the -f option. Available subystems:

    all Enables debugging for all subsystems.

    any This is an alias for “all”.

    adaptor
        The routines that implement the Adaptor protocol.

    atom
        The routines used to serialize control messages.

    cli The command line support routines.

    conn_io
        The connection I/O routines used by NABU connections and control connections.

    control
        The control message routines.

    fileio
        The abstracted file I/O routines used to read and write local and remote files.

    image
        The routines that manage NABU program images.

    nhacp
        The routines that implement the NHACP protocol.

    retronet
        The routines that implement the RetroNet protocol extensions.

    stext
        The routines that implement the storage extensions back-end, shared by NHACP and RetroNet.

-f  Runs nabud in the foreground. Without this option, nabud detaches from the controlling terminal and runs as a daemon.

-l logfile
    Tells nabud to write log messages to the specified log file. By default, nabud logs all messages to the system log using syslog(3) with the LOG_USER facility. Note that when -f is specified, all log message are written to the controlling terminal.

-u user
    Specifies an alternative user ID to run nabud as. Use of this option to specify a minimally-privileged user is highly recommended. This option is ignored if nabud is not started as the super-user.

-U umask
    Specifes the file creation mask to use when creating files. File creation on the server is suppored by the NHACP protocol and the NabuRetroNet protocol extensions.

CONFIGURATION
nabud requires a configuration file in order to run. The configuration file is a JSON-format dictionary with three stanzas in the following order:

Sources
    An array of objects that define channel sources.

Channels
    An array of objects that define the content channels available to connected NABUs.

Connections
    An array of objects that define the NABU connections ( either serial connections to real hardware or TCP/IP connections to emulators).

The next subsections describe the individual stanzas and the object definitions they contain. The described object properties are required unless specified otherwise.

  Sources
The “Sources” stanza is an array of source objects. Each source object has the following properties:

Name
    A string that specifies the name of the source.

Location
    A string that specifies the location of the source. The location may be a local path name or a URL.

  Channels
The “Channels” stanza is an array of channel objects. Each channel object has the following properties:

Name
    A string that specifies the name of the channel. In addition to being the name displayed to the user, this is default subdirectory relative to the root of the source that contains the content for the channel.

Path
    An optional string that specifies the path relative to the root of the source that contains the content for the channel.

Number
    A number between 1 and 255 that specifies the channel's number.

Type
    A string that specifies if the channel contains “pak” or “nabu” files.

Source
    A string that specifies the source of the channel.

ListURL
    An optional string that specifies a listing file in the format used by NabuRetroNet that lists the content of the channel. This listing can be viewed by nabuctl(1), which can then also select these files for download on individual connections.

DefaultFile
    An optional string that specifes a default file to be loaded when the NABU ROM requests image 000001. Indiviual connections can override this by selecting a different file.

RetroNetExtensions
    An optional boolean value ( “true” or “false”) that specifies if the NabuRetroNet protocol extensions are enabled for connections using this channel. NabuRetroNet protocol extensions are disabled by default due to collisions with NHACP; if the NabuRetroNet protocol extensions are enabled, then NHACP will not be available for connections using this channel.

  Connections
The “Connections” stanza is an array of connection objects. Each connection object has the following properties:

Type
    A string that specifies if the connection type, either “serial” or “tcp”.

Port
    A string that specifies the connect port. For “serial” connections, this is the path to the serial port's device special file, for example “/dev/ttyU0”. For “tcp” connections, this is the TCP port number on which nabud will listen for incoming connections from NABU emulators.

Baud
    An optional number with a value of at least 1 that specifies the baud rate to use for this connection. Baud rate is only applicable to serial connections. If the baud rate is un-specified, then the connection will default to the NABU native baud rate of 111860, and will fall back to 115200 if the native baud rate is not supported by the serial interface. This option is really only useful if you have modified your NABU's HCCA port to use a different baud rate clock.

BaudRate
    This is an alias for “Baud”. If the “Baud” property is not present, “BaudRate” will be consulted.

FlowControl
    An optional boolean value ( “true” or “false”) that specifies if RTS/CTS flow control is to be used for this connection. Flow control is only applicable to serial connections. The default is “false”. This option is really only useful if you have modified your NABU's HCCA port to support RTS/CTS flow control.

StopBits
    An optional number with a value of 1 or 2 that specifies the number of stop bits to use for this connection. Stop bits is only applicable to serial connections. If the number of stop bits is unspecified, then the connection will default to 2.

Channel
    An optional number between 1 and 255 that specifies the connection's default channel.

StorageArea
    An optional string that specifies the local file storage directory for this connection. This option must be specified if you wish to use the NHACP or RetroNet storage extensions. In previous releases, this property was called “FileRoot”, and the old name is still recognized for compatibility with existing configuration files.

Here is a simple example configuration file:

    {
      "Sources": [
        {
          "Name": "NabuRetroNet",
          "Location": "https://cloud.nabu.ca",
        }
      ],
      "Channels": [
        {
          "Name": "NABU Network 1984 Cycle v1",
          "Path": "cycle1",
          "Number": 1,
          "Type": "pak",
          "Source": "NabuRetroNet"
        }
      ],
      "Connections": [
        {
          "Type": "serial",
          "Port": "/dev/ttyU0",
          "Channel": 1,
        }
      ]
    }

RUN-TIME SETUP
While it is possible to simply run nabud without any run-time setup, it is strongly recommended that you do a little extra work to run nabud as a minimally-privileged user. This section is intended to provide some guidance for how to configure the run-time environment of nabud as well as provide suggestions for file system permissions and group management.

First and foremost, you should create a dedicated group for all users on the system that will have permission to do make changes to files accessed by nabud and interact with nabud using nabuctl(1). In these examples, we will use the group name “nabu”.

Next, you should create a dedicated user for running nabud. This user does not need a home directory or a login shell, and should have no other role on the system. In these examples, we will use the user name “nabu”. This user's primary group should also be the “nabu” group created in the first step.

If you will be using a serial port to communicate with real NABU hardware, nabud will need to be able to open the serial port devices for reading and writing. Many Unix-like systems provide a system group for the purpose of granting permission to specific users to open serial ports for dial-out. This group might be called “dialer”, “dialout”, or “uucp”. If your system does not provide a suitable group, create one. In this example, the system provides a “dialer” group, and so we will use that name throughout the examples.

Ensure the “dialer” group has read-write permission for the serial port that will be used to connect to the NABU. In this example, the path to the serial port is “/dev/ttyU0”.

    0 crw-rw----  1 uucp  dialer  66, 0 Dec 31 14:15 /dev/ttyU0

Once the persmissions on the serial port devices are set correctly, add the “nabu” user to that group.

If you will be using the storage extensions to the NABU Adaptor protocol (such as NHACP), then you should create a directory for your NABU's files. This directory will be specified in the “StorageArea” property of your NABU's connection object in the nabud configuration file. The directory should be owned by the “nabu” user and group, and should have the mode 0775 (octal):

    4 drwxrwxr-x  2 nabu  nabu  512 Jan 16 22:05 living-room-nabu/

This will allow nabud to create files in that directory, as necessary (e.g. game save files, etc.). It is still possible to put more restrictive permissions on files inside that directory if you want the NABU to have read-only access to some files (such as your Zork CP/M disk image). This will also allow other users in the “nabu” group to add files to that directory to be accessed by programs running on the NABU.

Once you have set up the run-time environment as described above, you should use the -u user and -U umask options when running nabud:

    /usr/pkg/sbin/nabud -u nabu -U 002

The -U umask argument ensures that users in the “nabu” group will be able to manipulate any files created by programs running on the NABU.

nabud creates a Unix domain socket to allow the nabuctl(1) program to send control messages. nabud will set the owner and group of this socket to the user ID and effective group ID that nabud is running as, and allow connections from any user in that group. If nabud is configured as described above, the permissions on this socket ( located at “/tmp/nabuctl.sock”) will be:

    0 srwxrwxr-x  1 nabu  nabu  0 Feb  4 05:29 /tmp/nabuctl.sock=

FILES
By default, nabud will look for its configuration file at:

    /usr/pkg/etc/nabud.conf

nabud creates a control message socket at:

    /tmp/nabuctl.sock

A more complex example configuration file can be found at:

    /usr/pkg/share/nabud/examples/nabud.conf

rc.conf.d and rc.d files can be found at:

    /usr/pkg/share/nabud/rc.conf.d/nabud
    /usr/pkg/share/nabud/rc.d/nabud

SEE ALSO
nabuctl(1)