Skip to main content

cPanel plugin

The stillorigin cPanel plugin adds a Manage protection page to cPanel. Your cPanel users see their sites that have stillorigin Website protection on, and each site has a Manage protection button that signs them in to that site's owner area. Your users don't need a stillorigin account.

The plugin is free and open source (MIT licence).

What the plugin does​

  • It adds Manage protection to the Security section of cPanel, for the hosting plans you choose.
  • The page lists the user's own domains that have Website protection on in your stillorigin account.
  • When the user clicks Manage protection next to a site, the plugin creates a one-time sign-in link and opens the owner area for that one site in a new tab.
  • In the owner area the user sees Overview, Traffic, Blocks, Protection, Countries and Settings, and can change only the settings you allow on the Settings tab. See What domain owners see.

The Manage protection page never changes anything in stillorigin by itself. It doesn't add domains or turn Website protection on or off. It only shows the domains that already have Website protection on, and opens their owner area. The WHM plugin, for you as the host, can add domains.

What your cPanel users see​

The page is headed Manage protection, with the note Open protection settings for one of your sites. Each button opens in a new tab. Below it is a list of their sites, each with a Manage protection button.

  • Each sign-in link is created only when the user clicks the button. It works once and expires after 5 minutes. They can click the button again at any time to get a new one.
  • If none of their domains has Website protection on, they see None of your domains have protection you can manage here yet.
  • The owner area is stillorigin-branded, but stillorigin doesn't offer support to domain owners. Your users get help from you, through the Get help from your host link you set on Owner access. See Support link for owners.
  • cPanel team users (account names that contain @) can't get owner sign-in links from the plugin.

Before you start​

You need:

  • a cPanel & WHM server with the Jupiter theme (the plugin installs into Jupiter only), and root access to it, for example over SSH;
  • the stillorigin origin agent installed on that server and showing Connected on the origin's page in the portal. If it isn't installed yet, follow step 3 of the Setup guide;
  • each site already added to stillorigin with this server as its Origin server, and with Website protection on;
  • owner access set up: what your users can change, and your support link. Every permission is off by default, so until you allow something, users can only view their site's protection.

Which key does it use?​

The plugin uses the origin agent's own key, which the agent got when you installed it. It doesn't use your account API key, so don't put your API key on the cPanel server.

The agent's key stays readable only by root. The cPanel page runs as the cPanel user and never sees the key: it asks a small module that runs as root, and that module asks the origin agent. Only the domain names and the one-time sign-in links reach the page.

The origin agent's key can only create sign-in links for domains with Website protection on the origin servers that agent serves. It can't open other sites in your account.

1. How the plugin is installed​

On a cPanel server, the origin agent installer installs the plugin for you. There's no separate download, and you don't copy files or run an install script.

When the origin agent updates, it updates the plugin too. If the origin agent is already on the server, the plugin is installed or updated the next time the agent updates (it checks for updates by itself every 6 hours). See Keeping the origin agent up to date. You can also re-run the install command from the origin's page.

You still need to turn the plugin on for your hosting plans, in the next step. It isn't turned on for existing plans automatically.

2. Turn it on for your plans​

The plugin is a cPanel feature, so you choose which hosting plans get it. Installing the plugin doesn't turn the feature on for existing plans.

  1. In WHM, go to Packages › Feature Manager.
  2. Edit the feature list used by a plan that should have the plugin.
  3. Tick Manage protection (its feature name is stillorigin_protection) and save.
  4. Repeat for each feature list that should have it.

Users on plans without the feature don't see Manage protection in cPanel.

3. Test it​

  1. Pick a site on this server that's in stillorigin with Website protection on, and whose Origin server is this server.
  2. In WHM, open cPanel for the account that owns the site, or sign in to that account's cPanel.
  3. In the Security section, click Manage protection.
  4. You should now see the site in the list. Click Manage protection next to it. The owner area for that site opens in a new tab.
Changes are real

Anything you change in the owner area applies to the live site, even when you're only testing.

Each sign-in appears in your audit log as made by the origin agent, for example domain owner via agent 12.

How it decides which domains to show​

A site is listed only when all of these are true:

  • The cPanel account owns it. The plugin takes the account's domains from cPanel itself: its main domain, addon domains, subdomains and parked (alias) domains. It never trusts a domain name sent from the browser.
  • It's in your stillorigin account with Website protection on. Domains with only Network protection have no owner area, so they aren't listed.
  • Its origin server is one this origin agent serves. A site whose Origin server in stillorigin is a different server isn't listed, even if the same name is on this cPanel account.

The name can match with or without www., so www.example.com in cPanel finds example.com in stillorigin, and the other way round.

When the user clicks Manage protection, the origin agent checks all of this again before it asks stillorigin for a link.

Messages and troubleshooting​

These are the messages your cPanel users can see on the Manage protection page.

MessageWhat it means and what to do
None of your domains have protection you can manage here yet.None of the account's domains is in stillorigin with Website protection on and this server as its origin. Check the domain's Origin server and that Website protection is on, on the domain's page in the portal. See How it decides which domains to show.
Too many requests. Wait a minute, then try again.Each cPanel user can create up to 10 sign-in links a minute on this server. Wait a minute and try again.
Protection isn't on for this domain, so there's nothing to manage.Website protection was turned off for the domain after the page was opened. Turn Website protection back on in the portal if it should be on. Reload the page to see the current list.
This domain isn't protected on this server, or isn't on your account.The domain was removed from stillorigin, moved to another origin server, or removed from the cPanel account after the page was opened. Reload the page to see the current list.
Protection settings aren't available right now. Try again later.The plugin couldn't get an answer from the origin agent or from stillorigin. See below.

If Manage protection isn't in cPanel at all:

  • Is the origin agent running and connected? On the origin's page in the portal, the origin agent should show Connected. On the server, systemctl status stillorigin-agent should show it running. See Origin agent status.
  • Has the agent updated? The plugin is installed and updated with the origin agent. Wait for the agent to update, or re-run the install command from the origin's page. As root on the server, you can also run stillorigin-agent install-cpanel-plugin.
  • Does the user's plan have the feature? Turn Manage protection on in Feature Manager, as above.

If users see Protection settings aren't available right now. Try again later., check these on the cPanel server, as root:

  • Is the origin agent running and connected? On the origin's page in the portal, the origin agent should show Connected. On the server, systemctl status stillorigin-agent should show it running. See Origin agent status.
  • Was the origin agent removed, or its install replaced? The plugin needs the agent installed at /opt/stillorigin-agent and connected to your account. If you removed the origin from stillorigin or uninstalled the agent, install it again from Get install command.
  • Can the server reach stillorigin? It needs outgoing HTTPS to control.stillorigin.app.
  • Does the user's plan have the feature? If you turn Manage protection off in Feature Manager while a user has the page open, their next click shows this message.

Updating and removing the plugin​

  • The plugin stays up to date with the origin agent. You don't need to update it by hand.
  • Removing the origin agent also removes the plugin. See Removing the origin agent.
  • To remove only the plugin and leave the origin agent (so your sites stay protected), run stillorigin-agent uninstall-cpanel-plugin as root on the server.

Using WHMCS too?​

The WHMCS module gives your clients the same Manage protection button in the WHMCS client area, and can turn Website protection on and off with their orders. You can use both. Both open the same owner area, with the same permissions.

The IP address cPanel shows​

cPanel's Tools page still shows the server's shared IP address, which customers sometimes copy into their DNS. Show your sentry's IP address in cPanel explains how to add a notice, and optionally show a sentry address in its place. stillorigin doesn't write the notice for you, but with the WHM plugin the origin agent puts your copy back after every cPanel update.

WHM plugin​

Coming with the next release

The WHM plugin arrives with the next origin agent release. Until your origin agent has updated, it isn't in WHM.

The WHM plugin is for you as the host. It helps you move a whole cPanel server onto stillorigin: it lists your protected domains with their DNS, checks that each one points at your sentries and fixes it in one click, and protects many domains at once. It also adds new accounts and domains for you, flags removed ones, and puts the shared IP notice back after cPanel updates.

It's installed, updated and removed with the origin agent, like the cPanel plugin, and uses the origin agent's own key in the same way. The key stays readable only by root and never reaches your browser.

Opening it​

In WHM, go to Plugins › stillorigin. Only root can open it: resellers don't see it.

Open in portal, at the top right, opens this server's origin page in the portal. Click a protected domain's name to open that domain in the portal.

This server's cluster​

The plugin uses this server's cluster: the one you chose when you added this origin server in the portal. It's shown at the top of the page, with the addresses to point DNS at. Bulk protect and new accounts and domains always use this cluster.

If the origin server has no cluster, for example because its cluster was deleted, the plugin asks you to Choose this server's cluster first, and shows nothing else until you do. After that, you change it on the origin's page in the portal (Change in the portal).

Protected domains​

The page opens on Protected domains: every domain on this server with Network protection or Website protection, grouped by cPanel account. Suspended cPanel accounts are skipped, and their domains aren't listed or processed until the account is unsuspended. For each domain you see:

  • Protection: Network protection, Website protection log mode or Website protection blocking. A domain counts as protected when it's in your stillorigin account and either its Origin server is this server, or it's in this server's latest domain list.
  • DNS: whether the website points at your sentries. See DNS Check.

Protected domains point their A (and AAAA) records at the addresses shown under Cluster: the cluster's VIP if it has one, otherwise each sentry's public address.

Unprotected domains, above the list, with how many there are, opens the domains that aren't protected yet, where you protect them in bulk. Protected domains takes you back.

Use Search to find an account or domain on either screen. Accounts are shown 25 to a page.

Protecting domains in bulk​

  1. Open Unprotected domains. Tick the domains to protect, or tick Select all next to an account name to protect all its domains.
  2. Choose the protection:
    • Network protection; or
    • Website protection, starts in log mode. This is offered only while your account has free Website protection licences, and each new Website protection domain uses one. New domains with Website protection start in log mode, so they only record what they would block until you switch them to blocking in the portal.
  3. Click Protect selected. The domains are added to this server's cluster, and move to Protected domains.

Each order is all or nothing: if one domain can't be added, for example because there aren't enough free Website protection licences, nothing is added and the page says why. Domains that are already in stillorigin are skipped. You can protect up to 500 domains at a time. Each domain is added with this server as its Origin server, and shows in your audit log as added from WHM by the origin agent. The page then shows what would follow the website when you point these domains at your sentries, with a one-click fix.

New accounts and domains​

When an account, addon domain, alias or subdomain is created on this server, the plugin adds it to stillorigin for you with Network protection protection. That's the default. Under New accounts and domains you can choose:

  • Add them with Network protection (the default); or
  • Don't add them, if you'd rather add them yourself here or in the portal.

New domains are never given Website protection automatically. Website protection needs a Website protection licence, so you turn it on yourself: here, in the portal, through the API or with the WHMCS module.

New domains go to this server's cluster. If the origin server has no cluster, nothing is added until you choose one, and Recent automatic changes says so.

A domain is usually added within a minute of being created. If stillorigin can't be reached, the agent tries again for up to a day. What was added, and anything that couldn't be, is listed under Recent automatic changes (times in UTC).

Removed accounts and domains​

When a cPanel account is removed, or a domain is removed from an account, the plugin doesn't remove the domain from stillorigin, so the site stays protected. Instead, the domain is flagged:

  • On the Domains page in the portal, it shows as Not found on origin, with a note that the cPanel account (or the domain) was removed from this origin server, and when.
  • In WHM, it's listed under Removed from this server.

If the site has gone, remove the domain in the portal. If it moved to another server, change its Origin server. If the domain comes back on this server, the flag clears by itself.

DNS Check​

To move a site behind your sentries, its website DNS records have to point at them. Click DNS Check above Protected domains to check every protected domain. For each one, it:

  • reads the domain's DNS zone on this server: whether the domain's and www.'s A and AAAA records point at your sentries, and whether mail and cPanel service names still point at this server;
  • looks up which nameservers the domain uses, from its registry, not from the records your server sees. That decides who can change the records: you, or your client with their DNS provider.
You seeWhat it means
Pointing at sentriesThis server's DNS points the website at your sentries, so its visitors are protected.
Not pointing at sentriesThe website doesn't point at your sentries yet, or only some of its records do. Fix DNS points it there. Hover over it to see the nameservers, or why they couldn't be looked up.
Uses other nameserversThe domain's DNS is hosted somewhere else, for example Cloudflare. Fix DNS still updates this server's zone, but the change only counts once your client sets the same records with their DNS provider. The confirm step lists them, and so does Records to set once this server points at your sentries.
Not checked yetDNS Check hasn't checked this domain yet. Click DNS Check.

If mail and cPanel service names follow the website, the DNS status says so when you hover over it, and Fix DNS keeps them on this server. Each row has at most one action on the right: Fix DNS, Point back to this server, or Records to set, which opens the records under the row. Fix DNS shows on every protected domain whose zone is on this server and doesn't point at your sentries yet, whatever its nameservers. Checked, next to the button, says when DNS Check last ran (in this server's time).

Your own nameservers are the ones set in WHM under Server Configuration › Basic WebHost Manager Setup › Nameservers. If your domains are delegated to other nameservers you run, such as a DNS cluster with different names, add them to /etc/stillorigin-agent/agent.json as "ownNameservers": ["ns1.example.net", "ns2.example.net"] and they count as yours too.

Subdomains use their parent domain's nameservers.

Few lookups, so registries don't block your server. The nameservers are looked up only when you click DNS Check or Fix DNS, never when the page loads or in the background. The origin agent asks the registry's own DNS servers first, with one small query per domain, and uses RDAP, the registries' lookup service, only when DNS can't answer. Subdomains share their parent domain's lookup, and each answer is kept for a day, so clicking DNS Check again only re-reads the zones on this server. A lookup that didn't work isn't kept: the next DNS Check tries it again. If this server can't reach DNS servers on the internet (port 53), the agent stops trying DNS for the rest of that check and uses RDAP. On a big server, each click checks 50 domains, oldest first, and says how many are left.

If a registry limits the lookups from your server, the page says Nameserver lookups are paused and until when. The records on this server are still checked, and domains keep their last result (or show Not checked yet) until the pause is over.

Fix DNS​

Coming with the next release

This is coming with the next origin agent release.

When a protected domain shows Not pointing at sentries, the plugin changes the website's DNS records on this server for you, so you don't need the client's Zone Editor. If DNS Check couldn't confirm that the domain uses this server's nameservers, the confirm step says so and lists the records to set with the domain's DNS provider: the change on this server only takes effect once the domain uses it.

  1. Click Fix DNS in the domain's row.
  2. The page asks Point example.com at your sentries? and lists what will change. Nothing has changed yet. Click Fix DNS to go ahead, or Cancel.

For each domain, the plugin:

  • first keeps mail and cPanel services on this server;
  • then points the domain's own A and AAAA records, and those of www., at the addresses shown under Cluster. Each record keeps its TTL. A www. that is a CNAME to the domain is left as it is, because it follows the domain.

Afterwards, DNS Check runs again for that domain.

Nothing else in the zone changes. A domain isn't changed, and the page says why, if its records (or www.) point at another server or are a CNAME to another host, it isn't protected, its cPanel account is suspended, it's a subdomain, or your sentries have no address yet.

IPv6. If your sentries have IPv6 addresses, the website's AAAA records point at them. If they don't, the website's AAAA records are removed. Otherwise IPv6 visitors would reach this server directly, without protection. The confirm step says so.

Undo. Domains that show Pointing at sentries (or point there only partly) have Point back to this server. It puts back the addresses the website had on this server before you pointed it, including IPv6. If those aren't known, it uses the account's address on this server and removes the sentries' AAAA records. Visitors then reach the site without protection. Mail and cPanel service records stay as they are.

Each change is listed under Recent automatic changes and recorded in your audit log. On the server, as root, echo example.com | stillorigin-agent dns-website --point-sentries shows what would change, and adding --apply makes the change. Use --point-origin to point back.

Keep mail and cPanel services on this server​

Coming with the next release

This check is coming with the next origin agent release.

cPanel's default DNS zone points mail.example.com at the website with a CNAME record, and does the same for ftp., webmail., cpanel., whm., webdisk., cpcalendars., cpcontacts., autodiscover. and autoconfig.. When you point the website's A record at your sentries, those names follow it. Sentries only forward web traffic, so email, FTP and cPanel logins would stop working. Fix them before you change the website's DNS. Fix DNS does this for you first.

When you protect domains. After Protect selected, the page shows Before you point these domains at your sentries at the top, with what would change for the domains you just protected. Click Fix these domains, then use Fix DNS to point the website DNS at your sentries. If nothing needs changing, the page says you can go ahead.

Any time. Under Keep mail and cPanel services on this server, click Check mail and cPanel services to check every domain on the server. Nothing is changed until you click Fix these domains.

The fix replaces each of those names that is a CNAME to the website with an A record to this server's address for the site (and an AAAA record when the website has this server's IPv6 address), with the same TTL. It uses the address the website pointed at on this server, or the account's address if the website already points at your sentries.

MX records. If a domain's MX record points at the website itself (example.com), or at a name that follows it, mail would go to the sentries too. The page says so. To fix it, tick Also point MX records that follow the website at mail.<domain> before you click Fix these domains. The box is unticked each time. The MX record keeps its priority and TTL, and is changed only when mail.example.com is (or is about to become) an A record to this server. MX records that point anywhere else are never changed.

The plugin leaves everything else alone:

  • names that are already A records, or CNAMEs to another host, such as a mail provider;
  • other names, such as shop.example.com;
  • domains whose website is hosted on another server;
  • domains using other nameservers. Your client changes their records with their DNS provider.

Each change is listed under Recent automatic changes, and recorded in your audit log against the domain as made by the origin agent, for example Changed DNS record mail.example.com from CNAME example.com to A 203.0.113.5 (TTL 3600) on the origin server (origin agent 12). If stillorigin can't be reached at the time, the change is still made and the audit log entry is added later.

You can also run the check on the server as root: echo example.com | stillorigin-agent dns-mail shows what would change, and echo example.com | stillorigin-agent dns-mail --apply makes the change. Add --mx to include MX records. Use @user for all of an account's domains, or --all for every domain on the server.

Websites hosted on another server​

Some domains have an account on this server but a website somewhere else. For example, the domain's DNS zone is here, but its A record points at another server's address. Protecting one of those from here would send its visitors to the wrong server, so the plugin locks it.

A locked domain has a padlock instead of a checkbox, and says Points to another server, followed by the address (or host name) its records point at. Protect selected, Select all and automatic adding for new domains all leave it out. If you protect a whole account, the account's other domains are still added, and the result tells you how many were left out.

The plugin checks this server's own DNS zone for the domain and its www.: the A and AAAA records, and any CNAME they follow. Addresses on this server and your sentries' addresses don't lock a domain. If the zone isn't on this server, the domain isn't locked.

If the website really is on this server, correct its records in WHM › DNS Functions › Edit DNS Zone and reload the page. If it's on another server, add the domain in the portal with that server as its origin.

The shared IP notice after cPanel updates​

If you set up the notice from Show your sentry's IP address in cPanel, the origin agent puts your copy back after every cPanel update. It copies the files from /root/stillorigin-cpanel/content_includes/ into cPanel's content includes when they're missing or different. It never writes the notice itself: with no files in that folder, it does nothing.

Updating and removing the WHM plugin​

  • The WHM plugin is updated with the origin agent.
  • stillorigin-agent uninstall-whm-plugin, as root, removes only the WHM plugin and its cPanel hooks. stillorigin-agent install-whm-plugin puts it back.
  • stillorigin-agent uninstall-cpanel-plugin removes both the Manage protection page and the WHM plugin. Removing the origin agent removes both too.