NAME

bptracker - ION Bundle Protocol transmission tracker and management utility with enhanced debugging

SYNOPSIS

bptracker [-v] [-vv] [-vvv] [-h] source_eid [dest_eid]

DESCRIPTION

bptracker is an interactive Bundle Protocol utility that provides real-time bundle tracking and management with Bundle Protocol status report support. It operates in a fully interactive mode where users can configure transmission parameters, send individual bundles, and monitor bundle status through the Bundle Protocol status report mechanism.

The utility opens a source endpoint with detention enabled, allowing detailed tracking of sent bundles. Users can configure status report request flags and specify a report-to endpoint to receive Bundle Protocol status reports for transmitted bundles.

Note: To receive and display status reports, use bptrace in listen-only mode (bptrace -listen reportEid) on the same or different terminal. Status report reception directly in bptracker is planned for a future release.

OPTIONS

• -v

  Enable verbose output (debug level 1). Shows basic operations and status changes.

• -vv

  Enable more verbose output (debug level 2). Shows detailed function calls and tracking steps.

• -vvv

  Enable most verbose output (debug level 3). Shows verbose internal state and queue details.

• -h, --help

  Display usage information and exit.

PARAMETERS

• source_eid

  Source endpoint identifier (e.g., ipn:1.1). Must be a valid EID that the local node can open as a source endpoint. Required.

• dest_eid

  Optional default destination endpoint identifier (e.g., ipn:2.1). If provided, this sets the default destination that can be used for convenience. Individual send commands can override this by specifying a different destination.

INTERACTIVE COMMANDS

bptracker provides a fully interactive command interface immediately upon startup:

• config [param] [value]

  Configure transmission parameters or show current configuration. When called without arguments, displays all current settings. Configuration parameters:

  • dest eid

    Set default destination endpoint. The send command can override this on a per-bundle basis. Example: config dest ipn:2.1

  • report eid

    Set the report-to endpoint where Bundle Protocol status reports will be sent. Example: config report ipn:1.2

  • srr flags

    Set status report request flags. Can be specified as hex (e.g., 0f) or comma-separated text flags: rcv (received), fwd (forwarded), dlv (delivered), del (deleted). Example: config srr rcv,dlv or config srr 0f

  • ttl seconds

    Set default time-to-live in seconds. Example: config ttl 300

  • priority 0-2

    Set default priority: 0=bulk, 1=standard, 2=expedited. Example: config priority 1

• send [dest_eid] payload_size

  Send a bundle with the given payload size (1-65536 bytes). The destination can be specified explicitly or omitted to use the default destination set via config dest. If provided, the destination parameter overrides the configured default. Uses current configuration for status report flags, report-to endpoint, TTL, and priority.

  Examples: send ipn:2.1 1024 (explicit destination) send 1024 (uses configured default destination)

• reports [bundle_id]

  Show status report statistics (not yet implemented - use bptrace -listen to view reports).

• q, quit

  Release all detained bundles and exit the program gracefully.

• s, status

  Display current tracker status including active bundles, completion statistics, success rates, and current debug level.

• l, list

  List all tracked bundles with enhanced information including:

  • Bundle ID and current status
  • Age in seconds since bundle was sent
  • Source EID extracted from bundle
  • Creation time in YYYY-MM-DD HH:MM:SS.mmm.count format
  • Current queue status within ION
  • Bundle object address for transmitted bundles

• r id, release id

  Release a specific bundle by ID from detention, allowing it to be deleted when all retention constraints are removed.

• ra, release-all

  Release all currently detained bundles from detention.

• suspend id, sp id

  Suspend transmission of a specific bundle by ID. Only works for bundles still in local storage that haven't been transmitted yet.

• resume id, res id

  Resume transmission of a previously suspended bundle by ID.

• h, help

  Display comprehensive help information about available commands, bundle information fields, status meanings, and current debug level.

BUNDLE STATES

bptracker tracks bundles through the following states:

• PENDING

  Bundle is awaiting transmission or currently being processed for transmission.

• SUSPENDED

  Bundle transmission has been manually suspended using ION's bp_suspend() function and is held in suspension until resumed.

• TRANSMITTED

  Bundle has been successfully transmitted by the convergence layer and is now detained in local storage for manual management.

• COMPLETED

  Bundle has been manually released from detention and is eligible for deletion when all retention constraints are satisfied.

QUEUE STATUS INFORMATION

bptracker provides detailed visibility into ION's internal queue status for each bundle:

• PLAN

  Bundle is in the egress plan queue awaiting route processing.

• DUCT

  Bundle is in the outduct transmission queue awaiting convergence layer processing.

• FWD

  Bundle is in the forwarding queue awaiting forwarding decisions.

• DLV

  Bundle is in the delivery queue awaiting local delivery.

• DETAINED

  Bundle is held in detention post-transmission.

• CLEAR

  Bundle is not currently in any ION queues (transmission complete).

• RELEASED

  Bundle has been manually released from detention.

Multiple queue statuses may be displayed simultaneously if a bundle is present in multiple queues.

DEBUG LEVELS

bptracker supports four debug verbosity levels:

• Level 0 (default)

  No debug output. Only normal operation messages and user interactions are displayed.

• Level 1 (-v)

  Basic operations and status changes including bundle send/suspend/resume/release operations and monitoring loop activities.

• Level 2 (-vv)

  Detailed function calls and tracking steps including SDR transactions, bundle object operations, and tracking record updates.

• Level 3 (-vvv)

  Verbose internal state and queue details including bundle object reads, queue status changes, and detailed ION interaction debugging.

Debug output is sent to stderr while normal program output goes to stdout, allowing for clean output redirection.

ENHANCED BUNDLE INFORMATION

Each tracked bundle displays comprehensive information:

• Bundle ID

  Sequential identifier assigned by bptracker (1, 2, 3, ...).

• Status

  Current bundle state (PENDING, SUSPENDED, TRANSMITTED, COMPLETED).

• Age

  Seconds elapsed since the bundle was initially sent.

• Source EID

  Original source endpoint identifier extracted from the bundle header.

• Creation Time

  Bundle creation timestamp in ION DTN time format converted to human-readable YYYY-MM-DD HH:MM:SS.mmm.count format showing both millisecond precision and sequence count.

• Queue Status

  Current location within ION's internal queue system, providing visibility into bundle processing state.

PAYLOAD FORMAT

Each bundle contains a test payload filled with a repeating byte pattern where each byte contains the value (byte_position % 256). This creates a predictable test pattern useful for verifying payload integrity.

BUNDLE DETENTION

bptracker uses BP detention to retain bundles in local storage even after transmission. This allows for:

• Real-time status monitoring of transmitted bundles with queue visibility
• Manual control over bundle lifecycle management
• Detailed inspection of bundle transmission behavior through ION queues
• Testing of bundle suspension and resumption capabilities
• Enhanced debugging of bundle processing flow

Detained bundles must be explicitly released to be eligible for deletion from the bundle database.

SIGNAL HANDLING

bptracker handles SIGINT (Ctrl+C) and SIGTERM signals gracefully by:

• Releasing all detained bundles
• Cleaning up tracking data structures and SDR resources
• Terminating the input handler thread safely
• Closing the Bundle Protocol SAP
• Detaching from ION

THREADING

The utility uses multiple threads with proper synchronization:

• Main thread: Bundle status monitoring, queue status updates, and application control
• Input thread: Interactive command processing with 2-second startup delay

Thread synchronization ensures safe access to shared tracking data and SDR operations.

EXAMPLES

• Send 5 bundles of 1024 bytes each (silent operation):

  % bptracker ipn:1.1 ipn:2.1 1024 5
  

• Send with basic debug output:

  % bptracker -v ipn:1.1 ipn:2.1 1024 5
  

• Send with detailed debug output:

  % bptracker -vv ipn:1.1 ipn:2.1 1024 5
  

• Send with maximum verbosity:

  % bptracker -vvv ipn:1.1 ipn:2.1 1024 5
  

• Show help and exit:

  % bptracker -h
  

• Interactive session example:

  % bptracker -v ipn:1.1 ipn:2.1 1024 3
  > list              # Show all bundles with enhanced info
  ID  Status       Age(s)  Source_EID    Creation_Time         Queue_Status
  --- ------------ ------- ------------- -------------------- ---------------
  1   TRANSMITTED  45      ipn:1.1       2024-01-15 14:30:25.123.1  CLEAR
  2   PENDING      12      ipn:1.1       2024-01-15 14:30:25.223.2  PLAN DUCT
  3   SUSPENDED    8       ipn:1.1       2024-01-15 14:30:25.323.3
  
  > suspend 2         # Suspend bundle 2 (if still local)
  > status            # Check current statistics
  > resume 2          # Resume bundle 2
  > release 1         # Release bundle 1 from detention
  > quit              # Release all and exit
  

EXIT STATUS

• 0

  Successful completion.

• 1

  Invalid command line arguments, initialization failure, or system error.

FILES

None.

ENVIRONMENT

No special environment dependencies. Uses standard ION environment configuration.

DIAGNOSTICS

bptracker reports various diagnostic messages based on debug level:

• Normal operation

  Bundle transmission confirmations, status changes, and interactive command responses.

• Debug level 1

  Basic operation logging including send/suspend/resume/release operations and monitoring activities.

• Debug level 2

  Detailed function tracing including SDR transactions, bundle tracking setup, and status update procedures.

• Debug level 3

  Verbose internal state including bundle object details, queue status changes, and ION interaction debugging.

• Error conditions

  ION system errors, memory allocation failures, SDR transaction failures, and invalid operations are reported through ION's standard error reporting mechanism.

• Status summaries

  Periodic and on-demand statistics about bundle transmission success rates, current active bundle counts, and debug level information.

BUGS

• Bundle suspension and resumption only work for bundles still in local storage. Once bundles have been forwarded to the next hop, they cannot be suspended or resumed.
• Queue status information depends on ION's internal bundle object structure and may not reflect all possible queue states in complex routing scenarios.
• Debug output at level 3 can be quite verbose and may impact performance during high-throughput testing scenarios.
• Critical bundles (those with BP_MINIMUM_LATENCY flag) cannot be suspended by ION's design.

Report bugs to ION development team.

SEE ALSO

bpadmin(1), bpdriver(1), bprecvtest(1), bpsendtest(1), bpsink(1), bpsource(1), bptrace(1), bp(3), ion(3)

AUTHOR

ION Bundle Protocol implementation.