From: plugd Date: Sun, 11 Aug 2024 14:27:04 +0000 (+0200) Subject: Added README. X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?a=commitdiff_plain;h=b2af18b746a9118b51dc6b50cac580945fe720f4;p=qwikboard.git Added README. --- diff --git a/README b/README new file mode 100644 index 0000000..3d3d083 --- /dev/null +++ b/README @@ -0,0 +1,119 @@ +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. + +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 | 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. + +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. + +The nncp_handler command assumes that the name of the sending NNCP +node is the name of the user. Thus, when registering users to the +BBS, ensure that you configure their node names appropriately in +nncp.hjson. + +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. \ No newline at end of file