Download
jcs
/subtext
/GUIDE
(View History)
jcs GUIDE: Add FTN info | Latest amendment: 449 on 2023-03-26 |
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 | |
29 | Setup |
30 | ================================================================== |
31 | Most of the administration is done through the BBS itself, by logging in as |
32 | a sysop and accessing the sysop menu. BBS settings, file areas, message |
33 | boards, and user accounts can all be modified through this menu. |
34 | |
35 | Editing views must be done from console, as it is easier to work in large |
36 | blocks of text in a Mac window than through telnet. |
37 | |
38 | When first run, Subtext will ask to open an existing BBS database. Clicking |
39 | Cancel will prompt to save a new database. On subsequent runs, Subtext |
40 | will automatically try to open the last database that it successfully opened. |
41 | |
42 | When creating a new database, Subtext will create a default sysop user |
43 | with the username "sysop" and password "p4ssw0rd". It will also fill in |
44 | some defaults such as an example BBS name and hostname. |
45 | |
46 | On launch, Subtext will open its logger window and initialize its connection |
47 | methods, which are only the console by default. Clicking the BBS menu and |
48 | then Open Console will open a sysop session. Pressing ! will access the |
49 | Sysop menu, and then S will enter the BBS Settings menu. |
50 | |
51 | To enable dialin access, change the Modem Port setting to 1 for the modem |
52 | port, or 2 for the printer port depending on where the modem is connected. |
53 | An appropriate Modem Init String can also be configured, though it should |
54 | *not* be configured for Auto-Answer. |
55 | |
56 | To enable Telnet access, set the Telnet Port to anything other than 0, such |
57 | as the standard telnet port of 23. Enabling Telnet requires MacTCP to be |
58 | installed. |
59 | |
60 | View Templates |
61 | ================================================================== |
62 | In the BBS -> Views menu, each view used in the BBS can be edited: |
63 | |
64 | - Pre-Login (Issue) |
65 | - Main Menu |
66 | - Short Menu (shown after user has seen main menu) |
67 | - Account Signup |
68 | - No Free Nodes |
69 | - Session Signoff |
70 | |
71 | Views support expansion of variables, which are put inside {{ and }} |
72 | characters, such as "You are connected to {{node}}." |
73 | |
74 | Supported variables: |
75 | |
76 | - {{B}} |
77 | Enable bold attribute if the user's terminal supports ANSI (otherwise |
78 | it prints nothing). |
79 | - {{/B}} |
80 | Resets ANSI attributes (including bold) if the user's terminal supports |
81 | ANSI. |
82 | - {{#}} |
83 | Stops varible expansion for the rest of the template. Useful when |
84 | printing untrusted data (mostly used internally). |
85 | - {{new_mail}} |
86 | If the user has any new, unread mail messages, the count such as |
87 | "(4 New)". Otherwise it is blank. |
88 | - {{node}} |
89 | The current node, such as "ttyt0". |
90 | - {{phone_number}} |
91 | The system's configured phone number, such as "(312) 555-1212". |
92 | - {{time}} |
93 | The current system time in 24-hour format, such as "23:59". |
94 | - {{timezone}} |
95 | The system's configured "Timezone (Abbrev)". |
96 | - {{username}} |
97 | The currently logged-in user's username, or "guest". |
98 | - {{"string"}} |
99 | Print the literal string "string". This is useful in conditionals. |
100 | |
101 | Variable results can also be truncated or padded to a particular length, |
102 | which can be helpful when creating menus with columns. This is done with |
103 | the pipe character and the length, such as: |
104 | |
105 | {{ username|10 }} |
106 | |
107 | Conditionals are also supported with ternary operators "?" and ":" to print |
108 | something if the condition is true (or non-null), otherwise print something |
109 | else. The following conditionals are supported: |
110 | |
111 | - user |
112 | True if the current user is logged in as a non-guest. |
113 | - sysop |
114 | True if the current user is a sysop. |
115 | |
116 | For example, the following would print one string in menu if the user is |
117 | a sysop, otherwise it prints something else. |
118 | |
119 | {{ sysop ? "Answer sysop page" : "Page the sysop" }} |
120 | |
121 | Or when printing mail for the user: |
122 | |
123 | {{ user ? new_mail : "Guests cannot access mail." }} |
124 | |
125 | Main Menu Configuration |
126 | ================================================================== |
127 | In addition to creating a custom menu layout, it may be desirable to change |
128 | the mapping of keys to functions. This can be done through Edit Menu |
129 | Options. The mapping is one action per line, with the Action, Menu Key, |
130 | All Keys list, and Label, separated by a colon. Blank lines and those starting |
131 | with # are ignored. |
132 | |
133 | When there is no custom Main Menu view defined, a list of options will be |
134 | programmatically generated by showing all menu options with a Menu Key |
135 | defined with the Menu Key and Label. Options with no Menu Key defined are |
136 | still accessible by any key in the All Keys field, but are not shown. |
137 | |
138 | The default mapping is: |
139 | |
140 | # Action:Menu Key:All Keys:Label |
141 | BOARD_LIST_FTN_AREAS:A:Aa:List FTN Areas |
142 | BOARD_SHOW_FIRST:B:Bb:Message Board |
143 | BOARD_SHOW_1::1:Message Board 1 |
144 | BOARD_SHOW_2::2:Message Board 2 |
145 | BOARD_SHOW_3::3:Message Board 3 |
146 | BOARD_SHOW_4::4:Message Board 4 |
147 | BOARD_SHOW_5::5:Message Board 5 |
148 | BOARD_SHOW_6::6:Message Board 6 |
149 | BOARD_SHOW_7::7:Message Board 7 |
150 | BOARD_SHOW_8::8:Message Board 8 |
151 | BOARD_SHOW_9::9:Message Board 9 |
152 | BOARD_SHOW_10::10:Message Board 10 |
153 | CHAT:C:Cc:Multi-User Chat |
154 | FILES_MENU:F:Ff:File Areas |
155 | GOODBYE:G:GgXx:Goodbye |
156 | RECENT_LOGINS:L:Ll:Recent Logins |
157 | MAIL_COMPOSE:N:Nn:Compose New Mail |
158 | MAIL_MENU:M:Mm:Private Mail {{ user ? new_mail : "" }} |
159 | MOTD:O:Oo:Message Of The Day |
160 | PAGE_SEND_OR_ANSWER:P:Pp:{{ sysop ? "Answer Page" : "Page Sysop" }} |
161 | SETTINGS_OR_SIGNUP:S:Ss:{{ user ? "Settings" : "Signup For Account" }} |
162 | WHOS_ONLINE:W:Ww:Who's Online |
163 | SHOW_MENU:?:?:List Menu Options |
164 | SYSOP_MENU::!:Sysop Menu |
165 | |
166 | FTN (FidoNet) Support |
167 | ================================================================== |
168 | Subtext supports FTN EchoMail (distributed message boards) and NetMail |
169 | (relayed mail to a user at another node) by way of a Binkp hub. |
170 | Directly-delivered "CrashMail" is not supported. Subtext has a built-in |
171 | scanner/tosser with limited support for PKZIP archives of FTN packets. |
172 | |
173 | To get started, configure the FTN Hub Binkp hostname, port, and password |
174 | settings. The network name, hub node address (e.g., "21:3/100"), local node |
175 | address, and packet passwords must also be set. This is enough to enable |
176 | NetMail, so users can send mail to a user@XX:X/XXX and have it delivered |
177 | through the hub. Likewise, any incoming NetMail for valid usernames are |
178 | delivered, or bounced to the Sysop. |
179 | |
180 | To enable EchoMail areas, create local boards in the Sysop menu and set the |
181 | "FTN Area Name" field to match each desired area name exactly. Note that |
182 | once a board has its FTN area name set, it cannot be removed later due to |
183 | FTN boards using a different database structure than local, threaded boards. |
184 | |
185 | Once Binkp polling is enabled, Subtext will attempt to login to the Binkp hub |
186 | at the configured interval and retrieve any packets sent from the hub, saving |
187 | them to the "binkp-inbox" directory. After fetching any outstanding files, |
188 | any packets in the "binkp-outbox" directory are sent to the hub. |
189 | |
190 | Packets (or PKZIP archives of packets) in the inbox are tossed and NetMail is |
191 | delivered. Any EchoMail packets for areas that match the FTN Area Name set |
192 | in a local board are imported. |
193 | |
194 | To minimize latency, the Binkp poller will not start while there are any |
195 | users logged in. This means that NetMail messages sent locally will not be |
196 | sent out right away unless a Sysop manually triggers Binkp polling from the |
197 | Sysop menu. This comes into play when communicating back and forth with an |
198 | FTN AreaFix bot to configure which area messages should be delivered through |
199 | the Binkp hub. |
200 | |
201 | |
202 | Trusted Host |
203 | ================================================================== |
204 | While Subtext can handle direct TCP connections for Telnet, it will likely |
205 | be behind a firewall/trusted host. To limit brute-force login attempts, |
206 | Subtext has a hard-coded list of banned account names that most bots will |
207 | try in rapid succession, such as "root", "admin", etc. When a Telnet client |
208 | tries one of these usernames, Subtext can send a UDP packet to the trusted |
209 | host containing the IP to be banned (in dotted-quad plaintext format, such |
210 | as "192.168.1.1"). The trusted host IP and port can be configured in the |
211 | Sysop menu. If either value is empty/zero, this functionality is disabled. |
212 | Since there is no authentication with this mechanism, ensure the trusted |
213 | host is only listening for UDP packets on the interface facing the Subtext |
214 | server! |
215 | |
216 | Also during Telnet negotiation, if the IP of the connecting client matches |
217 | the trusted host's IP, Subtext will honor the "REMOTE_ADDR" value present |
218 | in the NEWENV variable list and use it as the client's connecting IP address |
219 | in logs. This is useful if the trusted host is acting as a web proxy and can |
220 | pass the IP of the web client through to Subtext over Telnet. |
221 | |
222 | Screen Blanking |
223 | ================================================================== |
224 | When running on compact Macs, it is recommended to enable Subtext's |
225 | screen blanking option to prevent the log window from burning into the |
226 | CRT. When the system is idle for a configured amount of time, it will blank |
227 | the entire screen for a configured amount of time, immediately unblanking |
228 | as soon as a new connection comes in, or when a key is pressed or a mouse |
229 | button is clicked. This is better than using a dedicated screen saver which |
230 | will not unblank after a period of time, and may be wasting CPU time |
231 | drawing flying toasters while Subtext needs to process user activity. |
232 | |
233 | Run on Startup (System 6) |
234 | ================================================================== |
235 | To run Subtext when your Mac starts up, select the Subtext application in |
236 | Finder, then open the Special -> Set Startup... menu. Under "Upon startup, |
237 | automatically open:" select Subtext. |