Configuring the HTTP Server Group
The http_server group is used to allow an EMS to accept local calls from the machine or device code that may be running in a different process, such as the Lua Script Resource.
 |
If you are connecting from the Lua Script Resource and have changed the host and port properties for the EMS, you must update the config.lua file (in the /microserver/etc directory) and modify the properties, scripts.rap_host and scripts.rap.port.
|
Here is an example of the http_server group. Change the values of the properties to fit your environment; do not use this example as is.
"http_server": {
"host" : "localhost",
"port": 8000,
"ssl": true,
"certificate" : "/path/to/certificate/file",
"private_key" : "/path/to/private/key",
"passphrase" : "password"
"authenticate" : true,
"user" : "johnsmith",
"password" : "some_encrypted_user_password",
"content_read_timeout": 20000
"ports_to_try" : 10
"max_clients" : 15
"enable_csrf_tokens" : true
"csrf_token_rotation_period" : 10
},
 |
Always configure a secure HTTP server. Otherwise, the EMS and LSR will log warning messages when SSL, authentication, or certificate validation is disabled or when self-signed certificates are allowed. Starting with v.5.4.8 of the EMS and LSR, application keys and passwords are automatically encrypted on the first startup of the EMS or LSR. For information about automatic encryption, refer to Automatic Configuration Encryption. For earlier versions, you can learn how to encrypting these secrets in Encrypting Application Keys, Passwords, and Passphrases.
|
For examples of secure configurations for communications between the EMS and the LSR, refer to Setting Up Secure Communications for the EMS and LSR. These examples are presented in order of least secure (testing purposes ONLY) to most secure (strongly recommended for production environments).
 |
Starting with v.5.4.8, the EMS provides a parameter called http_client_ca_certs that allows the use of a separate Certificate Authority (CA) certificate file that will only be used for Edge to Edge HTTPS connections. If this option is not used, the default CA certificate list that is used to validate the platform connection will be used. This parameter is in the certificates group in the EMS configuration file. For more information, refer to Using a Custom Certificate and Private Key.
|
The following table describes the properties in the http_server group :
|
Property
|
ThingWorx Base Type
|
Description
|
||
|---|---|---|---|---|
|
host
|
STRING
|
The name of the host that the EMS listens to. The default value is localhost, but this value means IPV6 localhost and not 127.0.0.1. Change this value to 127.0.0.1 to use IPV4 instead.
To configure an IP address other than localhost or 127.0.0.1 for REST Web Service calls, refer to Configuring EMS to Listen on IP Other Than localhost
|
||
|
port
|
NUMBER
|
The port number on which the EMS listens for messages from clients running the LSR. Typically, incoming messages on this port are from an LSR instance/application, but it is possible for any other application to send messages to the EMS HTTP Server.. The default port is 8000.
|
||
|
ssl
|
BOOLEAN
|
Whether or not to use SSL/TLS for communications between clients running the LSR and EMS. The default value is true.
|
||
|
certficate
|
STRING
|
When ssl is true, specifies the complete path to the certificate file that EMS will use when connecting to LSR clients. The default value is an empty STRING.
|
||
|
private_key
|
STRING
|
When ssl is true, specifies the complete path to the private key that EMS will use when connecting to LSR clients.
|
||
|
passphrase
|
STRING
|
When ssl is true and a private_key is used for connections with LSR clients, specifies the password defined for the private key. This value should be encrypted for security. For information about encrypting a passphrase, refer to Encrypting Application Keys, Passwords, and Passphrases.
|
||
|
authenticate
|
BOOLEAN
|
Whether or not to enable authentication between the LSR clients and the EMS. The default value is true.
|
||
|
user
|
STRING
|
The user name to pass to the HTTP server. The example above shows a name as all lowercase and all one word. However, there are no restrictions on the user name other than it must be a valid STRING.
|
||
|
password
|
STRING
|
The encrypted password for the user named in the user property. For information about encrypting passwords, refer to Encrypting Application Keys,, Passwords, and Passphrases.
|
||
|
content_read_timeout
|
NUMBER
|
The maximum amount of time (in milliseconds) that the EMS will wait before timing out when it tries to read a PUT or POST. The default value is 20000 milliseconds (20 seconds).
|
||
|
ports_to_try
|
NUMBER
|
The number of additional ports to try. If it cannot bind on the configured port, EMS increments the port number by 1. The default value is 10. For example, if the configured port is 8000, the next port to try would be 8001. If it could not bind to that port, the next port to try would be 8002, and so on. Port retries continue until the EMS binds to a port or until 10 ports plus the configured port have been tried. In this example, a total of 11 ports might be tried.
|
||
|
max_clients
|
NUMBER
|
The maximum number of clients that can be connected to the EMS at the same time. In this context, “clients” are devices that are running the LSR, connected to the EMS, and communicating with a ThingWorx Platform through the EMS. The default value is 15 clients.
|
||
|
enable_csrf_tokens
|
BOOLEAN
|
A flag to enable (true)or disable (false) the use of CSRF tokens with the REST services. By default the use of CSRF tokens is enabled. For more information, refer to Running REST API Calls with Postman on EMS and LSR.
|
||
|
csrf_token_rotation_period
|
NUMBER
|
The number of minutes between rotations of the CSRF token for a given session. The default value is 10 minutes.
|