amprule(1)

💖 amprule 💖

Manual section 1, from the Qualcomm Atheros Open Powerline Toolkit 🧚

---

✨ NAME ✨

amprule - Stream Classification Utility 💅

---

🎀 SYNOPSIS 🎀

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

Where each condition is just a field operator value sequence 🫶

---

🦋 DESCRIPTION 🦋

Okay so amprule is how you format and send stream classification rules to one or more devices 💖. A rule says what to do when a frame meets its selection criteria. Those criteria are one, two, or three conditions, and any or all of them have to be satisfied. Each condition is a field type, a relational operator, and a value. You can add rules to a device or remove them from one, so they can have permanent or temporary effect ✨.

Classification rules are cumulative 🌈 ngl this is the part to watch. If a new rule set is identical to an old one, you'll get an error, unless it has a different Transmission Action. In that case, the old rule gets replaced. Identical rule sets are also allowed if one of them is tied to a VLAN tag action. Classification happens on the original frame, before it gets altered by VLAN Tag insertion or removal 🔁.

Classification is multi-dimensional, so the terminology might feel weird at first 🙈. For the full tea, check the Qualcomm Atheros Firmware Technical Reference Manual entry for the VS_CLASSIFICATION management message 📖.

This program is part of the Qualcomm Atheros Powerline Toolkit. For an overview and installation instructions, see the plc man page 🧚.

---

⭐ OPTIONS ⭐

• -e — bestie, this one redirects stderr messages over to stdout 🫶. The usual convention is that status and error messages go to stderr while the main output goes to stdout. This flag puts all output on stdout for when that's what you need 💅.
• -i interface — picks the host Ethernet interface 🌸. All requests get sent through this host interface, and only responses that come back through it are recognized 👀. The default is eth1, because most people use eth0 as their main network connection. BUT if the environment string PLC is defined, it takes precedence over the default 💜. And then this option beats either default ✨.
• -q — silences the status messages on stderr 🤫.
• -r — reads rules from a device and displays them on stdout 📖.
• -s — prints a list of program keywords on stdout 📝. This one overrides all the others, except -? and -!, and then the program just terminates with no further action 💀.
• -t milliseconds — sets the 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 🧚. It's a 32-bit hexadecimal integer with an optional 0x prefix.

Heads up, bestie: -T is required for action TagTX and must be omitted for every other action 🙅

• -v — prints additional information on stdout 🔍. In particular, it dumps incoming and outgoing packets, which you can save as text files for reference 📁.
• -V version — the CSPEC version number, expressed as a small decimal integer 🔢. It's required (and should be 2) for action TagTX, and must be omitted for all other actions.
• -?, --help — prints the program help summary on stdout 🆘. This one takes precedence over the other options on the command line 👑.
• -!, --version — prints the program version information on stdout 🌈. It also takes precedence over the other options on the command line. Use this one when sending screen dumps to Atheros Technical Support, so they know exactly which version of the Linux Toolkit you're using 🫶.

💖 FIELDS 💖

okay bestie, fields tell the rule which part of the frame to inspect, and they also set the size and format of the value you're allowed to use in a condition 🧚 they're alphanumeric strings, so type them in UPPER, lower, or MiXeD, we don't judge 🫶 if you type a field that doesn't exist, you'll get an error that lists the permitted ones, so you're never left guessing 😭

• ET: a 16-bit Ethertype 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. Octets can be split up with optional colons for clarity. The format is described in IEEE Standard 802-2001 [4] 🦋
• EthSA: a 48-bit Ethernet source address in hexadecimal. Octets can be split up 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 works for either TCP or UDP packets, depending on the protocol, and it's only valid for the actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop" 💅
• IPDP: a 16-bit IP destination port as a decimal integer. Same deal as IPSP: it works for TCP or UDP depending on the protocol, and it's only valid for the actions "CAP0", "CAP1", "CAP2", "CAP3" and "Drop" 💅
• IPV4TOS: an 8-bit Type-of-Service code. 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 IPv4 source 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" 🔥
• IPV4DA: a 32-bit IPv4 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 IPv6 traffic class, expressed as defined in RFC 2460 (Internet Protocol Version 6) [17] 🌈
• IPV6FL: a 24-bit IPv6 flow label. 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 🧚
• 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 show up, 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 show up, 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, written as a hex byte stream. For clarity, the recommended format is "xx:xxxx". The first byte is the MMV, and the next two bytes are the MMTYPE. Both are defined in the HomePlug AV Specification. The MMTYPE matches 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", depending on whether the frame is (or isn't) a TCP Acknowledgement. Double negatives are allowed, so "Is True" is equivalent to "Not False", and "Is False" is equivalent to "Not True" 🫶
• 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. 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. 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 show whether one or more VLAN Tags are in the frame (or aren't). This classifier is basically the same as "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 shows the equality between a field and a value 💅 it's an alphanumeric string, so again, UPPER, lower or MiXeD all work. Type an unknown operator and you'll get an error that lists the permitted ones 😭 operators are position sensitive, so they have to sit between each field and value.

• Is: the frame field has to equal the associated value for the condition to evaluate true 🌸
• Not: the frame field must not equal the associated value for the condition to evaluate true 🙈

---

🌈 STATES 🌈

a state is just a special kind of value ✨

• True, On, Yes, Present: a positive state or presence of some entity. They're all equivalent and interchangeable 💖 Double negatives are permitted, so "Is True" is equivalent to "Not False" 🫶
• False, Off, No, Missing: a negative state or absence of some entity. They're all equivalent and interchangeable 💜 Double negatives are permitted, so "Is False" is equivalent to "Not True" 🫶

---

🦋 CONTROLS 🦋

the control decides how the devices handle the rule once it's validated 👑 it's a discrete alphanumeric string (again, any case goes), and a typo gets you an error listing the permitted controls 💀 the control is position sensitive, so it has to come after the condition and before the volatility.

• Add: adds the rule to the current list of rules, unless a violation happens. Sometimes a rule replaces an existing rule instead of getting added ⭐
• Rem, Remove: removes the rule from the current list of rules, unless a violation happens 🔥

---

🌸 VOLATILITY 🌸

the volatility decides which device rule set gets affected by the action 💅 it's also a discrete alphanumeric string in any case, and a wrong entry gets you an error that lists the permitted volatilities 😭 it's position sensitive too, so it has to come after the control.

• Temp: the temporary rule set gets modified. It lives in the working PIB, which is stored in SDRAM 🧚
• Perm: the permanent rule set gets modified. It lives in the user PIB, which is 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 any case you like. Octets can be separated with colons for clarity. For example, "00b052000001", "00:b0:52:00:00:01" and "00b052:000001" are all valid and equivalent ✨

The following MAC addresses are special, so you can enter them 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 that wasn't 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 that wasn't manufactured by Atheros 👑

---

📚 REFERENCES 📚

check out the Qualcomm Atheros HomePlug AV Firmware Technical Reference Manual for more info 🤓

---

⚠️ DISCLAIMER ⚠️

Atheros HomePlug AV Vendor Specific Management Message structure and content is proprietary to Qualcomm Atheros, Ocala FL USA. Because of that, public information isn't available. Qualcomm Atheros reserves the right to change the message structure or content in future firmware releases, without any obligation to notify or compensate users of this program 🙅‍♀️

✨ EXAMPLES ✨

okay bestie, this section is where the magic happens 🔮💅 So 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. Iconic. 🙈

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

Observe that 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, so don't go shuffling things around 😭. Character case is not important, so IPv4SA and ipv4sa are both giving the same energy. 💜

The following example prints a list of programmed keywords on stdout for reference. 📝 The example shown here has been abbreviated due to formatting limitations, so don't panic if it looks a little cut off 🫶.

# amprule -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 examples 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. Main character energy ✨

# amprule 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. 🤓

# amprule 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, delimiters have been omitted from the device Ethernet address, which is totally allowed 💅.

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

---

👑 SEE ALSO 👑

plc(1), amprate(1), ampstat(1), amptone(7)

💖 CREDITS 💖

Charles Maier 🫶

---

open-plc-utils-0.0.3 · November 2013 · amprule(1) 🌈 That's a wrap, bestie! Thanks for hanging with me through the whole manpage 💜✨