chmonitor

Audit user sessions, login attempts, access control roles, and user definitions.

Routes/users, /roles, /security/sessions, /security/login-attempts, /security/audit-log
Feature idsecurity
Default accesspublic
Requires authNo (set CHM_FEATURE_SECURITY_ACCESS=authenticated to gate)
System tablessystem.users, system.roles, system.session_log
ClickHouse grantsSELECT on system.users, system.roles, system.session_log; or SHOW ACCESS

What it does

The Security section gives operators visibility into who has access to ClickHouse and what they have been doing.

Users lists defined ClickHouse users with their authentication methods and profile settings, sourced from system.users.

Roles lists defined roles, sourced from system.roles.

Sessions shows user session history with authentication details, sourced from system.session_log.

Login Attempts shows authentication events with failure reasons, also from system.session_log. Use it to detect brute-force attempts or misconfigured client credentials.

Audit Log is a filtered view of system.session_log focused on security-relevant events.

Pages

PageRouteWhat it showsSystem tables
Users/usersDefined users, auth methods, profilessystem.users
Roles/rolesDefined rolessystem.roles
Sessions/security/sessionsUser session historysystem.session_log
Login Attempts/security/login-attemptsAuth events and failure reasonssystem.session_log
Audit Log/security/audit-logSecurity-relevant session eventssystem.session_log

Permissions & access

All Security pages share the security feature id.

This section contains sensitive access-control data. It is recommended to gate it behind authentication in production:

CHM_FEATURE_SECURITY_ACCESS=authenticated

Disable entirely:

CHM_FEATURE_SECURITY_ENABLED=false

Config file:

[features.security]
enabled = true
access = "authenticated"

Configuration

No feature-specific configuration. Visibility of data depends on the ClickHouse grants held by the CLICKHOUSE_USER chmonitor connects as.

The minimum grant set needed for this section:

GRANT SELECT ON system.users TO chmonitor_user;
GRANT SELECT ON system.roles TO chmonitor_user;
GRANT SELECT ON system.session_log TO chmonitor_user;

Alternatively, SHOW ACCESS grants read access to all access-related system tables at once.

Notes & limitations

  • system.users and system.roles reflect users and roles defined in the ClickHouse access control system. Users defined only in users.xml may not appear (depends on ClickHouse version and configuration).
  • system.session_log must be enabled in the ClickHouse server config (<session_log>). If absent, Sessions, Login Attempts, and Audit Log pages show no data.
  • Session log retention depends on the TTL configured on system.session_log (default 30 days).
  • Grants (row-level grant assignments) are not yet surfaced as a dedicated page. Use the Users or Roles pages and the ClickHouse SHOW GRANTS command directly for grant details.