--- title: On-host integrations: Legacy configuration format source: https://docs.newrelic.com/docs/infrastructure/host-integrations/infrastructure-integrations-sdk/specifications/host-integrations-legacy-configuration-format --- New Relic Infrastructure [on-host integrations](https://docs.newrelic.com/docs/integrations/host-integrations/getting-started/introduction-host-integrations) can use one of two types of [configuration formats](https://docs.newrelic.com/docs/integrations/integrations-sdk/file-specifications/config-file-overview). This document explains the older, legacy configuration format. > #### ⚠️ IMPORTANT > > New Relic recommends using the new [standard improved configuration format](https://docs.newrelic.com/docs/create-integrations/infrastructure-integrations-sdk/specifications/host-integrations-standard-configuration-format). > To update your configuration file to this new format, check the [update section](https://docs.newrelic.com/docs/create-integrations/infrastructure-integrations-sdk/specifications/host-integrations-standard-configuration-format#update) For an introduction to configuration, see [Config overview](https://docs.newrelic.com/docs/integrations/integrations-sdk/file-specifications/config-file-overview). ## Configuration file structure [#structure] An on-host integration that uses the standard configuration format requires two configuration files: - A [definition file](#definition-file) - A [configuration file](#config-file) ## Definition file The definition file has a naming format like `INTEGRATION_NAME-definition.yml`. This file provides descriptive information about the integration, such as: the version of the JSON protocol it supports, a list of commands it can execute, and arguments that it accepts. It lives in this directory: - Linux: ``` /var/db/newrelic-infra/newrelic-integrations ``` - Windows: ``` C:\Program Files\New Relic\newrelic-infra\newrelic-integrations ``` Here's an example of an NGINX integration definition file with two command sections on a Linux system: ```yaml name: com.myorg.nginx protocol_version: 2 description: Collect metric and configuration data from NGINX os: linux commands: metrics: command: - myorg-nginx - --metrics interval: 15 inventory: command: - myorg-nginx - --inventory interval: 120 prefix: integration/myorg-nginx ``` A definition file can be broken down into two parts: - The [header](#def-header) - The [commands section](#def-commands) ### Definition file header [#def-header] Here are explanations of a definition file's header elements: | Definition header field | Description | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Required. A unique name `name` to identify the integration for logging, internal metrics, etc. When the agent loads the config file, New Relic uses the `name` to look up the integration in the agent's registry. | | `protocol_version` | Required. The version number of the protocol. New Relic uses this to ensure compatibility between the integration and the agent. If the agent does not recognize an integration's version, it will filter out that integration and create a log message. The current version of the JSON protocol is `2`. For more on protocol changes, see [SDK changes](https://docs.newrelic.com/docs/integrations/integrations-sdk/getting-started/compatibility-requirements-infrastructure-integrations-sdk#change-log). | | `description` | Optional. Human-friendly explanation of what the integration does. | | `os` | Optional. The operating system where the integration runs. New Relic uses this to filter integrations that you intend to run only on specific operating systems. Default: Run the integration regardless of the `os` value. To restrict the integration to a specific operating system, use either of these options: - `linux` - `windows` | ### Definition file commands [#def-commands] After the header is a list of commands. The commands section defines: - One or more independent operating modes for the executable - The runtime data required for it to be executed The commands section is a YAML map of command definitions, where each key is the unique alias name of the command in the integration's config file that specifies the executable to run. | Definition commands | Description | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command` | Required. The actual command line to be executed as a YAML array of command parts. These are assembled to run the actual command. For simple commands, the array might be only a single element. Additional command rules include: - `command` arguments: The command and any command line arguments that are shared for all instances of the integration configuration. - `command` execution: The command will be executed in the same directory as the definition file. - `command` path: Any commands available on the host's `$PATH` can be used. Executables located in the same directory as the definition file, or in a subdirectory of it, can be executed using a relative path. For example: - **Linux:** To run an executable called `myorg-nginx` in the same directory as the definition file, you could use `myorg-nginx` or `./myorg-nginx`. Linux systems will execute `myorg-nginx` as if the user used `./myorg-nginx`. - **Windows:** To run an executable called `myorg-nginx.exe` in the same directory as the definition file, you could use `\myorg-nginx.exe` or `.\myorg-nginx.exe`. Windows systems writing `myorg-nginx.exe` will be executed as if indicating the current path: `.\myorg-nginx.exe`. - To use a command installed inside a directory on the host's `$PATH`, simply use the command name. Example: `python`. - To run any other executable which is neither on the host's `$PATH` nor within the integration's directory, use an absolute path to the executable. Example: `/opt/jdk/bin/java`. If the given executable name exists within the integration's directory but also exists elsewhere on the system `$PATH`, the version in the integration's directory takes precedence. | | `interval` | Optional. The number of seconds between two consecutive executions of the command, in particular between the end of the previous execution and the start of the next execution. - Default for metric polling: 30 seconds. - Minimum (floor): 15 seconds. - Alerts: For metrics being used for alerts, use an interval of 30 seconds or less. | | `prefix` | Optional. The categorization of the inventory in the form of `category/short_integration_name`. Example: `integration/myorg-nginx`. The prefix is not a platform-specific path. The forward slash is the correct separator between the category and `short_integration_name`. The prefix can have a maximum of two levels. Otherwise inventory will not be reported. Default value if not set: `integration/integration_name`. | ## Configuration file [#config-file] The [configuration file](https://docs.newrelic.com/docs/infrastructure/infrastructure-integrations/custom-integrations/create-integration-config-file) has a naming format like `INTEGRATION_NAME-config.yml`. This file specifies which executables to run and the parameters required to run them. It lives in this directory: - Linux: ``` /etc/newrelic-infra/integrations.d/ ``` - Windows: ``` C:\Program Files\New Relic\newrelic-infra\integrations.d ``` > #### 💡 TIP > > We recommend [linting](http://www.yamllint.com/) the YAML configuration files before using them to avoid formatting issues. Here's an example of a config file with one instance defined. Explanations of these fields are explained below the example. ```yaml integration_name: com.myorg.nginx instances: - name: nginx1.myorg.com-metrics command: metrics arguments: status_url: http://127.0.0.1/status labels: environment: production role: load_balancer ``` Another example of a config file with two instances defined. ```yaml integration_name: com.myorg.nginx instances: - name: nginx1.myorg.com-metrics command: metrics arguments: status_url: http://one.url/status labels: environment: production role: load_balancer - name: nginx2.myorg.com-metrics command: metrics arguments: status_url: http://another.url/status labels: environment: production role: load_balancer ``` ### Config file field definitions [#config-fields] | Config file field | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `integration_name` | Required. This is the header and is used to identify which executables to run. This name must exactly match the name specified in the integration's [definition file](#definition-file). Recommendation: To ensure unique names, use reverse domain name notation. | | `name` | Required. This is the name for the specific invocation (instance) of the integration. This is used to help identify any log messages generated by this integration and is also useful for [troubleshooting](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/troubleshooting/generate-logs-troubleshooting-infrastructure). | | `command` | Required. This is the command to be executed. This must exactly match one of the unique alias names specified in the integration's [definition file](https://docs.newrelic.com/docs/infrastructure/integrations-sdk/file-specifications/integration-definition-file-specifications). | | `arguments` | Optional. A YAML object where: - Keys: The argument name. Transformed to upper case when set as environment variable. - Values: The argument values. Passed through as is. The arguments are made available to an integration as a set of environment variables. Arguments in the config file cannot be capitalised and should use underscores to separate words. | | `labels` | Optional. A YAML object where: - Keys: The label name. - Values: The defined label value. | | `integration_user` | Optional. String with the name the agent will use for executing the integration binary. Default: depends on the `usermode`. By default, integrations are executed with the same user that's running the integration agent, nri-agent for privileged and unprivileged mode and root user for root mode. When present, the infrastructure agent will execute the integration binary as the specified user. For example, to run the integration binary as the root user when running the agent in a `usermode` different than `root`, just add `integration_user: root` to the configuration file. |