rustfs/docs/tls.md

TLS / mTLS configuration

RustFS supports TLS for serving HTTPS and for outbound gRPC connections (MNMD). It also supports optional client certificate authentication (mTLS) for outbound gRPC: if a client identity is configured, RustFS will present it; otherwise it will use server-authenticated TLS only.

Recommended tls/ directory layout

Place these files in a directory (default: ./tls, configurable via RUSTFS_TLS_PATH).

TLS_DIR/
  ca.crt              # PEM bundle of CA/root certificates to trust (recommended)
  public.crt          # optional extra root bundle (PEM)
  rustfs_cert.pem     # server leaf certificate (PEM) used by the RustFS server
  rustfs_key.pem      # server private key (PEM) used by the RustFS server

  # Optional: outbound mTLS client identity for MNMD
  client_cert.pem     # client certificate chain (PEM)
  client_key.pem      # client private key (PEM)

  # Optional: server-side mTLS (inbound client certificate verification)
  client_ca.crt       # PEM bundle of CA certificates to verify client certificates

Environment variables

Root trust

• RUSTFS_TLS_PATH (default: tls): TLS directory.
• RUSTFS_TRUST_SYSTEM_CA (default: false): When true, include the platform/system trust store as additional roots. When false, system roots are not used.
• RUSTFS_TRUST_LEAF_CERT_AS_CA (default: false): Compatibility switch. If true, RustFS will also load rustfs_cert.pem into the root store (treating leaf certificates as trusted roots). Prefer providing ca.crt instead.

Outbound mTLS identity

• RUSTFS_MTLS_CLIENT_CERT (default: ${RUSTFS_TLS_PATH}/client_cert.pem): path to PEM client cert/chain.
• RUSTFS_MTLS_CLIENT_KEY (default: ${RUSTFS_TLS_PATH}/client_key.pem): path to PEM private key.

If both files exist, RustFS enables outbound mTLS. If either is missing, RustFS proceeds with server-only TLS.

Server-side mTLS (inbound client certificate verification)

• RUSTFS_SERVER_MTLS_ENABLE (default: false): When true, the RustFS server requires clients to present valid certificates signed by a trusted CA for authentication.

When enabled, RustFS loads client CA certificates from:

1. ${RUSTFS_TLS_PATH}/client_ca.crt (preferred)
2. ${RUSTFS_TLS_PATH}/ca.crt (fallback if client_ca.crt does not exist)

Important: Server mTLS is disabled by default. When enabled but no valid CA bundle is found, RustFS will fail to start with a clear error message. This ensures that server mTLS cannot be accidentally enabled without proper client CA configuration.

Failure mode for HTTPS without roots

When connecting to an https:// MNMD address, RustFS requires at least one configured trusted root. If none are loaded (no ca.crt/public.crt and system roots disabled), RustFS fails fast with a clear error message.