Install Doors

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

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.

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:

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.

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.

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.

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

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

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.

• ftp://vert.synchro.net/main/util/patchcrt.zip

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.

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.

The 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.

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.

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.

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:

1. Start-up Directory
2. Command Line
3. I/O Method
4. Native Executable/Script
5. BBS Drop File Type

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.

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.

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.

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:

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

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, I/O Method, and Use Shell or New Context 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.

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

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

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.).

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.

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

• Most 16-bit (DOS) BBS doors will require this option be set to FOSSIL or UART (only available for 16-bit DOS programs).
• Most native (Win32 or *nix) BBS doors will require this option be set to Socket (only available for native programs).
• When executing an in-process module (Baja or JavaScript), the I/O Method option is not applicable.

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/Script option is not used (all modules are native).

If this program requires an OS 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 a JavaScript module, enabling this option forces a new JS engine context (i.e. sandbox) to be created and used to execute the script.

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

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
• Local/Sysop Chat

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.

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.

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:

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.

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:

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.

• sbbsexec.dll
• sbbsexec.ini
• Configure Command Lines
• dosemu
• doscmd
• How-To Pages
• cioxtrn