Download
jcs
/subtext
/GUIDE
(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 <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. |