Usage

The plugin registers a Backups menu in the backend.

• Application backup creates a backup of all project files and the database. By default the project base path is backed up without vendor and node_modules; change that in the plugin Settings.
• Database backup creates a database-only backup.
• Clean old backups removes old backups according to the Cleanup settings.

Permissions

Access is granted per action under Settings → Administrators, on the Backups tab. Super users bypass all of them.

Copy restore command only hides the button. Restoring runs from the console, so anybody with shell access can restore regardless of this permission.

Restoring a backup

Restoring replaces your database with the one stored inside a backup archive. It is available from the console only, because it cannot be undone. The terminal button in the backups list copies the matching command to your clipboard.

php artisan backup:restore
php artisan backup:restore --path="October CMS/2026-01-15-09-20-58.zip" --disk=local

Only the database is restored. Project files inside the archive are never touched.

You will be logged out. The dump contains backend_users and sessions, so accounts return to the state they were in when the backup was taken.

Restoring is not transactional. An import that fails halfway leaves the database inconsistent, which is why a safety backup is taken first - keep the path it prints.

A few things to know:

• Anything passed as --password shows up in ps and the shell history; on a shared server use BACKUP_RESTORE_PASSWORD or let the command ask.
• The safety backup is encrypted only with --password, never with the password from the settings, because that one lives in the database being replaced. Without --password it is stored in plain form - delete it once you have verified the restore.
• The restore waits for no other backup: if one is running, it stops before touching the database.
• Tables not present in the dump are left untouched.
• When the archive holds several dumps, the one matching --connection is used, by database name first and connection name second. If none matches, the restore stops and lists what the archive contains.
• PostgreSQL and SQLite dumps contain no drop statements, so they can only be restored into an empty database.
• The native client - mysql, psql or sqlite3 - must be in PATH, and proc_open enabled.

If the application no longer boots

A safety backup taken without --password can be imported without this application:

unzip -p "storage/app/October CMS/safety-2026-01-15-09-20-58.zip" "db-dumps/*.sql" > /tmp/recover.sql
mysql -u USER -p DATABASE < /tmp/recover.sql

Maximum execution time error

A Maximum execution time of ... seconds exceeded error means the backup is too large to finish in a single web request. You can:

1. Raise max_execution_time in your PHP configuration.
2. Use the Scheduler (recommended).
3. Use Console commands.
4. Enable Queued backups.

Queued backups

Enabling Queue backups on the Destination tab runs backend backups through the queue, so the request returns immediately and the backup continues in the background. This requires a running queue worker:

php artisan queue:work

Only a flash message is shown after clicking; open the History page to see the output once the job completed.

Leave this setting off if you do not run a queue worker, otherwise backups started from the backend will never run.

Backup history

The History page records every backup and cleanup run: when it happened, how long it took, how large the archive was and whether it succeeded. Clicking an entry shows the output of that run.

The history is a journal of what the plugin did, not a list of the archives that exist - the backups list always reads the disk. Removing an entry, selected entries or the whole history never touches the archives. Entries expire according to Keep history entries for days in the settings.

Settings

Go to Settings and open Backup Manager under the Backup section.

Database

Files

Destination

Scheduler

Configure how often the plugin runs the database backup, application backup, cleanup and health monitor.

Important note: For scheduled tasks to operate correctly you must set up the scheduler: https://docs.octobercms.com/4.x/setup/scheduler.html

Allow external trigger

For hosting without a system cron, Allow external trigger publishes three addresses that run the tasks over HTTP:

https://example.com/backupmanager/trigger/<token>/db
https://example.com/backupmanager/trigger/<token>/app
https://example.com/backupmanager/trigger/<token>/clean

Point an external cron service (cron-job.org, EasyCron, an uptime monitor) at the one you need. A 200 means the task ran, a 500 means it failed.

The address is the password. Anybody who knows it can run the task, so keep it out of tickets, screenshots and anything else that gets shared. If it leaked, Generate new addresses replaces the token and every old address stops working at once. Switching the trigger off disables the addresses immediately.

Use HTTPS only - the token travels in the URL and ends up in server, proxy and cron service logs. When the calling service can send headers, call https://example.com/backupmanager/trigger/db (or app, clean) with an X-Backup-Token header instead.

The endpoint answers 404 to a wrong token, an unknown task and a disabled trigger alike, and limits requests to five per minute per IP address and ten per minute across all addresses combined. With Queue backups enabled it returns as soon as the task is queued, and only one job per task waits in the queue at a time.

Security

Password

Password-protects the archive. Use a long string and keep it safe - without it, you will never be able to open your backup. Leave it blank for an unprotected archive.

Secrets in the file backup

With the default settings the file backup contains the whole project, including .env with APP_KEY, database credentials and storage keys. Without an archive password anyone who can read the backup can read the secrets.

Either set an archive password, or add .env to the Exclude list if your hosting recreates it. The backups page warns as long as .env is backed up without a password.

Encryption

Test decrypting an archive once, so you know the restore path works before you need it.

Warning: the default macOS archive utility cannot open encrypted ZIP files. Use The Unarchiver or BetterZip.

Cleanup

Monitoring

A backup is considered unhealthy when the latest backup is too old or the backups use more storage than allowed.

Dumping the database

If mysqldump / pg_dump is not in a default location, or the dump exceeds the default 60 second timeout, configure the connection in config/database.php:

'connections' => [
    'mysql' => [
        'driver' => 'mysql'
        ...,
        'dump' => [
           'dump_binary_path' => '/path/to/the/binary', // only the path, so without `mysqldump` or `pg_dump`
           'use_single_transaction',
           'timeout' => 60 * 5, // 5 minute timeout
           'exclude_tables' => ['table1', 'table2'],
           'add_extra_option' => '--optionname=optionvalue',
        ]
    ],

Configuring the backup disk

By default backups are saved to storage/app/October CMS/. Create a dedicated disk (for example backups) in config/filesystems.php and select it in the plugin Settings.

Filesystems

Supported storage drivers: local, S3, FTP, SFTP and Dropbox. Configure the disk in config/filesystems.php, then select it on the Destination tab of the plugin Settings.

S3

composer require league/flysystem-aws-s3-v3 "^3.0"

A sample s3 disk is included in config/filesystems.php.

FTP

composer require league/flysystem-ftp "^3.0"

'ftp' => [
    'driver' => 'ftp',
    'host' => env('FTP_HOST'),
    'username' => env('FTP_USERNAME'),
    'password' => env('FTP_PASSWORD'),

    // Optional FTP Settings...
    // 'port' => env('FTP_PORT', 21),
    // 'root' => env('FTP_ROOT'),
    // 'passive' => true,
    // 'ssl' => true,
    // 'timeout' => 30,
],

SFTP

composer require league/flysystem-sftp-v3 "^3.0"

'sftp' => [
    'driver' => 'sftp',
    'host' => env('SFTP_HOST'),

    // Settings for basic authentication...
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'),

    // Settings for SSH key based authentication with encryption password...
    'privateKey' => env('SFTP_PRIVATE_KEY'),
    'password' => env('SFTP_PASSWORD'),

    // Optional SFTP Settings...
    // 'hostFingerprint' => env('SFTP_HOST_FINGERPRINT'),
    // 'maxTries' => 4,
    // 'passphrase' => env('SFTP_PASSPHRASE'),
    // 'port' => env('SFTP_PORT', 22),
    // 'root' => env('SFTP_ROOT', ''),
    // 'timeout' => 30,
    // 'useAgent' => true,
],

Dropbox

Install the Dropbox Adapter plugin and configure the disk as described in its documentation.

Console commands

• backup:run - run a backup; --only-db backs up only the database
• backup:clean - clean old backups
• backup:list - display the status of all monitored destination filesystems
• backup:monitor - check the health of all monitored destination filesystems
• backup:restore - restore the database from a backup archive, see Restoring a backup

Notification channels

Notifications go out by e-mail, to Discord and to any service accepting a webhook. A channel is used once it has an address; leave a field empty to disable it. Configure them on the Notifications tab of the plugin Settings.

A notification is sent when a backup or cleanup succeeds or fails, and when the monitor finds a healthy or unhealthy backup.

Upgrade guide

Versions not listed here need no action.

Upgrading To 2.0.0

Plugin requires October CMS build 420+ with Laravel 5.5 and PHP >=7.0. Settings were reset to defaults, so review them.

Upgrading To 2.1.0

Dropbox support moved to the Dropbox Adapter plugin.

Upgrading To 2.1.4

The database port must be set in the database config.

Upgrading To 4.0.0

Plugin requires October CMS build 467+ with Laravel 6.x and PHP >=7.2.

Upgrading To 4.1.0

Plugin requires October CMS 1.x with Laravel 6.x and PHP >=7.3.

Upgrading To 4.2.0

Plugin requires October CMS 2.x.

Upgrading To 5.0.0

Plugin requires October CMS 3.0 or higher, Laravel 9.0 or higher and PHP >=8.0.

Upgrading To 5.1.0

Mail notification settings changed. Configure them again on the Notifications tab if you use them.

Upgrading To 6.1.0

Plugin requires PHP 8.3 or higher. spatie/laravel-backup was updated to 10.x, so run composer update.

Upgrading To 6.6.0

Run php artisan october:migrate.

Upgrading To 6.6.1

A malformed notification e-mail address is now refused when saving the settings.

Upgrading To 6.7.0

Run php artisan october:migrate. The Backup log popup was replaced by the History page; its retention is set on the Cleanup tab.

Upgrading To 7.0.0

The plugin permissions were replaced and nothing is migrated. Every role loses access to Backup Manager until you grant the new permissions by hand. Go to Settings → Role Permissions and tick what each role needs on the Backups tab; tick everything to restore what a role could do before. Super users are unaffected.

Upgrading To 7.2.0

The external trigger token is now created when the settings are saved. If you enabled Allow external trigger in 7.1.0, open the plugin settings, save them once and point your external cron service at the new addresses.

Upgrading To 7.3.0

The safety backup taken by backup:restore is encrypted only with --password (or BACKUP_RESTORE_PASSWORD); without it the safety backup is stored unencrypted.

The backup lock and queue deduplication need a cache store shared across processes. If CACHE_STORE is array, switch to file, database or redis.

The backups page warns when the file backup includes .env without an archive password. Set a password in Settings > Security or exclude .env.