Skip to main content
syscall record loads the eBPF programs, attaches seven tracepoints, drops privilege, creates a session, and runs one target command.

Before recording

  1. Check the host with syscall info.
  2. Confirm the target and database paths are authorized and writable by the invoking user.
  3. Decide whether target arguments should be persisted.
  4. Choose target-tree unless host-wide activity is explicitly required.
Recording requires effective UID 0, CAP_BPF + CAP_PERFMON, or CAP_SYS_ADMIN on older kernels. SYSCALL never invokes sudo or prompts for a password.
When started through sudo, the recorder loads and attaches as root, then becomes the invoking user before creating the database or spawning the target.

Command shape

The -- separator is required. Target flags are passed to the target, not parsed as recorder flags.
The target is spawned directly, not through a shell. Use an explicit shell if shell syntax is required:

Options

The database path can also be set with SYSCALL_DB.

Scope

The kernel tracepoints are system-wide in both modes. Scope is userspace admission, not a kernel security boundary. Out-of-scope events are counted as filtered. They are not collection loss.
--scope system can collect unrelated host activity and produce a much larger database. Use it only when host-wide observation is intended and authorized.

Redaction

Target arguments are persisted by default:
Redact them:
--redact-args replaces all arguments with "<redacted>". The executable path is still stored. File paths and network destinations recorded by tracepoints are not redacted.

Session identity and database

A generated session ID is time- and randomness-based. Use --session-id when an external workflow requires a stable identifier. The default database is ~/.local/share/syscall/syscall.db. To keep an investigation isolated:
The directory must already exist and be writable by the invoking user. The recorder creates the database with mode 0600; the data directory is expected to be mode 0700. After sudo, the database, WAL sidecar, and target process are owned by the invoking user.

What happens during recording

  1. The request, scope, target, and session ID are validated.
  2. Privilege, BTF, tracefs, and unprivileged_bpf_disabled are inspected.
  3. The BPF skeleton is loaded and all seven programs are attached.
  4. Privilege is dropped to the invoking user.
  5. The session row is created.
  6. The target starts in its own process group.
  7. The root PID is registered with the scope tracker.
  8. Events are decoded, attributed, and written in batches.
  9. On exit or signal, the recorder drains, finalizes counters, and joins the writer.
The session row exists before the target starts. A normal error marks it failed. A hard crash leaves it recording, but committed rows remain inspectable.

Signals and exit codes

record mirrors the target when recording succeeds. On SIGINT or SIGTERM, the recorder stops accepting work, sends SIGTERM to the target process group, waits up to two seconds, sends SIGKILL if needed, drains for up to 500 ms, and finalizes the session as interrupted.

Detached descendants

The recorder follows the launched target tree while the target is alive. Descendants that detach and outlive the target are not followed after finalization. If long-running background processes are part of the investigation, keep the target alive for the required duration or record with an explicit wrapper that waits for them.

Failure behavior

Do not treat a failed or recording session as a clean capture. Inspect its counters before using it.

Confirm the result

Check:
  • Status and termination reason.
  • Persisted event count versus received, decoded, and attributed counts.
  • Ring-buffer loss, userspace drops, malformed samples, and persistence failures.
  • Filtered events if target-tree scope was used.
  • Unresolved identity or ancestry.
Then proceed to Investigate a session.