Troubleshooting

Diagnose a Ringleader install: local status, a stuck workstation, the daemon logs, and the sendable diagnostics bundle you share with the Ringleader team.

When something is wrong, whether Ringleader will not start on your machine, a workstation never reaches Ready, or rl shell cannot connect, there are four places to look, and one command that packages all of them up to send to us.

Work from the outside in:

  1. Local status: is the daemon alive, are you logged in, is the host sane?
  2. A specific workstation: what does the control plane think, and what do live probes on the workstation say?
  3. The logs: raise the detail, reproduce the problem, read what the daemon recorded.
  4. The diagnostics bundle: capture everything above as a single, secret-free .zip to share with the Ringleader team.

Local status

Run rl troubleshoot with no arguments to print a snapshot of this machine:

rl troubleshoot

It reads only what is already on this machine, so it works offline and touches no credentials. It reports:

  • Version. The rl CLI version and build.
  • Host / system. OS, kernel, architecture, CPU/RAM, virtualization, and disk usage for the data directory and /.
  • Daemon. Whether the local daemon is running, its PID, version, uptime, and last log line. If the daemon is a different build from your CLI, it says so and tells you to run rl daemon restart.
  • SSH config include. Whether your ~/.ssh/config pulls in the Ringleader-managed config, so plain ssh <workstation> resolves. If it is missing or mis-ordered it points you at rl ssh-config install.
  • Origins / auth. Each Ringleader server (origin) you are logged in to, its URL and your user there, its version, and whether your login is still valid. It never prints the login token itself.

This is the fastest first look, and it still works when Ringleader’s own database on this machine cannot be opened: the parts that do not need it are printed, and the part that does is named as missing rather than left out.

A stuck workstation

Point rl troubleshoot at a workstation to diagnose it:

rl troubleshoot my-box

You get these views, in this order:

  • Controller view. What Ringleader believes about the workstation: its phase, its conditions, and what happened on the last pass over it.
  • Egress. This view appears only for a workstation with an egress policy. It shows the rule set Ringleader built for the workstation and the destinations it permits. It also names any destination the rule set cannot hold. If an edge VM on this machine serves the workstation, it names that too. A live reachability check dials some permitted destinations and, where it can, one the policy should block.
  • Device-local port forwarding. Which port-forwarding rule (a LocalBinding) on this machine points at the workstation, and what it forwards. When none does, the section says so, because “nothing is forwarding” is usually the answer to “why can’t I reach my port”.
  • Live probes. Ringleader connects to the workstation and checks what is actually there: the OS, the Ringleader agent, Docker, disk space, your login user.
  • Provisioning timeline. The record the agent inside the workstation keeps of every step it ran to set the workstation up, and whether each one succeeded.

When a workstation has done a lot, narrow the timeline:

rl troubleshoot my-box --failed              # only steps that failed
rl troubleshoot my-box --kind devtool --since 1h
rl troubleshoot my-box --reconcile latest    # only the most recent configuration pass
rl troubleshoot my-box --report-only         # just the in-VM ledger
rl troubleshoot my-box --json                # machine-readable ledger

The full flag list is on the workstation lifecycle & access page.

Logs and verbosity

The Ringleader daemon keeps a log on your machine: daemon.log in your data directory (~/.ringleader unless you set RINGLEADER_HOME). When you need us to look at a problem, do three things, in this order:

  1. Raise the daemon’s log level so it records more detail: rl daemon log-level debug.
  2. Reproduce the problem.
  3. Capture the log, on its own or inside a diagnostics bundle (rl troubleshoot --all --diagnostics).

Raise the level first, because at the default level the line that explains a failure may never be written. The running daemon picks up the new level within a few seconds and keeps it across restarts. Run rl daemon log-level info to go back to the default. The rl daemon page has the details.

The desktop app’s Troubleshoot pane shows the daemon log and can generate the bundle for you. rl logs <workstation> shows a different log: the one the Ringleader agent keeps inside a workstation.

The diagnostics bundle

When you want to send us the whole picture, generate a diagnostics bundle: one .zip containing everything above, for every workstation, with no tokens, secrets or private keys in it. It is the one file we ask for.

rl troubleshoot --all --diagnostics

Generate a diagnostics bundle says exactly what is inside, how to make one from the desktop app, and what is kept out of it.

Getting help

If all of that leaves you stuck, generate a bundle and reach out. Include the .zip so we can see your install without a back-and-forth. Start at ringleader.dev.