---
title: Agent Control settings reference
source: https://docs.newrelic.com/docs/new-relic-control/agent-control/configuration-reference
---

This page lists the Agent Control settings you can modify, with their default values. For an overview of local and remote configuration, and for examples of how to configure the agents that Agent Control manages, see [Managing configurations](https://docs.newrelic.com/docs/new-relic-control/agent-control/configuration).

The Fleet Control connection (`fleet_control`), `host_id`, the managed `agents`, and value providers are covered in [Managing configurations](https://docs.newrelic.com/docs/new-relic-control/agent-control/configuration).

## How Agent Control reads its settings [#how-settings-are-read]

Agent Control reads its settings from the local configuration file:

| Environment | Local configuration file                                                                       |
| ----------- | ---------------------------------------------------------------------------------------------- |
| Linux       | `/etc/newrelic-agent-control/local-data/agent-control/local_config.yaml`                       |
| Windows     | `C:\Program Files\New Relic\newrelic-agent-control\local-data\agent-control\local_config.yaml` |
| Kubernetes  | The `agentControlDeployment.chartValues.config` section of your `values.yaml` file             |

> #### ⚠️ IMPORTANT
>
> Only the `agents` setting and the version settings used for upgrades can be changed through remote configuration from Fleet Control. All other settings on this page are local: change them in the local configuration file or with environment variables, and restart Agent Control to apply them.

### Override settings with environment variables [#environment-variables]

You can set any setting as an environment variable. Use the `NR_AC_` prefix, write the setting name in uppercase, and use a double underscore (`__`) to separate nested keys. Environment variables take precedence over the local configuration file.

```bash
# log.level
NR_AC_LOG__LEVEL=DEBUG

# fleet_control.auth_config.client_id
NR_AC_FLEET_CONTROL__AUTH_CONFIG__CLIENT_ID="some-client-id"
```

On hosts, you can define these variables in the service environment file or in an `environment_variables.yaml` file in the local configuration directory (`/etc/newrelic-agent-control/` on Linux, `C:\Program Files\New Relic\newrelic-agent-control\` on Windows). The file must be a flat YAML map of string keys to string values:

```yaml
NR_AC_LOG__LEVEL: "DEBUG"
HTTPS_PROXY: "http://proxy.local:8443"
```

-   Keys must start with a letter or underscore, and contain only letters, digits, and underscores.
-   Agent Control doesn't watch this file. Restart Agent Control after you change it.
-   Agent Control passes these variables to the agents it manages.
-   If the file has an invalid entry, Agent Control fails to start.

## Logging: `log` [#log]

Use the `log` setting to change the log level, enable file logging, or change the log format.

```yaml
log:
  level: debug
  format:
    formatter: pretty
    target: true
  file:
    enabled: true
    path: /var/log/my-folder/agent-control.log
```

| Setting                           | Description                                                                                                                                                                                                                                                                                                                                                                                          | Default                 |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `log.level`                       | Log level: `error`, `warn`, `info`, `debug`, or `trace`. Only Agent Control's own components log at this level; logs from external dependencies stay disabled.                                                                                                                                                                                                                                       | `info`                  |
| `log.insecure_fine_grained_level` | A [tracing filter directive](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) (for example, `debug`) that also enables logs from external dependencies. When you set it, `log.level` is ignored. This setting is insecure because external dependencies can log sensitive data, such as HTTP headers. Use it only for short debugging sessions. | (empty)                 |
| `log.format.formatter`            | `json` for newline-delimited JSON logs, or `pretty` for human-readable single-line logs.                                                                                                                                                                                                                                                                                                             | `json`                  |
| `log.format.target`               | Include the log target (the module that emitted the log) in each log line.                                                                                                                                                                                                                                                                                                                           | `false`                 |
| `log.format.timestamp`            | Timestamp format, using [strftime specifiers](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).                                                                                                                                                                                                                                                                                      | `%Y-%m-%dT%H:%M:%S`     |
| `log.format.ansi_colors`          | Use ANSI colors in the logs sent to standard error.                                                                                                                                                                                                                                                                                                                                                  | `false`                 |
| `log.file.enabled`                | Write logs to a file.                                                                                                                                                                                                                                                                                                                                                                                | `false`                 |
| `log.file.path`                   | Path of the log file. If you don't set it, Agent Control writes `newrelic-agent-control.log` in its default log directory.                                                                                                                                                                                                                                                                           | (default log directory) |
| `log.show_spans`                  | Show tracing spans as log lines. Spans add details that can help with debugging.                                                                                                                                                                                                                                                                                                                     | `false`                 |

> #### 💡 TIP
>
> Log files rotate daily, and Agent Control keeps the last 30 files. You can't change this behavior.

## Proxy: `proxy` [#proxy]

Agent Control uses the `HTTP_PROXY` and `HTTPS_PROXY` environment variables of your system. You can also set a proxy with the `proxy` setting. If more than one is defined, Agent Control uses them in this order of precedence:

1.  The `proxy` setting
2.  The `HTTP_PROXY` environment variable
3.  The `HTTPS_PROXY` environment variable

```yaml
proxy:
  url: https://user:password@proxy.example.com:8080
  ca_bundle_file: /etc/ssl/certs/proxy-ca.pem
```

| Setting                     | Description                                                                               | Default |
| --------------------------- | ----------------------------------------------------------------------------------------- | ------- |
| `proxy.url`                 | Proxy URL, in the format `<protocol>://<user>:<password>@<host>:<port>`.                  | (empty) |
| `proxy.ca_bundle_dir`       | Directory with CA certificates in PEM format. Agent Control reads all `.pem` files in it. | (empty) |
| `proxy.ca_bundle_file`      | Path to a CA certificate bundle in PEM format.                                            | (empty) |
| `proxy.ignore_system_proxy` | Ignore the `HTTP_PROXY` and `HTTPS_PROXY` environment variables.                          | `false` |

> #### ⚠️ CAUTION
>
> The proxy you configure in Agent Control isn't applied automatically to the agents it manages. Configure the proxy separately for each agent.

## Status server: `server` [#server]

The local status server reports the status of Agent Control and its managed agents. For how to query it, see [Monitoring with Agent Control](https://docs.newrelic.com/docs/new-relic-control/agent-control/monitoring).

```yaml
server:
  enabled: true
  host: "127.0.0.1"
  port: 51200
```

| Setting          | Description                           | Default     |
| ---------------- | ------------------------------------- | ----------- |
| `server.enabled` | Enable the status server.             | `false`     |
| `server.host`    | Address the status server listens on. | `127.0.0.1` |
| `server.port`    | Port the status server listens on.    | `51200`     |

## Health checks: `health_check` [#health-check]

```yaml
health_check:
  interval: 60s
  initial_delay: 60s
```

| Setting                      | Description                                 | Default |
| ---------------------------- | ------------------------------------------- | ------- |
| `health_check.interval`      | Time between Agent Control health checks.   | `30s`   |
| `health_check.initial_delay` | Time to wait before the first health check. | `30s`   |

## Uptime report: `uptime_report` [#uptime-report]

Agent Control reports its uptime as a metric when [self-instrumentation](#self-instrumentation) metrics are enabled.

```yaml
uptime_report:
  enabled: true
  interval: 60s
```

| Setting                  | Description                         | Default |
| ------------------------ | ----------------------------------- | ------- |
| `uptime_report.enabled`  | Report the uptime of Agent Control. | `true`  |
| `uptime_report.interval` | Time between uptime reports.        | `60s`   |

## Self-instrumentation: `self_instrumentation` [#self-instrumentation]

Agent Control can report its own logs and metrics using OpenTelemetry. If you configure a [proxy](#proxy), self-instrumentation uses it.

```yaml
self_instrumentation:
  opentelemetry:
    endpoint: https://otlp.nr-data.net:4318
    headers:
      api-key: YOUR_LICENSE_KEY
    metrics:
      enabled: true
      interval: 120s
    logs:
      enabled: true
```

| Setting                                                                | Description                                                                                                                                                                              | Default                                               |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `self_instrumentation.opentelemetry.endpoint`                          | HTTPS endpoint that receives the OTLP data. Required when `opentelemetry` is set. For New Relic, use the `api-key` header to authenticate.                                               | (none)                                                |
| `self_instrumentation.opentelemetry.headers`                           | Headers added to every request to the endpoint.                                                                                                                                          | (empty)                                               |
| `self_instrumentation.opentelemetry.client_timeout`                    | Timeout for requests to the endpoint.                                                                                                                                                    | `30s`                                                 |
| `self_instrumentation.opentelemetry.custom_attributes`                 | Attributes added to all reported metrics and logs.                                                                                                                                       | (empty)                                               |
| `self_instrumentation.opentelemetry.insecure_level`                    | Filter directive that defines which logs are reported. It's insecure because enabling external dependencies can leak sensitive data. The default only includes Agent Control components. | `newrelic_agent_control=debug,opamp_client=debug,off` |
| `self_instrumentation.opentelemetry.metrics.enabled`                   | Report metrics.                                                                                                                                                                          | `false`                                               |
| `self_instrumentation.opentelemetry.metrics.interval`                  | Time between metric reports.                                                                                                                                                             | `60s`                                                 |
| `self_instrumentation.opentelemetry.logs.enabled`                      | Report logs.                                                                                                                                                                             | `false`                                               |
| `self_instrumentation.opentelemetry.logs.batch_config.scheduled_delay` | Delay between batch exports of logs.                                                                                                                                                     | `30s`                                                 |
| `self_instrumentation.opentelemetry.logs.batch_config.max_size`        | Maximum number of logs in a single batch.                                                                                                                                                | `512`                                                 |

## OCI registry: `oci` [#oci]

Agent Control pulls agent packages from an OCI registry.

```yaml
oci:
  registry: "docker.io"
  auth:
    basic:
      username: "my-user"
      password: "my-password"
```

| Setting                                              | Description                                   | Default          |
| ---------------------------------------------------- | --------------------------------------------- | ---------------- |
| `oci.registry`                                       | Registry host name or URL. It can't be empty. | `docker.io`      |
| `oci.auth.basic.username`, `oci.auth.basic.password` | Credentials for basic authentication.         | Anonymous access |
| `oci.auth.bearer.token`                              | Token for bearer authentication.              | Anonymous access |

If you set `oci.auth`, define exactly one of `basic` or `bearer`.

## Package and agent type verification [#verification]

Agent Control verifies the signatures of the packages it downloads and of the agent type definitions it pulls. Only disable verification for testing: Agent Control logs a warning when it's disabled.

```yaml
agent_packages:
  signature_verification_enabled: true

agent_types:
  default_remote:
    signature_verification_enabled: true
```

| Setting                                                     | Description                                                                          | Default                            |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------- |
| `agent_packages.signature_verification_enabled`             | Verify the signature of agent packages.                                              | `true`                             |
| `agent_types.default_remote.signature_verification_enabled` | Verify the signature of agent type definitions.                                      | `true`                             |
| `agent_types.default_remote.repository`                     | Repository, in the configured `oci.registry`, that holds the agent type definitions. | New Relic's agent types repository |
| `agent_types.default_remote.public_key_url`                 | JWKS URL of the public key used to verify agent type signatures.                     | New Relic's public key URL         |

## Self-update on hosts: `self_update` [#self-update]

On hosts, Agent Control can update itself when Fleet Control deploys a new version.

```yaml
self_update:
  download_retry:
    max_attempts: 3
  upgrade_backoff:
    base_delay: 30s
    max_delay: 600s
```

| Setting                                                | Description                                                                                                                                           | Default                    |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `self_update.signature_verification_enabled`           | Verify the signature of the Agent Control package.                                                                                                    | `true`                     |
| `self_update.package.download.oci.repository`          | OCI repository that holds the Agent Control packages.                                                                                                 | New Relic's repository     |
| `self_update.package.download.oci.public_key_url`      | JWKS URL of the public key used to verify the package signature.                                                                                      | New Relic's public key URL |
| `self_update.download_retry.max_attempts`              | Maximum download attempts per update attempt. Must be greater than zero.                                                                              | `3`                        |
| `self_update.download_retry.base_delay`                | Initial delay between download retries.                                                                                                               | `1s`                       |
| `self_update.download_retry.max_delay`                 | Maximum delay between download retries.                                                                                                               | `30s`                      |
| `self_update.download_retry.jitter`                    | Add random jitter to the retry delays.                                                                                                                | `true`                     |
| `self_update.upgrade_backoff.max_consecutive_failures` | Number of consecutive failed upgrades before Agent Control escalates the failure report. It keeps retrying at `max_delay`. Must be greater than zero. | `5`                        |
| `self_update.upgrade_backoff.base_delay`               | Initial wait before retrying a failed upgrade.                                                                                                        | `30s`                      |
| `self_update.upgrade_backoff.max_delay`                | Maximum wait before retrying a failed upgrade.                                                                                                        | `600s`                     |
| `self_update.upgrade_backoff.jitter`                   | Add random jitter to the upgrade retry delays.                                                                                                        | `true`                     |

## Kubernetes settings: `k8s` [#k8s]

The Agent Control Helm chart sets most of the `k8s` settings for you. Change them only if you manage the deployment yourself.

```yaml
k8s:
  cluster_name: "my-cluster"
  namespace: "newrelic-agent-control"
  namespace_agents: "newrelic-agent-control-agents"
```

| Setting                           | Description                                                                                                                                                                                                           | Default                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `k8s.cluster_name`                | Required. Name that identifies the cluster in Fleet Control.                                                                                                                                                          | (none)                          |
| `k8s.namespace`                   | Required. Namespace where Agent Control creates the resources it manages directly.                                                                                                                                    | (none)                          |
| `k8s.namespace_agents`            | Required. Namespace where Agent Control creates the resources of the managed agents.                                                                                                                                  | (none)                          |
| `k8s.current_chart_version`       | Version of the chart used to deploy Agent Control. The Helm chart passes it as an environment variable to avoid race conditions after a failed upgrade.                                                               | (empty)                         |
| `k8s.ac_remote_update`            | Apply remote updates of the Agent Control chart. When `false`, Agent Control ignores them.                                                                                                                            | `false`                         |
| `k8s.ac_release_name`             | Helm release name of Agent Control. If it's empty, Agent Control doesn't check its own health or apply updates.                                                                                                       | (empty)                         |
| `k8s.cd_enabled`                  | Whether the continuous deployment (Flux) component is enabled. When `false`, Agent Control doesn't check the health of that component or update it, and it also disables remote updates for it and for Agent Control. | `true`                          |
| `k8s.cd_remote_update`            | Apply remote updates of the Agent Control CD chart. When `false`, Agent Control ignores them and doesn't check the health of that component.                                                                          | `false`                         |
| `k8s.cd_release_name`             | Helm release name of the Agent Control CD chart.                                                                                                                                                                      | (empty)                         |
| `k8s.auth_secret.secret_name`     | Name of the Kubernetes secret that holds the credentials.                                                                                                                                                             | `newrelic-agent-control-secret` |
| `k8s.auth_secret.secret_key_name` | Key in the secret that holds the credential value.                                                                                                                                                                    | `api-key`                       |
