Web Server (ws)

Description

Provides access to the system API over HTTP and WebSocket and serves static files of system and role web applications. For API access, performs authorization and works with HTTP sessions by setting and using cookies. For some endpoints, token authorization is available using the `Authorization: Bearer <integration_point.token_local>` header.

Made redundant and scaled in Active-Active mode.

On role startup, the certificate specified in the *certdir* parameter is checked. If validation fails, the role starts with an immutable certificate. The certificate can be overridden through domain settings.

Table 1. System characteristics

Code

ws

Operation mode

Service

Redundancy mode

Active-Active

Site types

Any

Layer

Business logic

Placement

Border

State preservation and recovery on restart

No

Application

era_ws

Limitations

  • Present in the initial configuration.

  • Is a border role and uses a TLS certificate for HTTPS and WSS connections.

Parameters

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and digits and must start with a letter.

roletype

str

required

Role type. Possible values: "ws".

ext

json

empty

Additional role options. Contains a JSON object or list.

enabled

bool

empty

Role activity flag. When set to false, the role does not participate in validation and is not started.

limit_of_cores

int

empty

Limit on the number of CPU logical cores used. Default: 0 - unlimited.

logging_default_level

int

empty

Default logging level set specifically for the role instance (microservice type). More

allow_divergence

bool

false

Flag allowing parameter differences in roles of the same group. Default: false - not allowed.

roleid

int

required

Role identifier.
Unique across the entire system, regardless of site or server. Cannot be changed after assignment. An integer from 1 to 9999

separate

bool

false

Flag indicating whether the role is allocated to a separate node.

apdir

str

empty

Alias of the server directory for storing autoprovision files.

certdir

str

empty

Alias of the server directory for storing certificates ('server.crt' and 'server.key' files).
If a certificate chain to a certification authority (CA) must be specified, it must be placed at the end of the certificate file.
If the path is not specified, certificates are searched in the "/usr/lib/era/era_ws/priv/ssl" directory.

This parameter is used only when the certificate specified in domain settings is not applied (settings.certificate_pem):

  • the server is accessed by a domain name that does not correspond to the platform domain tree, and the certificate is not specified in master domain settings;

  • no certificate is specified in the settings of the access domain and its parent domains up to the master domain;

  • automatic certificate issuance is not used.

keypass

str

empty

Password for decrypting the certificate private key file. Secret: ciphertext when read; the plaintext value is not returned via API and is decrypted by the service when used; a plaintext value can be supplied on input (Encryption and keys).

http_ifaces

array<str>

[]

List of HTTP interfaces.
Specified by server interface aliases.
If none is specified, all interfaces are listened to (0.0.0.0).

If any specified network interface is not up when the server starts, the listener does not start. After it appears, the microservice node must be restarted to start the listener. This does not apply to virtual addresses.

If only the loopback interface 127.0.0.1 is left in the http_ifaces list, this setting can automatically prevent HTTP use by any clients except local ones.

https_ifaces

array<str>

[]

List of HTTPS interfaces.
Specified by server interface aliases.
If none is specified, all interfaces are listened to (0.0.0.0).

If any specified network interface is not up when the server starts, the listener does not start. After it appears, the microservice node must be restarted to start the listener. This does not apply to virtual addresses.

httpport

int

80

Local web server port for open TCP connections.

httpsport

int

443

Local web server port for TLS connections.

proxy_httpport

int

empty

Local web server port for open TCP connections through PROXY PROTOCOL.

proxy_httpsport

int

empty

Local web server port for TLS connections through PROXY PROTOCOL.

virtual_ifaces

array<str>

[]

List of monitored virtual interfaces (Virtual IP).
Specified by server interface aliases marked with the 'virtual' flag.
If none is specified, the service starts normally on static addresses according to http_ifaces and https_ifaces settings.

If some virtual interfaces are specified in the list, the web server instance monitors their appearance before starting the service.
The absence of at least one virtual address from the specified list among the server’s available interfaces causes the service to be unloaded and wait for all addresses to appear.
Virtual interface availability is checked every 2 seconds.

The virtual interface is used by the web server for its primary purpose only if the corresponding alias list in http_ifaces or https_ifaces is empty or contains this virtual interface alias.

The target use of a virtual interface assumes the following combination of settings:

  • each virtual interface is specified in at least one of http_ifaces or https_ifaces; alternatively, the lists are empty;

  • another server in the cluster has the same address similarly configured as virtual;

  • another web server microservice instance bound to that server has the same interface specified among virtual ones.

ports_mode

str

"both"

Port operation mode.
Possible values:

  • "both" – http and https ports are open;

  • "http-only" – only the http port is open;

  • "https-only" – only the https port is open;

  • "http+redir" – http and https ports are open, but https redirects to http;

  • "https+redir" – http and https ports are open, but http redirects to https.

When redirecting to https, the scheme changes but the host name is preserved if access is by domain name.
If access is by IP address, the https_host property must be set in master domain parameters for successful redirection.
In particular, this is necessary for correct operation of the product layer when there is no web server instance whose internal interface is accessible over http.

user_auth_mode

int

empty

Supported user authorization methods.
Possible values:

  • 'any' - any supported mode: login and password, external authorization server (OAuth, OpenID).

  • 'oauth' - only oauth.

Does not affect third-party token authentication.

tls_mode

int

empty

TLS port operation mode.

  • 'public' - normal mode, without client certificate verification.

  • 'debug' - debug mode; client certificates are verified, but absence or failed verification is only logged and does not affect operation.

  • 'mutual' - mode with mutual certificate verification. A client certificate is mandatory to pass verification and must pass chain validation.

  • 'strong' - mode with mutual certificate verification. In addition to mutual, an additional strict check is performed for the certificate in the 'dm/Certificates' collection.

The CA certificate that signed the certificates issued to devices is used for chain validation and can be placed in the :SYNC/common/cacerts folder in PEM format.

anti_spam_enabled

bool

true

Forced spam filter switch for the microservice instance.
The limit density is configured by border filter rules and the master domain parameter mps_limit_defaults → sip.

By default, the spam filter is not blocked but is inactive because master domain settings do not set the limit density.

rest_reattempts_sec

int

62

Interval in seconds during which the server does not return 5xx responses to sent requests but instead periodically retries the request.
A value of 0 disables the retry mechanism.
Applied to WebSocket connections when processing "rest" requests to DMS and domain center collections.
For domain center collections, this is the default timeout (no more than 120 seconds); a request can override it with the timeout parameter.
More about the parameter.

dc_rest_limit

int

10

Maximum number of simultaneously executed "rest" WebSocket requests to the domain center of one domain from a microservice instance.
Other requests wait in the queue. If the domain center is unavailable, the queue pauses until recovery.
A value of 0 removes the limit. The change is applied without restart.
More about the parameter.

dc_rest_conn_limit

int

5

Maximum number of simultaneously executed "rest" requests to the domain center from one WebSocket connection.
Other requests of the connection wait in its own queue and do not occupy the microservice instance’s shared queue ('dc_rest_limit').
A value of 0 removes the limit. The change applies to subsequent requests without restart.
More about the parameter.

service_mode

str

empty

Request servicing mode

  • "both" – both parts work (API and static content: system and role web applications);

  • "api-only" – only API works;

  • "static-only" – only static content works.

dmsquery_mode

str

admin

Access to dmsquery requests (websocket token and user API): an arbitrary Select to the class DB without checking class permissions.
Possible values:

  • 'denied' - denied to everyone.

  • 'admin' - only users and integration channels with the admin role.

  • 'role' - users and integration channels with the admin or dmsquery role.

  • 'authorized' - any authorized user or integration channel with the dmsquery capability.

Integration channel roles include the roles of the bound user.

tags

array<str>

List of keys for building various web server groups and specifying lists as access points for product layer microservices and for selecting the web server to which VCS connects.
Not used in web server operation itself.

order

int

0

Priority number when building web server lists and specifying them as access points for product layer microservices and selecting the web server to which VCS connects.
Not used in web server operation itself.

websock_debug_level_enabled

bool

true

Switch for special WebSocket logging level configuration.
Default: true.
Possible values:

  • true - special WebSocket connection logging level mode is enabled. In this case, the logging level is determined by the adjacent websock_debug_level parameter.

  • false - the WebSocket connection logging level is determined by the current node logging level (can be changed by the master domain administrator in the settings application).

    • 'DEBUG' - corresponds to WebSocket connection logging level 6.

    • 'TRACE' - corresponds to WebSocket connection logging level 5.

    • 'INFO' - corresponds to WebSocket connection logging level 3.

    • 'WARNING' - corresponds to WebSocket connection logging level 2.

    • 'ERROR' - corresponds to WebSocket connection logging level 1.

    • 'CRASH' - corresponds to WebSocket connection logging level 0.

websock_debug_level

int

0

WebSocket protocol message logging level.
Default: 0.
Possible values:

  • 0 – does not log;

  • 1 – logs connection starts and stops;

  • 2 – logs simple errors;

  • 3 – logs errors with the erroneous message body;

  • 4 – logs all incoming and outgoing messages;

  • 5 – logs all incoming and outgoing messages, truncating the first 1024 bytes;

  • 6 – logs all incoming and outgoing messages completely.

wwwdir

string

empty

Alias of the server directory with web server static resources.
Default: "/usr/lib/era/era_ws/priv/www"

add_headers

array(string)

empty

List of additional static headers added to every HTTP(S) response.

webapps

str

empty

Web application metadata set suffix: when set to X, the webapps_X and url_routes_X sets are used instead of the standard ones.

Configuration example

Configuration management is performed in an application available to master domain administrators. The application hides the full configuration content, but it is still available through the API.

The configuration contains a section describing all instances of all roles. Parameters are defined for each specific role instance.

Node example
{
  "name": "ws1",
  "roletype": "ws",

  "roleid": 11230,

  "certdir": "alias://paths/default_certdir",
  "keypass": "eb9c4458016d3f1e378d02004c4f4f50",

  "httpport": 80,
  "httpsport": 443,
  "http_ifaces": ["eth0", "eth2"],
  "https_ifaces": [],
  "ports_mode": "both",

  "service_mode": "both",

  "websock_debug_level_enabled": 1,
  "websock_debug_level": 2
}

See also