| 1 |
Subtext: a multi-user BBS server for Macintosh |
| 2 |
Written by joshua stein <jcs@jcs.org> - http://jcs.org/subtext |
| 3 |
|
| 4 |
Subtext is free software; see the LICENSE file for copyright/licensing. |
| 5 |
|
| 6 |
Introduction |
| 7 |
================================================================== |
| 8 |
Subtext is a multi-user BBS server that is developed and runs on Macintosh |
| 9 |
System 6 and above. It supports dialin access through a serial modem and |
| 10 |
Telnet access through MacTCP. |
| 11 |
|
| 12 |
Features |
| 13 |
================================================================== |
| 14 |
- Multithreaded, multi-user BBS server that runs on System 6+ |
| 15 |
- Telnet support through MacTCP |
| 16 |
- Direct serial modem support (no Communications Toolbox) |
| 17 |
- Integrated ANSI-capable local console |
| 18 |
- Local log window with smart screen blanking |
| 19 |
- Multiple threaded message boards |
| 20 |
- FTN (FidoNet) EchoMail and NetMail support with Binkp hub synching |
| 21 |
- Multi-user interactive chat |
| 22 |
- Private messaging/mail |
| 23 |
- File uploading and downloading with ZMODEM support |
| 24 |
- Secure user password storage with SHA256 |
| 25 |
- View/menu templates with variable expansion |
| 26 |
- Configurable main menu key shortcuts |
| 27 |
- Telnet brute-force IP banning by sending messages to a firewall host |
| 28 |
- Offline IP geolocation database support for connecting telnet IPs |
| 29 |
|
| 30 |
Setup |
| 31 |
================================================================== |
| 32 |
Most of the administration is done through the BBS itself, by logging in as |
| 33 |
a sysop and accessing the sysop menu. BBS settings, file areas, message |
| 34 |
boards, and user accounts can all be modified through this menu. |
| 35 |
|
| 36 |
Editing view tepmlates is done by editing plaintext files in the "views" |
| 37 |
directory created where the BBS database lives. |
| 38 |
|
| 39 |
When first run, Subtext will ask to open an existing BBS database. Clicking |
| 40 |
Cancel will prompt to save a new database. On subsequent runs, Subtext |
| 41 |
will automatically try to open the last database that it successfully opened |
| 42 |
unless the Command key is held down at startup. |
| 43 |
|
| 44 |
When creating a new database, Subtext will create a default sysop user |
| 45 |
with the username "sysop" and password "p4ssw0rd". It will also fill in |
| 46 |
some defaults such as an example BBS name and hostname. |
| 47 |
|
| 48 |
On launch, Subtext will open its logger window and initialize its connection |
| 49 |
methods, which are only the console by default. Clicking the BBS menu and |
| 50 |
then Open Console will open a sysop session. Pressing ! will access the |
| 51 |
Sysop menu, and then S will enter the BBS Settings menu. |
| 52 |
|
| 53 |
To enable dialin access, change the Modem Port setting to 1 for the modem |
| 54 |
port or 2 for the printer port depending on where the modem is connected. |
| 55 |
An appropriate Modem Init String can also be configured, though it should |
| 56 |
*not* be configured for Auto-Answer. The number of rings after which an |
| 57 |
"ATA" is issued can be configured in the settings menu. |
| 58 |
|
| 59 |
To enable Telnet access, set the Telnet Port to anything other than 0, such |
| 60 |
as the standard telnet port of 23. Enabling Telnet requires MacTCP to be |
| 61 |
installed and configured. |
| 62 |
|
| 63 |
View Templates |
| 64 |
================================================================== |
| 65 |
In the "views" directory automatically created where the BBS database |
| 66 |
lives are a number of text files that are used throughout the BBS: |
| 67 |
|
| 68 |
- issue.txt: Pre-login welcome screen ("issue" file) |
| 69 |
- menu.txt: Main menu |
| 70 |
- menu_options.txt: Menu commands, see Main Menu Configuration below |
| 71 |
- no_free_nodes.txt: "No Free Nodes" message shown through telnet |
| 72 |
- page_sysop.txt: Text shown before paging the sysop |
| 73 |
- short_menu.txt: Short menu shown after user has seen the main menu |
| 74 |
- signoff.txt: Session signoff |
| 75 |
- signup.txt: Account signup text |
| 76 |
|
| 77 |
After editing view text files, they must be reloaded through the BBS's |
| 78 |
console menu option, or through the sysop menu when logged in. |
| 79 |
|
| 80 |
Views support expansion of variables, which are put inside {{ and }} |
| 81 |
characters, such as "You are connected to {{node}}." Supported variables: |
| 82 |
|
| 83 |
- {{B}} |
| 84 |
Enable bold attribute if the user's terminal supports ANSI (otherwise |
| 85 |
it prints nothing). |
| 86 |
- {{/B}} |
| 87 |
Resets ANSI attributes (including bold) if the user's terminal supports |
| 88 |
ANSI. |
| 89 |
- {{#}} |
| 90 |
Stops varible expansion for the rest of the template. Useful when |
| 91 |
printing untrusted data (mostly used internally). |
| 92 |
- {{center_XX}} |
| 93 |
Print spaces of length equal to the user's terminal width minus XX, divided |
| 94 |
by two. For example, if the user's terminal is 80 characters wide and the |
| 95 |
variable {{center_50}} is used before a 50-character-wide menu line, 15 |
| 96 |
space characters will be printed. This is useful for centering a menu on |
| 97 |
wide terminals but preventing empty space on narrower terminals. |
| 98 |
- {{logged_in_time}} |
| 99 |
The amount of time the user has been logged in (still usable in |
| 100 |
signoff template), such as "7m20s". |
| 101 |
- {{new_mail}} |
| 102 |
If the user has any new, unread mail messages, the count such as |
| 103 |
"(4 New)". Otherwise it is blank. |
| 104 |
- {{node}} |
| 105 |
The current node, such as "ttyt0". |
| 106 |
- {{phone_number}} |
| 107 |
The system's configured phone number, such as "(312) 555-1212". |
| 108 |
- {{time}} |
| 109 |
The current system time in 24-hour format, such as "23:59". |
| 110 |
- {{timezone}} |
| 111 |
The system's configured "Timezone (Abbrev)". |
| 112 |
- {{username}} |
| 113 |
The currently logged-in user's username, or "guest". |
| 114 |
- {{"string"}} |
| 115 |
Print the literal string "string". This is useful in conditionals. |
| 116 |
|
| 117 |
Variable results can also be truncated or padded to a particular length, |
| 118 |
which can be helpful when creating menus with columns. This is done with |
| 119 |
the pipe character and the length, such as: |
| 120 |
|
| 121 |
{{ username|10 }} |
| 122 |
|
| 123 |
Conditionals are also supported with ternary operators "?" and ":" to print |
| 124 |
something if the condition is true (or non-null), otherwise print something |
| 125 |
else. The following conditionals are supported: |
| 126 |
|
| 127 |
- user |
| 128 |
True if the current user is logged in as a non-guest. |
| 129 |
- sysop |
| 130 |
True if the current user is a sysop. |
| 131 |
|
| 132 |
For example, the following would print one string in menu if the user is |
| 133 |
a sysop, otherwise it prints something else. |
| 134 |
|
| 135 |
{{ sysop ? "Answer sysop page" : "Page the sysop" }} |
| 136 |
|
| 137 |
Or when printing mail for the user: |
| 138 |
|
| 139 |
{{ user ? new_mail : "Guests cannot access mail." }} |
| 140 |
|
| 141 |
Main Menu Configuration |
| 142 |
================================================================== |
| 143 |
In addition to creating a custom menu layout, it may be desirable to change |
| 144 |
the mapping of keys to functions. This can be done by editing the |
| 145 |
menu_options.txt file and then reloading it through the BBS. The mapping is |
| 146 |
one action per line, with the Action, Menu Key, All Keys list, and Label, |
| 147 |
separated by a colon. Blank lines and those starting with # are ignored. |
| 148 |
|
| 149 |
When there is no custom Main Menu view defined, a list of options will be |
| 150 |
programmatically generated by showing all menu options with a Menu Key |
| 151 |
defined with the Menu Key and Label. Options with no Menu Key defined are |
| 152 |
still accessible by any key in the All Keys field, but are not shown. |
| 153 |
|
| 154 |
The default mapping is: |
| 155 |
|
| 156 |
# Action:Menu Key:All Keys:Label |
| 157 |
BOARD_LIST_FTN_AREAS:A:Aa:List FTN Areas |
| 158 |
BOARD_SHOW_FIRST:B:Bb:Message Board |
| 159 |
BOARD_SHOW_1::1:Message Board 1 |
| 160 |
BOARD_SHOW_2::2:Message Board 2 |
| 161 |
BOARD_SHOW_3::3:Message Board 3 |
| 162 |
BOARD_SHOW_4::4:Message Board 4 |
| 163 |
BOARD_SHOW_5::5:Message Board 5 |
| 164 |
BOARD_SHOW_6::6:Message Board 6 |
| 165 |
BOARD_SHOW_7::7:Message Board 7 |
| 166 |
BOARD_SHOW_8::8:Message Board 8 |
| 167 |
BOARD_SHOW_9::9:Message Board 9 |
| 168 |
BOARD_SHOW_10::10:Message Board 10 |
| 169 |
CHAT:C:Cc:Multi-User Chat |
| 170 |
FILES_MENU:F:Ff:File Areas |
| 171 |
GOODBYE:G:GgXx:Goodbye |
| 172 |
RECENT_LOGINS:L:Ll:Recent Logins |
| 173 |
MAIL_COMPOSE:N:Nn:Compose New Mail |
| 174 |
MAIL_MENU:M:Mm:Private Mail {{ user ? new_mail : "" }} |
| 175 |
MOTD:O:Oo:Message Of The Day |
| 176 |
PAGE_SEND_OR_ANSWER:P:Pp:{{ sysop ? "Answer Page" : "Page Sysop" }} |
| 177 |
SETTINGS_OR_SIGNUP:S:Ss:{{ user ? "Settings" : "Signup For Account" }} |
| 178 |
WHOS_ONLINE:W:Ww:Who's Online |
| 179 |
SHOW_MENU:?:?:List Menu Options |
| 180 |
SYSOP_MENU::!:Sysop Menu |
| 181 |
|
| 182 |
FTN (FidoNet) Support |
| 183 |
================================================================== |
| 184 |
Subtext supports FTN EchoMail (distributed message boards) and NetMail |
| 185 |
(relayed mail to a user at another node) by way of a Binkp hub. |
| 186 |
Directly-delivered "CrashMail" is not supported. Subtext has a built-in |
| 187 |
scanner/tosser with limited support for PKZIP archives of FTN packets. |
| 188 |
|
| 189 |
To get started, configure the FTN Hub Binkp hostname, port, and password |
| 190 |
settings. The network name, hub node address (e.g., "21:3/100"), local node |
| 191 |
address, and packet passwords must also be set. This is enough to enable |
| 192 |
NetMail, so users can send mail to a user@XX:X/XXX and have it delivered |
| 193 |
through the hub. Likewise, any incoming NetMail for valid usernames are |
| 194 |
delivered, or bounced to the Sysop. |
| 195 |
|
| 196 |
To enable EchoMail areas, create local boards in the Sysop menu and set the |
| 197 |
"FTN Area Name" field to match each desired area name exactly. Note that |
| 198 |
once a board has its FTN area name set, it cannot be removed later due to |
| 199 |
FTN boards using a different database structure than local, threaded boards. |
| 200 |
|
| 201 |
Once Binkp polling is enabled, Subtext will attempt to login to the Binkp hub |
| 202 |
at the configured interval and retrieve any packets sent from the hub, saving |
| 203 |
them to the "binkp:inbox" directory. After fetching any outstanding files, |
| 204 |
packets in the "binkp:outbox" directory are sent to the hub. |
| 205 |
|
| 206 |
Packets (or PKZIP archives of packets) in the inbox are tossed and NetMail is |
| 207 |
delivered. Any EchoMail packets for areas that match the FTN Area Name set |
| 208 |
in a local board are imported. Packets that cannot be tossed properly are |
| 209 |
moved to the "binkp:bad" directory. If the "FTN Hub Binkp Delete After |
| 210 |
Processing" option is enabled, packets are moved to the "binkp:processed" |
| 211 |
directory upon completion, which can be useful during testing. Otherwise, |
| 212 |
processed packets are deleted. |
| 213 |
|
| 214 |
To minimize latency, the Binkp poller will not start while there are any |
| 215 |
users logged in. This means that NetMail messages sent locally will not be |
| 216 |
sent out right away unless a Sysop manually triggers Binkp polling from the |
| 217 |
Sysop menu. This comes into play when communicating back and forth with |
| 218 |
an FTN AreaFix bot to configure which area messages should be delivered |
| 219 |
through the Binkp hub. |
| 220 |
|
| 221 |
Trusted Host |
| 222 |
================================================================== |
| 223 |
While Subtext can handle direct TCP connections for Telnet, it will likely |
| 224 |
be behind a firewall/trusted host. To limit brute-force login attempts, |
| 225 |
Subtext has a hard-coded list of banned account names that most bots will |
| 226 |
try in rapid succession, such as "root", "admin", etc. When a Telnet client |
| 227 |
tries one of these usernames, Subtext can send a UDP packet to the trusted |
| 228 |
host containing the IP to be banned (in dotted-quad plaintext format, such |
| 229 |
as "192.168.1.1"). The trusted host IP and port can be configured in the |
| 230 |
Sysop menu. If either value is empty/zero, this functionality is disabled. |
| 231 |
Since there is no authentication with this mechanism, ensure the trusted |
| 232 |
host is only listening for UDP packets on the interface facing the Subtext |
| 233 |
server! |
| 234 |
|
| 235 |
Also during Telnet negotiation, if the IP of the connecting client matches |
| 236 |
the trusted host's IP, Subtext will honor the "REMOTE_ADDR" value present |
| 237 |
in the NEWENV variable list and use it as the client's connecting IP address |
| 238 |
in logs. This is useful if the trusted host is acting as a web proxy and can |
| 239 |
pass the IP of the web client through to Subtext over Telnet. |
| 240 |
|
| 241 |
When transferring files to and from a host connecting through the trusted |
| 242 |
host, Subtext will use its custom NoModem protocol instead of ZMODEM. |
| 243 |
This makes it easier to implement file transfers through a web or other |
| 244 |
custom frontend. |
| 245 |
|
| 246 |
IP Geolocation |
| 247 |
================================================================== |
| 248 |
When configured with the path of an appropriate IP geolocation database, |
| 249 |
Subtext will use it to lookup connecting IPs. If a location is found, it will |
| 250 |
be logged to the logger and stored in the session log, which will also make |
| 251 |
it visible from the "who's online" and "recent logins' screens, so users can |
| 252 |
see where other users are connecting from. |
| 253 |
|
| 254 |
The format of this database is specified in the ipdb.c file. Free pre-built |
| 255 |
databases generated from public IP geolocation data can be downloaded |
| 256 |
from the Subtext website. These databases can be quite large (>40MB) and |
| 257 |
may be updated frequently, so they are not distributed with Subtext. |
| 258 |
|
| 259 |
Screen Blanking |
| 260 |
================================================================== |
| 261 |
When running on compact Macs, it is recommended to enable Subtext's |
| 262 |
screen blanking option to prevent the log window from burning into the |
| 263 |
CRT. When the system is idle for a configured amount of time, it will blank |
| 264 |
the entire screen for a configured amount of time, immediately unblanking |
| 265 |
as soon as a new connection comes in, or when a key is pressed or a mouse |
| 266 |
button is clicked. This is better than using a dedicated screen saver which |
| 267 |
will not unblank after a period of time, and may be wasting CPU time |
| 268 |
drawing flying toasters while Subtext needs to process user activity. |
| 269 |
|
| 270 |
Run on Startup (System 6) |
| 271 |
================================================================== |
| 272 |
To run Subtext when your Mac starts up, select the Subtext application in |
| 273 |
Finder, then open the Special -> Set Startup... menu. Under "Upon startup, |
| 274 |
automatically open:" select Subtext. |