home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / teldr110.lzh / teldor.doc < prev    next >
Text File  |  1996-10-01  |  23KB  |  461 lines
  1. Documentation for Telnet Door version 1.10, the universal interface between an
  2. OS/2 BBS and the Internet.
  3.  
  4.  
  5. INDEX
  6.  
  7. (1.0.0)   Introduction
  8.  
  9. (2.0.0)   Legal Statement (this is commercial software)
  10. (2.1.0)   Disclaimer
  11. (2.2.0)   Trial Usage Conditions
  12. (2.3.0)   My Committment to Future support
  13.  
  14. (3.0.0)   System requirements
  15.  
  16. (4.0.0)   Usage of Telnet Door
  17. (4.1.0)   Help Screen
  18. (4.2.0)   Command Line Parameters and Environment Variables
  19. (4.2.1)   Specifying the Target Address
  20. (4.2.2)   Using a Door Configuration File
  21. (4.2.3)   Passing a Hot File Handle
  22. (4.2.4)   Opening a Serial Port Without a Hot File Handle
  23. (4.2.5)   Limiting User's Online Time
  24. (4.2.6)   Log Files
  25. (4.2.7)   Hostname resolution timeout
  26. (4.2.8)   Options
  27.  
  28. (5.0.0)   Development of Telnet Door
  29. (5.1.0)   Test System
  30. (5.2.0)   Compiler used
  31.  
  32. (6.0.0)   Environment considerations - how to get best performance
  33.  
  34. (7.0.0)   Error Levels
  35.  
  36. (8.0.0)   Applying your registration key
  37.  
  38. (9.0.0)   Registering:
  39.  
  40.  
  41.  
  42.  
  43. (1.0.0)   Introduction
  44.  
  45.   Telnet Door is a program that I initially wrote because I wanted to connect
  46. my BBS to the Internet via a UNIX system.  I wrote this door to enable users
  47. of my system to login to my UNIX system via OS/2s TCP/IP networking, and from
  48. access the Internet from there (once I got a connection).  I soon realised that
  49. many other sysops want to do the same thing, so I decided to release this as
  50. shareware.  Now I am starting work on commercial projects based on this code.
  51.  
  52.  
  53.  
  54. (2.0.0)   Legal Statement (this is commercial software)
  55.  
  56.     If you wish to use this program for more than 30 days from the date you
  57. received it you must register it (see the file TELDOR.REG for details).
  58. Users who register this software will receive free updates to fix bugs.  Also
  59. small new features will be free, however for major new features I may at some
  60. future time request an upgrade fee.
  61.  
  62.  
  63. (2.1.0)   Disclaimer
  64.  
  65.    This product is not guaranteed to do anything other than consume space on
  66. your hard drive.  If by any failure to operate or through operation in an
  67. unexpected fashion it causes you to suffer data, monetary, or other losses then
  68. I will not be held responsible.  However if a bug is reported to me I will do
  69. my best to fix it so that the problem does not happen again.
  70.    Your agreement to this disclaimer and the other legal conditions I impose
  71. are a condition for running any program that forms part of this product.
  72.  
  73.  
  74. (2.2.0)   Trial Usage Conditions
  75.  
  76.    You may use this program for 30 days before registering it.  During that
  77. time you will be limited to either running no more than 2 copies of Telnet Door
  78. concurrantly with a maximum time limit of 45 minutes, or to running 16 copies
  79. with a maximum time limit of 10 minutes for each login.  If you wish to use
  80. the 16 lines with 10 minutes option for the unregistered version of Telnet
  81. Door then you must use the command line option of "UNREGMODE=2".
  82.    After you have exceeded your trial usage period Telnet Door will display
  83. reminder messages to inform you (and the users of your BBS) that it is time
  84. to register.
  85.  
  86.  
  87. (2.3.0)   My Committment to Future support
  88.  
  89.    I intend to support this product as long as it is being used.  I have plans
  90. to implement many new features.  Those new features which are minor
  91. enhancements to the current product will be free to all registered users, and
  92. the same applies with bug fixes.  All major new features will require payment
  93. of upgrade fees.
  94.  
  95.  
  96.  
  97. (3.0.0)   System requirements
  98.  
  99.    This program requires at least OS/2 version 2.0 running IBM's TCP/IP
  100. networking software version 2.0 (I believe that my program is compatible with
  101. FTP software's TCP/IP for OS/2, but I haven't been able to test it).  OS/2 Warp
  102. with it's built-in TCP/IP system is just as good for running this program.
  103. Requirements for RAM and hard drive space are so small that it won't make an
  104. impact on the typical BBS system.
  105.  
  106.  
  107.  
  108. (4.0.0)   Usage of Telnet Door
  109.  
  110.  
  111. (4.1.0)   Help Screen
  112.  
  113.    Here's the help screen which is displayed when you give it incorrect command
  114. line parameters, no command line arguements or run it with the "?" parameter:
  115.  
  116. ------------------------------------------------------------------------------
  117. Registered to Russell Coker of Multi BBS for 16 nodes.
  118. Serial number:1.
  119.  
  120. Usage: teldor [ OPTIONS ] A=host address
  121.  
  122. hostname is in dotted decimal or *domain name* convention
  123.  
  124. Options: h=file handle       file handle of open serial port passed from
  125.                              external program
  126.          c=com port          device name for serial port
  127.          fd=door config file full file and path name for DORINFO1.DEF file
  128.          t=mins              time in minutes that the user may be logged in
  129.          d=filename          debugging file name
  130.          l=filename          logging file name
  131.          o=options           misc on/off options, see manual
  132.  
  133. If multiple hostnames are entered then a menu will be displayed.
  134. Telnet Door VX.XX, copyright 1995 Russell Coker.
  135. ------------------------------------------------------------------------------
  136.  
  137. (4.2.0)   Command Line Parameters and Environment Variables
  138.  
  139.    All command line parameters have the form TOKEN=VALUE, all environment
  140. variables have the form "TELDOR."TOKEN=VALUE where TOKEN is the name of some
  141. data type that Telet Door may require, EG the token "H" is used for a hot file
  142. handle and the value it requires must be a number.  So the command line
  143. parameter "H=3" could be used with the same affect as the environment variable
  144. "TELDOR.H=3".
  145.    If a command line parameter is used for the same token as an environment
  146. variable then the environment variable is ignored.
  147.    Further sections of this document will only refer to "parameters" with the
  148. "H=3" form, the environment variable form of all these works.
  149.  
  150. (4.2.1)   Specifying the Target Address
  151.  
  152.    The way to specify the target address of the telnet connection is via the
  153. "A" token.  For example the commands "teldor A=202.12.87.129" and
  154. "teldor A=snoopy.virtual.net.au" will both connect to my UNIX system.  Addresses
  155. can be specified by either machine names or IP addresses.  If the given address
  156. is an IP address then the program will attempt to find it's name to display to
  157. the user for cosmetic reasons.
  158.    If you wish to connect to the host system using a port other than port 23
  159. or a service other than the LOGIN service then this program allows you to
  160. specify a different port or service.  Ports are numbered from 0 to 32767 and
  161. services are named using the text names.  The way to tell Telnet Door that you
  162. wish to use a particular port or service is to append it to the host name with
  163. a "+" character.  EG to connect to my UNIX system via the FINGER protocol (port
  164. 79) you could use either "teldor A=202.12.87.129+finger" or
  165. "teldor A=202.12.87.129+79".
  166.    NB  These examples all use the internet address of my UNIX box.  If you
  167. actually use this address you should be able to connnect to that system.
  168. However I don't currently have a guest account set up (so you won't be able
  169. to log in).
  170.  
  171. (4.2.2)   Using a Door Configuration File
  172.  
  173.    The "FD" token specifies the fully qualified path name of a DORINFO1.DEF
  174. file which contains all necessary information on the user.  The 'F' stands for
  175. the file name of a settings file, and the 'D' stands for DORINFO1.DEF format.
  176. The "FS" token specifies the fully qualified path name of a DOOR.SYS file which
  177. contains the same information.  These tokens are mutually exclusive.
  178. In future I will support other formats on demand.
  179.    The "COMx" line in the door file is taken to contain the number of the open
  180. OS/2 file handle for the serial port.  So "COM3" does not mean serial port 3
  181. it means file handle 3 which points to a serial port.  If you don't understand
  182. this then read the documentation for Maximus or BinkleyTerm.  I don't agree
  183. with that feature being used in that way, but I know 99% of you have BBSs set
  184. up like that.  The preferred way of passing an open serial port handle is via
  185. the "H=x" command line parameter which overrides the parameter in the door
  186. file (all command line parameters take precedence over door file parameters).
  187.    The graphics option in the door file is taken to indicate whether the
  188. connection should operate in binary mode.  If the BBS user doesn't support
  189. graphics then binary data will not be transmitted to their terminal.  This
  190. means that Zmodem transfers over Telnet Door probably won't work.
  191.  
  192. (4.2.3)   Passing a Hot File Handle
  193.  
  194.    Telnet Door operates best when provided with a "Hot" file handle for a
  195. serial port.  This is when an external program (such as Maximus or
  196. Binkleyterm) has opened the serial port and tells Telnet Door which numbered
  197. file handle it should use.  The number of the file handle bears no great
  198. resemblance to the number of the serial port.  On my system BinkleyTerm has
  199. always given a handle number of 3 for every line (serial ports 1 to 16),
  200. however I can't count on it continuing to use the same number (so I haven't
  201. hard-coded the number 3 in my REXX programs).  If you are running Telnet Door
  202. from Bink or Max then you should use whatever number that program gives you.
  203.    To pass a hot file handle you use the "H" token.  EG "H=3" on the command
  204. line will tell it to use file handle 3.
  205.  
  206. (4.2.4)   Opening a Serial Port Without a Hot File Handle
  207.  
  208.    If you want Telnet Door to open the serial port (EG when called from a DOS
  209. BBS) then use the option "C=COMn" where 'n' is the number of the serial port
  210. to use.  This option will cause Telnet Door to open the serial port and
  211. initialise it before doing anything else.
  212.    NB You generally should not call it that way from an OS/2 BBS package.  The
  213. preferred way is via the "H=handle" parameter.
  214.  
  215. (4.2.5)   Limiting User's Online Time
  216.  
  217.    This program will exit if a user tries to stay online longer than they are
  218. allowed.  It does not hang up on them, it merely tells them that their time
  219. is up and exits.  This allows the BBS software to decide exactly what to do
  220. when someone stays online too long.  The amount of time in minutes that they
  221. are allowed is taken from the command line via the "T=x" parameter, or from
  222. the door file if it's not specified on the command line (NB the doorfile is
  223. strictly optional, if you don't specify a time limit on the command line and
  224. the doorfile isn't being used then they are allowed to stay online forever).
  225. The user is given a warning 5 minutes before their time is due to expire to
  226. give them time to save files etc.
  227.  
  228. (4.2.6)   Log Files
  229.  
  230.     The parameters "D=" and "L=" are for specifying the debugging and logging
  231. file names respectively.  The logging file will store all data sent to the
  232. user on disk and may be useful to a sysop.  The debugging file will only store
  233. information on the state of my program.  The intended usage of the debugging
  234. file is for you to send it to me if you encounter a bug in my program, however
  235. if you feel curious then feel free to try and decipher it.
  236.  
  237. (4.2.7)   Hostname resolution timeout.
  238.  
  239.   I have added support for changing the timeout for looking up host names
  240. using the Domain Name System.  By default TelDor will spend 8 seconds looking
  241. up a host name, but using the "DNS=" parameter you can tell it to spend as
  242. long as you like looking up the host name.  If your name server is on the wrong
  243. end of a slow SLIP link then 8 seconds probably won't be long enough.  This
  244. parameter accepts values between 0 and 65 seconds.
  245.   If given a value of 0 it disables the DNS timeout which means that when the
  246. target address is a numeric address then a host name will not be resolved for
  247. it (TelDor will just connect to the numeric address).  If the taget address is
  248. a host name it will wait as long as it takes for the name to be resolved.
  249.  
  250.  
  251. (4.2.8)   Options
  252.  
  253.    The "O=" command line parameter is used for specifying options to change the
  254. operation of Telnet Door.  It can be used in the following ways:
  255.     "O=C" will turn the local console off.  This is useful for BBS sysops who
  256. don't want to see what the user is doing.  It turns off all local display and
  257. keyboard input.  This will greatly reduce the amount of CPU time used by the
  258. program.
  259.     "O=7" will turn off binary mode.  This is necessary if you wish to login to
  260. an OS/2 system and not have the screen garbled.  In general this option
  261. disables binary mode because some host systems make such feeble attempts at
  262. supporting it.
  263.     "O=8" will force my program to pass binary data in both directions when not
  264. in binary mode!  It should never be necessary to use this feature, but I expect
  265. that there are some telnet servers out there that are buggy and require this.
  266.    "O=L" will tell Telnet Door to consider the serial port a "Lame" port.  This
  267. is useful when using something other than a standard serial port (eg a named
  268. pipe over a network, a serial port that has a badly written device driver, or
  269. some other interface that acts like a serial port but doesn't have the full
  270. capabilities).  It tells TelDor to not try changing serial port settings.  If
  271. Telnet Door doesn't run and you are using non-standard serial drivers then try
  272. using this option.
  273.     If you wish to have all data displayed locally except for BEL characters
  274. then the setting O=Q (for quiet) will cause all beeps to be filtered out from
  275. local display (they will still be sent to the remote user however).  This
  276. option will also enable filtering of some VT100 control sequences which get
  277. interpreted badly by the ANSI parser in OS/2 Warp 3.0.
  278.     You use multiple options in the following way "O=7C" to turn console output
  279. off and to use non-binary mode, or "O=8Q" to force binary transmission and
  280. filter out beeps from local display.
  281.    NB  The options "8" and "7" should be avoided if at all possible.  They
  282. should only be necessary for some buggy Telnet Daemons and you should not need
  283. to ever use them.  I have not seen a system that needs the "8" option, but I
  284. assumed that there would be one so I implemented the feature.  I regularly do
  285. transfers of binary data (including Zmodem file transfers) over Telnet Door
  286. without using the "8" option.  It is theoretically possible that use of the "8"
  287. option where it is not appropriate could cause problems resulting in a loss
  288. of the TELNET connection.
  289.  
  290. (4.2.8)   Registration File
  291.  
  292.    If you want Telnet Door to access registration information from a file on
  293. disk instead of from an INI file, then use the "R=filename" option to tell
  294. it which file name to look for.
  295.  
  296.  
  297.  
  298. (5.0.0)   Development of Telnet Door
  299.  
  300.  
  301. (5.1.0)   Test System
  302.  
  303.    This program is developed and tested on a Pentium System running OS/2 Warp
  304. version 3.00.  It is connected to a Linux system via an Ethernet network.  The
  305. Linux system is running the Slackware Linux Distribution version 2.0.0 with
  306. kernel version 1.1.94.
  307.    Previously this program was tested on target machines running older versions
  308. of Linux (as far back as version 1.0.0) and versions of OS/2 as old as 2.10.
  309. I don't often test on the lower systems any more - if I tested on every system
  310. I would not have any time for development.  So I am not doing as much testing
  311. as I would like and I am relying on the users of this program to report
  312. problems to me.  If you find a bug or a feature that is lacking in this package
  313. then please let me know and I will work on it.  If you have reported a bug or
  314. lack of a feature to me and it has not been fixed within 2 weeks then please
  315. send me a reminder message.  I receive so many messages requesting new features
  316. that youur message might have got forgotten.
  317.  
  318.  
  319. (5.2.0)   Compiler used
  320.  
  321.    This program was compiled with IBM's Cset++ version 2.1 using the OS/2 Warp
  322. 3.0 toolkit and header files and the TCP/IP libraries and header files from
  323. the DevCon CD.
  324.  
  325.  
  326.  
  327. (6.0.0)   Environment considerations - how to get best performance
  328.  
  329.   This program is not particularly susceptible to changes in the CONFIG.SYS
  330. file, it should work fairly well no matter what settings you have in place.
  331. However there are some guidelines that may help you in setting up your system
  332. to get maximum performance.
  333.    If you are running many copies of Telnet Door you generally should not
  334. change the TIMESLICE parameter in CONFIG.SYS in an attempt to improve
  335. performance.  Some people may think that when running many copies of a program
  336. they will get faster user-response time by decreasing the size of a time
  337. slice - this is generally not true and definately not true for this program.
  338. Telnet Door spends most of it's time (99.9%) blocked on IO or sleeping, so
  339. when it is doing something (which will generally be of short duration) it is
  340. better if it is allowed to complete the operation before blocking on IO or
  341. sleeping again.  Otherwise CPU time will be wasted on excessive task switching
  342. and user response may be slowed down as a result.
  343.    If you are running Telnet Door on a system that also runs badly behaved
  344. applications (or DOS and Windows applications which are badly behaved by
  345. definition) then it may be necessary to use the MAXWAIT parameter in your
  346. CONFIG.SYS file to ensure that users of Telnet Door (and other BBS
  347. applications) get keyboard response in a reasonable amount of time.  It may
  348. be necessary to change this value to 2 or 1 to give users of your BBS an
  349. acceptable response time.  This will affect all programs not just Telnet Door
  350. so any setting that works well with your favourite OS/2 BBS package should
  351. work well with Telnet Door.
  352.   When you are running Telnet Door you must ensure that you have enough threads
  353. set in your CONFIG.SYS file.  Telnet Door requires 4 threads for modem
  354. operation when time-limits are enforced, and 2 threads for non-modem
  355. operation without time-limits, so a 16 line BBS could require up to 64 threads
  356. for Telnet Door alone!  Increasing the number of threads for the system has
  357. not been found to lower system performance so I recommend a minimum of 256
  358. threads for a typical BBS system.  More may be required depending on the
  359. number of lines and the amount of networking that is being performed.
  360.  
  361.  
  362.  
  363. (7.0.0)   Error Levels
  364.  
  365.   Telnet door will exit with the following error levels which you may want to
  366. use in batch files etc:
  367.  
  368. 0   Normal exit - no error.
  369.  
  370. 1   Command line error.
  371.  
  372. 2   Carrier loss.
  373.  
  374. 3   Socket error (crash of UNIX host?).
  375.  
  376. 4   Serial port error (connected to wrong serial port or another program is
  377.     interfering with the serial port).
  378.  
  379. 5   Display error - shouldn't happen.
  380.  
  381. 6   Keyboard error - shouldn't happen.
  382.  
  383. 255 Really serious or unplanned error, could be a bug in Telnet Door.  If this
  384.     happens then let me know.
  385.  
  386.  
  387.  
  388. (8.0.0)   Applying your registration key
  389.  
  390.   The program APPLY.EXE is used to apply your registration key file (that you
  391. will receive after registering Telnet Door) to your system.  The command is
  392. simply "APPLY nnnnn.KEY" where "nnnnn" is the serial number of your key.  Do
  393. not delete your key file after running this program as you will need it in
  394. future.  The APPLY program will apply the registration file to your INI files.
  395. If you do not want this data stored in your INI files or if you have problems
  396. with this method then you can use the "R=filename" command line option to tell
  397. Telnet Door the name of a file to open to read the registration data.
  398.    Do not let anyone else receive a copy of your KEY file, distributing a KEY
  399. file is piracy (and it has your name in it so it will be well advertised
  400. piracy too).  If you believe that someone may have stolen a copy of your KEY
  401. file then contact me immidiately and I will cancel it as of the next release
  402. of Telnet Door.
  403.    When I send you your key file it will be in an LHArc archive which has a
  404. name based on your name, that archive will contain a file named nnnnn.KEY where
  405. nnnnn is the serial number of the key.  For example if I was sending myself a
  406. KEY file I would send an LHArc archive named RUSSELL.LZH containing a file
  407. named 1.KEY.
  408.  
  409.  
  410.  
  411. (9.0.0)   Registering:
  412.  
  413.  To register post a cheque or International bank draft, or credit card payment
  414. program to the address listed in TELDOR.REG.  I accept payment by VisaCard,
  415. MasterCard, and BankCard from any country in the world through my agent
  416. Multifunction Computing.  If you pay me by credit card you will see the name
  417. Multifunction Computing on your next bank statement.
  418.   The file TELDOR.REG contains all information necessary to register this
  419. program including pricing information.
  420.  
  421.   The next full release of Telnet Door will require a key file to provide full
  422. functionality.  Make sure you send me your EMAIL address when you register so
  423. I can send you your key.
  424.  
  425.  
  426.    To get the latest version and for technical support you can send EMAIL to
  427. your choice of the following addresses:
  428. rjc@snoopy.virtual.net.au.
  429. Russell Coker @ 3:633/363.0 @ fidonet
  430.  
  431.     Or call my BBS directly on +61-3-739-7145.
  432.  
  433.     You can now login to my BBS via the Internet by using the VMODEM function
  434. that is built into Ray Gwinn's SIO drivers.  Use address multi.apana.org.au
  435. which is IP address 202.12.87.130 with the default VMODEM port.
  436.  
  437.   To get the absolutely latest version FREQ "TELDOR" from 3:633/363@fidonet,
  438. download it from files area OBBS in my BBS as the latest file that matches
  439. "TELDR" (do a locate to find it), or do an anonymous FTP from my Internet
  440. system (snoopy.virtual.net.au).  Also many other sites have copies of my program,
  441. the systems hobbes.nmsu.edu and ftp-os2.cdrom.com get copies soon after release
  442. and they both have Internet links that are thousands of times faster than mine
  443. so you may prefer to FTP from them instead of from me.  But if you are paranoid
  444. about corrupt files or something then feel free to download it from
  445. snoopy.virtual.net.au.  Snoopy is an Internet host that is totally administered
  446. by myself.
  447.    If you wish to logon to my BBS using the Internet (to avoid paying long
  448. distance phone charges if you don't live in the same city or country as me) you
  449. can login to multi.apana.org.au using either the Telnet or Vmodem protocols.
  450.    Also if you experience problems with this product and you are on the
  451. Internet then you can use either snoopy.virtual.net.au or multi.virtual.net.au
  452. as telnet targets for testing.  These are the systems that I use for testing
  453. Telnet Door during development so you can count on these working.
  454.  
  455.    I am currently running a mailing list for UUencoded copies of this program.
  456. This means that people who have Internet EMAIL addresses don't have to do
  457. anything to keep up to date with the very latest versions of my program, they
  458. can just automatically receive copies in their mail account without having to
  459. do anything.  If you are interested in this idea then just send me an EMAIL
  460. message to my Internet address and I'll put you on the list.
  461.