sredird: RFC 2217 compliant serial port redirector
Version 1.1.8, 09 November 2000
Copyright (C) 1999, 2000 InfoTecna di Cesana D. & C. s.n.c.

1 - Disclaimer

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

To contact the author:

  Denis Sbragion
  InfoTecna
  Tel, Fax: +39 039 2324054
  URL: http://www.infotecna.it
  E-Mail: d.sbragion@infotecna.it

2 - Introduction

Sredird is a serial port redirector that is compliant with the RFC 2217
"Telnet Com Port Control Option" protocol. This protocol lets you share
a serial port through the network. The only RFC 2217 aware client that
I know of is DialOut/IP V2, which is a Windows 95/98/NT client. For more
information on it look at www.tacticalsoftware.com. Anyone interested in
writing a client and who may need help with the RFC 2217 protocol could
contact me at the address above. Information on RFC 2217 and the Telnet
Protocol is available at www.ietf.org.

3 - Compilation

Just compile the sredird.c file with your favorite compiler and your
favorite optimizations options. Under Linux a line like:

gcc -O3 -m486 -pipe -fomit-frame-pointer

should do the job. Rename the output (usually a.out) to sredird.
You can also try the supplied Makefile. Check it for compiler option
before running the make command.

4 - Command line parameters

Sredird takes three mandatory parameters and one optional parameter.
The mandatory parameters are:

Log level: 0 to 7, 0 being no log and 7 being debug log. Sredird uses
the standard syslog facility for logging. Look at the syslog(3) man page
for further information on the syslog facility and log levels.

Device: the device complete path. Something like /dev/ttyS0 or /dev/modem.

Lock file: the file to use for inter-application locking. This must
match the one used by other applications, usually something like
/var/lock/LCK..ttyS0 or /var/lock/LCK..modem for the devices considered
above. Sredird supports only HDB style (i.e. ASCII) file locking.

The optional parameter is:

Poll interval: sredird checks for line state changes (DSR/CTS/DCD/RNG)
on every single char sent on the serial line. To prevent losing state
change when there's no traffic on the serial port, sredird also polls
the line state when there's no traffic on the line for more than the
poll interval. The value is in milliseconds and the default is 100
milliseconds. Setting it to 0 disables the polling feature. This is
also the maximum time data is left in the output buffer before sending
it, even if the buffer isn't completely full, so the polling interval
globally sets the maximum latency of any sredird action.

5 - Installation

Put the executable in a suitable directory (/usr/sbin or /usr/local/sbin).
Sredird is designed to run under inetd control.  The line in the inetd
configuration file (usually /etc/inetd.conf) should look like this:

sredir stream tcp nowait root /usr/local/libexec/sredird sredird 5 /dev/cuaa0 /var/spool/lock/LCK..cuaa0

Of course, "sredir" should be defined in the services file (usually
/etc/services, usual values start at port 7000) and "/dev/modem" should
be substituted by the appropriate device. The lock and the device name
must match for correct interlocking with other programs. The tcpd program
is the usual tcp wrapper that's not needed for correct operation but
is useful for security purposes. Don't forget to send a SIGHUP to the
inetd daemon in order to force reload of the configuration file.

6 - Bugs

Patches, bug reports, comments, improvements and anything else is welcome.

7 - Final considerations

The RFC 2217 protocol is a rather complete protocol that provides a lot
of features. Most of them are implemented in sredird but some seldom
used options are missing:

- Line state notification supports only the break signal. Also I'm not
sure break handling is performed the right way.

- Setting the port to 1.5 stop bits isn't supported. 1 stop bit is
used instead.

- Setting the parity to mark or space isn't supported. No flow control
is used instead.

- DTR, DSR and DCD flow control isn't supported. No flow control is
used instead.

- Setting hardware (RTS/CTS) flow control on input set it on the output
also.

Furthermore:

- Use of polling to notify change on the serial control lines isn't a
good solution. Anybody with a better solution is invited to send it to me.

- Better documentation and a man page would be useful. Anybody wants to
write it?

- The program has been tested only under Linux 2.0.36, gcc 2.7.2.1,
libc5 and RedHat 5.2 but should work on any POSIX compliant operating
system. Sredird has been tested only with DialOut/IP V2 as client,
so some features not used by DialOut/IP have never been tested at all.

- DialOut/IP V2 version 2.0.0 has a known bug that prevent it from running
at 115200 baud. If you ask for 115200 baud it sets the serial line at 9600
baud. It also has some other small bugs that cause it to crash or fail
under some rare circumstances. Version 2.0.2 works pretty well instead.

- Sredird set the input and output sockets for the lowest latency
(IPTOS_LOWDELAY and TCP_NODELAY). This could cause quite high cpu
consumption under weird load conditions.

8 - English

Forgive my poor English. I'm Italian, and this is the best I can do. Any
correction is welcome despite what the Netiquette says.

9 - Credits

Thanks to David Yon and Mike Krueger of Tactical Software for their help
in the sredird developing process. Thanks also to Tactical Software for
its wonderful DialOut/IP package and for choosing an open standard for it.
Tactical Software provides also some other useful communication tools
and an RFC 2217 compliant server for the Windows environment. Browse
http://www.tacticalsoftware.com for more information.

Nordic Messaging Tech. AB provides a complete commercial RFC 2217
compliant server for various operating systems including Linux. See
http://www.nordicmessaging.com for more information.

10 - Commercial support

InfoTecna (http://www.infotecna.it) is a commercial company and
provides commercial support for the sredird package. Sorry, but we really
have no time to provide free support apart for bug correction.

11 - History

01 June 1999 - Version 1.0.0: First stable release.

02 June 1999 - Version 1.0.1: Corrected a bug on the stop size detection
function. Corrections and exstensions to the documentation. Added credits
to Tactical Software and Nordic Messaging.

07 June 1999 - Version 1.1.0: Added errno.h to the list of the
include files.  Thanks to Federico Bianchi (f.bianchi@arte.unipi.it)
for this. Added an internal buffering scheme, along with handling of the
RFC 2217 FLOWCONTROL-SUSPEND and FLOWCONTROL-RESUME, to reduce network
latency caused by TCP and socket buffering. Added also some socket options
to further reduce network latency. Fixed a bug on the polling feature.

09 June 1999 - Version 1.1.3: Added an output buffer scheme that provides
both low latency, depending on the polling interval, and reasonable cpu
consumption without limiting the global throughput. Some other minor
bug fixing.

11 June 1999 - Version 1.1.4: Fixed compilation under SCO OpenServer
and SCO like distributions (Red Hat). Thanks to Anthony Veale
(aveale@hotmail.com) and Harri Vartiainen (harriv@sci.fi) for reporting
the problem and testing the fixed version. Fixed some other minor bugs.

18 June 1999 - Version 1.1.5: SCO support abandoned. Providing SCO
support would require huge changes to the code. Minor cosmetic and
documentation changes.

04 September 1999 - Version 1.1.6: Corrected an important bug where 
bytes directed to the socket were sent to the modem, then read back
through the modem device and finally sent to the socket macking things
apparently working. Many thanks to Ayman Akt (ayman@uniware.com.au)
from UniWare (www.uniware.com.au) for discovering this nasty bug.

20 September 1999 - Version 1.1.7: Improved handling of the clocal 
tty flag.

09 November 2000 - Version 1.1.8: Corrected a bug in the telnet option
negotiation code. Many options were always incorrectly negotiated as
TN_TRANSMIT_BINARY. Thanks to David Yon (yon@rfdsoftware.com) for his
bug report. Changed the default speed to 9600 baud instead of 38400 when
an unknown baud rate is asked by the client. Furthermore now SRedird try
to serve anyway when the client refuse the Com Port Control option. Added
a simple makefile. Thanks to Kevin Bertram (kevin@cate.com.au) for
suggesting this improvements and supplying the makefile. Changed e-mail
and web references everywere.


--

  Denis Sbragion
  InfoTecna
  Tel, Fax: +39 039 2324054
  URL: http://www.infotecna.it
  E-Mail: d.sbragion@infotecna.it
