Download the PHP package tearoom1/kirby-ftp-backup without Composer

Kirby FTP Backup

A Kirby CMS plugin that creates backups of your site content and uploads them to an FTP server.

Features

• Create ZIP backups of your site content
• Automatic upload to FTP server
• Configurable backup retention
• Panel interface for manual backups and downloads
• Scheduled backups via cron job

Installation

Manual Installation

1. Download or clone this repository
2. Place the folder kirby-ftp-backup in your site's /site/plugins directory

Composer Installation

Configuration

All configuration is handled through Kirby's option system. Add the following to your site/config/config.php file:

Configuration Options

Plugin Control Options

Disable Entire Plugin

To completely disable the plugin (no backups will be created):

When disabled:

• Panel UI will not be accessible
• API routes will return error responses
• CLI commands will not execute
• URL-based execution will be blocked

Access Control

By default, only users with the admin role can access the plugin — that includes the panel area, the menu entry, the stats view, listing/creating/cancelling backups, and downloading backup files. Non-admins will not see the menu item at all, and any direct API call returns 403 Forbidden.

If you want to grant access to additional Kirby roles (for example, an editor or a dedicated backup-operator role), list them in allowedRoles:

Notes:

• Admins are always allowed; you do not need to include 'admin' in the list.
• Users with any of the listed roles get full access — there is no read-only mode. They can create backups, download archives (which contain your entire site), and cancel running jobs. Only grant this to roles you fully trust.
• The allowedRoles option does not apply to the URL-based /ftp-backup/execute endpoint — that endpoint is protected by its own token and is intended for unauthenticated cron-style use (see URL-Based Backup Execution).

Disable FTP Only

To create backups locally but skip FTP uploads:

When FTP is disabled:

• Backups are still created and stored locally
• No FTP connection or upload attempts
• Local retention policies still apply
• Panel UI remains functional for viewing/downloading local backups

This is useful when:

• You want local backups only
• FTP server is temporarily unavailable
• Testing backup creation without uploading
• Migrating between FTP servers

Retention Strategies

The plugin supports two retention strategies for managing old backups:

Simple Retention

Keeps a fixed number of most recent backups, discarding older ones. This is controlled by the backupRetention option.

Tiered Retention

A more sophisticated approach that keeps backups with decreasing frequency as they age:

This strategy:

1. Keeps all backups from the last X days
2. Then keeps one backup per week for Y weeks
3. Then keeps one backup per month for Z months
4. Deletes anything older

This provides a good balance between recent recovery points and long-term archiving.

File Filtering

You can control which files are included in backups using regex patterns. This is useful for excluding large media files, temporary files, or other content you don't need to back up.

How it works

1. Default behavior: All files are included
2. Include patterns: If specified, only files matching these patterns are included
3. Dedicated excludes: excludeContentWatch, excludeDrafts and excludePaths are applied before regex patterns
4. Exclude patterns: Files matching these patterns are always excluded
5. Case-insensitive: Regex patterns are automatically case-insensitive

Examples

Exclude specific file types:

Exclude Content Watch history and drafts:

Exclude specific relative paths:

Include only specific file types:

Exclude large media files but keep images:

Complex filtering:

Note: Patterns are standard regex patterns without delimiters. The plugin automatically adds # delimiters and makes all patterns case-insensitive.

Panel Interface

The plugin adds a "FTP Backup" area to your Kirby Panel:

• View all available backups
• Create new backups manually with live progress indication
• Cancel a running backup
• Download existing backups
• View backup statistics (count, total size, latest backup)
• View FTP server stats and file listing

Automatic Backups with Cron

To set up automatic backups, add a cron job to your server. The cron job should run the included run.php script:

Optionally the path to the kirby root directory can be passed as the first argument:

The root directory is the one with the kirby folder inside.

Successful runs are silent by default. This can be configured globally:

The cron command can override the configuration for a single invocation:

Errors are always written to STDERR and return a non-zero exit code.

Example Crontab Entry

To run a backup every day at 2 AM:

Replace /path/to/site with the actual path to your Kirby installation.

Using the Run Script

The run.php script handles:

• Creating a new backup
• Uploading the backup to the configured FTP server
• Cleaning up old backups based on the retention setting
• Optionally printing successful runs, controlled by configuration or --silent/--verbose
• Writing a message to STDERR and returning exit code 1 on failure

URL-Based Backup Execution

As an alternative to cron jobs, you can trigger backups via HTTP requests. This is useful for:

• External monitoring services
• Webhook-based automation
• Manual triggering from remote systems
• URL based cronjob execution

Configuration

First, enable URL execution and set a secure token in your config.php:

⚠️ Security: the token is the only thing protecting this endpoint. The /ftp-backup/execute URL is publicly reachable whenever urlExecutionEnabled is true — it is not behind the panel login, only behind the token. The plugin does not rate-limit failed attempts, so a weak token can be brute-forced.

You must:

• Generate a long, high-entropy token (at least 32 random characters), e.g. openssl rand -hex 32 or php -r "echo bin2hex(random_bytes(32));". Never use a guessable string.
• Treat the token like a password: do not commit it to public repos, do not share it in chats, rotate it if exposed.
• Prefer HTTPS so the token is not sent in the clear.
• For defense in depth, add rate limiting / IP allow-listing at the web server level (e.g. fail2ban, nginx limit_req, Cloudflare rules). The plugin itself does not throttle requests.
• If you don't need URL execution, leave urlExecutionEnabled set to false.

Usage

Once configured, you can trigger a backup by making a GET request to:

Security Features

• Token Authentication: Requires a matching token to execute
• Enable/Disable Toggle: Can be completely disabled via configuration
• Timing-Safe Comparison: Uses hash_equals() to prevent timing attacks
• Plain Text Response: Returns simple status messages for easy monitoring

Not provided by the plugin: rate limiting on the execute endpoint. Token strength and any throttling are entirely your responsibility — see the warning above.

Example Response

On success:

On error:

Advanced Options

ftpTimeout

How long to wait for the server to respond to each individual packet, in seconds. This is not a total transfer timeout — large files will transfer for as long as needed as long as the connection stays active. The default of 30 seconds is appropriate for most servers. Increase it only if uploads fail on very slow or high-latency connections.

ftpKeepAlive (SFTP only)

Sends an SSH keepalive packet every N seconds to prevent firewalls or load balancers from dropping idle connections during large uploads. Disabled by default (0).

Note: Some OpenSSH servers respond to keepalives with a [email protected] global request that phpseclib cannot handle mid-transfer, which can interrupt the upload. Only enable this if you have confirmed that idle-timeout drops are the cause of your upload failures.

Security Considerations

• Store your FTP credentials securely in your config.php file
• Make sure your config.php file is not accessible from the web
• Consider using SFTP or FTP with SSL for secure transfers
• Regularly verify that your backups are being created and can be restored

Troubleshooting

If you encounter issues:

1. Check that your FTP credentials and server settings are correct
2. Verify that the FTP directory exists and has write permissions
3. Check your server's PHP error logs for any PHP errors
4. Make sure the local backup directory is writable by PHP
5. Check if you have the required PHP extensions (zip, ftp)
6. If uploads fail on slow or high-latency connections, increase ftpTimeout — see Advanced Options
7. If you get a 504 Gateway Timeout when creating backups from the Panel, increase your web server's proxy/fastcgi read timeout to match or exceed max_execution_time in your php.ini

Requirements

• Kirby 4+
• PHP 7.4+
• PHP ZIP extension
• PHP FTP extension

Tests

The tests can be run with:

Make sure to cleanup the vendor after running tests, to remove dev dependencies.

License

This plugin is licensed under the MIT License

Credits

• Developed by Mathis Koblin
• Assisted by AI Claude Sonnet 4.6