TLS In Transit

This topic describes how to enable unified TLS for FE, BE, and internal service-to-service communication, and how certificate-based authentication and certificate rotation work.

Scope

enable_tls is the recommended entry point for transport encryption. It covers more links than the legacy single-protocol options such as enable_https and enable_ssl, and it uses a single certificate management model.

Component	Protocols covered by unified TLS
FE	http, mysql, thrift, brpc, arrowflight, bdbje
BE	http, thrift, brpc, arrowflight

The legacy options still exist, but they are better suited for compatibility scenarios where only one protocol needs TLS.

Certificate requirements

Unified TLS uses a server certificate, a private key, and a CA certificate. PEM files are recommended. Make sure that:

• the certificate SAN matches the domain name or IP address used by clients;
• internal client certificates are issued by a trusted CA if mutual TLS is enabled;
• the private key files are readable only by the Doris runtime user.

Quick start

FE configuration

Edit conf/fe.conf:

enable_tls = true
tls_certificate_path = /path/to/server.crt
tls_private_key_path = /path/to/server.key
tls_ca_certificate_path = /path/to/ca.crt
tls_verify_mode = verify_peer
tls_cert_refresh_interval_seconds = 3600

If the private key is encrypted, also configure:

tls_private_key_password = your_private_key_password

BE configuration

Edit conf/be.conf:

enable_tls = true
tls_certificate_path = /path/to/server.crt
tls_private_key_path = /path/to/server.key
tls_ca_certificate_path = /path/to/ca.crt
tls_verify_mode = verify_peer
tls_cert_refresh_interval_seconds = 3600

Restart FE and BE after changing the configuration.

Endpoints and ports

Unified TLS does not use FE ports in the same way as the legacy enable_https path:

• when unified TLS protects FE HTTP, HTTPS is served directly on http_port, which is 8030 by default;
• when unified TLS protects FE MySQL, it still uses query_port, which is 9030 by default;
• https_port is primarily for the legacy enable_https path and should not be treated as the main access port for unified TLS.

In practice, the FE HTTP entry point for unified TLS is:

https://fe.example.com:8030

not https://fe.example.com:8050.

Key parameters

Parameters shared by FE and BE

Parameter	Default	Description
enable_tls	false	Enables unified TLS.
tls_verify_mode	verify_peer	Certificate verification mode.
tls_certificate_path	empty	Certificate file used by both server and client roles.
tls_private_key_path	empty	Private key path.
tls_ca_certificate_path	empty	CA certificate path.
tls_cert_refresh_interval_seconds	3600	Certificate polling interval in seconds.
tls_excluded_protocols	empty	Comma-separated list of protocols excluded from TLS.
tls_peer_cert_required_san_dns	empty	Per-protocol DNS SAN allowlist for peer certificates.

FE-only parameters

Parameter	Default	Description
tls_private_key_password	empty	Password for an encrypted private key file.
tls_cert_based_auth_ignore_password	false	Allows passwordless login after successful certificate verification for users configured with REQUIRE SAN.

tls_verify_mode values

Value	Description
verify_none	Disables certificate verification. Use only in test environments.
verify_peer	Verifies peer certificates but does not require every peer to present one.
verify_fail_if_no_peer_cert	Requires every peer to present a CA-verifiable certificate. Use this for mTLS.

Excluding specific protocols

If only part of the traffic should use TLS, exclude protocols explicitly:

tls_excluded_protocols = arrowflight

On FE, valid protocol names are thrift,mysql,http,brpc,arrowflight,bdbje. On BE, valid protocol names are thrift,http,brpc,arrowflight.

Mutual TLS

To enforce mutual authentication, set:

tls_verify_mode = verify_fail_if_no_peer_cert
tls_ca_certificate_path = /path/to/ca.crt

Then the client must present a valid certificate and key. Example for MySQL client connections:

mysql -h fe.example.com -P 9030 -uroot \
  --ssl-mode=VERIFY_CA \
  --ssl-ca=/path/to/ca.crt \
  --ssl-cert=/path/to/client.crt \
  --ssl-key=/path/to/client.key

Example for HTTPS Stream Load:

curl --location-trusted -u user:password \
  --cacert /path/to/ca.crt \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  -H "label:tls-demo" \
  -T data.csv \
  https://fe.example.com:8030/api/db/table/_stream_load

If you only want to verify one-way TLS before enabling strict client certificate checks, you can first test:

curl -I --cacert /path/to/ca.crt \
  https://fe.example.com:8030/

Certificate-based user authentication

User-level certificate requirements support only:

• REQUIRE SAN '...'
• REQUIRE NONE

ISSUER, SUBJECT, CIPHER, and compound TLS requirements are not supported.

Configure a user requirement

CREATE USER 'etl_user'@'%' IDENTIFIED BY 'Password@123'
REQUIRE SAN 'DNS:client.example.com,URI:spiffe://etl,EMAIL:etl@example.com';

ALTER USER 'etl_user'@'%' REQUIRE SAN 'DNS:client.example.com';

ALTER USER 'etl_user'@'%' REQUIRE NONE;

SAN validation is performed entry by entry. In practice, the safest approach is to copy the SAN entries directly from the certificate to avoid failures caused by missing entries or case differences.

Passwordless certificate login

By default, a successful certificate check does not replace password verification. To allow passwordless login for users who have REQUIRE SAN, set this on FE:

tls_cert_based_auth_ignore_password = true

This applies only when the user has a TLS certificate requirement configured and the certificate check succeeds.

Peer certificate DNS SAN allowlist

tls_peer_cert_required_san_dns restricts the DNS SAN values accepted from peer certificates. Only thrift and brpc are supported. The format is:

tls_peer_cert_required_san_dns = brpc=be-1.internal,be-2.internal;thrift=fe-1.internal,fe-2.internal

This feature works only when all of the following are true:

• enable_tls = true
• the protocol is not excluded by tls_excluded_protocols
• tls_verify_mode = verify_fail_if_no_peer_cert
• tls_ca_certificate_path is configured

Certificate hot reload

Unified TLS polls the configured certificate files and reloads them automatically according to tls_cert_refresh_interval_seconds.

When replacing both a private key and a certificate, use this order:

1. Replace the private key first.
2. Replace the certificate immediately after that.
3. Keep the certificate chain and key in sync.

This reduces the chance of the reload loop observing a mismatched key and certificate pair.

Validation

Validate HTTPS

openssl s_client -connect fe.example.com:8030 -servername fe.example.com -CAfile /path/to/ca.crt

Validate MySQL TLS

mysql -h fe.example.com -P 9030 -uroot --ssl-mode=REQUIRED

If mutual TLS is enabled, also provide --ssl-ca, --ssl-cert, and --ssl-key.

Recommended rollout

For a first-time unified TLS deployment, use this order:

1. prepare the PEM certificate, private key, and CA files for FE and BE;
2. configure enable_tls, the certificate paths, and tls_verify_mode in both fe.conf and be.conf;
3. restart FE and BE;
4. verify HTTPS on FE port 8030 with openssl s_client or curl --cacert;
5. verify MySQL TLS on port 9030 with mysql --ssl-mode=REQUIRED;
6. switch to verify_fail_if_no_peer_cert only after client certificates are ready;
7. add CREATE USER ... REQUIRE SAN ... only when you are ready to enforce user-level certificate requirements.

Relationship to legacy options

You can still use enable_https and the Java keystore settings if you only want HTTPS on the FE HTTP endpoint, or enable_ssl and related MySQL settings if you only want TLS on the MySQL port.

For new deployments or any environment that needs end-to-end transport encryption across multiple Doris protocols, enable_tls is the preferred configuration model.