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.