Re: [PATCH rtems-docs v2] TFTPFS: New documentation

[Joel Sherrill]

Thanks for the ping. Sorry I was out of town and didn't get to it until
today.

Verify this was merged correctly and this was it.

Thanks.

--joel

On Thu, Jun 9, 2022 at 8:21 AM Frank Kuehndel <
frank.kuehn...@embedded-brains.de> wrote:

> From: Frank Kühndel 
>
> ---
>  filesystem/index.rst   |   1 +
>  filesystem/trivial_ftp.rst | 564 -
>  2 files changed, 562 insertions(+), 3 deletions(-)
>
> diff --git a/filesystem/index.rst b/filesystem/index.rst
> index f4e2ed6..64a2f1d 100644
> --- a/filesystem/index.rst
> +++ b/filesystem/index.rst
> @@ -9,6 +9,7 @@ RTEMS Filesystem Design Guide (|version|).
>  .. topic:: Copyrights and License
>
>  | |copy| 1988, 2015 On-Line Applications Research Corporation (OAR)
> +| |copy| 2022 embedded brains GmbH (http://www.embedded-brains.de)
>
>  .. include:: ../common/license.rst
>
> diff --git a/filesystem/trivial_ftp.rst b/filesystem/trivial_ftp.rst
> index e43c036..3ef8bba 100644
> --- a/filesystem/trivial_ftp.rst
> +++ b/filesystem/trivial_ftp.rst
> @@ -3,7 +3,565 @@
>  Trivial FTP Client Filesystem
>  *
>
> -This chapter describes the Trivial FTP (TFTP) Client Filesystem.
> +This chapter describes the Trivial File Transfer Protocol (TFTP) Client
> +Filesystem.  TFTP is designed to be an especially simple protocol which
> +uses the User Datagram Protocol (UDP) for data transfer over the Internet.
> +Its purpose is to send a single file between to network nodes (client and
> +server).  A file can be sent in both directions, i.e. a client can either
> +read a file from a server or write a file to the server.
>
> -This chapter should be written after the IMFS chapter is completed and
> describe
> -the implementation of the TFTP.
> +Besides reading or writing a file no other operations are supported.  That
> +is, one cannot seek the file, not append to the end of a file, not open
> +the file for reading and writing at the same time, not list directories,
> +not move files and so on.
> +
> +TFTP is inherent insecure as it does not provide any means for
> +authentication or encryption.  Therefore, it is highly recommended not
> +to employ it on public networks.  Nevertheless, it is still widely used
> +to load software and configuration data during early boot stages over
> +a Local Area Network (LAN).
> +
> +RTEMS TFTP Filesystem Implementation
> +
> +
> +The RTEMS TFTP filesystem implements a TFTP client which can be used
> +through the file system.  With other words, one needs to mount the
> +TFTP filesystem and can afterwards open a file for reading or writing
> +below that mount point.  The content of that file is then effectively
> +read from or written to the remote server.  The RTEMS implementation
> +implements the following features:
> +
> +* `RFC 1350 `_
> +  *The TFTP Protocol (Revision 2)*
> +* `RFC 2347 `_
> +  *TFTP Option Extension*
> +* `RFC 2348 `_
> +  *TFTP Blocksize Option*
> +* `RFC 7440 `_
> +  *TFTP Windowsize Option*
> +
> +Many simple TFTP server do not support options (RFC 2347). Therefore, in
> +case the server rejects the first request with options, the RTEMS client
> +makes automatically a second attempt using only the "classical" RFC 1350.
> +
> +The implementation has the following shortcomings:
> +
> +* IPv6 is not supported (yet).
> +
> +* No congestion control is implemented.
> +
> +  (Congestion is simply expressed a network traffic jam which involves
> +  package loss.)  This implementation would worsen a congestion situation
> +  and squeeze out TCP connections.  If that is a concern in your setup,
> +  it can be prevented by using value `1` as `windowsize` when mounting
> +  the TFTP file system.
> +
> +* One must call ``open()``, ``read()``, ``write()`` and ``close()``
> +  at a good pace.
> +
> +  TFTP is designed to read or write a whole already existing file in
> +  one sweep.  It uses timeouts (of unspecified length) and it does not
> +  know keep-alive messages.  If the client does not respond to the
> +  server in due time, the server sets the connection faulty and drops it.
> +  To avoid this, the user must read or write enough data fast enough.
> +
> +  The point here is, one cannot pause the reading or writing for longer
> +  periods of time.  TFTP cannot be used for example to write log files
> +  where all few seconds a line is written.  Also opening the
> +  file at the beginning of an application and closing it that the end
> +  will certainly lead to a timeout.  As another example, one cannot
> +  read a file by reading one byte per second, this will trigger a
> +  timeout and the server closes the connection.  The opening, reading
> +  or writing and closing must happen in swift consecutive steps.
> +
> +* The transfer mode is 

Re: [PATCH rtems-docs v2] TFTPFS: New documentation

[Frank Kühndel]

ping!

Since this patch was sent in June to the list I will shortly recap the 
context:


* I extended the TFTP file system by block and window size options. 
These patches are already part of RTEMS.


* The patch below is the documentation for it. Version 1 of this patch 
has already been reviewed by Chris, Joel and Sebastian (many thanks 
again) and I fixed all raised issues (see 
https://lists.rtems.org/pipermail/devel/2022-June/071822.html).


* What is missing is an OK for this patch.

For your convenience, I put v2 of the generated filesystem.pdf for 
download at the link shown below. I hope the PDF is more convenient to 
read than the patch itself. Please, remind that only chapter "Trivial 
FTP Client Filesystem" is affected by this patch.


https://share.embedded-brains.de/index.php/s/Qg6aoX7kByxfQLZ

My question is: Do you have more critic or are you OK with v2 of this patch?

Thanks in advance
Frank

On 6/9/22 15:21, Frank Kuehndel wrote:

Subject:
[PATCH rtems-docs v2] TFTPFS: New documentation
From:
Frank Kuehndel 
Date:
6/9/22, 15:21

To:
devel@rtems.org


From: Frank Kühndel

---
  filesystem/index.rst   |   1 +
  filesystem/trivial_ftp.rst | 564 -
  2 files changed, 562 insertions(+), 3 deletions(-)

diff --git a/filesystem/index.rst b/filesystem/index.rst
index f4e2ed6..64a2f1d 100644
--- a/filesystem/index.rst
+++ b/filesystem/index.rst
@@ -9,6 +9,7 @@ RTEMS Filesystem Design Guide (|version|).
  .. topic:: Copyrights and License
  
  ||copy|  1988, 2015 On-Line Applications Research Corporation (OAR)

+||copy|  2022 embedded brains GmbH (http://www.embedded-brains.de)
  
  .. include:: ../common/license.rst
  
diff --git a/filesystem/trivial_ftp.rst b/filesystem/trivial_ftp.rst

index e43c036..3ef8bba 100644
--- a/filesystem/trivial_ftp.rst
+++ b/filesystem/trivial_ftp.rst
@@ -3,7 +3,565 @@
  Trivial FTP Client Filesystem
  *
  
-This chapter describes the Trivial FTP (TFTP) Client Filesystem.

+This chapter describes the Trivial File Transfer Protocol (TFTP) Client
+Filesystem.  TFTP is designed to be an especially simple protocol which
+uses the User Datagram Protocol (UDP) for data transfer over the Internet.
+Its purpose is to send a single file between to network nodes (client and
+server).  A file can be sent in both directions, i.e. a client can either
+read a file from a server or write a file to the server.
  
-This chapter should be written after the IMFS chapter is completed and describe

-the implementation of the TFTP.
+Besides reading or writing a file no other operations are supported.  That
+is, one cannot seek the file, not append to the end of a file, not open
+the file for reading and writing at the same time, not list directories,
+not move files and so on.
+
+TFTP is inherent insecure as it does not provide any means for
+authentication or encryption.  Therefore, it is highly recommended not
+to employ it on public networks.  Nevertheless, it is still widely used
+to load software and configuration data during early boot stages over
+a Local Area Network (LAN).
+
+RTEMS TFTP Filesystem Implementation
+
+
+The RTEMS TFTP filesystem implements a TFTP client which can be used
+through the file system.  With other words, one needs to mount the
+TFTP filesystem and can afterwards open a file for reading or writing
+below that mount point.  The content of that file is then effectively
+read from or written to the remote server.  The RTEMS implementation
+implements the following features:
+
+* `RFC 1350<https://www.rfc-editor.org/rfc/rfc1350.html>`_
+  *The TFTP Protocol (Revision 2)*
+* `RFC 2347<https://www.rfc-editor.org/rfc/rfc2347.html>`_
+*TFTP Option Extension*
+* `RFC 2348<https://www.rfc-editor.org/rfc/rfc2348.html>`_
+*TFTP Blocksize Option*
+* `RFC 7440<https://www.rfc-editor.org/rfc/rfc7440.html>`_
+*TFTP Windowsize Option*
+
+Many simple TFTP server do not support options (RFC 2347). Therefore, in
+case the server rejects the first request with options, the RTEMS client
+makes automatically a second attempt using only the "classical" RFC 1350.
+
+The implementation has the following shortcomings:
+
+* IPv6 is not supported (yet).
+
+* No congestion control is implemented.
+
+  (Congestion is simply expressed a network traffic jam which involves
+  package loss.)  This implementation would worsen a congestion situation
+  and squeeze out TCP connections.  If that is a concern in your setup,
+  it can be prevented by using value `1` as `windowsize` when mounting
+  the TFTP file system.
+
+* One must call ``open()``, ``read()``, ``write()`` and ``close()``
+  at a good pace.
+
+  TFTP is designed to read or write a whole already existing file in
+  one sweep.  It uses timeouts (of unspecified length) and it does not
+  know keep-alive messages.  If the client does not respond to the
+  server in due

[PATCH rtems-docs v2] TFTPFS: New documentation

[Frank Kuehndel]

From: Frank Kühndel 

---
 filesystem/index.rst   |   1 +
 filesystem/trivial_ftp.rst | 564 -
 2 files changed, 562 insertions(+), 3 deletions(-)

diff --git a/filesystem/index.rst b/filesystem/index.rst
index f4e2ed6..64a2f1d 100644
--- a/filesystem/index.rst
+++ b/filesystem/index.rst
@@ -9,6 +9,7 @@ RTEMS Filesystem Design Guide (|version|).
 .. topic:: Copyrights and License
 
 | |copy| 1988, 2015 On-Line Applications Research Corporation (OAR)
+| |copy| 2022 embedded brains GmbH (http://www.embedded-brains.de)
 
 .. include:: ../common/license.rst
 
diff --git a/filesystem/trivial_ftp.rst b/filesystem/trivial_ftp.rst
index e43c036..3ef8bba 100644
--- a/filesystem/trivial_ftp.rst
+++ b/filesystem/trivial_ftp.rst
@@ -3,7 +3,565 @@
 Trivial FTP Client Filesystem
 *
 
-This chapter describes the Trivial FTP (TFTP) Client Filesystem.
+This chapter describes the Trivial File Transfer Protocol (TFTP) Client
+Filesystem.  TFTP is designed to be an especially simple protocol which
+uses the User Datagram Protocol (UDP) for data transfer over the Internet.
+Its purpose is to send a single file between to network nodes (client and
+server).  A file can be sent in both directions, i.e. a client can either
+read a file from a server or write a file to the server.
 
-This chapter should be written after the IMFS chapter is completed and describe
-the implementation of the TFTP.
+Besides reading or writing a file no other operations are supported.  That
+is, one cannot seek the file, not append to the end of a file, not open
+the file for reading and writing at the same time, not list directories,
+not move files and so on.
+
+TFTP is inherent insecure as it does not provide any means for
+authentication or encryption.  Therefore, it is highly recommended not
+to employ it on public networks.  Nevertheless, it is still widely used
+to load software and configuration data during early boot stages over
+a Local Area Network (LAN).
+
+RTEMS TFTP Filesystem Implementation
+
+
+The RTEMS TFTP filesystem implements a TFTP client which can be used
+through the file system.  With other words, one needs to mount the
+TFTP filesystem and can afterwards open a file for reading or writing
+below that mount point.  The content of that file is then effectively
+read from or written to the remote server.  The RTEMS implementation
+implements the following features:
+
+* `RFC 1350 `_
+  *The TFTP Protocol (Revision 2)*
+* `RFC 2347 `_
+  *TFTP Option Extension*
+* `RFC 2348 `_
+  *TFTP Blocksize Option*
+* `RFC 7440 `_
+  *TFTP Windowsize Option*
+
+Many simple TFTP server do not support options (RFC 2347). Therefore, in
+case the server rejects the first request with options, the RTEMS client
+makes automatically a second attempt using only the "classical" RFC 1350.
+
+The implementation has the following shortcomings:
+
+* IPv6 is not supported (yet).
+
+* No congestion control is implemented.
+
+  (Congestion is simply expressed a network traffic jam which involves
+  package loss.)  This implementation would worsen a congestion situation
+  and squeeze out TCP connections.  If that is a concern in your setup,
+  it can be prevented by using value `1` as `windowsize` when mounting
+  the TFTP file system.
+
+* One must call ``open()``, ``read()``, ``write()`` and ``close()``
+  at a good pace.
+
+  TFTP is designed to read or write a whole already existing file in
+  one sweep.  It uses timeouts (of unspecified length) and it does not
+  know keep-alive messages.  If the client does not respond to the
+  server in due time, the server sets the connection faulty and drops it.
+  To avoid this, the user must read or write enough data fast enough.
+
+  The point here is, one cannot pause the reading or writing for longer
+  periods of time.  TFTP cannot be used for example to write log files
+  where all few seconds a line is written.  Also opening the
+  file at the beginning of an application and closing it that the end
+  will certainly lead to a timeout.  As another example, one cannot
+  read a file by reading one byte per second, this will trigger a
+  timeout and the server closes the connection.  The opening, reading
+  or writing and closing must happen in swift consecutive steps.
+
+* The transfer mode is always ``octet``.  The only alternative
+  ``netascii`` cannot be selected.
+
+* Block number roll-over is currently not supported.  Therefore,
+  the maximum file size is limited to max-block-number times blocksize.
+  For RFC 1350 blocksize is would be 65535 * 512 = 32 MB.  For the
+  default blocksize is would be 65535 * 1456 = 90 MB.
+
+* The inherent insecurity of the protocol has already be mentioned but
+  it is worth