AmendHub

Download

jcs

/

subtext

/

GUIDE

 

(View History)

jcs   GUIDE: Wrap line, add section on running Subtext at startup Latest amendment: 295 on 2022-11-30

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