Essentials Server Tools
Essentials Server Tools collects the tools that work on servers: giving everyone in a role access to the same servers (Servers by Role), starring servers and pages and jumping to them (favourites and the Go to switcher), making copies of a server, a floating console button on every page inside a server, and a button that starts, restarts, stops or kills many servers at once. It is meant for panel owners and staff who manage more than a handful of servers. It replaces the older Essentials Console and Essentials Duplicate plugins and takes over their settings and permissions.
At a glance
| Plugin ID | essentials-server-tools |
| Current version | 1.2.3 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The scheduler, for Servers by Role (it runs every minute). The queue worker, for power actions and for taking SFTP access away when Servers by Role removes somebody. The panel's frontend build (Node.js and Yarn), because the plugin ships stylesheets and scripts. |
| Works with (optional) | Essentials Core |
| Adds | Admin area, sidebar group Essentials Server Tools: page Server access (Servers by Role, /admin/essentials-access), page Duplicate server (/admin/essentials-duplicate), page Console (the console button's settings, /admin/essentials-console) and page Favourites. A Favourites page in the client area too, and Favourites in the user menu. A Power actions button on Pelican's own server list in the admin area. A star on each server card, a Go to button beside the panel's search, and a floating console button on the pages inside a server. |
| Permissions | Role editor section Essentials Server Tools: view, update, access, view-access, duplicate, view-duplicate, console, view-console, power (see "Permissions" below) |
Before you install
- Essentials Console or Essentials Duplicate installed? That is fine. Installing Server Tools switches them off and carries their settings and role permissions across (see "Coming from Essentials Console or Essentials Duplicate" under "Installing").
- Essentials Core 1.0.21 or older installed? Those versions still draw Servers by Role, favourites and the switcher themselves. Server Tools waits until Core stops drawing them, so update Core to a newer version to let Server Tools take them over. The mappings, the favourites and the permissions come across with them.
- A database backup. Servers by Role writes to Pelican's own subuser table, and Duplicate creates servers. A backup before you start using them is cheap insurance.
- The scheduler (a cron job that runs Pelican's timed tasks every minute) for the web user:
* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1, added withsudo crontab -e -u www-data. Without it Servers by Role only updates when somebody presses Save and apply. - The queue worker (Pelican's background worker, usually the systemd service
pelican-queue). Installs started from the admin area run there, and so do power actions and SFTP revocations. Check it withsystemctl status pelican-queue. - Node.js and Yarn on the panel server. Pelican compiles the plugin's stylesheets and scripts into the panel's own frontend build when the plugin is installed. The build must run as the panel's web user.
- Pelican Panel 1.0. Pelican 1.0.0-rc.2 itself needs PHP 8.4 or 8.5.
- Not the legacy all-in-one "Essentials" plugin (plugin id
essentials) on the same panel. 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 Server Tools 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). The examples 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).cd /var/www/pelican sudo unzip essentials-server-tools-x.y.z.zip -d plugins/ sudo chown -R www-data:www-data plugins/essentials-server-tools sudo -u www-data php artisan p:plugin:install essentials-server-tools sudo -u www-data php artisan p:plugin:listThe folder must be exactly
plugins/essentials-server-tools. 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.
This module runs no migrations and creates no tables. On its first install it also:
- switches off Essentials Duplicate and Essentials Console if they are enabled (once per panel; the log says "Essentials Server Tools switched off essentials-console, which it replaces"),
- gathers the settings of Core, Duplicate and Console into a settings file of its own,
- gives each role the Server Tools permissions that match what it held under those plugins.
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). - If the star, the Go to button or the console button look unstyled or are missing, rebuild the frontend:
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core, the Panel health section on the Essentials page reports missing built assets. - Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root (cache files,public/build) cause errors and failed updates later.
Coming from Essentials Console or Essentials Duplicate
Installing Server Tools for the first time:
- switches Essentials Console and Essentials Duplicate off, if they are enabled. Their files and settings stay where they are. This happens once per panel: if you switch one of them back on later, Server Tools does not switch it off again, but steps back and leaves that part to the old plugin.
- reads their settings once into its own file: which parts were switched off, and the console button's mode, position and label. Settings the legacy all-in-one kept in
.envare read too where nothing newer said otherwise. Nothing is written back to the old files or to.env. - gives each role the matching Server Tools permission, once:
viewunder Console becomesview-console,updatebecomesconsole,consoleandview-consolestay the same; the same for Duplicate withview-duplicateandduplicate. From Essentials Core it takesaccessandview-access. The old grants are left alone.
The pages keep their old addresses (/admin/essentials-console, /admin/essentials-duplicate, /admin/essentials-access), so bookmarks still work. Afterwards, remove the old plugins under Admin -> Plugins.
First-time setup
- Give your staff roles the permissions listed under "Permissions" below: Admin -> Roles, section Essentials Server Tools.
- Open the Admin area, sidebar group Essentials Server Tools. Check which parts you want under Parts (a button at the top of the Server access page, needs
update): Duplicate server, Starred servers, Go to menu and Power actions. Switched off, a part is gone for everybody, its page or buttons with it. Save the window; the page reloads. With Essentials Core, the Parts window on the Essentials page has all six switches, including Server access by role and Console button. - Set up the parts you use, as described below.
Permissions
All in the role editor section Essentials Server Tools (Admin -> Roles, open a role). Root Admins have everything already.
| Permission | Allows |
|---|---|
view |
Opening every page of the plugin without changing anything |
update |
Changing everything, using Power actions, and the Parts switches |
access / view-access |
Changing Servers by Role, or only seeing that page. Adding a server to a role, or giving a role more on it, also needs Pelican's own permission to update that server (its node within the admin's role), unless they are a Root Admin |
duplicate / view-duplicate |
Duplicating a server, or only seeing the page. Duplicating also needs Pelican's own permission to create servers |
console / view-console |
Changing the console button's settings, or only seeing them |
power |
The Power actions button on the server list |
Power actions have no read-only form, so there is no view-power box (1.2.0 showed one that did nothing).
Favourites and the Go to switcher have no permission: each person only sees and stars what Pelican already lets them open. The console button inside a server follows Pelican's own subuser permissions (start, restart, stop, console, and connect to websocket for the console window), checked when it is drawn and again when it is pressed.
Servers by Role
Pelican has no link between roles and servers. This page gives everybody holding a role the same servers by making them a subuser of each server (the same rows you would add by hand on a server's Users page), and keeps that true.
- Open Server access (the page title is Servers by role). Read How this works at the top once.
- Make sure Server access by role is switched on.
- Under The mappings, press Add a role and fill in:
- Role: everyone holding it, including anyone given it later.
- Servers: the servers they get. Removing one later takes that access away again.
- What they may do: Pelican's subuser permissions. The default is the console, the power buttons, files, backups, the activity log and reading the startup settings, and nothing that edits the server, its users, its databases or its allocations. Connect to websocket is always added.
- Press Save and apply. The mapping is applied at once, and the notice says how many were granted and taken back.
- Sign in as somebody in that role (or ask them) and check that the servers appear in their list.
After that, a run every minute on the scheduler picks up people given the role later and servers added to a mapping. Somebody who loses the role loses its servers on their next request to the panel, and a person's own access is brought up to date when they sign in; the minute run also catches people who are not using the panel. The line under How this works says what the last run did.
What it does and does not do:
- Server owners and Root Admins are skipped; they already have more than a mapping could give them.
- Somebody in two roles gets everything both grant.
- It only ever changes or removes rows it created itself. A subuser you added by hand is never touched, even when a mapping wants the same person on the same server, so that person keeps exactly the permissions you gave them.
- Nobody is emailed when a role grants them a server. The server simply appears in their list.
- Taking access away also revokes the person's SFTP access to that server. That runs on the queue worker.
- Limits: 50 mappings, 200 servers in one mapping, and 20,000 grants in one run. A run above that limit writes nothing and says "Too much at once". The Servers picker offers the first 1000 servers by name.
Favourites and the switcher
Nothing to set up. Once the parts are on:
- Every server card in the server list has a star. In the grid layout starred servers come first; in the list layout they are only marked. A Favourites tab on the server list shows only the starred servers on the current page.
- The Go to button beside the panel's search opens a box that searches all servers you can open (up to 25 results at a time), shows your favourites, and has Star this page for the page you are on and See all for the Favourites page.
- The Favourites page (sidebar and user menu) lists starred servers and pages; the cross removes one.
Each person's stars are kept on the panel, so they follow them to every device. Up to 100 servers and 100 pages per person.
Duplicate
- Open Duplicate server (title Duplicate a server).
- Under Copy from, pick the server. The copies go on the same node, on free allocations.
- Name the copy is filled in for you. More than one copy is numbered: "Bot 1", "Bot 2" and so on.
- How many offers as many as there are free allocations on that node, up to 10.
- Press Save at the bottom. It creates the servers.
Copied: the owner, the egg, the Docker image, the startup command, the description, the resource limits, the database, allocation and backup limits, and every variable. Not copied: files, databases, backups and schedules. The copies are created through Pelican's own server creation and are not started. Each copy is made on its own, so if one fails the ones before it stay, and the notice lists what failed.
Console button
- Open Console in the sidebar group.
- Console button switches the button on or off for the whole panel.
- Console button on every server page: Console and power buttons or Console only.
- Where it floats: Top, Right or Bottom. The button shows: Icon and name or Icon only.
- Press Save.
Inside a server, the button appears on every page except the console page itself. It opens Pelican's own console in a window over the page, with the server's state and Start, Restart, Stop and Kill in the header. New window opens the console in a browser window of its own. Kill asks for confirmation first. Each button only shows for people who have the matching Pelican permission on that server, and the power buttons are not shown while a server is suspended, installing or being transferred.
Power actions for many servers
- Go to Admin -> Servers (Pelican's own server list) and press Power actions at the top. You need
powerorupdate. - Choose the Action: Start, Restart, Stop or Kill.
- Choose Servers: All servers, Servers on these nodes, Servers of these eggs or These servers, and pick them.
- Read This reaches: it lists the servers that will get the action (the first 30 by name, then how many more). Only servers you may control are listed: those where you have the power permission yourself, or that your admin role may change (Pelican limits that to the nodes your role may reach). The pickers show every node, egg and server, but the list is what counts.
- Press Send. There is no second warning, also not for Kill.
The action runs in the background on the queue worker. When it is done you get a notification in the panel's bell with the result and a line for each server that did not take it (up to 20 lines). If the job is cut off part way (a very long batch against slow nodes), you get a notification that it stopped before it reached every server; the reason is in the panel's log. Servers that are suspended, installing, restoring a backup, being transferred or on a node in maintenance are skipped with that reason. Permissions are checked again for each server when the job runs. A power action is never retried, so a restart is never sent twice.
Things to watch out for
- Uninstalling does not take access back. Every subuser Servers by Role created stays after the plugin is removed, and nothing removes it any more. Switch Servers by Role off and press Take it all back on the Server access page before you uninstall (see "Removing it").
- Switching Servers by Role off does not take access back either. It only stops the updates. The switch then shows how many people still have servers it granted. Take it all back removes every row the page created, on every server, together with the SFTP access, and leaves rows you added by hand alone. The mappings stay, so the next save or run grants them again unless you empty the list first.
- Do not delete
storage/app/private/essentials/server-tools/access-managed.json. It is the record of which subusers Servers by Role created. Without it the plugin can no longer take those rows back, and they stay for good. - When access is taken away. When somebody loses a role, their servers go on their next request to the panel (from 1.2.1 on), at the next scheduler run (within a minute) or when somebody presses Save and apply, whichever comes first. Somebody who does not use the panel but still has SFTP access only loses it through the scheduler, so keep the scheduler running.
- Mappings write to Pelican's own table. Check What they may do carefully. Giving a role permissions for users, databases or allocations gives everyone in that role those rights on every mapped server.
- Duplicate and power actions work on all servers. People with
duplicatecan copy any server on the panel, and the copies use free allocations on its node. Giveduplicate,powerandupdateonly to staff you trust with that. - Favourites are a file per person under
storage/app/private/legend-theme/favourites. Anyone with access to the machine can read which servers and pages somebody starred. - The star relies on Pelican's server list. It is placed into Pelican's own cards by script. If it cannot find them (for example after a Pelican update changed the list), the list simply shows without stars.
- 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. Server Tools refuses to start next to a legacy release older than 3.222.0-dev.
Things to keep an eye on
- Health notes. With Essentials Core, the module's row on the Essentials page says "Servers by Role has not run for over ten minutes. Check that the panel's scheduler runs." when the scheduler has stopped while mappings exist.
- The last run on the Server access page: "Last run ... seconds ago: ... added, ... removed, ... in place." A message starting with "Too much at once" means nothing was written; narrow a mapping.
- The scheduler. Check that the cron entry exists:
sudo crontab -l -u www-data. - The queue worker. Power actions and SFTP revocations wait for it. Recommended:
Restart=alwayson thepelican-queueservice, and a drop-in withStartLimitIntervalSec=0under[Unit](sudo systemctl edit pelican-queue) so systemd never gives up restarting it after repeated crashes. If it has given up,sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queuebrings it back. - Power action results in the notification bell, for servers that did not take the action.
- Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). 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. Settings, mappings and favourites are kept. Updates do not switch Essentials Console or Essentials Duplicate off again. A database backup before any plugin update is good practice.
Removing it
-
If you used Servers by Role: open Server access, switch Server access by role off and press Save and apply, so the next run cannot grant anything again. Then press Take it all back and confirm. The notice says how many rows were removed.
-
Uninstall it under Admin -> Plugins, or from the command line:
cd /var/www/pelican sudo -u www-data php artisan p:plugin:uninstall essentials-server-tools --delete--deletealso removes the plugin's files.
The plugin owns no table, so nothing is deleted from the database. Subusers it created and servers it duplicated stay where they are. Files left behind:
storage/app/private/essentials/server-tools/: the settings, the mappings (role-servers.json), the record of created subusers (access-managed.json) and a few small marker files.storage/app/private/legend-theme/favourites/: one file per person with their stars. The legacy plugin and Essentials Core 1.0.21 or older used the same folder.
Delete them by hand if you do not plan to reinstall:
sudo rm -r /var/www/pelican/storage/app/private/essentials/server-tools
sudo rm -r /var/www/pelican/storage/app/private/legend-theme/favourites
Troubleshooting
| Problem | What to do |
|---|---|
| The plugin will not start and says "Update legacy Essentials to a version supporting standalone Server Tools, or disable legacy Essentials" | The legacy all-in-one plugin is running. Remove it or the modules; do not run both. |
| Server access, Favourites, the star or Go to are missing | Essentials Core 1.0.21 or older is still drawing them. Update Core. Otherwise check the part's switch under Parts and your role's permissions. |
| The Console page or the console button is missing | Essentials Console is still enabled (perhaps switched back on); Server Tools leaves the button to it. Disable or uninstall Essentials Console. Also check Console button on the Console page. |
| The Duplicate server page is missing | Essentials Duplicate is still enabled, or Duplicate server is off under Parts, or your role has none of view, view-duplicate, duplicate, update. |
| A role's members do not get their servers | Press Save and apply and read the notice. Check the scheduler. Owners and Root Admins are skipped on purpose. A "Too much at once" message means the run was above the limit. |
| Somebody keeps a server after losing the role | It goes on their next request to the panel, or within a minute through the scheduler; check that the scheduler runs. If the subuser was added by hand on the server's Users page, Servers by Role never removes it; remove it there. |
| Saving shows "Could not save" with "The list could not be written to storage" | Make sure storage belongs to the web user: sudo chown -R www-data:www-data /var/www/pelican/storage. |
| Power actions is not on the server list | You need power or update, and Power actions must be on under Parts. |
| No result notification after Send | The queue worker is not running. Start it; the action is carried out once it runs. |
| Some servers were skipped | The notification gives the reason for each: you may not control it, or it is suspended, installing, restoring, being transferred or on a node in maintenance. |
| Duplicate says "There is no free address left on ..." | Add allocations to that node under Admin -> Nodes. |
| Starred servers do not move to the top | Switch the server list to the grid layout; in the list layout stars only mark. |
| "Your starred servers could not be saved" | The panel cannot write to its storage folder. Fix the ownership as above. |
| Star, Go to or console button unstyled or missing after an install | Run cd /var/www/pelican && sudo -u www-data yarn build. |
| 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.