plcrule(1)

📦 version 0.0.6+git20250712.46c3506, in alpine 3.24, debian bookworm, debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

plcrule(1) — okay bestie, this is the Qualcomm Atheros Open Powerline Toolkit page for the Stream Classification Utility. No cap, it’s giving network rule energy. 💅✨

💖 NAME 💖

plcrule — Stream Classification Utility 🦋

🌸 SYNOPSIS 🌸

plcrule [options] action operand condition [condition] [condition]
control volatility [device] [device] [...]

where condition is a field operator value sequence. And yes bestie, that’s literally the shape of it. 🎀

🦋 DESCRIPTION 🦋

okay so this utility formats and sends stream classification rules to one or more devices. Rules specify an action to be taken when a frame satisfies selection criteria. Selection criteria consists of one, two or three conditions where any or all conditions must be satisfied. Each condition consists of a field type, a relational operator and a value. Rules may be added to a device, or removed from a device, so that they have permanent or temporary effect. Periodt. 💅

Classification rules are cumulative. If a new rule set is identical to an old rule set then an error will occur unless it contains a different Transmission Action. In that case the old rule will be replaced. Identical classification rule sets are permitted if one of the sets is associated with a VLAN tag action. Classification is based on the original frame before it is altered by VLAN Tag insertion or removal. 🦋

Classification is multi-dimensional and the terminology used here may seem strange at first. Refer to the Qualcomm Atheros Firmware Techncial Reference Manual description of the VS_CLASSIFICATION management message for a full explanation. iykyk. 👑

This program is part of the Qualcomm Atheros Powerline Toolkit. See the plc man page for an overview and installation instructions. 🌈

✨ OPTIONS ✨

bestie, here are the flags. Every single one. No skipping. 💖

  • -e — Redirects stderr messages to stdout. By convention status and error messages are printed on stderr while primary program output is printed on stdout. This option prints all output on stdout in cases where this is desired.
  • -i interface — Select the host Ethernet interface. All requests are sent via this host interface and only responses received via this host interface are recognized. The default interface is eth1 because most people use eth0 as their principle network connection; however, if environment string "PLC" is defined then it takes precedence over the default interface. This option then takes precedence over either default. 🦋
  • -q — Suppresses status messages on stderr.
  • -r — Read rules from a device and display them on stdout.
  • -s — Print a list of program keywords on stdout. This option overrides all others, except -? and -!, and the program will terminate without further action. ✨
  • -t milliseconds — Read timeout in milliseconds. Values range from 0 through UINT_MAX. This is the maximum time allowed for a response. The default is shown in brackets on the program menu.
  • -T tag — The VLAN tag to be inserted into frames before they are transmitted. The tag is a 32-bit hexadecimal integer with optional "0x" prefix. This option is required for action TagTX and must be omitted for all other actions. 🎀
  • -v — Print additional information on stdout. In particular, this option dumps incoming and outgoing packets which can be saved as text files for reference.
  • -V version — The CSPEC version number expressed as a small decimal integer. This option is required (and should be 2) for action TagTX and must be omitted for all other actions. 💜
  • -?, --help — Print program help summary on stdout. This option takes precedence over other options on the command line.
  • -!, --version — Print program version information on stdout. This option takes precedence over other options on the command line. Use this option when sending screen dumps to Atheros Technical Support so that they know exactly which version of the Linux Toolkit you are using. 🙈

🎀 ARGUMENTS 🎀

Here’s what you feed it, bestie. 🍓

  • action — The action to be taken for frames that meet any (or all) selection criteria. Valid actions are listed and described under ACTIONS. 💅
  • operand — The operand specifies the logical relationship between conditions before the action to be taken. Valid operands are listed and described under OPERANDS.
  • condition — A conditional expression consisting of a field, operator and value. See CONDITIONS for more information.
  • control — The control specifies the action to be taken by the device upon receipt of the rule. The basic actions are to add it to, or remove it from, the list of existing rules. Valid controls are listed and described under CONTROLS. 🔥
  • volatility — The volatility specifies the effective lifetime of the rule. Temporary rules are stored in SDRAM and are lost when the device is reset. Permanent rules are stored in NVRAM and are restored after the device is reset. Valid volatilities are listed and described under VOLATILITY. 👑
  • device — The MAC address of some powerline device. More than one address may be specified on the command line. If more than one address is specified then operations are performed on each device in turn. The default address is "local". See DEVICES for more information. 🌈

🔥 ACTIONS 🔥

Actions indicate the disposition of frames that match selection criteria. They are expressed as discrete alphanumeric strings entered in upper, lower or mixed character case. They are position sensitive. Failure to enter a known action will result in an error message that lists permitted actions. Slay. 💅

  • CAP0,CAP1,CAP2,CAP3 — Assign a specific Channel Access Priority to frames. 👑
  • Drop,DropTX — Do not forward frames over powerline. 💀
  • DropRX — Do not forward frames to host. 🙈
  • Boost — Boost frame priority to CAP3 for MMEs only. At least one condition must be "MME". 🔥
  • StripTX — Remove the VLAN Tag from frames before transmission over powerline. This option checks for a VLAN Tag even when there are no VLAN related conditions. ✨
  • StripRX — Remove the VLAN Tag from frames before forwarding to host. This option checks for a VLAN Tag even when there are no VLAN related conditions. 🦋
  • TagTX — Insert a given VLAN Tag into frames before transmission over powerline. This action requires option -T to specify the tag and option -V to specify the CSPEC version. 🎀

👑 OPERANDS 👑

The operand indicates the logical relationship that must exist between conditions in the rule set before the action is applied to a frame. Operands are expressed as discrete alphanumeric strings entered in upper, lower or mixed character case. Failure to enter a known operand will result in an error message that lists permitted operands. They are position sensitive. One operand is allowed and it must appear after the action and before any condition. Periodt. 💜

  • Any — Apply the action to frames that satisfy any of the conditions. This is equivalent to the logical or operation. 🌈
  • All — Apply the action to frames that satisfy all of the conditions. This is equivalent to the logical and operation. 💖
  • Always — Apply the action to all frames. All conditions are ignored. ✨

💜 CONDITIONS 💜

A condition consists of a field, an operator and a value. One condition is required but three are permitted. Condition order is not important but all conditions must appear after the operand and before the control. Okay? Okay. 🎀

field

The field is the part of the Ethernet frame to be examined. Some fields are not valid for some actions but this program does not enforce such rules since validation is performed by runtime firmware on each device. Recognized fields are listed and described under FIELDS. 🦋

operator

The operator specifies the relationship that must exist between the field and value in order for the condition to evaluate True. Currently, only equality operators are supported. Valid operators are listed and described under OPERATORS. 💅

value

The value must be appropriate to the field type. Some fields are MAC or IP addresses, some are integers, some are bitmaps and others are states. Integers and bitmaps may be expressed in binary, decimal or hexadecimal format. Binary values start with 0b. Hexadecimal values start with 0x. States are expressed using keywords. Users are responsible for knowing how many bits are significant for each type of value. Valid values are described along with fields under FIELDS. 🎀

✨ FIELDS ✨

okay so a field is literally just which part of the frame we're snooping on during selection — and it also decides the size + format of the value you're allowed to put in the condition statement. Fields get written as discrete alphanumeric strings, and you can type them in UPPER, lower or MiXeD case, we're not picky 💅. Type a field that doesn't exist and you get an error message listing the permitted ones. slay.

  • ET — a 16-bit Ethertype, written in hexadecimal with an optional 0x prefix. The format is described in IEEE Standard 802-2001 [4].
  • EthDA — a 48-bit Ethernet destination address, written in hexadecimal. You can separate the octets with optional colons for clarity, we love a readable address 🎀. The format is described in IEEE Standard 802-2001 [4].
  • EthSA — a 48-bit Ethernet source address, written in hexadecimal. Octets may be separated with optional colons for clarity. The format is described in IEEE Standard 802-2001 [4].
  • IPSP — a 16-bit IP source port, written as a decimal integer. This condition applies to either TCP or UDP packets, depending on the protocol used, and it's valid only for actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop". periodt.
  • IPDP — a 16-bit IP destination port, written as a decimal integer. This condition applies to either TCP or UDP packets, depending on the protocol used, and it's valid only for actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop". periodt.
  • IPV4TOS — an 8-bit Type-of-Service code, where the format is defined in the RFC 791 (Internet Protocol) [14].
  • IPV4PROT — an 8-bit Ethernet protocol code. The format is defined in the RFC 791 (Internet Protocol) [14].
  • IPV4SA — a 32-bit Internet Protocol source address, written in dotted-decimal notation. The official format is defined in RFC 791 (Internet Protocol) [14]. Our implementation permits empty octets and leading zeros within fields. For example, "..." is equivalent to 0.0.0.0 and "127..000.001" is equivalent to 127.0.0.1.
  • IPV4DA — a 32-bit Internet Protocol destination address, written in dotted-decimal notation. The official format is defined in RFC 791 (internet Protocol) [14]. Our implementation permits empty octets and leading zeros within fields. For example, "..." is equivalent to 0.0.0.0 and "127..000.001" is equivalent to 127.0.0.1.
  • IPV6TC — an 8-bit Internet Protocol V6 traffic class, expressed as defined in RFC 2460 (Internet Protocol Version 6) [17].
  • IPV6FL — a 24-bit IPV6 flow label, where the lower 20 bits are the IPv6 Flow Label defined in RFC 2460 (Internat Protocol Version 6) [17]. The upper 4 bits should be zero. The value can be entered either as a decimal, binary or hex integer.
  • IPV6SA — a 128-bit IPV6 source address, expressed as colon-separated hexadecmial quartets (octet pairs). The official format is defined in RFC 2460 (Internet Protocol Version 6) [17]. Our implementation permits multiple empty fields, abreviated fields and leading zeros within fields. When multiple empty fields appear, the right-most occurance expands to multiple zeros. For example, "AAAA::BBBB::CCCC" is equivalent to "AAAA:0000:BBBB:0000:0000:0000:0000:CCCC".
  • IPV6DA — a 128-bit IPV6 destination address, expressed as colon-separated hexadecimal quartets (octet pairs). The official format is defined in RFC 2460 (Internet Protocol Version 6) [17]. Our implementation permits multiple empty fields, abbreviated fields and leading zeros within fields. When multiple empty fields appear, the right-most occurance expands to zeros. For example, ":1::2" is equivalent to "0000:0001:0000:0000:0000:0000:0000:0002".
  • MME — a 24-bit Atheros HomePlugAV Management Message type, expressed as a hex byte stream. For clarity, the recommeded format it "xx:xxxx". The first byte is the MMV. The next two bytes are the MMTYPE. Both are defined in the HomePlug AV Specification. The MMTYPE will match all MME variants, such as Request, Confirm, Indicate and Response, because the lower two bits are ignored. This field is only valid for action "Boost". 👑
  • TCPAck — the string "True" or "False", to indicate that the frame is (or is not) a TCP Acknowledgement. Double negatives are allowed, so "Is True" is equvalent to "Not False" and "Is False" is equivalent to "Not True". the way double negatives just work here? iconic.
  • TCPSP — a 16-bit TCP source port, as a decimal integer. The format is defined in RFC 793 (Transmission Control Protocol [15]).
  • TCPDP — a 16-bit TCP destination port, expressed as a decimal integer. The format is defined in RFC 793 (Transmission Control Protocol [15]).
  • UDPSP — a 16-bit UDP source port, expressed as a decimal integer. The format is defined in RFC 768 (User Datagram Protocol [13]).
  • UDPDP — a 16-bit UDP destination port, expressed as a decimal integer. The format is defined in RFC 768 (User Datagram Protocol [13]).
  • VLANID — a 16-bit VLAN identifier, where the lower 12 bits are the VLAN Identifier (VID) defined in IEEE Std 802.1Q-1998 (Virtual Bridged Local Area Networks) [11]. The upper 4 bits should be zero.
  • VLANUP — an 8-bit Ethernet VLAN tag, where the lower 3 bits are the User Priority sub-field of a VLAN Tag defined in IEEE Std 802.1Q-1998 (Virtual Bridged Local Area Networks) [11]. The upper 5 bits should be zero.
  • VLANTag — the string "Present" or "Missing", to indicate the presence (or absence) of one or more VLAN Tags within a frame. This classifier is essentially equivalent to "ET Is 0x8100". Double negatives are allowed, so "Is Present" is equivalent to "Not Missing" and "Is Missing" is equivalent to "Not Present".

🌈 OPERATORS 🌈

An operator is literally just saying "this equals that" between a field and a value. It's an alphanumeric string, and again you can type it in upper, lower or mixed case. Type one that isn't real and boom 💀 error message listing the permitted operators. and bestie, listen: operators are position sensitive — they have to sit right between each field and its value. no skipping the line.

  • Is — says the frame field must equal the associated value for the condition to evaluate true.
  • Not — says the frame field must not equal the associated value for the condition to evaluate true.

💜 STATES 💜

A state is just a special case of a value, iykyk.

  • True, On, Yes, Present — indicates a positive state, or the presence of some entity. All of these are equivalent and totally interchangeable, use whichever vibes. Double negatives are permitted, so "Is True" is equvalent to "Not False".
  • False, Off, No, Missing — indicates a negative state, or the absence of some entity. All of these are equivalent and interchangeable too. Double negatives are permitted, so "Is False" is equvalent to "Not True".

🦋 CONTROLS 🦋

The control decides how the devices handle the rule after it's been validated. It's a discrete alphanumeric string, upper/lower/mixed case all fine. Type one that doesn't exist and you'll get an error listing the permitted controls. Also: the control is position sensitive — it has to come after the condition and before the volatility. no cap, order matters.

  • Add — adds the rule to the current list of rules, unless a violation occurs. In some cases, a rule may replace an existing rule instead of being added. sneaky but valid ✨
  • Rem, Remove — removes the rule from the current list of rules, unless a violation occurs.

🎀 VOLATILITY 🎀

Volatility decides which device rule set the action is gonna touch. Discrete alphanumeric string, upper/lower/mixed case, all good. Type a fake one and you get an error message listing the permitted volatilities. And yes, it's position sensitive too — it must occur after the control.

  • Temp — the temporary rule set will be modified. The temporary rule set resides in the working PIB stored in SDRAM.
  • Perm — the permanent rule set will be modified. The permanent rule set resides in the user PIB stored in NVRAM.

👑 DEVICES 👑

Powerline devices use Ethernet Media Access Control (MAC) addresses. A MAC address is a 48-bit value entered as 12 hexadecimal digits, in upper, lower or mixed character case. You can separate the octets with colons for clarity if you want. For example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are all valid and equivalent. same address, three outfits 💅

The following MAC addresses are special and may be entered by name instead of by number:

  • all — same as "broadcast".
  • broadcast — a synonym for the Ethernet broadcast address, FF:FF:FF:FF:FF:FF. All devices, whether local, remote or foreign, recognize messages sent to this address. A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.
  • local — a synonym for the Qualcomm Atheros vendor specific Local Management Address (LMA), 00:B0:52:00:00:01. All local Atheros devices recognize this address, but remote and foreign devices do not. A remote device is any device at the far end of a powerline connection. A foreign device is any device not manufactured by Atheros.

📚 REFERENCES 📚

See the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more information.

🙈 DISCLAIMER 🙈

Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. Consequently, public information is not available. Qualcomm Atheros reserves the right to modify message structure or content in future firmware releases without any obligation to notify or compensate users of this program.

like. they said what they said. 💀

✨ EXAMPLES ✨

Okay bestie, this is where it all comes together. Watch this one do its little thing:

# plcrule drop any IPv4SA is 192.168.99.2 IPv4DA is 192.168.99.100 add temp 00:B0:52:BA:BE:01

So what did we just do? This command adds a temporary classification rule to the classification table on device B00:B0:52:BA:BE:01. The rule tells the device to drop frames that match either (any) of two conditions. Condition one: the IPv4 source address is 192.168.99.2. Condition two: the IPv4 destination address is 192.168.99.100. Two conditions, one any, one vibe. 💅

Observe — and this is the part people get wrong — the action, operand and conditions come first, then the control and volatility, then the affected devices. Up to three conditions may be specified. Keyword order is important. Character case is not important. (So yes, IPv4SA and ipv4sa are the same girlie. 🫶)

Next up, the glow-up of just asking for a list. The following example prints a list of programmed keywords on stdout for reference. The example shown here has been abbreviate due to formatting limitations (not my typo, that's literally what the page says 😭):

# plcrule -t

  Controls are 'Add'|'Rem'|'Remove'
  Volatilities are 'Temp'|'Perm'
  Actions are 'CAP0'|'CAP1'|'CAP2'|'CAP3'|'Boost'|...|'StripTX'|'StripRX'|'TagRX'
  Operands are 'All'|'Any'|'Always'
  Fields are 'EthDA'|'EthSA'|'VLANUP'|'VLANID'|'IPv4TOS'|...|'TCPAck'|'VLANTag'
  Operators are 'Is'|'Not'

More example follow: 🌈

🌸 Ethernet Address Rules 🌸

Ethernet address rules have the following general format:

| CAP0 | ANY | EthSA | IS  | xx:xx:xx:xx:xx:xx | ADD    | TEMP | xx:xx:xx:xx:xx:xx
| CAP1 | ALL | EthDA | NOT |                   | REMOVE | PERM |
| CAP2 |
| CAP3 |
| DROP |

For example, instruct device 00:B0:52:BA:BE:FF to temporarily add a rule to forward frames from 00:2B:FE:CA:FE:BA at CAP3. Observe Ethernet hardware addresses are used both in the condition and for the affected powerline devices. Same format, two jobs, she's versatile like that. ✨

# plcrule cap3 any ethsa is 00:2b:fe:ca:fe:ba add temp 00:b0;52:ba:be:ff
Careful — that semicolon in 00:b0;52:ba:be:ff is exactly as written in the source. Copy it character for character, bestie, don't "fix" it. 🫣

💜 IP Address Rules 💜

IP address rules have the following general format:

| CAP0 | ANY | IPv4SA | IS  | ddd.ddd.ddd.ddd | ADD    | TEMP | xx:xx:xx:xx:xx:xx
| CAP1 | ALL | IPv4DA | NOT |                 | REMOVE | PERM |
| CAP2 |
| CAP3 |
| DROP |

For example, instruct device 00:B0:52:BA:BE:FF to permanently remove the rule that drops packets from 192.168.99.1. Notice that the IP address is specified in dotted decimal format but the device address is specified in hexadecimal octet format. Dotted decimal format permits empty and variable length octets but octet delimiters are mandatory. Hexadecimal octet format requires fixed length octets but octet delimiters are optional. It's giving two totally different dialects in one command and honestly? iconic. 👑

# plcrule drop any ipv4sa is 192.168.99.1 remove perm 00:b0:52:ba:be:ff

🦋 IP Protocol Rules 🦋

IP protocol rules have the following general format:

| CAP0 | ANY | IPv4PROT | IS  | xxxx | ADD    | TEMP | xx:xx:xx:xx:xx:xx
| CAP1 | ALL |          | NOT |      | REMOVE | PERM |
| CAP2 |
| CAP3 |
| DROP |

For example, to instruct device 00:B0:52:BA:BE:FF to permanently add a rule to forward non-IP packets at CAP2. In this example, delmiters have been omitted from the device Ethernet address. (Again — that spelling is straight from the source. I do not make the rules, I just relay them faithfully. 😌)

# plcrule CAP2 all ipv4prot not 0x0800 add perm 00b052babeff

🔗 SEE ALSO 🔗

👑 CREDITS 👑

Charles Maier

And that's the whole page, bestie. This one's from open-plc-utils-0.0.3, dated November 2013, and it lives at plcrule(1) in the manual. Now go forth and rule the powerline. 💖✨🎀

📦 where this page comes from