Audit connection events

Describes how to audit connection events.

Starting with version 6.2.18, Redis Enterprise Software lets you audit database connection and authentication events. This helps you track and troubleshoot connection activity.

The following events are tracked:

• Database connection attempts
• Authentication requests, including requests for new and existing connections
• Database disconnects

When tracked events are triggered, notifications are sent via TCP to an address and port defined when auditing is enabled. Notifications appear in near real time and are intended to be consumed by an external listener, such as a TCP listener, third-party service, or related utility.

For development and testing environments, notifications can be saved to a local file; however, this is neither supported nor intended for production environments.

For performance reasons, auditing is not enabled by default. In addition, auditing occurs in the background (asynchronously) and is non-blocking by design. That is, the action that triggered the notification continues without regard to the status of the notification or the listening tool.

Enable audit notifications

Cluster audits

To enable auditing for your cluster, use:

• rladmin

  rladmin cluster config auditing db_conns \
     audit_protocol <TCP|local> \
     audit_address <address> \
     audit_port <port> \
     audit_reconnect_interval <interval in seconds> \
     audit_reconnect_max_attempts <number of attempts>
  

  where:

  • audit_protocol indicates the protocol used to process notifications. For production systems, TCP is the only value.

  • audit_address defines the TCP/IP address where one can listen for notifications

  • audit_port defines the port where one can listen for notifications

  • audit_reconnect_interval defines the interval (in seconds) between attempts to reconnect to the listener. Default is 1 second.

  • audit_reconnect_max_attempts defines the maximum number of attempts to reconnect. Default is 0. (infinite)

  Development systems can set audit_protocol to local for testing and training purposes; however, this setting is not supported for production use.

  When audit_protocol is set to local, <address> should be set to a stream socket defined on the machine running Redis Enterprise and <port> should not be specified:

  rladmin cluster config auditing db_conns \
     audit_protocol local audit_address <output-file>
  

  The output file (and path) must be accessible by the user and group running Redis Enterprise Software.

• the REST API

  PUT /v1/cluster/auditing/db_conns
  { 
      "audit_address": "<address>", 
      "audit_port": <port>, 
      "audit_protocol": "TCP",
      "audit_reconnect_interval": <interval>,
      "audit_reconnect_max_attempts": <max attempts>
  }
  

  where <address> is a string containing the TCP/IP address, <port> is a numeric value representing the port, <interval> is a numeric value representing the interval in seconds, and <max attempts> is a numeric value representing the maximum number of attempts to execute.

Database audits

Once auditing is enabled for your cluster, you can audit individual databases. To do so, use:

• rladmin

  rladmin tune db db:<id|name> db_conns_auditing enabled
  

  where the value of the db: parameter is either the cluster ID of the database or the database name.

  To deactivate auditing, set db_conns_auditing to disabled.

  Use rladmin info to retrieve additional details:

  rladmin info db <id|name>
  rladmin info cluster
  

• the REST API

  PUT /v1/bdbs/1
  { "db_conns_auditing": true }
  

  To deactivate auditing, set db_conns_auditing to false.

You must enable auditing for your cluster before auditing a database; otherwise, an error appears:

Error setting description: Unable to enable DB Connections Auditing before feature configurations are set.
Error setting error_code: db_conns_auditing_config_missing

To resolve this error, enable the protocol for your cluster before attempting to audit a database.

Policy defaults for new databases

To audit connections for new databases by default, use:

• rladmin

  rladmin tune cluster db_conns_auditing enabled
  

  To deactivate this policy, set db_conns_auditing to disabled.

• the REST API

  PUT /v1/cluster/policy
  { "db_conns_auditing": true }
  

  To deactivate this policy, set db_conns_auditing to false.

Notification examples

Audit event notifications are reported as JSON objects.

New connection

This example reports a new connection for a database:

{
    "ts":1655821384,
    "new_conn":
    {
        "id":2285001002 ,
        "srcip":"127.0.0.1",
        "srcp":"39338",
        "trgip":"127.0.0.1",
        "trgp":"12635",
        "hname":"",
        "bdb_name":"DB1",
        "bdb_uid":"5"
    }
}

Authentication request

Here is a sample authentication request for a database:

{
    "ts":1655821384,
    "action":"auth",
    "id":2285001002 ,
    "srcip":"127.0.0.1",
    "srcp":"39338",
    "trgip":"127.0.0.1",
    "trgp":"12635",
    "hname":"",
    "bdb_name":"DB1",
    "bdb_uid":"5",
    "status":2,
    "username":"user_one",
    "identity":"user:1",
    "acl-rules":"~* +@all"
}

The status field reports the following:

• Values of 2, 7, or 8 indicate success.

• Values of 3 or 5 indicate that the client authentication is in progress and should conclude later.

• Other values indicate failures.

Database disconnect

Here's what's reported when a database connection is closed:

{
    "ts":1655821384,
    "close_conn":
    {
        "id":2285001002,
        "srcip":"127.0.0.1",
        "srcp":"39338",
        "trgip":"127.0.0.1",
        "trgp":"12635",
        "hname":"",
        "bdb_name":"DB1",
        "bdb_uid":"5"
    }
}

Notification field reference

The field value that appears immediately after the timestamp describes the action that triggered the notification. The following values may appear:

• new_conn indicates a new external connection
• new_int_conn indicates a new internal connection
• close_conn occurs when a connection is closed
• "action":"auth" indicates an authentication request and can refer to new authentication requests or authorization checks on existing connections

In addition, the following fields may also appear in audit event notifications:

Status result codes

The status field reports the results of an authentication request as an integer. Here's what different values mean: