How do I momentarily disable Matomo User Interface and/or Matomo visitor Tracking?

Before a Database upgrade on a high traffic Matomo server, it is highly recommended to:

Disable Matomo Tracking

In the config/config.ini.php, add the following

[Tracker]
record_statistics = 0

This will cause all Matomo Tracking API requests (to matomo.php or piwik.php) to return quickly the response and status code 204, without connecting to the database or doing any processing. Requests for configs.php for Heatmaps & Session Recordings will still return a status code 200.

Disable the Matomo User Interface and APIs

To disable the User Interface and the APIs, but still track all of your data correctly, you can enable maintenance mode.

When maintenance_mode is on, a maintenance message instead of the standard Matomo reporting interface. Your data is still tracked as expected, but the UI and the Reporting APIs are disabled.

If you run the Matomo Database Upgrade script using the shell/console command, we highly recommend turning Matomo off while the upgrade is in process. Disabling the Matomo User Interface will prevent other users from accessing Matomo while the Database upgrade is in process.

To do so, add the following in the config file:

[General]
maintenance_mode = 1

If the line [General] already exists, add the line maintenance_mode = 1 below the line [General].

The following XML messages will be returned by the API:

<result><error message="Matomo is in scheduled maintenance. Please come back later. "/></result>

The Reporting API endpoint index.php will return an HTTP error status code 503 (Service unavailable) while it is in maintenance mode. Unless Matomo is configured behind a load balancer, with General config multi_server_environment=1, should return HTTP status code 200

Re-enable Tracking API and UI

When the Matomo update is finished, do not forget to re-enable Visit Tracking and/or the User Interface.

And if you need to recover any missing data that wasn’t tracked during the maintenance window, learn more in about replay the traffic to Matomo and ingest logs of piwik.php requests