QWiKBoard
=========

QWikBoard is a simple Lua programme which provides the backend for a
message board system based entirely around the QWK offline mail packet
format.  The idea is to provide something akin to the message board
elements of a 1980s-style BBS, but without the online elements.

Requirements
------------

The programme itself has fairly modest requirements, needing only
a Lua 5.4 interpreter and the lua-posix package. Under Debian systems
these can be met by installing the required packages using apt:

      apt-get install lua5.4 lua-posix

Installation
------------

Installation simply involves placing the qwikboard executable Lua script
somewhere in your execution path, for instance in /usr/local/bin.

Setting up a message board
--------------------------

Each message board requires a directory on your filesystem to call its own.
For a system-wide message board, a directory under /var is perhaps appropriate.
(In this case, it probably makes sense to create a system user and group to
own the directory.)

For the purposes of this introduction, lets assume you've chosen the directory
to be /var/mybbs.

Once you've set up this directory, run qwikboard to create a default
configuration file.

    qwikboard /var/mybbs newcfg

This will create a new file /var/mybbs/config.lua.  Open this file and modify
to your liking.

Finally, issue the following command to initialise the board structure.

    qwikboard /var/mybbs init

This command creates the board directory structure, including
- /var/mybbs/conferences which holds the message database, and
- /var/mybbs/notices which holds the notice files which are
displayed to users by their offline mail reader when they open (hello)
and close (goodbye) mail packets.  An additional file (news) contains
any board-wide news you'd like to distribute to your users.
(You can remove any of these notice files if they're not relevant.)

Interacting with a message board
--------------------------------

Interaction with the board is of course primarily via QWK packets and
corresponding REP files (reply files generated by offline mail readers).

To generate a QWK file for board user USER, use the following

   qwikboard /var/mybbs qwkout USER outfile.qwk

The "outfile.qwk" argument specifies the name and location of the QWK file
which will be generated.

To incorporate new messages from user USER into the board, use the command

   qwikboard /var/mybbs repin USER infile.rep

(All messages will be sent from USER, regardless of the sender named in the
rep file messages.) The "infile.rep" argument is the name and location of the
REP file to be read.

NNCP integration
----------------

Of course, manual generation of QWK files and reading of REP files
using the above commands for each user would be incredibly tedious.
QWiKBoard is intended to be used in conjunction with the NNCP store
and forward networking tool, and provides the "nncp_handler" command
for interaction with this system.

To enable this, simply add an exec entry to any of your neighbours
(entries in the "neigh" section of nncp.hjson) who you'd like to have
access to the board.  For instance, for our board in /var/mybbs
we could use:

    exec: {
        qwikboard: ["/usr/local/bin/qwikboard", "/var/mybbs", "nncp_handler"]
    }

Any of these neighbours can then retrieve QWK files using:

    echo get USER | nncp-exec bbsnode qwikboard

This will result in the QWK file being assembled sent to the
requesting node using nncp-file, meaning the requesting node will also
need an incoming directory specified. The "USER" argument specifies
the handle which will be associated with the requesting node
when replies are sent, and is optional for subsequent requests
from the same node. (It is an error to request a packet for
a username which has already been associated with another node.)

Similarly, REP files can be submitted using:

    nncp-exec bbsnode qwikboard < replyfile.rep

This will result in the messages contained in replyfile.rep being
incorporated into the message database.

Finally, a user can export all of their own messages (under their
current handle) to a text file using

    echo export | nncp-exec bbsnode qwikboard

License
-------

QWiKBoard is free software, and is distributed under the terms of the
GNU General Public License version 3.0.  A copy of this license can be
found in a file named COPYING in the same directory as this README
file.