Generate a diagnostics bundle

A diagnostics bundle is one .zip file describing your Ringleader install, made to be sent to us as-is. It gathers everything you would otherwise collect by hand (what rl troubleshoot prints, the log, and the state of each workstation) and it is built to contain no login tokens, secret values or private keys.

It is the first thing we ask for when you get in touch about a problem.

Make one

From the desktop app

The Ringleader desktop app, on macOS and on Windows, has a Troubleshoot page with a Generate bundle button.

Open the app’s window and choose Troubleshoot.
If you can, raise the daemon’s log level and reproduce the problem first, so the log has the detail we need. To raise it, run rl daemon log-level debug in a terminal.
Click Generate bundle.

The app writes ringleader-diagnostics.zip into your Ringleader data directory, shows its path on the page, and opens it. Under the path it shows the notes the capture printed, such as the time range the daemon log covers. Attach the file to an email or a chat. If some items could not be collected, the bundle is still written and opened, and it notes what was skipped.

The page also shows the command it runs, with a Copy button, if you would rather run it yourself.

From the command line

rl troubleshoot --all --diagnostics

The desktop button runs this command with its own output path. Run from a terminal, it writes ./ringleader-diagnostics-<timestamp>.zip in the current directory and prints the absolute path it wrote.

Command	What it captures
`rl troubleshoot --diagnostics`	Local diagnostics only (no workstation info).
`rl troubleshoot --all --diagnostics`	Local diagnostics plus every workstation.
`rl troubleshoot my-box --diagnostics`	Local diagnostics plus just `my-box`.
`rl troubleshoot --diagnostics=out.zip`	Write to an explicit path instead of the default.
`rl troubleshoot --diagnostics --log-since=6h`	Widen the bundled daemon log to reach at least 6 hours back.

--all connects to every workstation over SSH, so with many workstations it takes a little longer.

Check the log reaches back far enough

Only the most recent part of the log goes into the bundle, so if the problem happened a while ago, the bundled log may start after it. The time range it covers is printed when the zip is written and recorded in diagnostics/COLLECTION.md. If it starts too late, run the command again with --log-since=<duration>, for example --log-since=6h, and it reaches further back.

The covered-range line can end with one of these, and each tells you what to do:

INCOMPLETE: records before <time> are still on disk but NOT in this bundle: older records exist on your machine. Capture again with --log-since=<duration> to include them.
INCOMPLETE: --log-since=<duration> is NOT covered: the capture reached its size limit before it reached that far back, so the bundle starts later than you asked.
records before <time> are not on disk: the log on your machine starts at that time, because the daemon could not keep the records before it. No flag brings them back.
INCOMPLETE: some records are missing before <time>: the daemon could not write or keep some records, for example on a full disk, so the log has a gap inside the range.

The desktop app highlights a note that says INCOMPLETE.

What’s inside

README.md                     what this bundle is, how it was made, and the privacy guarantee
diagnostics/
    host.md                   OS, version, virtualization, CPU/cores, RAM, disk usage, architecture, timezone, network interfaces
    daemon.md                 the local daemon: running? since when? version, PID, heartbeat, why it cannot write its log (if it cannot), on Windows whether it runs as an administrator, last log line, restarts in the log tail
    origins.md                per origin: name, URL, user, backend version, token validity (no tokens)
    localbindings.yaml        every device-local LocalBinding: what this device forwards, and what it is actually holding
    seeded-bindings.md        which workstations the daemon has already auto-seeded a binding for
    cloudidentities.yaml      every CloudIdentity in the namespaces the captured workstations live in, including the fact that a namespace has none
    versions.md               the rl CLI version and build
    daemon.log                the daemon log, trimmed to its most recent tail (across rotated backups)
    COLLECTION.md             every item the bundle tried to collect: OK / FAILED / SKIPPED with the reason, and the daemon log's covered time range and any gap in it
workstations/
    <namespace>__<name>/
        troubleshoot.txt      the `rl troubleshoot <name>` output (controller view + egress + forwarding + probes + timeline)
        workstation.yaml      the Workstation object (spec + status + conditions)
        config-<name>.yaml    one per WorkstationConfig this workstation's status says it applied
        report.json           the raw in-VM provisioning ledger, when one was captured
        vz-host-logs.txt      a vz workstation's helper, network and console logs, with the previous run's copies, when it is on vz
        hcs-host-logs.txt     an hcs workstation's network log and its console output from the current and previous start, when it is on hcs

The workstations/ folder is present only when you captured with --all or named a workstation. localbindings.yaml and cloudidentities.yaml are absent when the control-plane store could not be opened; seeded-bindings.md is always present. A *.error file next to an expected entry means that item failed to collect; its content is the error.

A bundle is written even when parts of it fail. A workstation that is powered off, or a check that cannot run, does not stop the rest. Every failure is recorded three times over: on your terminal, in diagnostics/COLLECTION.md inside the zip, and in the command’s exit code. A partial bundle is still useful to us, so send it.

That also makes it the command for when everything is broken: if Ringleader itself cannot start on your machine, the bundle still captures the machine, the daemon’s state and, most importantly, the log, and records why the rest is missing.

How to read one

If you are the one reading a bundle, start at the top:

diagnostics/COLLECTION.md: what was and was not captured.
diagnostics/host.md and diagnostics/daemon.md: is the environment sane and is the daemon alive?
diagnostics/origins.md: is the user logged in, and is the token still valid?
workstations/<…>/troubleshoot.txt: the per-workstation controller view, egress checks, device-local forwarding, live probes, and provisioning timeline.
For a “my ports are not forwarded” report: diagnostics/localbindings.yaml (is there a binding at all, and what is its status?), then diagnostics/seeded-bindings.md (if there is none, was one ever seeded?).
For a “my configuration did not apply” report: workstations/<…>/config-<name>.yaml, each configuration the workstation says it applied, and, for a cloud box that never came up, diagnostics/cloudidentities.yaml.

Privacy

The bundle is built to be safe to share:

No credentials. It carries no login tokens, secret values or private keys. Where it reports on your logins, it says only whether each is still valid and until when.
The log is trimmed and redacted. Only the most recent part is included, and anything in it that looks like a token or a private key is blanked out.
Secrets stay as references. A workstation’s configuration may refer to a secret by name, as ${secret:NAME}. The bundle contains the name, never the value.

The redaction is a second line of defense. The first is that Ringleader never writes a credential into the bundle to begin with. Even so, if your environment is known to log sensitive data, glance through diagnostics/daemon.log before you send it.