---
title: Configure the infrastructure agent
source: https://docs.newrelic.com/docs/infrastructure/infrastructure-agent/configuration/configure-infrastructure-agent
---

The infrastructure agent can be configured in a variety of ways. The default method is to edit the [configuration variables](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings) in the `newrelic-infra.yml` file.

A configuration file template is available in [Infrastructure config file template](https://github.com/newrelic/infrastructure-agent/blob/master/assets/examples/infrastructure/newrelic-infra-template.yml.example). You can also override the config file by setting [environment variables](#Environment_Variables), or use [config management tools](#config-mgmt), such as Ansible or Puppet.

To configure on-host integrations that work with the infrastructure agent, see a [specific integration's documentation](https://docs.newrelic.com/docs/integrations/host-integrations/get-started/introduction-host-integrations).

> #### ⚠️ IMPORTANT
>
> Always [restart the agent](https://docs.newrelic.com/docs/infrastructure-start-stop-restart-check-agent-status) after changing settings.
> Integration config updates do not require an agent restart (hot-reload is supported).

## Configuration methods and precedence [#precedence]

The default method to configure the infrastructure agent is the `newrelic-infra.yml` config file. You can override the config file by setting environment variables, which is ideal for containerized environments.

![infrastructure config cascade (orders of precedence).webp](https://docs.newrelic.com/images/infrastructure_diagram_cascade-config.webp "infrastructure config cascade (orders of precedence).webp")

Environment variables override the config file. The config file overrides the agent defaults.

Here are detailed descriptions of each configuration method:

**Configuration file (`newrelic-infra.yml`) location and description**

To configure the infrastructure agent, use the `newrelic-infra.yml` file. Its default location is:

-   Linux: `/etc/newrelic-infra.yml`
-   Windows: `C:\Program Files\New Relic\newrelic-infra\newrelic-infra.yml`
-   MacOS Intel: `/usr/local/etc/newrelic-infra/newrelic-infra.yml`
-   MacOS Apple Silicon: `/opt/homebrew/etc/newrelic-infra/newrelic-infra.yml`

    For a sample config file, see our [infrastructure config file template](https://github.com/newrelic/infrastructure-agent/blob/master/assets/examples/infrastructure/newrelic-infra-template.yml.example).

**Environment variable syntax and description**

To set an environment variable, use the variable name from the config file in all caps and prefix with `NRIA_`; for example, `NRIA_LICENSE_KEY`. In containerized environments, populate configuration properties such as license key and tags via environment variables.

The options described in the [infrastructure config file template](https://github.com/newrelic/infrastructure-agent/blob/master/assets/examples/infrastructure/newrelic-infra-template.yml.example) include their corresponding environment variables, labeled as `Env var`. Environment variables are also listed in [Infrastructure configuration settings](https://docs.newrelic.com/docs/infrastructure/install-configure-manage-infrastructure/configuration/infrastructure-configuration-settings).

You can also define environment variables in the configuration file with double curly brackets `{{MY_ENV_VAR}}`. For example:

````yml
license_key: {{MY_LICENSE_KEY}}
```

<Callout variant="important">
  Often the infrastructure agent runs as a system service in the host, managed globally (e.g. `systemd` for Linux, Windows Services, `launchd` for macOS, etc).
  To apply configuration changes with environment variables in this setup, these environment variables need to be set and made visible to the isolated context where the infrastructure agent service is running.
  The way of doing this is platform-dependent, check the documentation for your platform's service manager to know how to add environment variables to system services.
</Callout>

````

**Using environment variable passthroughs with on-host integrations**

You can use environment variables to control config settings for [on-host integrations](https://docs.newrelic.com/docs/infrastructure/host-integrations/host-integrations-list), which can then be passed through to the infrastructure agent. Variables that can be used with each on-host integration are listed in the documentation for each integration, and can be set through one of the following methods.

The `passthrough_environment` option supports regex for variable names.

-   From inside the config file: Add an entry to the [infrastructure config file](https://github.com/newrelic/infrastructure-agent/blob/master/assets/examples/infrastructure/newrelic-infra-template.yml.example) to allow the agent to get the environment variables you've set.

    ```yml
    passthrough_environment:
      - HTTPS_PROXY
      - HTTP_PROXY
      - HTTP.*
      - .* 
    ```
-   From the command line: Use another environment variable to pass through these settings.

    ```ini
    NRIA_PASSTHROUGH_ENVIRONMENT="HTTPS_PROXY,HTTP_PROXY"
    ```

    Each integration has a set of variables that can be overwritten by defining and passing an environment variable with the exact same name as the argument (for example, a PORT environment variable to replace the `redis` port argument).

    You can also define environment variables in the integrations config file with the `{{}}` notation. For example:

    ```yml
    integration_name: com.newrelic.redis
    instances:
      - name: redis-metrics
        command: metrics
        arguments:
          hostname: localhost
          port: 6379
          password: {{MY_REDIS_PASSWORD}}
    ```

    > #### 💡 TIP
    >
    > Make sure the `newrelic-infra` service has visibility to any custom environment variable defined in the host. Service managers such as [systemd will not set all env vars by default](https://unix.stackexchange.com/questions/455261/how-to-set-environmental-variable-in-systemd-service) and might need additional steps.

## Explore configuration options

For a list of all settings you can configure, including definitions, defaults, and related environment variables, see [Infrastructure configuration settings](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings).

## Configuration file structure [#config_structure]

When editing agent or integration YAML config files:

-   Follow [YAML formatting conventions](https://en.wikipedia.org/wiki/YAML).
-   Do not modify the casing of the configuration options: YAML keys are case sensitive.
-   Respect the indentation levels. All indentations are in similar increments, typically of two space characters. Data in the same section of the file must use the same level of indentation. Indent any sub-sections by two spaces (see examples in [Custom attributes](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings#custom-attributes) and [Network interface filters](https://docs.newrelic.com/docs/infrastructure/install-configure-infrastructure/configuration/infrastructure-configuration-settings#network-interface-filters)).
-   YAML format distinguish between numbers and strings. Use quotes to parse configuration values as string.

A template of `newrelic-infra.yml` is available in the [infrastructure agent repository](https://github.com/newrelic/infrastructure-agent/blob/master/assets/examples/infrastructure/newrelic-infra-template.yml.example). Use a [validator](http://www.yamllint.com/) to ensure the syntax is accurate before using the file with the infrastructure agent.

## Configuration management tools [#config-mgmt]

To install and manage the infrastructure agent with configuration management tools, see the docs for:

-   [Ansible](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/config-management-tools/configure-new-relic-infrastructure-using-ansible)
-   [AWS Beanstalk](https://docs.newrelic.com/docs/infrastructure/install-infrastructure-agent/config-management-tools/configure-infrastructure-agent-aws-elastic-beanstalk)
-   [Chef](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/config-management-tools/configure-new-relic-infrastructure-using-chef)
-   [Puppet](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/config-management-tools/configure-new-relic-infrastructure-puppet)

For other options for deploying at scale, see [Automate workflows](https://developer.newrelic.com/automate-workflows).