operations-jail-inventory

FreeBSD jail estate inventory: jails, ZFS datasets, snapshots and listening sockets, and the disagreements between them

What it is for

FreeBSD jail estate inventory: what a host actually holds, and where its own records disagree with its disks.

operations_host_inventory answers what the hardware is. This crate answers what the software estate is: the jails, the ZFS datasets and snapshots beneath them, what is listening, and — the part no existing tool answered — which datasets belong to no jail.

What running it against a real host taught it

The first version of this crate, driven only by fixtures, reported 22 orphaned datasets on a live FreeBSD 13.2 host. One was real — a 7 GB dataset whose jail had not existed for years. Of the rest, five were the boot pool's own system datasets and fourteen held virtual machine disks, two of them belonging to running virtual machines. An earlier claim that the question was worth "roughly 110 GB" came from that bad reading and is false; the interesting finding is the other one, that most of a jail host's unexplained space is usually explained, and a tool that cannot say by what will recommend deleting a running machine.

That is why a reconciliation here reports three things and not one: what is wrong (Disagreement), what is claimed by something other than a jail (DatasetClaim), and what it could not classify at all (Reconciliation::unclassified). An empty orphan list must never mean both "nothing to reclaim" and "I could not read this host".

Why the parsing lives here and the running does not

Every reader in this crate takes text and returns data. Nothing here runs a command by itself; a CommandRunner is passed in, and its subprocess calls use strict argument vectors — never a shell string. That rule is inherited from operations-host-inventory deliberately: three separate failures in one session came from shell strings being re-split by an intermediate shell, including a ps -axo user=,rss=,command= that silently returned one column because = swallowed the rest of the argument as a header. Argument vectors make that class impossible.

Capabilities

crate root

FreeBSD jail estate inventory: what a host actually holds, and where its own records

EstateError

FreeBSD jail estate inventory: what a host actually holds, and where its own records

Result

FreeBSD jail estate inventory: what a host actually holds, and where its own records

datasets (other)

ZFS datasets and snapshots, as zfs list reports them.

Dataset

ZFS datasets and snapshots, as zfs list reports them.

Snapshot

ZFS datasets and snapshots, as zfs list reports them.

jails (other)

The jails a host is running, as jls reports them.

ConfiguredJails

The jails a host is running, as jls reports them.

Jail

The jails a host is running, as jls reports them.

Listener

What is listening, as sockstat reports it.

reconcile (other)

Where a host's records and its disks disagree — and, just as importantly, what it could

Claim

Where a host's records and its disks disagree — and, just as importantly, what it could

DatasetClaim

Where a host's records and its disks disagree — and, just as importantly, what it could

Disagreement

Where a host's records and its disks disagree — and, just as importantly, what it could

Estate

Where a host's records and its disks disagree — and, just as importantly, what it could

JailLayout

Where a host's records and its disks disagree — and, just as importantly, what it could

Reconciliation

Where a host's records and its disks disagree — and, just as importantly, what it could

testkit (other)

Fixtures captured from a real FreeBSD 13.2 jail host on 2026-09-11.

How to use it

From `examples/estate-report.rs`:

use std::{fs, process};

use operations_jail_inventory::{
    datasets, jails,
    reconcile::{self, Claim, Disagreement, Estate, JailLayout},
    strip_ansi, ConfiguredJails,
};

fn main() {
    let args: Vec<String> = std::env::args().skip(1).collect();
    let [jls_path, zfs_path, configured_path] = match args.as_slice() {
        [a, b, c] => [a, b, c],
        _ => {
            eprintln!("usage: estate-report <jls.txt> <zfs-list.txt> <configured.txt>");
            process::exit(2);
        }
    };

Module structure

operations_jail_inventory

• datasets
• jails
• listeners
• reconcile
• testkit

flowchart TD
  n_operations_jail_inventory["operations_jail_inventory"]
  n_operations_jail_inventory --> n_datasets["datasets"]
  n_operations_jail_inventory --> n_jails["jails"]
  n_operations_jail_inventory --> n_listeners["listeners"]
  n_operations_jail_inventory --> n_reconcile["reconcile"]
  n_operations_jail_inventory --> n_testkit["testkit"]

Public surface

`crate root`

`datasets`

`jails`

`listeners`

`reconcile`

`testkit`

Re-exports. Exported here, defined elsewhere.

Boundary

Depends on no other workspace tier.

Shares tier operations with 42 other crates: operations-approval-workflow, operations-assessments, operations-block-imaging, operations-boot-media, operations-browser-agent-worker, operations-camera-discovery, operations-camera-liveview, operations-camera-registry, … (42 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Dependencies

Runtime, in this workspace.

Runtime, from outside the workspace.

Development, from outside the workspace.

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["operations-jail-inventory"]
  SELF -->|runtime| n_operations_host_inventory["operations-host-inventory"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

Related capabilities

No workspace crate depends on this one.

Verification

Evidence by module. How often each public module is named by something executable.

What the tests establish, by name:

• a_configured_jail_with_no_dataset_is_reported — tests/estate.rs
• a_dataset_holding_a_vm_disk_is_claimed_not_orphaned — tests/estate.rs
• a_dataset_whose_jail_is_not_configured_is_an_orphan — tests/estate.rs
• a_dataset_with_no_mountpoint_is_read_as_having_none — tests/estate.rs
• a_host_using_another_layout_reports_unclassified_not_a_clean_estate — tests/estate.rs
• a_jail_with_no_address_reports_none_not_a_dash — tests/estate.rs
• a_leading_blank_line_does_not_turn_the_header_into_a_listener — tests/estate.rs
• a_refused_command_is_a_command_failure_not_an_empty_estate — tests/estate.rs
• a_running_jail_without_an_address_is_reported — tests/estate.rs
• a_stopped_jail_is_not_an_orphan — tests/estate.rs
• a_truncated_jls_row_is_refused_by_line_number — tests/estate.rs
• a_vm_disk_is_recognised_by_its_child_even_under_a_jail_mountpoint — tests/estate.rs
• another_pools_system_datasets_are_not_jail_orphans — tests/estate.rs
• configured_jail_names_are_stripped_of_the_colour_cbsd_emits_when_piped — tests/estate.rs
• dataset_detection_passes_each_flag_as_its_own_argument — tests/estate.rs
• datasets_are_split_on_tabs_and_keep_the_hosts_own_units — tests/estate.rs
• jail_detection_passes_each_column_as_its_own_argument — tests/estate.rs
• jails_are_read_by_header_position_not_field_order — tests/estate.rs
• jls_output_without_a_header_is_unreadable_not_empty — tests/estate.rs
• listener_detection_passes_each_flag_as_its_own_argument — tests/estate.rs
• listeners_skip_the_header_and_read_the_local_address — tests/estate.rs
• snapshot_rows_are_parsed_and_their_used_is_per_snapshot_only — tests/estate.rs
• sockstat_output_without_a_header_is_unreadable — tests/estate.rs
• zfs_output_with_no_rows_is_unreadable_not_an_empty_estate — tests/estate.rs

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 36
    "No rustdoc detected" : 1

Metrics

pie showData
    title Public API by kind
    "constant" : 7
    "enum" : 3
    "function" : 10
    "method" : 7
    "struct" : 9
    "type alias" : 1

pie showData
    title Rust source composition
    "Code" : 501
    "Blank or comment" : 307

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.