Xon/Xoff State Control for Telnet Com Port Control Option
draft-edwards-telnet-xon-xoff-state-control-00

Internet Draft                                             Grant Edwards
<draft-edwards-telnet-xon-xoff-state-control-00.txt>        Comtrol Corp
Intended status: Experimental                             March 23, 2010
Expires September 23, 2010

       Xon/Xoff State Control for Telnet Com Port Control Option
          <draft-edwards-telnet-xon-xoff-state-control-00.txt>

Status of this Memo

   Distribution of this memo is unlimited.

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on September 23, 2010.

   Comments are solicited and should be addressed to the author.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.

Edwards                Expires September 23, 2010               [Page 1]
Internet Draft     Telnet Xon/Xoff Flow State Control     March 23, 2010

Abstract

   This document defines new values for use with the telnet com port
   control option's SET-CONTROL sub-command defined in RFC2217.  These
   new values provide a mechanism for the telnet client to control and
   query the outbound Xon/Xoff flow control state of the telnet server's
   physical serial port.  This capability is exposed in the serial port
   API on some operating systems and is needed by telnet clients that
   implement a port-redirector service which provides applications local
   to the redirector/telnet-client with transparent access to the remote
   serial port on the telnet server.

1.  Introduction

   When a telnet server acting as a serial device server (as shown in
   the figure below and also described in [RFC2217]) is configured to
   use Xon/Xoff outbound flow control, it maintains an internal state
   variable that reflects whether or not it is currently allowed to
   transmit data via the physical serial port.  When the telnet server
   receives an XOFF character via the physical serial port, the server
   will stop transmitting data via the physical serial port until an XON
   character is received via the physical serial port.

        +-----------+   telnet/RFC2217
        |  telnet   |   connection          physical
        |  client   +----+                / serial port
        |           |    |               /
        +-----------+    |              /
                         |             /
                    +----+----------+ /
                    |               |/    RS-232      +----------+
                    |   telnet     ++      with       |  serial  |
                    |   server     |+-----------------+  device  |
                    |              ++    Xon/Xoff     |          |
                    |               |      flow       +----------+
                    +---------------+     control

   This memo extends that behavior by defining new telnet com port
   control option [RFC2217] SET-CONTROL subcommand values that allow the
   telnet client to force the server to behave as if an XOFF or XON
   character has been received via the physical serial port.

   This extension is needed by telnet clients that implement a port-
   redirection service in order to provide other local applications
   access to the remote serial port (physically located on the telnet
   server) via the same serial port API that is used to access local
   serial ports.  Since some operating systems provide in the serial
   port API a mechanism to control the state of the outbound Xon/Xoff
   flow control, the telnet com port control option is extended to

Edwards                Expires September 23, 2010               [Page 2]
Internet Draft     Telnet Xon/Xoff Flow State Control     March 23, 2010

   provide a corresponding mechanism.

   This ability to control the internal state of the Xon/Xoff flow
   control feature is not provided by [RFC1372] "Telnet Remote Flow
   Control Option" which provides a way to enable and disable the
   Xon/Xoff flow control feature itself rather than to control the state
   of the feature after it has been enabled.

2.  Sub-command Value Definition

   New values are defined for use in the SET_CONTROL sub-command which
   is defined in section 3 of RFC2217 and reproduced here for
   convenience:

      IAC SB COM-PORT-OPTION SET-CONTROL <value> IAC SE

   This document defines new values for the <value> field as follows:

           Value      Command

             20       REQUEST-Xon/Xoff-STATE
             21       SET-XOFF-STATE
             22       SET-XON-STATE

   If Xon/Xoff outbound flow control is not enabled, then the sub-
   commands defined above will not affect data transmission in any way,
   and the flow state returned by the server is undefined.

3.  General Discussion

   The Xon/Xoff flow state is defined to have two states: "XON" and
   "XOFF".

   The server will only transmit data via the physical serial port when
   the flow state is XON. Transmission of data via the physical serial
   port by the server is disabled when in the XOFF state.

   The flow state is initially XON when a session is initiated.

   During normal operation the state is set to XOFF when the server
   receives an XOFF character via the physical serial port (tx data is
   halted).  Conversely, when an XON character is received, the state is
   set to XON (tx data resumes).

   When the telnet client sends the SET-XOFF-STATE command, the telnet
   server will set the state to XOFF and stop sending data via the
   physical serial port until either an XON character is received via
   the physical serial port or the SET-XON-STATE command is received
   from the telnet client.

   Likewise, if the server has received an XOFF character via the

Edwards                Expires September 23, 2010               [Page 3]
Internet Draft     Telnet Xon/Xoff Flow State Control     March 23, 2010

   physical serial port, data transmission via the physical serial port
   will be halted until either an XON character is received via the
   physical serial port or the SET-XON-STATE command is received from
   the telnet client.

   This is summarized in the table below:

               Event             Flow State     Tx Data
            --------------       ----------     ------------

            rx XOFF char            XOFF        Halted

            SET-XOFF-STATE cmd      XOFF        Halted

            rx XON char             XON         Allowed

            SET-XON-STATE cmd       XON         Allowed

   This document describes only the server internal state that governs
   transmission of data via the physical serial port by the telnet
   server.  It does not address the operation of the flow control
   mechanism that governs the stream of data being received on the
   physical serial port by the server.

   The responses to all three of the newly defined sub-command values
   will reflect the flow control state after execution of the command.
   Examples are shown below (byte values are in decimal).  "Cmd" is
   client->server and "Rsp" is server->client:

   Query Xon/Xoff State:

   Cmd: IAC SB COM-PORT-OPTION SET-CONTROL REQUEST-Xon/Xoff-STATE IAC SE
        255 250      44            5                 20          255 240

   Rsp: IAC SB COM-PORT-OPTION SET-CONTROL SET-X[ON|OFF]-STATE IAC SE
        255 250      44           105             [21/22]*     255 240

         *Value in response is 21 if state is XOFF (tx suspended)
          and is 22 if state is XON (tx allowed).

   Set XOFF state (stops tx data):

   Cmd: IAC SB COM-PORT-OPTION SET-CONTROL SET-XOFF-STATE IAC SE
        255 250      44            5             21       255 240

   Rsp: IAC SB COM-PORT-OPTION SET-CONTROL SET-XOFF-STATE IAC SE
        255 250      44           105            21       255 240

   Set XON state (starts tx data):

Edwards                Expires September 23, 2010               [Page 4]
Internet Draft     Telnet Xon/Xoff Flow State Control     March 23, 2010

   Cmd: IAC SB COM-PORT-OPTION SET-CONTROL SET-XON-STATE IAC SE
        255 250      44            5            22       255 240

   Rsp: IAC SB COM-PORT-OPTION SET-CONTROL SET-XON-STATE IAC SE
        255 250      44           105           22       255 240

4.  Usage by Redirectors

   It is intended that MS Windows com-port redirector software will
   issue a SET-XOFF-STATE command to the telnet device server when the
   user application calls EscapeCommFunction(handle,SETXOFF) on the
   virtual COM port, and will issue a SET-XON-STATE command to the
   server when the user application calls
   EscapeCommFunction(handle,SETXON) on the virtual COM port.

   The two EscapeCommFunction() calls shown above do not directly affect
   flow of data between the redirector (telnet client) and the device
   server (telnet server).

   The control of data flow between the telnet client and telnet server
   is defined by section 5 of RFC2217.  Xon/Xoff flow control and the
   corresponding EscapeCommFunction() calls affect flow of data between
   physical serial port on the device server and the external serial
   device to which it is attached.

   However, the Xon/Xoff flow state may indirectly affect data flow
   between client and server if Xon/Xoff flow state changes cause
   internal buffers to fill/drain to a point that triggers flow control
   actions as defined in RFC2217 section 5.

   Likewise, the flow-control commands defined in section 5 of RFC2217
   have no direct effect on flow of data between the device server's
   physical serial port and the external serial device to which it is
   connected.

5.  Security Considerations

   There are no security considerations relevant to this document.

6.  IANA Considerations

   No actions are required from IANA as result of the publication of
   this document.

7.  References

7.1.  Normative References

   [RFC2217]  Clark, G., "Telnet Com Port Control Option", RFC 2217,
              October 1997.

Edwards                Expires September 23, 2010               [Page 5]
Internet Draft     Telnet Xon/Xoff Flow State Control     March 23, 2010

7.2.  Informative References

   [RFC1372]  Hedrick, C. and D. Borman, "Telnet Remote Flow Control
              Option", RFC 1372, October 1992.

Author's Address

   Grant Edwards
   Comtrol Corporation
   Minneapolis, Minnesota USA

   Email:  grant.edwards@comtrol.com
   URL:    www.comtrol.com

Edwards                Expires September 23, 2010               [Page 6]