Skip to main content
Version: 9.2605.x RR

Http2Servlet

The Http2Servlet forwards HTTP/HTTPS requests to backends using HTTP/HTTPS over TCP/IP.

The servlet is still experimental and it works with the following limitations (not exhaustive list):

  • no PKCS#11 support
  • no Telemetry support
  • no server streaming supported
  • no Trailer Only support
  • no Client Certificate support (not yet supported by the HTTP/2 protocol)
  • if used together with an ICAPFilter, the parameters BufferRequest=true and ScanResponse=false have to be set in the ICAPFilter
  • only simple requests (no streaming) are supported when used with a ModsecurityFilter or a LuaFilter.
  • no load balancing supported but it can be achieved via the LoadBalancingServlet
  • no rewriting, cookie caching or similar is supported (can be achieved via a LuaFilter)
Classname
ch::nevis::nevisproxy::servlet::connector::http::Http2Servlet
Library
libBackendServlet.so.1
TraceGroup
BC.Tracer.DebugProfile.NPHttp2Svt

Configuration​

Url​

Type: string
Usage Constraints: required
Syntax: http[s]://<hostname>[:<portnumber>]

Describes the URL to connect to the service.

CACertificateFile​

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

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. PKCS#11 URLs are not supported. If the attribute CACertificateFile attribute is not specified, the peer certificate will be trusted automatically.
For security reasons it is recommended that you always specify the CACertificateFile attribute.

ClientCertificateFile​

Type: string
Usage Constraints: optional

Specifies the X509 node certificate that will be sent to the application server (if requested by a SSL/TLS CertificateRequest message). PEM encoded files are supported for node certificates and certificate chains. 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.

Client certificates are experimental when using TLSv1.3.

ClientKeyFile​

Type: string
Usage Constraints: optional

The key for a TLS client certificate may be provided either in the same file as the certificate (specified with the ClientCertificateFile attribute), or it may be provided in a separate file specified with the ClientKeyFile attribute. Configure the ClientCertificateFile attribute only if both the certificate and the key are contained in the same file.

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 CACertificateFile.

SSLProtocolMin​

Type: string
Usage Constraints: optional
Default: TLSv1.2
Secure Default: TLSv1.3

This parameter controls the minimum acceptable version of the SSL/TLS protocol to use for the connection. Valid values are SSLv3, TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.

SSLProtocolMax​

Type: string
Usage Constraints: optional
Default: TLSv1.3

This parameter controls the maximum acceptable version of the SSL/TLS protocol to use for the connection. Valid values are TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3.

SSLCipherSuites​

Type: string
Usage Constraints: optional
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

Specifies the list of cipher suites to use for the SSL/TLS connection. This configuration applies to connections up to TLSv1.2.

SSLCipherSuites_TLSv1_3​

Type: string
Usage Constraints: optional
Default: TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256

Specifies the list of cipher suites specifically used for TLSv1.3 connections.

Curves​

Type: string
Usage Constraints: optional

Pass a string as a parameter with a colon-delimited list of key exchange algorithms (also known as groups). This option defines the client's supported key exchange methods in the SSL/TLS handshake.

CrlFile​

Type: string
Usage Constraints: optional

Specifies a file containing the Certificate Revocation List (CRL) in PEM format. This file is used for certificate validation during the SSL exchange. When configured, a CRL check is required against all elements of the certificate chain. This option is only effective when peer verification (via CheckPeerHostname) is enabled.

SSLCache​

Type: string
Usage Constraints: required
Syntax: on or off (case-insensitive)
Default: on

This parameter enables or disables the use of the SSL session-ID cache. Setting this to off disables caching entirely, which may be required as a workaround if the backend has broken SSL implementation.

ConnectionPoolSize​

Type: integer
Default: 100

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.

CurlTraceConfig​

Type: String
Default: http/2,ssl

With this parameter you can configure which trace components of the underlying curl library should be traced.

Trace components:

  • tcp: Tracing of TCP socket handling: connect, sends, receives.
  • ssl: Tracing of SSL/TLS operations.
  • http/2: Details about HTTP/2 handling: frames, events, I/O, etc.
  • dns: Tracing of DNS operations to resolve hostnames and HTTPS records.
  • read: Traces reading of upload data from the application in order to send it to the server.
  • ssls: Tracing of SSL Session handling, e.g. caching/import/export.
  • write: Traces writing of download data, received from the server, to the application.
  • all: all trace components enabled
  • network: All components involved in bare network I/O, including the SSL layer.
  • All components involved in transfer protocols
info
  • some basic HTTP/2 and SSL information are logged regardless of what is configured
  • the trace group NPHttp2Svt needs to be set at least to INFO

Examples​

Log details of HTTP/2 and SSL handling:

http/2,ssl

Log all details, except SSL handling:

all,-ssl

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 Url will be sent.
It is possible to define variables from the ENV and AUTH context, for example: ENV:HTTP_Host;. This makes it possible to use the Host header sent by the client.

FrontendTimeout​

Type: Integer (milliseconds)
Default: 10000

The timeout to wait for data from the frontend. If the timeout expires the connection to the frontend will be closed.

URLEncoding​

Type: boolean
Usage Constraints: optional, troubleshooting
Default: true

nevisProxy decodes the incoming request URI to build the filter and servlet chain mappings, then re-encodes the URI when forwarding the request to the backend. When URLEncoding is true (the default), this re-encoding step encodes forbidden characters in the outgoing URI — for example, /UIFont CMSStyle.swift becomes /UIFont%20CMSStyle.swift. The characters ; and = are also treated as forbidden in the path and are encoded (%3B/%3D).

If the request path is not changed then the original path is returned, preserving the encodedness of the special characters. If the path was changed (for example by a LuaFilter), nevisProxy encodes the changed path, which also percent-encodes ; and = if present. This behavior can be turned off by setting the bc property ch.nevis.navajo.KeepOriginalPath to false, in which case the path is always re-encoded from its currently resolved value.

We recommend keeping this attribute set to true. Set it to false only when custom URL encoding is needed, which can be achieved with an added LuaFilter.

Note: You can set the attribute URLEncoding to false centrally. To do this, add the following code line to the bc.properties configuration file:

ch.nevis.nevisproxy.servlet.connector.http.Http2Servlet.URLEncoding=false

The above code line sets the attribute URLEncoding to false for all Http2Servlets, unless it is explicitly overwritten in the servlet itself.
The file bc.properties is usually located under /var/opt/nevisProxy/<instance name>/conf/bc.properties.