Embedthis Appweb 4.3.4
Home > Users Guide > Configuration Directives > Sandbox Directives

# Quick Nav

- ExitTimeout
- LimitBuffer
- LimitCache
- LimitCacheItem
- LimitChunk
- LimitClients
- LimitFiles
- LimitKeepAlive
- LimitMemory
- LimitProcesses
- LimitRequests
- LimitRequestsPerClient
- LimitRequestBody
- LimitRequestForm
- LimitRequestHeader
- LimitRequestHeaderLines
- LimitResponseBody
- LimitUpload
- LimitUri
- LimitWebSocketsMessage
- LimitWebSocketsPacket
- LimitWebSocketsFrame
- LimitWorkers
- MinWorkers
- ThreadStack

# See Also

- Logging Overview
- Configuration
- Configuration Directives

# 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.

## 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 client systems. A system with many users all using the same IP address will be counted as one client.

## 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.

## LimitRequests

Description | Sets the maximum number of simultaneous HTTP requests
Synopsis | LimitRequests count
Context | Default server, VirtualHost, Route
Example | LimitRequests 40

Notes

The LimitRequests directive defines the maximum number of simultaneous incoming HTTP requests that are permitted. Requests in excess of this count will be rejected. A limit of '0' means unlimited.

This directive limits the number of HTTP requests, 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. Some browsers will initiate up to six requests at a time for a single tab.

## 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.

## 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.

## 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 prune|restart|exit
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 enforcing 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.

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

If the memory policy is set to prune, 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 up to 30 seconds for existing requests to complete. If the policy is set to exit, then Appweb will immediately exit if the maximum is exceeded.

## 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.

If you are experiencing crashes when running multi-threaded, and Appweb runs without error when running single-threaded, you may need to increase this value. See the Appweb command line for details on running single user by setting the "-p 0" option.

## 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 LLC, 2003-2013. All rights reserved. Embedthis, Appweb, ESP, Ejscript and Embedthis GoAhead are trademarks of Embedthis Software LLC.