Doors

A door is a single-user game (or utility) the BBS launches as a
sub-process. Originals were DOS programs talking to the BBS via a
fake COM port; today there's a wider menagerie.

Door types ANetBBS supports

Note: ANetCRAFT (the bundled builtin_python door above) is a
separate codebase from the standalone ANetCRAFT-Door project (a
C# .NET Minecraft-replica door) — same name, different projects. Don't
assume a fix or feature in one applies to the other.

Playing

• Web: /games/ — game list. Pick one and play in the browser
  (web games) or in a Web Terminal popup (terminal games).
• Terminal: main menu — usually under a "Games" or "Doors" sub-menu.

Dropfiles

Terminal doors expect a dropfile — a text file with the user's
name, time remaining, baud rate, etc. ANetBBS writes the major
formats automatically right before launch:

• DOOR.SYS — almost-universal
• DORINFO1.DEF — Synchronet/Telegard-flavored
• DOOR32.SYS — modern 32-bit format, used by newer FPC-based door kits
• CHAIN.TXT — caller information format used by some native doors,
  including Cepheus Trader

Stored in each door's working directory; cleared on launch.

Cepheus Trader

Cepheus Trader can be run from ANetBBS as a
native Linux door. The Cepheus Trader client connects to its remote
game server while ANetBBS supplies the current caller information
through a CHAIN.TXT dropfile.

The configuration below was tested successfully with Cepheus Trader
Client v0.7.15.

Prerequisites

Before adding the door to ANetBBS, obtain the following from the
Cepheus Trader administrator:

• Cepheus Trader server hostname
• Game/player port
• Sysop/configuration port
• Your assigned BBS ID
• Your BBS PSK

The BBS ID and PSK identify the BBS installation, not an individual
caller. Do not use the BBS ID as the player's username.

Security: The BBS PSK and generated credential file are secrets.
Never publish them or commit them to a public repository.

Install the client

Extract the Linux Cepheus Trader client into a directory under your
ANetBBS installation. For example:

doors/ct/

The package contains executables including:

bin/cepheus-trader-door
bin/cepheus-trader-sysop
bin/cepheus-trader-league

Verify the installed version from the Cepheus Trader directory:

bin/cepheus-trader-door --version
bin/cepheus-trader-sysop --version

Initialize the BBS credential

From the Cepheus Trader directory, initialize the installation using
the hostname and ports supplied by the Cepheus Trader administrator:

bin/cepheus-trader-sysop \
  --server <CT_SERVER> \
  --game-port <GAME_PORT> \
  --sysop-port <SYSOP_PORT> \
  init-credential

You will be prompted for your assigned BBS ID and PSK.

A successful initialization creates files including:

cepheus-trader.conf
cepheus-trader.credential
cepheus-trader.identities

The PSK is stored in the protected credential file rather than directly
in cepheus-trader.conf.

Configure the BBS identity

Configure the BBS name, polity name, Trade/Combat value, and Chaos/Order
value:

bin/cepheus-trader-sysop \
  --config cepheus-trader.conf \
  set-config "<BBS_NAME>" "<POLITY_NAME>" 50 50

The two numeric values above are examples. Set them as appropriate for
your BBS.

Verify the configuration with:

bin/cepheus-trader-sysop \
  --config cepheus-trader.conf \
  get-config

A successful response should show that the BBS is configured.

File ownership and permissions

Cepheus Trader performs ownership/security checks on its credential
files. The credential and identity files must be owned by the Unix
account that actually runs the door.

Check which account runs ANetBBS:

systemctl show anetbbs -p User -p Group -p DynamicUser

If ANetBBS runs as a dedicated service account, make that account the
owner of the Cepheus Trader credential and identity files.

For example:

sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.credential
sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.identities
sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.identities.lock

sudo chmod 600 cepheus-trader.credential
sudo chmod 600 cepheus-trader.identities
sudo chmod 600 cepheus-trader.identities.lock

The configuration itself can remain readable:

chmod 644 cepheus-trader.conf

You can test credential access as the ANetBBS service account:

sudo -u <ANETBBS_USER> \
  bin/cepheus-trader-sysop \
  --config <FULL_PATH_TO_CT>/cepheus-trader.conf \
  get-config

If the BBS configuration is returned successfully, the service account
can read the credential and authenticate with the Cepheus Trader server.

Add Cepheus Trader to ANetBBS

Create a new game in the ANetBBS Door Games administration interface.

Use the following settings:

Set the command-line arguments to:

--config <FULL_PATH_TO_CT>/cepheus-trader.conf -D %f

Replace <FULL_PATH_TO_CT> with the absolute path to your Cepheus
Trader installation.

ANetBBS expands %f to the full path of the generated dropfile when
the door is launched.

Why CHAIN.TXT?

For Cepheus Trader v0.7.15, the tested ANetBBS integration uses
CHAIN.TXT.

Do not configure the working ANetBBS installation using:

-L
-USERNAME
-SOCKET

During testing, OpenDoors local mode with -USERNAME did not provide
the caller identity correctly to Cepheus Trader when entering the game,
even when a valid username was supplied directly.

Using CHAIN.TXT allows ANetBBS to provide the caller information
through the normal door dropfile mechanism and avoids this issue.

The known-good command line is:

--config <FULL_PATH_TO_CT>/cepheus-trader.conf -D %f

First login

The first time a caller enters Cepheus Trader, the game may report that
no captain is registered for the local BBS account.

The caller should complete the normal character creation process.

After creating the character:

1. Exit Cepheus Trader normally.
2. Return to ANetBBS.
3. Launch Cepheus Trader again.
4. Confirm that the existing character is restored.

If the character returns, the local BBS account has been associated
successfully with its Cepheus Trader identity.

Back up the Cepheus Trader files

Back up these files:

cepheus-trader.conf
cepheus-trader.credential
cepheus-trader.identities

In particular:

• cepheus-trader.credential contains the protected credential used
  by this BBS installation to authenticate with the Cepheus Trader
  server.
• cepheus-trader.identities maintains the local BBS user-to-game
  identity associations.

Treat both files as private.

The .lock file does not normally need to be backed up.

Troubleshooting Cepheus Trader

credential file is not owned by the current user

The credential is owned by a different Unix account than the one
running the door.

Check ownership:

ls -l cepheus-trader.*

Then assign the credential and identity files to the ANetBBS service
account and restrict their permissions:

sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.credential
sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.identities
sudo chown <ANETBBS_USER>:<ANETBBS_GROUP> cepheus-trader.identities.lock

sudo chmod 600 cepheus-trader.credential
sudo chmod 600 cepheus-trader.identities
sudo chmod 600 cepheus-trader.identities.lock

BBS user name must contain 1..255 bytes

If the door is configured with -L -USERNAME, switch to the tested
CHAIN.TXT configuration.

Use:

Drop File Type: CHAIN.TXT

and:

--config <FULL_PATH_TO_CT>/cepheus-trader.conf -D %f

Remove -L, -USERNAME, and -SOCKET.

Door connects but asks the caller to create a character

This is normal on the caller's first successful connection if the BBS
account has not yet been associated with a Cepheus Trader identity.

Complete character creation, exit normally, and launch the door again.
The existing character should be restored.

Known-good configuration

For quick reference:

Game Type:          Native/Script Door Game
Executable Path:    doors/ct/bin/cepheus-trader-door
Working Directory:  doors/ct/
Drop File Type:     CHAIN.TXT

Command-line arguments:

--config <FULL_PATH_TO_CT>/cepheus-trader.conf -D %f

This configuration has been tested with Cepheus Trader Client v0.7.15
through ANetBBS, including initial character creation, normal exit, and
successful restoration of the existing character on the next login.

Don't touch the door's working dir

ANetBBS deliberately does not sweep files inside a door's
working directory between launches. Some doors keep persistent
node-specific state in files named like NODE1.DAT that look like
lockfiles but are actually config. Sysops who run an aggressive
cleanup will break the door.

Adding a door

See Door Setup for the long version.