From f93cd8f20e2446f04098b09903a2a2b5103e6f1f Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 7 Dec 2024 14:55:57 -0500 Subject: [PATCH 1/4] docs(admin): Configuration Parameter chapter refactoring Signed-off-by: Josh --- .../config_sample_php_parameters.rst | 274 +++++++++++++----- 1 file changed, 201 insertions(+), 73 deletions(-) diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index 4edc56895a4..bfa7b3e26f9 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -2,38 +2,215 @@ Configuration Parameters ======================== -Nextcloud uses the ``config/config.php`` file to control server operations. -``config/config.sample.php`` lists all the configurable parameters within -Nextcloud, along with example or default values. This document provides a more -detailed reference. Most options are configurable on your Admin page, so it -is usually not necessary to edit ``config/config.php``. - -.. note:: The installer creates a configuration containing the essential parameters. - Only manually add configuration parameters to ``config/config.php`` if you need to - use a special value for a parameter. **Do not copy everything from** - ``config/config.sample.php`` **. Only enter the parameters you wish to modify!** - -Multiple config.php file ------------------------- +Introduction +------------ + +Nextcloud uses ``config/config.php`` as its main configuration file. This file controls +various fundamental aspects of server operations. It is typically modified as part of initial +deployment, when troubleshooting, and when making adjustments to surrounding infrastructure. + +This is a required file for all Nextcloud deployments and thus it is critical for Nextcloud +administrators to be familiar with managing it. + +This section of the *Administration Manual* documents how to adjust this essential file, +certain special characteristics of the ``config/`` directory, and all of the supported +parameters that can be specified in a ``config/config.php`` file. + +.. note:: While ``config/config.php`` is a required file, many Nextcloud or Nextcloud app + settings are managed elsewhere and thus not included in it. These settings are typically + managed via individual apps. + +Loading +------- + +Configuration files located in ``config/`` are parsed automatically when Nextcloud +starts up. They are also checked for changes periodically (approximately every two seconds +in a standard PHP environment running with default *OPcache* settings; approximately every +sixty seconds in many pre-packaged Nextcloud installation methods). + +The ``config/config.php`` file may be supplemented by additional ``*.config.php`` files +placed in the ``config/`` directory (if appropriately named and formatted). + +.. danger:: Be cautious when naming or creating backup copies of your active + ``config/config.php``. If a backup is located within ``config/`` and is named + ``(ANYTHING).config.php``, it will be loaded as part of your live configuration + and override your ``config/config.php`` values! + +.. tip:: If your configuration changes don't seem to be taking effect, check: (a) your PHP opcache + configuration; (b) for additional ``*.config.php`` files located in ``config/``; (c) the documentation + for your Nextcloud installation method/package; (d) the output of ``occ config:list system``. + +Format +------ + +The short answer is that``config/`` files are plain text files with some special formatting +requirements for different types of parameters and values. This makes it extensible and easy for +Nextcloud to interact with. It also makes it easy for administartors to view with any text viewer +and from the command-line. + +Technically these configuration files are PHP files containing a special (to Nextcloud) PHP array +called ``$CONFIG``. This array consists of various Nextcloud specific "key-value" pairs (in some cases +arrays themselves). Each pair has the form ``key => value`` and is comma-separated. + +Types of Values +^^^^^^^^^^^^^^^ + +Strings: + +* ``"thisIsAnImportantValue"`` +* Note: These must be either single or double quoted - i.e. ``"string"`` or ``'string'``. +* Note: IP addresses are considered strings. +* Examples: + - ``'logo_url' => 'https://example.org',`` + - ``'versions_retention_obligation' => 'auto, D',`` + - ``'logtimezone' => 'Europe/Berlin',`` + +Boolean: + +* ``true`` or ``false`` +* Note: These should **not** be surrounded by quote marks within the configuration file itself. +* Examples: + - ``'session_keepalive' => true,`` + - ``'hide_login_form' => false,`` + +Numerical: + +* ``12`` +* This includes both integers and floating point numbers. +* Note: These should **not** be surrounded by quote marks within the configuration file itself. +* Examples: + - ``'loglevel' => 2,`` + - ``'session_lifetime' => 60 * 60 * 24,`` + +Arrays of any of the above types: + +* ``[ 'value1', 'value2' ]`` +* All value types (including other arrays) can be included in arrays. +* Note: Only some parameters support array style values. +* Examples: + - ``'connectivity_check_domains' => [ 'www.nextcloud.com', 'www.eff.org', ],`` + - ``'enabledPreviewProviders' => [ 'OC\Preview\BMP', 'OC\Preview\GIF', 'OC\Preview\JPEG', ],`` + +.. tip:: Nextcloud attempts to remedy some value type/formatting mistakes, but this is not foolproof. + Use the correct formatting (for the type of value in question) to avoid unexpected results arising + from values being cast in unexpected ways. + +Modifying +--------- + +Parameters may be modified in a standard text editor (i.e. via the command-line or from a PC +then re-uploaded). They may also, in most cases, be modified using the commands in +the ``occ config:system:*`` namespace. + +.. tip:: Incorrectly formatted ``key => value`` entries (or incorrectly specified values) may + not generate immediate errors or problems (such as parsing / syntax errors), but may still + lead to unexpected and undesirable results. Review your fully parsed (by PHP) configuration + by using the command ``occ config:list system`` and/or ``occ config:list system --private`` + to identify anything unexpected. + +Defaults +-------- + +Nextcloud creates a base ``config/config.php`` file at installation time containing the most +essential parameters for operations. These values are a mixture of auto-generated and drawn from +information provided by the administrator at installation time. + +The file ``config/config.sample.php`` lists all the parameters within Nextcloud that can be +specified in ``config/`` files, along with example and default values for each. The content of +that sample configuration file is included here for ease of reference and alongside additional +context. + +.. tip:: Only add parameters to ``config/config.php`` that you wish to modify. + +.. danger:: **Do not copy everything from ``config/config.sample.php`` into your own + ``config/config.php``!** Besides being unnecessary, it will break things and possibly even + require re-installation. + +Multiple/Merged Configuration Files +----------------------------------- + +Nextcloud supports loading configuration parameters from multiple files. You can add arbitrary +files ending with ``.config.php*`` (i.e. ``*.config.php``) in the ``config/`` directory. The values +in these files take precedence over ``config/config.php``. This allows you to easily create and +manage custom configurations, or to divide a large complex configuration file into a set of smaller files. +These custom files are not overwritten by Nextcloud. + +For example, you could place your email server configuration in ``config/email.config.php`` and +whatever parameters you specify in it will be merged with your ``config/config.php``. + +.. note:: The values in these additional configuration files **always** take precedence over + ``config/config.php``. + +.. tip:: To view your fully merged configuration (i.e. incorporating all config files), use + ``occ config:list system`` and/or ``occ config:list system --private``. + +.. danger:: Be cautious when naming or creating backup copies of your active + ``config/config.php``. If a backup config file is located within ``config/`` and happens to be + named ``(ANYTHING).config.php``, it will be loaded as part of your live configuration and override + your ``config/config.php`` values! + +Examples +-------- + +These are some examples of the content of typical ``config/config.php`` files immediately after +a basic installation of Nextcloud. + +When you use SQLite as your Nextcloud database, your ``config.php`` looks like +this after installation. The SQLite database is stored in your Nextcloud +``data/`` directory:: + + 'occ6f7365735', + 'passwordsalt' => '2c5778476346786306303', + 'trusted_domains' => + array ( + 0 => 'localhost', + 1 => 'studio', + ), + 'datadirectory' => '/var/www/nextcloud/data', + 'dbtype' => 'sqlite3', + 'version' => '7.0.2.1', + 'installed' => true, + ); + +.. note:: SQLite is a simple, lightweight embedded database that is fine for testing + and simple installations, but production environments you should use MySQL/MariaDB, + Oracle, or PosgreSQL. + +This example is from a new Nextcloud installation using MariaDB:: + + 'oc8c0fd71e03', + 'passwordsalt' => '515a13302a6b3950a9d0fdb970191a', + 'trusted_domains' => + array ( + 0 => 'localhost', + 1 => 'studio', + 2 => '192.168.10.155' + ), + 'datadirectory' => '/var/www/nextcloud/data', + 'dbtype' => 'mysql', + 'version' => '7.0.2.1', + 'dbname' => 'nextcloud', + 'dbhost' => 'localhost', + 'dbtableprefix' => 'oc_', + 'dbuser' => 'oc_carla', + 'dbpassword' => '67336bcdf7630dd80b2b81a413d07', + 'installed' => true, + ); -Nextcloud supports loading configuration parameters from multiple files. -You can add arbitrary files ending with :file:`.config.php` in the :file:`config/` -directory, for example you could place your email server configuration -in :file:`email.config.php`. This allows you to easily create and manage -custom configurations, or to divide a large complex configuration file -into a set of smaller files. These custom files are not overwritten by -Nextcloud, and the values in these files take precedence over :file:`config.php`. .. The following section is auto-generated from .. https://github.com/nextcloud/server/blob/master/config/config.sample.php .. Do not edit this file; edit the source file in core .. DEFAULT_SECTION_START +Auto-generated Parameters +------------------------- -Default Parameters ------------------- - -These parameters are configured by the Nextcloud installer, and are required +These parameters are generated by the Nextcloud installer, and are required for your Nextcloud server to operate. @@ -261,55 +438,6 @@ Defaults to ``false`` .. DEFAULT_SECTION_END .. Generated content above. Don't change this. -Default config.php Examples ---------------------------- -When you use SQLite as your Nextcloud database, your ``config.php`` looks like -this after installation. The SQLite database is stored in your Nextcloud -``data/`` directory. SQLite is a simple, lightweight embedded database that -is good for testing and for simple installations, but for production Nextcloud -systems you should use MySQL, MariaDB, or PosgreSQL. - -:: - - 'occ6f7365735', - 'passwordsalt' => '2c5778476346786306303', - 'trusted_domains' => - array ( - 0 => 'localhost', - 1 => 'studio', - ), - 'datadirectory' => '/var/www/nextcloud/data', - 'dbtype' => 'sqlite3', - 'version' => '7.0.2.1', - 'installed' => true, - ); - -This example is from a new Nextcloud installation using MariaDB:: - - - 'oc8c0fd71e03', - 'passwordsalt' => '515a13302a6b3950a9d0fdb970191a', - 'trusted_domains' => - array ( - 0 => 'localhost', - 1 => 'studio', - 2 => '192.168.10.155' - ), - 'datadirectory' => '/var/www/nextcloud/data', - 'dbtype' => 'mysql', - 'version' => '7.0.2.1', - 'dbname' => 'nextcloud', - 'dbhost' => 'localhost', - 'dbtableprefix' => 'oc_', - 'dbuser' => 'oc_carla', - 'dbpassword' => '67336bcdf7630dd80b2b81a413d07', - 'installed' => true, - ); - .. Generated content below. Don't change this. .. ALL_OTHER_SECTIONS_START From 7609fb6a71401c4b3ec510b6b0f5c99da0e25c0a Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 10 Dec 2024 09:51:16 -0500 Subject: [PATCH 2/4] fix: typo found during review Also changed "PC" reference to "externally" to be more generic. Signed-off-by: Josh --- .../configuration_server/config_sample_php_parameters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index bfa7b3e26f9..5a6eb19f46c 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -43,7 +43,7 @@ placed in the ``config/`` directory (if appropriately named and formatted). Format ------ -The short answer is that``config/`` files are plain text files with some special formatting +The short answer is that ``config/`` files are plain text files with some special formatting requirements for different types of parameters and values. This makes it extensible and easy for Nextcloud to interact with. It also makes it easy for administartors to view with any text viewer and from the command-line. @@ -98,7 +98,7 @@ Arrays of any of the above types: Modifying --------- -Parameters may be modified in a standard text editor (i.e. via the command-line or from a PC +Parameters may be modified in a standard text editor (i.e. via the command-line or externally then re-uploaded). They may also, in most cases, be modified using the commands in the ``occ config:system:*`` namespace. From 89f282a8f8125988dc133b1d7a0d4fd5e9018527 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Tue, 10 Dec 2024 10:12:02 -0500 Subject: [PATCH 3/4] fix: small formatting error found upon compilation Signed-off-by: Josh Richards --- .../configuration_server/config_sample_php_parameters.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index 5a6eb19f46c..ebac46c2c2b 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -122,8 +122,8 @@ context. .. tip:: Only add parameters to ``config/config.php`` that you wish to modify. -.. danger:: **Do not copy everything from ``config/config.sample.php`` into your own - ``config/config.php``!** Besides being unnecessary, it will break things and possibly even +.. danger:: Do not copy everything from ``config/config.sample.php`` into your own + ``config/config.php``! Besides being unnecessary, it will break things and possibly even require re-installation. Multiple/Merged Configuration Files From df60e7466d464dc68dc02ced5bc4bde9e1e75384 Mon Sep 17 00:00:00 2001 From: Josh Richards Date: Tue, 10 Dec 2024 12:33:02 -0500 Subject: [PATCH 4/4] fix: add ref link to sample config section per review suggestion Signed-off-by: Josh Richards --- .../configuration_server/config_sample_php_parameters.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index ebac46c2c2b..4e538e2a313 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -117,8 +117,8 @@ information provided by the administrator at installation time. The file ``config/config.sample.php`` lists all the parameters within Nextcloud that can be specified in ``config/`` files, along with example and default values for each. The content of -that sample configuration file is included here for ease of reference and alongside additional -context. +that sample configuration file is included :ref:`below` for ease of reference +and alongside additional context. .. tip:: Only add parameters to ``config/config.php`` that you wish to modify. @@ -438,6 +438,8 @@ Defaults to ``false`` .. DEFAULT_SECTION_END .. Generated content above. Don't change this. +.. _config-php-sample: + .. Generated content below. Don't change this. .. ALL_OTHER_SECTIONS_START