| .. _http-server-sample: |
| |
| HTTP Server |
| ########### |
| |
| Overview |
| ******** |
| |
| The HTTP Server sample application for Zephyr implements a basic TCP server |
| on top of the HTTP Server Library that is able to receive HTTP 1.1 requests, |
| parse them and write back the responses. |
| |
| The source code for this sample application can be found at: |
| :file:`samples/net/http_server`. |
| |
| Requirements |
| ************ |
| |
| - Linux machine with wget and the screen terminal emulator |
| - Either QEMU or real device like Freedom Board (FRDM-K64F) |
| - For QEMU see this :ref:`networking_with_qemu` |
| - LAN for testing purposes (Ethernet) |
| |
| |
| Building and Running |
| ******************** |
| |
| Currently, the HTTP Server application is configured to listen at port 80. |
| If you want to modify the http-server sample application, please check |
| the configuration settings in :file:`samples/net/http_server/src/main.c` file |
| and also in the :file:`samples/net/http_server/src/config.h` file. |
| |
| To use QEMU for testing, follow the :ref:`networking_with_qemu` guide. |
| |
| This sample code supports both static and dynamic (DHCPv4) IP addresses that |
| can be defined in the project configuration file: |
| |
| .. code-block:: console |
| |
| CONFIG_NET_APP_MY_IPV6_ADDR="2001:db8::1" |
| CONFIG_NET_APP_MY_IPV4_ADDR="192.0.2.1" |
| |
| Adding URLs |
| =========== |
| |
| To define a new URL or to change how a URL is processed by the HTTP server, |
| open the :file:`samples/net/http_server/src/main.c` file and locate the |
| following lines: |
| |
| .. code-block:: c |
| |
| http_server_add_default(&http_urls, default_handler); |
| http_server_add_url(&http_urls, "/headers", HTTP_URL_STANDARD); |
| http_server_add_url(&http_urls, "/index.html", HTTP_URL_STANDARD); |
| |
| The first line defines how Zephyr will deal with unknown URLs. In this case, |
| it will respond with a soft HTTP 404 status code, i.e. an HTTP 200 OK status |
| code with a 404 Not Found HTML body. |
| |
| To build this sample on your Linux host computer, open a terminal window, |
| locate the source code of this sample application and type: |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: samples/net/http_server |
| :board: qemu_x86 |
| :goals: run |
| :compact: |
| |
| |
| Sample Output |
| ============= |
| |
| Assume in this example that this HTTP server is configured to listen at |
| IPv4 address 192.168.1.120 and IPv6 address 2001:db8::1 port 80. |
| On your Linux host computer, open a terminal window and type: |
| |
| .. code-block:: console |
| |
| wget 192.168.1.120/index.html |
| |
| wget will show: |
| |
| .. code-block:: console |
| |
| --2017-01-17 00:37:44-- http://192.168.1.120/ |
| Connecting to 192.168.1.120:80... connected. |
| HTTP request sent, awaiting response... 200 OK |
| Length: unspecified [text/html] |
| Saving to: 'index.html' |
| |
| The HTML file generated by Zephyr and downloaded by wget is: |
| |
| .. code-block:: html |
| |
| <html> |
| <head> |
| <title>Zephyr HTTP Server</title> |
| </head> |
| <body><h1><center>It Works!</center></h1></body> |
| </html> |
| |
| The screen application will display the following information: |
| |
| .. code-block:: console |
| |
| [http-server] [DBG] http_connected: (0x00403fa0): HTTP connect attempt URL /index.html |
| [http-server] [DBG] http_serve_index_html: (0x00403fa0): Sending index.html (170 bytes) to client |
| [http-server] [DBG] http_closed: (0x00403fa0): Connection 0x004004c0 closed |
| |
| To obtain the HTTP Header Fields web page, use the following command: |
| |
| .. code-block:: console |
| |
| wget 192.168.1.120/headers -O index.html |
| |
| wget will show: |
| |
| .. code-block:: console |
| |
| --2017-01-19 22:09:55-- http://192.168.1.120/headers |
| Connecting to 192.168.1.120:80... connected. |
| HTTP request sent, awaiting response... 200 OK |
| Length: unspecified [text/html] |
| Saving to: 'index.html' |
| |
| This is the HTML file generated by Zephyr and downloaded by wget: |
| |
| .. code-block:: html |
| |
| <html> |
| <head> |
| <title>Zephyr HTTP Server</title> |
| </head> |
| <body> |
| <h1>Zephyr HTTP server</h1> |
| <h2>HTTP Header Fields</h2> |
| <ul> |
| <li>User-Agent: Wget/1.16 (linux-gnu)</li> |
| <li>Accept: */*</li> |
| <li>Host: 192.168.1.120</li> |
| <li>Connection: Keep-Alive</li> |
| </ul> |
| <h2>HTTP Method: GET</h2> |
| <h2>URL: /headers</h2> |
| <h2>Server: arm</h2> |
| </body> |
| </html> |
| |
| To test the 404 Not Found soft error, use the following command: |
| |
| .. code-block:: console |
| |
| wget 192.168.1.120/not_found -O index.html |
| |
| Zephyr will generate an HTTP response with the following header: |
| |
| .. code-block:: console |
| |
| HTTP/1.1 200 OK |
| Content-Type: text/html |
| Transfer-Encoding: chunked |
| |
| and this is the HTML message that wget will save: |
| |
| .. code-block:: html |
| |
| <html> |
| <head> |
| <title>Zephyr HTTP Server</title> |
| </head> |
| <body><h1><center>404 Not Found</center></h1></body> |
| </html> |
| |
| HTTPS Server |
| ============ |
| |
| The sample code also includes a HTTPS (HTTP over TLS) server example |
| running side by side with the HTTP server, this server runs on QEMU. |
| In order to compile and run the code execute: |
| |
| .. zephyr-app-commands:: |
| :zephyr-app: samples/net/http_server |
| :board: qemu_x86 |
| :conf: prj_tls.conf |
| :goals: run |
| :compact: |
| |
| |
| Known Issues and Limitations |
| ============================ |
| |
| - Currently, this sample application only generates HTTP responses in |
| chunk transfer mode. |
