From 732236e623de4ceb8a84fc5b633f7bdfa0a815da Mon Sep 17 00:00:00 2001 From: Anna Larch Date: Sat, 25 Apr 2026 17:10:46 +0200 Subject: [PATCH 1/2] docs(config): document missing admin-configurable config keys Add documentation for config keys that are used in the server code but were absent from config.sample.php, making them invisible to admins and excluded from the auto-generated configuration reference. Keys added: User/auth settings: - allow_user_to_change_email (defaults true, falls back to allow_user_to_change_display_name) - auth_can_create_app_token (defaults true) - auth_onetime_token_validity (defaults 120s) - twofactor_enforced / twofactor_enforced_groups / twofactor_enforced_excluded_groups (managed via occ twofactorauth:enforce, documented here for direct config.php use) Server/networking: - dns_pinning (defaults true, prevents DNS rebinding attacks) - pollinterval (defaults 60s, sync client poll frequency) - webdav-root (defaults remote.php/webdav) - registration_link (defaults nextcloud.com/register, shown on login page) - enable_avatars (defaults true) App management: - app_install_overwrite (defaults [], bypass max-version check for listed apps) Previews: - preview_format (defaults jpeg, jpeg/webp/png for Imaginary service) File locking: - filelocking.enabled (defaults true, strongly discouraged to disable) Config Lexicon: - lexicon.default.userconfig (set server-wide defaults for user config keys) - lexicon.default.userconfig.enforced (prevent users from overriding specific values) Signed-off-by: Anna Larch Signed-off-by: Anna Larch --- config/config.sample.php | 165 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) diff --git a/config/config.sample.php b/config/config.sample.php index dca5c29038a69..5cce7282d9bb3 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -303,6 +303,34 @@ */ 'allow_user_to_change_display_name' => true, + /** + * ``true`` allows users to change their email address (on their Personal + * pages), and ``false`` prevents them from changing their email address. + * Falls back to ``allow_user_to_change_display_name`` if not set. + * + * Defaults to ``true`` + */ + 'allow_user_to_change_email' => true, + + /** + * ``true`` allows users to create app passwords (tokens) in their personal + * security settings. Set to ``false`` to prevent users from generating app + * passwords, for example when SSO is enforced and app passwords would + * bypass it. + * + * Defaults to ``true`` + */ + 'auth_can_create_app_token' => true, + + /** + * Validity period (in seconds) for one-time authentication tokens, such as + * those used for email-based login or share link authentication. + * The minimum value is ``120``. + * + * Defaults to ``120`` + */ + 'auth_onetime_token_validity' => 120, + /** * The directory where the skeleton files are located. These files will be * copied to the data directory of new users. Set empty string to not copy any @@ -408,6 +436,30 @@ */ 'token_auth_enforced' => false, + /** + * Enforce two-factor authentication for all users, or for members of specific + * groups. Managed via ``occ twofactorauth:enforce``. + * + * Defaults to ``'false'`` (stored as string) + */ + 'twofactor_enforced' => 'false', + + /** + * When ``twofactor_enforced`` is ``'true'``, restrict enforcement to these + * groups. All other users are not affected. Empty array enforces for all users. + * + * Defaults to ``[]`` + */ + 'twofactor_enforced_groups' => [], + + /** + * Exclude specific groups from two-factor authentication enforcement. + * Only relevant when ``twofactor_enforced`` is ``'true'``. + * + * Defaults to ``[]`` + */ + 'twofactor_enforced_excluded_groups' => [], + /** * The interval at which token activity should be updated. * Increasing this value means that the last activity on the security page gets @@ -827,6 +879,16 @@ */ 'allow_local_remote_servers' => true, + /** + * Enable DNS pinning for outbound HTTP requests. When enabled, Nextcloud + * resolves the hostname of a request target once and rejects the connection + * if the resolved IP changes during the request. This prevents DNS rebinding + * attacks at the cost of slightly increased latency on the first request. + * + * Defaults to ``true`` + */ + 'dns_pinning' => true, + /** * Add the URL of the Nextcloud server in User-Agent headers HTTP calls. * @@ -1327,6 +1389,15 @@ 'customclient_fdroid' => 'https://f-droid.org/packages/com.nextcloud.client/', + /** + * URL shown as a sign-up / registration link on the login page. Set to a + * custom URL to point users to your own registration flow. + * Set to empty string ``''`` to hide the link entirely. + * + * Defaults to ``'https://nextcloud.com/register'`` + */ + 'registration_link' => 'https://nextcloud.com/register', + /** * Activity * @@ -1385,6 +1456,25 @@ */ 'defaultapp' => 'dashboard,files', + /** + * Interval (in seconds) at which sync clients poll the server for changes. + * Lowering this value increases server load; increasing it reduces update + * frequency for connected clients. + * + * Defaults to ``60`` + */ + 'pollinterval' => 60, + + /** + * WebDAV root path advertised to sync clients via the capabilities API. + * Clients use this value to construct the WebDAV URL; changing it does not + * remap the server's routing. Only set this if you have configured a custom + * WebDAV path at the web server level and need clients to use that path. + * + * Defaults to ``'remote.php/webdav'`` + */ + 'webdav-root' => 'remote.php/webdav', + /** * When enabled, admins may install apps from the Nextcloud app store. * @@ -1392,6 +1482,17 @@ */ 'appstoreenabled' => true, + /** + * Allow installing apps that declare a maximum version requirement lower than + * the current Nextcloud version. List the app IDs to override. + * Apps force-enabled via ``occ app:enable --force`` are added here automatically. + * + * Use with care: apps may be incompatible with the current server version. + * + * Defaults to ``[]`` + */ + 'app_install_overwrite' => [], + /** * Enables the installation of apps from a self-hosted apps store. * Requires that at least one of the configured apps directories is writable. @@ -1433,6 +1534,14 @@ * These options control enabling and disabling previews, and thumbnail size. */ + /** + * ``true`` enables avatar support. Set to ``false`` to disable avatars + * server-wide, which also removes the avatar section from personal settings. + * + * Defaults to ``true`` + */ + 'enable_avatars' => true, + /** * By default, Nextcloud can generate previews for the following filetypes: * @@ -1540,6 +1649,18 @@ */ 'preview_imaginary_url' => 'http://previews_hpb:8088/', + /** + * Image format used when generating preview thumbnails via the Imaginary + * service. Applies only when ``preview_imaginary_url`` is configured. + * Accepted values: ``jpeg``, ``webp``, ``png``. + * + * ``webp`` produces smaller files at comparable quality. ``jpeg`` has the + * broadest client compatibility. + * + * Defaults to ``'jpeg'`` + */ + 'preview_format' => 'jpeg', + /** * If you want to set an API key for Imaginary. */ @@ -2605,6 +2726,16 @@ */ 'max_filesize_animated_gifs_public_sharing' => 10, + /** + * Enable transactional file locking. This prevents simultaneous processes + * from writing to the same files, which can cause data corruption. + * Disabling this is strongly discouraged unless you are using an external + * file locking provider. + * + * Defaults to ``true`` + */ + 'filelocking.enabled' => true, + /** * Set the lock's time-to-live (TTL) in seconds. Locks older than this are * automatically cleaned up. @@ -3013,4 +3144,38 @@ * Defaults to ``0``. */ 'preview_expiration_days' => 0, + + /** + * Set server-wide default values for user config keys managed by the Config + * Lexicon. These defaults are used when the user has not explicitly set a value. + * The structure mirrors the app config lexicon: ``appId => [ configKey => value ]``. + * + * Example:: + * + * 'lexicon.default.userconfig' => [ + * 'files' => [ + * 'show_hidden' => 'false', + * ], + * ], + * + * Defaults to ``[]`` + */ + 'lexicon.default.userconfig' => [], + + /** + * Enforce server-wide values for user config keys managed by the Config + * Lexicon. Users cannot override enforced values. The structure is the same + * as ``lexicon.default.userconfig``. + * + * Example:: + * + * 'lexicon.default.userconfig.enforced' => [ + * 'files' => [ + * 'show_hidden' => 'false', + * ], + * ], + * + * Defaults to ``[]`` + */ + 'lexicon.default.userconfig.enforced' => [], ]; From 8de14df01a358236e4454ef360e328cd1aa3ff01 Mon Sep 17 00:00:00 2001 From: Anna Larch Date: Tue, 5 May 2026 20:39:07 +0200 Subject: [PATCH 2/2] docs(config): document activity_db* keys for dedicated Activity database The Activity app's ConnectionFactory call with the 'activity_' prefix has been undocumented in config.sample.php, making the dedicated-DB feature invisible to admins. Add entries for activity_dbhost, _dbname, _dbuser, _dbpassword and _dbdriveroptions with usage notes. AI-Assisted-By: Claude Sonnet 4.6 Signed-off-by: Anna Larch --- config/config.sample.php | 55 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/config/config.sample.php b/config/config.sample.php index 5cce7282d9bb3..223d8f59128ac 100644 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -1439,6 +1439,61 @@ */ 'activity_use_cached_mountpoints' => false, + /** + * Dedicated database connection for the Activity app. + * + * On busy installations the ``*_activity`` table is often the fastest-growing + * table in the database. Offloading it to a separate database server or + * instance reduces I/O contention on the main database. + * + * When any of the ``activity_db*`` keys below is present, the Activity app + * opens a second connection using those values, falling back to the + * corresponding main-connection value for any key that is omitted. The + * database type (``dbtype``) and table prefix (``dbtableprefix``) are always + * inherited from the main connection and cannot be overridden. + * + * All four keys must point to a database that already contains the activity + * tables; run ``occ db:migrate activity`` after setting up the new database. + */ + + /** + * Hostname (and optional port) of the dedicated Activity database server. + * Port can be appended with a colon, e.g. ``db-activity.example.com:3306``. + * Defaults to the value of ``dbhost``. + */ + // 'activity_dbhost' => '', + + /** + * Name of the dedicated Activity database. + * Defaults to the value of ``dbname``. + */ + // 'activity_dbname' => '', + + /** + * Username for the dedicated Activity database connection. + * Defaults to the value of ``dbuser``. + */ + // 'activity_dbuser' => '', + + /** + * Password for the dedicated Activity database connection. + * Defaults to the value of ``dbpassword``. + */ + // 'activity_dbpassword' => '', + + /** + * Low-level PDO driver options for the dedicated Activity database connection, + * e.g. TLS/SSL parameters for MySQL. Defaults to the value of ``dbdriveroptions``. + * + * Example for MySQL with TLS:: + * + * 'activity_dbdriveroptions' => [ + * PDO::MYSQL_ATTR_SSL_CA => '/etc/ssl/certs/ca-certificates.crt', + * PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT => true, + * ], + */ + // 'activity_dbdriveroptions' => [], + /** * Apps *