(View History)

jcs   session: Add support for {{center_XX}} template variable Latest amendment: 570 on 2023-11-28

1 Subtext: a multi-user BBS server for Macintosh
2 Written by joshua stein <> -
4 Subtext is free software; see the LICENSE file for copyright/licensing.
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.
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
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.
36 Editing view tepmlates is done by editing plaintext files in the "views"
37 directory created where the BBS database lives.
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.
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.
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.
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.
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.
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:
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
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.
80 Views support expansion of variables, which are put inside {{ and }}
81 characters, such as "You are connected to {{node}}." Supported variables:
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.
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:
121 {{ username|10 }}
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:
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.
132 For example, the following would print one string in menu if the user is
133 a sysop, otherwise it prints something else.
135 {{ sysop ? "Answer sysop page" : "Page the sysop" }}
137 Or when printing mail for the user:
139 {{ user ? new_mail : "Guests cannot access mail." }}
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.
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.
154 The default mapping is:
156 # Action:Menu Key:All Keys:Label
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
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.
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.
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.
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.
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.
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.
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 ""). 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!
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.
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.
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.
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.
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.
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.