Putting Nextcloud into / out of Maintenance Mode

Maintenance mode stops most user‑facing actions while you carry out upgrades, migrations or other risky work.

1. Enable Maintenance Mode

# Switch to the web‑server user (usually www-data) and run the OCC tool
sudo -u www-data php /path/to/nextcloud/occ maintenance:mode --on

• What happens
• All web requests return the message “Nextcloud is in maintenance mode…” – users cannot log in or upload files.
• Background jobs (cron, webcron, system cron) are paused, so no sync, file‑scanning or external‑storage tasks run.
• Database schema changes and app upgrades can be performed safely because no other process is writing to the DB.

2. Verify it’s on

sudo -u www-data php /path/to/nextcloud/occ maintenance:mode --status

You should see maintenance mode is enabled.

3. Disable Maintenance Mode

sudo -u www-data php /path/to/nextcloud/occ maintenance:mode --off

• What happens
• The “maintenance” banner disappears and users can log in again.
• Cron jobs resume; any queued background tasks are executed on the next run.

4. Quick alternative (config file)

If the OCC command is unavailable you can edit config/config.php:

'maintenance' => true,   // turn on
'maintenance' => false,  // turn off

Note: After editing the file you must clear the PHP opcache (e.g. service php8.1-fpm reload) for the change to take effect.

Implications of Using Maintenance Mode

Changing the Log Level (Fatal → Debug)

Nextcloud writes to data/nextcloud.log by default. The log level determines how much detail is stored.

1. Set the log level via OCC

# Example: switch to Debug (level 4)
sudo -u www-data php /path/to/nextcloud/occ config:system:set loglevel --value=4

To revert to a production‑friendly level (e.g. Error):

sudo -u www-data php /path/to/nextcloud/occ config:system:set loglevel --value=1

2. Set the log level by editing config.php

Add or modify the entry:

'loglevel' => 4,   // Debug

After saving, reload PHP (or simply wait a few seconds – Nextcloud reads the file on each request).

3. Choose a log backend (optional)

You can also send logs to syslog or a remote service:

sudo -u www-data php /path/to/nextcloud/occ config:system:set logfile --value='/var/log/nextcloud.log'
sudo -u www-data php /path/to/nextcloud/occ config:system:set logtimezone --value='UTC'
sudo -u www-data php /path/to/nextcloud/occ config:system:set log_type --value='syslog'   # options: file, syslog, errorlog

4. Practical tips for Debug logging

• Rotate logs – Debug can fill a few megabytes per hour. Set up logrotate:

  /var/log/nextcloud.log {
      weekly
      rotate 4
      compress
      missingok
      notifempty
      create 640 www-data adm
  }

• Limit duration – Only enable Debug while you are actively troubleshooting, then switch back to Error or Warning.

• Sensitive data – Debug may log request parameters, URLs or file names. Avoid leaving it on in a production environment for security and GDPR reasons.

• Viewing the log – Use tail -f /var/log/nextcloud.log to watch live output, or grep for a specific app:

  grep -i 'files_external' /var/log/nextcloud.log

• Web UI – The Admin settings → Logging page shows the current level and a small viewer, but the file gives the full picture.

Quick Checklist

• Before maintenance

1. Put Nextcloud into maintenance mode (occ maintenance:mode --on).
2. Verify status.
3. (Optional) Raise log level to Debug if you need extra detail during the upgrade.

• During maintenance
• Run the upgrade / migration commands.
• Monitor the log for any errors.

• After maintenance

1. Reset log level to a normal production value (loglevel = 1 or 2).
2. Disable maintenance mode (occ maintenance:mode --off).
3. Run a quick health check (occ status, occ db:convert-type, occ maintenance:mode --status).

Following these steps keeps your Nextcloud instance safe, minimises downtime for users, and gives you the diagnostic information you need when things go wrong.