Document the httpd command, the environment variables it uses and sets, and its security implications.
Signed-off-by: Vitaliy Sochnev <[email protected]> --- doc/usage/cmd/httpd.rst | 92 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 doc/usage/cmd/httpd.rst diff --git a/doc/usage/cmd/httpd.rst b/doc/usage/cmd/httpd.rst new file mode 100644 index 000000000..4b765c8fc --- /dev/null +++ b/doc/usage/cmd/httpd.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. index:: + single: httpd (command) + +httpd command +============= + +Synopsis +-------- + +:: + + httpd [loadAddress] + +Description +----------- + +The httpd command acts as a minimal HTTP server and receives the first file +uploaded to it into memory. It lets a host load an image with only a web +browser, e.g. to recover a device. + +loadAddress + memory address where the received file is stored. If not provided, the + address is taken from the *loadaddr* environment variable or the default + image load address. + +Requesting ``/`` returns an upload page with one file selector per upload +target. The targets are listed, separated by spaces, in the *httpd_targets* +environment variable. If the variable is not set, a single target named +*file* is offered. Target names may only contain lower case letters, digits, +``_`` and ``-``; other names are ignored. + +A file is uploaded by sending it as the raw body of a request +``POST /upload/<target>``. Multipart form data is refused, as it would be +stored verbatim. Uploads which do not fit into free memory are refused before +any data is written. The lwIP httpd reads at most nine digits of the +Content-Length header, so files of 1 GB or more cannot be uploaded. + +After a successful upload, the *fileaddr* and *filesize* environment variables +describe the received file and *httpd_target* holds the target name. The +command then returns successfully. It does not boot or write the file itself; +boot scripts decide what to do with each target. An interrupted upload is +discarded and the command keeps listening. + +The command runs until a file has been received or Ctrl-C is pressed. + +Security +-------- + +The server has no authentication and no encryption. Anybody who can reach the +board while the command is running can upload a file, and a boot script may +act on it. Only run the command on a trusted network, typically on explicit +user request such as a button pressed at power-on. + +Example +------- + +In the example the board offers two targets. A FIT image uploaded as +*initramfs* is booted, a file uploaded as *bl2* would be written to flash by +a board specific script. + +:: + + => setenv ipaddr 192.168.1.1 + => setenv netmask 255.255.255.0 + => setenv httpd_targets "initramfs bl2" + => setenv httpd_do_initramfs 'bootm $fileaddr' + => httpd && run httpd_do_$httpd_target + Using ethernet@1fb50000 device + Listening for HTTP uploads on http://192.168.1.1/ + Load address: 0x81800000 + + Receiving 'initramfs' (9437184 bytes) + Loading: ################################################## + Bytes transferred = 9437184 (900000 hex) + ## Loading kernel (any) from FIT Image at 81800000 ... + +Open http://192.168.1.1/ in a browser on a host with an address in the same +subnet, or send the file from the command line: + +:: + + $ curl --data-binary @image.itb \ + -H 'Content-Type: application/octet-stream' \ + http://192.168.1.1/upload/initramfs + +Configuration +------------- + +The command is only available if CONFIG_CMD_HTTPD=y. It requires the lwIP +network stack (CONFIG_NET_LWIP=y) and uses the lwIP httpd application. -- 2.55.0
