Using the newrelic-install script

The interactive newrelic-install script simplifies installing New Relic for PHP. It works with multiple PHP installations as well as installations in non-standard locations. Running it will:

  • Copy the correct PHP modules into place.
  • Install sample ini files.
  • Configure the New Relic proxy daemon.

Be sure to review the information about working with multiple installations and non-standard locations before running the script.

Find the installer script

The installer script location depends on how you installed the New Relic PHP agent.

  • Via system package manager: The installation script is in the /usr/bin directory.
  • Via a tarball: The installation script is in the directory where you extracted the tar archive file. The script in the tar distribution includes installation steps otherwise handled by the package manager.

Work with multiple PHP installations

For newrelic-install to correctly detect multiple installations, ensure your PATH environment variable is correctly set. The newrelic-install script can only install the agent for versions it can find.

If you want to... Do this...
Specify additional directories Use the NR_INSTALL_PATH environment variable with a colon-separated list.
Override NR_INSTALL_PATH and PATH Specify a set of directories in the NR_INSTALL_PHPLIST environment variable as a colon-separated list. These directories must contain either the command line version of PHP or the php-config script.

Invoke the installer script

The script has two modes: install and uninstall. If you invoke it with no arguments you will be prompted to select a mode.

From the command line, run the script at its location:

  • Via system package manager: /usr/bin/newrelic-install

  • Via a tar archive directory: ./newrelic-install

Use install mode

As of PHP agent version 4.0, the installer will not work properly if it detects a single version of PHP and if that version is PHP 5.1, which is deprecated. If you must run PHP 5.1, use PHP agent version 3.9.5.13. If you need help, get support at support.newrelic.com.

Follow this process to install New Relic.

1. Invoke install mode.

Invoke install mode by using one of these methods:

  • Run newrelic-install with the install command line option.
  • Run newrelic-install with no options and select the install option from the main menu when invoking the script.
2. Provide your New Relic license key.

At the prompt, enter your New Relic license key. This key will be inserted into any INI files created during the rest of the installation process.

3. Select which PHP version to use if applicable.

If newrelic-install finds more than one version of PHP, select which version of PHP to use. You will not see this screen if the script only found a single version of PHP.

Example: The menu shows seven options:

   1)   /usr/bin
   2)   /usr/local/php/5.2.16/bin
   3)   /usr/local/php/5.2.16-zts/bin
   4)   /usr/local/php/5.3.4/bin
   5)   /usr/local/php/5.3.4-zts/bin
   6)   /usr/local/php/5.4.19-zts/bin
   7)   /usr/local/php/5.5.4-zts/bin

   0)   Exit

   Select (1-7, 0 to exit, or all):

At the menu, use any of these options:

  • To select only one version, enter the number indicating the version you want to use.
  • To select multiple versions, enter a comma- or space-separated list of numbers.
  • To select every version listed, enter the keyword all.
  • To exit the installation process, Enter 0.

For each directory selected, the script will attempt to install the agent in the proper place and report on each attempt.

For PHP installations that allow multiple .ini files, the install script will copy a template file into place, if a modified one is not already installed. Make a note of the .ini files you will need to modify manually.

4. Install the daemon if applicable.

If the daemon was not installed by the package manager, install the daemon.

If this is an update or reinstall, the script provide a confirmation prompt before overwriting the old copy of the daemon.

If installation is successful, the script will show this final message:

New Relic is now installed on your system. Congratulations!
5. Restart your web server.

To activate the PHP agent, restart your web server.

If you are running PHP-FPM, you may also need to restart PHP-FPM separately before the agent will be active.

6. Note your archive file.

Note the name and location of the install archive file. This file will be located at /tmp/nrinstall-nnnn.tar and will contain both the install log and useful system information to help New Relic Technical Support with troubleshooting.

7. Fine-tune your configuration.

After you install New Relic successfully and restart your web server, you can begin gathering data about your applications. After a few minutes, data will begin to appear on your New Relic APM Overview page.

To fine-tune operation of both the PHP agent and daemon, review the PHP configuration options.

Troubleshoot PHP installation

If there were problems with the installation process, or if no data appears in New Relic APM, review the PHP troubleshooting procedures before contacting New Relic for support. Be sure to attach your archive file to any bug report, as well as the output of the phpinfo() function produced by your web server.

Use uninstall mode

You can uninstall New Relic but keep valuable config files (useful when upgrading), or permanently uninstall New Relic from your system.

Uninstall and keep config files.

This method is useful when you want to uninstall and upgrade. To uninstall New Relic using the install script, use either of these options:

  • Invoke newrelic-install with the uninstall option.
  • Run newrelic-install with no options, and select the uninstall option from the main menu when invoking the script.

The uninstall does not remove important configuration files, such as your daemon configuration file. Also, it does not remove any newrelic.ini files that you have modified.

Permanently uninstall New Relic.

To permanently uninstall New Relic from your system: Invoke newrelic-install with the purge option.

This will remove all the configuration files and any links created at installation time. This will not affect any configuration parameters that might have been placed in files such as php.in. Also, this will not remove the software packages installed on the system.

To remove the New Relic software packages installed with a package manager, see Uninstalling (RedHat and CentOS) or Uninstalling (Ubuntu and Debian).

For more help

Additional documentation resources include:

Join the discussion about PHP in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at support.newrelic.com.