Add FAQ for how to use SSL connections to MySQL

[diosmosis]

After adding the FAQ, change the link in DbOverSSLCheck.php.

Steps to using an SSL connection to MySQL include:

1. obtain SSL keys and certificate files generated using the same version of openssl as MySQL
2. in config.ini.php's [database] section, set the ssl_cert, ssl_key, ssl_ca to absolute paths to the required files (and make sure PHP can read those files or you'll get strange MySQL errors)
3. Optionally set ssl_cipher to your desired cipher
4. If you're using a self signed certificate (& your PHP version has a PDO/MySQLi that supports skipping the verification check), set the ssl_no_verify option to 1.
5. Verify in the Piwik system check that you are using an SSL connection to the database.

Not sure if this is accurate for cloud providers, and this doesn't work if the MySQL instance requires SSL, since in that case you won't be able to actually install Piwik (at least not through the web UI). We should add links to the cloud provider docs for obtaining required files as well.

Refs #10866

[fitzoh]

For reference, my config looked like this using the AWS RDS version of MySQL:

; Database SSL Options START
; Turn on or off SSL connection to database, possible values for enable_ssl: 1 or 0
enable_ssl = 1
; Direct path to server CA file, CA bundle supported (required for ssl connection)
ssl_ca = "/etc/mysql-certs/rds-combined-ca-bundle.pem"
; Direct path to client cert file (optional)
ssl_cert =
; Direct path to client key file (optional)
ssl_key =
; Direct path to CA cert files directory (optional)
ssl_ca_path =
; List of one or more ciphers for SSL encryption, in OpenSSL format (optional)
ssl_cipher =
; Database SSL Options END

Where rds-combined-ca-bundle.pem is from https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html

[diosmosis]

Good to know @fitzoh, guess the faq should have links to cloud provider docs, maybe AWS, Azure & Google (if required for Google).

[mattab]

Thanks @diosmosis @fitzoh
The FAQ has been published: How do I setup Matomo to securely connect to the database using MySQL SSL?

Not sure if this is accurate for cloud providers, and this doesn't work if the MySQL instance requires SSL, since in that case you won't be able to actually install Piwik (at least not through the web UI).

What do you mean by this @diosmosis ?

[diosmosis]

Details for the following:

Not sure if this is accurate for cloud providers

I think cloud providers require less setup than using a self signed certificate. Might be one or two settings, could link to their pages, eg:

AWS: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_MySQL.html#MySQL.Concepts.SSLSupport
Azure: maybe https://docs.microsoft.com/en-us/azure/mysql/howto-configure-ssl

this doesn't work if the MySQL instance requires SSL, since in that case you won't be able to actually install Piwik (at least not through the web UI).

If the MySQL server requires ssl connections, then you can't install Matomo through the UI, since there will be no config.ini.php to store the SSL options. New fields would have to be added to the db setup page (and maybe a file uploader for the certificate files). But I don't think this is super important, azure, eg, will let you require ssl later.

[hameno]

If the MySQL server requires ssl connections, then you can't install Matomo through the UI, since there will be no config.ini.php to store the SSL options. New fields would have to be added to the db setup page (and maybe a file uploader for the certificate files). But I don't think this is super important, azure, eg, will let you require ssl later.

@diosmosis I just wasted more than an hour until I found this -.- Could you please make that more explicit in the FAQ or even better provide full support for a secure-by-default setup? 😠

[diosmosis]

Hi @hameno, sorry it took you more than an hour to search for this. I can add more details to the faq, but I'm not in charge of prioritizing work in matomo, so I can't say if/when installing w/ an SSL connection to mysql will be supported.

[mattab]

Updated the FAQ https://matomo.org/faq/how-to-install/faq_26273/ with:

1. First, you need to install Matomo over standard insecure non-SSL connections. If your MySQL server requires SSL connections, then you can't install Matomo through the UI, so you will need to disable SSL temporarily while you install Matomo, and then re-enable SSL in MySQL after you installed Matomo.

@hameno feel free to create a new issue here to add support for installing over SSL (although we won't work on it anytime soon, there may be someone else who is interested and creates a pull request, which we would then review and try to merge)