Skip to content
Essentials
The plugins Docs Sign in

Essentials Security

Open Essentials Security Last changed November 9, 2026

Essentials Security adds three things to a Pelican panel: two-factor authentication required for the roles you choose, a notice when an account signs in from a device it has not used recently, and a page that lists failed sign-in attempts. It is meant for panel owners who want staff accounts protected by a second factor without forcing it on every customer. Everything it shows is read from the activity log Pelican already keeps, so it adds no database tables.

At a glance

Plugin ID essentials-security
Current version 0.0.3
Pelican Panel 1.0 (tested on 1.0.0-rc.2)
Needs The queue worker, for the device notices in the panel's notification bell. The panel's mailer only if you switch on device notices by email. No scheduler entry and no frontend build of its own.
Works with (optional) Essentials Core, Essentials Mobile (device notices reach the owner's phone)
Adds Admin area, sidebar group Essentials Security: page Security (the settings, /admin/essentials-security) and page Failed sign-ins (/admin/essentials-security/sign-ins). A redirect to the profile's 2FA tab for people in the chosen roles who have no second factor.
Permissions Role editor section Essentials Security: View (open both pages without changing anything) and Update (change the settings)

Before you install

  • A second administrator account you can sign in with. You need it to test the two-factor rule before it applies to your own role (see "Things to watch out for").
  • If you want device notices by email as well: the panel's mailer set up under Admin -> Settings -> Mail. Send Pelican's own test mail from that page first.
  • If people should set up two-factor authentication with codes by email, the mailer must work for that too. An authenticator app works without it.
  • 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). Installs started from the admin area run there, and so do the notices in the notification bell. Check it with systemctl status pelican-queue.
  • Not the legacy all-in-one "Essentials" plugin (plugin id essentials) on the same panel. The all-in-one never handled sign-ins, so there is nothing to take over from it, but it must not run beside any essentials-* 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 Security 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.

  1. 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.)

  2. 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.

  3. With the Essentials Auto Updater. If that plugin is installed, its Plugin updates page offers Essentials modules that are not installed yet.

  4. From the command line (advanced). The examples assume Pelican is in /var/www/pelican and the web server user is www-data (Debian/Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems).

    cd /var/www/pelican
    sudo unzip essentials-security-x.y.z.zip -d plugins/
    sudo chown -R www-data:www-data plugins/essentials-security
    sudo -u www-data php artisan p:plugin:install essentials-security
    sudo -u www-data php artisan p:plugin:list
    

    The folder must be exactly plugins/essentials-security. 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 own plugin.json), so always run the install command again after unzipping.

This module runs no migrations and creates no tables. After installing, all three parts are switched on, but the two-factor rule enforces nothing until you choose at least one role.

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

  1. Give your staff roles the permissions: Admin -> Roles, open a role, section Essentials Security. Tick View for people who may look, Update for people who may change the settings. Root Admins have both already.
  2. Open the Admin area, sidebar group Essentials Security, page Security.
  3. In the section Two-factor authentication by role:
    1. Leave Require two-factor authentication for the roles below switched on.
    2. Under Roles, choose the roles that must use two-factor authentication. Start with a test role, not your own (see the test below).
    3. Decide on A passkey counts as two-factor authentication. It is on by default, but a passkey only counts on a panel where signing in with a password is switched off (AUTH_DISABLE_PASSWORD_LOGIN=true in .env), because while the password form is there the password alone still opens the account. Switched off, only an authenticator app or codes by email count, as in Pelican's own rule.
    4. The line under it says how many people in the chosen roles have no two-factor authentication yet.
  4. In the section New device notices: Tell people when their account signs in from a new device is on by default. Switch on Also by email only if the panel's mailer works.
  5. In the section Failed sign-ins: Show the overview of failed sign-ins is on by default.
  6. Press Save at the bottom of the page. The page reloads, because the switches decide which pages exist.

Test the two-factor rule before you rely on it:

  1. Make a test role under Admin -> Roles, and give it to a second account that has no two-factor authentication.
  2. On the Security page, choose only that test role under Roles and save.
  3. Sign in as the test account in a private browser window. Every page should send you to the 2FA tab of the profile, with the warning "Two-factor authentication is required". Signing out and the profile itself still work.
  4. Set up an authenticator app there. After that the panel should work normally for the test account.
  5. Only then add your real staff roles. Add your own role last, and only after you have set up two-factor authentication on your own account.

What people in a chosen role see: on every page of every panel (admin, client and server pages) they are sent to the 2FA tab of their profile, the same place Pelican sends people for its own rule, until they have a second factor. What counts is what Pelican counts (an authenticator app or codes by email) and, while the passkey switch is on and password sign-in is off, a passkey on their account. From 0.0.3 on the rule also covers Livewire's own requests and the client API: an account in a chosen role without a second factor gets 403 TwoFactorRequired from /api/client, with its session or with an API key. SFTP goes through Wings, not the panel, so it is outside this rule.

Things to watch out for

  • Do not enforce the rule on your own role first. If you are in a chosen role and have no second factor, every page sends you to your profile until you set one up, and you cannot reach the Security page to undo it before then. Always test with a second admin account first, as described above.
  • Root Admin is a role like the others. The Roles list contains every role on the panel, including Root Admin. Choosing it applies the rule to every Root Admin.
  • If somebody is locked out, in this order:
    1. Somebody who can still sign in is only being sent to their profile. They can set up two-factor authentication there and carry on.

    2. Another administrator who can reach the panel can open Security, remove the role from Roles or switch off Require two-factor authentication for the roles below, and save. With Essentials Core, the same switch is in the Parts window on the Essentials page (Two-factor authentication by role).

    3. If nobody can reach the page, switch the whole plugin off from the command line:

      cd /var/www/pelican
      sudo -u www-data php artisan p:plugin:disable essentials-security
      

      This also stops the device notices and removes the Failed sign-ins page until you enable the plugin again under Admin -> Plugins. If pages still redirect afterwards, reload PHP-FPM.

  • This plugin does not check codes. It only decides who must have a second factor and sends them to set one up. Switching it off does not remove a second factor somebody already has, and it does not help somebody who lost their authenticator.
  • Pelican's own rule still applies. Pelican's 2FA Requirement setting (Admin -> Settings) can require two-factor authentication of administrators or of everybody. This module adds the chosen roles on top of that. If Pelican already requires it of everybody, the role rule adds nothing.
  • A check that fails lets people in. If the panel cannot work out whether somebody needs or has a second factor (for example a database error), that person is let through rather than locked out, and the error is written to the log.
  • A device is a browser that signed in before, not an address. Each sign-in leaves a random token in a cookie, and the panel keeps a hash of the last twenty per account (from 0.0.3 on). A browser without one of them is a new device, even with the same browser and system; clearing cookies therefore counts as a new device once. A notice names the device like "Firefox on Windows". A phone changing address does not count as a new device. The first sign-in of an account sends no notice, and neither does a remembered session being picked up again.
  • The 90-day window depends on Pelican's activity log. A device counts as new when the account has not signed in with it in the last 90 days, read from Pelican's activity log. If Pelican prunes that log sooner (Admin -> Settings -> Misc -> Activity Logs -> Prune Age), the window is shorter and people get more notices. The Failed sign-ins page is limited the same way.
  • Email is optional and can fail quietly for the user. When Also by email is on and the mailer refuses, the notice in the panel is still sent and the mail error is written to the log.
  • 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 any essentials-* 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

  • Health notes. With Essentials Core, the module's row on the Essentials page says "Two-factor authentication by role is on, but no role is chosen." (shown from the first install until you choose a role or switch that part off) and how many people in roles that need two-factor authentication have not set it up.
  • The Failed sign-ins page. It lists every failed sign-in of the last 30 days (When, Address, Tried, Device) under three numbers for the last 24 hours: Failed in the last 24 hours, From different addresses and Most attempts from one address. A handful a day is people mistyping. Hundreds from one address is somebody guessing passwords; block that address in your firewall and check that the account it tried has a strong password and two-factor authentication.
  • The queue worker. Device notices reach the notification bell through the queue. If it stops, notices are not delivered. Recommended: Restart=always on the pelican-queue service, and a drop-in with StartLimitIntervalSec=0 under [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-queue brings it back.
  • Logs. Errors go to storage/logs/laravel-YYYY-MM-DD.log (or laravel.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. Your settings are kept. This module keeps no tables, but a database backup before any plugin update is still good practice.

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-security --delete

--delete also removes the plugin's files. Uninstalling stops everything at once: nobody is redirected any more, no new device notices are sent, and the Failed sign-ins page disappears. Nothing is deleted from the database, because the module has no tables. The failed sign-ins and sign-in history stay in Pelican's own activity log, and notices already sent stay in people's notification lists.

The settings stay behind in storage/app/private/essentials/security/ (settings.json 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/security

Troubleshooting

Problem What to do
Everybody in a role is sent to the profile, including people who say they have two-factor authentication Check what they set up. Only an authenticator app, codes by email or (while the passkey switch is on and password sign-in is off) a passkey count.
Nobody is sent to set up two-factor authentication Check that Require two-factor authentication for the roles below is on, that at least one role is chosen and saved, and that the people are actually in that role.
You locked yourself out of the admin area Ask another administrator to remove your role on the Security page, or run sudo -u www-data php artisan p:plugin:disable essentials-security in /var/www/pelican.
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.
No device notices arrive Check that Tell people when their account signs in from a new device is on and that the queue worker runs. The first sign-in of an account and sign-ins from a browser that signed in before send nothing.
Device notices by email do not arrive Check Also by email and the mailer under Admin -> Settings -> Mail. Mail errors are in the log.
The Failed sign-ins page is missing Switch on Show the overview of failed sign-ins and save, and check that your role has View or Update in Essentials Security.
Every failed sign-in shows the same address The panel sees your proxy's address instead of the visitor's. Set Trusted Proxies in Admin -> Settings (Pelican has a button for Cloudflare).
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.

Put Essentials on your home screen

Your browser can install it now. It opens in a window of its own, without the address bar, like any other app.