.. include:: /Includes.rst.txt

.. _configuration:

=============
Configuration
=============

Runtime settings live outside the web root in
:file:`<project>/var/t3vault/config.local.php` (0600). The plaintext backup
password is stored separately in :file:`<project>/var/t3vault/backup.password.php`
(0600) so a single file read never yields both the signing secret and the
archive password. Provisioning never overwrites these files; legacy copies
inside :file:`<web-dir>/t3vault/` are migrated automatically. Settings can also
be changed from the T3Vault UI (**Settings**).

.. figure:: /Images/screenshot-settings.png
   :alt: T3Vault Settings dialog with data directory, passwords and HTTP proxy
   :class: with-shadow
   :zoom: lightbox

   Runtime settings can be edited in the UI; secrets stay outside the web root.

.. _configuration-keys:

Settings overview
=================

=======================  ======================================================
Key                      Description
=======================  ======================================================
``passwordHash``         Argon2id hash of the standalone login password
``secret``               Signing secret (sessions, SSO tokens, integrity HMAC)
``backupPassword``       AES-256 password for all backup ZIP archives (min. 8
                         chars); stored in :file:`backup.password.php`, not in
                         the config file
``backupBaseDir``        Absolute override for the backup directory; empty =
                         default
``allowedBackupRoots``   Additional roots a backup directory may live in
                         (project root is always allowed)
``uploadMaxFiles``       Files accepted per import request (default 200)
``uploadMaxFileBytes``   Maximum size of a single imported file (default 20 GiB)
``uploadMaxTotalBytes``  Maximum total size of one import (default 40 GiB)
``httpProxyMode``        Proxy mode for OpenTimestamps calendar traffic
``httpProxy``            Custom proxy URL when ``httpProxyMode`` is ``custom``
``canonicalHost``        Host (optionally ``host:port``) used for self-generated
                         URLs; empty = validated request host
``trustedHostsPattern``  Anchored regex the request ``Host`` must match to be
                         trusted (mirrors the TYPO3 setting of the same name)
``trustedProxies``       List of reverse proxy IPs whose ``X-Forwarded-Proto``
                         is believed; empty = ignore forwarded headers
``allowedOrigins``       Explicit cross-origin origins; empty = same-origin only
                         (no wildcard is accepted)
=======================  ======================================================

Scheduled backup tasks are **not** stored in ``config.local.php``. They live in
:file:`tasks.json` next to the config (same data directory, mode 0600). See
:ref:`backup-tasks`.

.. _configuration-trusted-proxies:

Reverse proxies
===============

``X-Forwarded-Proto`` is freely settable by any client, so it is only honoured
when ``REMOTE_ADDR`` matches ``trustedProxies`` (or the
``T3VAULT_TRUSTED_PROXIES`` environment variable, comma separated). Without this
a client could claim an HTTPS connection and suppress the plaintext-transport
warnings. The standalone restore installer reads the environment variable only,
because it runs without a configuration file.

.. _configuration-backup-dir:

Backup directory
================

Default (relative to the TYPO3 project root, parent of :file:`public/`):

.. code-block:: text

   var/t3vault/backups

This keeps archives outside the web root. Override via ``backupBaseDir`` in
:file:`config.local.php` or the Settings UI. Even AES-encrypted archives must
not live under :file:`public/`: ZIP metadata (file names, sizes, structure)
is readable without the password.

The Settings API therefore refuses a target that

* resolves into the web root (symlinks and ``..`` are resolved first),
* is a system location (:file:`/etc`, :file:`/root`, :file:`/usr`, a bare home
  directory, …), or
* lies outside the allowed roots.

Allowed roots are the project root plus everything declared in
``allowedBackupRoots`` (:file:`config.local.php`) or in the
``T3VAULT_ALLOWED_BACKUP_ROOTS`` environment variable (comma separated). Use
this for external volumes:

.. code-block:: php

   'allowedBackupRoots' => ['/srv/backups'],

Declaring roots outside the API is deliberate — an authenticated session cannot
widen its own target range. A directory that is already configured stays usable
even if it is outside those roots, so existing installations keep working.

.. _configuration-proxy:

HTTP proxy (OpenTimestamps)
===========================

Calendar submissions and proof upgrades need outbound HTTPS. Modes:

==========  ================================================================
Mode        Behaviour
==========  ================================================================
``auto``    Prefer TYPO3 HTTP options, then environment variables
``typo3``   Use TYPO3 ``HTTP`` / proxy settings only
``env``     Use ``HTTP_PROXY`` / ``HTTPS_PROXY`` / ``NO_PROXY``
``custom``  Use ``httpProxy`` from :file:`config.local.php`
``none``    Disable proxy
==========  ================================================================

A custom proxy is accepted as ``http(s)://[user:pass@]host[:port]`` or
``host:port``; paths, whitespace and other schemes are rejected. Private and
loopback addresses are allowed (corporate and DDEV proxies live there), but
link-local ranges are not — ``169.254.169.254`` is a cloud metadata endpoint,
never a proxy. Host names are additionally resolved once and rejected if they
point into those ranges.

.. _configuration-self-invocation:

Self-invocation base URL
========================

Backup batches continue server-side via HTTP self-invocation. Behind a reverse
proxy you may set ``Config::BACKUP_BASE_URL`` in the packaged API config to
the public base URL of the API (example:
``https://example.com/t3vault/Api``). Leave empty for auto-detection from the
request.