spec

---
name: gorouter

description: "Gorouter maintains a dynamic routing table based on updates received from NATS and (when enabled) the Routing API. This routing table maps URLs to backends. The router finds the URL in the routing table that most closely matches the host header of the request and load balances across the associated backends."

templates:
  pre-start.erb: bin/pre-start
  post-start.erb: bin/post-start
  setup-jq.erb: bin/setup-jq
  dns_health_check.erb: bin/dns_health_check
  nats_client.erb: bin/nats_client
  gorouter.yml.erb: config/gorouter.yml
  healthchecker.yml.erb: config/healthchecker.yml
  prom_scraper_config.yml.erb: config/prom_scraper_config.yml
  prometheus.crt.erb: config/certs/prometheus/prometheus.crt
  prometheus.key.erb: config/certs/prometheus/prometheus.key
  prometheus_ca.crt.erb: config/certs/prometheus/prometheus_ca.crt
  drain.erb: bin/drain
  uaa_ca.crt.erb: config/certs/uaa/ca.crt
  bpm.yml.erb: config/bpm.yml
  bpm-pre-start.erb: bin/bpm-pre-start
  retrieve-local-routes.erb: bin/retrieve-local-routes
  indicators.yml.erb: config/indicators.yml
  error.html.erb: config/error.html

packages:
  - routing_utils
  - gorouter
  - routing-healthchecker

provides:
  - name: gorouter
    type: http-router
    properties:
    - router.backends.ca

consumes:
- name: nats
  type: nats
  optional: true
- name: nats-tls
  type: nats-tls
  optional: true
- name: routing_api
  type: routing_api
  optional: true

properties:
  router.port:
    description: "Listening Port for Router."
    default: 80
  router.status.port:
    description: "Port for the /health, /varz, and /routes endpoints."
    default: 8080
  router.status.user:
    description: "Username for HTTP basic auth to the /varz and /routes endpoints."
    default: router-status
  router.status.password:
    description: "Password for HTTP basic auth to the /varz and /routes endpoints."
  router.status.enable_nontls_health_checks:
    description: "Toggles whether or not gorouter will listen on a non-tls endpoint for load balancer health checks."
    default: true
  router.status.enable_deprecated_varz_healthz_endpoints:
    description: |
      Toggles whether or not gorouter will respond to the deprecated /healthz,
      /varz, and /routes endpoints on its non-tls load balancer status port.
      Requires 'router.status.enable_nontls_health_checks' to be true.
    default: false
  router.status.routes.port:
    description: "Port used for the /routes endpoint (available on localhost-only)"
    default: 8082
  router.status.tls.port:
    description: "Port used for the TLS listener of the LB healthcheck endpoint"
    default: 8443
  router.status.tls.certificate:
    description: "TLS Certificate used for the TLS listener of the LB healthcheck endpoint"
  router.status.tls.key:
    description: "Private Key used for the TLS listener of the LB healthcheck endpoint"
  router.prometheus.port:
    description: "Port for the prometheus endpoint."
  router.prometheus.server_name:
    description: "The server name used in the certificate for the metrics endpoint."
  router.prometheus.ca_cert:
    description: "TLS CA cert to verify requests to prometheus endpoint."
    default: ""
  router.prometheus.cert:
    description: "TLS certificate for prometheus server."
    default: ""
  router.prometheus.key:
    description: "TLS private key for prometheus server."
    default: ""
  router.requested_route_registration_interval_in_seconds:
    description: |
      On startup, the router will delay listening for requests by this duration to increase likelihood that it has a complete routing table before serving requests.
      The router also broadcasts the same duration as a recommended interval to registering clients via NATS.
      This must be less than 60, otherwise monit will mark the process as failed.
    default: 20
  router.load_balancer_healthy_threshold:
    description: "Time period in seconds to wait until declaring the router instance started after starting the listener socket. This allows an external load balancer time to register the instance as healthy."
    default: 20
  router.balancing_algorithm:
    description: "Algorithm used to distribute requests for a route across backends. Supported values are round-robin and least-connection"
    default: round-robin
  router.balancing_algorithm_az_preference:
    description: |
      Configuration option used in conjunction with the `router.balancing_algorithm` to decide from which
      availability zone to pick a suitable backend. Defaults to "None".
      "none" - There is no preference regarding availability zones. The router uses the 
        `router.balancing_algorithm` across all possible backends in all existing AZs.
      "locally-optimistic" - On the initial attempt to pick a backend, the router will use
        `router.balancing_algorithm` across all backends in the same AZ as the router itself. Subsequent
        retries, in the case of failure or unavailability, will use _all_ available AZs.
    default: "none"
  router.number_of_cpus:
    description: "Number of CPUs to utilize, the default (-1) will equal the number of available CPUs"
    default: -1
  router.debug_address:
    description: "Endpoint for process profiling. For more info see https://github.com/cloudfoundry/debugserver"
    default: "127.0.0.1:17002"
  router.secure_cookies:
    description: "Set secure flag on http cookies"
    default: false
  router.sticky_session_cookie_names:
    description: "The names of the cookies to use for handling sticky sessions"
    default: [ "JSESSIONID" ]
  router.sticky_sessions_for_auth_negotiate:
    description: "Controls whether or not gorouter will apply sticky sessions to request/response flows using 'Authorization: Negotiate'"
    default: false
  router.drain_wait:
    description: |
      Delay in seconds after shut down is initiated before server stops listening.
      During this time the server will reject requests to the /health endpoint.
      This accommodates requests forwarded by a load balancer until it considers the router unhealthy.
    default: 20
  router.drain_timeout:
    description: |
      Delay in seconds after drain wait has completed to allow existing connections to finish their active requests.
      The drain will begin when there are no active connections or until the timeout is reached.
      Any remaining connections that are open when the drain timeout is reached will be closed.
      To reduce the drain time during deploys, set the value of drain timeout below the request timeout.
    default: 900
  router.healthcheck_user_agent:
    description: DEPRECATED. Use /health endpoint on port specified by status.port. User-Agent for the health check agent (usually the Load Balancer).
    example: "ELB-HealthChecker/1.0"
    default: "HTTP-Monitor/1.1"
  router.enable_ssl:
    description: "When enabled, Gorouter will listen on port 443 and terminate TLS for requests received on this port."
    default: false
  router.tls_port:
    description: Listening port for SSL connections to the router, when SSL is enabled.
    default: 443
  router.client_cert_validation:
    description: |
      none - Gorouter will not request client certificates in TLS handshakes, and will ignore them if presented. Incompatible with `forwarded_client_cert: forward` or `sanitize_set`.
      request - Gorouter will request client certificates in TLS handshakes, and will validate them when presented, but will not require them.
      require - Gorouter will fail a TLS handshake if the client does not provide a certificate signed by a CA it trusts. Select this option if your load balancer terminates TLS and does not require client certificates, and the load balancer provides a compatible client certificate of its own to Gorouter in an independent TLS handshake. This option may also be selected for Isolation Segments when Gorouter is the first point of TLS termination. Many clients of CF platform APIs do not present client certificates in TLS handshakes, so the first point of TLS termination for requests to the system domain must not require them. This option has no effect on the HTTP listener; to disable HTTP support set `disable_http: true`.
    default: request
  router.disable_http:
    description: Disables the http listener on port specified by router.port. This cannot be set to true if enable_ssl is false.
    default: false
  router.enable_http2:
    description: Enables support for HTTP/2 ingress traffic to the Gorouter. Also enables the option to use the HTTP/2 protocol for traffic to specified backends.
    default: true
  router.enable_http1_concurrent_read_write:
    description: Enables concurrent request reads and response writes for HTTP/1 requests
    default: false
  router.min_tls_version:
    description: Minimum accepted version of TLS protocol. All versions above this, up to the max_tls_version, will also be accepted. Valid values are TLSv1.0, TLSv1.1, TLSv1.2, and TLSv1.3.
    default: TLSv1.2
  router.max_tls_version:
    description: |
      Maximum accepted version of TLS protocol. Versions below this will, down to the min_tls_version, will also be accepted. Valid values are TLSv1.2 and TLSv1.3.
      Warning: Setting this to TLSv1.3 will cause things to fail with any Java clients using versions of Java without a fix for the following issue: https://bugs.openjdk.java.net/browse/JDK-8236039
    default: TLSv1.2
  router.dns_health_check_host:
      description: "Host to ping for confirmation of DNS resolution, only used when Routing API is enabled"
      default: "uaa.service.cf.internal"
  router.tls_pem:
    description: "Array of private keys and certificates for serving TLS requests. Each element in the array is an object containing fields 'private_key' and 'cert_chain', each of which supports a PEM block. Required if router.enable_ssl is true."
    example: |
      - cert_chain: |
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          -----END CERTIFICATE-----
        private_key: |
          -----BEGIN RSA PRIVATE KEY-----
          -----END RSA PRIVATE KEY-----
  router.ca_certs:
    description: "Required. List of Strings of concatenated certificate authorities in PEM format, used to validate server certificates provided by remote systems. Gorouter also trust certificates signed by well-known CAs and by CA certificates installed on the filesystem. These CA certificates are also used to validate client certificates when router.only_trust_client_ca_certs is false."
  router.client_ca_certs:
    description: "Required. String of concatenated certificate authorities in PEM format, used to validate certificates provided by remote systems. By default, Gorouter will trust certificates signed by well-known CAs and by CA certificates installed on the filesystem."
    default: ""
  router.only_trust_client_ca_certs:
    description: "When router.only_trust_client_ca_certs is true, router.client_ca_certs are the only trusted CA certs for client requests. When router.only_trust_client_ca_certs is false, router.client_ca_certs are trusted in addition to router.ca_certs and the CA certificates installed on the filesystem. This will have no affect if the `router.client_cert_validation` property is set to none."
    default: false
  router.backends.max_attempts:
    description: |
      Maximum number of attempts on failing requests against backend routes.
      The number of attempts per request is limited by the number of endpoints on the route, regardless of this setting.
      This includes CF apps and route-registrar endpoints.
      The minimum value for this setting is 1. This prevents gorouter from getting blocked by indefinite retries.
    default: 3
  router.backends.ca:
    description: Certificate authority that was used to sign certificates for TLS-registered backends. In PEM format.
  router.backends.cert_chain:
    description: Certificate chain used for client authentication to TLS-registered backends.  In PEM format.
  router.backends.private_key:
    description: Private key used for client authentication to TLS-registered backends.  In PEM format.
  router.ssl_skip_validation:
    description: "Skip validation of TLS certificates received from route services and UAA."
    default: false
  router.cipher_suites:
    description:
      An ordered, colon-delimited list of golang supported TLS cipher suites in OpenSSL or RFC format.
      The selected cipher suite will be negotiated according to the order of this list during a TLS handshake.
      See https://github.com/golang/go/blob/release-branch.go1.21/src/crypto/tls/cipher_suites.go#L663-L690 for golang supported cipher suites.
      The first four of these are supported for TLSv1.0/1.1 only.
      See https://www.openssl.org/docs/man1.1.0/apps/ciphers.html for a mapping of OpenSSL and RFC suite names.
    default: "ECDHE-RSA-AES128-GCM-SHA256:TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
  router.forwarded_client_cert:
    description: |
      How to handle the x-forwarded-client-cert (XFCC) HTTP header. Possible values are:
      - always_forward: Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.
        Use this value when your load balancer is forwarding the client certificate and requests are not forwarded to Gorouter over mTLS.
        In the case where the connection between load balancer and Gorouter is mTLS, the client certificate received by Gorouter in the TLS handshake will not be put in the XFCC header.
      - forward: Forward the XFCC header received from the client only when the client connection is mTLS.
        This is a more secure version of `always_forward`. The client certificate received by Gorouter in the TLS handshake will not be put in the XFCC header.
        Requires `client_cert_validation: request` or `require`.
      - sanitize_set: Strip any instances of XFCC headers from the client request.
        When the client connection is mTLS, the client certificate received by Gorouter in the TLS handshake will be put in this header.
        Values will be base64 encoded PEM. Use this value when Gorouter is the first component to terminate TLS.
        Requires `client_cert_validation: request` or `require`.
    default: always_forward
  router.route_services.max_attempts:
    description: |
      Maximum number of attempts on failing requests against route service URLs.
      The minimum value for this setting is 1. This prevents gorouter from getting blocked by indefinite retries.
    default: 3
  router.route_services.cert_chain:
    description: Certificate chain used for client authentication to TLS-registered route services.  In PEM format.
  router.route_services.private_key:
    description: Private key used for client authentication to TLS-registered route services.  In PEM format.
  router.route_services_secret:
    description: "Support for route services is disabled when no value is configured. A robust passphrase is recommended."
    default: ""
  router.route_services_internal_lookup:
    description: "setting this property to true causes gorouter to bypass another trip through the load balancer when directing traffic to a route service that is a known route by the gorouter."
    default: false
  router.route_services_internal_lookup_allowlist:
    description: "a list of host names for route services that should be resolved internally. Each entry can be a fully qualified domain name or DNS wildcard (i.e. wildcard on 1 segment of a subdomain). If the list is empty, it is not in effect and internal lookup will be attempted for all host names, which can lead to CVE-2019-3789. Please turn on internal lookup only with an allowlist."
    default: []
  router.route_services_internal_server_port:
    description: "Gorouter will use this port for internal route services."
    default: 7070
  router.route_services_secret_decrypt_only:
    description: "To rotate keys, add your new key here and deploy. Then swap this key with the value of route_services_secret and deploy again."
    default: ""
  router.route_services_recommend_https:
    description: "Route Services are told where to send requests after processing using the X-CF-Forwarded-Url header. When this property is true, the scheme for this URL is https. When false, the scheme is http. As requests from Route Services to applications on CF transit load balancers and gorouter, disable this property for deployments that have TLS termination disabled."
    default: true
  router.route_services_timeout:
    description: "Expiry time of a route service signature in seconds"
    default: 60
  router.route_services_strict_signature_validation:
      description: "Enforce strict validation of a route service signature"
      default: false
  router.max_header_kb:
    description: |
        Deprecated, use router.max_request_header_kb instead which is equivalent to this option.
    default: 1024 # 1Mb
  router.max_request_header_kb:
    description: |
        This value controls the maximum number of bytes (in KB) the gorouter will read
        parsing the request header's keys and values, including the request
        line. It does not limit the size of the request body. Requests with
        larger headers will result in a 431 status code. Must be between 1 and 1024kb.
        Note: This value takes precedence over router.max_header_kb but has no default to not break
        existing setups. If you previously configured router.max_header_kb it is recommended to
        switch to this property instead.
    example: 1024 # 1Mb
  router.max_response_header_kb:
    description: |
        This value controls the maximum number of bytes (in KB) the gorouter will read
        parsing the response header's keys and values, including the request
        line. It does not limit the size of the response body. Responses with
        larger headers will result in a 502 status code. A limit of zero or less will
        result in the default GoLang limit being used.
    default: 0
  router.max_request_headers:
    description: |
        This value controls the maximum number of headers gorouter will accept in a
        single request. Only the header keys are counted and values separated by commas
        are not considered additional headers. Setting this to zero or less disables the
        limit. Must be at least 30 for CF to function properly (enforced).
    default: 0
  router.max_response_headers:
    description: |
        This value controls the maximum number of headers gorouter will accept in a
        single response. Only the header keys are counted and values separated by commas
        are not considered additional headers. Setting this to zero or less disables the
        limit. Must be at least 30 for CF to function properly (enforced).
    default: 0
  router.extra_headers_to_log:
    description: "An array of headers that access log events will be annotated with. This only applies to headers on requests."
    default: []
  router.logging_level:
    description: "Log level for router"
    default: "info"
  router.enable_log_attempts_details:
    description: "Log additional fields in the access log that provide more details on the specific timings and attempts performed towards endpoints."
    default: false
  router.logging.syslog_tag:
    description: "Tag to use when writing syslog messages"
    default: "vcap.gorouter"
  router.logging.syslog_message_limit:
    description: "Limit the number of bytes per access log written to syslog. A value of zero disables the limit."
    default: 0
  router.logging.syslog_addr:
    description: "Address of a syslog server to send access logs"
    default: "localhost:514"
  router.logging.syslog_network:
    description: "Network protocol to use when connecting to the syslog server. Valid values are 'tcp', 'udp', <empty>. When choosing an empty string value, the local syslog daemon is used."
    default: "udp"
  router.logging.extra_access_log_fields:
    description: |
      An array of additional access log fields to log. Any new log fields will only be exposed via
      this property and operators have to explicitly enable them. This is done to prevent breaking
      log parsing in existing setups by the introduction of new fields. Does not affect stdout /
      stderr logs.
      Available fields are: local_address
    default: []
  router.logging.format.timestamp:
    description: |
      Format for timestamp in component logs. Valid values are 'rfc3339', 'deprecated', and 'unix-epoch'."
      'rfc3339' is the recommended format. It will result in all timestamps controlled by gorouter to be in RFC3339 format, which is human readable. This includes stdout, pre-start, and post-start logs. This does not include stderr logs from golang libraries.
      'deprecated' will result in all timestamps being in the format they were before the rfc3339 flag was introduced. This format is different for different logs. We do not recommend using this flag unless you have scripts that expect a particular timestamp format.
      'unix-epoch' is an old flag that we do not recommend using, but we are keeping for backwards compatibility. It will result in the gorouter logs to be in unix-epoch format. This does not effect pre-start or post-start logs. This does not effect stderr logs from golang libaries.
    default: "rfc3339"
  router.enable_proxy:
    description: "Enables support for the popular PROXY protocol, allowing downstream load balancers that do not support HTTP to pass along client information."
    default: false
  router.max_idle_connections:
    default: 100
    description: |
      When 0, keepalive connections are disabled.
      When a number greater than zero, keepalives are enabled, and Gorouter will keep up to this number of idle keepalive connections open across all backends.
      When keepalive connections are enabled, the maximum number of idle keepalive connections Gorouter will keep open to an individual backend is 100, which cannot be changed.
  router.keep_alive_probe_interval:
    default: 1s
    description: Interval between TCP keep alive probes. Value is a string (e.g. "10s")
  router.keep_alive_100_continue_requests:
    description: "If set gorouter reuses backend connection for requests expecting 100-Continue"
    default: false
  router.force_forwarded_proto_https:
    description: "Enables setting X-Forwarded-Proto header if SSL termination happened upstream and incorrectly set the header value. When this property is set to true gorouter sets the header X-Forwarded-Proto to https. When this value set to false, gorouter set the header X-Forwarded-Proto to the protocol of the incoming request"
    default: false
  router.sanitize_forwarded_proto:
    description: |
      When true, Gorouter will strip the X-Forwarded-Proto header when present in client request and set it to the scheme of the request.
      When false, Gorouter will pass through the value of this header.
      When force_forwarded_proto_https: true, this property will be ignored.
      Otherwise,  we recommend setting the property to true if Gorouter is the first component to terminate TLS, and set to false when your load balancer is terminating TLS and setting the X-Forwarded-Proto header.
    default: false
  router.http_rewrite.responses.add_headers_if_not_present:
    description: |
      (optional, array pairs name-value) If set, gorouter will add the given headers into the response if they are not already present.
    example:
    - name: "Strict-Transport-Security"
      value: "max-age=31536000; includeSubDomains; preload"
    - name: "Cache-Control"
      value: "no-cache"
  router.http_rewrite.responses.remove_headers:
    description: |
      (optional, array pairs name-value) List of HTTP headers that will be stripped from responses.
    example:
    - name: X-Vcap-Request-Id
    - name: Accept-Ranges
  router.hop_by_hop_headers_to_filter:
    description: |
        (optional, array value) List of HTTP Headers that are filtered for
        Hop-By-Hop Connection header.
        When clients make requests to the gorouter and the gorouter proxies
        their request, these HTTP Headers will be automatically be removed from
        the request's Connection header and sent as normal headers to the
        target backend. This list *also* specificies the Headers that can be
        returned by the backend; i.e. if a client attempts to send one of these
        Headers in their Connection Header to gorouter and it's *NOT* filtered,
        the header will *NOT* be returned to client properly after proxying the
        request.
    default:
    - X-Forwarded-For
    - X-Forwarded-Proto
    - B3
    - X-B3
    - X-B3-SpanID
    - X-B3-TraceID
    - X-Request-Start
    - X-Forwarded-Client-Cert
  router.frontend_idle_timeout:
    description: |
      (optional, integer) Duration in seconds to maintain an open connection when client supports keep-alive.
      This property must be configured with regards to how an IaaS-provided load balancer behaves in order to prevent connections from being closed prematurely.
      Generally, this timeout must be greater than that of the load balancer. As examples, GCP HTTP(S) load balancer has a default timeout of 600 seconds so a value greater than 600 is recommended and AWS ELB has a default timeout of 60 seconds so a value greater than 60 is recommended.
      However, depending on the IaaS, this timeout may need to be shorter than the load balancer's timeout, e.g., Azure's load balancer times out at 240 seconds (by default) and GCP TCP load balancer times out at 600 seconds without sending a TCP RST to clients, so a value lower than this is recommended in order to force it to send the TCP RST.
    default: 900
  router.read_header_timeout:
    description: "The amount of time allowed to read request headers."
    default: 0
  router.backends.max_conns:
    description: "Maximum concurrent TCP connections per backend. When set to 0 there is no limit"
    default: 500
  router.tracing.enable_zipkin:
    description: "Enables the addition of the X-B3-Trace-Id header to incoming requests. If the header already exists on the incoming request, it will not be overwritten."
    default: false
  router.tracing.enable_w3c:
    description: |
      Enables the addition of the W3C tracing headers to incoming requests.
      If the traceparent and tracestate headers exist on the incoming request, they will be updated, if they do not exist they will be created.
      The W3C tracing specification has more information: https://www.w3.org/TR/trace-context/
    default: false
  router.tracing.w3c_tenant_id:
    description: |
      Specifies the tenant ID to use in the W3C tracestate header, only used when W3C tracing headers are enabled.
      If specified, the tracestate identifier will be "tenant-id@gorouter" where "tenant-id" is the value specified.
      If not specified, the tracestate identifier will be "gorouter"
      The W3C tracing specification has more information: https://www.w3.org/TR/trace-context/
    default: ""
  router.isolation_segments:
    description: "Routes with these isolation segments will be registered. Used in combination with routing_table_sharding_mode."
    default: []
  router.routing_table_sharding_mode:
    description: |
      all: all routes will be registered.
      shared-and-segments: both routes for the configured isolation segments and those that do not have an isolation segment specified will be registered.
      segments: only routes for the configured isolation segments will be registered.
    default: all
  router.disable_log_forwarded_for:
    description: |
      (optional, boolean) When false, gorouter will include the value of the HTTP header X-Forwarded-For which it sends to a backend.
      When true, the value of this header will not be logged. This is to comply with EU regulations that do not allow persisting personal data.
    default: false
  router.disable_log_source_ip:
    description: |
      (optional, boolean) When false, gorouter will include the source IP in access logs. When true, the source IP will not be logged.
      This is to comply with EU regulations that do not allow persisting personal data. When Gorouter is behind an L3 load balancer that
      persists the IP of the originating client, set this to true to comply with GDPR.
    default: false
  router.redact_query_parameters:
    description: |
      (optional, string) This option can be used to hide potentially sensitive information on GET request query parameters in the access log.
      none: Log all query parameters on GET requests. E.g. GET /users?name=peter
      all: Log no query parameters on GET requests.   E.g. GET /users
      hash: Log query parameters in hashed form only. E.g. GET /users?hash=a6909eece4005d85fb1894cc4efa38564b9c30c3
    default: none
  router.html_error_template:
    description: |
      (optional) When given a valid Go template, gorouter will generate HTML error pages instead of plain text error pages.
      The following is an example of a valid HTML template:

      <html>
        <body>
          Code: {{ .Status }} {{ .StatusText }}
          Message: {{ .Message }}
          Cause: {{ .Header.Get "X-Cf-RouterError" }}
        </body>
      </html>
    default: ""

  nats.user:
    description: User name for NATS authentication
    example: nats
  nats.password:
    description: Password for NATS authentication
    example: natSpa55w0rd
  nats.port:
    description: TCP port of NATS servers
    example: 4222
  nats.machines:
    description: IPs of each NATS cluster member
    example: |
      - 192.168.50.123
      - 192.168.52.123
  nats.tls_enabled:
    description: When enabled, Gorouter will prefer to connect to NATS over TLS
    default: false
  nats.ca_certs:
    description: "String of concatenated certificate authorities in PEM format, used to validate certificates presented by NATS."
  nats.cert_chain:
    description: Certificate chain used for client authentication to NATS. In PEM format.
  nats.private_key:
    description: Private key used for client authentication to NATS. In PEM format.

  router.offset:
    description:
    default: 0
  router.trace_key:
    description:
      If the X-Vcap-Trace request header is set and has this value,
      trace headers are added to the response.
    default: 22
  request_timeout_in_seconds:
    description: |
      This configures an entire request timeout.
      Requests from router to backend endpoints that are longer than this duration will be canceled and logged as
      `backend-request-timeout` errors. If set to 0 this timeout is disabled.
    default: 900
  endpoint_dial_timeout_in_seconds:
    description: |
      Maximum time in seconds for gorouter to establish a TCP connection with a backend. This timeout comes before `tls_handshake_timeout_in_seconds`
      and `request_timeout_in_seconds`.
    default: 5
  websocket_dial_timeout_in_seconds:
    description: |
      Maximum time in seconds for gorouter to establish a websocket upgrade for the websocket ForwardIO connection with a backend.
      This timeout comes before `tls_handshake_timeout_in_seconds` and `request_timeout_in_seconds`. When not set, defaults to `endpoint_dial_timeout_in_seconds`.
    default: endpoint_dial_timeout_in_seconds
  tls_handshake_timeout_in_seconds:
    description: |
      Maximum time in seconds for gorouter to establish a TLS connection with a backend container. This timeout is for establishing
      the TLS connection only. Actual HTTP request timeout is defined by `router.request_timeout_in_seconds`.
    default: 10

  metron.port:
    description: "The port used to emit dropsonde messages to the Metron agent."
    default: 3457

  uaa.clients.gorouter.secret:
    description: "Password for UAA client for the gorouter."
  uaa.token_endpoint:
    description: "UAA token endpoint host name. Do not include a scheme in this value; TCP Router will always use TLS to connect to UAA."
    default: uaa.service.cf.internal
  uaa.ssl.port:
    description: "Secure Port on which UAA is running."

  routing_api.enabled:
    description: "When enabled, GoRouter will fetch HTTP routes from the Routing API in addition to routes obtained via NATS."
    default: false
  routing_api.uri:
    description: "URL where the routing API can be reached internally"
    default: https://routing-api.service.cf.internal
  routing_api.port:
    description: "Port on which Routing API is running."
  routing_api.auth_disabled:
    description: "When false, Routing API requires OAuth tokens for authentication."
    default: false
  routing_api.ca_certs:
    description: "String of concatenated certificate authorities in PEM format, used to validate certificates provided by the routing API."
  routing_api.cert_chain:
    description: Certificate chain used for client authentication to the routing API. In PEM format.
  routing_api.private_key:
    description: Private key used for client authentication to the routing API. In PEM format.

  router.write_access_logs_locally:
    description: "Enables writing access log to local disk."
    default: true
  router.enable_access_log_streaming:
    description: "Enables streaming access log to syslog server."
    default: false
  router.suspend_pruning_if_nats_unavailable:
    description: |
      Suspend pruning of routes when NATs is unavailable and maintain the
      current routing table. Note: only non-TLS routes are ever pruned.
    default: true

  uaa.ca_cert:
    description: "Certificate authority for communication between clients and uaa."
    default: ""

  router.set_kernel_parameters:
    description: |
      Optimize kernel networking settings for GoRouter. If you deploy GoRouter in a container set this to false.
      This configures the following kernel parameters:
        * Increases the number of allowed IP local port ranges specified by the `router.ip_local_port_range` value.
        * Reserves ports configured for gorouter and other bosh components via /proc/sys/net/ipv4/ip_local_reserved_ports.
        * Reduces the timeout of TCP_FIN_TIMEOUT, so that TCP/IP can release closed connections faster, making more
          resources available for new connections.
        * Disables TCP_TW_RECYCLE to enable fast recycling of TIME_WAIT sockets.
        * Enables TCP_TW_REUSE to reuse sockets in TIME_WAIT state for new connections when it is safe from protocol viewpoint
        * Increase the number of max queued connections than are allowed by default.
    default: true

  router.ip_local_port_range:
    description: "Ephemeral port range. `router.set_kernel_parameters` must be enabled."
    default: "1024 65535"

  for_backwards_compatibility_only.empty_pool_response_code_503:
    description: |
      This property is provided for backwards compatibility reasons. We recommend leaving it set to true.
      When it set to true, the gorouter will return a 503 when a route is known but there is nothing in the pool available to handle the request. When false, the gorouter will return a 404.
    default: true

  for_backwards_compatibility_only.empty_pool_timeout:
    description: |
      This property depends on empty_pool_response_code_503. If empty_pool_response_code_503 is set to true, then gorouter will consider empty_pool_timout parameter.
      If set to 0, gorouter will remove empty pools after pruning their endpoints. The gorouter will respond with 404 code.
      If set to different value, gorouter will wait until this timeout is reached then will delete the empty pools. Before pool deletion, gorouter will continue to respond with 503 code.
      The type of empty_pool_timeout is time.Duration. We have to specify the unit of time. For example, a value "10s" means 10 seconds.
    default: "0s"

  router.per_app_prometheus_http_metrics_reporting:
    description: "Reports the http latency in a prometheus histogram for each application"
    default: false

  router.per_request_metrics_reporting:
    description: "Report the metrics latency, latency.<component> and route_lookup_time for each request"
    default: true

  router.send_http_start_stop_server_event:
    description: "Send a httpstartstopevent of type server for each request"
    default: true

  router.send_http_start_stop_client_event:
    description: "Send a httpstartstopevent of type client for each request"
    default: true

  router.max_open_files:
    description: "The number of file descriptors a router can have open at one time"
    default: 100000

  router.enable_verify_client_certificate_metadata:
    description: |
        Enable additional client certificate verification via verify_client_certificate_metadata (see below).
    default: false
  router.verify_client_certificate_metadata:
    description: |
      Additional client certificate verification, after the certificate was validated using the regular mTLS mechanism and is issued using one of the CAs in `client_ca_certs`.
      The additional verification limits the allowed client certificates for a given signing CA (identified by its distinguished name) to certificates with subjects provided in the list of valid subjects. Within the certificate chain there may be more than one CA certificates (e.g. intermediate CA certificates). The `issuer_in_chain` must match one of the CA certificates in the chain.
      Each list entry contains an issuer_in_chain with a corresponding list of valid subjects. Each issuer_in_chain must match one of the certificates in `client_ca_certs`. When an issuer_in_chain is defined that does not match, this raises an error during templating time and at startup in gorouter.
      - issuer_in_chain:
          common_name: ""
          serial_number: ""
          country: []
          organization: []
          organizational_unit: []
          locality: []
          province: []
          street_address: []
          postal_code: []
        valid_cert_subjects:
          - common_name: ""
            serial_number: ""
            country: []
            organization: []
            organizational_unit: []
            locality: []
            province: []
            street_address: []
            postal_code: []
    default: []

  healthchecker.failure_counter_file:
    description: "File used by the healthchecker to monitor consecutive failures."
    default: /var/vcap/data/gorouter/counters/consecutive_healthchecker_failures.count

  go.httplaxcontentlength:
    description: |
        Environment Flag to temporarily allow requests containing an invalid, empty `Content-Length` header for backwards compatibility.
        This toggle allows operators to add the `GODEBUG` field `httplaxcontentlength=1`, as allowable per the [go 1.22 release documentation](https://tip.golang.org/doc/go1.22#minor_library_changes).
        Defaults to `false` as the default behavior in go 1.22+ is to reject these requests.
    default: false