enigma-bbs/local-doors.md at 97ae34a9713b7f3024e3308a09d59eaa60e7d3ed

11 KiB

Raw Blame History

layout	title
page	Local Doors

Local Doors

ENiGMA½ has many ways to add doors to your system. In addition to the many built in door server modules, local doors are of course also supported using the ! The abracadabra module!

ℹ️ See also Let’s add a DOS door to Enigma½ BBS by Robbie Whiting for a great writeup on adding doors!

The abracadabra Module

The abracadabra module provides a generic and flexible solution for many door types. Through this module you can execute native processes & scripts directly, and perform I/O through standard I/O (stdio) or a temporary TCP server.

Configuration

The abracadabra config block can contain the following members:

Item	Required	Description
`name`	👍	Used as a key for tracking number of clients using a particular door.
`dropFileType`	👎	Specifies the type of dropfile to generate (See Dropfile Types below). Can be omitted or set to `none`.
`cmd`	👍	Path to executable to launch.
`args`	👎	Array of argument(s) to pass to `cmd`. See Argument Variables below for information on variables that can be utilized here.
`preCmd`	👎	Path to a pre-command executable or script to launch. Executes before `cmd`.
`preCmdArgs`	👎	Array of argument(s) to pass to `preCmd`. See Argument Variables below for information on variables that can be utilized here.
`cwd`	👎	Sets the Current Working Directory (CWD) for `cmd`. Defaults to the directory of `cmd`.
`env`	👎	Sets the environment. Supplied in the form of an map: `{ SOME_VAR: "value" }`
`nodeMax`	👎	Max number of nodes that can access this door at once. Uses `name` as a tracking key.
`tooManyArt`	👎	Art spec to display if too many instances are already in use.
`io`	👎	How to process input/output (I/O). Can be `stdio` or `socket`. When using `stdio`, I/O is handled via standard stdin/stdout. When using `socket` a temporary socket server is spawned that can be connected back to. The server listens on localhost on `{srvPort}` (See Argument Variables below for more information). Default value is `stdio`.
`encoding`	👎	Sets the door's encoding. Defaults to `cp437`. Linux binaries often produce `utf8`.

Dropfile Types

Dropfile types specified by dropFileType:

Value	Description
`none`	No door file is needed
`DOOR`	DOOR.SYS
`DOOR32`	DOOR32.SYS
`DORINFO`	DORINFOx.DEF

Argument Variables

The following variables may be used in args and preCmdArgs entries:

Variable	Description	Example
`{node}`	Current node number.	`1`
`{dropFile}`	Dropfile filename only.	`DOOR.SYS`
`{dropFilePath}`	Full path to generated dropfile. The system places dropfiles in the path set by `paths.dropFiles` in `config.hjson`.	`C:\enigma-bbs\drop\node1\DOOR.SYS`
`{dropFileDir}`	Full path to directory containing the generated dropfile.	`/home/enigma-bbs/drop/node1/`
`{userAreaDir}`	Full path to a directory safe for user-specific save files/etc.	`/home/enigma-bbs/drop/node1/NuSkooler/lord/`
`{userId}`	Current user ID.	`420`
`{userName}`	Sanitized username. Safe for filenames, etc. If the full username is sanitized away, this will resolve to something like "user_1234".	`izard`
`{userNameRaw}`	Raw username. May not be safe for filenames!	`\/\/izard`
`{srvPort}`	Temporary server port when `io` is set to `socket`.	`1234`
`{cwd}`	Current Working Directory.	`/home/enigma-bbs/doors/foo/`
`{termHeight}`	Current client term height	`25`
`{termWidth}`	Current client term width	`80`

Example args member using some variables described above:

args: [
    "-D", "{dropFilePath}",
    "-N", "{node}"
    "-U", "{userId}"
]

DOSEMU with abracadabra

DOSEMU can provide a good solution for running legacy DOS doors when running on Linux systems. For this, we will create a virtual serial port (COM1) that communicates via stdio.

As an example, here are the steps for setting up Pimp Wars:

First, create a dosemu.conf file with the following contents:

$_cpu = "80486"
$_cpu_emu = "vm86"
$_external_char_set = "utf8"
$_internal_char_set = "cp437"
$_term_updfreq = (8)
$_layout = "us"
$_rawkeyboard = (0)
$_com1 = "virtual"

The line $_com1 = "virtual" tells DOSEMU to use stdio as a virtual serial port on COM1.

Next, we create a virtual X drive for Pimp Wars to live such as /enigma-bbs/DOS/X/PW and map it with a custom AUTOEXEC.BAT file within DOSEMU:

@echo off
path d:\bin;d:\gnu;d:\dosemu
set TEMP=c:\tmp
prompt $P$G
REM http://www.pcmicro.com/bnu/
C:\BNU\BNU.COM /L0:57600,8N1 /F
lredir.com x: linux\fs\enigma-bbs\DOS\X
unix -e

Note that we also have the BNU FOSSIL driver installed at C:\BNU\\. Another option would be to install this to X: somewhere as well.

Finally, let's create a menu.hjson entry to launch the game:

doorPimpWars: {
    desc: Playing PimpWars
    module: abracadabra
    config: {
        name: PimpWars
        dropFileType: DORINFO
        cmd: /usr/bin/dosemu
        args: [
            "-quiet",
            "-f",
            "/path/to/dosemu.conf",
            "X:\\PW\\START.BAT {dropFile} {node}"
        ],
        nodeMax: 1
        tooManyArt: DOORMANY
        io: stdio
    }
}

Shared Socket Descriptors

Due to Node.js limitations, ENiGMA½ does not directly support DOOR32.SYS style socket descriptor sharing (other DOOR32.SYS features are fully supported). However, a separate binary called bivrost! can be used. bivrost! is available for Windows and Linux x86/i686 and x86_64/AMD64. Other platforms where Rust builds are likely to work as well.

Example configuration

Below is an example menu.hjson entry using bivrost! to launch a door:

doorWithBivrost: {
    desc: Bivrost Example
    module: abracadabra
    config: {
        name: BivrostExample
        dropFileType: DOOR32
        cmd: "C:\\enigma-bbs\\utils\\bivrost.exe"
        args: [
            "--port", "{srvPort}",          //  bivrost! will connect this port on localhost
            "--dropfile", "{dropFilePath}", //  ...and read this DOOR32.SYS produced by ENiGMA½
            "--out", "C:\\doors\\jezebel",  //  ...and produce a NEW DOOR32.SYS here.

            //
            //  Note that the final <target> params bivrost! will use to
            //  launch the door are grouped here. The {fd} variable could
            //  also be supplied here if needed.
            //
            "C:\\door\\door.exe C:\\door\\door32.sys"
        ],
        nodeMax: 1
        tooManyArt: DOORMANY
        io: socket
    }
}

Please see the bivrost! documentation for more information.

Phenom Productions Releases

Pre-built binaries of bivrost! have been released under Phenom Productions and can be found on various boards.

Alternative Workarounds

Alternative workarounds include Telnet Bridge module to hook up Telnet-accessible (including local) door servers -- It may also be possible bridge via NET2BBS.

QEMU with abracadabra

QEMU provides a robust, cross platform solution for launching doors under many platforms (likely anywhere Node.js is supported and ENiGMA½ can run). Note however that there is an important and major caveat: Multiple instances of a particular door/OS image should not be run at once! Being more flexible means being a bit more complex. Let's look at an example for running L.O.R.D. under a UNIX like system such as Linux or FreeBSD.

Basically we'll be creating a bootstrap shell script that generates a temporary node specific GO.BAT to launch our door. This will be called from AUTOEXEC.BAT within our QEMU FreeDOS partition.

Step 1: Create a FreeDOS image

FreeDOS is a free mostly MS-DOS compatible DOS package that works well for running 16bit doors. Follow the QEMU/FreeDOS guide for creating an freedos_c.img. This will contain FreeDOS itself and installed BBS doors.

After this is complete, copy LORD to C:\DOORS\LORD within FreeDOS. An easy way to tranfer files from host to DOS is to use QEMU's vfat as a drive. For example:

qemu-system-i386 -localtime /home/enigma/dos/images/freedos_c.img -hdb fat:/path/to/downloads

With the above you can now copy files from D: to C: within FreeDOS and add the following to it's autoexec.bat:

CALL E:\GO.BAT

Step 2: Create a bootstrap script

Our bootstrap script will prepare GO.BAT and launch FreeDOS. Below is an example:

#!/bin/bash

NODE=$1
DROPFILE=D:\\$2
SRVPORT=$3

mkdir -p /home/enigma/dos/go/node$NODE

cat > /home/enigma/dos/go/node$NODE/GO.BAT <<EOF
C:
CD \FOSSIL\BNU
BNU.COM
CD \DOORS\LORD
COPY /Y $DROPFILE
CALL START.BAT $NODE
FDAPM POWEROFF
EOF

unix2dos /home/enigma/dos/go/node$NODE/GO.BAT

qemu-system-i386 -localtime /home/enigma/dos/images/freedos_c.img -chardev socket,port=$SRVPORT,nowait,host=localhost,id=s0 -device isa-serial,chardev=s0 -hdb fat:/home/enigma/xibalba/dropfiles/node$NODE -hdc fat:/home/enigma/dos/go/node$NODE -nographic

Note the qemu-system-i386 line. We're telling QEMU to launch and use localtime for the clock, create a character device that connects to our temporary server port on localhost and map that to a serial device. The -hdb entry will represent the D: drive where our dropfile is generated, while -hdc is the path that GO.BAT is generated in (E:\GO.BAT). Finally we specify -nographic to run headless.

For doors that do not require a FOSSIL driver, it is recommended to not load or use one unless you are having issues.

Finally we can create a menu.hjson entry using the abracadabra module:

doorLORD: {
    desc: Playing L.O.R.D.
    module: abracadabra
    config: {
        name: LORD
        dropFileType: DOOR
        cmd: /home/enigma/dos/scripts/lord.sh
        args: [
            "{node}",
            "{dropFile}",
            "{srvPort}",
        ],
        nodeMax: 1
        tooManyArt: DOORMANY
        io: socket
    }
}

11 KiB

Raw Blame History

Local Doors

The abracadabra Module

Configuration

Dropfile Types

Argument Variables

DOSEMU with abracadabra

Shared Socket Descriptors

Example configuration

Phenom Productions Releases

Alternative Workarounds

QEMU with abracadabra

Step 1: Create a FreeDOS image

Step 2: Create a bootstrap script

Step 3: Create a menu entry

See Also

Additional Resources

DOS Emulation

Door Downloads & Support Sites

General

L.O.R.D.

11 KiB Raw Blame History Unescape Escape

Local Doors

The abracadabra Module

Configuration

Dropfile Types

Argument Variables

DOSEMU with abracadabra

Shared Socket Descriptors

Example configuration

Phenom Productions Releases

Alternative Workarounds

QEMU with abracadabra

Step 1: Create a FreeDOS image

Step 2: Create a bootstrap script

Step 3: Create a menu entry

See Also

Additional Resources

DOS Emulation

Door Downloads & Support Sites

General

L.O.R.D.

11 KiB

Raw Blame History