This is an old revision of the document!


Install Doors

Instructions for installing external online programs (a.k.a. doors) into the Synchronet BBS for use by users of the Terminal Server.

Overview

BBS “doors” are external online programs, often games, that may be installed on a BBS system for its remote terminal users to use interactively. Doors are usually 16-bit DOS programs from “back in the day” and can be challenging to get working on the computers and operating systems of today. A little patience and the use of pages like this one can usually get them working however.

Supported External Program Types

The following table should help you to identify what types of online external programs (doors, external editors, file transfer protocol drivers) are supported by Synchronet and in what environments:

I/O Method Description Examples Typical Drop File Types OS
FOSSIL 16-bit DOS BBS doors and external editors TradeWars 2002, GlobalWar, LORD, FDSZ DOOR.SYS and DORINFO#.DEF Windows
COM/UART 16-bit DOS BBS doors and external editors DSZ, NukeWars DOOR.SYS and DORINFO#.DEF Windows
DOS Console 16-bit Synchronet and WWIV doors and external editors Food Fight! Rigor Mortis, Dragon's Hoard, SBJ/SBL v2.x CHAIN.TXT and XTRN.DAT Windows
TCP/IP Socket Native TCP/IP BBS doors and external editors DoorMUD, PimpWars/Win32, Darkness/Win32, SBJ/SBL v3.x DOOR32.SYS and XTRN.DAT Windows and *nix
Standard Native stdio/console programs (traditionally, UNIX) PimpWars/Linux, Lord/X, “scfg -d”, cmd.exe, bash, pico DOOR32.SYS Windows and *nix

CIOXTRN

Through the use of Deuce's CIOXTRN.EXE program (similar to the old 16-bit DOS DoorWay program), DOS and Windows-native console I/O programs not intended to run on a BBS can also be run on Synchronet for Windows.

Modules

Although technically not external programs, Synchronet also supports the interpretation and execution of external modules written in Baja or JavaScript (preferred), on all currently supported platforms.

Note: There is an active movement within the Synchronet development community to port or re-write old BBS door games and utilities in JavaScript so that they may be run natively on all Synchronet-supported platforms without any compiling or communications issues. In fact, the latest Synchronet Installer (for Windows) release includes no 16-bit DOS programs and very few native external programs, replacing the traditionally pre-configured DOS door games and external editors with newer, better games and editors written in JavaScript.

Installation

Doors are usually installed into a sub-directory of the Synchronet xtrn directory. Example: /sbbs/xtrn/doorname, where doorname is a short (8 characters or less) abbreviation of the door's name.

:!: Tip: do not install DOS doors into a directory with a long name (more than 8 characters) or with spaces or other special characters in the directory name or the door program may not work.

Some doors may require the sysop to run some sort of setup or initialization program before the door can be used, so be sure to read the door's documentation files (e.g. readme.1st, sysop.txt, *.doc, etc.) first. Remember that most door documentation was written in the 1990's (or earlier), so take some instructions (specifically those referring to FOSSIL drivers) with a grain of salt.

Automated Install

If the door is included with Synchronet, or Synchronet already has a configuration for it (in xtrn/3rdp-install), you can use the install-xtrn.js script to install your door.

Run exec/jsexec install-xtrn.js

For more information, see Install Xtrn

Manual Install

If the door you're installing is listed in the following How-To Install pages, that might be all the instructions you need.

Runtime error 200

Some 16-bit DOS programs (including many old doors) which were written and compiled with Turbo Pascal will have a problem (divide by zero) running on faster computers. The error will show itself upon execution of the door something like this:

Runtime error 200 at 345A:0091

This is a well known problem (often referred to as “RTE200”) and there are several programs which you can use to 'patch' the .EXE files to fix the problem. Which patch works seems to depend upon the program in question.

This is an entire page on the subject matter with links to several patching programs.

You may need to patch the .EXE files before you can even install or setup the door.

FOSSIL Driver

With Synchronet on 32-bit Windows operating systems, you do not need to install a FOSSIL driver (Synchronet comes with its own). There is a free 3rd party FOSSIL driver for Windows NT-based operating systems called NetFoss, but you should not need it and installing it will only complicate matters. The old 16-bit DOS FOSSIL drivers (e.g. BNU, X00) will not work either.

DOSXTRN.EXE

This 16-bit DOS component of the Synchronet FOSSIL driver for Windows (all flavors) is called DOSXTRN.EXE and it is located in the Synchronet exec directory. This program will not work with 64-bit versions of Windows since Microsoft does not include a DOS virtual machine (NTVDM) with those versions of Windows.

Windows 9x

The kernel component of the Synchronet FOSSIL driver for Microsoft Windows 95-based operating systems (no longer supported) is called sbbsexec.vxd and it is loaded when needed by Synchronet automatically. This FOSSIL driver is not actively maintained but has worked well for many sysops and their BBSes for many years. This FOSSIL driver implements the FOSSIL interface only (i.e. does not emulate a physical UART or COM port), so the doors must support and be configured to use FOSSIL interrupts for input and output.

Windows NT

The kernel component of the Synchronet FOSSIL driver for Microsoft Windows NT-based operating systems (this includes XP, Vista, and Windows 7/8/10) is called sbbsexec.dll and it is loaded when needed by Synchronet automatically.

This FOSSIL driver is also a virtual UART driver so that external DOS programs that require COM/UART access for input and output (i.e. do not support FOSSIL), can still be used on the BBS. When supported, doors should be configured to use a FOSSIL interface instead of COM/UART for input and output (for better performance and compatibility).

This FOSSIL driver can be configured (tweaked) for the specific needs of your system or a particular DOS door program by editing your sbbsexec.ini file.

Configuration

Add the program in SCFG Online Programs under Available Online Programs... in a new or existing Online Program Section.

The most critical SCFG configuration options for successful installation of an online program (door) are:

Name

Enter a descriptive name for the program, but try not to be redundant (the words “door” and “game” and not likely useful in the name). Some sysops choose to include the version of the program as well as the name.

Internal Code

Enter a short (8 characters or less), unique name for the program which Synchronet will use for internal reference purposes.

The chosen internal code may not be the same as any other installed external program.

The internal code may be used to programmatically launch the external program when the remote user views a specific text or menu file (see atcodes) or from a custom module or command shell.

Start-up Directory

The Start-up Directory should normally be the directory where the door was installed (e.g. ../xtrn/doorgame).

If the door was installed in a subdirectory of your xtrn directory, it is recommended that you use a relative path (e.g. starting with ../xtrn/) rather than an absolute path (e.g. c:\sbbs\xtrn\doorgame or /sbbs/xtrn/doorgame) as this will allow you to move the Synchronet directory tree to another drive or to another directory hierarchy without requiring modifications to your external program configurations.

On Windows, the Start-up Directory may use forward-slashes (/) or back-slashes (\) as path separators, but for compatibility with other OSes, it is recommended to use forward-slashes (e.g. ../xtrn/doorgame/ instead of ..\xtrn\doorgame\) always.

The Start-up Directory may or may not end in a trailing path separator (slash).

If no Start-up Directory is specified, the current working directory when the program is executed will be your Synchronet ctrl directory.

An invalid (e.g. non-existing) Start-up Directory will cause Synchronet to log and display an error message and not attempt to execute the program.

When executing an in-process Baja module (.bin file), the Start-up Directory is not used.

When executing an in-process JavaScript module (.js file), the Start-up Directory is searched for the script to execute and the string is also placed in the global JavaScript property/variable: startup_dir.

Command Line

This is the command to be executed when a remote user launches this external program.

Some programs may require command-line switches or options to enable specific behavior (e.g. /F to enable FOSSIL support) or specify the path to the BBS drop file.

As part of the command-line, you may use Synchronet Command Line Specifiers. These are variables which will expand to useful dynamic values before the command-line is executed.

The most commonly used Specifiers for use with external program command-lines are:

Specifier Description
%f Path to the drop file created by the BBS for this external program execution (e.g. C:\SBBS\NODE1\DOOR.SYS)
%s Path to the program's startup directory, if specified (e.g. ../xtrn/mygame/)
%n Path to the current node directory (e.g. C:\SBBS\NODE1\)
%# Current node number (1-255)
%h Current socket descriptor
%t User's time remaining/available, in seconds (e.g. 60)
%. Expands to .exe on Windows, nothing on other operating systems. Useful when hosting BBS nodes on multiple OSes with the same configuration files.

Modules

When executing an in-process module (Baja or JavaScript), begin the Command Line with a * (JavaScript or Baja) or ? (JavaScript only) character.

The path to the module and the .bin or .js file suffix/extension is not required.

Example: ?mymodule

Clean-up Command Line

This is an optional command-line to be executed after the program has returned control to the BBS.

The Clean-up Command Line may contain Command Line Specifiers.

The Native, Intercept I/O, and Use Shell To Execute options affect the execution of the Clean-up Command Line (if non-blank).

Most external programs do not require a Clean-up Command Line to be specified.

Execution Cost

This optional value is the number of credits to deduct from the user when executing this program.

Access Requirements

This is the optional Access Requirements String (ARS) which specifies which users may see this program (default: all users).

Execution Requirements

This is the optional Access Requirements String (ARS) which specifies which users may execute (run) this program (default: all users).

If you are host BBS nodes on multiple OSes and this program is only compatible with a subset of those OSes, you may want to specify the compatible ARS OS keywords here (e.g. WIN32, LINUX, etc.).

Multiple Concurrent Users

If this program supports execution by multiple simultaneous users, then this option should be set to Yes.

Note: for multiple-user programs, it is highly recommended that the BBS drop file be created in the node directory.

Intercept I/O

If this program requires the BBS to intercept standard console input and output operations, then this option should be set to Standard.

  • Most BBS doors will require this option be set to No.
  • BBS Doors that use FOSSIL I/O must have this option set to No.
  • BBS Doors that use COM/UART I/O must have this option set to No.
  • BBS Doors that use Socket I/O must have this option set to No.

When executing an in-process module (Baja or JavaScript), the Intercept I/O option is not used.

Native Executable

If this program is native to the host operating system (e.g is not a 16-bit DOS program), then this option should be set to Yes.

  • BBS Doors that use FOSSIL I/O are inherently 16-bit DOS programs and must have this option set to No.
  • BBS Doors that use COM/UART I/O are usually 16-bit DOS programs and should therefore have this option set to No.
  • BBS Doors that use Socket I/O are native (32-bit or 64-bit) programs and must have this option set to Yes.

When executing an in-process module (Baja or JavaScript), the Native Executable option is not used (all modules are native).

Use Shell to Execute

If this program requires a command shell (e.g. it's a *nix shell script, .sh file, or Windows .bat or .cmd file), then this option should be set to Yes.

When executing an in-process module (Baja or JavaScript), this option is not used.

Modify User Data

If this program supports modification of the user's data via drop file, then this option should be set to Yes.

Execute on Event

If you wish for this program to be automatically executed based on specific user operations, you may select those events here.

The available events are:

  • Logon
  • Logoff
  • New User
  • Birthday
  • Message Posted
  • File Uploaded
  • File Downloaded

If an event is selected, you may also specify that the program may be executed only on that event and not purposely selected by the user from a menu for manual execution.

Normally, this option is set to No for most door programs.

Pause After Execution

This option may be useful if you wish to debug a problem with a program which is displaying text just before quitting and the screen is being cleared (and you don't have scroll-back capabilities).

Normally, this option is set to No for most door programs.

BBS Drop File Type

Most BBS door programs require a drop file to be created by the BBS in a predetermined format and often with a predetermined filename.

This menu option allows you to select the proper drop file format, name, and case (sometimes important on non-Windows systems) and whether or not to include the user's alias or real name in the drop file.

The available drop file formats are:

Type File
Synchronet XTRN.DAT
WWIV CHAIN.TXT
GAP DOOR.SYS
RBBS/QuickBBS DORINFO#.DEF
Wildcat CALLINFO.BBS
PCBoard PCBOARD.SYS
SpitFire SFDOORS.DAT
MegaMail UTIDOOR.TXT
Solar Realms DOORFILE.SR
RBBS/QuickBBS DORINFO1.DEF
TriBBS TRIBBS.SYS
Mystic DOOR32.SYS

Place Drop File In

The drop file (if not set to None) may be created in either the node directory or the specified Start-up Directory based on the setting of this option.

If the path to the drop file (e.g. %f) is included on the Command Line, then it may not matter where the drop file is created.

However, for multiple-user programs, it is highly recommended that the drop file be created in the node directory to avoid collisions and race conditions between nodes.

Time Options

This sub-menu allows you to specify certain time constraints and monitoring behavior while the program is being run by the user.

The defaults Time Options settings are:

Extra Time None
Maximum Time None
Suspended (Free) Time No
Monitor Time Left No

How-To Install Specific Doors

Note: When using Linux with dosemu, specify full filename with extension under the Command Line option in the scfg External Programs settings, more specifically when using batch (.bat) files. For example LORD2 would be “lord2.bat %#” and not “lord2 %#” which is mentioned on the Use DOS Doors with Synchronet on Linux page.

See Also

howto/door/index.1613245714.txt · Last modified: 2021/02/13 11:48 by mlong
Back to top
CC Attribution 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0