Monedula
monedula-sim-link docs menu

Connect to a secured cluster

Run monedula-sim-link connect against a Kafka cluster that needs TLS, SASL or mutual TLS, and keep the password out of your shell history.

How-to guides 1 of 6

3 min read

Updated 16 October 2026

Markdown

On this page

The cluster_to_url tool of the MCP server takes the same settings as the connect flags on this page.

Before you start

  • monedula-sim-link installed, as described in the install section.
  • The bootstrap addresses of the listener you connect to, and the authentication method it expects.
  • For a private certificate authority, the CA certificate as a PEM file. Client certificates and keys are PEM files too.
  • A principal that may describe the cluster, its topics, its consumer groups and its topic configs. connect needs no write permission (the read-only guarantee lists its requests). Only --producers needs more: READ on each selected topic (step 4).

Steps

1. Choose the setup that matches your listener

export MONEDULA_SIM_LINK_PASSWORD='...'
monedula-sim-link connect \
  --brokers broker1.example.com:9093,broker2.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer
monedula-sim-link connect --brokers broker:9093 \
  --tls --ca-cert ca.pem --client-cert client.pem --client-key client.key

What each flag does:

  • --brokers lists the bootstrap brokers as host:port, separated by commas. It is the only required flag.
  • --tls connects over TLS and verifies the brokers against the system trust store. --ca-cert, --client-cert and --client-key each imply --tls. The connection needs TLS 1.2 or newer.
  • --ca-cert adds your CA to the system trust pool; it does not replace the pool.
  • --client-cert and --client-key are the client keypair for mutual TLS.
  • --sasl-mechanism is plain, scram-sha-256 or scram-sha-512, and it requires --username.

2. Keep the password out of your shell history

The password comes from --password if you give it, otherwise from the environment variable MONEDULA_SIM_LINK_PASSWORD. Prefer the variable, as the SCRAM example above does: a flag value lands in your shell history and in the process list.

3. Raise the timeout for a slow or distant cluster

--timeout is the overall time connect has for the whole snapshot. The default is 15 seconds. A cluster behind a slow link, or one with many partitions, can need more:

monedula-sim-link connect --brokers broker1.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer \
  --timeout 60s

4. Allow reading the topics for producers (optional)

--producers adds the idempotent and transactional producers that wrote lately to the link. It sends a DescribeProducers request, which needs READ on each selected topic, where the other requests on this page need only describe permissions (DESCRIBE_CONFIGS for the topic configs):

monedula-sim-link connect --brokers broker1.example.com:9093 \
  --tls --ca-cert ./cluster-ca.pem \
  --sasl-mechanism scram-sha-512 --username viewer \
  --topics orders,payments --producers

Without the flag the request is never sent, so a principal that cannot read the topics keeps working. With the flag and no READ, connect still prints a link: it warns that the request was refused with TOPIC_AUTHORIZATION_FAILED, names the topics, and leaves out the producers that wrote only to them. READ is also the permission that lets a client fetch records. connect never sends a fetch, but grant READ only on the topics you pass. The mapping reference says what the flag shows and what it cannot see.

Check it worked

connect exits 0 and prints the link on standard output. Add --dry-run to see the broker table first: every real broker id should appear in it, each next to its broker-N name.

If it stops with an error instead, the message names the cause. These come from the flags on this page:

  • --ca-cert holds no usable PEM certificates, or the file cannot be read.
  • --client-cert and --client-key must be given together.
  • --sasl-mechanism requires --username.
  • unsupported --sasl-mechanism, which lists the three valid values.

The command exits 1 for these, and 2 when the flags themselves do not parse, --brokers is missing, or --producers-window is not positive. A producers read that fails is not an error: the warning line reads warning: --producers: ..., and the link is printed without those producers.