Unless instructed otherwise, the standard installation for the PHP agent will automatically start the daemon if it detects that it is not running. The license key is configured for the agent in a PHP INI file, and it can be modified on a per-directory or per-virtual host basis. The daemon also is configured via the agent configuration (INI) file.
Automatically starting newrelic-daemon (Agent mode)
Unless you have specific reasons to use the external startup mode, use this automatic configuration process. Most users find this to be the easiest and least error-prone, because configuration takes place in a single file, and you do not need to start up the daemon.
This mode uses settings in your INI file to configure the daemon. It also automatically starts the daemon if the agent detects the daemon is not already running. This is sometimes referred to as "agent mode."
In automatic startup mode:
- Daemon configuration and all other global settings are in your global PHP ini file.
- The agent automatically starts the daemon each time it starts up (either on the command line or each time Apache/PHP-FPM restarts).
- Write access permissions in the daemon log file control who may start the daemon.
- The startup header in the php-agent.log file includes "agent" to indicate automatic startup mode.
To use the agent startup mode:
- Ensure the daemon isn't running by executing
- Ensure that
/etc/newrelic/newrelic.cfgdoes not exist. If it does, move it elsewhere or remove it.
- Edit your INI file and set the daemon-related options. These options are also documented in the INI template file located at
- Restart your web server or PHP process manager to pick up the new settings.
Selecting manual (External) mode
In manual mode, you must start the daemon and the web server in order to start the agent. This is also referred to as "external" mode. Here are examples of why you may want to use manual mode instead of automatic startup mode:
- You run a multi-tenant site where each customer has control over their own web service. You would not want all tenants to be running their own private copy of the daemon, so providing one that is started at system boot time and shared across all tenants better utilizes your system resources. Each customer can provide their own private license key in their INI files (or you provide the license keys on a virtual host basis).
- You want to retain the ability to shut the daemon down without affecting your web server uptime. This mode ensures that if you need to shut the daemon down, it will stay shut down until you reboot the system or explicitly start it again.
- You want the daemon to run as root (or some other user with appropriate permissions) so that the log file need not be exposed to anyone except root or a special user. The daemon log file has the potential, albeit a low one, to contain sensitive data.
- You are more comfortable with service daemons being started by traditional init scripts.
Manually starting newrelic-daemon (External mode)
In manual (or external) startup mode:
- Daemon configuration is in newrelic.cfg.
- The daemon starts up either at system boot time or by running its startup script.
- The log file and config file permissions control which users may start and stop the daemon.
- The startup header in the php-agent.log file includes init to indicate manual startup mode.
If your daemon configuration file is located at /etc/newrelic/newrelic.cfg, the agent does not attempt to automatically start the daemon. If you have moved this file and still want to use this startup method, add the following to your global INI file:
newrelic.daemon.dont_launch = 3.
If you want to use this external startup method:
- Go to:
cp /etc/newrelic/newrelic.cfg.template /etc/newrelic/newrelic.cfg
- Edit /etc/newrelic/newrelic.cfg and adjust any required values.
- Restart your web server or PHP process manager in order to pick up the new settings.