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).
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| commandLine | string optional, advanced, supports variable replacement | The attribute 'commandLine' configures the command line arguments that will be used for starting the server. Example: commandLine="-X" starts the Apache server in debug mode. With the commandline 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 | string required, advanced, supports variable replacement default:/opt/nevisproxy/etc/host2.template | The attribute 'hostTemplate' 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 | string optional, advanced, supports variable replacement 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 | string required, advanced, supports variable replacement 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 | string required, advanced, supports variable replacement 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. (Changing that file is a way of including additional Apache1/2 modules. However, that should not be necessary. Contact Nevis if you think you need additional modules.) |
| verbose | boolean: true, false optional, troubleshooting 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. |
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 (except for the parameter 'memorySize' that may need to be increased for huge reverse proxy setups). The Core section does not contain any operation-relevant parameters (even though the runtime model and memory parameters may be of interest).
Runtime model, memory type The runtime model and the memory type used (depending on whether Apache1 or Apache2 is used) are specified in the Core configuration tag.
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| memoryProtection | boolean: true, false optional, advanced default: true | The attribute memoryProtection configures memory protection. After initialization and loading of all web applications, the container memory is write protected. This is possible only if memory type is set to ’shared’. Use of memory protection is recommended for the following reasons: The server can be restarted and current session context (authenticated users) is kept. Vendor code, that violates memory, is likely to not being able to corrupt nevisProxy runtime structures and user session context. Must not be changed. |
| memorySize | integer required, advanced, supports variable replacement default: 10’000’000 | The attribute memorySize specifies the amount of memory to be allocated. This memory is used to store the nevisProxy’s runtime structures. Memory requirements depend mainly on the size and number of the web applications to be loaded. The used memory, i.e. shared or heap, is configured in the Core element. (After booting the service, a log entry shows used and available memory. This information can be used for optimizing the configuration.) This parameter has to be increased if starting of nevisProxy failed due to out of memory errors. The default of 10 MB is about 10 times higher than a usual reverse proxy setup requires. See also "Appendix G - Sizing Parameters in the Nevis Proxy". |
| memoryType | enumeration: heap, shared optional, advanced default: shared | The attribute memoryType is used to configure the memory model used. Can be changed for performance reasons. |
| memoryAnonomous | boolean default: true | The attribute memoryAnonymous configures memory mapping. If set to ’false’, the shared memory will be mapped to a file <workDir>/shared_map_XXXXXX. Otherwise it will be mapped anonymously. |
| workDir | string required, advanced, supports variable replacement 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). |
| RLIMIT_NOFILE | integer optional, basic default: 1024 | Deprecated This attribute is deprecated. The attribute RLIMIT_NOFILE limits the maximum number of file descriptors. Must be increased if the server is running out of file descriptors. 1024 is an OS default, whereas 4096 is a common value for large scale proxies (for example, many concurrently active threads, many backends with enabled connection pooling). For the possible configuration of other resource limits, see the navajo_1_0.dtd. |
Timer
Timers are used to trigger asynchronous functions like the periodic check of the session cache for expired sessions.
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| periodicity | integer optional, advanced, supports variable replacement default: 60 | The attribute periodicity configures the periodicity of the internal timer for releasing unused resources. 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. |
Quality of service (Qos)
The QoS element has been deprecated. To configure QoS directives, use an ApacheConfigFilter instead. For more information, see the chapter Attack prevention strategies by mod_qos.
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. The following table describes the Qos attributes:
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| libname | string optional, supports variable replacement default: "@PKGHOME@/lib/libmodqos_ap${HTTPD_LIB_VERSION}.so.1" | Deprecated The parameter libname is deprecated. The mod_qos library is now linked in inside the proxy. This attribute defines the path to the library of the mod_qos module. |
Usually, the path to the mod_qos library is as follows:
/opt/nevisproxy/lib/libmodqos_ap_${HTTPD_LIB_VERSION}.so.1
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| SrvMinDataRate | bytes per second, max. bytes per second, number of connections optional, supports variable replacement default: 75 300 – | This attribute defines the minimum throughput a client must generate (throughput = bytes sent/received by the client per second). If the client does not fulfill the required minimum throughput rate, the server disconnects the client. The attribute includes three parameters (SrvMinDataRate="xxx yyy zzz"). The first parameter "xxx" defines the minimum throughput a client must generate to keep the client connection open. The system automatically increases the required minimum throughput in relation to the number of concurrent clients sending/receiving data. This is a protection against "slow" clients jamming the TCP connection. The second parameter "yyy" defines the "maximum" minimum throughput. When the server is busy and there are no free connections, the client must achieve this throughput rate to stay connected. The third parameter "zzz" defines the required number of parallel client connections to enable the attribute. As long as the number of connections is below the defined number, the attribute is inactive. If you do not define this third parameter, the attribute is active as soon as the first connection to the server is established. |
| SrvMaxConnClose | number optional, supports variable replacement default: 85% | This attribute specifies the maximum number of concurrent connections that is accepted to keep the TCP connection between clients and server alive. If the number of connections exceeds this threshold, the server disables the keep-alive feature. Define the maximum number of connections as a percentage of the MaxClients attribute in the Server tag (see the table in the chapter Server. |
| SetEnvResHeaderMatch | header field name, regular expression (regex)optional, supports variable replacement default: Set-Cookie Navajo | This attribute copies the HTTP response header onto the request environment variables. As a precondition, the regular expression defined in the attribute must match the value of the relevant header field.E.g., the attribute default is "Set-Cookie Navajo". "Set-Cookie" is the header field name, "Navajo" the regular expression. Suppose that in the HTTP response header of a certain request the Set-Cookie field is set as follows: Set-Cookie: Navajo=vjnfvjkbiostöhgflvjyläbfgbbThis matches the regular expression defined in the attribute. So in this case, the variable "Set-Cookie Navajo=vjnfvjkbiostöhgflvjyläbfgbb" is set in the request environment variables. |
| SetEnvIf | env-variable1, env-variable2, variable=value optional, supports variable replacement default: Set-Cookie !QSNOT QS_Block=yes | The SetEnvIf attribute defines environment variables based on the request variables. This attribute makes it possible to combine multiple variables into a new event type.Specifically, the attribute sets "variable=value" if the request variable list includes variable1 AND variable2 (not case sensitive). You specify variable1, variable2 and variable=value in the attribute definition. E.g., the attribute default is "Set-Cookie !QSNOT QS_Block=yes". Here, "Set-Cookie" is variable1, "!QSNOT" is variable2. If both "Set-Cookie" and "!QSNOT" are part of the request variables list, the attribute sets the environment variable QS_Block.We recommend using the following attribute value (instead of the default): "NAVAJO_HTTPSESS_CREATED !QSNOT QS_Block=yes". By doing so, the previous attribute SetEnvResHeaderMatch is obsolete. |
| ClientEventBlockCount | number, seconds optional, supports variable replacement default: 100 300 | This attribute defines the maximum number of events that the client is allowed to trigger within the defined time interval. When this number is reached, the server blocks the client IP (connection) for the rest of the interval.E.g., suppose the maximum number of events is "100" and the time interval "300" seconds or five minutes (this is the default). Now if the client has reached the threshold of 100 events already after three minutes, then the server blocks the client connection for the remaining two minutes (of the five minutes time interval). |
| SrvMaxConnPerIP | <number>default: 0 | Defines the maximum number of connections per source IP address for this server (virtual host). If the number of busy connections exceeds the limit set here, the request will be blocked. The <connections> argument defines the number of busy connections of the server (all virtual hosts) to enable the limitation set with this attribute. The default is "0". This means that the limitation is always enabled, even the server is idle. |
Server
The Server configuration tag contains the values that are used for the server part of the generated Apache configuration. The next table describes the relevant attributes. Note that all these attributes support variable replacement.
All listed parameters are directives of the Apache carrier server. They are documented in the corresponding Apache documentation: official Apache documentation](https://httpd.apache.org/docs/2.4/mod/directives.html)".
| Name | Type, Usage constraints, Defaults | Description |
|---|---|---|
| DocumentRoot | string required, advanced default: @PKG_VAR@/@PKG_INSTANCE@/htdocs | The attribute DocumentRoot configures the document directory for the Apache web server. It can be accessed from outside with a browser, the directory should therefore be empty. Should not be changed. |
| User | string required, advanced default: @PROXY_RT_USER@ | The attribute User configures the owner of the running nevisProxy process. Should not be changed, as changes may lead to permission problems. If you set this attribute yourself, make sure that the ownership of the configuration, log files, and access to the binaries are set accordingly. |
| Group | string required, advanced default: @PROXY_RT_GROUP@ | The attribute Group configures the process group of the current nevisProxy process. Should not be changed, as changes may lead to permission problems. If you set this attribute yourself, make sure that the ownership of the configuration, log files, and access to the binaries are set accordingly. |
| KeepAlive | enum: on, off optional, advanced default: on | The attribute KeepAlive configures the HTTP keepalive behavior of the frontend connectors of nevisProxy. If set to "on", it enables HTTP persistent connections. The thread or process remains bound to the client and cannot be used by others during the time period defined by the attribute KeepAliveTimeout. |
| KeepAliveTimeout | integer optional scaling, advanced default: 5 | Defines the number of seconds Apache HTTPD will wait for a subsequent request before closing the connection. By adding the postfix ms the timeout can be also set in milliseconds. |
| MaxKeepAliveRequests | integer optional, scaling default: 100 | The attribute MaxKeepAliveRequests limits the number of requests allowed per connection when the attribute KeepAlive is "on". If it is set to "0", an unlimited number of requests is allowed. It is recommended setting a high value for maximum server performance. |
| MaxClients | integer optional, scaling default: 600 | MaxClients is the old name for the attribute MaxRequestWorkers. The attribute limits the number of simultaneous requests that will be served. |
| MaxClientsPerIpAddr | integer optional, scaling default: 0 (unlimited) | Deprecated The parameter MaxClientsPerIpAddr is deprecated. Instead, use the mod_qos parameter SrvMaxConnPerIP (see the previous table. The attribute MaxClientsPerIpAddr limits the number of TCP connections that can be established for one and the same IP address, to prevent DOS attacks. Remarks: If the value ofMaxClientsPerIpAddris lower than "1", the check is disabled. If the attribute value is higher than the value of the attribute MaxClients, the configuration is not valid. To find an appropriate value for this attribute: GiveMaxClientsPerIpAddrthe same value asMaxClients. Set tracing BC.Tracer.DebugProfile.NavajoReqIO=1 and check for "6-INFO" messages. Set the value ofMaxClientsPerIpAddr* to "peak", where "peak" is the number of concurrent TCP connections for a single IP address. |
| MaxRequestsPerChild | integer optional, advanced default: 0 (unlimited) | MaxRequestsPerChild is the old name for the MaxConnectionsPerChild attribute. It limits the number of connections that an in |
| Timeout | integer optional, scaling default: 30 | Amount of time the server will wait for certain events before failing a request. |
| LimitRequestLine | integer optional, security default: 5120 | Limits the size of the HTTP request line that will be accepted from the client. |
| LimitRequestBody | integer optional, scaling default: 512000 | The attribute specifies the number of bytes that are allowed in a request body. It restricts the total size of the HTTP request body sent from the client. Allowed are integers from "0" (meaning unlimited) to "2147483647" (2GB). |
| LimitRequestFields | integer optional, security default: 50 | Limits the number of HTTP request header fields that will be accepted from the client. Allowed are integers from "0" (meaning unlimited) to "32767". |
| LimitRequestFieldsize | integer optional, security default: 5120 | Limits the size of the HTTP request header allowed from the client. |
| LimitRequestParameters | integer optional, security default: 10’000 | The maximum number of parameters allowed in a request. |
| Loglevel | enum optional, troubleshooting default: notice | The Loglevel attribute adjusts the verbosity of the messages recorded in the error logs (see the ErrorLog attribute). For the available options, see the official Apache documentation. |
| ErrorLog | string required, advanced default: ""\|@PKG_HOME@/bin/bclogmgr size=1000000 archives=10 @PKG_VAR@/@PKG_INSTANCE@/logs/apache.log"" | Location where the server will log errors ("apache.log" by default). In the pkg default configuration, the file rotation of the error log is enabled using the bclogmgr. Note: The character ” must be escaped in XML using ". Notes about configuring a custom location: The directory containing the logs must exist when starting the instance. The nevisProxy user must be able to read and write in this directory. See its username and group in the <Server> element of the navajo.xml file. |
| SSLLoglevel | enum: debug, info, notice, warn, error optional, troubleshooting default: notice | Deprecated This attribute is deprecated. Use the attribute Loglevel instead. The attribute SSLLoglevel configures the log level of mod_ssl. |
| TransferLog | string optional, basic feature, default: ""\|@PKG_HOME@/bin/bclogmgr size=10000000 archives=10 @PKG_VAR@/@PKG_INSTANCE@/logs/access.log"" | Specifies the location of the access log file. In the pkg default configuration, the file rotation of the error log is enabled using the bclogmgr. Note: The character ” must be escaped in XML using ". Notes about configuring a custom location: The directory containing the logs must exist when starting the instance. The nevisProxy user must be able to read and write in this directory. See its username and group in the <Server> element of the navajo.xml file. See also Enabling the Apache transfer log. |
| CustomLog | string optional, advanced feature, default: ""\|@PKG_HOME@/bin/qslog -f ISBDUkEa -x -u @PROXY_RT_USER@ -o @PKG_VAR@/@PKG_INSTANCE@/logs/stat.log" "%h %>s %b %D %{clID}e %k %{Event}e %{dTr1B}e"" | Configures an additional log facility. Note: The character ” must be escaped in XML using ". Notes about configuring a custom location: The directory containing the logs must exist when starting the instance. The nevisProxy user must be able to read and write in this directory. See its username and group in the <Server> element of the navajo.xml file. See also Using the Apache CustomLog. |
| LogFormat | string optional, advanced default: ""%h %l %u %t \"%r\" %>s %b %{content-length}i %T \"%{Referer}i\" \"%{User-Agent}i\" trID=%{UNIQUE_ID}e"" | This attribute specifies the format of the access log file. Note: The character ‘”’ must be escaped in XML using ‘"’ |
| ServerAdmin | string required, advanced default:(mailto:[email protected]) | Deprecated This attribute is deprecated. The attribute ‘ServerAdmin’ configures the mail address of the server administrator and should be changed after installation. As the default Apache error page should never be displayed, this attribute is not really relevant. |
| ServerName | string required, basic connectivitydefault: DNS name of the machine | The attribute ServerName sets the request scheme, hostname and port that the server uses to identify itself.Syntax: *[scheme://]domain-name |
| ServerRoot | string required, advanced default: @PKG_VAR@/@PKG_INSTANCE@ | The attribute ServerRoot configures the root directory of the Apache web server. Should not be changed. |
| ServerSignature | enum: On, Off, EMail optional default: Off | Configures the Apache directive "ServerSignature".Usually this should not be changed. |
| ServerTokens | enum: Major | Minor |
| Include | string optional, advanced default: not set | Use this attribute to include any additional Apache configuration fragment. |
| DefaultType | string optional, advanced default: text/plain | Deprecated This attribute is deprecated. This attribute has been disabled. This directive has no effect other than to emit warnings if the value is not none. In prior versions, DefaultType would specify a default media type to assign to response content for which no other media type configuration could be found. |
| CoreDumpDirectory | string optional, troubleshooting default: not set | The attribute CoreDumpDirectory configures the directory to which the Apache web server writes core files. |
| UseCanonicalName | enum: On, Off, DNSoptional, troubleshooting default: On | Configures how the server determines its own name and port. For more information, see the official Apache documentation. |
| ThreadStackSize | integer optional, scaling default: 1048576 | Defines the size in bytes of the stack used by threads handling client connection. See also Appendix G - Sizing Parameters in the Nevis Proxy. |
| HttpProtocolOptions | string optional, advanced default: not set | Modifies restrictions on HTTP Request Messages.Syntax: *[Strict |
| SSLPassPhraseDialog | string optional, advanced default: ‘builtin’ | The attribute SSLPassPhraseDialog configures the passphrase retriever used by mod_ssl. Only the "builtin" option is supported. For information on how the passwords for password protected keys are fetched, see the description of the bc-properties bc.security.PassPhrasePolicy and bc.security.PassPhraseDialog in the chapter Low-level properties. |
| SSLSessionCacheTimeout | integer optional default: 300 | Defines the number of seconds before an SSL session expires in the Session Cache. This directive sets the timeout in seconds for the information stored in the global/inter-process SSL Session Cache, the OpenSSL internal memory cache and for sessions resumed by TLS session resumption (RFC 5077). It can be set as low as 15 for testing, but should be set to higher values like 300 in real life. If you use an own SSLCache or RemoteSSLCache, the system ignores the SSLSessionCacheTimeout parameter. |
| SSLSessionCache | string optional default: "shmcb:@PKG_VAR@/@PKG_INSTANCE@/run/apache_shmcb" | This attribute defines the TLS session cache. The following value options are available:"None"This setting disables the global/inter-process TLS session cache. It will incur a noticeable speed penalty and may cause problems if using certain browsers, particularly if client certificates are enabled. We do not recommend this setting. "Nonenotnull"This setting disables any global/inter-process TLS session cache. However, the setting does force OpenSSL to send a non-null session ID, to accommodate buggy clients that require one. "shmcb:/path/to/datafile[(size) This setting makes use of a high-performance cyclic buffer (approx. (size) bytes in size) inside a shared memory segment in RAM (established via/path/to/datafile*), to synchronize the local OpenSSL memory caches of the server processes. |