Sandbox Directives

Appweb supports directives that limit its use of system resources such as memory and threads. This technique is know as "sandboxing" because it creates a limited or safer area in which Appweb executes.

ExitTimeout

Description Timeout to wait when exiting or restarting
Synopsis ExitTimeout period
Context Default server
Example ExitTimeout 30secs
Notes

This directive defines the maximum time to wait for existing requests to complete before exiting or restarting Appweb.

LimitBuffer

Description Defines the pipeline stage buffer size
Synopsis LimitBuffer size
Context Default server, VirtualHost
Example LimitBuffer 8192
Notes

This directive defines the maximum buffer size in bytes for each stage in the request pipeline. This directive places a limit on the amount of memory consumed by pipeline stages.

NOTE: this does not imply a maximum response size (See LimitResponseBody for that functionality). It merely limits the memory consumed when trying to buffer the response data. Appweb handlers will flush the buffers and use HTTP/1.1 chunked output if the amount of response data exceeds the output buffer size.

LimitCache

Description Maximum size of response data and session state
Synopsis LimitCache size
Context Default server, VirtualHost
Example LimitCache 8192
Notes

This directive defines the maximum size of the Appweb data cache. This cache store is used for caching responses and for the session state date for ESP applications. If the maximum size is exceeded, Appweb will prune the oldest data in the cache to make room for newer items.

LimitCacheItem

Description Maximum size of a single item in the cache
Synopsis LimitCacheItem size
Context Default server, VirtualHost
Example LimitCacheItem 512K
Notes

This directive defines the maximum size of a single item in the Appweb data cache. This cache store is used for caching responses and for the session state date for ESP applications. If the maximum size is exceeded, Appweb will not store the item in the cache. The request will continue, but not be served from the cache.

LimitChunk

Description Defines the maximum chunk size
Synopsis LimitChunk size
Context Default server, VirtualHost
Example LimitChunk 8192
Notes

This directive defines the maximum chunk size when using Transfer Chunk Encoding.

LimitClients

Description Sets the maximum number of simultaneous client systems
Synopsis LimitClients count
Context Default server, VirtualHost
Example LimitClients 10
Notes

The LimitClients directive defines the maximum number of simultaneous client systems that can connect to the server. Connections in excess of this count will be rejected. A limit of '0' means unlimited.

This directive counts the number of unique client systems. A system with many users all using the same IP address will be counted as one client.

LimitConnections

Description Sets the maximum number of simultaneous client endpoint connections
Synopsis LimitConnections count
Context Default server, VirtualHost
Example LimitConnections 50
Notes

The LimitConnections directive defines the maximum number of simultaneous client connections to the server. Connections in excess of this count will be rejected. A limit of '0' means unlimited.

This directive counts the number of client socket connections. A single browser may open many separate connections (typically up to 6).

LimitFiles

Description Sets the maximum number of open files/sockets that Appweb can open.
Synopsis LimitFiles count
Context Default server
Example LimitFiles 1024
Notes

The LimitFiles directive defines the maximum number of files/sockets that Appweb can open on a Unix system. The files limit must be set sufficiently high to support the peak load anticipated for Appweb. Each request will always consume one file descriptor for the network socket. CGI requests will consume an additional three file descriptors to communicate with the CGI process.

The default limit for Appweb is defined by the system ulimit. A limit of '0' means set the limit to the maximum permitted by the operating system.

LimitKeepAlive

Description Define the maximum number of requests for a connection.
Synopsis LimitKeepAlive number
Context Default Server, Virtual Host, Route
Example LimitKeepAlive 50
Notes

This directive defines the maximum number of requests that may be serviced using a single TCP/IP connection.

Security

Limiting the number to a reasonable maximum can help reduce the impact of some denial of service attacks.

LimitMemory

Description Sets the maximum heap memory that Appweb can allocate.
Synopsis LimitMemory size
Context Default server
Example LimitSize 10MB
Notes

The LimitMemory directive defines the maximum amount of memory that Appweb can use. On Linux and MacOSX, where a fast memory size API exists, this is the amount of memory currently used by the application. On other platforms, it is the amount of Appweb heap memory and does not include thread stack, code allocations, or memory allocated by means other than the MPR memory allocation primitives. If the memory limit is exceeded, Appweb will invoke the policy specified by the MemoryPolicy directive.

LimitProcesses

Description Sets the maximum number of processes Appweb will spawn for CGI.
Synopsis LimitProcesses count
Context Default server
Example LimitProcesses 1000000
Notes

The LimitProcesses directive defines the maximum number of processes that Appweb will spawn to serve CGI processes. If this maximum is exceeded, Appweb will deny the request.

LimitRequestsPerClient

Description Sets the maximum number of simultaneous HTTP requests for a single client IP address
Synopsis LimitRequestsPerClient count
Context Default server, VirtualHost, Route
Example LimitRequestsPerClient 20
Notes

The LimitRequestsPerClient directive defines the maximum number of simultaneous client HTTP requests that are permitted per single client IP address. Requests in excess of this count will be rejected. A limit of '0' means unlimited.

NOTE: that many browsers can and will initiate multiple requests when requesting a page. Some browsers will initiate up to six requests at a time for a single tab.

Security

To mitigate denial of service attacks, this limit should be set as low as possible.

LimitRequestBody

Description Sets the maximum size of the request body from the client.
Synopsis LimitRequestBody limit
Context Default server, VirtualHost
Example LimitRequestBody 65536
Notes

The LimitRequestBody directive defines a maximum size for the request body. For embedded applications, it is useful to limit the request body to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request.

The limit is an integer between zero and 2147483647 (2GB), where zero means unlimited. If a request is received that is larger than the limit, it will be rejected and the client will receive an error. The default limit is 64 MB.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends large documents of a certain type.

LimitRequestForm

Description Sets the maximum size of the request form from the client.
Synopsis LimitRequestForm limit
Context Default server, VirtualHost
Example LimitRequestForm 65536
Notes

The LimitRequestForm directive defines a maximum size for the request form data. Form data is encoded with a Content-Type of "application/x-www-form-urlencoded". Form data is fully buffered before doing Route matching and constructing the pipeline. Whereas, non-form data is streamed to the handler and not buffered.

For embedded applications, it is useful to limit the request body to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request.

The limit is an integer between zero and 2147483647 (2GB), where zero means unlimited. If a request is received that is larger than the limit, it will be rejected and the client will receive an error. The default limit is 64 MB.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends large documents of a certain type.

LimitRequestHeader

Description Maximum size of the request headers from the client
Synopsis LimitRequestHeader limit
Context Default server, VirtualHost
Example LimitRequestHeader 65536
Notes

The LimitRequestHeader directive defines the maximum size of the request header from the client. For embedded applications, it is useful to limit the size of the header to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request. Typically, HTTP requests will not have more than 4K of header data.

The limit is an integer between zero and 1 MB, where zero means unlimited. If a request is received that has a header larger than the limit, it will be rejected and the client will receive an error. The default limit is 8 K.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends requests with large bogus headers.

LimitRequestHeaderLines

Description Maximum number of header lines in the request body from the client.
Synopsis LimitRequestHeaderLines limit
Context Default server, VirtualHost
Example LimitRequestHeaderLines 64
Notes

The LimitRequestHeaderLines directive defines a maximum number of header lines that may be in a request from a client. For embedded applications, it is useful to limit the number of header lines to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request. Typically, HTTP requests will not have more than 15-20 header lines.

The limit is an integer between zero and 4096, where zero means unlimited. If a request is received that has more header lines than the limit, it will be rejected and the client will receive an error. The default limit is 40.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends requests with many spurious header lines.

LimitResponseBody

Description Set the maximum size of the response body buffered by a dynamic Appweb handler.
Synopsis LimitResponseBody number
Context Default server, VirtualHost, Route
Example LimitResponseBody 65536
Notes

The LimitResponseBody directive defines the maximum size for response body data.

LimitSessions

Description Sets the maximum number of simultaneous client sessions
Synopsis LimitSessions count
Context Default server, VirtualHost, Route
Example LimitSessions 40
Notes

The LimitSessions directive defines the maximum number of simultaneous client sessions that utilize server-side session state storage. Requests in excess of this count will be rejected. A limit of '0' means unlimited.

This directive limits the number of session states, whereas the LimitClients directive limits the number of connected client systems.

NOTE: that many browsers can and will initiate multiple requests when requesting a page. These will share the same session state storage. Some browsers will initiate up to six requests at a time for a single tab.

LimitUri

Description Maximum size of a URL in a request from a client.
Synopsis LimitUri limit
Context Default server, VirtualHost
Example LimitUri 4096
Notes

The LimitUri directive defines the maximum size of a URL in Appweb. In embedded applications, it is useful to limit the number of header lines to the expected maximum. This ensures that rogue or malicious requests will not cause the server to allocate unwanted memory to servicing the request.

The limit is an integer between zero and 256 K where zero means unlimited. If a request is received that has a URL larger than the limit, it will be rejected and the client will receive an error. The default limit is 4 K.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends requests with bogus URLs.

LimitUpload

Description Maximum size of a URL in a request from a client.
Synopsis LimitUpload size
Context Default server, VirtualHost
Example LimitUpload 20MB
Notes

The LimitUpload directive defines the maximum size of an uploaded file. In embedded applications, it is useful to limit the maximum file upload size to ensure that rogue or malicious requests will not cause the server to allocate unwanted space for uploads.

If set to zero, there is no limit. If a file larger than the limit is uploaded, Appweb will reject the request and the client will receive an error. The default value is unlimited.

Security

This directive can be quite useful in certain denial-of-service attacks where the attacker sends requests with bogus URLs.

Memory Policy

Description Defines the policy for memory depletion situations.
Synopsis MemoryPolicy continue|restart
Context Default server
Example MemoryPolicy restart
Notes

Appweb manages memory proactively and ensures reliable operation by preventing memory allocation errors before they occur. It does this by defining a memory limit and applying a memory policy for how to react when memory is depleted.

The MemoryPolicy directive defines how Appweb will respond to low memory conditions. While the LimitMemory directive defines a maximum amount of memory that Appweb is permitted to use, the MemoryPolicy directive defines how Appweb will respond when the limit is approached and exceeded.

If memory utilization exceeds the maximum memory limit, Appweb will invoke the memory depletion policy defined by this directive. Appweb also institutes a memory redline that is 85% of the memory limit. When memory utilization exceeds the redline value, Appweb will issue a warning to the error log and attempt to free non-essential memory such as old session data and request caching.

If the memory policy is set to continue, Appweb will prune all non-essential memory, but will continue to run. i.e. the limit becomes a soft limit and can be exceeded. If the policy is set to restart, then Appweb will do a graceful restart if the maximum is exceeded. A graceful restart will allow existing requests to complete up to the timeout specified by the ExitTimeout directive. Appweb relies on the appman manager application to restart appweb in this case.

MinWorkers

Description Number of worker threads to pre-allocate in the Appweb worker pool
Synopsis MinWorkers number
Context Default Server
Example MinWorkers 100
Notes

The MinWorkers directive will pre-allocate the specified number of worker threads on startup and then ensure that the worker pool always has at least this minimum number of workers.

Appweb will automatically adjust the number of workers between the minimum specified by this directive and the maximum specified by the WorkerLimit directive or via the Appweb command line. Every ten minutes, Appweb will prune workers that have been idle for five minutes to reduce resource consumption.

Appweb 4 has two non-worker threads: one for the master event loop and one for the garbage collector. So the total number of Appweb threads will be two plus the number of active workers.

ThreadStack


Description Define the size of the stack to allocate for each thread
Synopsis ThreadStack limit
Context Default Server
Example ThreadStack 64K
Notes

The ThreadStack directive defines the size of the thread stack to allocate for each thread. The limit is an integer between zero and an operating system defined maximum  where zero means use the system default. The default limit is zero which implies the system default.

LimitWebSocketsMessage

Description pool.
Synopsis LimitWebSocketsMessage number
Context Default Server, Virtual Host, Route
Example LimitWebSocketsMessage 64K
Notes

The LimitWebSocketsMessage directive defines the maximum size of a Web Sockets message.

WorkerLimit

Description Maximum size of a packet containing a portion of a Web Sockets message.
Synopsis LimitWebSocketsPacket size
Context Default Server, Virtual Host, Route
Example LimitWebSocketsPacket 8K
Notes

This defines the maximum packet size for a portion of a Web Sockets message.

LimitWebSocketsFrame

Description Maximum size of a Web Sockets message frame.
Synopsis LimitWebSocketsFrame size
Context Default Server, Virtual Server, Route
Example LimitWebSocketsFrame 4K
Notes

This specifies the maximum frame size used for Web Sockets messages when sent over the wire.

LimitWorkers

Description Maximum number of worker threads to allocate for the Appweb worker pool.
Synopsis LimitWorkers number
Context Default Server
Example LimitWorkers 8
Notes

The LimitWorkers directive defines a maximum number of threads for the Appweb thread pool. When running in multithreaded mode, Appweb will use a pool thread to service each request and then will return the thread to the pool. This results in a highly responsive and scalable architecture with excellent throughput characteristics. Each thread requires a thread stack and thus consumes memory. By limiting the number of threads, memory can be conserved.

If the maximum number of threads is also specified via the Appweb command line, the command line value will take precedence.

Appweb will automatically adjust the number of pool threads between the minimum specified by the MinWorkers directive and the maximum specified by this directive. Appweb will prune idle threads to reduce resource consumption as required.

© Embedthis Software. All rights reserved.