| Message ID | 20241114142004.2051240-1-jerome.forissier@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | doc: cmd: wget: document lwIP syntax | expand |
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>
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 ------------
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(-)