int6krule(1)

int6krule(1) — okay bestie, sit down, hydrate, because this one is a whole Stream Classification Utility from the Qualcomm Atheros Open Powerline Toolkit and it is genuinely iconic 💅

---

✨ NAME ✨

int6krule — Stream Classification Utility 🎀

📜 SYNOPSIS 📜

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

where condition is a field operator value sequence.

So like, the shape of a call is: some options, then an action, then an operand, then one to three conditions, and then — plot twist — a control and a volatility, and then as many devices as your little heart desires. And yeah, a condition is literally a field operator value sequence. No cap.

🌸 DESCRIPTION 🌸

This tool formats stream classification rules and sends them off to one or more devices. A rule is basically "when a frame matches this, do that." The "do that" is the action, and the "matches this" is the selection criteria 💖

Selection criteria is made of one, two or three conditions, and the rule says either any or all of them have to be satisfied. Each condition is three things glued together: a field type, a relational operator, and a value. You can add rules to a device or remove rules from a device, so they can hit different — permanent vibes or temporary vibes, your call ✨

Now, classification rules are cumulative. That means if a new rule set is identical to an old rule set, you get an error — unless it contains a different Transmission Action, in which case the old rule gets replaced. Also, identical classification rule sets are permitted if one of the sets is associated with a VLAN tag action. And important: classification is based on the original frame before it gets altered by VLAN Tag insertion or removal. Periodt.

Classification is multi-dimensional, so the terminology here is gonna seem strange at first — that's normal, don't panic 🦋. Go read the Qualcomm Atheros Firmware Technical Reference Manual description of the VS_CLASSIFICATION management message for the 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 🎀

• -e — Redirects stderr messages to stdout. By convention, status and error messages go to stderr while the primary program output goes to stdout. This option prints all output on stdout, for when that's the vibe you want.
• -i interface — Pick the host Ethernet interface. All requests go out through this host interface, and only responses that come back through this host interface get recognized. The default interface is eth1, because most people use eth0 as their principle network connection. However, if the environment string PLC is defined, it takes precedence over the default interface. And this option then takes precedence over either default. Hierarchy, bestie 💅
• -r — Read rules from a device and display them on stdout. 👀
• -q — Suppresses status messages on stderr. Shhh.
• -s — Print a list of program keywords on stdout. This one overrides all others except -? and -!, and the program terminates without further action. It said what it said.
• -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're transmitted. The tag is a 32-bit hexadecimal integer with an optional "0x" prefix. This option is required for action TagTX and must be omitted for all other actions.

ngl, in the source page this one runs straight into the tail end of -t's paragraph with zero warning 😭 but it is absolutely its own option, bestie.

• -v — Print additional information on stdout. Specifically, this dumps incoming and outgoing packets, which you can save as text files for reference. Screenshot era 📸
• -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 one when you're sending screen dumps to Atheros Technical Support so they know exactly which version of the Linux Toolkit you're using. Very "receipts" of you 🫶

---

🧚 ARGUMENTS 🧚

• action — The action to be taken for frames that meet any (or all) selection criteria. Valid actions are listed and described under ACTIONS.
• operand — Specifies the logical relationship between conditions, before the action gets taken. Valid operands are listed and described under OPERANDS.
• condition — A conditional expression consisting of a field, operator and value. See CONDITIONS for more info.
• control — Specifies the action the device should take upon receipt of the rule. The basic moves are adding it to, or removing it from, the list of existing rules. Valid controls are listed and described under CONTROLS.
• 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. You can put more than one address on the command line, and if you do, 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 the selection criteria. They're written as discrete alphanumeric strings, and you can type them in upper, lower or mixed character case. They are position sensitive 📍 And if you type something that isn't a known action, you'll get an error message that lists the permitted actions. Rude but helpful.

• CAP0, CAP1, CAP2, CAP3 — Assign a specific Channel Access Priority to frames.
• Drop, DropTX — Do not forward frames over powerline. Bye 👋
• 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. No tag, no version, no service 🎀

---

🌈 OPERANDS 🌈

The operand tells you the logical relationship that has to exist between the conditions in the rule set before the action gets applied to a frame. Operands are discrete alphanumeric strings, typed in upper, lower or mixed character case. Type a bad one and you'll get an error message listing the permitted operands. They are position sensitive 📍 You get one operand, and it must appear after the action and before any condition.

• 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. Main character energy, honestly 👑

---

💜 CONDITIONS 💜

A condition = 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.

• field — The part of the Ethernet frame to be examined. Some fields aren't valid for some actions, but this program does not enforce that, since validation is performed by runtime firmware on each device. Recognized fields are listed and described under FIELDS.
• operator — Specifies the relationship that must exist between the field and the value in order for the condition to evaluate True. Currently, only equality operators are supported. Valid operators are listed and described under OPERATORS.
• 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. Know your bits, bestie 🧠✨

---

✨ FIELDS ✨

Okay bestie, fields are literally the main characters of this whole thing 💅 A field tells you which part of the frame gets inspected when the rule does its selection thing, AND it tells you the size and format of the value you're allowed to drop into the condition statement. You write them as discrete alphanumeric strings, and you can type them in UPPER, lower, or MiXeD case — she does not care 🫶

If you type a field that isn't a thing, you get an error message that lists all the fields that are a thing. Rude? No. Helpful? Yes. It's giving "here's the menu, girl" 🍓

• 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 in hexadecimal. You can separate the octets with colons for clarity if you want, purely aesthetic. The format is described in IEEE Standard 802-2001 [4].
• EthSA — a 48-bit Ethernet source address 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 as a decimal integer. This condition applies to either TCP or UDP packets, depending on which protocol is in play, and it's valid only for the actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop".
• IPDP — a 16-bit IP destination port as a decimal integer. Same deal: applies to either TCP or UDP depending on the protocol, and valid only for the actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop".
• IPV4TOS — an 8-bit Type-of-Service code, where the format is defined in RFC 791 (Internet Protocol) [14].
• IPV4PROT — an 8-bit Ethernet protocol code. The format is defined in RFC 791 (Internet Protocol) [14].
• IPV4SA — a 32-bit Internet Protocol source address in dotted-decimal notation. The official format is defined in RFC 791 (Internet Protocol) [14]. Our implementation is chill and 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 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 (Internet Protocol Version 6) [17]. The upper 4 bits should be zero. You can enter the value as a decimal, binary or hex integer, your call 💁‍♀️
• IPV6SA — a 128-bit IPV6 source address, written 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 occurrence 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, written 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 occurrence 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 recommended format is "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 — Request, Confirm, Indicate and Response — because the lower two bits are ignored. This field is only valid for the action "Boost".
• TCPAck — the string "True" or "False", saying whether the frame is (or is not) a TCP Acknowledgement. Double negatives are allowed, so "Is True" is equivalent to "Not False" and "Is False" is equivalent to "Not True". Yes bestie, you can be messy about it 💀
• 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 as a decimal integer. The format is defined in RFC 793 (Transmission Control Protocol) [15].
• UDPSP — a 16-bit UDP source port as a decimal integer. The format is defined in RFC 768 (User Datagram Protocol) [13].
• UDPDP — a 16-bit UDP destination port 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", saying whether one or more VLAN Tags are present (or absent) 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 says there's an equality between a field and a value. It's an alphanumeric string, and again you can write it in upper, lower or mixed case — she's not picky 💜

Type an operator nobody knows and you'll get an error message listing the permitted operators. Consider it a vibe check that you failed, but gently.

Operators are position sensitive, bestie. They have to sit between each field and value. No skipping, no rearranging, that's just the rules ✨

• 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 a special case of value. Like, a value with main character energy 👑

• True,On,Yes,Present — indicates a positive state or the presence of some entity. All of these are equivalent and can be used interchangeably. Double negatives are permitted, so "Is True" is equivalent to "Not False".
• False,Off,No,Missing — indicates a negative state or the absence of some entity. All of these are equivalent and can be used interchangeably. Double negatives are permitted, so "Is False" is equivalent to "Not True".

---

💅 CONTROLS 💅

The control decides how the devices will handle the rule after it's been validated. It's a discrete alphanumeric string, entered in upper, lower or mixed character case.

Enter a control that doesn't exist and boom 💥 error message listing the permitted controls. The more you know 🌈

The control is position sensitive and must occur after condition and before volatility. Do not shuffle her.

• 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 legal.
• Rem,Remove — removes the rule from the current list of rules unless a violation occurs.

---

⭐ VOLATILITY ⭐

The volatility decides which device rule set is gonna be affected by the action. It's a discrete alphanumeric string, upper/lower/mixed case, you know the drill by now 🫶

Unknown volatility? You guessed it — error message, list of permitted volatilities, moment of reflection 🙈

The volatility is position sensitive and must occur after 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. Octets may be separated with colons for clarity. For example, these are all valid and equivalent, no cap:

00b052000001
00:b0:52:00:00:01
00b052:000001

The following MAC addresses are special and may be entered by name instead of by number. Little shortcuts, we love her ✨

• 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. Everybody hears this one 📢
• 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. It's giving private group chat 💬

---

🌈 REFERENCES 🌈

See the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more information. Go read the lore, bestie 📚

---

💀 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. So yeah — they can change it whenever and you just have to deal 😭

✨ EXAMPLES ✨

Okay bestie, here's where it all clicks. 💖

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.

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

Notice the order, bestie: 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. 😌

---

The next example prints a list of programmed keywords on stdout for reference. The example shown here has been abbreviate due to formatting limitations. 🎀

# int6krule -s

  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 that Ethernet hardware addresses are used both in the condition and for the affected powerline devices. 💅

# int6krule cap3 any ethsa is 00:2b:fe:ca:fe:ba add temp 00:b0;52:ba:be:ff

🦋 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. iykyk 😌

# int6krule 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. 🫶

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

---

👀 SEE ALSO 👀

plc(1), int6krate(1), int6kstat(1), int6ktone(7)

💖 CREDITS 💖

Charles Maier

---

And that's the whole page, bestie — you made it to the end, iconic behavior honestly. 🌟 This one's from open-plc-utils-0.0.3, dated November 2013, and yeah it's int6krule(1) if you forgot already (you didn't). Now go forth and classify those frames. periodt. 💅✨