Skip to content

Commit 1df4a67

Browse files
susnuxsusnux
committed
feat(admin): document SSL/TLS encryption of database connection
ref: nextcloud/server#62958 Assisted-by: ClaudeCode:claude-opus-5 Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>
1 parent 4263c96 commit 1df4a67

4 files changed

Lines changed: 241 additions & 0 deletions

File tree

‎admin_manual/configuration_database/linux_database_configuration.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,13 @@ This just covers the SSL database configuration on the Nextcloud server. First y
188188

189189
Adjust the paths to the pem files for your environment.
190190

191+
.. tip::
192+
The encrypted connection can also be set up during the installation, so that
193+
no unencrypted connection is used at any point. See
194+
:ref:`autoconfig_database_encryption_label` when installing with an
195+
autoconfig file, or :ref:`command_line_installation_ssl_label` when
196+
installing with ``occ maintenance:install``.
197+
191198
.. _db-config-postgresql-label:
192199

193200
PostgreSQL database
@@ -292,6 +299,35 @@ this:
292299
"dbhost" => "localhost",
293300
"dbtableprefix" => "oc_",
294301

302+
SSL for PostgreSQL database
303+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
304+
305+
As with MySQL, enabling SSL is only necessary if your database does not reside on the same server as your
306+
Nextcloud instance. First configure your database server accordingly, then add the ``pgsql_ssl``
307+
configuration to your :file:`config/config.php`.
308+
309+
::
310+
311+
'pgsql_ssl' => [
312+
'mode' => 'verify-full',
313+
'rootcert' => '/../ca-cert.pem',
314+
'cert' => '/../ssl-cert.pem',
315+
'key' => '/../ssl-key.pem',
316+
],
317+
318+
The ``mode`` corresponds to the ``sslmode`` connection parameter of PostgreSQL, see the
319+
`PostgreSQL documentation
320+
<https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS>`_ for the
321+
available modes. Only ``verify-full`` verifies that the certificate of the database server was
322+
issued for the hostname used to connect. Adjust the paths to the pem files for your environment.
323+
324+
.. tip::
325+
The encrypted connection can also be set up during the installation, so that
326+
no unencrypted connection is used at any point. See
327+
:ref:`autoconfig_database_encryption_label` when installing with an
328+
autoconfig file, or :ref:`command_line_installation_ssl_label` when
329+
installing with ``occ maintenance:install``.
330+
295331
.. _db-troubleshooting-label:
296332

297333
Troubleshooting

‎admin_manual/installation/automatic_configuration.rst‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,8 @@ The following parameters are commonly used:
4040
``dbtableprefix``
4141
* ``adminlogin`` and ``adminpass``
4242
* optionally, ``trusted_domains`` and ``adminemail``
43+
* optionally, the parameters of an
44+
:ref:`encrypted database connection <autoconfig_database_encryption_label>`
4345

4446
Two parameters have different names from their corresponding
4547
:file:`config.php` settings:
@@ -52,6 +54,70 @@ Two parameters have different names from their corresponding
5254
| ``dbpass`` | ``dbpassword`` |
5355
+--------------------+-------------------+
5456

57+
.. _autoconfig_database_encryption_label:
58+
59+
Encrypted database connection
60+
-----------------------------
61+
62+
.. versionadded:: 35
63+
64+
An SSL/TLS encrypted connection to the database server can be configured during
65+
the installation. Use this when the database does not run on the same host as
66+
Nextcloud, so that the credentials and all queries are not sent in plaintext.
67+
68+
The following parameters are independent of the database backend. Nextcloud
69+
translates them into the corresponding :file:`config.php` settings before the
70+
first connection is opened, so the installation itself already uses an
71+
encrypted connection.
72+
73+
.. list-table:: Connection encryption parameters
74+
:header-rows: 1
75+
:widths: 20 20 60
76+
77+
* - Parameter
78+
- Supported by
79+
- Description
80+
* - ``dbsslmode``
81+
- PostgreSQL
82+
- Encryption mode of the connection, for example ``require`` or
83+
``verify-full``. See the `PostgreSQL documentation
84+
<https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS>`_
85+
for the available modes.
86+
* - ``dbsslca``
87+
- MySQL/MariaDB, PostgreSQL
88+
- Path to the CA certificate the database server is verified against.
89+
* - ``dbsslcert``
90+
- MySQL/MariaDB, PostgreSQL
91+
- Path to the client certificate used to authenticate against the
92+
database server.
93+
* - ``dbsslkey``
94+
- MySQL/MariaDB, PostgreSQL
95+
- Path to the private key belonging to the client certificate.
96+
* - ``dbsslcrl``
97+
- PostgreSQL
98+
- Path to the certificate revocation list.
99+
* - ``dbsslnoverify``
100+
- MySQL/MariaDB
101+
- Set to ``true`` to not verify that the certificate of the database
102+
server matches the hostname used to connect. MySQL and MariaDB verify
103+
this by default, PostgreSQL only in the ``verify-full`` mode.
104+
105+
Note the following restrictions:
106+
107+
* ``dbsslcert`` and ``dbsslkey`` have to be provided together.
108+
* A parameter that the selected database does not support is rejected with an
109+
error instead of being ignored, and the installation does not proceed.
110+
SQLite and Oracle support none of them — an Oracle connection is encrypted
111+
through the connect string and :file:`sqlnet.ora` instead.
112+
* The certificates and keys have to be readable by the PHP process.
113+
114+
Alternatively, the backend-specific ``dbdriveroptions`` (MySQL/MariaDB) and
115+
``pgsql_ssl`` (PostgreSQL) settings, as documented in
116+
:doc:`../configuration_server/config_sample_php_parameters`, can be written to
117+
:file:`autoconfig.php` verbatim. They are passed to :file:`config.php` as
118+
provided and are not validated. Values set through the parameters above take
119+
precedence over individual entries of these arrays.
120+
55121
Examples
56122
--------
57123

@@ -122,6 +188,53 @@ directory and administrator-account settings in the setup form.
122188
"dbtableprefix" => "",
123189
];
124190
191+
Encrypted MySQL / MariaDB connection
192+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
193+
194+
This configuration connects to a remote MySQL or MariaDB server over an
195+
encrypted connection, verifying the server against a CA certificate and
196+
authenticating with a client certificate.
197+
198+
.. code-block:: php
199+
200+
<?php
201+
$AUTOCONFIG = [
202+
"dbtype" => "mysql",
203+
"dbname" => "nextcloud",
204+
"dbuser" => "username",
205+
"dbpass" => "password",
206+
"dbhost" => "db.example.com",
207+
"dbtableprefix" => "",
208+
"dbsslca" => "/etc/ssl/nextcloud/ca-cert.pem",
209+
"dbsslcert" => "/etc/ssl/nextcloud/client-cert.pem",
210+
"dbsslkey" => "/etc/ssl/nextcloud/client-key.pem",
211+
];
212+
213+
Nextcloud stores these paths as ``dbdriveroptions`` in :file:`config.php`.
214+
215+
Encrypted PostgreSQL connection
216+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
217+
218+
This configuration requires an encrypted connection to a remote PostgreSQL
219+
server and verifies both the certificate of the server and the hostname it was
220+
issued for.
221+
222+
.. code-block:: php
223+
224+
<?php
225+
$AUTOCONFIG = [
226+
"dbtype" => "pgsql",
227+
"dbname" => "nextcloud",
228+
"dbuser" => "username",
229+
"dbpass" => "password",
230+
"dbhost" => "db.example.com",
231+
"dbtableprefix" => "",
232+
"dbsslmode" => "verify-full",
233+
"dbsslca" => "/etc/ssl/nextcloud/ca-cert.pem",
234+
];
235+
236+
Nextcloud stores these values as ``pgsql_ssl`` in :file:`config.php`.
237+
125238
Complete non-interactive setup
126239
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
127240

‎admin_manual/installation/command_line_installation.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ For the complete manual-installation prerequisites, see
5353
5454
$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install --help
5555
56+
When the database runs on another host, encrypt the connection using the
57+
``--database-ssl-*`` options described in
58+
:ref:`command_line_installation_ssl_label` below.
59+
5660
Supported databases are:
5761

5862
- ``sqlite`` (SQLite)
@@ -64,4 +68,71 @@ Supported databases are:
6468
The selected database requires its corresponding PHP extension or driver to be
6569
installed and enabled.
6670

71+
.. _command_line_installation_ssl_label:
72+
73+
Encrypted database connection
74+
-----------------------------
75+
76+
.. versionadded:: 35
77+
78+
When the database does not run on the same host as Nextcloud, the connection
79+
should be encrypted so that the credentials and all queries are not sent in
80+
plaintext. The following options configure this during the installation, so
81+
that the installation itself already uses an encrypted connection:
82+
83+
.. list-table:: SSL/TLS options of ``maintenance:install``
84+
:header-rows: 1
85+
:widths: 30 20 50
86+
87+
* - Option
88+
- Supported by
89+
- Description
90+
* - ``--database-ssl-mode``
91+
- ``pgsql``
92+
- Encryption mode of the connection, for example ``require`` or
93+
``verify-full``. See the `PostgreSQL documentation
94+
<https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS>`_
95+
for the available modes.
96+
* - ``--database-ssl-ca``
97+
- ``mysql``, ``pgsql``
98+
- Path to the CA certificate the database server is verified against.
99+
* - ``--database-ssl-cert``
100+
- ``mysql``, ``pgsql``
101+
- Path to the client certificate used to authenticate against the
102+
database server.
103+
* - ``--database-ssl-key``
104+
- ``mysql``, ``pgsql``
105+
- Path to the private key belonging to the client certificate.
106+
* - ``--database-ssl-crl``
107+
- ``pgsql``
108+
- Path to the certificate revocation list.
109+
* - ``--database-ssl-no-verify``
110+
- ``mysql``
111+
- Do not verify that the certificate of the database server matches the
112+
hostname used to connect. MySQL and MariaDB verify this by default,
113+
PostgreSQL only in the ``verify-full`` mode.
114+
115+
``--database-ssl-cert`` and ``--database-ssl-key`` have to be provided
116+
together. Passing an option that the selected database does not support aborts
117+
the installation with an error — ``sqlite`` and ``oci`` support none of them.
118+
The certificates and keys have to be readable by the PHP process.
119+
120+
This example installs Nextcloud with a remote MySQL database, verifying the
121+
server against a CA certificate:
122+
123+
.. code-block:: console
124+
125+
$ sudo -E -u www-data php /var/www/nextcloud/occ maintenance:install \
126+
--database mysql --database-name nextcloud \
127+
--database-host db.example.com \
128+
--database-user nextcloud \
129+
--database-ssl-ca /etc/ssl/nextcloud/ca-cert.pem \
130+
--admin-user admin
131+
132+
Nextcloud writes the resulting configuration to ``dbdriveroptions``
133+
(MySQL/MariaDB) or ``pgsql_ssl`` (PostgreSQL) in ``config.php``, see
134+
:doc:`../configuration_server/config_sample_php_parameters`. The same
135+
connection can be configured for the Installation Wizard, see
136+
:ref:`autoconfig_database_encryption_label`.
137+
67138
See :ref:`command_line_installation_label` for more information.

‎admin_manual/occ_system.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -904,6 +904,22 @@ Display the available installation options:
904904
--database-pass[=DATABASE-PASS] Password of the database login
905905
--database-table-space[=DATABASE-TABLE-SPACE]
906906
Table space of the database (``oci`` only)
907+
--database-ssl-mode[=DATABASE-SSL-MODE]
908+
Encryption mode for the database connection,
909+
e.g. "require" or "verify-full" (``pgsql`` only)
910+
--database-ssl-ca[=DATABASE-SSL-CA] Path to the CA certificate the database server
911+
is verified against (``mysql`` and ``pgsql`` only)
912+
--database-ssl-cert[=DATABASE-SSL-CERT]
913+
Path to the client certificate used to
914+
authenticate against the database
915+
(``mysql`` and ``pgsql`` only)
916+
--database-ssl-key[=DATABASE-SSL-KEY] Path to the private key of the client certificate
917+
(``mysql`` and ``pgsql`` only)
918+
--database-ssl-crl[=DATABASE-SSL-CRL] Path to the certificate revocation list
919+
(``pgsql`` only)
920+
--database-ssl-no-verify Do not verify that the database server certificate
921+
matches the hostname used to connect
922+
(``mysql`` only)
907923
--disable-admin-user Disable the creation of an administrator login
908924
--admin-user[=ADMIN-USER] Login for initial administrator account [default: "admin"]
909925
--admin-pass[=ADMIN-PASS] Password for initial administrator login
@@ -935,6 +951,11 @@ Supported databases:
935951
* ``oci`` — Oracle; contact `Nextcloud GmbH
936952
<https://nextcloud.com/enterprise/>`_ for enterprise support
937953

954+
.. versionadded:: 35
955+
The ``--database-ssl-*`` options set up an SSL/TLS encrypted connection to
956+
the database, see
957+
:ref:`Encrypted database connection <command_line_installation_ssl_label>`.
958+
938959
.. _command_line_upgrade_label:
939960

940961
Command line upgrade

0 commit comments

Comments
 (0)