README (8484B)
1 tii: a Tcl-based suite for working with ii/IDEC protocol 2 ======================================================== 3 This suite implements the client and server sides of the ii/IDEC protocol of 4 distributed, cross-platform, text-based communication (a FIDOnet successor, so 5 to speak). See ii-doc.txt for the protocol documentation. 6 7 The tii suite requires at least Tcl 8.6 to run. Running it inside starpacks is 8 possible but not recommended. 9 10 It also depends upon SQlite 3.44 and above (3.47 recommended) with the proper 11 Tcl extension enabled for it.. 12 13 The tii distribution consists of the following parts: 14 15 * tiifetch.tcl: the core ii/IDEC message fetching library and CLI utility 16 * tiipost.tcl: the core ii/IDEC message posting library and CLI utility 17 * tiiview.tcl: the CLI viewer of the fetched ii/IDEC messages and conferences 18 * tii.db: the SQLite3 database that contains all messages and echo lists 19 * config.txt: the set of parameters for all HTTP requests by the tii scripts 20 * stations.txt: the list of stations to be auto-fetched by tiifetch when none 21 of its command-line parameters is passed (not included in the repo) 22 * auth.txt: the list of station/authstring mappings to be used by tiipost when 23 posting messages to a particular station (not included in the repo) 24 * tiix.tcl: the GUI ii/IDEC viewer that also leverages tiifetch and tiipost to 25 provide fetching and posting functionality 26 * tiid.tcl: the basic ii/IDEC node software that uses the same DB format 27 * tiid-user.tcl: user management utility for the tiid node 28 29 Readiness status 30 ---------------- 31 * tiifetch.tcl: ready/tested 32 * tiipost.tcl: ready/tested 33 * tiiview.tcl: ready/tested 34 * tii.db (format): ready/tested 35 * config.txt (format/fields): ready/tested 36 * stations.txt (format): ready/tested 37 * auth.txt (format): ready/tested 38 * tiix.tcl: ready/testing 39 * tiid.tcl: ready/testing 40 * tiid-user.tcl: ready/tested 41 * Overall status: basically ready, bugfixing in progress 42 43 Client usage 44 ------------ 45 46 ### Fetching the messages (tiifetch.tcl): ### 47 48 tclsh tiifetch.tcl [station_url] [echos] [dbfile] 49 50 This command will fetch all messages into the dbfile ("tii.db" in the script 51 dir by default) from the station_url (can be empty, see below) based on the 52 echo conference names (can be delimited with slash /, comma (,) or semicolon 53 (;)) and create the corresponding file structure if it's missing. 54 55 Fetching is supported for the following station URL schemes and protocols: 56 57 * HTTP (http://) 58 * HTTPS (https://) 59 * Gopher (gopher://) 60 * Gopher over TLS (gophers://) 61 * Finger (finger://) 62 * Nex (nex://) 63 * Spartan (spartan://) 64 * Gemini (gemini://) 65 66 If the station_url parameter is empty or no parameters are passed at all, 67 tiifetch.tcl will look for a file called stations.txt that lists (each on a 68 new line) all the station URLs to sync from and the amount of IDs that can 69 be fetched from a particular station with a single GET request (this amount 70 can be 12 or more): 71 72 https://url1 389 73 gemini://url2 24 74 http://url3 12 75 76 Messages from all listed stations will be merged into the same echo database. 77 You also can comment out a station to temporarily stop fetching from it by 78 prepending the # sign. 79 80 ### Viewing the messages from CLI (tiiview.tcl): ### 81 82 tclsh tiiview.tcl [echo_name] [filter_string] [line_width] [dbfile] 83 84 If the echo_name parameter is passed, this command will write all formatted 85 messages from the coresponding echo conference to the standard output. 86 You should pipe this message stream to your $PAGER terminal application, like 87 less or most. The messages will be formatted according to the filter_string 88 format (see below). If the filter string is empty or omitted, the messages 89 will appear in the exact order their IDs appear in the echo conference file. 90 91 If the echo_name parameter is empty or no parameters are passed at all, this 92 command will output the list of echo conferences registered in the dbdir. 93 The conference list will be alphabetically ordered and the filter_string will 94 have no effect at all if you pass it. 95 96 If the line_width parameter is omitted, the text reflows to 80 chars per line. 97 98 If the dbfile is omitted, it defaults to "tii.db" in the script directory. 99 100 This component is fully offline and can only work with a compatible message 101 database that tiifetch.tcl can generate. 102 103 The filter string can take one of the following basic forms: 104 105 * [number]: only take [number] messages from the head (start) of the list 106 * r[number]: same but output messages from newest to oldest in the list 107 108 If [number] is 0 then it means no message limit. 109 The reverse operation is always done after limiting the results. 110 111 e.g. r50 will output 50 newest messages in the conference, starting from the 112 most recent one. The default basic value is h0, so no filter applied will mean 113 outputting all messages from the oldest to the newest. 114 115 You can extend the basic form by appending a search regular expression to it, 116 like this: [form]/[regex]. Note that the regex always applies AFTER the basic 117 filtering has been done. Also note that the search is done within all fields 118 of the message. E.g. h100/retro will find the retro-themed messages among the 119 first 100 of them. 120 121 ### Posting the messages from CLI (tiipost.tcl): ### 122 123 echo my_post_text | tiipost.tcl station_root_url echo_name msgto subj [repto] 124 125 The tiipost.tcl script accepts the message body from the standard input. The 126 body must be provided in UTF-8 encoding and all command line parameters except 127 [repto] (reply-to ID) are mandatory. 128 129 The script will look for the auth.txt file in its directory, with the format: 130 131 station_url_1 password1 132 station_url_2 password2 133 ... 134 135 If the station root URL matches one of the lines in auth.txt, it automatically 136 will use the password as the authstring when posting to the station. 137 138 On success, tiipost.tcl will output a message that starts with "Success", in 139 case of an error the line will start with "Error". The server-side description 140 will follow this success or error status. 141 142 As of now, posting is only supported for HTTP/HTTPS station URLs. 143 144 HTTP client configuration 145 ------------------------- 146 For both fetching and posting, you can configure several values in the config 147 file (config.txt in the script directory, the example is included in the repo) 148 that will allow you to set HTTP proxy and override the user agent. As of now, 149 the file is a Tcl dictionary (`key "value"`) and has the following fields: 150 151 * useragent: the user agent string to set for all HTTP requests 152 * proxyhost: the HTTP proxy hostname to use (if empty or omitted, the scripts 153 will connect directly) 154 * proxyport: the HTTP port to use on the proxy (only effective if proxyhost is 155 set to a non-empty string) 156 * net_timeout: the timeout (in milliseconds) for all network requests 157 158 Any of the fields can be omitted, as well as the file itself. 159 You can also use torsocks with any script invocation in order to fully cloak 160 your originating IP address. 161 162 Server usage 163 ------------ 164 This section is in progress. 165 166 ### Starting the tiid server ### 167 168 The tiid.tcl server accepts the following parameters: 169 170 tiid.tcl [port] [nodename] [dbfile] 171 172 where: 173 174 * port (default 8080) is the TCP port to listen to, 175 * nodename (default "tiid") is the unique node name (needed to fill the fields 176 like message originating address), 177 * dbfile (default "tii.db" in the script directory) is your database path. 178 179 The tiid server is compatible with all existing HTTP-based clients and also 180 with the clients that utilize Gopher/Nex transport, like tiifetch/tiix. It has 181 automatic protocol detection, so both HTTP and Gopher/Nex clients can connect 182 to the same port. 183 184 Although the tii client only can post via HTTP, the tiid server also supports 185 direct TCP posting with GET-like queries via Gopher/Nex protocols. 186 187 ### User management on the tiid server ### 188 189 As of now, only manual user management is supported. The simplest way is to 190 use the included tiid-user.tcl script to perform administrative tasks. 191 192 Adding a user or changing its password (auth string): 193 194 tiid-user.tcl dbfile user someusername auth SuperSecretAuth123 acl "*" 195 196 If you don't supply the acl parameter, it will default to "*". 197 198 Changing the list of echos the user can post ("*" means all, "" means none): 199 200 tiid-user.tcl dbfile user someusername acl "echo.1,echo.2..." 201 202 Note that you need to set up ACL every time you change a user's password. 203 204 In both cases, the database file and the user field are mandatory. 205 206 207 Credits 208 ------- 209 Created by Luxferre in 2024, released into public domain with no warranties. 210