doc: cmd: wget: document lwIP syntax

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@linaro.org>
---
 doc/usage/cmd/wget.rst | 71 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 60 insertions(+), 11 deletions(-)

Hi Jerome

+CC Simon, since he asked for an update on the docs

On Thu, 14 Nov 2024 at 16:20, Jerome Forissier <jerome.forissier@linaro.org>
wrote:

> 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@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.
>
> -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
>  ------------
> --
> 2.40.1
>
>
 Reviewed-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>

On Thu, 14 Nov 2024 at 07:32, Ilias Apalodimas
<ilias.apalodimas@linaro.org> wrote:
>
> Hi Jerome
>
> +CC Simon, since he asked for an update on the docs
>
> On Thu, 14 Nov 2024 at 16:20, Jerome Forissier <jerome.forissier@linaro.org> wrote:
>>
>> 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@linaro.org>
>> ---
>>  doc/usage/cmd/wget.rst | 71 +++++++++++++++++++++++++++++++++++-------
>>  1 file changed, 60 insertions(+), 11 deletions(-)

Reviewed-by: Simon Glass <sjg@chromium.org>

Am 14. November 2024 15:20:04 MEZ schrieb Jerome Forissier <jerome.forissier@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@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
> ------------