--- title: Install & configure NRDOT for MSSQL monitoring with CLI source: https://docs.newrelic.com/docs/opentelemetry/db360/mssql/cli --- You can install and configure the NRDOT Collector for SQL Server monitoring using the New Relic CLI. The CLI installs the collector, creates or authorizes the monitoring identity, and configures the collector in a single command. > #### 💡 TIP > > To install this through the New Relic UI instead, go to **[one.newrelic.com](https://one.newrelic.com) > Integrations & Agents > MSSQL (OpenTelemetry)** . Follow the on-screen instructions to set up the integration. ## Prerequisites [#prerequisites] - A New Relic account with a valid [license key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#overview-keys). - A New Relic [account ID](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id). - Microsoft SQL Server 2017 or later. - **Self-hosted SQL Server:** - **SQL Server Authentication:** A Linux or Windows collector host, and a login in the `sysadmin` server role (or equivalent) with its password. - **Windows Authentication or gMSA:** A Windows collector host, an administrator PowerShell session, and a Windows account or gMSA with the required permissions. - **SQL Server on AWS RDS:** - A Linux or Windows collector host with network connectivity to the RDS endpoint (inbound access granted on the SQL Server port within the RDS security group), alongside the RDS master username and password. - **Windows Domain Authentication or gMSA:** A Windows collector host and an RDS instance already joined to an AWS Managed Microsoft Active Directory domain. - **Linux collector host:** The `curl` utility, `systemd`, and the `sqlcmd` utility installed and available on `PATH` (or located under `/opt/mssql-tools18/bin` or `/opt/mssql-tools/bin`). - **Windows collector host:** The `sqlcmd.exe` utility installed and available on `PATH`. - Network connectivity to the [New Relic OTLP endpoint](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp) corresponding to the target region. ## Install and configure the NRDOT Collector [#cli-install] **Self-hosted - SQL Server Authentication** This recipe monitors one or more SQL Server instances from a single collector. Instead of prompting for a single host/port/credential set, it reads two files you create ahead of time: an **instances file** (YAML) listing every instance to monitor, and a **secrets file** (`KEY=VALUE`) with an admin login and password for each, indexed to match. 1. Create the instances file. Add one entry per SQL Server instance you want this collector to monitor, or just one entry if you're only running a single instance: ```bash cat > ~/mssql-instances.yml << 'EOF' instances: - host: localhost port: 1433 login_name: newrelic EOF ``` 2. Create the secrets file with an admin login and password for each instance, indexed to match the instances file's order. The admin login must be a member of the `sysadmin` role (or equivalent): ```bash umask 077 cat > ~/mssql-secrets.env << 'EOF' NR_CLI_MSSQL_ADMIN_USER_1= NR_CLI_MSSQL_ADMIN_PASSWORD_1= EOF chmod 600 ~/mssql-secrets.env ``` **Linux:** ```bash curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash && sudo NEW_RELIC_API_KEY=INSERT_YOUR_API_KEY NEW_RELIC_ACCOUNT_ID=INSERT_YOUR_ACCOUNT_ID NEW_RELIC_REGION=INSERT_YOUR_REGION /usr/local/bin/newrelic install -n nrdot-collector-mssql ``` **Windows** (run in an Administrator PowerShell session): ```powershell [Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql ``` The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively. | Variable | Description | Default | | ----------------------------- | --------------------------------------------------------------------------------------------- | ------- | | `NR_CLI_MSSQL_CONFIG_PRESET` | NRDOT configuration: 1 for Basic 2 for Advanced | `1` | | `NR_CLI_MSSQL_INSTANCES_FILE` | Required. Path to the instances YAML file. | None | | `NR_CLI_MSSQL_SECRETS_FILE` | Required. Path to the secrets file (`KEY=VALUE`, one admin login/password pair per instance). | None | > #### 💡 TIP > > To monitor more than one SQL Server instance from this collector, add more entries to the instances file and matching numbered credentials (`_2`, `_3`, ...) to the secrets file. An instance that fails its checks is skipped with a logged reason rather than aborting the whole install. The install only fails outright if none of the instances pass. **Self-hosted - Windows Authentication or gMSA** This method is only supported on a Windows collector host. It uses Windows authentication (`integrated security=true`) instead of SQL logins, and monitors one or more SQL Server instances from a single collector. The collector is one Windows service with one logon account, and connects to **every** instance as that account, so a multi-instance install always uses one auth mode and one Windows identity, granted on every instance you list. 1. Create the instances file. Add one entry per SQL Server instance you want this collector to monitor, or just one entry if you're only running a single instance. Only `host` and `port` are needed (no `login_name`, no secrets file): ```yaml instances: - host: sql01.contoso.com port: 1433 - host: sql02.contoso.com port: 1433 ``` Save this anywhere on the collector host, for example `C:\mssql-instances.yml`. For a named instance, use `host` plus its static TCP port rather than `host\INSTANCE`. Before you run this command, have ready: - The instances file from step 1 - Whether you're using a Windows account or a gMSA account - For Windows Authentication: whether the collector runs on the same host as SQL Server, or on a different host - The Windows account (or gMSA account) to grant permissions to (not needed if the collector runs on the same host as SQL Server) - Whether you want Basic or Advanced metrics Run this in an Administrator PowerShell session: ```powershell [Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-winauth ``` The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively. | Variable | Description | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `NR_CLI_MSSQL_CONFIG_PRESET` | NRDOT configuration: 1 for Basic 2 for Advanced | `1` | | `NR_CLI_MSSQL_AUTH_MODE` | SQL Server authentication: 1 for Windows Authentication 2 for gMSA | `1` | | `NR_CLI_MSSQL_WINAUTH_LOCATION` | Windows Authentication only: 1 if the collector runs on the same host as SQL Server (the installing user's identity is used and the service stays LocalSystem, so no domain account is needed) 2 if it runs on a different host | `1` | | `NR_CLI_MSSQL_INSTANCES_FILE` | Required. Path to the instances YAML file (`host`/`port` per instance). | None | | `NR_CLI_MSSQL_WIN_ACCOUNT` | Windows account to grant permissions to, `DOMAIN\username`. Required only when `NR_CLI_MSSQL_AUTH_MODE` is `1` and `NR_CLI_MSSQL_WINAUTH_LOCATION` is `2`; leave blank for gMSA or for the same-host flow. | None | | `NR_CLI_MSSQL_WIN_PASSWORD` | Password for that Windows account. Required only when `NR_CLI_MSSQL_AUTH_MODE` is `1` and `NR_CLI_MSSQL_WINAUTH_LOCATION` is `2`; leave blank for gMSA or for the same-host flow. | None | | `NR_CLI_MSSQL_GMSA_ACCOUNT` | gMSA account, `DOMAIN\gMSAName$`. gMSA only; leave blank for Windows Authentication. | None | > #### 💡 TIP > > To monitor more than one SQL Server instance from this collector, add more entries to the instances file. One auth mode and one Windows identity are used for **every** instance in the file; different identities per instance aren't supported. An invalid host or port, a duplicate `host:port`, or an instance that fails its version check or permission setup is skipped with a logged reason rather than aborting the whole install. The same-host flow (`NR_CLI_MSSQL_WINAUTH_LOCATION` `1`) only works for instances on this machine. List instances on other hosts using the different-host flow, or gMSA. **AWS RDS - SQL Server Authentication** This recipe monitors one or more RDS SQL Server endpoints from a single collector, using the same instances file / secrets file pattern as self-hosted. 1. Create the instances file, using the RDS endpoint as `host`, with just one entry if you're only monitoring a single RDS instance: ```bash cat > ~/mssql-instances.yml << 'EOF' instances: - host: mydb1.abcdefg12345.us-east-1.rds.amazonaws.com port: 1433 login_name: newrelic EOF ``` 2. Create the secrets file with the RDS master username and password for each instance, indexed to match the instances file's order: ```bash umask 077 cat > ~/mssql-secrets.env << 'EOF' NR_CLI_MSSQL_ADMIN_USER_1=admin NR_CLI_MSSQL_ADMIN_PASSWORD_1=YourMasterPassword1 EOF chmod 600 ~/mssql-secrets.env ``` **Linux:** ```bash curl -Ls https://download.newrelic.com/install/newrelic-cli/scripts/install.sh | bash && sudo NEW_RELIC_API_KEY=INSERT_YOUR_API_KEY NEW_RELIC_ACCOUNT_ID=INSERT_YOUR_ACCOUNT_ID NEW_RELIC_REGION=INSERT_YOUR_REGION /usr/local/bin/newrelic install -n nrdot-collector-mssql-rds ``` **Windows** (run in an Administrator PowerShell session): ```powershell [Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-rds ``` The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively. | Variable | Description | Default | | ----------------------------- | ----------------------------------------------------------------------------------------------------- | ------- | | `NR_CLI_MSSQL_CONFIG_PRESET` | NRDOT configuration: 1 for Basic 2 for Advanced | `1` | | `NR_CLI_MSSQL_INSTANCES_FILE` | Required. Path to the instances YAML file, using RDS endpoints as `host`. | None | | `NR_CLI_MSSQL_SECRETS_FILE` | Required. Path to the secrets file (`KEY=VALUE`, one RDS master username/password pair per instance). | None | > #### 💡 TIP > > To monitor more than one RDS SQL Server endpoint from this collector, add more entries to the instances file and matching numbered credentials to the secrets file. An instance that fails its checks is skipped with a logged reason rather than aborting the whole install. **AWS RDS - Windows Domain Authentication or gMSA** This method is only supported on a Windows collector host, and requires your RDS instances to already be joined to an AWS Managed Microsoft AD domain. It monitors one or more RDS SQL Server endpoints from a single collector. The collector is one Windows service with one logon account, and connects to **every** endpoint as that account, so a multi-instance install always uses one auth mode and one Windows identity, granted on every endpoint you list. Unlike the self-hosted method above, there's no "same host" option here: a domain account (or gMSA) is always required. 1. Create the instances file, using each RDS endpoint as `host`, with just one entry if you're only monitoring a single RDS instance: ```yaml instances: - host: mydb1.xxxxxxxxxx.us-east-1.rds.amazonaws.com port: 1433 - host: mydb2.xxxxxxxxxx.us-east-1.rds.amazonaws.com port: 1433 ``` Save this anywhere on the collector host, for example `C:\mssql-instances.yml`. Before you run this command, have ready: - The instances file from step 1 - Whether you're using a Windows domain account or a gMSA account - The domain account (or gMSA account) to grant permissions to - Whether you want Basic or Advanced metrics Run this in an Administrator PowerShell session: ```powershell [Net.ServicePointManager]::SecurityProtocol = 'tls12, tls'; $WebClient = New-Object System.Net.WebClient; $WebClient.DownloadFile("https://download.newrelic.com/install/newrelic-cli/scripts/install.ps1", "$env:TEMP\install.ps1"); & PowerShell.exe -ExecutionPolicy Bypass -File $env:TEMP\install.ps1; $env:NEW_RELIC_API_KEY='INSERT_YOUR_API_KEY'; $env:NEW_RELIC_ACCOUNT_ID='INSERT_YOUR_ACCOUNT_ID'; $env:NEW_RELIC_REGION='INSERT_YOUR_REGION'; & 'C:\Program Files\New Relic\New Relic CLI\newrelic.exe' install -n nrdot-collector-mssql-rds-winauth ``` The CLI prompts interactively for the following variables. You can also set them ahead of time as environment variables to run non-interactively. | Variable | Description | Default | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------- | | `NR_CLI_MSSQL_CONFIG_PRESET` | NRDOT configuration: 1 for Basic 2 for Advanced | `1` | | `NR_CLI_MSSQL_AUTH_MODE` | SQL Server authentication: 1 for Windows Domain Authentication 2 for gMSA | `1` | | `NR_CLI_MSSQL_INSTANCES_FILE` | Required. Path to the instances YAML file, using RDS endpoints as `host`. | None | | `NR_CLI_MSSQL_WIN_ACCOUNT` | Windows domain account to grant permissions to, `DOMAIN\username`. Windows Domain Authentication only; leave blank for gMSA. | None | | `NR_CLI_MSSQL_WIN_PASSWORD` | Password for that domain account. Windows Domain Authentication only; leave blank for gMSA. | None | | `NR_CLI_MSSQL_GMSA_ACCOUNT` | gMSA account, `DOMAIN\gMSAName$`. gMSA only; leave blank for Windows Domain Authentication. | None | > #### 💡 TIP > > To monitor more than one RDS SQL Server endpoint from this collector, add more entries to the instances file. One auth mode and one Windows identity are used for **every** endpoint in the file. An invalid host or port, a duplicate `host:port`, or an endpoint that fails its version check or permission setup is skipped with a logged reason rather than aborting the whole install. ## Find and use your data [#find] Once your data is being collected, you can access comprehensive SQL Server database monitoring through the New Relic UI. To find your SQL Server database entity in New Relic: 1. Go to **[one.newrelic.com](https://one.newrelic.com) > All capabilities > Databases**. 2. From the **Entity type** dropdown, select **MSSQL instance**, then click **Apply**. 3. Select your SQL Server database from the list of entities. After setting up SQL Server monitoring with NRDOT, you can: - [Create custom dashboards](https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/introduction-dashboards/) to visualize your database metrics - [Set up alerts](https://docs.newrelic.com/docs/alerts/create-alert/create-alert-condition/alert-conditions/) for critical database performance thresholds - [Explore your data](https://docs.newrelic.com/docs/query-your-data/explore-query-data/browse-data/introduction-data-explorer/) using New Relic query capabilities ## Related documentation [#related-docs] [Set up APM-database correlation](https://docs.newrelic.com/docs/opentelemetry/db360/capabilities/db-apm) Learn how to correlate your application performance with database operations in New Relic. [Troubleshooting](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/troubleshooting) Learn how to troubleshoot your MSSQL monitoring setup in New Relic. [Metrics reference](https://docs.newrelic.com/docs/opentelemetry/db360/mssql/metrics-reference) Learn about the available metrics collected by the NRDOT Collector.