Skip to content

NAME

bpinspect - Bundle Protocol (BP) comprehensive bundle inspection and management utility

SYNOPSIS

bpinspect [options]

DESCRIPTION

bpinspect is a comprehensive utility program for inspecting, filtering, and managing bundles that currently reside in the local node. It combines and extends the functionality of bplist and bpcancel, providing advanced filtering, sorting, batch operations, and export capabilities.

The utility enumerates bundles from the local bundle agent's timeline list, applies user-specified filters and sorting criteria, and performs requested operations such as listing, detailed inspection, batch cancellation, or export to files.

OPTIONS

General Options

  • -l

    List bundles (default action if no other action specified).

  • -d level

    Detail level for bundle display: 0 = Summary table (one line per bundle, default) 1 = Detailed information (metadata, flags, timestamps) 2 = Full information (includes extension blocks, CRC types, SDR addresses)

  • -c

    Cancel matching bundles. Requires user confirmation unless -n is specified. Bundles are identified and canceled using the same mechanism as bpcancel.

  • -n

    Skip confirmation prompts (use with -c for automated cancellation).

  • -D

    Dry-run mode. Show what would be done without actually performing the action. Useful for previewing which bundles would be canceled by filter criteria.

  • -e file

    Export bundle details to the specified file. Appends to file if it exists.

  • -h

    Display usage information and exit.

Filtering Options

  • -s eid

    Filter by source EID using prefix matching. Example: -s ipn:1. matches all bundles from node 1 (ipn:1.1, ipn:1.2, etc.).

  • -S eid

    Filter by source EID using exact matching. Example: -S ipn:1.1 matches only bundles from service 1 on node 1.

  • -t eid

    Filter by destination EID using prefix matching.

  • -T eid

    Filter by destination EID using exact matching.

  • -p priority

    Filter by bundle priority level: 0 = Bulk priority 1 = Standard priority 2 = Urgent priority

  • -m bytes

    Filter by minimum payload size in bytes.

  • -M bytes

    Filter by maximum payload size in bytes.

  • -x seconds

    Filter bundles expiring within the specified number of seconds. Useful for finding bundles that are about to expire.

  • -a

    Show only administrative bundles (exclude data bundles).

  • -A

    Show only data bundles (exclude administrative bundles).

  • -f

    Show only bundle fragments.

  • -q state

    Filter by queue state. State can be a comma-separated combination of: fwd = Bundles in forwarding queue dlv = Bundles in delivery queue xmit = Bundles in transmission queue limbo = Bundles in limbo (no active queue)

    Example: -q fwd,xmit shows only bundles in forwarding or transmission queues.

Sorting Options

  • -o field

    Sort bundles by the specified field: time = Creation time (default, newest first) exp = Expiration time (soonest expiring first) size = Payload size src = Source EID (alphabetical) dst = Destination EID (alphabetical) pri = Priority level

  • -r

    Reverse sort order (ascending instead of descending).

  • -L count

    Limit results to the first count bundles (default: 1000). Useful for large bundle sets to prevent excessive output.

Display Options

  • --color

    Force color output using ANSI escape codes. Overrides auto-detection. Colors are used to highlight: - Priority levels (Bulk=Blue, Standard=White, Urgent=Yellow) - Queue states (Forwarding=Green, Delivery=Cyan, Transmission/Planned=Yellow, Limbo=Red) - TTL warnings (Expired or <5min=Red, <1hour=Yellow)

  • --no-color

    Disable color output. Overrides auto-detection and the NO_COLOR environment variable.

COLOR SUPPORT

bpinspect automatically detects terminal color support and enables color output when appropriate. Color output is enabled when:

  • Standard output is connected to a terminal (not a pipe or file)
  • The TERM environment variable indicates a color-capable terminal
  • The NO_COLOR environment variable is not set

When color output is enabled, the table uses Unicode box-drawing characters for professional borders, and bundle information is color-coded for quick visual identification of priorities, queue states, and time-sensitive bundles.

Use --color to force color output (e.g., for specific terminal emulators), or --no-color to disable colors for scripting or accessibility needs.

EXAMPLES

  • bpinspect -l

    List all bundles in summary table format.

  • bpinspect -s ipn:1. -d 1

    Show detailed information for all bundles from node ipn:1.

  • bpinspect -x 60 -o exp

    Show bundles expiring within 60 seconds, sorted by expiration time.

  • bpinspect -t ipn:2.1 -c

    Cancel all bundles destined for ipn:2.1 (with confirmation prompt).

  • bpinspect -p 0 -D -c

    Dry-run: show which bulk priority bundles would be canceled.

  • bpinspect -s ipn:1.1 -T ipn:2.1 -e bundles.txt

    Export details of bundles from ipn:1.1 to ipn:2.1 to file.

  • bpinspect -m 1000000 -o size -r

    Show bundles larger than 1MB, sorted by size (largest first).

  • bpinspect -q fwd,xmit -d 1

    Show detailed view of bundles in forwarding or transmission queues.

  • bpinspect -a -s ipn:1.

    List administrative bundles from node ipn:1.

  • bpinspect -x 300 -c -n

    Cancel all bundles expiring within 5 minutes without confirmation.

EXIT STATUS

  • "0"

    bpinspect terminated successfully.

  • "1"

    bpinspect encountered an error. Common causes include: - Unable to attach to Bundle Protocol operations (bpadmin not run) - Invalid command-line arguments - Errors during bundle enumeration or operations - Insufficient memory for bundle cache

OUTPUT FORMAT

Summary Table (detail level 0)

Displays bundles in a tabular format with columns:

Source          - Source EID
Destination     - Destination EID
Size            - Payload size (B/KB/MB)
TTL             - Time to live (seconds/minutes/hours until expiration)
P               - Priority (B=Bulk, S=Standard, U=Urgent)
Queue           - Queue state (Forwarding/Delivery/Transmit/Planned/Limbo)

Detailed View (detail level 1)

Includes all summary information plus:

- Full bundle ID (source, creation timestamp, fragment info)
- Creation timestamp (human-readable and milliseconds)
- Expiration timestamp with countdown
- Total ADU length
- Bundle processing flags (ADMIN, FRAGMENT, ACK-REQ)
- Fragment offset and length (if applicable)

Full View (detail level 2)

Includes all detailed information plus:

- SDR (Simple Data Recorder) address
- Number and types of extension blocks
- Payload CRC type
- Primary block CRC type
- List of extension block type numbers

FILES

No configuration files are needed.

ENVIRONMENT

No environment variables apply.

DIAGNOSTICS

The following diagnostics may be issued to the ion.log log file:

  • Can't attach to BP.

    bpadmin has not yet initialized BP operations.

  • Can't get BP constants.

    Unable to access the Bundle Protocol database. The local ION node may need to be restarted.

  • Can't allocate bundle cache.

    Insufficient memory to create the in-memory bundle cache. Try reducing the maximum results limit with -L.

  • Can't enumerate bundles.

    Error accessing the bundle timeline. This may indicate a serious database error requiring node restart.

  • Can't find bundle to cancel.

    The specified bundle could not be located. It may have already been transmitted, delivered, or expired.

  • Can't destroy bundle.

    Unable to cancel the bundle, possibly due to database error or because the bundle has already been cloned for transmission.

IMPLEMENTATION NOTES

bpinspect uses internal Bundle Protocol APIs to access bundle metadata and perform operations. It enumerates bundles from the SDR timeline list and caches key metadata in memory for efficient filtering and sorting.

Bundle cancellation uses the same mechanism as bpcancel, destroying bundles by simulating immediate TTL expiration. Bundles that have been cloned for transmission cannot be canceled.

All database operations are performed within SDR transactions to ensure consistency. The utility keeps transactions brief to minimize lock contention.

PERFORMANCE CONSIDERATIONS

For systems with large numbers of bundles (10,000+):

  • Use -L to limit the number of results displayed
  • Apply specific filters to reduce the working set
  • Avoid detail level 2 unless necessary (reads full bundle metadata)
  • Use dry-run mode (-D) before performing batch cancellations

BUGS

Report bugs to <https://github.com/nasa-jpl/ION-DTN/issues>

SEE ALSO

bpadmin(1), bpcancel(1), bpclock(1), bplist(1), bpstats(1)