Core Settings

Core settings are global Gruxi settings that control various aspects of the server behavior.

These settings apply globally to all sites and bindings by default, but may be overridden per site or binding.

Base Settings

Settings related to the basic operation of the Gruxi server.

Max Connection Duration

Defines the maximum duration in seconds a connection can remain open. Connections exceeding this duration will be force closed by the server. This helps prevent resource exhaustion from long-lived connections.

Users will not see an explicit error; the connection simply closes, and the client will open a new one if it needs to make more requests.

Max Body Size

Defines the maximum allowed size for request bodies. Requests with bodies exceeding this size will be rejected with a 413 Payload Too Large response.

This setting helps prevent abuse and resource exhaustion by limiting the size of incoming request bodies. You should adjust this value based on the expected size of requests your server will handle.

Blocked File Patterns

A list of file extension patterns that should be blocked from being served by Gruxi. Requests for files matching these patterns will receive a 404 Not Found response. You can adapt this list to your security needs and the types of files you want to restrict access to. The primary consumer of this list is the static file processor, but other processors may also respect these settings.

Admin Portal Settings

The admin portal settings control the behavior of the Gruxi admin portal.

Domain Name

The domain is used to access the admin portal. You can set this to a specific domain or leave it empty to allow access from any domain. This is useful for security, to restrict access to the admin portal to specific domains only. For TLS, the domain should be set to a valid domain name that matches the TLS certificate you want for the admin portal.

Enable Automatic TLS

Enables automatic TLS certificate acquisition and renewal via Let's Encrypt for the admin portal. When enabled, Gruxi will automatically obtain and renew TLS certificates for the specified domain using Let's Encrypt. Make sure that the domain is correctly set and points to the Gruxi server for this to work.

TLS Certificate Path

If automatic TLS is not used, you can specify the path to a custom TLS certificate file here for the admin portal. If automatic TLS is enabled, this setting will be ignored.

TLS Key Path

If automatic TLS is not used, you can specify the path to a custom TLS key file here for the admin portal. If automatic TLS is enabled, this setting will be ignored.

File Cache Settings

The file cache is an important mechanism to improve performance by caching accessed files in memory.

This reduces disk I/O and speeds up file serving for accessed files.

It’s important to configure it properly to avoid excessive memory usage and ensure optimal performance. Especially for servers with limited memory, careful configuration of the file cache is crucial.

When compression is also active, the compressed version of the file is stored in cache to avoid recompressing on each request.

Enable File Caching

Enable or disable the file caching mechanism. When enabled, accessed files will be cached in memory for faster subsequent access.

Max Cached Items (count)

The maximum number of files to aim for in the cache. The cache may temporarily exceed this value.

This is primarily used in conjunction with the Forced Eviction Threshold (%) setting to determine when to start evicting files. For example, if the maximum is 1000 items and the forced eviction threshold is 80%, eviction begins once the cache reaches 800 items.

This is best thought of as a target value rather than a hard limit.

Max Size Per File (MB)

The maximum size of a single file to be cached. Files larger than this size will not be cached. This helps prevent large files from consuming excessive memory in the cache.

Cache Update Thread Interval (seconds)

Defines the interval at which the file cache checks for updates to cached files on disk and evicts them if they have changed. It also checks for files that have exceeded their maximum time in cache and evicts them, but only if the server has reached the forced eviction threshold.

For most use cases, a value between 10 and 60 seconds is reasonable. Setting it too low may cause excessive disk I/O, while setting it too high may result in stale cache entries.

A Gruxi server restart or a configuration reload will also clear the file cache.

Max Time To Keep a File (seconds)

Defines the maximum time a file can remain in the cache. This is only enforced when cache eviction is triggered, either due to reaching the maximum cached items threshold or during periodic cleanup.

Forced Eviction Threshold (%)

Defines the percentage of the maximum cached items at which forced eviction of files from the cache will begin. When the number of cached items reaches this threshold, the cache will start evicting the files that have reached their max time in cache to free up space.

Gzip Compression Settings

Compression of responses can significantly reduce the amount of data transferred over the network, improving load times and reducing bandwidth usage. Used in conjunction with file caching, it can greatly enhance performance for clients that support compressed responses, as it will cache the compressed version of the file in memory.

Enable Gzip Compression

Enables Gzip compression for responses. When enabled, Gruxi will compress responses using Gzip for clients that support it, reducing bandwidth usage and improving load times.

Compressible Content Types

Only responses with content types matching these patterns will be compressed. This allows you to specify which types of content should be compressed, such as text-based formats like HTML, CSS, and JavaScript. This is the default list, but you can modify it to suit your needs.

TLS Settings

LetsEncrypt Account Email

Email address used for Let’s Encrypt account registration and notifications globally on this Gruxi server. This email will be used by Let’s Encrypt to send important information about your certificates, such as expiration reminders.

Use LetsEncrypt Staging Server

When enabled, Gruxi will use the Let’s Encrypt staging server for obtaining TLS certificates. This is useful for testing and development purposes, as it allows you to obtain test certificates without hitting rate limits on the production Let’s Encrypt servers.

WARNING

Certificates obtained from the staging server are not trusted by browsers and will result in security warnings.

Be sure to disable this setting when moving to production to obtain valid certificates.

HTTP Caching

Enable HTTP Caching Headers

When enabled, Gruxi will add HTTP caching headers to responses to help clients cache content effectively. This can improve performance for repeat visitors by allowing browsers to cache static resources. Currently, Gruxi adds these headers for static file responses only:

Cache-Control:

• public, max-age=31536000 for static files (js, css, fonts, images, video, audio etc.), indicating that they can be cached for one year.
• no-cache for .html files, indicating that browsers should always check for a fresh version.
• public, max-age=86400 for other file types, indicating they can be cached for one day.

ETag header based on the file's last modified time and size, allowing clients to validate cached content.

Expires header is added to all files served by the static file processor, and the value is set to one year from today.

Last-Modified header based on the file's last modified time.

HTTP Caching headers are only added for the static file processor

This is intentional because Gruxi should not modify dynamic content generated by other processors, such as another web server or a scripting engine like PHP. Those processors are best left to handle their own caching headers as appropriate. You can force headers by adding them explicitly in your site's configuration if needed.

Gruxi supports conditional requests

This support is based on ETag and Last-Modified headers for static files, which specifically is:

• If-Match (RFC 7232 Section 3.1)
• If-None-Match (RFC 7232 Section 3.2)
• If-Modified-Since (RFC 7232 Section 3.3)
• If-Unmodified-Since (RFC 7232 Section 3.4)

INFO

All the caching headers can be overridden by explicitly setting them in your site's configuration.