Short-term solution (optional)

If you are using a flavor of Linux that uses Security-Enhanced Linux (SELinux), try disabling it until you get Blackfire to work. See the SELinux docs for your platform for how to disable SELinux for your distribution.

It is up to you to decide whether it makes sense to disable SELinux while you get Blackfire installed. While it can help ensure that Blackfire is indeed installed and not simply blocked by SELinux, it does disable important security features, so we recommend not doing this in production.

If you disable SELinux for this purpose, remember to enable it again as soon as you are done configuring Blackfire!

Long-term solution

Once you have Blackfire Agent installed and are relatively certain that everything is installed correctly, you can attempt a longer-term solution that will allow you to continue to benefit from full SELinux protection but also be able to profile with Blackfire.

First, you'll need to try to create a profile with Blackfire with one of the Companions. You will likely see an error asking if you have permission to profile this site.

Next, you'll need to use the audit2allow command to determine the correct SELinux policy that needs to be put into place.

grep blackfire/agent.sock /var/log/audit/audit.log | \
  audit2allow -M blackfire-agent

This will leave you with two files, blackfire-agent.pp and blackfire-agent.te . The latter will contain a human-readable output of the policy that was created.

The human-readable output will look something like this:

module blackfire-agent 1.0;

require {
type httpd_t;
type initrc_t;
class unix_stream_socket connectto;
}

#============= httpd_t ==============

#!!!! The file '/run/blackfire/agent.sock' is mislabeled on your system.
#!!!! Fix with $ restorecon -R -v /run/blackfire/agent.sock
allow httpd_t initrc_t:unix_stream_socket connectto;

It is important for you to double-check this file to ensure you are satisfied with the SELinux policy that is created.

Finally, use semodule to install the new policy.

semodule -i blackfire-agent.pp

Once installed, the Blackfire Agent policy will stay in effect even after a reboot. Please note that this command may take some time to complete.

You should now be able to profile your application with Blackfire using the Companions.

Still doesn't work?

Unfortunately, SELinux is quite complicated. The Blackfire team does not have the resources to configure SELinux on a case-by-case basis.

Your best bet would be truncate your audit log, try to create a profile again, and run audit2allow again. It is possible in some scenarios that unlocking one block from SELinux will expose additional scenarios that will need to be allowed.

Did this answer your question?