ws/ExternalRoutedHosts

Collection for specifying DNS names for master site web servers whose requests the web server routes by special scenarios: serving externally hosted static content and proxying http and websocket requests.

TLS certificates are supported, including regular automatic issuance using the LetsEncrypt service.

When creating routes, port type bindings can be used to perform different routing for open ports and ports with TLS certificates. For example, this way all insecure connections can be redirected to the TLS port. This is also available for main domain names and IP addresses, so this functionality is an alternative to the ws microservice 'ports_mode' parameter.

Importantly, for hostnames created this way, certificates are configured individually without binding to the platform main domain tree. However, a fallback mode applies: if no route is found for a specific request arriving at such a hostname, the call is passed to the main platform processing dispatcher. Therefore, to exclude main API processing for a hostname, add the general path '/' at the end of the route list (separately for http and websocket).

Served by the webserver microservice.

Storage type: category.

Table 1. Class fields
Field Description

id

Identifier

host

DNS name or IP address routed to the site server or servers.

The main list of system resource and API endpoints is appended to the end of the route list specified for any host.

The value '*' can be used for all other domains, including when the Host header is not passed in the request.

It is assumed that one entity uniquely describes one host, i.e., one entity is created for a host. However, another arrangement is possible; see the 'priority' field for details.

priority

Record priority for the case of several records bound to the same 'host'. Default 0. If there are several active records for one host, their routes ('routes') are merged into one list in increasing order of the priority field value. And when ACME mode is enabled ('acme_enabled'), a certificate is issued only for one of such records with the same 'host', also guided by the priority value.

enabled

Enabled flag. Default true.

routes

Route list sorted in descending order. An array of objects containing fields:

  • port_type - port type to which the rule applies (open or TLS). Possible values:

    • 'all' - for all port types. Applied by default.

    • 'http' - only for open ports.

    • 'https' - only for TLS ports.

  • path - URL path from which the route is active. For all handlers except redirects, the value is forcibly supplemented at the end with an arbitrary remaining path mask "/[…​]" if it is not already specified in the value itself. Redirects work strictly on the specifically specified path. Examples of correct paths:

    • /

    • /[…​]

    • /folder1/folder2

    • /folder1/resource

    • /folder1/folder2/[…​]

    • /proxy/[…​]

    • /proxy/:domain/:port/[…​]

    • /my_path/:any1/:any2/static/[…​]

  • paths - array of URL paths that expands the route into several same-type routes. Applied similarly to the 'path' parameter when the 'path' parameter is not set.

  • handler - handler type. Each handler has additional specific fields. Available handlers:

    • 'static' - serves static content from the specified directory. Additional handler parameters:

      • directory. Root directory with static content to serve. The directory must be specified via the alias ":SYNC/common/", ":GLOBALSHARE/", ":SITESHARE/", or ":LOCAL/". Content is addressed by relative paths appended to the specified path.

    • 'redirect' - redirects to a constant path, returning a 3xx response. Additional handler parameters:

      • http_code - 3xx response code. Default 302.

      • location - Redirect path on the same host.

    • 'redirect_regex' - redirects to a path computed using a regular expression, returning a 3xx response. Additional handler parameters:

      • http_code - 3xx response code. Default 302.

      • location_match - Regular expression to select the replacement place in the path received in the request. Default ".*" - the whole value.

      • location_replacement - Value substituted at the place found by the regular expression. Default "" - replace with empty.

    • 'error' - sends an error response. Additional handler parameters:

      • http_code - 4xx-6xx response code. Default 500.

      • content_type - Type of returned content. The header is added to the response only if a non-empty 'body' parameter value is set. Default "application/octet-stream".

      • body - Response body. Default empty string - response without body.

    • 'proxy_http' and 'proxy_websocket' - proxy http requests and websocket connections to the specified hostname. If the path ends with a slash, all child paths of the directory are redirected; if not, only the specified resource. Platform session cookies and its token in the Authorization header are not passed to the destination hostname. Response cookies (Set-Cookie) are passed to the client without the Domain attribute (route host cookie); cookies with platform session names are discarded. A path with add_path in the cookie Path attribute and in the Location header is replaced with the route path; an absolute destination address in Location — with a path on the route host. Additional handler parameters:

      • host - destination hostname.

      • hosts - list of alternative destination hostnames; connection is made to all in parallel and the first available is used.

      • port - destination port.

      • tls - tls usage mode. Value variants: true, false, "auto" (automatic determination based on port, default), "same" (identical to the source request).

      • add_path - static path segment added to the beginning of the redirected request path. Default empty. For example, for a route with path = "/abc/[…​]", add_path = "/def/ghi" ensures that the received request for page "/abc/x/1.txt" is redirected to page "/def/ghi/x/1.txt" of the specified web server. The template '$path$' can be specified, in which case the source path without trailing slashes is substituted.

      • pass_session - true: the platform session is passed to the destination hostname and back — the session cookie and token in the Authorization header are passed, and the session cookie from the response (Set-Cookie) is passed to the client. Only for the case when the destination hostname is the platform itself (for example, login via an external OAuth provider on the route host). Default false.

    • 'proxy_http_ex' and 'proxy_websocket_ex' - proxy http requests or websocket connections to the hostname and port specified in the requested path. The path specified in the 'path' field must contain the bindings "/:domain/" and "/:port/". If the path ends with a slash, all child paths of the directory are redirected; if not, only the specified resource. Request and response cookies (Cookie, Set-Cookie) are not passed, nor is the platform session token in the Authorization header. Additional handler parameters:

      • tls - tls usage mode. Value variants: true, false, "auto" (automatic determination based on port, default), "same" (identical to the source request).

      • add_path - static path segment added to the beginning of the redirected request path. Default empty. For example, for a route with path = "/abc/[…​]", add_path = "/def/ghi" ensures that the received request for page "/abc/x/1.txt" is redirected to page "/def/ghi/x/1.txt" of the specified web server. The template '$path$' can be specified, in which case the source path without trailing slashes is substituted.

  • archive_referers - mode for saving transitions along the route to ws/ArchiveReferers, overrides the record field of the same name. Values are the same as the record field. If the field is not set, the record value applies. For example, with the recording mode disabled and "archive_referers": "utm" in the route, transitions are saved only along this route.

  • cert - for 'proxy' modes, allows setting specific settings for verifying the certificate chain validity. By default the standard set of root certificates from the OS (in the container) and in the :SYNC/common/cacerts directory is used. Setting the value "verify_none" disables verification of the server certificate validity. PEM content or a macro path to a file with PEM content in the :SYNC directory applies the specified certificate as a root for the trusted chain. Other values are invalid and lead to default validity verification settings.

archive_referers

Mode for saving client transitions to the ws/ArchiveReferers collection for all record routes (a route can override the mode with the archive_referers field). Values:

  • 'off' - do not save. Default, including for records created before the field appeared.

  • 'utm' - save; only utm_* parameters are saved in the URL, other query parameters are discarded (they may contain link tokens and other secrets).

  • 'full' - save the URL with the full query.

acme_enabled

Flag for enabling automatic LetsEncrypt certificate issuance. Default false. Makes sense only for domain names. Certificate issuance is performed by the mware microservice. The 'acme.sh' package is used for certificate issuance.

Before requesting LetsEncrypt, the domain name availability and its correct addressing to the current site are checked (a secondary check is performed using an external proxy server).

The operation is skipped if one of the conditions holds:

  • email for acme is not set in the master domain settings;

  • the certificate_pem field certificate was uploaded by the administrator;

  • the previously issued LetsEncrypt certificate is still valid for the coming week.

certificate_pem

Certificate PEM content. Uploaded by the administrator or filled automatically after certificate issuance. Used when TLS requests arrive. The certificate is applied by ws microservice instances when requests arrive for the configured DNS name.