HTTP Server

http.server.api_enabled

Abbreviation

ht s a

Access

get/set

Description

Enable the HTTP Server RESTful API.

See Networking and Security, HTTP Server.

The API is enabled by default, so enabling the HTTP server with http.server.enabled also allows access to the API. To disable HTTP RESTful API calls when the HTTP server is running, set http.server.api_enabled to 0.

Arguments

<1|true|on/0|false|off>

Default

1

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server.rest_api

Get example

> get http.server.api_enabled
1

Set example

> set ht s a 0
Set OK

http.server.auth_title

Abbreviation

ht s h

Access

get/set

Description

Configure the authentication header displayed when a user fails to enter a valid username or password. This sets the title of a web browser's authentication dialog.

Gecko OS sets the variable value in the WWW-Authenticate HTTP header:

WWW-Authenticate: Basic realm=<http.server.auth_title>

This variable should be used with http.server.username and http.server.password.

See Networking and Security, HTTP Server.

Arguments

title

Default

"" (empty)

Properties

• takes effect immediately

Gecko OS Kernel Plugin

• protocols.http.server

Set example

> set http.server.auth_title MyServer
Set OK

Get example

> get http.server.auth_title
MyServer

http.server.cors_origin

Abbreviation

ht s c

Access

get/set

Description

Specifies origins for which the web browser same-origin policy is relaxed.

If <origin> is set to an empty string, then CORS is completely disabled.

For requests without credentials, a value of * acts as a wildcard, allowing any origin to access the resource.

If the value of http.server.cors_origin contains a # character, then the # character is replaced with the last 3 characters of the device's MAC address. This works in conjunction with using the # character in mdns.name.

See HTTP Server RESTful API, CORS.

Arguments

<origin>

Default

"" (empty string). To set the http.server.cors_origin variable to the empty string, supply an argument with two double quotes: ""

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.cors_origin

Set example

> set ht s c *
Set OK

http.server.denied_filename

Abbreviation

ht s d

Access

get/set

Description

Specify the file name of the page to be displayed in the event that the HTTP server denies authentication.

See Networking and Security, HTTP Server.

Arguments

<filename>

Default

webapp/unauthorized.html

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.denied_filename
webapp/unauthorized.html

Set example

> set ht s d access_denied.html
Set OK

http.server.enabled

Abbreviation

ht s e

Access

get/set

Description

Enable the HTTP server.

See Networking and Security, HTTP Server.

Arguments

<1|true|on/0|false|off>

Default

0

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s e
0

Set example

> set ht s e 1
Set OK

http.server.interface

Abbreviation

ht s i

Access

get/set

Description

Specifies the network interface used by the HTTP server.

See Networking and Security, HTTP Server.

Arguments

<default/softap/wlan>

Default

default

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.interface
default

Set example

> set ht s i wlan
Set OK

http.server.keep_alive_enabled

Abbreviation

ht s b

Access

get/set

Description

To avoid the overhead of opening and closing a new HTTP connection for each request, you can keep the HTTP connection open for a series of requests, or for a specified time.

If http.server.keep_alive_enabled is set to 1 and the HTTP request contains the header:

Connection: Keep-Alive

OR the Connection header is NOT in the request, then Gecko OS keeps the HTTP connection opened until it is manually closed by the client or device, or until no requests have been received for a period set by the http.server.keep_alive_timeout variable.

While the HTTP connection is open, the client can send additional REST API requests.

Note: If this feature is enabled AND the following header is added to the HTTP request, then the HTTP connection is closed after the HTTP response is returned.

Connection: Close

See also:

• http.server.keep_alive_timeout

Arguments

<1|true|on/0|false|off>

Default

0

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.keep_alive_enabled
0

Set example

> set ht s b 1
Set OK

http.server.keep_alive_timeout

Abbreviation

ht s j

Access

get/set

Description

The maximum time, in seconds, for which a previously opened HTTP keep-alive connection remains open without any activity. If a keep-alive connection is opened and the client does not send another HTTP request within this timeout, then the server automatically closes the connection.

See also:

• http.server.keep_alive_enabled

Arguments

<seconds>

Range: 0-65535

Default

5*60

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.max_clients
3

Set example

> set ht s m 1
Set OK

http.server.max_clients

Abbreviation

ht s m

Access

get/set

Description

Specifies the maximum number of clients the HTTP server allows to connect.

Restricting connected clients may be necessary to limit memory usage. See Memory.

See Networking and Security, HTTP Server.

Arguments

<clients>

Default

6

Range

1 - 9

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.max_clients
3

Set example

> set ht s m 1
Set OK

http.server.notfound_filename

Abbreviation

ht s n

Access

get/set

Description

Specifies the filename of the web page to be displayed in the event that the HTTP server reports a 404 - not found error. <filename>

See Networking and Security, HTTP Server.

Default

''

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.notfound_filename

Set example

> set ht s n notfound.html
Set OK

http.server.password

Abbreviation

ht s w

Access

get/set

Description

Set the password of the http server. The username MUST be set as well for the http server to start.

See HTTP Server Security and Authorization.

Arguments

<password>

Default

none

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Set example

> set ht s w secretpassword
Set OK

Get example

> get ht s w
secretpassword

http.server.port

Abbreviation

ht s p

Access

get/set

Description

Set the port on which the HTTP server listens.

See Networking and Security, HTTP Server.

Arguments

<listening port>

Default

80

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s p
80

Set example

> set http.server.port 8080
Set OK

http.server.root_filename

Abbreviation

ht s r

Access

get/set

Description

This sets or gets the root file of the HTTP server. If a plain request to http:// is issued, with no url specified, this file is returned.

See Networking and Security, HTTP Server.

Arguments

<filename>

Default

/webapp/index.html

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s r
webapp/index.html

Set example

> set http.server.root_filename /setup/home.html
Set OK

http.server.tls_cert

Abbreviation

ht s l

Access

get/set

Description

The server TLS CA certificate filename.

See Networking and Security, HTTPS Server.

Arguments

<filename>

Default

null

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s c
mycert.pem

Set example

> set ht s c mycert.pem
Set OK

http.server.tls_enabled

Abbreviation

ht s t

Access

get/set

Description

Enable server Transport Level Security (TLS).

See Networking and Security, HTTPS Server.

Arguments

<1|true|on/0|false|off>

Default

0

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s t
0

Set example

> set ht s t 1
Set OK

http.server.tls_key

Abbreviation

ht s k

Access

get/set

Description

The server TLS certificate key filename.

See Networking and Security, HTTPS Server.

Arguments

<filename>

Default

null

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s k
mycert.key

Set example

> set ht s k mycert.key
Set OK

http.server.tls_log_clients

Abbreviation

ht s o

Access

get/set

Description

Enable/disable TLS client logging. http.server.tls_verify_peer must be enabled for this feature.

See http.server.tls_client_log.

See Networking and Security, HTTPS Server.

Arguments

<1|true|on/0|false|off>

where

• 0 or false or off: TLS client logging disabled
• 1 or true or on: TLS client logging enabled

Default

false

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.tls_log_clients
0

Get example

> set http.server.tls_log_clients 1
Set OK

http.server.tls_verify_peer

Abbreviation

ht s v

Access

get/set

Description

When this variable is set, a connecting client must provide a valid TLS certificate that the server validates. The client is disconnected if the provided certifcate is invalid. Note: The http.server.tls_cert variable must be set if using this feature.

See Networking and Security, HTTPS Server.

Arguments

<1|true|on/0|false|off>

where

• 0 or false or off: do not verify
• 1 or true or on: verify with client TLS certificate

Default

0

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get ht s v
0

Set example

> set ht s v 1
Set OK

http.server.username

Abbreviation

ht s u

Access

get/set

Description

Set the username of the http server. The password MUST be set as well for the http server to start.

See HTTP Server Security and Authorization.

Arguments

<username>

Default

null

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.http.server

Get example

> get http.server.username
cyrano

Set example

> set ht s u cyrano
Set OK

http.server.ws_connected_gpio

Abbreviation

ht s x

Access

get/set

Description

The GPIO used to indicate whether a websocket stream is connected. It is asserted when one or more websocket streams are open.

Note: Set to -1 to disable feature and free assigned GPIO.

See also system.oob.gpio.

See Networking and Security, Websocket Server.

Arguments

<gpio #>

Default

-1

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.websocket.server

Get example

> get http.server.ws_connected_gpio
-1

Set example

> set http.server.ws_connected_gpio 9
Set OK
> get gp u
!  # Description
...
#  9 http.server.ws_connected_gpio
...

http.server.ws_data_gpio

Abbreviation

ht s y

Access

get/set

Description

The GPIO used to indicate whether a websocket stream has data available to read. It is asserted when one or more websocket streams have data to be read.

See also system.oob.gpio.

Note: Set to -1 to disable feature and free assigned GPIO.

See Networking and Security, Websocket Server.

Arguments

<gpio #>

Default

-1

Properties

• network_restart to apply change

Gecko OS Kernel Plugin

• protocols.websocket.server

Get example

> get http.server.ws_data_gpio
-1

Set example

> set http.server.ws_data_gpio 9
Set OK
> get gp u
!  # Description
...
#  9 http.server.ws_data_gpio
...