home *** CD-ROM | disk | FTP | other *** search
/ kermit.columbia.edu / kermit.columbia.edu.tar / kermit.columbia.edu / sredird / old / README < prev    next >
Text File  |  2003-07-08  |  13KB  |  322 lines

  1. sredird: RFC 2217 compliant serial port redirector
  2. Version 2.2.0, 09 July 2003
  3. Copyright (C) 1999-2003 InfoTecna s.r.l.
  4. Copyright (C) 2001, 2002 Trustees of Columbia University
  5. in the City of New York
  6.  
  7. 1 - Disclaimer
  8.  
  9. This program is free software; you can redistribute it and/or modify it
  10. under the terms of the GNU General Public License as published by the
  11. Free Software Foundation; either version 2 of the License, or (at your
  12. option) any later version.
  13.  
  14. This program is distributed in the hope that it will be useful, but
  15. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  16. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17. for more details.
  18.  
  19. You should have received a copy of the GNU General Public License along
  20. with this program; if not, write to the Free Software Foundation, Inc.,
  21. 675 Mass Ave, Cambridge, MA 02139, USA.
  22.  
  23. To contact the authors:
  24.  
  25.   Denis Sbragion
  26.   InfoTecna
  27.   Tel, Fax: +39 0362 805396
  28.   URL: http://www.infotecna.it
  29.   E-Mail: d.sbragion@infotecna.it
  30.  
  31.   Jeffrey Altman
  32.   Columbia University
  33.   URL:  http://www.columbia.edu/kermit/
  34.   E-mail: kermit-support@columbia.edu
  35.  
  36.  
  37. 2 - Introduction
  38.  
  39. Sredird is a serial port redirector that is compliant with the RFC 2217
  40. "Telnet Com Port Control Option" protocol. This protocol lets you share
  41. a serial port through the network. RFC 2217 was orginally implemented
  42. in Cisco Terminal Servers in IOS version 11.x.
  43.  
  44. RFC 2217 clients include:
  45.  
  46.  . C-Kermit 8.0 for Unix,VMS,QNX,... 
  47.    <http://www.columbia.edu/kermit/ckermit.html>
  48.  
  49.  . DialOut/IP V2, a commercial Windows 95/98/NT client. 
  50.    <www.tacticalsoftware.com>
  51.  
  52. Information on RFC 2217 and the Telnet Protocol is available at www.ietf.org.
  53.  
  54. 3 - Compilation
  55.  
  56. Just compile the sredird.c file with your favorite compiler and your
  57. favorite optimizations options. Under Linux a line like:
  58.  
  59. gcc -O3 -m486 -pipe -fomit-frame-pointer
  60.  
  61. should do the job. Rename the output (usually a.out) to sredird.
  62. You can also try the supplied Makefile. Check it for compiler option
  63. before running the make command.
  64.  
  65. 4 - Command line parameters
  66.  
  67. Sredird takes three mandatory parameters and two optional parameters, 
  68. one at the beginning and one at the end of the command line.
  69.  
  70. The mandatory parameters are:
  71.  
  72. Log level: 0 to 7, 0 being no log and 7 being debug log. Sredird uses
  73. the standard syslog facility for logging. Look at the syslog(3) man page
  74. for further information on the syslog facility and log levels.
  75.  
  76. Device: the device complete path. Something like /dev/ttyS0 or /dev/modem.
  77.  
  78. Lock file: the file to use for inter-application locking. This must
  79. match the one used by other applications, usually something like
  80. /var/lock/LCK..ttyS0 or /var/lock/LCK..modem for the devices considered
  81. above. Sredird supports only HDB style (i.e. ASCII) file locking.
  82.  
  83. The optional parameters are:
  84.  
  85. - At the beginning of the command line:
  86.  
  87. A -i option enables compatibility with the Cisco IOS wich has a small
  88. bug in the handling of the inbound flow control.
  89.  
  90. - At the end of the command line:
  91.  
  92. Poll interval: sredird checks for line state changes (DSR/CTS/DCD/RNG)
  93. on every single char sent on the serial line. To prevent losing state
  94. change when there's no traffic on the serial port, sredird also polls
  95. the line state when there's no traffic on the line for more than the
  96. poll interval. The value is in milliseconds and the default is 100
  97. milliseconds. Setting it to 0 disables the polling feature. This is
  98. also the maximum time data is left in the output buffer before sending
  99. it, even if the buffer isn't completely full, so the polling interval
  100. globally sets the maximum latency of any sredird action.
  101.  
  102. 5 - Installation
  103.  
  104. Put the executable in a suitable directory (/usr/sbin or /usr/local/sbin).
  105. Sredird is designed to run under inetd control. The line in the inetd
  106. configuration file (usually /etc/inetd.conf) should look like this:
  107.  
  108. sredir          stream  tcp     nowait  root    /usr/sbin/tcpd /usr/sbin/sredird -i 5 /dev/modem /var/lock/LCK..modem
  109.  
  110. Of course, "sredir" should be defined in the services file (usually
  111. /etc/services, usual values start at port 7000) and "/dev/modem" should
  112. be substituted by the appropriate device. The lock and the device name
  113. must match for correct interlocking with other programs. The tcpd program
  114. is the usual tcp wrapper that's not needed for correct operation but
  115. is useful for security purposes. Don't forget to send a SIGHUP to the
  116. inetd daemon in order to force reload of the configuration file. The
  117. initial -i paramater is optional and enables compatibility with the
  118. Cisco IOS.
  119.  
  120. 6 - Bugs
  121.  
  122. Patches, bug reports, comments, improvements and anything else are welcome.
  123.  
  124. 7 - Outstanding issues
  125.  
  126. The RFC 2217 protocol is a rather complete protocol that provides a lot
  127. of features. Most of them are implemented in sredird but some seldom
  128. used options are missing:
  129.  
  130.  . does not properly check implement BREAK handling.  Need to figure
  131.    out how to turn a BREAK on and then off based upon receipt of 
  132.    COM-PORT Subnegotiations
  133.  
  134.  . does not properly use select to handle input, output and
  135.    errors on all devices.
  136.  
  137.  . Lack of login processing
  138.  
  139.  . Lack of Telnet START_TLS to protect the data stream
  140.  
  141.  . Lack of Telnet AUTHENTICATION
  142.  
  143.  . LineState processing is not implemented
  144.  
  145.  . The code probably won't compile on most versions of Unix due to the
  146.    highly platform dependent nature of the serial apis.
  147.    The program has been tested only under Linux 2.0.36, gcc 2.7.2.1,
  148.    libc5 and RedHat 5.2/7.1 but should work on any POSIX compliant 
  149.    operating system.
  150.  
  151.  . Use of polling to notify change on the serial control lines is not
  152.    desireable.  Anyone know of an event driven mechanism for discovering
  153.    modem and line signal changes?
  154.  
  155.  . Better documentation and a man page would be useful.
  156.  
  157. 8 - Implementation Notes
  158.  
  159.  . Setting the port to 1.5 stop bits isn't supported. When requested,
  160.    1 stop bit is set and returned as the response value.
  161.  
  162.  . Setting the parity to mark or space isn't supported.  When requested,
  163.    Parity is set to None and returned as the response value.
  164.  
  165.  . DTR, DSR and DCD flow control isn't supported.  When requested, 
  166.    flow control is disabled and "no flow control" is returned as the
  167.    response value.
  168.  
  169.  . RFC 2217 supports the ability for the Input and Output Parity and
  170.    Flow control settings to be independent of each other.  This is not
  171.    supported by the majority of serial port UARTs available on the market
  172.    and is not supported by sredird.  Sredird ignores all requests to set
  173.    the Input Parity and Flow control.  The Output values are used for 
  174.    both input and output as specified in the RFC.
  175.  
  176.  . DialOut/IP V2 version 2.0.0 has a known bug that prevent it from 
  177.    running at 115200 baud. If you ask for 115200 baud it sets the serial
  178.    line at 9600 baud. It also has some other small bugs that cause it to
  179.    crash or fail under some rare circumstances. Use Version 2.0.2 or 
  180.    higher to avoid this problem.
  181.  
  182. 9 - Credits
  183.  
  184. Thanks to David Yon and Mike Krueger of Tactical Software for their help
  185. in the sredird developing process. Thanks also to Tactical Software for
  186. its wonderful DialOut/IP package and for choosing an open standard for it.
  187. Tactical Software provides also some other useful communication tools
  188. and an RFC 2217 compliant server for the Windows environment. Browse
  189. http://www.tacticalsoftware.com for more information.
  190.  
  191. Nordic Messaging Tech. AB provides a complete commercial RFC 2217
  192. compliant server for various operating systems including Linux. See
  193. http://www.nordicmessaging.com for more information.
  194.  
  195. Implementation of the Telnet State Machines, corrections to RFC 2217,
  196. testing against various clients and comparison to hardware implementations
  197. in Cisco IOS software was performed by the Kermit Project at Columbia 
  198. University.  The Kermit Project provides the only known client implementation
  199. of RFC 2217 for Unix in its C-Kermit and Kermit 95 Telnet clients.  See
  200. http://www.columbia.edu/kermit/ for further details.
  201.  
  202. Thanks to Mario Viara for fixing some long lasting small bugs.
  203.  
  204. Thanks to Russell Coker for providing a man page, a better makefile and
  205. some other small patches. 
  206.  
  207. 10 - Commercial support
  208.  
  209. InfoTecna (http://www.infotecna.it) is a commercial company and
  210. provides commercial support for the sredird package. Sorry, but we really
  211. have no time to provide free support apart for bug correction.
  212.  
  213. The Kermit Project provides support for C-Kermit and will provide support
  214. for sredird when used in conjunction with Kermit software.
  215.  
  216. 11 - History
  217.  
  218. 01 June 1999 - Version 1.0.0: First stable release.
  219.  
  220. 02 June 1999 - Version 1.0.1: Corrected a bug on the stop size detection
  221. function. Corrections and exstensions to the documentation. Added credits
  222. to Tactical Software and Nordic Messaging.
  223.  
  224. 07 June 1999 - Version 1.1.0: Added errno.h to the list of the
  225. include files.  Thanks to Federico Bianchi (f.bianchi@arte.unipi.it)
  226. for this. Added an internal buffering scheme, along with handling of the
  227. RFC 2217 FLOWCONTROL-SUSPEND and FLOWCONTROL-RESUME, to reduce network
  228. latency caused by TCP and socket buffering. Added also some socket options
  229. to further reduce network latency. Fixed a bug on the polling feature.
  230.  
  231. 09 June 1999 - Version 1.1.3: Added an output buffer scheme that provides
  232. both low latency, depending on the polling interval, and reasonable cpu
  233. consumption without limiting the global throughput. Some other minor
  234. bug fixing.
  235.  
  236. 11 June 1999 - Version 1.1.4: Fixed compilation under SCO OpenServer
  237. and SCO like distributions (Red Hat). Thanks to Anthony Veale
  238. (aveale@hotmail.com) and Harri Vartiainen (harriv@sci.fi) for reporting
  239. the problem and testing the fixed version. Fixed some other minor bugs.
  240.  
  241. 18 June 1999 - Version 1.1.5: SCO support abandoned. Providing SCO
  242. support would require huge changes to the code. Minor cosmetic and
  243. documentation changes.
  244.  
  245. 04 September 1999 - Version 1.1.6: Corrected an important bug where 
  246. bytes directed to the socket were sent to the modem, then read back
  247. through the modem device and finally sent to the socket macking things
  248. apparently working. Many thanks to Ayman Akt (ayman@uniware.com.au)
  249. from UniWare (www.uniware.com.au) for discovering this nasty bug.
  250.  
  251. 20 September 1999 - Version 1.1.7: Improved handling of the clocal 
  252. tty flag.
  253.  
  254. 09 November 2000 - Version 1.1.8: Corrected a bug in the telnet option
  255. negotiation code. Many options were always incorrectly negotiated as
  256. TN_TRANSMIT_BINARY. Thanks to David Yon (yon@rfdsoftware.com) for his
  257. bug report. Changed the default speed to 9600 baud instead of 38400 when
  258. an unknown baud rate is asked by the client. Furthermore now SRedird try
  259. to serve anyway when the client refuse the Com Port Control option. Added
  260. a simple makefile. Thanks to Kevin Bertram (kevin@cate.com.au) for
  261. suggesting this improvements and supplying the makefile. Changed e-mail
  262. and web references everywere.
  263.  
  264. 14 January 2002 - Version 2.0.0, fixes the following bugs:
  265.  
  266.  . Cisco IOS returns 0 to the client when INBOUND flow control is SET but
  267.    not supported seperately from OUTBOUND.
  268.   
  269.  . Telnet negotiations are used alter the states of both the client
  270.    and the server.  sredird did not implement a Telnet state machine
  271.    as required by RFC 854.  Version 2.0 adds support for a state
  272.    machine.
  273.  
  274.  . Version 1.1.8 corrected the negotiation of Telnet Binary mode
  275.    (RFC 856).  However, it never implemented it.  This is now 
  276.    corrected.
  277.  
  278.  . Telnet DO ECHO should not be refused.  The modem handles the echoing
  279.    if necessary.
  280.  
  281.  . RFC 2217 allows the server (sredird) to give control over a serial
  282.    port to the client (server in DO mode).  It also allows the client
  283.    to give control over a serial port to the server (server in WILL mode).
  284.    sredird required both modes even though sredird only offers control
  285.    over a serial port.
  286.  
  287.  . sredird did not properly implement flow control.  Buffering was only
  288.    implemented when writing data to the serial port.  Data was not 
  289.    buffered when reading data from the serial port.  This could have
  290.    resulted in inadvertent blocking.  Proper select() driven reads
  291.    and writes are now implemented.
  292.  
  293. 14 November 2002 - Version 2.1.0:
  294.  
  295.  . GetPortFlowControl should return 1 to indicate NO FLOW CONTROL
  296.    instead of 0.
  297.  
  298.  . The Cisco IOS hack should become activated only if set by command-
  299.    line option [-i].
  300.  
  301.  . Changed the order of checks in the EscWriteChar function for slightly
  302.    better performance
  303.  
  304. 09 July 2003 - Versione 2.2.0
  305.  
  306.  . Applied the patch provided by Marco Viaria
  307.  
  308.  . Applied the patch supplied by Russell Coker
  309.  
  310. --
  311.  
  312.   Denis Sbragion
  313.   InfoTecna
  314.   Tel, Fax: +39 0362 805396
  315.   URL: http://www.infotecna.it
  316.   E-Mail: d.sbragion@infotecna.it
  317.  
  318.   Jeffrey Altman
  319.   Columbia University
  320.   URL:  http://www.columbia.edu/kermit/
  321.   E-mail: kermit-support@columbia.edu
  322.