> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm/broker-vm-data-collector-applets/activate-database-collector.md). # Activate Database Collector {% hint style="info" %} ### Notice Ingesting logs and data from external sources requires a Cortex XDR Pro per GB license. {% endhint %} {% hint style="info" %} ### Note This data source is only available in your tenant if the tenant was activated before October 1, 2025 with an active Cortex XDR Pro per GB license. {% endhint %} The Broker VM provides a Database Collector applet that enables you to collect data from a client relational database directly to your log repository for query and visualization purposes. After you activate the Database Collector applet on a Broker VM in your network, you can collect records as datasets (**`__raw`**) by defining the following. * Database connection details, where the connection type can be MySQL, PostgreSQL, MSSQL, and Oracle. Cortex XDR uses Open Database Connectivity (ODBC) to access the databases. * Settings related to the query details for collecting the data from the database to monitor and upload to Cortex XDR . {% hint style="warning" %} ### Prerequisite * [Set up and configure Broker VM](/cortex-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm.md) * Kerberos authentication for MSSQL: * DNS resolution: The Broker VM must resolve and reach the Active Directory. Domain controllers serve as the Kerberos KDC. Configure DNS on the Broker VM so it can locate the domain. * Network access to the KDC: The Broker VM must have open network connectivity to reach the Active Directory domain controllers for Kerberos authentication. * Time synchronization: The Broker VM's clock must be tightly synchronized with the Active Directory domain. Kerberos security protocols strictly reject authentication requests if there is a significant clock difference. * Service Principal Name (SPN): The target SQL Server instance must have a valid SPN registered within Active Directory. {% endhint %} ### How to activate the Database Collector 1. Select Settings → Configurations → Data Broker → **Broker VMs**. 2. Do one of the following: * On the **Brokers** tab, find the Broker VM, and in the **APPS** column, left-click **Add** → **DB Collector**. * On the **Clusters** tab, find the Broker VM, and in the **APPS** column, left-click **Add** → **DB Collector**. 3. Configure your Database Collector settings.
Database Connection | Field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Connection | Select the type of database connection as **MySQL**, **PostegreSQL**, **MSSQL**, or **Oracle**. | | Host | Specify the hostname or IP address of the database. | | Port | Specify the port number of the database. | | Database |

Specify the database name for the type of database configured. This field is relevant when configuring a Connection Type for MySQL, PostegreSQL, and MSSQL.

When configuring an Oracle connection, this field is called Service Name, so you can specify the name of the service.

| | Enable SSL |

Select whether to Enable SSL (default) to encrypt the data while in transit between the database and the Broker VM.

Important

When configuring the DB collector to work with an Oracle database and enabling this option, ensure the following steps are completed for a successful connection:

  1. Ensure you have the certificate of the Database server.

  2. Upload certificate to Broker CA Trust Store (Conditional):

    This step is only required if the Oracle server's certificate is self-signed or signed by a private Certificate Authority (CA). Skip this step if the certificate is signed by a publicly known CA.

    1. Navigate to the Broker VMs page by selecting Settings → Configurations → Data Broker → Broker VMs.
    2. Right-click on the relevant broker and select Configure.
    3. Scroll down to the Trusted CA Certificate section.
    4. Upload the certificate file that contains the database server's SSL/TLS certificate.
  3. Verify server-side port encryption: Confirm that the port configured for the connection has encryption enabled on the Oracle Database server side. The database must be listening for encrypted connections on the specified port.

These steps ensure that the connection is secure and the client (the Broker VM/DB Collector) successfully trusts the server's identity.

| | Username |

Enter the domain or local user identity authorized to access the database. Format restrictions apply depending on your selected Authentication Method:

  • SQL Server auth: The username may only contain letters (A-Z), digits (0-9), underscores (\_), dollar signs ($), and hash signs (#) .
  • Kerberos auth: Must use the User Principal Name (UPN) format, such as user\@REALM.
  • Kerberos / NTLM auth: Must use either the standard down-level logon format (DOMAIN\Username) or the User Principal Name (UPN) format.
| | Password |

Enter the password to access the database.

Note

The DB Collector does not support passwords containing semicolons (;).

| | Authentication Method |

Visible only when Connection is set to MSSQL. Select the authentication mechanism used to log into your MSSQL Server.

Supported options:

  • SQL Server (Default): Uses standard SQL internal authentication with a username and password defined directly on the database master catalog.
  • Kerberos: Enforces strict modern Kerberos authentication.
  • Kerberos / NTLM: A hybrid option where the system attempts a secure Kerberos authentication first.
    If the environment does not meet all Kerberos prerequisites, the applet will automatically fall back to attempting the legacy NTLM authentication mechanism.

Note

Kerberos is the recommended method for Windows Authentication. Using NTLM fallback is not recommended, as it is an outdated protocol that is no longer considered secure.

| | Test Connection | Select to validate the database connection. |
Database Query | Field | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Storage Method |

Specify whether to append the read data to the dataset, or to replace all the data in the dataset with the newly read data.

  • Append (default): Adds new data to an existing dataset. This mode is optimal for collecting aggregated logs or data, where new records are simply added to the end of the existing dataset.
  • Replace: This option is only available for Snapshot datasets and each read cycle overwrites the entire dataset with the newly collected data. This is necessary when the data that needs to be collected from the database is static data or reference data, such as a list of computers, IP addresses, or a list of users.

Important

The Database Collector applet supports a single row size of up to 65 KB. Ensure your source data does not exceed this limit per record to avoid ingestion errors.

Note

The reference data ingested using the DB Collector is counted towards license utilization.

| | Target Dataset |

This option is only displayed when the Storage Method is Replace. Select the name of an existing Snapshot dataset or create a new Snapshot dataset by specifying the name.

When you create a new target dataset name, specify a name that will be more meaningful for your users when they query the dataset. For example, if the original table name is accssusr, you can save the dataset as access\_per\_users.

Dataset names can contain special characters from different languages, numbers (0-9) and underscores (\_). You can create dataset names using uppercase characters, but in queries, dataset names are always treated as if they are lowercase.

| | Rising Column | This option is only displayed when the Storage Method is **Append**. Specify a column for the Database Collector applet to keep track of new rows from one input execution to the next. The column name must be configured with the same column name that is returned from the database and not the aliased name used in the query. This column must also be included in the query results. | | Retrieval Value |

This option is only displayed when the Storage Method is Append. Specify a Retrieval Value for the Database Collector applet to determine which rows are new from one input execution to the next. Cortex XDR supports configuring this value as an integer or a string that contains a timestamp. The following string timestamp formats are supported: ISO 8601 format, RFC 2822 format, date strings with month names spelled out, such as “January 1, 2022”, date strings with abbreviated month names, such as “Jan 1, 2022", and date strings with two-digit years- MM/DD/YY.

The first time the input is run, the Database Collector applet only selects those rows that contain a value higher than the value you specified in this field. Each time the input finishes running, the Database Collector applet updates the input's Retrieval Value with the value in the last row of the Rising Column.

| | Unique IDs (Optional) | This option is only displayed when the Storage Method is **Append**. Specify the column name(s) to match against when multiple records have the same value in the **Rising Column**. This column must be included in the query results. This is a comma separated field that supports multiple values. In addition, when specifying a **Unique IDs**, the query should use the greater than equal to sign (`>=`) in relation to the **Retrieval Value**. If the **Unique IDs** is left empty, the user should use the greater than sign (`>`). | | Collect Every | Specify the execution frequency of collection by designating a number and then selecting the unit as either **Seconds**, **Minutes**, **Hours**, or **Days**. When the Storage Method is **Append** the default is 30 seconds and for **Replace** the default is 12 hours. | | Vendor and Product | This option is only displayed when the Storage Method is **Append**. Specify the **Vendor** and **Product** for the type of data being collected. The vendor and product are used to define the name of your Cortex Query Language (XQL) dataset (`__raw`). | | SQL Query | Specify the **SQL Query** to run and collect data from the database by replacing the example query provided in the editor box. When the Storage Method is **Append**, the question mark (`?`) in the query is a checkpoint placeholder for the **Retrieval Value**. Every time the input is run, the Database Collector applet replaces the question mark with the latest checkpoint value (i.e. start value) for the **Retrieval Value**. The query duration, when the Storage Method is in **Replace** mode, is limited to a maximum of 24 hours. | | Generate Preview | Select **Generate Preview** to display up to 10 rows from the **SQL Query** and **Preview** the results. The **Preview** works based on the Database Collector settings, which means that if after running the query no results are returned, then the **Preview** returns no records. | | Add Query (Optional) | To define another **Query** for data collection on the configured database connection, select **Add Query**. Another **Query** section is displayed for you to configure. |
4. (Optional) Click **Add Connection** to define another database connection to collect data from another client relational database. 5. (Optional) Other available options. As needed, you can return to your Database Collector settings to manage your connections. Here are the actions available to you: * Edit the connection name by hovering over the default **Collection** name, and selecting the edit icon to edit the text. * Edit the query name by hovering over the default **Query** name, and selecting the edit icon to edit the text. * **Disable**/**Enable** a query by hovering over the top area of the query section, on the opposite side of the query name, and selecting the applicable button. * Delete a connection by hovering over the top area of the connection section, on the opposite side of the connection name, and selecting the delete icon. You can only delete a connection when you have more than one connection configured. Otherwise, this icon is not displayed. * Delete a query by hovering over the top area of the query section, on the opposite side of the query name, and selecting the delete icon. You can only delete a query when you have more than one query configured. Otherwise, this icon is not displayed. 6. Activate the Database Collector applet. After a successful activation, the **APPS** field displays **DB** with a green dot indicating a successful connection. 7. (Optional) To view metrics about the Database Collector, left-click the **DB** connection in the **APPS** field for your Broker VM. Cortex XDR displays **Resources**, including the amount of **CPU**, **Memory**, and **Disk** space the applet is using. 8. Manage the Database Collector. After you activate the Database Collector, you can make additional changes as needed. To modify a configuration, left-click the **DB** connection in the **APPS** column to display the Database Collector settings, and select: * **Configure** to redefine the Database Collector configurations. * **Deactivate** to disable the Database Collector. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm/broker-vm-data-collector-applets/activate-database-collector.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.