Server configuration
nevisProxy server properties are configured via the four tags Service, Core, Timer, and Server. The Qos tag defines some frequently used attributes of Apache's quality of the service module mod_qos. By setting the Qos tag parameters, you enable a basic protection against denial of service (DoS) attacks. The Qos tag is optional.
Service
The attributes in the following table are only relevant for integration purposes and are mainly documented here as a reference. If nevisProxy is installed using the delivered package, none of these parameters need to be changed. The Service section does not contain any operation-relevant parameters (e.g., scaling).
commandLine
Type: String
Usage Constraints: optional, advanced
Default: <spool_dir>/run
The attribute configures the command line arguments that will be used for starting the server. For example the argument commandLine="-X" starts the Apache server in debug mode. With the argument NAVAJOgroup=<group-name> the group of the initial process can be configured. If configured, a setgid(..) call will be made. If an error occurs, an error message will be traced on stderr but without terminating the process.
hostTemplate
Type: String
Usage Constraints: required, advanced
Default: /opt/nevisproxy/etc/host2.template
Specifies the path to the template file used for creating the host part of the generated Apache configuration file (httpd.conf). It is not recommended to change this setting.
name
Type: String
Usage Constraints: optional, advanced
Default: isi3web
The attribute 'name' is a logical name. It is reserved for future use, e.g. running several services in one carrier server. This value should not be changed.
spoolDir
Type: String
Usage Constraints: required, advanced
Default: <spool_dir>
The path of the spooldir, i.e. the directory that contains the directory 'logs' for log files and 'run' for runtime data. This value should not be changed (must not be an NFS-mounted directory).
serverTemplate
Type: String
Usage Constraints: required, advanced
Default: </opt/nevisproxy/etc/server2.template
The attribute 'serverTemplate' specifies the path to the template file used to create the server part of the generated Apache 2 configuration file. Should not be changed.
verbose
Type: boolean
Usage Constraints: optional
Default: false
The attribute 'verbose' specifies server verbosity. If set to 'true', the message of all caught exceptions is sent to the client. Should be set to 'false' in production.
crashRecoveryStrategy
Type: enum
Possible values: recover, block, kill
Usage Constraints: optional, advanced
Default: recover
Specifies what should happen after a worker crash. By default, the child process is recovered by the parent process. This is the recommended strategy for classic deployments. If block is configured, after a worker crash every request will be blocked by 503 Service Unavailable status code. If kill is configured, the whole nevisproxy process (including the parent process) will be killed. This works only if the owner of the child process has the rights to kill the parent process (for example in some Kubernetes setups). If the parent cannot be killed, then the behaviour will be the same as block. The strategies block and kill are mainly designed for Kubernetes setups with an automated liveness monitoring, so the given pod can be terminated normally in case of a crash. If you set block or kill for a classic deployment, make sure to setup an automated procedure to restart nevisProxy after a crash. Note for testing: with the strategy block and kill, the blocking takes place only if at least one request is in processing when the crash occurs.
Core
The attributes in the following table are only relevant for integration purposes and are mainly documented here for reference. If nevisProxy is installed using the delivered package, none of these parameters needs to be changed. The Core section does not contain any operation-relevant parameters.
workDir
Type: String
Usage Constraints: required
Default: <spool_dir>/run
The attribute workDir configures the directory for the internal files. Should not be changed (may not be an NFS-mounted directory).
Timer
Timers are used to trigger asynchronous functions like the periodic check of the session cache for expired sessions.
periodicity
Type: Integer
Unit: seconds
Default: 60
Configures the periodicity of the internal timer. A session with an absolute timeout of 2 hours would therefore have a real maximum lifetime of 2 hours and 60 seconds, in this case. Setting the value to a lower number, in turn, leads to more load.
OpenTelemetry
The OpenTelemetry configuration tag integrates the OpenTelemetry standard to export observability data to a variety of open source and commercial backends.
This tag contains the tags Trace and Metrics.
Trace
The Trace configuration tag contains the values that are used to send tracing information to the OpenTelemetry service.
If no Trace section is configured, the following default values will be used (which may differ from the default values below):
PropagateContextExtract: true
PropagateContextInject: true
Sampler: AlwaysOff
PropagateTraceparentHeader: false
ExporterType
Type: Enum
Possible values: http, https, grpc
Default: http
Configures the protocol used for communicating with the traces endpoint.
See also section HttpsExporter for further information about the ExporterType https and grpc.
ExporterAddress
Type: String
Usage Constraints: required if DeploymentEnvironment is set
Syntax: <hostname>:<port>
Target URL to which the exporter sends spans. The /v1/traces path is automatically attached to it.
PropagateContextExtract
Type: Boolean
Usage Constraints: optional
Default: true
If present, extracts the trace context from the HTTP request header and sets it as parent for the current span.
PropagateContextInject
Type: Boolean
Usage Constraints: optional
Default: true
Injects the current context (span ID, trace ID, etc.) as a HTTP header to the request.
It's not recommended to set this parameter to false because this will disable the propagation of the traceparent header to the other Nevis components which could break the tracing for those components.
ResourceServiceName
Type: String
Usage Constraints: optional
Default: nevisproxy
Allows the configuration of the service.name key-value pair resource attribute.
DeploymentEnvironment
Type: String
Usage Constraints: optional
Default: not set
Allows the configuration of the deployment.environment.name key-value pair resource attribute.
CaptureRequestHeaders
Type: String
Usage Constraints: optional
Default: Content-Type, Content-Length, User-Agent, Referer, Host, X-Forwarded-For
A comma-separated list of HTTP header names. HTTP client instrumentation will capture HTTP request header values for all configured header names.
CaptureResponseHeaders
Type: String
Usage Constraints: optional
Default: Content-Type, Content-Length, Content-Encoding, Location, Server, Connection, Keep-Alive, X-Forwarded-For
A comma-separated list of HTTP header names. HTTP client instrumentation will capture HTTP response header values for all configured header names.
Sampler
Type: Enum
Possible values: AlwaysOn, AlwaysOff, ParentBased:<delegate_sampler>, TraceIdRatio:<ratio>
Usage Constraints: optional
Default: AlwaysOn
Configures the available head sampling methods. Possible values are:
AlwaysOn: Samples every trace. With high traffic in a production application it may cause significant overhead.AlwaysOff: Samples no traces. NevisProxy still generates the spanID for internal trace ID.TraceIdRatio:<ratio>: Samples a given fraction of traces based on the configuredratio.ParentBased:<delegate_sampler>: Makes the decision based on the parent of the span. If the span has a parent, the sampler flag of the parent span will decide. If there is no parent span, the delegate sampler is used, that can be any of the samplers above.
PropagateTraceparentHeader
Type: Boolean
Usage Constraints: optional
Default: false
Controls if the traceparent header should be propagated back to the frontend with the response.
If enabled, the parameter PropagateContextInject has to be true.
MaxQueueSize
Type: Integer
Usage Constraints: optional
Default: 2048
The maximum buffer/queue size. After the size is reached, spans are dropped.
ScheduleDelay
Type: Integer (milliseconds)
Usage Constraints: optional
Default: 5000
The time interval in milliseconds between two consecutive exports.