1. Documentation
  2. Integrations
  3. cPanel

cPanel

If your project is hosted on a server infrastructure that uses WHM/cPanel, integration with Blackfire is possible by following this chapter’s instructions.

Before starting, check with your provider that the Blackfire stack is installed and enabled on the server. If not, follow the administrator procedure or ask your provider to do so.

Then, follow the procedure depending on which EasyApache version is installed: EasyApache 3 or EasyApache 4 if you want to use different sets of credentials per website.

EasyApache 4

To configure Blackfire for EasyApache 4, go to the MultiPHP INI Editor (Home >> Software >> MultiPHP INI Editor), switch to “Editor Mode”, select the proper domain, and then copy/paste/adapt to your needs the following snippet:

1
2
3
4
5
[blackfire]
; Adapt the following credentials using the ones found on
; https://blackfire.io/my/settings/credentials or your environment settings.
blackfire.server_id=e0b30241-a25d-4162-9ebb-329f784f1fc7
blackfire.server_token=3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1

EasyApache 3

To configure Blackfire for EasyApache 3, define some environment variables by creating or editing the .htaccess file in the project’s document root:

1
2
3
4
5
6
<IfModule mod_env.c>
    # Adapt the following credentials using the one found on
    # https://blackfire.io/my/settings/credentials or your environment settings.
    SetEnv BLACKFIRE_SERVER_ID e0b30241-a25d-4162-9ebb-329f784f1fc7
    SetEnv BLACKFIRE_SERVER_TOKEN 3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1
</IfModule>

Note

If Blackfire has been installed but not enabled for all users, enable it by creating a custom php.ini configuration file.

Create a php.ini file in your home directory, copy/paste the content of the default PHP configuration (usually found at /usr/local/lib/php.ini) and append the following content:

1
2
3
[blackfire]
; Only required if Blackfire is not loaded for all websites
extension=blackfire.so

Then, adapt .htaccess to use the custom php.ini file by adding the following:

1
2
3
<IfModule mod_suphp.c>
    suPHP_ConfigPath /home/<myuser>/php.ini
</IfModule>

Caution

Some of these steps may not be allowed by your provider. In such a case, contact its support and ask for the configuration by pointing at this documentation.

Administrator Procedure

As a cPanel administrator, if you want to provide the Blackfire stack to your users, you need to install the Agent and the Probe.

To install the stack, you first need to create an account on Blackfire.io.

Then follow the installation instructions for RedHat based distributions.

Then, follow the specific procedure for EA3 or EA4.

Cluster setup

If you are managing a cluster setup, please refer to our Load Balancer section to learn more about the various options at your disposal.

EasyApache 3

To enable Blackfire for your users, go to the PHP Configuration Editor, switch to “Advanced Mode” and add blackfire.so to the extension field.

EasyApache 4

Blackfire should have been automatically enabled by our Redhat package. You can check by running /opt/cpanel/ea-php56/root/usr/bin/php --ri blackfire (tweak to match the installed PHP versions).

Tip

Starting with cPanel 68 and Blackfire probe 1.19.0, the next step is not required anymore. You only need to follow it if you did not upgrade yet.

Next, allow your users to add Blackfire settings to their php.ini. Edit /usr/local/cpanel/whostmgr/etc/phpini_directives.yaml and append the following snippet at the end of the file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
blackfire.server_id:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe Server ID'
  section: 'blackfire'
  type: string
blackfire.server_token:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe Server Token'
  section: 'blackfire'
  type: string
blackfire.log_level:
  changeable: PHP_INI_ALL
  default: 1
  multiple: 0
  note: 'Blackfire probe log verbosity level'
  section: 'blackfire'
  type: integer
blackfire.log_file:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe log destination file'
  section: 'blackfire'
  type: string

Caution

cPanel Updates

Currently, because of a cPanel limitation, this last step must be repeated on every cPanel upgrade.

cPanel is aware of this limitation and we are currently in discussion with their team to smooth this experience soon.

Uninstall Blackfire

If you are using EA3, go to the PHP Configuration Editor, switch to “Advanced Mode” and remove blackfire.so from the extension field.

In all cases, remove the installed Blackfire packages.