                       DOOR HUB 0.1.0 - JOINING A HUB
                     For sysops connecting a BBS to a hub

CONTENTS
  1. What you need
  2. Getting an account
  3. The connector settings
  4. Installing the connector on Linux
  5. Installing the connector on Windows
  6. Synchronet: adding the hub to your doors menu
  7. Mystic and other BBS programs
  8. Testing
  9. Your players
 10. Running more than one hub, and DoorParty
 11. Troubleshooting
 12. Leaving a hub


1. WHAT YOU NEED
----------------
  - A BBS that can open an outgoing RLogin connection for a caller.
    Synchronet does this with bbs.rlogin_gate (doorhub.js uses it).
    Mystic does it with the IR menu command. See section 7 for others.
  - The connector for your system: doorhub-connector (Linux x64 or arm64)
    or doorhub-connector.exe (Windows 64-bit).
  - Outgoing internet access to the hub's SSH port (2022 unless the hub
    says otherwise). Nothing needs to be opened on your router: the
    connector only makes outgoing connections, and it listens only on
    your own machine.


2. GETTING AN ACCOUNT
---------------------
Ask the hub's sysop for an account. Tell them your BBS name and the
system tag you would like (2 to 8 letters or digits, for example KAL).
The tag appears in front of your callers' names on the hub, so pick one
that people will connect with your board. For the Kalgoorlie Door Hub,
email slaterm@theiguru.au.

The hub sends you a filled-in doorhub-connector.ini. It holds your hub
password, so treat it like any other password: keep it on the BBS
machine only, readable by the BBS account only.


3. THE CONNECTOR SETTINGS
-------------------------
doorhub-connector.ini uses the same names as DoorParty's connector:

  system_tag      = KAL               your tag (the hub checks it)
  ssh_username    = kal_bbs           your hub account
  ssh_password    = ...               your hub password
  local_interface = 127.0.0.1         where the connector listens
  local_port      = 9998              the port your BBS connects to
  ssh_host        = hub.example.com   the hub's address
  ssh_port        = 2022              the hub's SSH port
  rlogin_host     = 127.0.0.1         leave as it is
  rlogin_port     = 513               leave as it is

Notes:
  - Keep local_interface = 127.0.0.1 unless the BBS runs on a different
    machine from the connector. Anyone who can reach local_port can send
    players to the hub in your BBS's name.
  - local_port can be any free port. DoorParty's connector usually uses
    9999, so Door Hub's examples use 9998 and both can run side by side.
  - Lines starting with ; or # are comments.
  - An optional line  known_hosts = path  changes where the hub's key is
    remembered (see below).

The hub's key. The first time the connector reaches the hub it saves the
hub's SSH key in doorhub_known_hosts, next to the ini, and logs a line
"Trusting hub key ... SHA256:...". You can check that fingerprint with
the hub's sysop. After that the connector refuses to connect if the key
changes, because that would mean it isn't talking to the real hub. If the
hub sysop tells you they reinstalled the hub, delete doorhub_known_hosts
and restart the connector.


4. INSTALLING THE CONNECTOR ON LINUX
------------------------------------
These steps use /sbbs/doorhub and assume the BBS runs as the user
"sbbs". Use your own folder and BBS account.

  sudo mkdir /sbbs/doorhub
  sudo cp doorhub-connector doorhub-connector.ini /sbbs/doorhub/
  sudo chown -R sbbs: /sbbs/doorhub
  sudo chmod 700 /sbbs/doorhub
  sudo chmod 600 /sbbs/doorhub/doorhub-connector.ini

Try it in the foreground first:

  sudo -u sbbs /sbbs/doorhub/doorhub-connector /sbbs/doorhub/doorhub-connector.ini

You should see "listening on 127.0.0.1:9998". Press Ctrl+C to stop it.

Run it as a service. Edit doorhub-connector.service (from the package)
so User, Group and the paths match your system, then:

  sudo cp doorhub-connector.service /etc/systemd/system/
  sudo systemctl daemon-reload
  sudo systemctl enable --now doorhub-connector
  systemctl status doorhub-connector

The log is /sbbs/doorhub/doorhub-connector.log (set in the unit file).


5. INSTALLING THE CONNECTOR ON WINDOWS
--------------------------------------
  1. Make a folder, for example C:\sbbs\doorhub, and copy
     doorhub-connector.exe and doorhub-connector.ini into it.
  2. Try it: open a Command Prompt in that folder and run
         doorhub-connector.exe
     It reads doorhub-connector.ini from its own folder. You should see
     "listening on 127.0.0.1:9998". Windows Firewall may ask about the
     program: it only needs outgoing access, so you can leave incoming
     blocked. Press Ctrl+C to stop it.
  3. Install it as a Windows service, so it starts with Windows. Open a
     Command Prompt as Administrator, in the same folder:
         doorhub-connector.exe service install
         doorhub-connector.exe service start
     The service is called "Door Hub Connector" (DoorHubConnector) and
     restarts itself if it stops. Its log is doorhub-connector.log next
     to the ini. To use a different ini:
         doorhub-connector.exe service install C:\path\to\file.ini
  4. To stop or remove it:
         doorhub-connector.exe service stop
         doorhub-connector.exe service remove


6. SYNCHRONET: ADDING THE HUB TO YOUR DOORS MENU
------------------------------------------------
Copy doorhub.js into your Synchronet mods folder (/sbbs/mods or
C:\sbbs\mods). It works like doorparty.js: it opens an RLogin connection
to the connector with the caller's alias and a password it makes for
each caller and keeps in their user properties.

If your connector is not on localhost:9998, add this to ctrl/modopts.ini:

  [doorhub]
  tunnel_host = localhost
  tunnel_port = 9998

Then in SCFG:

  External Programs > Online Programs (Doors) > choose a section > add:

  Name                       Door Hub Games
  Internal Code              DOORHUB
  Start-up Directory         (blank)
  Command Line               ?doorhub.js
  Multiple Concurrent Users  Yes
  BBS Drop File Type         None
  Native Executable/Script   No (it's JavaScript)

That entry shows the hub's game menu. To send callers straight into one
game, add the game's code after the script name. Ask the hub for its
list of codes; the Kalgoorlie Door Hub has:

  ?doorhub.js lord      Legend of the Red Dragon
  ?doorhub.js reach     Ember Reach
  ?doorhub.js seal      The Broken Seal
  ?doorhub.js wake      The Long Wake

Tip: while testing, set the entry's Access Requirements to SYSOP so only
you see it. Clear it when you're ready for callers.

Synchronet reads SCFG changes when nobody is online. If the new entry
doesn't appear, log off and back on.


7. MYSTIC AND OTHER BBS PROGRAMS
--------------------------------
Any BBS that can make an outgoing RLogin connection can use the
connector. The connector expects the RLogin fields in the order
Synchronet and SyncTERM use:

  client user name   = the caller's hub password (any fixed string per
                       caller; it must stay the same for that caller)
  server user name   = the caller's name (the connector adds [TAG])
  terminal type      = the game code, or blank for the hub menu

Mystic (not yet tested with Door Hub). Add a menu item with the command
IR (outbound RLogin) and data like:

  /addr=127.0.0.1 /port=9998 /user=@USER@ /pass=hubpass /term=lord

Mystic sends the password first, which is the order the connector
expects. Use /term= with a game code, or leave it out for the hub menu.
With a fixed /pass every caller has the same hub password, which is fine:
the hub only uses it to check that a returning name is the same person
from your board.

Other software. If your BBS can run a Linux command for a door, the
system rlogin program can be used, the same way DoorParty's Mystic
script does it:

  rlogin -p 9998 -l "CallerName" localhost

That form sends no game code, so the caller gets the hub menu.


8. TESTING
----------
  1. Check the connector is running and listening:
       Linux:   ss -ltn | grep 9998
       Windows: netstat -an | findstr 9998
  2. Log on to your BBS and pick the hub entry. You should see
     "Connecting to the Door Hub, please wait ..." and then the hub menu
     or the game.
  3. The connector log shows each session:
       [KAL]Heisenberg connected to hub, door: "lord"
       [KAL]Heisenberg disconnected


9. YOUR PLAYERS
---------------
  - On the hub your callers are [TAG]Name, for example [KAL]Heisenberg.
    On the hub's own BBS, which the games see, they appear as
    "Heisenberg (KAL)", because Synchronet doesn't allow names starting
    with [.
  - Names may be up to 30 characters and may not contain [ or ].
  - The first time a caller connects, the hub remembers their password
    (made by doorhub.js). If a different password arrives later for the
    same name, the hub refuses it, so a new caller who takes an old name
    on your board can't play as the old caller. If you rebuild your user
    base, ask the hub sysop to reset the affected players.
  - The hub may limit how many of your callers play at once (10 by
    default). Extra callers see a "try later" message.


10. RUNNING MORE THAN ONE HUB, AND DOORPARTY
--------------------------------------------
Each hub needs its own connector, with its own ini, folder, service name
and local_port. On Windows the service name is fixed, so for a second
hub run the second connector some other way (for example from a
scheduled task at start-up), or ask for a future version.

Door Hub and DoorParty don't share anything. Keep DoorParty's connector
on its port (usually 9999) and Door Hub's on another (9998).


11. TROUBLESHOOTING
-------------------
"Sorry, the Door Hub can't be reached right now"
    The connector couldn't log in to the hub. Its log says why:
    - "connection refused" / "i/o timeout": wrong ssh_host or ssh_port,
      the hub is down, or a firewall blocks outgoing port 2022.
    - "unable to authenticate": wrong ssh_username or ssh_password, or
      the hub has disabled your BBS.
    - "hub key ... has CHANGED": see section 3.

Nothing happens / "Connecting to the Door Hub" then back to the BBS
    The connector isn't running, or isn't on the port doorhub.js uses.
    Check section 8 and the [doorhub] options in modopts.ini.

"Your BBS is not allowed on the Door Hub at the moment"
    The hub sysop has disabled your BBS. Contact them.

"Your Door Hub password doesn't match"
    See section 9. The hub sysop can reset the player.

"This connection is not allowed (wrong system tag)"
    system_tag in your ini doesn't match your hub account.

"That game is closed at the moment"
    The hub has closed that game. The caller gets the hub menu instead.

The game screen looks wrong
    Hub games expect an ANSI terminal, 80 columns by 24 or 25 lines.


12. LEAVING A HUB
-----------------
Stop and remove the connector (systemctl disable --now
doorhub-connector, or doorhub-connector.exe service remove), delete its
folder and doorhub.js, remove the SCFG entry, and let the hub sysop know
so they can remove your account.
