Essentials Backups
Essentials Backups makes automatic backups of many Pelican servers at once. Pelican on its own backs a server up when somebody presses the button or when that server has a schedule with a backup task; on a panel with forty servers that is forty schedules to set up, and servers nobody set one up for have no backup at all. This module adds policies instead: one policy covers all servers, or those of chosen eggs, nodes or servers, says how often to back them up and how many of its own backups each server keeps. The backups themselves are made by Pelican's own backup service, exactly as if a server's schedule had made them.
At a glance
| Plugin ID | essentials-backups |
| Current version | 0.0.3 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The scheduler (it checks once a minute what is due). Backups that already work in Pelican itself, on Pelican's backup host, and a backup limit above 0 on every server you want backed up. Enough space on the backup storage. No frontend build of its own. |
| Works with (optional) | Essentials Core |
| Adds | Admin area, sidebar group Essentials Backups: page Automatic backups (/admin/essentials-automatic-backups) and page Backup policies (/admin/essentials-automatic-backups/policies). One database table, essentials_backup_runs. |
| Permissions | Role editor section Essentials Backups: view (open both pages without changing anything) and update (save the policies and use Run now). Restoring, downloading and deleting a backup stay on the server's own Backups page, under Pelican's own permissions. |
Before you install
-
Backups must already work in Pelican. Open one server, go to its Backups page, make a backup by hand and check that it finishes successfully. This module starts every backup through Pelican's own backup service, on Pelican's backup host and with Pelican's backup throttle. If a manual backup fails, every automatic one fails the same way.
-
A backup limit above 0 on the servers you want backed up. The limit is part of each server's settings in the admin area. Servers with a backup limit of 0 are never backed up by any policy; that limit is treated as an administrator's decision about the server.
-
Space on the backup storage. Every backup takes disk space where Pelican stores backups. A rough estimate: number of servers x Keep x the size of a typical backup, per policy. See "Things to watch out for".
-
The panel's timezone. Policy times are in the panel's timezone, which the policies page shows under the At field. Check it is the one you expect.
-
The scheduler (a cron job that runs Pelican's timed tasks every minute). Without it nothing is ever started. The entry for the web user is:
* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1Add it with
sudo crontab -e -u www-data. The examples on this page assume Pelican is in/var/www/pelicanand the web server user iswww-data(Debian/Ubuntu). On another setup, adapt the path and the user (for examplenginxon some systems). -
Pelican Panel 1.0. Pelican 1.0.0-rc.2 itself needs PHP 8.4 or 8.5.
-
The queue worker (Pelican's background worker, usually the systemd service
pelican-queue) if you install from the admin area, because installs started there run in the background. Check it withsystemctl status pelican-queue. -
Not the legacy all-in-one "Essentials" plugin (plugin id
essentials) on the same panel. The all-in-one never made backups, so there is nothing to take over, but it must not run beside anyessentials-*module. See "Things to watch out for". -
Essentials Core is optional. With Core installed this module appears in Core's module list on the Essentials page, with its switches in the Parts window and its health notes. Without Core it works on its own.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Backups and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use stable on a live panel.
Then install it one of these ways. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key. You make that key on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_. Then press Install on the plugin's page on the website. -
With the Essentials Auto Updater. If that plugin is installed, its Plugin updates page offers Essentials modules that are not installed yet.
-
From the command line (advanced).
cd /var/www/pelican sudo unzip essentials-backups-x.y.z.zip -d plugins/ sudo chown -R www-data:www-data plugins/essentials-backups sudo -u www-data php artisan p:plugin:install essentials-backups sudo -u www-data php artisan p:plugin:listThe folder must be exactly
plugins/essentials-backups. The list must show the plugin as enabled. Unzipping over an existing plugin folder resets it to "not installed" (its status is kept in its ownplugin.json), so always run the install command again after unzipping.
The install runs one migration, which creates the table essentials_backup_runs (the run log). Automatic backups and Failure notifications are switched on straight away, but nothing is backed up until you add and enable a policy.
After every install:
- The plugin clears Pelican's route and view caches and asks the queue worker to restart. If a new page answers 404 or an old version still shows, reload PHP-FPM (
sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue). - Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root cause errors and failed updates later.
First-time setup
- Give your staff roles the permissions: Admin -> Roles, open a role, section Essentials Backups. Tick
viewfor people who may look,updatefor people who may change the policies and press Run now. Root Admins have both already. - Open the Admin area, sidebar group Essentials Backups, page Backup policies.
- In the section General:
- Automatic backups: on by default. Off starts nothing new; backups already running still finish and are logged.
- Failure notifications: on by default. A notification in the panel when backups could not be made, at most once an hour.
- Backups started per minute: 2 by default (1 to 20). Due servers are started a few at a time so the nodes do not write every archive at once.
- Skip suspended servers: on by default. A suspended server keeps the backups it has and gets no new ones until it is unsuspended.
- In the section Policies, press Add policy and fill in:
- Name: also the start of each backup's name (followed by the date and time), so a server's owner can see where a backup came from.
- Enabled.
- Servers: All servers, Servers of these eggs, Servers on these nodes or These servers, then pick the eggs, nodes or servers. A server in more than one policy is backed up by each of them.
- How often: Every 6 hours, Every 12 hours, Daily or Weekly (then also a Day).
- At: the time of day, in the panel's timezone. Every 6 or 12 hours counts from this time, so 03:00 every 6 hours is 03:00, 09:00, 15:00 and 21:00.
- Keep: how many of this policy's own backups each server keeps (1 to 50, 3 by default). Older ones are removed once a new one has finished.
- When a server is at its backup limit: Replace this policy's oldest backup, otherwise skip the server (the default) or Replace the server's oldest unlocked backup, as Pelican's own schedules do. Read "Things to watch out for" before choosing the second.
- Files to leave out: one path per line, in the same form as on a server's own backup page.
- Press Save at the bottom of the page.
- A new policy waits for its first due moment: saving a daily 03:00 policy at noon starts nothing until three the next morning. To start straight away, open Automatic backups, press Run now, choose the policy and confirm. Its servers are then started a few a minute (the Backups started per minute number), whether or not they are due.
- Watch the first run on Automatic backups (see "Things to keep an eye on"), and open one of the backups on its server's Backups page to check it.
The page takes up to 25 policies.
Things to watch out for
- Backups take space, and Keep decides how much. Each server keeps up to Keep backups per policy, a server in two policies keeps both policies' backups, and backups made by hand or by the server's own schedules come on top. Check the free space on your backup storage before you raise Keep or add a policy, and keep checking it. A full disk is also where backups start failing.
- Servers with a backup limit of 0 are never backed up. They are left out quietly rather than logged as skipped. The policy cards on Automatic backups show them as Without backup slots, and with Essentials Core the Essentials page counts them. Raise their limit to include them.
- The backup limit also limits the policy. A server whose backups have reached its limit is handled by the policy's When a server is at its backup limit choice:
- Replace this policy's oldest backup, otherwise skip the server: removes the policy's own oldest backup and starts a new one. If none of the backups on the server belong to this policy (for example they were all made by hand), the server is skipped with "The server is at its backup limit and none of its backups belong to this policy."
- Replace the server's oldest unlocked backup, as Pelican's own schedules do: Pelican removes the oldest unlocked backup on the server, whoever made it, including backups made by hand or by another policy.
- In both cases the old backup is removed before the new one has finished. If the new backup then fails, the server has one backup fewer than before.
- Locked backups are never removed by this module. Somebody who wants to keep a particular backup can lock it on the server's Backups page. Keep in mind that a locked backup still counts against the server's limit.
- Only the policy's own backups are cleaned up. Keep removes only finished, unlocked backups that the same policy made, and only after a new backup of that server has succeeded. Lowering Keep therefore takes effect after the next successful backup of each server.
- Removing a policy leaves its backups behind. They stay on the servers as ordinary backups, are no longer cleaned up by any policy and still count against each server's backup limit. Delete them on each server's Backups page if you do not need them. Renaming a policy or changing which servers it covers keeps its backups as its own.
- Changing a policy's schedule restarts its count. Changing How often, At or the Day of a policy counts its due moments from the moment you save, as with a new policy.
- Run now only works for an enabled policy while Automatic backups is on. The button only offers enabled policies, and it is hidden while Automatic backups is off.
- Busy servers wait. A server whose previous backup is still running gets no new one until it finishes. Servers that are installing, restoring, being transferred or on a node in maintenance are tried again on a later minute. A server that was backed up a moment ago can be held back by Pelican's backup throttle; it is tried again the next minute.
- Two pages called Backups. Essentials Monitoring has its own read-only Backups overview at
/admin/essentials-backups. This plugin's pages are at/admin/essentials-automatic-backups(since 0.0.2; 0.0.1 used the same address as Monitoring, so only one of the two pages could be opened). Update to 0.0.2 or later if you run both. - This is not a backup of the panel itself. The policies back up server files through Pelican. The panel's database and its
storagefolder (including this module's settings instorage/app/private/essentials) still need backups of their own. - The legacy all-in-one plugin. "Essentials" (plugin id
essentials) is the older plugin that contains what the modules now do separately. Never run it on the same panel as anyessentials-*module: installing a module switches the all-in-one off, installing the all-in-one on a panel with modules can switch modules off, and uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys). Pick one: the all-in-one, or the modules.
Things to keep an eye on
- The Automatic backups page. A card per policy shows what it covers (Covers), how many of those servers have no backup slots (Without backup slots), when it is due (Next) and its Last 24 hours (succeeded, running, failed, skipped). Below is the log of every backup the policies started or skipped, with Started, Server, Policy, Status (Running, Succeeded, Failed, Skipped), Finished and Details. Backups of this server on a row opens Pelican's backups page for that server, where restoring and downloading happen.
- The scheduler. If the scheduler has not run for five minutes, the page says "The panel's scheduler has not run for ... minutes, so no backups are started. Check the cron entry that runs schedule:run."
- Failure notifications. When backups fail, Root Admins and everybody whose role has
updatein Essentials Backups get a notification in the panel's notification bell, at most once an hour, saying how many failed and which was the latest. A node that is down fails every server on it, so one notification can stand for many failures; the log has the details. - Health notes. With Essentials Core, the module's row on the Essentials page can say: "Automatic backups are switched on, but no policy is enabled.", that the scheduler has not run, how many servers in a policy have a backup limit of 0, and how many automatic backups failed in the last 24 hours.
- Space on the backup storage, as above.
- The run log. It grows by one row per server per due moment. Rows older than 90 days are removed once their backup no longer exists; rows whose backup still exists are kept, because they are how the module knows that backup is its own.
- Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Look for lines starting with "Essentials Backups: could not start a backup of server" or "Essentials Backups: could not remove backup". Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB.
Updating
Download the new version and import it the same way you installed it (Pelican shows Update on the plugin when an update is known), or let the Essentials Auto Updater do it. The module switches itself back on after an update through the admin area. Your policies and the run log are kept. Make a database backup before updating, since the run log lives in a table.
Removing it
Uninstall it under Admin -> Plugins, or from the command line:
cd /var/www/pelican
sudo -u www-data php artisan p:plugin:uninstall essentials-backups --delete
--delete also removes the plugin's files. Uninstalling stops everything at once: no new backups are started and nothing is cleaned up any more. Backups the policies made stay on the servers as ordinary backups, still counting against each server's backup limit; delete them on each server's Backups page if you do not want them.
The run log table essentials_backup_runs is kept on purpose, so that a reinstall still knows which backups are its own. If you drop it and reinstall later, the module no longer recognises its old backups and never removes them. To remove it for good, make a database backup and run this in your database client:
DROP TABLE essentials_backup_runs;
The settings stay behind in storage/app/private/essentials/backups/ (settings.json, which holds the policies, and a small file that remembers the sidebar order). Delete that folder by hand if you do not plan to reinstall:
sudo rm -r /var/www/pelican/storage/app/private/essentials/backups
Troubleshooting
| Problem | What to do |
|---|---|
| Nothing happens after saving a policy | A policy waits for its next due moment (shown as Next on its card). Use Run now to start at once. Also check that Automatic backups and the policy's Enabled are on, and that the scheduler runs. |
| Run now is missing, or a policy is not in its list | Run now only shows while Automatic backups is on, and only lists policies that are Enabled. Servers with a backup limit of 0 are never started. |
| A card shows servers Without backup slots | Those servers have a backup limit of 0. Raise their limit in the admin area. |
| Skipped: "The server is at its backup limit and none of its backups belong to this policy." | Raise the server's backup limit, delete or unlock older backups on its Backups page, or choose Replace the server's oldest unlocked backup for the policy. |
| Failed: "The node reported that the backup failed." | Try a manual backup on that server. Check the free space on the backup storage and the Wings log on the node. |
| Failed: "The backup could not be started: ..." | The reason follows the colon, and the full message is in the log. A manual backup on the same server usually fails the same way. |
| Failed: "The backup was removed before it finished." | Somebody deleted the backup while it was running. |
| A row stays Running | The node has not finished that backup yet. Check the server's Backups page. After 24 hours the row is marked Failed with a notification, because that server is left out of every policy until the backup ends; check the node's Wings log. |
| Old backups are not removed | Only finished, unlocked backups of the same policy are removed, after the next successful backup. Backups of a removed policy, manual backups and locked backups are never removed. |
| "The panel's scheduler has not run for ... minutes" | Check the cron entry for schedule:run (sudo crontab -l -u www-data). |
| No failure notifications | Check Failure notifications on the policies page, and that the person is a Root Admin or has update in Essentials Backups. They are sent at most once an hour. |
| The Automatic backups entry opens Essentials Monitoring's Backups page | You are on 0.0.1, which used Monitoring's address. Update to 0.0.2 or later. |
| Saving shows "Could not save the settings" | The panel cannot write to its storage folder. Make sure storage/app belongs to the web user (sudo chown -R www-data:www-data /var/www/pelican/storage). The reason is in the log. |
| A new page answers 404 after installing or updating | Reload PHP-FPM (sudo systemctl reload php8.4-fpm) and restart the queue worker. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.