BackendConnectorServlet

The still experimental BackendConnectorServlet forwards HTTP/HTTPS requests to content providers in the backend, using HTTP/HTTPS over TCP/IP.

info

Connecting to the backend and forwarding requests is the only responsibility of this servlet. It does not support load balancing, rewriting, cookie caching, or similar operations. To configure these tasks, use the following filters:

• load balancing --> LuaFilter (for a possible setup, see the example loadbalancing_servlets.example that is provided in the nevisProxy package)
• rewriting --> RewriteFilter, LuaFilter
• cookie caching --> CookieCacheFilter

The advantages of using the BackendConnectorServlet instead of the Http{s}ConnectorServlet (whenever this is possible) are the following:

• The BackendConnectorServlet is easier to configure and troubleshoot due to focused responsibility.
• The BackendConnectorServlet will be optimized for more performance in the near future.

Classname:
ch::nevis::nevisproxy::servlet::connector::http::BackendConnectorServlet

Library:
libBackendServlet.so.1

Trace group:
BC.Tracer.DebugProfile.NPBackendSrv

Configuration

InetAddress

Type: string
Usage Constraints: required Syntax: <hostname>:<portnumber>

Describes the host and port of the backend to connect to.

HostName

Type: string
Usage Constraints: optional

Defines the value to send to the backend as Host Header. If you do not set this attribute, the value of the attribute InetAddress will be sent.

Secure

Type: boolean
Default and secure default: true

Defines whether to open a secure (HTTPS) or not secure (HTTP) connection to the backend.

Secure.Protocol

Type: string
Default and secure default: -all +TLSv1.2 +TLSv1.3 Syntax:

• TLSv1: Can be required for certain JSSE implementations (for example, certain BEA WLS versions). It sends an SSL version of 3.1 in the SSL/TLS client hello and enforces TLS 1.0.
• TLSV1.1: Sends a TLS 1.1 client hello.
• TLSV1.2: Sends a TLS 1.2 client hello.
• TLSV1.3: Sends a TLS 1.3 client hello.

This attribute is only evaluated if the attribute Secure is set to true.

No sign means +. Separate each entry in the SSL protocol list by a blank.

caution

Some backends may not understand TLSv1.3 and thus cannot tell the proxy to downgrade.

Secure.CipherSuites

Type: string, optional Default and secure default: ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256

This attribute is only evaluated if the attribute Secure is set to "true".

This attribute defines the SSL cipher suite to use. You can set all ciphers that are supported by OpenSSL.

Secure.ConnectionRetries

Type: integer
Usage Constraints: min: 0, max: 100
Default : 0

This attribute is only evaluated if the attribute Secure is set to "true".

Sometimes an TLS connection fails because of some unknown problem (such as a network problem). This parameter specifies how many times the servlet should try to connect before giving up.

Secure.CACertificateFile

Type: string
Usage Constraints: optional, mandatory if Secure.CheckPeerHostname is enabled

This attribute is only evaluated if the attribute Secure is set to "true".

Specifies the file containing the CA certificate(s) that are used to check whether the peer’s node certificate is trusted. All the certificates in the file will be verified. PEM encoded files are supported. Nevis PKCS#11 URLs are not supported. If the attribute Secure.CACertificateFile attribute is not specified, the peer certificate will be trusted automatically.

For security reasons it is recommended that you always specify the Secure.CACertificateFile attribute.

Secure.ClientCertificateFile

Type: string
Usage Constraints: optional

This attribute is only evaluated if the attribute Secure is set to "true".

Specifies the X509 node certificate that will be sent to the application server (if requested by a SSL/TLS CertificateRequest message). PEM-encoded files and Nevis PKCS#11 URLs are supported.

When setting the bc property ch.nevis.openssl.allowCertificateChain to true, then a certificate chain can be configured.
If the file contains a certificate chain then the certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA.

In case of a pkcs#11 based HSM (f.ex. Securosys) you can extract the certificate in PEM format via a command similar to this:

/opt/nevisproxy/bin/openssl storeutl -engine /opt/nevisproxy/lib/libnevisproxypkcs11engine.so 'pkcs11:library=/usr/local/primus/lib/libprimusP11.so&dologin=true&objectlabel=proxy.cert&type=cert&pinenv=PKCS11_PIN'

If you specify a certificate chain for an pkcs#11 based HSM then the pkcs#11 URL has to be specified in the parameter Secure.ClientKeyFile.

Client certificates are experimental when using TLSv1.3.

Secure.ClientKeyFile

Type: string
Usage Constraints: optional

This attribute is only evaluated if the attribute Secure is set to "true".

The key for a TLS client certificate may be provided either in the same file as the certificate (specified with the Secure.ClientCertificateFile attribute), or it may be provided in a separate file specified with the Secure.ClientKeyFile attribute.

Configure the Secure.ClientCertificateFile attribute only if both the certificate and the key are contained in the same file.

Secure.CheckPeerHostname

Type: boolean
Default and secure default: true

If enabled, among other validations, the DNS name will be checked against the CN/SAN of the certificate. Setting this parameter also requires setting the Secure.CACertificateFile.

Secure.CheckPeerHostname.AllowWildcards

Type: boolean
Default and secure default: false

This attribute is only evaluated if the attribute Secure.CheckPeerHostname is set to "true".

If set to "true", the system will also accept certificates containing wildcards.

caution

For security reasons, we recommend setting this parameter to "false" in production.

Secure.SNISupport

Type: boolean
Default: true

This attribute is only evaluated if the attribute Secure is set to "true".

Enables SNI support for this servlet. In case the backend has multiple name-based virtual servers configured with different certificates, the servlet can securely indicate, as part of the TLS handshake, to which one it intends to connect to. This indication happens at the beginning of the connection. It depends on the backend whether the indication is continuously checked.

Secure.CrlFile

Type: string
Usage Constraints: optional

Defines the path to a CRL file (PEM format). This path is automatically reloaded if the file is replaced by a newer one. The file modification check takes place in the time interval configured in the navajo.xml file (in the periodicity attribute of the Timer section).

KeepAlive

Type: boolean
Default and secure default: true

Pools TCP connections for later reuse. If set to "false", the connection is closed after use, and a new TCP connection will be established for the next request.

Only enable this attribute if the web server supports the keep-alive feature in an acceptable range. If this is not the case, KeepAlive should be disabled.

KeepAlive.ConnectionPoolSize

Type: integer
Default: 100

This attribute is only evaluated if the attribute KeepAlive is set to "true".

This attribute defines the number of pooled TCP connections. A TCP connection is only put in the pool if it does not exceed the configured size.

DNSCache.ttl

Type: integer
Default: 86400 (1 day)

Specifies the time period in seconds to cache DNS info, before the system will retrieve the IP address again. The IP adress is set in the attribute InetAddress.

ConnectTimeout

Type: integer
Default: 10000 (10 sec)

Defines the timeout in milliseconds to open the TCP connection to the content provider.

• Lower this timeout for fast recovery.
• Raise this timeout if your server has networking problems and the proxy receives "connection refused" errors, even though the server is up, running, and responding to connect requests.

RequestTimeout

Type: integer
Default: 120000 (2 min)

Defines the TCP timeout in milliseconds for the reading of the response from the web server.

ResponseLineSize

Type: integer
Default: 4096

Defines the maximum allowed line size in the HTTP header of the response.