Web Server (ws)

Description

Provides access to system APIs via HTTP and WebSocket, and serves the output of static files to system and role-based web applications. To access the API, it performs authorization and works with HTTP sessions by setting and using cookies. For some endpoints, authorization by token using the header `Authorization: Bearer <intergation_point.token_local>`.

Reserved and scaled in mode Active-Active.

When the role is started, the certificate specified in the *certdir* parameter is validated. If the validation fails, the role is started with an unchanged certificate. The certificate can be overridden through the domain settings.

Table 1. System Characteristics

Code

ws

Mode of operation

Service

Backup mode

Active-Active

Types of sites

Any

Layer

Business logic

Placement

Frontier

Saving and restoring state on reboot

No

appendix

era_ws

Limitations

  • Present in the initial configuration.

  • Is an edge role, uses a TLS certificate for HTTPS and WSS connections.

Parameters

Description of columns in the table

Table 2. Parameters
Name Type Default Description

name

str

required

Name. May consist of Latin letters and numbers, must begin with a letter.

roletype

str

required

Role Type. Possible values: "ws".

iface

str

required

The alias of the server network interface on which the roles will interact internally with each other.

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.

roleid

int

required

Role ID.
Unique to the entire system, regardless of the site or server. Cannot be changed once assigned. Integer from 1 to 9999

separate

bool

false

An indication that the role has been allocated to a separate node.

apdir

str

empty

Directory alias on the server for storing files autoprovision.

certdir

str

empty

The alias of the directory on the server for storing certificates (files 'server.crt' and 'server.key').
In case it is necessary to specify the certificate chain up to the CA (Certification Authority) it should be placed at the end of the certificate file.
If the path is not specified, the certificates are searched in the directory "/usr/lib/era/era_ws/priv/ssl".

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

  • the server was accessed using a domain name that does not correspond to the platform domain tree, and at the same time the certificate is not specified in the master domain settings;

  • the address domain and its parent domains up to the master domain do not have a certificate specified in the settings;

  • automatic certificate issuance is not used.

keypass

str

empty

Password for decrypting the certificate’s secret key file.

http_ifaces

array<str>

[]

A list of HTTP interfaces. Specifies interface aliases servers.
If none is specified, all interfaces are listened to (0.0.0.0).

If any of the specified network interfaces is not up at the moment of server startup, the listener is not started. After its appearance, the microservice node must be restarted to start the listener.

https_ifaces

array<str>

[]

HTTPS interface list. Specifies interface aliases servers.
If none is specified, all interfaces are listened to (0.0.0.0).

If any of the specified network interfaces is not up at the moment of server startup, the listener is not started. After its appearance, the microservice node must be restarted to start the listener.

httpport

int

80

Local web server port for open TCP connections.

httpsport

int

443

The local port of the web server for TLS connections.

ports_mode

str

"both"

Mode of operation of the ports.
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 is running in redirect mode on the http;

  • "https+redir" – http and https ports are open, but http is running in redirect mode on the https.

When redirecting to https, the scheme changes, but the hostname is preserved if accessed by domain name.
If the address is an IP address, then for successful redirection it is necessary to set the following property in the master domain parameters https_host.
In particular, this is necessary for the correct operation of the product layer in the case where there is no instance of a web server that has an internal interface accessible via http.

service_mode

str

empty

Request service mode

  • "both" – Both parts work (both APIs and statics (system and role-based web applications));

  • "api-only" – only works api;

  • "static-only" – only static works.

tags

array<str>

A list of keys for building different groups of webservers and specifying the lists as access points for microservices product layer.
It is not used in the operation of the webserver itself.

order

int

0

Priority number when building lists of webservers and specifying them as access points for microservices product layer.
It is not used in the operation of the webserver itself.

websock_debug_level_enabled

bool

true

Switch to specifically configure the logging level of web socket connection logging.
Default: true.
Possible values:

  • true - the mode of special setting of logging level of web socket connections is enabled. In this case, the logging level is determined by the neighboring parameter websock_debug_level.

  • false - the logging level of web socket connections is determined through the set logging level of the current node (can be changed by the master domain administrator in the settings application).

    • 'DEBUG' - corresponds to the logging level of websocket connections 6.

    • 'TRACE' - corresponds to the logging level of websocket connections 5.

    • 'INFO' - corresponds to the logging level of websocket connections 3.

    • 'WARNING' - corresponds to the logging level of websocket connections 2.

    • 'ERROR' - corresponds to the logging level of websocket connections 1.

    • 'CRASH' - corresponds to the logging level of websocket connections 0.

websock_debug_level

int

0

Protocol message logging layer websocket.
Default: 0.
Possible values:

  • 0 – doesn’t log;

  • 1 – logs connection stops starts;

  • 2 – logs simple errors;

  • 3 – logs errors with mentioning the body of the erroneous message;

  • 4 – logs the fact of all incoming and outgoing messages;

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

  • 6 – logs all incoming and outgoing messages completely.

wwwdir

string

empty

A directory alias on a server with static web server resources.
Default: "/usr/lib/era/era_ws/priv/www"

Configuration example

The configuration is managed in an application available to master domain administrators. The application hides the full content of the configuration, but it is nevertheless accessible via the API.

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

Example node
{
  "iface": "eth0",
  "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

  • Personalization
  • Increase font size
  • Decrease font size