INTERNET-DRAFT M. Johnston expires: December, 2003 Intel Corporation June, 2003 TFTP Streaming Definition draft-johnston-tftp-stream-00.txt Status of This Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 Copyright Notice Copyright (C) The Internet Society (2002). All rights reserved. Abstract This document describes a mechanism that can be used by TFTP clients and servers to improve throughput. This is accomplished by having the receiver collect a group (stream) of DATA packets and sending one ACK packet for the received DATA packets. M. Johnston draft-johnston-tftp-mtftp-00.txt [Page 1] Internet Draft TFTP Stream Option June, 2003 Table of Contents Status of This Memo......................................1 Copyright Notice.........................................1 Abstract.................................................1 Table of Contents........................................2 1 Introduction..........................................3 2 Packet Information....................................3 2.1 TFTP OpCodes......................................3 2.2 Read Request (RRQ) and Write Request (WRQ)........4 2.3 Data Packet (DATA)................................4 2.4 Option Acknowledgement Packet (OACK)..............5 2.5 Acknowledgement Packet (ACK)......................6 2.6 Error Packet (ERROR)..............................6 3 Streaming TFTP Client Operation.......................6 3.1 Definition of terms...............................7 3.2 Download (RRQ)....................................7 3.3 Upload (WRQ)......................................9 4 Examples.............................................11 4.1 Server Does Not Have Option Extension Support....11 4.2 Server Does Not Have Streaming Option Support....12 4.3 Server Does Have Streaming Option Support........12 5 Security Considerations..............................13 6 References...........................................13 7 AuthorĘs Address.....................................13 8 Full Copyright Statement.............................13 M. Johnston draft-johnston-tftp-stream-00.txt [Page 2] Internet Draft TFTP Stream Option June, 2003 1 Introduction One of the major strengths of TFTP [1] is its simplicity - it is light weight and easy to implement. Unfortunately, this simplicity hides an inherent weakness: performance. There are two issues that cause major performance problems for TFTP: very large image sizes and asynchronous speed links. Until recently, most images transferred using TFTP were under 100 megabytes in length and even on a 10 megabit per second link it only took a couple of minutes to download these images. Now that some installations are starting to transfer images that approach and even exceed one gigabyte in length, the amount of time spent acknowledging every DATA packet is prohibitive. The acknowledgement delay increases even more on asynchronous speed links that have an arbitrarily reduced upload speed. This document describes a solution to this performance issue without drastically increasing the size or complexity of the TFTP client or server. By allowing a group (stream) of TFTP DATA packets to be acknowledged by one ACK packet, overall transfer times can be cut nearly in half (more than in half for some asynchronous speed links). 2 Packet Information This section describes the TFTP packet types and options used by clients and servers implementing the TFTP streaming mechanism. Detailed information about the packet fields not covered in this document can be found in [1] and [2]. 2.1 TFTP OpCodes Below is the list of commonly used TFTP opcodes as of the writing of this document. RRQ 1 [1] WRQ 2 [1] DATA 3 [1] ACK 4 [1] ERROR 5 [1] OACK 6 [2] DIR 7 [4] M. Johnston draft-johnston-tftp-stream-00.txt [Page 3] Internet Draft TFTP Stream Option June, 2003 2.2 Read Request (RRQ) and Write Request (WRQ) 2-bytes string string string string -------------------------------------------------------------- | OpCode | Filename | 0 | Mode | 0 | Option | 0 | Value | 0 | -------------------------------------------------------------- To initiate a streaming TFTP transfer, the client creates a RRQ/WRQ packet that must include all three streaming option strings: "stream", "pktdelay" and "timeout". Like other TFTP option strings [2] [3] [6], these strings are not case dependent and must be paired with a value string. Legal values for the "stream" value string are integer numbers from "2" to "128", inclusive. This represents the number of DATA packets to be transmitted (streamed) before waiting for an ACK packet. The server may decrease this value in the OACK packet. Legal values for the "pktdelay" value string are from "0" to "10000", inclusive. This represents the number of microseconds to wait before transmitting the next DATA packet in a stream. The server may increase this value in the OACK packet. Legal values for the "timeout" value string are discussed in [2]. Suggested values for streaming client retries are "1", "2" and "3" seconds. After transmitting a RRQ/WRQ packet, the client sets a "timeout" event timer and waits for a reply. If a reply is not received before the timer expires, the client should increase the "timeout" value and try again. The client should abort the session (do not send an ERROR packet) if it receives an ICMP error or a TFTP ERROR packet from the server. The client should terminate the session (send an ERROR packet) if it receives an invalid or unexpected TFTP packet from the server or if does not receive a reply from the server. 2.3 Data Packet (DATA) 2-bytes 2-bytes n-bytes (DATA) ----------------------------- | OpCode | Block# | Data | ----------------------------- M. Johnston draft-johnston-tftp-stream-00.txt [Page 4] Internet Draft TFTP Stream Option June, 2003 If the server does not support TFTP option extensions, does not support the streaming option or determines that the file is not large enough to benefit from streaming, it may respond to the clientĘs RRQ packet with a DATA packet. The client may elect to continue a normal TFTP download, as defined in [1], or terminate the session by sending a 'TFTP option error' ERROR packet [2]. When streaming, the Block# must not roll over to zero. This is an error and the session must be terminated by sending an 'Illegal TFTP operation' ERROR packet [1]. Within a stream of DATA packets, some of the packets may arrive out of sequence or more than once. This is not an error. Clients and servers using TFTP streaming must be prepared for this possibility. Packets that have already been received must be ignored. Streamed DATA packets must not be transmitted until an OACK or ACK packet is received. This is done to keep from flooding the network with large quantities of unwanted DATA packets. If DATA packets are being missed on a fairly regular basis, the network connection may be too unreliable or the 'pktdelay' may be too small. The number of missed DATA packets and streams with missing DATA packets should be kept and the session aborted if it is determined that too many packets are missing. (There are no good metrics on what is too many missed DATA packets at this time. Initial implementations have been tested to abort if 2% of the DATA packets are missing or 5 streams in a row have a missing packet.) 2.4 Option Acknowledgement Packet (OACK) 2-bytes string string ----------------------------------- | OpCode | Option | 0 | Value | 0 | ----------------------------------- If the server does not support the streaming option or determines that the file is not large enough to benefit from streaming, it may respond to the clientĘs RRQ packet with an OACK packet that does not contain the streaming options. The client may elect to continue a normal download or terminate the session by sending a 'TFTP option error' ERROR packet [2]. M. Johnston draft-johnston-tftp-stream-00.txt [Page 5] Internet Draft TFTP Stream Option June, 2003 If the server does decide to use TFTP streaming it must copy the clientĘs option strings verbatim from the RRQ/WRQ packet to the OACK packet, as defined in [2]. The server may adjust the value string contents. 2.5 Acknowledgement Packet (ACK) 2-bytes 2-bytes 2-bytes (ACK) ----------------------------------- | OpCode | Block# | ... | Block# | ----------------------------------- If the server does not support TFTP option extensions or does not support the streaming option, it may respond to the clientĘs WRQ packet with an ACK packet. The client may elect to continue a normal TFTP upload, as defined in [1], or terminate the session by sending a 'TFTP option error' ERROR packet [2]. As in [1] each DATA packet transmitted must be acknowledged. The difference with TFTP streaming is that up to 128 DATA packet acknowledgements may be included in one ACK packet. Note: If TFTP streaming is combined with TFTP big block numbers it is possible for the ACK packet length to exceed 1024 bytes. The Block# from each of the valid received DATA packets is appended to the end of the ACK packet until the expected number of DATA packets has been received or the "pktdelay" timeout has expired. DATA packet Block#s not included in the ACK packet must be resent. The order of the Block#s in the ACK packet is not important. 2.6 Error Packet (ERROR) 2-bytes 2-bytes string ----------------------------------- | OpCode | ErrorCode | Message | 0 | ----------------------------------- No new ErrorCode values are defined in this document. 3 Streaming TFTP Client Operation M. Johnston draft-johnston-tftp-stream-00.txt [Page 6] Internet Draft TFTP Stream Option June, 2003 This section provides a rough outline of the TFTP client operation during TFTP streaming sessions. Refer to [1] and [2] for non-streaming TFTP sessions. 3.1 Definition of terms 3.1.1 Abort End the current TFTP session. Do not send a TFTP ERROR packet. 3.1.2 Terminate End the current TFTP session after sending a TFTP ERROR packet. 3.2 Download (RRQ) Download in this document means to transfer a file from the server to the client. 3.2.1 Start session Assemble and transmit a request packet. Enable the timeout event timer. Wait until an ICMP or TFTP packet is received from the server or until the timeout event timer expires. If the timeout event expired, terminate. Retry request after changing or removing options. If an ICMP or TFTP packet is received, disable the timeout event timer. If an ICMP error is received, abort. If a TFTP ERROR packet is received, abort. If this is a TFTP option ERROR, retry request after changing or removing options. If the first DATA packet (block# == 1) is received, terminate or complete the normal TFTP session [1]. If an OACK packet is received, process it. M. Johnston draft-johnston-tftp-stream-00.txt [Page 7] Internet Draft TFTP Stream Option June, 2003 If any other TFTP packet is received, terminate. Retry request after changing or removing options. 3.2.2 Process OACK packet If there are any invalid options, terminate. Retry request after changing or removing options. If there are no stream options, terminate or complete the normal TFTP session [1]. Assemble an ACK packet for the OACK [2] and send it. 3.2.3 Send ACK packet Transmit the previously assembled ACK packet. If all DATA packets have been received, the session is complete. Enable the timeout event timer. Wait until an ICMP or TFTP packet is received from the server or until the timeout event timer expires. If the timeout event expired, terminate or re-transmit the ACK packet. After an ICMP or TFTP packet is received, disable the timeout event timer. If an ICMP error is received, abort. If an expected TFTP DATA packet is received (beyond or before the current stream), store it and gather the rest of the DATA packets. If an unexpected TFTP DATA packet is received (beyond the current stream), terminate. Retry request after changing or removing options. If a TFTP ERROR packet is received, abort. If any other TFTP packet is received, terminate. 3.2.4 Gather DATA packets Enable the packet delay event timer. M. Johnston draft-johnston-tftp-stream-00.txt [Page 8] Internet Draft TFTP Stream Option June, 2003 Wait until a TFTP packet is received or until the packet delay event expires. If the pktdelay event expired, assemble a new ACK packet for the received DATA packets and send it. Disable the pktdelay event timer after a TFTP packet is received. If an old (already received) TFTP DATA packet is received, ignore it and gather the rest of the DATA packets. If an unexpected TFTP DATA packet (beyond the current stream) is received, terminate. Retry request after changing or removing options. If an expected TFTP DATA packet is received, store it. If the last DATA packet in the stream was received, assemble a new ACK packet and send it. If all of the DATA packets have been received, assemble a new ACK packet and send it. If any other TFTP packet is received, terminate. Retry request after changing or removing options. Continue gathering DATA packets. 3.3 Upload (WRQ) Upload in this document means to transfer a file from the client to the server. 3.3.1 Start session Assemble and transmit a request packet. Enable the timeout event timer. Wait until an ICMP or TFTP packet is received from the server or until the timeout event timer expires. If the timeout event expired, terminate. Retry request after changing or removing options. After an ICMP or TFTP packet is received, disable the timeout event timer. If an ICMP error is received, abort. M. Johnston draft-johnston-tftp-stream-00.txt [Page 9] Internet Draft TFTP Stream Option June, 2003 If a TFTP option error is received, abort. Retry request after changing or removing options. If any other TFTP ERROR packet is received, abort. If the first ACK packet (block# == 0) is received, terminate or complete the normal TFTP session [1]. If an OACK packet is received, process it. If any other TFTP packet is received, terminate. Retry request after changing or removing options. 3.3.2 Process OACK packet If there are any invalid options, terminate. Retry request after changing or removing options. If there are no stream options, terminate or complete the normal TFTP session [1]. Assemble the first DATA stream list and send the DATA packets. 3.3.3 Send DATA packets Assemble and transmit the next stream of DATA packets. Insert correct pktdelay between each pair of DATA packets. While transmitting, check for any incoming ICMP or TFTP packets. If an ICMP error is received, abort. If a TFTP ERROR packet is received, abort. If the previous OACK/ACK is received, ignore it. If an ACK for the current stream is received, stop sending DATA packets and process it. If any other TFTP packet is received, terminate. Retry request after changing or removing options. 3.3.4 Wait for ACK packet Enable the timeout event timer. M. Johnston draft-johnston-tftp-stream-00.txt [Page 10] Internet Draft TFTP Stream Option June, 2003 Wait until an ICMP or TFTP packet is received from the server or until the timeout event timer expires. If the timeout event expired, wait once more for an ACK packet then terminate. Retry request after changing or removing options. After an ICMP or TFTP packet is received, disable the timeout event timer. If an ICMP error is received, abort. If an ACK packet is received, process it. If a TFTP error packet is received, abort. Retry request after changing or removing options. If any other TFTP packet is received, terminate. Retry request after changing or removing options. 3.3.5 Process ACK packet If DATA blocks being acknowledged have not been sent, terminate. Retry request after changing or removing options. Mark acknowledged blocks as sent. Assemble a new DATA stream list and send the DATA packets. 4 Examples 4.1 Server Does Not Have Option Extension Support In this example the client sends a RRQ with the Stream option and the server responds with a DATA packet. The client decides to continue the transfer by responding with ACK packets. client server ----------------------------------------------------------- |1|foofile|0|octet|0|stream|0|4|0|pktdelay|0|500|0| |timeout|0|1|0| --> RRQ <-- |3|1| n octets of data | DATA |4|1| --> ACK <-- |3|2| n octets of data | DATA |4|2| --> ACK <-- |3|3| ACK M. Johnston draft-johnston-tftp-stream-00.txt [Page 11] Internet Draft TFTP Stream Option June, 2003 4.2 Server Does Not Have Streaming Option Support In this example the client sends a RRQ with the Stream option and the server responds with an empty OACK packet. The client decides to continue the transfer by responding with ACK packets. client server ----------------------------------------------------------- |1|foofile|0|octet|0|stream|0|4|0|pktdelay|0|500|0| |timeout|0|1|0| --> RRQ <-- |6| OACK |4|0| --> ACK <-- |3|1| n octets of data | DATA |4|1| --> ACK <-- |3|2| n octets of data | DATA |4|2| --> ACK <-- |3|3| ACK 4.3 Server Does Have Streaming Option Support In this example the client sends a RRQ with the Stream option and the server responds with an OACK packet that contains the Stream option. The client responds to the OACK and the streaming download begins. The client sends one ACK packet for the four preceding DATA packets. client server ----------------------------------------------------------- |1|foofile|0|octet|0|stream|0|4|0|pktdelay|0|500|0| |timeout|0|1|0| --> RRQ <-- |6|stream|0|4|0|pktdelay|0|500|0|timeout|0|1|0| OACK |4|0| --> ACK <-- |3|1| n octets of data | DATA <-- |3|2| n octets of data | DATA <-- |3|3| n octets of data | DATA <-- |3|4| n octets of data | DATA |4|1|2|3|4| --> ACK <-- |3|5| n octets of data | DATA <-- |3|6| n octets of data | DATA <-- |3|7| n octets of data | DATA <-- |3|8| n octets of data | DATA |4|5|6|7|8| --> ACK <-- |3|9| ACK M. Johnston draft-johnston-tftp-stream-00.txt [Page 12] Internet Draft TFTP Stream Option June, 2003 5 Security Considerations The basic TFTP protocol has no security mechanism. This is why it has no rename, delete, or file overwrite capabilities. This document does not add any security to TFTP; however, the specified extensions do not add any additional security risks. 6 References [1] The TFTP Protocol (Revision 2) RFC 783 [2] TFTP Option Extension RFC 2347 [3] TFTP Blocksize Option RFC 2348 [4] Extensible Firmware Interface Specification PXE BaseCode Protocol http://www.intel.com/technology/efi/index.htm [5] Preboot eXecution Environment (PXE) Specification ftp://download.intel.com/labs/manage/wfm/download/pxespec.p df [6] TFTP Timeout Interval and Transfer Size Options RFC 2348 7 AuthorĘs Address Michael Johnston Intel Corporation MS. JF1-239 2111 NE 25th Ave. Hillsboro, OR 97124 Phone: +1 503-264-9703 Email: michael.johnston@intel.com 8 Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. M. Johnston draft-johnston-tftp-stream-00.txt [Page 13] Internet Draft TFTP Stream Option June, 2003 This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY, THE INTERNET ENGINEERING TASK FORCE, THE AUTHOR AND THE AUTHORĘS EMPLOYER DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. M. Johnston draft-johnston-tftp-stream-00.txt [Page 14]