# Configuration keys of Total.js 5

> Configure Total.js 5 through CONF: application settings, HTTP responses, email and runtime defaults.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: en
Content-SHA256: 2ef72a7b9fcde672c1a24fc856022e87b39a3e5facf68c57efc087c9fb4b90ef
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

The `config` file holds one `key : value` setting per line and the values are available in the global `CONF` object (see the configuration recipe for the file format). The keys below are defined by `total5` 0.0.19 with these defaults; a key that is not here and not in the second table is yours. **Keys that start with `$` are settings of the framework** and `secret_` keys hold secrets.

Set application values in the config file and read them through CONF. The table gives the defaults and the purpose of each setting.

| Key | Default | Note |
|---|---|---|
| `name` | `'Total.js'` | The name of the application. In a view, `@{'%name'}` prints it. |
| `version` | `'1.0.0'` | Application version used in startup output, statistics and the default HTTP ETag suffix (index.js). |
| `author` | `''` | Application author displayed by startup imprint when nonempty (index.js). |
| `secret` | `F.syshash` | Set the application secret explicitly in configuration. |
| `secret_encryption` | `''` | Key read by encrypted WebSocket routes; this is distinct from an action encrypt metadata option (websocket.js). |
| `secret_totalapi` | `''` | Fallback token sent by the built-in TotalAPI driver (api.js); keep server-side. |
| `secret_csrf` | `''` | The secret of the CSRF tokens. Empty: the check always passes. |
| `secret_tms` | `''` | The token that TMS clients must send in the header `x-token`. |
| `$root` | `''` | URL prefix applied to route and asset paths; also adjusts the default API endpoint (routing.js, index.js). |
| `$cors` | `''` | Hostnames separated by comma. |
| `$api` | `'/api/'` | A default API endpoint. |
| `$sourcemap` | `true` | Loader metadata setting; LOAD sets it from the final DEBUG mode or disables it for selective resource loads (index.js). |
| `$httpreqlimit` | `0` | Request limit per ip. |
| `$httpcompress` | `true` | Enables negotiated gzip for eligible responses; the dynamic response path checks a 256-byte threshold (controller.js). |
| `$httpetag` | `''` | Suffix for framework-generated ETags; when empty, configuration derives it from the app version (index.js, controller.js). |
| `$httpmaxsize` | `256` | KB. |
| `$httprangebuffer` | `5120` | 5 MB. |
| `$httptimeout` | `5` | 5 seconds. |
| `$httpfiles` | `an object` | The file extensions that are served as static files, as an object `{ extension: true }`. |
| `$httpchecktypes` | `true` | For multipart data only. |
| `$httpmaxage` | `60` | In seconds. |
| `$httpmaxkeys` | `33` | Maximum parsed query-string key count (utils.js); not a JSON-body field limit. |
| `$httpmaxkey` | `25` | Maximum query-string key length used by the query parser (utils.js). |
| `$httpcacheoffset` | `''` | E.g. 1 minute. |
| `$blacklist` | `''` | HTTP/WebSocket request handling tests whether the configured value contains the client IP (http.js, websocket.js). Not a CIDR parser. |
| `$xpoweredby` | `'Total.js'` | Value of the generated X-Powered-By response header; empty suppresses it in the inspected response paths (controller.js). |
| `$minifyjs` | `true` | Minify the JavaScript files that are served. |
| `$minifycss` | `true` | Minify the CSS files that are served. |
| `$minifyhtml` | `true` | Minify the HTML that is sent. |
| `$port` | `'auto'` | HTTP listen port; auto is resolved at startup, and Total.run options can override it (index.js). |
| `$ip` | `'0.0.0.0'` | HTTP listen address; Total.run options can override it (index.js). |
| `$unixsocket` | `''` | Alternative Unix socket listen path (index.js). Socket permissions and reverse proxy setup are deployment concerns. |
| `$timezone` | `'utc'` | The time zone of the process (it is set in `process.env.TZ`). |
| `$insecure` | `false` | Configuration sets the process TLS verification environment from this flag (index.js). Keep false for authenticated TLS connections. |
| `$performance` | `false` | Adjusts HTTP agent maximum sockets and socket tuning (index.js); it is not evidence of an application speedup. |
| `$filtererrors` | `true` | Suppresses matching runtime error patterns in the framework error logger (index.js). |
| `$cleartemp` | `true` | Controls startup removal of selected generated/temp file extensions by the clear routine (index.js). |
| `$customtitles` | `false` | When false, the view metadata generator appends the application name to a non-home page title (viewengine.js). |
| `$clearcache` | `10` | Service-counter interval for resetting internal lookup/view/template/query-builder caches (index.js). Not a database deletion schedule. |
| `$imageconverter` | `'gm'` | The program that `Image` calls: `gm`, `im` or `magick`. |
| `$imagememory` | `0` | Disabled because e.g. GM v1.3.32 throws some error about the memory. |
| `$stats` | `true` | Controls statistics output/update branch; selective LOAD can disable it (index.js). |
| `$npmcache` | `'/var/www/.npm'` | Npm cache location passed by NPMINSTALL for the uid-33 execution branch (index.js). |
| `$python` | `'python3'` | Interpreter command used by Python execution and pip helpers (index.js); install Python separately. |
| `$wsmaxsize` | `256` | KB. |
| `$wscompress` | `true` | Enables negotiation of WebSocket permessage-deflate on server connections (websocket.js). |
| `$wsencodedecode` | `false` | Initial WebSocket server encode/decode setting (websocket.js); verify required wire format before changing it. |
| `$wsmaxlatency` | `2000` | Ping-latency threshold in milliseconds used by WebSocket connection checks (websocket.js). |
| `$proxytimeout` | `5` | 5 seconds. |
| `$cookiesamesite` | `'Lax'` | Default SameSite cookie policy when a cookie does not specify one (controller.js). |
| `$cookiesecure` | `false` | Default Secure cookie attribute when no per-cookie override is supplied (controller.js). |
| `$csrfexpiration` | `'30 minutes'` | How long a CSRF token is valid. |
| `$tapi` | `true` | Enables the built-in TotalAPI service driver; the special check operation bypasses this local gate (api.js). |
| `$tapiurl` | `'eu'` | Regional hostname prefix used by the TotalAPI driver (api.js). |
| `$tapimail` | `false` | Selects the TotalAPI mail path when the TotalAPI feature is enabled (mail.js). |
| `$tapilogger` | `false` | Enables the TotalAPI logger path when service access and its secret are configured (index.js). |
| `$imprint` | `true` | Enables the startup banner (index.js). |
| `$tms` | `false` | Turns on the TMS WebSocket endpoint. |
| `$tmsmaxsize` | `256` | The maximum size of a TMS message, in kB. |
| `$tmsurl` | `'/$tms/'` | The URL of the TMS endpoint. |
| `$tmsclearblocked` | `60` | In minutes. |
| `$total5` | set at start | The folder of the `total5` package (the framework reads its own files from it). |
| `$nodemodules` | set at start | The folder where `NPMINSTALL()` installs packages. |
| `secret_uid` | set at start | Secret input used by the short encrypted-identifier utility; initialized from the system hash (index.js, utils.js). |
| `$cryptoiv` | set at start | Initialization-vector buffer used by framework encryption helpers; initialized at startup (index.js, utils.js). |
| `$httpexpire` | set at start | Future UTC HTTP expiry date initialized and periodically refreshed by the framework (index.js, controller.js). |

These keys have no default. They configure the email sending and are used by `MAIL()` and `HTMLMAIL()` (see the email recipe):

| Key | Meaning |
|---|---|
| `mail_smtp` | The address of the SMTP server. |
| `mail_smtp_options` | An object with the rest of the connection settings: `port`, `user`, `password`, `secure`... |
| `mail_from` | The address of the sender. |
| `mail_from_name` | The name of the sender. |
| `mail_reply` | The address that gets the replies, added to every message. |
| `mail_cc` | A copy address, added to every message. |
| `mail_bcc` | A hidden copy address, added to every message. |

```js controllers/config.js
exports.install = function() {
	ROUTE('GET /config/', config);
};

function config($) {
	$.json({ conf: CONF });
}
```