====== The connector ======

''doorhub-connector'' runs on each member BBS. It listens on your own machine for RLogin connections from your BBS, adds your system tag to the caller's name and passes the connection to the hub through an SSH tunnel. It keeps one SSH connection to the hub open, shares it between all your callers, checks it every 30 seconds and reconnects by itself if it drops.

===== Settings: doorhub-connector.ini =====

The hub's sysop sends you this file. The setting names are the same as DoorParty's connector:

<code>
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
</code>

  * **local_interface**: keep ''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**: any free port. 9998 sits next to DoorParty's usual 9999.
  * Lines starting with '';'' or ''#'' are comments.
  * Optional: ''known_hosts = path'' changes where the hub's key is remembered.

==== 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:

<code>
Trusting hub key for hub.example.com:2022 (SHA256:dJxkWMLh0S5b...), saved in /sbbs/doorhub/doorhub_known_hosts
</code>

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's sysop says they reinstalled the hub with a new key, delete ''doorhub_known_hosts'' and restart the connector.

===== Linux =====

These steps use ''/sbbs/doorhub'' and assume the BBS runs as the user ''sbbs''. Use your own folder and account.

<code bash>
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
</code>

Try it in the foreground first. You should see ''listening on 127.0.0.1:9998''; press Ctrl+C to stop it.

<code bash>
sudo -u sbbs /sbbs/doorhub/doorhub-connector /sbbs/doorhub/doorhub-connector.ini
</code>

==== Run it as a service ====

The package has ''doorhub-connector.service''. Edit ''User'', ''Group'' and the paths to match your system:

<code ini>
[Unit]
Description=Door Hub Connector for Synchronet
After=network.target sbbs.service

[Service]
Type=simple
User=sbbs
Group=sbbs
WorkingDirectory=/sbbs/doorhub
ExecStart=/sbbs/doorhub/doorhub-connector /sbbs/doorhub/doorhub-connector.ini
Restart=always
RestartSec=10
StandardOutput=append:/sbbs/doorhub/doorhub-connector.log
StandardError=append:/sbbs/doorhub/doorhub-connector.log

[Install]
WantedBy=multi-user.target
</code>

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

The log is ''/sbbs/doorhub/doorhub-connector.log''.

**Updating:** replace the program file (copy the new one beside it and ''mv'' it over the old one), then ''sudo systemctl restart doorhub-connector''.

===== 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:

<code>
doorhub-connector.exe service install
doorhub-connector.exe service start
</code>

The service is called **Door Hub Connector** (''DoorHubConnector''). It starts with Windows and restarts itself if it stops. Its log is ''doorhub-connector.log'' next to the ini. To use an ini somewhere else: ''doorhub-connector.exe service install C:\path\to\file.ini''.

**4.** To stop or remove it:

<code>
doorhub-connector.exe service stop
doorhub-connector.exe service remove
</code>

**Updating:** ''service stop'', replace ''doorhub-connector.exe'', ''service start''.

===== Command line =====

^ Command ^ What it does ^
| ''doorhub-connector'' | Run in this window with ''doorhub-connector.ini'' from the program's folder |
| ''doorhub-connector path/to/file.ini'' | Run with another ini |
| ''doorhub-connector service install [ini]'' | Windows: install the service (Administrator) |
| ''doorhub-connector service start / stop / remove'' | Windows: manage the service |
| ''doorhub-connector version'' | Show the version |
| ''doorhub-connector help'' | Short help |

===== Log messages =====

^ Message ^ Meaning ^
| ''listening on 127.0.0.1:9998, hub ...'' | Started. |
| ''Trusting hub key for ...'' | First contact with the hub; key saved. |
| ''Connected to hub ...'' | SSH tunnel up. |
| ''[KAL]Name connected to hub, door: "lord"'' | A caller went to the hub (the door is blank for the menu). |
| ''[KAL]Name disconnected'' | The caller came back. |
| ''Hub connection closed: ...'' | The tunnel dropped; the next caller reconnects it. |
| ''... could not reach the hub: ...'' | See [[doorhub:troubleshooting|Troubleshooting]]. The caller sees "the Door Hub can't be reached right now". |
| ''hub key for ... has CHANGED - refusing'' | See "The hub's key" above. |