In multi-user environments, permission isolation is your first line of defense. Data collectors only need write access. Dashboards only need read access. Over-provisioning creates security risks; under-provisioning breaks workflows.

GreptimeDB 1.0 beta1 introduces fine-grained read/write permission control. With a simple configuration file, you can assign readonly, writeonly, or readwrite permissions to each user—implementing the principle of least privilege.

Permission Modes

GreptimeDB supports three permission modes:

Mode	Shorthand	Allowed Operations	Typical Use Cases
readwrite	rw	Read + Write	Administrators, development environments
readonly	ro	Read only	Dashboards, reporting systems, read replicas
writeonly	wo	Write only	Data collectors, IoT devices, log aggregators

Users without an explicit permission mode default to readwrite, maintaining backward compatibility.

Supported Protocols

Permission control applies to all data access protocols.

• Read operations include SQL queries (MySQL/PostgreSQL), PromQL, Prometheus Remote Read, and Log Query.
• Write operations include SQL INSERT/DELETE, Prometheus Remote Write, InfluxDB Line Protocol, OpenTelemetry (OTLP), OpenTSDB, and log writes.

Configuration File Format

User credentials live in a text file (we recommend using .properties extension), one user per line.

Basic Format

The simplest form: username and password separated by =:

admin=admin_password
alice=alice_password

Both users get the default readwrite permission.

Adding Permission Modes

Append the permission mode after the username with a colon:

username:permission_mode=password

Permission modes are case-insensitive and support multiple formats:

Permission	Supported Formats
Read-Write	rw, readwrite, read_write
Read-Only	ro, readonly, read_only
Write-Only	wo, writeonly, write_only

A complete example:

# Admin account
admin:readwrite=admin_secret

# Dashboard accounts - read only
grafana:readonly=grafana_pwd
dashboard:ro=dashboard_pwd

# Collector accounts - write only
telegraf:writeonly=telegraf_pwd
collector:wo=collector_pwd

# Legacy format - defaults to readwrite
legacy_user=legacy_pwd

The file supports # comments, blank lines (ignored), and special characters in passwords (e.g., p@ssw0rd!123).

Starting the Server

Standalone Mode

Use --user-provider to specify the user file:

./greptime standalone start \
    --user-provider=static_user_provider:file:/path/to/users.properties

💡 Tips:

1. The file path must be an absolute path, or a relative path from the directory where the startup command is executed.
2. In Docker environments, make sure to mount the file or directory containing users.properties into the container.

For quick testing, configure users directly on the command line (security risk, use only for testing):

./greptime standalone start \
    --user-provider=static_user_provider:cmd:admin:rw=admin_pwd,grafana:ro=grafana_pwd

After startup, credentials are loaded into memory. Connect with the appropriate username and password:

# MySQL protocol
mysql -h 127.0.0.1 -P 4002 -u grafana -pgrafana_pwd

# PostgreSQL protocol
psql -h 127.0.0.1 -p 4003 -U grafana -W

Permission Verification

A read-only user trying to write via Prometheus Remote Write gets an error:

# Prometheus config using grafana (readonly) account
remote_write:
  - url: http://localhost:4000/v1/prometheus/write?db=public
    basic_auth:
      username: grafana
      password: grafana_pwd

# Prometheus logs the error
err="server returned HTTP status 403 Forbidden: {\"error\":\"User is not authorized to perform this action\"}"

Write-only users are rejected when querying:

-- Logged in as telegraf (writeonly)
mysql> SELECT * FROM metrics;
ERROR 1045 (28000): User is not authorized to perform this action

Dynamic User Reloading

With static_user_provider, user files load once at startup—runtime changes won't take effect. In production, you often need to add or remove users without restarting the service.

watch_file_user_provider monitors file changes and reloads automatically:

./greptime standalone start \
    --user-provider=watch_file_user_provider:/path/to/users.properties

Key features:

• Same file format as static_user_provider
• Reloads within seconds after detecting changes
• Keeps the last valid config if the new file has errors
• Supports hot adding, removing, and modifying users

This works well for granting temporary debug access, rotating service account passwords, or any scenario where access control changes frequently.

Kubernetes Deployment

With Helm Chart, configure authentication in values.yaml:

auth:
  enabled: true
  users:
    - username: admin
      password: admin_secret
      permission: readwrite
    - username: grafana
      password: grafana_pwd
      permission: readonly
    - username: telegraf
      password: telegraf_pwd
      permission: writeonly

See the Helm Chart documentation for more details.

💡 Tip: Please use the latest version of GreptimeDB Helm Chart.

Common Scenarios

Here are a few typical permission setups.

Monitoring Data Collection

Prometheus, Telegraf, and OpenTelemetry Collector only need write access. Write-only accounts limit damage if credentials leak—attackers can't read historical data:

prometheus:writeonly=prom_secret_2024
telegraf:wo=tele_secret_2024
otel:wo=otel_secret_2024

Dashboards and Reporting

Grafana, Superset, and custom reporting systems only need read access. Read-only accounts prevent accidental data deletion:

grafana:readonly=grafana_pwd
superset:ro=superset_pwd
report_system:ro=report_pwd

Development and Production Isolation

Dev accounts shouldn't have write access to production:

prod_collector:writeonly=prod_write_secret
prod_dashboard:readonly=prod_read_secret
dev_alice:readonly=alice_dev_pwd
dev_bob:readonly=bob_dev_pwd

Multi-Tenant Isolation

Combined with database-level isolation, different teams use different accounts:

team_a_writer:writeonly=team_a_write
team_a_reader:readonly=team_a_read
team_b_writer:writeonly=team_b_write
team_b_reader:readonly=team_b_read

Note: Current permission control is global—no table-level or database-level authorization. For finer isolation, consider separate GreptimeDB instances or GreptimeCloud's multi-tenancy.

Security Recommendations

1. Follow least privilege. Give each service account only what it needs. Use writeonly for collectors, readonly for dashboards, readwrite only for admin tasks.

2. Rotate passwords regularly. watch_file_user_provider lets you update passwords without downtime.

3. Protect credential files. Set strict permissions (e.g., chmod 600) to prevent unauthorized access.

4. Use strong passwords. Generate random passwords with openssl rand -base64 32.

5. Monitor authentication failures. Watch logs to catch brute-force attempts early.

Quick Start

Two steps to get started:

# 1. Create user file
cat > users.properties << EOF
admin:rw=admin_pwd
grafana:ro=grafana_pwd
collector:wo=collector_pwd
EOF

# 2. Start the server
./greptime standalone start --user-provider=watch_file_user_provider:./users.properties

Further Reading:

• Static User Provider Documentation
• Kubernetes Deployment Guide
• GreptimeDB 1.0 Release Notes