BRSSCLA(1)

📦 version 3.2.1, in ubuntu jammy

💖 BRSSCLA(1) 💖

okay bestie, welcome to the BP executables corner of the manual, where today's main character is brsscla 🎀

✨ NAME ✨

brsscla — the BRSS-based BP convergence layer adapter (input and output) task. she does both. she contains multitudes. 💅

🌸 SYNOPSIS 🌸

brsscla local_hostname[:local_port_nbr][ first_duct_nbr_in_scope[ last_duct_nbr_in_scope]]

that's it. that's the whole summoning ritual. 🪄

🦋 DESCRIPTION 🦋

okay so first things first: BRSS is the "server" side of the Bundle Relay Service (BRS) convergence layer protocol for BP. she's got a counterpart, BRSC, who is the "client" side of the BRS convergence layer protocol for BP. it's giving duo. it's giving complementary energies. 💜

brsscla is a background "daemon" task, and she is busy — she spawns two plus N threads, no cap:

  • one thread that handles BRSS client connections and spawns sockets for continued data interchange with connected clients 🔌
  • one thread that handles BRSS protocol output, transmitting over those spawned sockets to the associated clients 📤
  • and one input thread for each spawned socket, handling BRSS protocol input from the associated connected client 📥

The connection thread simply accepts connections on a TCP socket bound to local_hostname and local_port_nbr, and spawns reception threads. and the default value for local_port_nbr, if you just... don't say it? is 80. iconic default behavior tbh. ✨

Each reception thread receives over the socket connection the node number of the connecting client (in SDNV representation), followed by a 32-bit time tag and a 160-bit HMAC-SHA1 digest of that time tag. The node number must be in the range first_duct_nbr_in_scope through last_duct_nbr_in_scope inclusive. when omitted, first_duct_nbr_in_scope defaults to 1 and last_duct_nbr_in_scope defaults to first_duct_nbr_in_scope plus 255. 🫶

The receiving thread also checks the time tag, requiring that it differ from the current time by no more than BRSTERM (default value 5) seconds. ⏰ then it recomputes the digest value using the HMAC-SHA1 key named "node_number.brs" as recorded in the ION security database (peep ionsecrc(5)), requiring that the supplied and computed digests be identical. if all registration conditions are met, the receiving thread sends the client a countersign — a similarly computed HMAC-SHA1 digest, for the time tag that is 1 second later than the provided time tag — to assure the client of its own authenticity, then commences receiving bundles over the connected socket. mutual verification?? we love a healthy relationship. 🥰

Each bundle received on the connection is preceded by its length, a 32-bit unsigned integer in network byte order. The received bundles are passed to the bundle protocol agent on the local ION node. 📦

The output thread extracts bundles from the queues of bundles ready for transmission via BRSS to remote bundle protocol agents, finds the connected clients whose node numbers match the proximate receiver node numbers assigned to the bundles by the routing daemons that enqueued them, and transmits the bundles over the sockets to those clients. Each transmitted bundle is preceded by its length, a 32-bit unsigned integer in network byte order. matchmaker, matchmaker, find me a match. 💘

Note that brsscla is a "promiscuous" convergence layer daemon, able to transmit bundles to any BRSS destination induct for which it has received a connection. 👀

Its sole outduct's name is the name of the corresponding induct, rather than the induct name of any single BRSS destination induct to which the outduct might be dedicated, so scheme configuration directives that cite this outduct must provide destination induct IDs. For the BRS convergence-layer protocol, destination induct IDs are simply the node numbers of connected clients. periodt. 💅

brsscla is spawned automatically by bpadmin in response to the 's' (START) command that starts operation of the Bundle Protocol, and she is terminated by bpadmin in response to an 'x' (STOP) command. she can also be spawned and terminated in response to START and STOP commands that pertain specifically to the BRSS convergence layer protocol. she's flexible like that. 🧚

🌈 EXIT STATUS 🌈

  • "0" — brsscla terminated normally, for reasons noted in the ion.log file. If this termination was not commanded, investigate and solve the problem identified in the log file and use bpadmin to restart the BRSS protocol. 🕵️
  • "1" — brsscla terminated abnormally, for reasons noted in the ion.log file. Investigate and solve the problem identified in the log file, then use bpadmin to restart the BRSS protocol. 😭

🎀 FILES 🎀

No configuration files are needed. not a single one. she comes with everything she needs. 💖

⭐ ENVIRONMENT ⭐

No environment variables apply. she's unbothered, moisturized, in her lane. 🧖

💜 DIAGNOSTICS 💜

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

  • brsscla can't attach to BP. — bpadmin has not yet initialized Bundle Protocol operations.
  • No such brss induct. — No BRSS induct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the induct, and then restart the BRSS protocol.
  • CLI task is already started for this duct. — Redundant initiation of brsscla. she's already here bestie, you can stop yelling. 🙈
  • No such brss outduct. — No BRSS outduct with duct name matching local_hostname and local_port_nbr has been added to the BP database. Use bpadmin to stop the BRSS convergence-layer protocol, add the outduct, and then restart the BRSS protocol.
  • Can't get IP address for host — Operating system error. Check errtext, correct problem, and restart BRSS.
  • Can't open TCP socket — Operating system error -- unable to open TCP socket for accepting connections. Check errtext, correct problem, and restart BRSS.
  • Can't initialize socket (note: must be root for port 80) — Operating system error. Check errtext, correct problem, and restart BRSS.
  • brsscla can't create sender thread — Operating system error. Check errtext, correct problem, and restart BRSS.
  • brsscla can't create access thread — Operating system error. Check errtext, correct problem, and restart BRSS.

🐛 BUGS 🐛

Report bugs to <ion-bugs@korgano.eecs.ohiou.edu> — they're literally waiting for your email. fr fr. 📧

🔥 SEE ALSO 🔥

bpadmin(1), bprc(5), brsccla(1)

okay that's the whole page!! this was rendered for perl v5.24.1 on 2016-07-07, so if you're reading this in the future, just know she's a vintage queen and she still slays 👑💖 bye bestie, go start your BRSS protocol!! ✨🦋

📦 where this page comes from