NAME

bptrace - Bundle Protocol (BP) network trace utility Updated from original by Silas Springer - March 2023. Updated to support CRS (Compressed Reporting Signals) - January 2026.

SYNOPSIS

bptrace [-v] [-msg "msg"] [-ttl ttl] [-rtt rtt] [-qos qos] [-flags flags] srcEid destEid traceEid

bptrace -listen [-v] listenEid

Backwards compatible with legacy usage: bptrace srcEid destEid traceEid ttl qos "msg" [flags]

DESCRIPTION

bptrace uses bp_send() to issue a single bundle to a designated destination endpoint, with status reporting options enabled as selected by the user, then terminates. The status reports returned as the bundle makes its way through the network provide a view of the operation of the network as currently configured.

bptrace transparently handles both traditional BPv7 status reports (admin record type 1) and Compressed Reporting Signals (CRS, admin record type 14) as defined in the CCSDS Orange Book specification. When nodes in the network are configured with m custodymode orangebook, they will generate CRS instead of traditional status reports. bptrace automatically detects the report type and displays the status information in a unified format.

Listen-only mode: When invoked with the -listen flag, bptrace opens the specified endpoint and displays bundle status reports as they arrive, without sending any trace bundles. This mode is useful for monitoring status reports from bundles sent by other applications. The program will continue listening until interrupted (Ctrl+C) or until 128 reports have been received. Status reports are displayed in real-time as they arrive.

ttl indicates the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed.

qos is custody-requested.priority[.ordinal[.unreliable.critical[.data-label]]], where custody-requested must be 0 or 1 (Boolean), priority must be 0 (bulk) or 1 (standard) or 2 (expedited), ordinal must be 0-254 (ION supports full 8-bit range; 255 is reserved), unreliable must be 0 or 1 (Boolean), critical must also be 0 or 1 (Boolean), and data-label may be any unsigned integer. custody-requested is passed in with the bundle transmission request, but if set to 1 it serves only to request the use of reliable convergence-layer protocols; this will have the effect of enabling custody transfer whenever the applicable convergence-layer protocol is bundle-in-bundle encapsulation (BIBE).

NOTE: The Quality of Service (QoS) extension block (type 254) is an ION-specific, non-standard extension. It is patterned after the IETF draft-burleigh-dtn-ecos-00 Extended Class of Service (ECOS) specification, but uses a different wire format. ION's QoS block encodes classOfService and ordinal as separate CBOR integers in a 4-element array, whereas the IETF draft specifies a 5-element array with priority and ordinal bit-packed into a single byte. This block will not interoperate with implementations following the IETF ECOS draft.

ordinal is ignored if priority is not 2. Setting qos to "0.2.254" or "1.2.254" gives a bundle the highest possible priority. Setting unreliable to 1 causes BP to forego convergence-layer retransmission in the event of data loss. Setting critical to 1 causes contact graph routing to forward the bundle on all plausible routes rather than just the "best" route it computes; this may result in multiple copies of the bundle arriving at the destination endpoint, but when used in conjunction with priority 2.63 it ensures that the bundle will be delivered as soon as physically possible.

msg can be any string of ASCII text; alternatively, if we want to send a file, it can be "@" followed by the name of the file.

flags must be a sequence of status report flags, separated by commas, with no embedded whitespace. Each status report flag must be one of the following: rcv, fwd, dlv, del.

-listen runs bptrace in listen-only mode. In this mode, only listenEid is required. bptrace will open the endpoint and display status reports as they arrive in real-time, without sending any bundles. The -v flag can be used for verbose debug output. The program listens indefinitely until interrupted (Ctrl+C) or until 128 reports have been received.

When traceEid is the same node as srcEid but with a differing, non-zero ID (e.g. srcEid is 2.2 and traceEid is 2.3) and the arguments are not specified using the legacy format; bptrace will listen on the specified traceEid and give a summary of recieved trace information to the terminal once the ttl has expired.

EXIT STATUS

"0"

bptrace has terminated.

FILES

No configuration files are needed.

ENVIRONMENT

No environment variables apply.

DIAGNOSTICS

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

bptrace can't attach to BP.

bpadmin has not yet initialized BP operations.
bptrace can't open own endpoint.

Another BP application task currently has srcEid open for bundle origination and reception. Try again after that task has terminated. If no such task exists, it may have crashed while still holding the endpoint open; the easiest workaround is to select a different source endpoint.
No space for bptrace text.

Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't create ZCO.

Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized.
bptrace can't send message.

BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun.

CRS (COMPRESSED REPORTING SIGNALS) SUPPORT

bptrace supports both traditional BPv7 status reports and Compressed Reporting Signals (CRS) as specified in the CCSDS Orange Book "Compressed Bundle Status Reporting and Custody Signaling" specification.

When a node is configured with m custodymode orangebook in its bprc file, bundles with status report requests will receive a CREB (Compressed Reporting Extension Block) instead of setting the traditional BPv7 status report request flags. Intermediate nodes generate CRS admin records (type 14) instead of traditional status reports (type 1).

bptrace automatically detects the admin record type and processes both formats identically. The displayed output uses a unified format regardless of which reporting mechanism was used.

CRS status codes are mapped to BPv7-equivalent flags:

0 (Received)

Maps to BPv7 "received" status (flag 0x01)
1 (Forwarded)

Maps to BPv7 "forwarded" status (flag 0x04)
2 (Delivered)

Maps to BPv7 "delivered" status (flag 0x08)
3 (Deleted)

Maps to BPv7 "deleted" status (flag 0x10)

Note that CRS does not carry timestamp information, so status times shown for CRS reports reflect the local receive time rather than the time the status event occurred at the remote node.

BUGS

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