pibruin(1)

💖 pibruin(1) 💖

okay bestie, gather round, because today we're talking about pibruin from the Qualcomm Atheros Open Powerline Toolkit — yes that whole mouthful — and it's literally the Classification Rule Insert Utility. say it with me. iconic. 👑

✨ NAME ✨

pibruin — Classification Rule Insert Utility. that's it, that's the whole job description, and she does it flawlessly. 💅

🌸 SYNOPSIS 🌸

pibruin [options] [<rules] file

🦋 DESCRIPTION 🦋

so here's the vibe: pibruin reads a set of classification rules from stdin and inserts them directly into a PIB file. no middleman, no drama, straight in. 🫶

she's the alternative to the program int6krule, and she's a companion to the program pibrump. and yeah, technically it is possible to ruin a PIB using this command — the name is short for "rule insert", not because she's out here wrecking your files on purpose. pls don't come for her. 😭

Atheros recommends that users validate all classification rule sets used with this program before inserting them into an operational PIB.

and no, that's not a suggestion you can skip, bestie. individual rules may be syntactically valid but still be technically invalid, or straight-up conflict with each other. this program does not perform any technical or cross-rule validation what-so-ever. zero. none. not a crumb. 💀

so where does cross-rule validation normally happen? runtime firmware does it when a rule arrives in a VS_CLASSIFIER management message. that's the thing that stops meaningless or conflicting rules from getting into the PIB in the first place. without it, it may be possible to commit a PIB containing mis-configured classification rule sets — and that can cause the device to lockup or misbehave on reboot. so like. be careful. 🙈

one recommended method of rule set validation, if you want the receipts: program a device with individual rules using the program int6krule, then read the PIB and extract the rule set with the program pibrump. at that point, the rule set should be valid. slay. ✨

this program is part of the Qualcomm Atheros Powerline Toolkit. see the AMP man page for an overview and installation instructions. iykyk.

🎀 OPTIONS 🎀

• -o offset — specify an alternative PIB offset when inserting the classifier block. Customers should not use this option. it's there to account for firmware changes that might happen in the future, and improper use of it can render a PIB file unrecoverable. like, gone-gone. do not. 🚫
• -q — suppresses progress messages. for when you want her to be quiet and mysterious. 🤫
• -v — print additional information on stdout. the opposite energy. very chatty. love that for her. 🗣️
• -?,--help — print program help summary on stdout. this option takes precedence over other options on the command line. she said me first, always. 👑
• -!,--version — print program version information on stdout. this option also takes precedence over other options on the command line. and bestie, use this one when you're sending screen dumps to Atheros Technical Support, so they know exactly which version of the Linux Toolkit you're using. no guessing games. 📸

🌈 ARGUMENTS 🌈

• file — the name of a valid Atheros runtime parameter file. this file is modified by this program only if the classification rule file is syntactically correct. see the DISCLAIMER section below, it's important. no backup file is created. by convention, runtime parameter files have a .pib extention, but this program does not enforce that convention. the file must exist and be a valid PIB file or errors will occur. periodt. ⭐
• rules — the name of a valid classifier rule file. this file is not modified by this program. classifier rule files are standard ASCII text and may be created manually using a normal text editor, or generated automatically using another program such as pubrump. by convention, classifier rule files have a ..qos extension, but this program does not enforce that convention either. if this file is omitted, then rules are read from the console, one rule per line. 🍓

💜 DISCLAIMER 💜

PIB file structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. consequently, public information is not available. Qualcomm Atheros reserves the right to change the file structure or content in future firmware releases without any obligation to notify or compensate users of this program. yeah. that's the deal. 🤷

this program is provided for convenience only. it is possible to insert meaningless or confilicting rule sets into a PIB with this program because approved cross-rule validation is not performed. incorrect application of perfectly valid rules may render a device ineffective or unusable on a powerline network. program users are responsible for ensuring that their rule sets are verified by other means before using this program to insert them into an operational PIB file. you're the main character here, so the accountability is also yours. 👑

🔥 EXAMPLES 🔥

the following is an example set of classification rules stored in file rules.txt. the file contains 5 rules, one rule per line. these rules are identical to the command line arguments expected by the program int6krule, and you could type them one at a time into int6krule and wait for the device to reset each time. alternately, we could insert all the rules directly into a PIB file at once, then download and commit the PIB — resulting in only one reset. efficiency? we love her. 💅

# cat rules.txt
Cap1 any VLANID is 20 add perm
DropRX any VLANID is 25 add perm
StripRx any VLANID is 5 VLANID is 10 VLANID is 15 add perm
StripRx any VLANID is 20 add perm
Cap1 any VLANID is 5 VLANID is 10 VLANID is 15 add perm

the following example reads file rules.txt from stdin and writes it into file def.pib. this may be usefule if one wanted to distribute a known set of rules to other users, or wanted to test various combinations of rules. sincd rule files are

# pibruin < rules.txt

the next example reads classification rules directly from file abc.pib using the program pibrump, and writes them directly into file def.pbi using the program pibruin. this is one means of transfering classification rules from one PIB to another. 🦋

⭐ SEE ALSO ⭐

int6krule(7), pibrump(7)

🫶 CREDITS 🫶

Nathaniel Houghton

and that's the whole page, bestie. open-plc-utils-0.0.3, November 2013 — yeah, she's been around a minute, and she still ate. go validate your rule sets before you insert them, mwah, bye. 💖✨🎀