Support Bundles

Support bundle collection and upload — pre-share PII warning, per-file redaction status, 180 MB cap, presigned S3 upload flow, and decision tree for when to collect.

The support-bundle subcommand collects an agent diagnostic archive intended for sharing with LinuxGuard support staff. This page documents the bundle's contents, the redaction status of each file, the 180 MB pre-compression cap with oldest-first trimming, and the presigned S3 upload flow.

⚠ Pre-share PII Warning: Support bundles ship agent.log and rotated segments verbatim up to 180 MB. Only attribute-key-format secrets (API keys, enrollment tokens) are redacted. Hostnames, IPs, usernames, file paths, and command-line arguments are NOT redacted. Review the bundle contents before sharing externally.

Synopsis

A support bundle is a .tar.zst archive containing:

• The current agent.log plus any rotated .gz segments that fit within the cap

• A system.json host snapshot (kernel, eBPF probe status, agent version, host arch)

• A config.redacted.json view of the agent config with secrets replaced by SHA256 fingerprints

• A BUNDLE-MANIFEST.json listing every file in the archive, what was trimmed, and the redaction summary

Bundles are produced via linuxguard-agent support-bundle collect and shared with LinuxGuard support via linuxguard-agent support-bundle upload <bundle-file> (presigned S3 upload) or via the console Support Bundles UI.

Per-file Redaction Status

The table below lists every file the agent places in the bundle, what is redacted, and what is NOT redacted.

File	What's redacted	What's NOT redacted
agent.log	Attribute-key regex only — api_key, enroll_token, *_token, *_secret keys replaced with [REDACTED] per the agent's log redactor	Hostnames, IPs, usernames, file paths, process command-line arguments, free-text message bodies. PII NOT additionally redacted.
agent.log.<N>.gz	Same as agent.log — attribute-key regex only	Same as agent.log — PII not additionally redacted
system.json	Nothing — system metadata only (kernel version, BPF probe status, agent version, host architecture)	Kernel version, host arch, agent version, eBPF probe status, recent error count
config.redacted.json	Secrets replaced with <redacted:<sha256(value)[:8 hex]>> fingerprints; TLS material replaced with <redacted:tls>. Explicit struct mapping in the bundle redactor — api_key, enroll_token, encryption_key, *_token, *_secret, *_password, *_key, *_cert, *_cert_pem, *_key_pem, tls_cert, tls_key_pem	Server ID, Tenant ID, base URL, mode, environment, tags, feature flags, cert/key file paths (paths only — content stays on disk)
BUNDLE-MANIFEST.json	Nothing — manifest is metadata only	Bundle version, agent version, generated-at, trigger, contents list, trimmed segments, redaction summary

Verifying Redaction Rules From the Bundle

Every bundle includes a redaction_summary block in BUNDLE-MANIFEST.json so operators can verify the rules without re-reading documentation:

{
  "redacted_keys": ["api_key", "enroll_token", "encryption_key"],
  "glob_patterns": ["*_token", "*_secret", "*_password", "*_key"],
  "tls_patterns": ["*_cert", "*_cert_pem", "*_key_pem", "tls_cert", "tls_key_pem"],
  "format": "<redacted:<sha256(value)[:8]>>",
  "tls_format": "<redacted:tls>",
  "strategy": "explicit_struct_mapping",
  "reflection_used": false
}

The strategy: explicit_struct_mapping field is load-bearing — the config redaction uses a hand-maintained struct mapping, NOT reflection. Adding a new secret field to the agent config requires a code change in the bundle redaction layer, not a documentation update.

Collect Workflow

Default Behavior

sudo linuxguard-agent support-bundle collect

The default behavior:

• Writes the bundle to /var/lib/linuxguard/support/<unix_timestamp>.tar.zst

• Caps the included agent.log + rotated .gz segments at 180 MB pre-compression

• Applies oldest-first trimming: when the cap is reached, the oldest rotated segment is dropped; current agent.log is always included

• Emits the bundle's SHA256 hex digest and size in bytes to stderr

• Stores the trimmed-segment list inside BUNDLE-MANIFEST.json for operator visibility

Custom Output Path

sudo linuxguard-agent support-bundle collect --out /tmp/my-bundle.tar.zst

The output file is opened with O_EXCL to mitigate symlink attacks. If the destination already exists, the command fails with a clear error rather than overwriting.

What's Collected

Item	Behavior
Current agent.log	Always included; non-fatal if absent (fresh agent)
Rotated agent.log.<N>.gz	Newest first; trimmed to fit the 180 MB cap; trimmed list recorded in manifest
system.json	Always included; required entry
config.redacted.json	Always included; required entry
BUNDLE-MANIFEST.json	Always included last; required entry

The cap counts the current agent.log size against the budget before deciding which rotated segments fit. When the cap budget is exhausted, the remaining rotated segments are dropped and their base names are recorded in the manifest's trimmed_segments array (never null; empty array if no trimming occurred).

Sample Output

support-bundle: wrote /var/lib/linuxguard/support/1735660800.tar.zst
support-bundle: sha256=a1b2c3d4...e5f6 size=42184326
support-bundle: trimmed_segments=2

Upload Workflow

The upload subcommand pushes a previously-collected bundle to LinuxGuard support via a three-step presigned URL flow.

sudo linuxguard-agent support-bundle upload /var/lib/linuxguard/support/1735660800.tar.zst

Flow

1. Stat + SHA256 — the CLI re-computes the SHA256 of the bundle on disk and stats its size.

2. Extract manifest — the CLI reads BUNDLE-MANIFEST.json from the archive to recover the trimmed_segments and agent_version fields (non-fatal if the manifest is missing).

3. Request presigned URL — the agent POSTs to /upload-url with bundle metadata (SHA256, size, kernel, distro, agent version, eBPF status, recent error count). The backend returns a presigned S3 PUT URL.

4. PUT to S3 — the agent uploads the bundle bytes via the presigned URL using a raw HTTP request (no Authorization header — auth is in the URL signature).

5. Register — the agent POSTs to /register with the upload result so the backend records the bundle in its database and exposes it to support engineers.

Sample Output

uploaded bundle_id=bnd_abc123 object_key=tenants/<tid>/bundles/1735660800.tar.zst uploaded_at=2026-05-31T12:00:00Z

On upload failure, the local bundle file is retained — the upload command does not delete it. Operators can re-run the upload command against the same file once connectivity is restored.

Authentication

The /upload-url and /register endpoints require the agent's standard API key authentication. The presigned PUT to S3 carries its own URL-encoded signature and does NOT require the API key.

Data Residency

The S3 bucket is provisioned in the LinuxGuard tenant's primary region per the tenant's data-residency configuration. Bundles are retained per the tenant's support data retention policy. Contact [email protected] for details on bucket location and retention for your tenant.

Console Support-Bundles UI

The LinuxGuard console exposes a Support Bundles section under the host detail view where operators can:

• List uploaded bundles for the host (by bundle_id, upload timestamp, size, agent version)

• View the bundle's manifest inline (contents list, trimmed segments, redaction summary)

• Download the raw .tar.zst archive for offline inspection

• See the audit trail of upload and access events

The console-driven push path also collects + uploads bundles, with trigger=console_push and a case_id populated from the support case context.

When to Collect

Use the decision tree below to determine whether a support bundle is needed.

Is the agent running and reporting to the console?
├── Yes — does the console show the host as Healthy?
│   ├── Yes — symptom is intermittent or correlation-only
│   │   └── Collect bundle if support staff requests; otherwise no.
│   └── No — agent reports Degraded or DegradedNoEBPFArch
│       └── Collect bundle. Include the time window of the degradation.
└── No — agent is not reporting
    ├── Agent process is running locally
    │   └── Collect bundle. Check for connectivity errors in agent.log.
    └── Agent process is not running
        └── Try to start it first; if it crashes, collect bundle from any
            available agent.log before re-installing.

Pre-share Checklist

Before sharing a collected bundle externally:

1. Re-read the redaction status table above. Confirm you understand what is NOT redacted.

2. Inspect agent.log content within the bundle for PII categories your data-handling policy regulates.

3. Inspect config.redacted.json to confirm secret fingerprints are present where expected.

4. Decide on the share path: direct upload to LinuxGuard support is safest because access is restricted to the LinuxGuard support team and audited. Email forwarding to third parties is the highest-risk path.

5. Record the bundle_id and SHA256 so you can audit which bundle was shared with which party.

Cross-References

• Log Management — Live-log redaction scope, central log collection patterns.

• Log Level and Rotation — Rotation defaults and operator knobs.

---

Related: Log Management | Log Level and Rotation | Troubleshooting