Install and configure VM private minions (legacy)


The end-of-life date for the legacy virtual private minions is August 9, 2019. For current users, we recommend using containerized private minions (CPM). For details, see the Sunset plan for Virtual private minion post on New Relic's Explorers Hub.

For more information about end-of-life support, see End-of-life policy.

Private locations are an add-on feature for paid Synthetics accounts. For more information, contact your account representative or a New Relic technical sales rep.

Virtual machine (VM) private minions accept and run the jobs you assign to your private locations. A private minion is a packaged virtual appliance (.ovf file) that runs in your hypervisor. This document describes how to install, secure, and configure private minions; and how to configure your firewall rules for private minions.

Local IP and DNS settings via DHCP

Your minion uses DHCP to obtain a local IP address and DNS settings. DHCP is the preferred method for network configuration. However, for private minion versions 1.6.2 and lower, you can also modify the Ubuntu network configuration file /etc/network/interfaces. For more on static IP assignment, see Ubuntu's network configuration documentation.

For private minion versions 1.6.3 and higher, which have cloud-init installed, network configuration changes should instead be set in /etc/network/interfaces.d/50-cloud-init.cfg. The configurations in this file get imported into /etc/network/interfaces.

Install a VM private minion

To install a new minion, begin by picking a parent private location for that minion and noting its private location key. Then, download the minion software and import it into your supported hypervisor. After the minion acquires an IP address, navigate to the minion's IP address and enter the private location key.

To install a new private minion:

  1. Go to > Private locations. Then select the appropriate option:
    • To add a new private location, select plus-circle Add new and note the Private location key for later.
    • To add minions to an existing location, select the pencil pencil icon for that location and note the Private location key for later.
  2. Download the latest Synthetics minion [ZIP | 3.3 GB] and unzip the file.
  3. In your hypervisor, import the .ovf file following standard procedures for your hypervisor. Start the minion.
  4. Secure your minion: At the minion command line, enter the default username of synthetics and default password of synthetics. Then, use the passwd command to change the password.
  5. In the minion's console log, copy the IP address (obtained via DHCP) to obtain a local IP address and DNS settings:

    IP address is MINION_IP_ADDRESS
  6. In your web browser, navigate to the minion Overview page at http://MINION_IP_ADDRESS (for example,
  7. Type the Private location key you noted earlier. If necessary, also configure your proxy settings and secure your minion user interface. Select Check your configuration, then Save your configuration.

After saving your configuration, your minion is ready to receive jobs.

Private minion console log: Use the IP address listed in your minion's console log to complete minion installation, and to access the Overview page.

Configure your minion from the Overview page

You can configure your minion from the Overview page at http://MINION_IP_ADDRESS (for example, Configuration options include:

Configure proxy settings

To receive jobs, the minion must be able to connect to the Synthetics horde endpoint at Depending on your network configuration, you may need to configure proxy settings for your minion. The proxy settings will only be used to communicate with New Relic; they are not used by the monitors.

The correct proxy settings depend on your specific network configuration. Contact your network administrator for more information.

To configure your proxy settings:

  1. From the minion Overview page, select the pencil pencil icon.
  2. Select Advanced settings, then type a host and port in the Proxy field and a username and password in the Proxy authentication field.
View minion environment details

The Overview page also lists a variety of key metrics for your minion, including:

  • Network access: Whether the minion can connect to the Internet.
  • New Relic access: Whether the minion can connect to the Synthetics horde endpoint (
  • Operational: Whether the minion is ready to receive and process jobs.
  • Minion: Status information about the minion, including its Minion ID and the specific Minion Version of the software.
  • System: Information about appliance environment.
  • Jobs: Counts of the number of jobs that were Received, Skipped, Queued, Started, Finished, Timed out, or Failed.

    The Skipped metric counts jobs sent while the minion was offline. After being disconnected for a long period, the minion intelligently skips redundant jobs in order to restart as quickly as possible. This also prevents the minion from overwhelming your target with hundreds of redundant checks.

http://MINION_IP_ADDRESS: Use the minion Overview page to configure your minion's private location and proxy settings, and to view information about your minion's parent environment. The page also indicates if your minion software is out of date.

RAM and CPU settings for your minion

You can increase the capacity of your minion by changing the default settings in your hypervisor. By default, the minion virtual machine is assigned 4 GB of RAM and a 2 core CPU. Recommendation: Add at least 2 GB of RAM for each additional CPU core you allocate to your minion.

You can also increase the processing capacity for your location by creating more minions.

If you want to forecast sizing and monitor performance of your Synthetics private location, you can use New Relic Infrastructure. Installing Infrastructure is simple and involves SSHing into your private location and running install commands. See Install Infrastructure for instructions.


You can optionally secure access to the user interface of your minion by setting up a password. This allows authorized users to see sensitive information about your minion.

To set up credentials on your minion:

  1. From the minion's Overview page, select the pencil pencil icon.
  2. Select Advanced settings, and scroll to the Minion username field.

    The username is always synthetics.
  3. In the Create minion password field, enter a password that matches the provided requirements, then re-enter the password to confirm.
  4. Select Check configuration, then save.
  5. After saving your configuration, make sure your minion restarts.

Once the credentials are set up, you will need to provide them into the dialog box that appears in your browser when you first try to access the minion. The provided credentials will be used throughout your browser session.

To remove credentials on your minion, or if you receive a 403 Forbidden message, follow these steps:

  1. SSH into your minion and remove the usercreds.json file in the /opt/newrelic/synthetics/.newrelic/synthetics/minion directory.
  2. Restart your minion.

Once the minion restarts, you can follow the initial steps to set up credentials on your minion.

Update a private minion

To update a private minion, uninstall the old minion from your hypervisor, then install the new minion software. Because private minions use an appliance model, you cannot update a running minion.

Recommendation: Upgrade to the containerized private minion (CPM).


To troubleshoot your private minion, use New Relic Diagnostics, a utility that automatically detects common problems with private minions.

For more help

Recommendations for learning more: