.. _http_server: *********** HTTP Server *********** TLS === App Suite Proxy can be used for TLS termination of HTTP requests. The Server can be configured to use one certificate for all incoming requests or utilize Server Name Indication (SNI) to choose a different certificate from the configured keystore for each host. Each certificate has to provide the hostname in its alternative name extension. If only one certificate is present in the keystore, this certificate is used without any hostname matching. Wildcard certificates are also supported, from first subdomain level, like ``*.appsuite.com or *.customer.appsuite.com``. Configuration ------------- Configuration takes place via properties in ``application.properties``. :zuul.ssl.openssl.allow: **Optional** Offloads TLS termination to OpenSSL via Java JNI. See https://netty.io/wiki/forked-tomcat-native.html for details. App Suite Proxy links and ships the ``io.netty:netty-tcnative-boringssl-static`` library for that purpose. This will also affect outbound connections (:ref:`Backend Pools::TLS `)! Default: ``false`` Reloadable: ``true`` :proxy.tls.enabled: **Optional:** Enables TLS Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_TLS_ENABLED`` :proxy.tls.port: **Manadatory for TLS:** TLS port Default: ``8443`` Reloadable: ``false`` EnvVar: ``PROXY_TLS_PORT`` :proxy.tls.keystore.type: **Manadatory for TLS:** Keystore type Default: ``PKCS12`` Reloadable: ``false`` EnvVar: ``PROXY_TLS_KEYSTORE_TYPE`` :proxy.tls.keystore: **Manadatory for TLS:** Path to keystore file Default: ```` Reloadable: ``false`` EnvVar: ``PROXY_TLS_KEYSTORE`` :proxy.tls.keystore.pass: **Manadatory for TLS:** Password to open keystore Default: ```` Reloadable: ``false`` EnvVar: ``PROXY_TLS_KEYSTORE_PASS`` :proxy.tls.ciphers: **Optional:** Set the cipher suites that should be supported Default:: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_RSA_WITH_AES_256_GCM_SHA384, TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 EnvVar: ``PROXY_TLS_CIPHERS`` :proxy.tls.protocols: **Optional:** Set the protocols that should be supported Default: ``TLSv1.2, TLSv1.1, TLSv1`` Reloadable: ``false`` EnvVar: ``PROXY_TLS_PROTOCOLS`` Server Name Indication `````````````````````` Since SNI is enabled whenever TLS is enabled, this feature can be used by simply adding new certificates to the keystore and ensuring, that the hostname is provided in the certificates alternative name extension. .. note:: So far, OpenSSL is not supported in cooperation with the SNI feature. If OpenSSL is desired, one single certificate should be present in the keystore. .. _compression: Compression =========== GZip compression of HTTP response payload is supported and enabled by default. Response payloads are compressed, if the content type is known to be compressible and the HTTP request contained ``gzip`` as part of an ``Accept-Encoding`` header. In addition the content must exceed a certain size to be compressed. Origin responses that are already compressed are streamed through as is and not re-compressed. Configuration ------------- Configuration takes place via properties in ``application.properties``. :zuul.response.gzip.filter.enabled: **Optional:** En-/disable GZip compression Default: ``true`` Reloadable: ``true`` :zuul.min.gzip.body.size: **Optional:** Minimum response body size to apply compression in bytes Default: ``860`` Reloadable: ``true`` :zuul.gzip.contenttypes: **Optional:** Comma-separated list of content types that apply for compression Default:: text/html, application/x-javascript, text/css, application/javascript, text/javascript, text/plain, text/xml, application/json, application/vnd.ms-fontobject, application/x-font-opentype, application/x-font-truetype, application/x-font-ttf, application/xml, font/eot, font/opentype, font/otf, image/svg+xml, image/vnd.microsoft.icon Reloadable: ``true`` .. _proxy_protocol: PROXY Protocol ============== The PROXY protocol provides a convenient way to safely transport connection information such as a client's address, client port and protocol across multiple layers of NAT or TCP proxies. .. _protocol_config: Configuration ------------- The following settings are applicable to ``application.properties``. :proxy.proxyprotocol.expected: **Optional:** A boolean value to enable/disable PROXY protocol support. If enabled and a request was sent using PROXY protocol: - the original client IP and port are used as input for :ref:`X-Forwarded headers ` - the original client IP is checked against any client :ref:`IP restriction ` Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_PROTOCOL_EXPECTED`` Example Setup ------------- Find below an example configuration for an HAProxy docker container that has PROXY protocol enabled. .. literalinclude:: config-examples/haproxy_setup_example.yml :language: yaml Enable proxy protocol in configfile with **send-proxy** or **send-proxy-v2**. Disable by deleting the keywords. For a local setup replace container- and appsuite-proxy IP with localhost. Finally start the HAProxy with **haproxy -f cfgfile** ======= .. _Management Endpoint: Management Endpoint =================== App Suite Proxy comes with an additional management endpoint which allows administrators and third party systems to get access to runtime environment. Following topics are currently covered: * Prometheus Metrics * Microprofile Health Check * Configuration Reload To enable management endpoint on startup set configuration property ``proxy.admin.port.enabled`` to ``true``. For a complete reference to all possible configuration properties and their defaults see section :ref:`Settings `. .. hint:: To get an overview of all exposed endpoints open root entry at **http://:** .. _Settings: Settings -------- .. note:: All properties can be found in ``application.properties``. If a property is missing, not set or the value is not in range the default value will be used. :proxy.admin.port.enabled: Enables Management Endpoint Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_ADMIN_PORT_ENABLED`` :proxy.admin.port: The Management Endpoint Port. Supported port range 8081-9999 Default: ``8888`` Reloadable: ``false`` EnvVar: ``PROXY_ADMIN_PORT`` :proxy.admin.http.errorresponse.enabled: Get a detailed error message in case of any HTTP Error (4xx, 5xx). This property can be changed on runtime. Default: ``false`` Reloadable: ``true`` EnvVar: ``PROXY_ADMIN_HTTP_ERRORRESPONSE_ENABLED`` :proxy.health.default.procedures.enabled: Register default health check procedures. See :ref:`Developers Guide ` for prerequisites. Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_HEALTH_DEFAULT_PROCEDURES_ENABLED`` :proxy.health.default.package: Classes within this package will be registered on server startup. See :ref:`Developers Guide ` for prerequisites. Default: ``io.ox.proxy.health.impl.checks`` Reloadable: ``false`` EnvVar: ``PROXY_HEALTH_DEFAULT_PACKAGE`` :proxy.health.jvm.threadcount.max: Health Check Threads- After exceeding this value the health check change to DOWN. Supported range 1 - Integer.MAX_VALUE. This property can be changed on runtime. Default: ``50`` Reloadable: ``true`` EnvVar: ``PROXY_HEALTH_JVM_THREADCOUNT_MAX`` :proxy.health.jvm.heapmemory.maxpercentage: Health Check Memory - After exceeding this value the health check change to DOWN. 0.01 -> 1%, 0.99 -> 99% of max heap. Supported range 0.01 - 0.99. This property can be changed on runtime. Default: ``0.9`` Reloadable: ``true`` EnvVar: ``PROXY_HEALTH_JVM_HEAPMEMORY_MAXPERCENTAGE`` :proxy.health.http: Health Check HTTP - If Endpoint is not available health check change to DOWN. If no value is present health check will be skipped. This property can be changed on runtime. Default: ```` Reloadable: ``true`` EnvVar: ``PROXY_HEALTH_HTTP`` :proxy.admin.openapi.enabled: Creates an additional Open API Endpoint when enabled. Endpoint is then available under ``{{baseUrl}}/openapi``, ``{{baseUrl}}/openapi.json``, ``{{baseUrl}}/openapi.yaml``. Must be set before Server Startup. Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_ADMIN_OPENAPI_ENABLED`` :proxy.admin.properties.sanitizekeys: Property names containing one the given keys will be sanitized when exposing via HTTP API. The values of well known properties will be sanitized even if this parameter is not set. Those values are ``.password,.secret,.key.,.token,.credentials``. By setting this property keys will be added as additional keys to the list. Does not support regular expressions Default: ``false`` Reloadable: ``false`` EnvVar: ``PROXY_ADMIN_PROPERTIES_SANITIZEKEYS`` :proxy.admin.properties.filter: Use positive filter where only property names matches the given value will be exposed via HTTP API. Leave this blank will disable the filter and lead to exposing all properties. Filter does not support regular expressions Default: `` `` Reloadable: ``true`` EnvVar: ``PROXY_ADMIN_PROPERTIES_FILTER`` Sample `````` A sample configuration may look like this: .. literalinclude:: config-examples/application-admin.properties :language: properties .. note:: This configuration will start the management listener on port 8888 and register all default health checks. Empty parameters will fall back to their default. Microprofile Health Check ------------------------- App Suite Proxy comes with an implementation of `Microprofile Health API `_. Some basic health checks are available by default and will be registered when enabled (see :ref:`Settings `). According to the API specification these health checks will be exposed to ``/health`` ``/health/live`` ``/health/ready``. Payload from ``http://:/health`` looks like the following example: .. literalinclude:: config-examples/health-payload.json :language: json Prometheus Metrics ------------------ Monitoring Metrics from server runtime will be exposed under ``/metrics``. The format follows the `Prometheus Format specification `_ . Payload from ``http://:/metrics`` looks like the following example: .. literalinclude:: config-examples/metrics-payload.txt :language: text Open API -------- Management Endpoint comes with an integrated Open API documentation which can be created while server startup, see section :ref:`Settings `. Once enabled the documentation is available at ``/openapi``, ``/openapi.yaml`` and ``/openapi.json``. ``/metrics``. Use this endpoint to import the payload in a tool of your choise e.g. Postman, or use ``/application.wadl`` to help with client generation. Payload from ``/openapi`` looks like the following example: .. literalinclude:: config-examples/openapi-payload.yaml :language: yaml Command Line Tool ================= Appsuite Proxy comes with a command line tool which basically gives access to Proxy`s management API Endpoints. The command line tool can be installed as additional docker image or locally using gradle a task. For more information see project`s readme. Once you have installed command line tool run ``appsuite-proxy --help`` to get a list with possible actions :: root@2a1f20a3b3d7:/usr/local/bin# appsuite-proxy Usage: appsuite-proxy [OPTIONS] COMMAND [ARGS]... Command line tool can be used to perform management tasks from shell which basically invoke Appsuite Proxy`s REST API Endpoints. Options: -u, --baseurl TEXT Base URL to proxy`s management API [default: (http://127.0.0.1:8888)] --debug Show debug output in case of any errors [default: (False)] --version Show the version and exit. -h, --help Show this message and exit. Commands: config Actions calling Appsuite Proxy`s configuration endpoint health Actions calling Appsuite Proxy`s health endpoint metrics Actions calling Appsuite Proxy`s metrics endpoint Run 'appsuite-proxy COMMAND --help' for more information CLI Docker Image ---------------- Alternatively you can use appsuite-proxy-cli docker image which includes the clt. To use it you need just to run the image, e.g. ``docker run ImageId``. This will show you the help text and you can just add options or commands on your next docker run call, e.g. ``docker run ImageId -v config get``.