[PATCH] doc: cmd: wget: document lwIP syntax

[Heinrich Schuchardt]

Am 14. November 2024 15:20:04 MEZ schrieb Jerome Forissier <jerome.forissier at linaro.org>:
>The lwIP version of wget supports a different syntax with a URL,
>in addition to the legacy syntax. Document that.
>
>While we're at it, fix a couple of minor issues in the legacy
>syntax:
>- hostIPaddr can be an IP address or a DNS name
>- path is mandatory
>
>Signed-off-by: Jerome Forissier <jerome.forissier at linaro.org>
>---
> doc/usage/cmd/wget.rst | 71 +++++++++++++++++++++++++++++++++++-------
> 1 file changed, 60 insertions(+), 11 deletions(-)
>
>diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst
>index b8ca35bb140..5be01a22e47 100644
>--- a/doc/usage/cmd/wget.rst
>+++ b/doc/usage/cmd/wget.rst
>@@ -11,29 +11,51 @@ Synopsis
> 
> ::
> 
>-    wget address [[hostIPaddr:]path]
>+    wget [address] [host:]path
>+    wget [address] url          # lwIP only
>+
> 
> Description
> -----------
> 
>-The wget command is used to download a file from an HTTP server.
>+The wget command is used to download a file from an HTTP(S) server.
>+In order to use HTTPS you will need to compile wget with lwIP support.
>+
>+Legacy syntax
>+~~~~~~~~~~~~~
>+
>+The legacy syntax is supported with the legacy network stack as well as
>+lwIP. It allows only HTTP.
> 
>-wget command will use HTTP over TCP to download files from an HTTP server.
> By default the destination port is 80 and the source port is pseudo-random.
>-The environment variable *httpdstp* can be used to set the destination port.
>+The environment variable *httpdstp* can be used to set the destination port
>+(legacy nework stack only).
> 
> address
>     memory address for the data downloaded
> 
>-hostIPaddr
>-    IP address of the HTTP server, defaults to the value of environment
>-    variable *serverip*
>+host
>+    IP address or DNS name of the HTTP server, defaults to the value of
>+    environment variable *serverip*.
> 
> path
>     path of the file to be downloaded.
> 
>-Example
>--------
>+
>+New syntax (lwIP only)
>+~~~~~~~~~~~~~~~~~~~~~~
>+
>+In addition to the syntax described above, wget accepts URLs if the network
>+stack is lwIP.
>+
>+address
>+    memory address for the data downloaded
>+
>+url
>+    HTTP or HTTPS URL, that is: http[s]://<host>[:<port>]/<path>.
>+
>+Example with the legacy network stack
>+-------------------------------------
> 
> In the example the following steps are executed:
> 
>@@ -52,13 +74,40 @@ In the example the following steps are executed:
>     HTTP/1.0 302 Found
>     Packets received 4, Transfer Successful
> 
>+Example with lwIP
>+-----------------
>+
>+In the example the following steps are executed:
>+
>+* setup client network address
>+* download a file from the HTTPS server
>+
>+::
>+
>+   => dhcp
>+   DHCP client bound to address 10.0.2.15 (3 ms)
>+   => wget https://download.rockylinux.org/pub/rocky/9/isos/aarch64/Rocky-9.4-aarch64-minimal.iso
>+   ##########################################################################
>+   ##########################################################################
>+   ##########################################################################
>+   [...]
>+   1694892032 bytes transferred in 492181 ms (3.3 MiB/s)
>+   Bytes transferred = 1694892032 (65060000 hex)
>+
> Configuration
> -------------
> 
> The command is only available if CONFIG_CMD_WGET=y.
>+To enable lwIP support set CONFIG_NET_LWIP=y.

DNS support depends on configuration (currently CMD_DNS).

Best regards

Heinrich


> 
>-TCP Selective Acknowledgments can be enabled via CONFIG_PROT_TCP_SACK=y.
>-This will improve the download speed.
>+TCP Selective Acknowledgments in the legacy network stack can be enabled via
>+CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective
>+Acknowledgments are enabled by default with lwIP.
>+
>+**Note**: U-Boot currently has no way to verify certificates for HTTPS.
>+A place to store the root CA certificates is needed, and then MBed TLS would
>+need to walk the entire chain. Therefore, man-in-the middle attacks are
>+possible and HTTPS should not be relied upon for payload authentication.
> 
> Return value
> ------------