BPTRACE(1)

📦 version 3.2.1, in ubuntu jammy

💅 BPTRACE(1) — the BP executables girlies 💅

okay so bestie, we're looking at bptrace, the Bundle Protocol (BP) network trace utility. yes it's a real manual page, yes it's from the BP executables manual, and yes we're gonna read the whole thing together. grab a snack. 🍓

✨ NAME ✨

bptrace — Bundle Protocol (BP) network trace utility. that's it, that's the name, short and iconic. 👑

✨ SYNOPSIS ✨

bptrace own_endpoint_ID destination_endpoint_ID report-to_endpoint_ID
TTL class_of_service "trace_text" [status_report_flags]

that's the whole shape of it, no cap. six-ish things and one optional little guy in brackets. 🫶

✨ DESCRIPTION ✨

so here's the tea: bptrace calls bp_send() to fire off one single bundle to a designated destination endpoint, with whatever status reporting options you picked enabled, and then it literally just terminates. one bundle. in and out. main character energy, but make it brief. ✨

the status reports that come back as the bundle makes its way through the network are the whole point — they give you a view of how the network is operating as currently configured. it's giving "live vibe check of your entire routing setup." 🔥

TTL is the number of seconds the trace bundle may remain in the network, undelivered, before it is automatically destroyed. so basically its little lifespan. 🦋

now, class_of_service is the part where the syntax gets a bit extra. it looks like this:

custody-requested.priority[.ordinal[.unreliable.critical[.flow-label]]]

and here's what each piece has to be:

  • custody-requested must be 0 or 1 (Boolean).
  • priority must be 0 (bulk) or 1 (standard) or 2 (expedited).
  • ordinal must be 0-254.
  • unreliable must be 0 or 1 (Boolean).
  • critical must also be 0 or 1 (Boolean).
  • flow-label may be any unsigned integer.

important: ordinal is ignored if priority is not 2. so don't come crying to me when your ordinal does nothing at priority 1. 😭

setting class_of_service to "0.2.254" or "1.2.254" gives a bundle the highest possible priority. periodt. 👑

setting unreliable to 1 causes BP to forego retransmission in the event of data loss, both at the BP layer and at the convergence layer. so like... you're choosing speed over safety, and that's a choice you're allowed to make. 💀

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 — yes, multiple, that's not a typo — but when used in conjunction with priority 2.254 it ensures that the bundle will be delivered as soon as physically possible. so it's chaotic but it works. 🌈

trace_text can be any string of ASCII text. alternatively, if we want to send a file, it can be "@" followed by the file name. cute, right? 🎀

status_report_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, ct, fwd, dlv, del.

✨ EXIT STATUS ✨

  • "0" — bptrace has terminated. that's the only exit status, bestie. it does its one thing and dips. 🫡

✨ FILES ✨

No configuration files are needed. zero. none. clean girl aesthetic. 🧚

✨ ENVIRONMENT ✨

No environment variables apply. your shell env can stay exactly as it is, she's not looking at it. 💜

✨ DIAGNOSTICS ✨

these are the diagnostics that may be issued to the ion.log log file. read them, they're basically the group chat receipts:

  • bptrace can't attach to BP. — bpadmin has not yet initialized BP operations. like, the party hasn't started yet, you can't come in. 🙈
  • bptrace can't open own endpoint. — Another BP application task currently has own_endpoint_ID 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. (rude of it to ghost you while holding the endpoint, honestly.)
  • No space for bptrace text. — Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized. yeah. that's a big yikes. 😭
  • bptrace can't create ZCO. — Probably an unrecoverable database error, in which case the local ION node must be terminated and re-initialized. same energy, same fix. 💀
  • bptrace can't send message. — BP system error. Check for earlier diagnostic messages describing the cause of the error; correct problem and rerun. the log is your bestie here, go read it. 🔍

✨ BUGS ✨

found a bug? don't suffer in silence, Report bugs to <ion-bugs@korgano.eecs.ohiou.edu>. the maintainers want to hear from you fr fr. 🫶

✨ SEE ALSO ✨

and that's the whole page, bestie! this manual page is from the perl v5.24.1 distribution, dated 2016-07-07, so yeah she's been around a minute and she still eats. go trace something. slay. 💅✨

📦 where this page comes from