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

Platforms

Properties

Gecko OS Plugin

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)

Platforms

Properties

Gecko OS Plugin

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: ""

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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:

Arguments

1|true|on/0|false|off

Default

0

Platforms

Gecko OS Plugin

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:

Arguments

<seconds>

Range: 0-65535

Default

5*60

Platforms

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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.

See Networking and Security, HTTP Server .

Arguments

<filename>

Default

""

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

None

Platforms

Properties

Gecko OS Plugin

Get example 

> get ht s c
mycert.pem

Set example 

> set ht s c mycert.pem
Set OK

http.server.tls_client_log

Abbreviation

ht s g

Access

get

Description

Return list of recently connected clients. Up to 8 clients are logged. When the log contains 8 clients and a new client is added, the oldest client is removed. Requires http.server.tls_log_clients to be enabled.

See Networking and Security, HTTPS Server .

Arguments

None

Default

None

Platforms

Gecko OS Plugin

Get example 

> get http.server.tls_client_log
! # Timestamp     Common Name
# 0 1422233232123 name@email.com
# 1 1422233232123 name2@email.com

Note : The timestamp shows the last time the client issued an HTTP request to the server, as system UTC time in milliseconds.

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

Platforms

Properties

Gecko OS Plugin

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

None

Platforms

Properties

Gecko OS Plugin

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

Default

False

Platforms

Properties

Gecko OS Plugin

Get example 

> get http.server.tls_log_clients
0

Get example 

> set http.server.tls_log_clients 1
Set OK

http.server.tls_peer_cert

Abbreviation

ht s s

Access

get/set

Description

This variable specifies the HTTP server's TLS client certificate chain.

In typical setups, there are two certificate chains:

Use http.server.tls_peer_cert to specify the client chain file, when it is different to the server chain file.

For details of creating certificates and chain files, see the HTTPS Intermediate Certificates example app .

Notes :

If http.server.tls_peer_cert is null then http.server.tls_cert is used for the client certificate chain. This is the legacy behavior.

To use this variable, set the variable http.server.tls_verify_peer to 1 .

Arguments

<cert_filename>

where:

Leave null to use http.server.tls_cert as the client certificate chain. To set the variable to null, set to the empty string:

set http.server.tls_peer_cert ""

Default

<null>

Platforms

Gecko OS Plugin

Example 

set http.server.tls_peer_cert my_client_chain.pem

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 certificate 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

Default

0

Platforms

Properties

Gecko OS Plugin

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

None

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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

Platforms

Properties

Gecko OS Plugin

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
...