EBTABLES-LEGACY(8)

📦
version 2.0.11 · 4 versions
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 EBTABLES-LEGACY(8) 💖

okay bestie, welcome to the System Manager's Manual page for ebtables-legacy — the legacy Ethernet bridge frame table administration tool. yes it's a mouthful, i know. let's get into it 🫶

✨ SYNOPSIS ✨

ebtables [-t table ] -[ACDI] chain rule specification [match extensions]
[watcher extensions] target
ebtables [-t table ] -P chain ACCEPT | DROP | RETURN
ebtables [-t table ] -F [chain]
ebtables [-t table ] -Z [chain]
ebtables [-t table ] -L [-Z] [chain] [ [--Ln] | [--Lx] ] [--Lc]
[--Lmac2]
ebtables [-t table ] -N chain [-P ACCEPT | DROP | RETURN]
ebtables [-t table ] -X [chain]
ebtables [-t table ] -E old-chain-name new-chain-name
ebtables [-t table ] --init-table
ebtables [-t table ] [--atomic-file file] --atomic-commit
ebtables [-t table ] [--atomic-file file] --atomic-init
ebtables [-t table ] [--atomic-file file] --atomic-save

🚨 LEGACY 🚨

bestie, listen. this tool uses the old xtables/setsockopt framework, and it is a legacy version of ebtables. that means a new, more modern tool exists with the same functionality using the nf_tables framework, and you are encouraged to migrate now. 💅 the new binaries (known as ebtables-nft and formerly known as ebtables-compat) use the same syntax and semantics than this legacy one.

you can still use this legacy tool. you should probably get some specific information from your Linux distribution or vendor tho. more docs are available at https://wiki.nftables.org 📚

🌈 DESCRIPTION 🌈

ebtables is an application program used to set up and maintain the tables of rules (inside the Linux kernel) that inspect Ethernet frames. it's analogous to the iptables application, but less complicated — because the Ethernet protocol is much simpler than the IP protocol. lowkey a slay. 🧚

🎀 CHAINS 🎀

there are three ebtables tables with built-in chains in the Linux kernel. these tables are used to divide functionality into different sets of rules. each set of rules is called a chain. 📋

each chain is an ordered list of rules that can match Ethernet frames. if a rule matches an Ethernet frame, then a processing specification tells what to do with that matching frame. that processing specification is called a 'target'. 🎯

but if the frame does not match the current rule in the chain, then the next rule in the chain is examined and so forth. the user can create new (user-defined) chains that can be used as the 'target' of a rule. user-defined chains are very useful to get better performance over the linear traversal of the rules and are also essential for structuring the filtering rules into well-organized and maintainable sets of rules. 💖

🔥 TARGETS 🔥

a firewall rule specifies criteria for an Ethernet frame and a frame processing specification called a target. when a frame matches a rule, then the next action performed by the kernel is specified by the target.

the target can be one of these values: ACCEPT, DROP, CONTINUE, RETURN, an 'extension' (see below) or a jump to a user-defined chain.

  • ACCEPT — means to let the frame through. 🟢
  • DROP — means the frame has to be dropped. 🔴 in the BROUTING chain however, the ACCEPT and DROP target have different meanings (see the info provided for the -t option).
  • CONTINUE — means the next rule has to be checked. this can be handy, f.e., to know how many frames pass a certain point in the chain, to log those frames or to apply multiple targets on a frame. 👀
  • RETURN — means stop traversing this chain and resume at the next rule in the previous (calling) chain. ↩️

for the extension targets please refer to the TARGET EXTENSIONS section of this man page. (that's coming in a later part bestie, stay with me 💜)

👑 TABLES 👑

as stated earlier, there are three ebtables tables in the Linux kernel. the table names are filter, nat and broute. of these three tables, the filter table is the default table that the command operates on. 🌟

if you are working with the filter table, then you can drop the -t filter argument to the ebtables command. however, you will need to provide the -t argument for the other two tables. moreover, the -t argument must be the first argument on the ebtables command line, if used. ⚠️

  • -t, --table — filter is the default table and contains three built-in chains: INPUT (for frames destined for the bridge itself, on the level of the MAC destination address), OUTPUT (for locally-generated or (b)routed frames) and FORWARD (for frames being forwarded by the bridge). 💫

nat is mostly used to change the mac addresses and contains three built-in chains: PREROUTING (for altering frames as soon as they come in), OUTPUT (for altering locally generated or (b)routed frames before they are bridged) and POSTROUTING (for altering frames as they are about to go out). a small note on the naming of chains PREROUTING and POSTROUTING: it would be more accurate to call them PREFORWARDING and POSTFORWARDING, but for all those who come from the iptables world to ebtables it is easier to have the same names. note that you can change the name (-E) if you don't like the default. 🙈

broute is used to make a brouter, it has one built-in chain: BROUTING. the targets DROP and ACCEPT have a special meaning in the broute table (these names are used instead of more descriptive names to keep the implementation generic). DROP actually means the frame has to be routed, while ACCEPT means the frame has to be bridged. the BROUTING chain is traversed very early. however, it is only traversed by frames entering on a bridge port that is in forwarding state. normally those frames would be bridged, but you can decide otherwise here. the redirect target is very handy here. 🔀

💅 EBTABLES COMMAND LINE ARGUMENTS 💅

after the initial ebtables '-t table' command line argument, the remaining arguments can be divided into several groups. these groups are commands, miscellaneous commands, rule specifications, match extensions, watcher extensions and target extensions. 🗂️

🫶 COMMANDS 🫶

the ebtables command arguments specify the actions to perform on the table defined with the -t argument. if you do not use the -t argument to name a table, the commands apply to the default filter table.

⚠️ only one command may be used on the command line at a time, except when the commands -L and -Z are combined, the commands -N and -P are combined, or when --atomic-file is used.
  • -A, --append — Append a rule to the end of the selected chain. ➕
  • -D, --delete — Delete the specified rule or rules from the selected chain. there are two ways to use this command:
    1. the first is by specifying an interval of rule numbers to delete (directly after -D). syntax: start_nr[:end_nr] (use -L --Ln to list the rules with their rule number). when end_nr is omitted, all rules starting from start_nr are deleted. using negative numbers is allowed, for more details about using negative numbers, see the -I command. 🗑️
    2. the second usage is by specifying the complete rule as it would have been specified when it was added. only the first encountered rule that is the same as this specified rule, in other words the matching rule with the lowest (positive) rule number, is deleted.
  • -C, --change-counters — Change the counters of the specified rule or rules from the selected chain. there are two ways to use this command:
    1. the first is by specifying an interval of rule numbers to do the changes on (directly after -C). syntax: start_nr[:end_nr] (use -L --Ln to list the rules with their rule number). the details are the same as for the -D command. 📊
    2. the second usage is by specifying the complete rule as it would have been specified when it was added. only the counters of the first encountered rule that is the same as this specified rule, in other words the matching rule with the lowest (positive) rule number, are changed.

in the first usage, the counters are specified directly after the interval specification, in the second usage directly after -C. first the packet counter is specified, then the byte counter. 🔢

  • if the specified counters start with a '+', the counter values are added to the respective current counter values.
  • if the specified counters start with a '-', the counter values are decreased from the respective current counter values.
  • no bounds checking is done. 💀
  • if the counters don't start with '+' or '-', the current counters are changed to the specified counters.
  • -I, --insert — Insert the specified rule into the selected chain at the specified rule number. if the rule number is not specified, the rule is added at the head of the chain. if the current number of rules equals N, then the specified number can be between -N and N+1. for a positive number i, it holds that i and i-N-1 specify the same place in the chain where the rule should be inserted. the rule number 0 specifies the place past the last rule in the chain and using this number is therefore equivalent to using the -A command. rule numbers strictly smaller than 0 can be useful when more than one rule needs to be inserted in a chain. 🪄
  • -P, --policy — Set the policy for the chain to the given target. the policy can be ACCEPT, DROP or RETURN. 👑
  • -F, --flush — Flush the selected chain. if no chain is selected, then every chain will be flushed. flushing a chain does not change the policy of the chain, however. 🧹
  • -Z, --zero — Set the counters of the selected chain to zero. if no chain is selected, all the counters are set to zero. the -Z command can be used in conjunction with the -L command. when both the -Z and -L commands are used together in this way, the rule counters are printed on the screen before they are set to zero. 0️⃣

more of this iconic page coming right up bestie, don't go anywhere 💖

  • -L, --list — bestie, this one lists every rule in the chain you picked. If you didn't pick a chain? It lists all of them. no cap. 💅

The following options change what -L actually spits out:

  • --Ln — puts the rule number right up front on every rule, so you can actually find the one you're looking for 🙈. This option is incompatible with the --Lx option — they do not vibe together, pick one.
  • --Lc — shows the counters at the end of each rule that -L displays. You get both a frame counter (pcnt) and a byte counter (bcnt). The frame counter tells you how many frames matched that specific rule; the byte counter is the sum of the frame sizes of all those matching frames. Plot twist: if you use this together with the --Lx option, the counters get written out in the -c <pcnt> <bcnt> option format.
  • --Lx — changes the output so it produces a whole set of ebtables commands that construct the contents of the chain (when a chain is specified). If you didn't specify a chain, you get ebtables commands that construct the contents of the table, including the commands for creating the user-defined chains (if there are any) 👑. You can drop this set of commands straight into an ebtables boot or reload script — like, the output could genuinely be used at system startup. The --Lx option is incompatible with the --Ln listing option. And if you use --Lx together with --Lc, the counters get written out in the -c <pcnt> <bcnt> option format.
  • --Lmac2 — shows all MAC addresses at the same length, adding leading zeroes when it needs to. The default representation just omits those leading zeroes in the addresses. ✨
  • -N, --new-chain — makes a brand new user-defined chain with the name you give it 🎀. The number of user-defined chains is limited only by the number of possible chain names. A user-defined chain name has a maximum length of 31 characters. The standard policy of the user-defined chain is ACCEPT. Wanna set a different standard target as the policy? Use the -P command together with the -N command — and in that case, the chain name does not have to be specified for the -P command.
  • -X, --delete-chain — deletes the user-defined chain you point at. Careful though: there must be no remaining references (jumps) to that chain, otherwise ebtables will flat-out refuse to delete it. If you don't specify a chain at all, every user-defined chain that isn't referenced gets removed.
  • -E, --rename-chain — renames the chain you specify to a new name. And it's not just user-defined chains — you can rename a standard chain to a name that suits your taste, main character energy fr fr. Like, if you like PREFORWARDING more than PREROUTING, you can use the -E command to rename the PREROUTING chain. But listen: if you do rename one of the standard ebtables chain names, please be sure to mention this fact if you ever post a question on the ebtables mailing lists, and it'd be wise to use the standard name in your post. Renaming a standard ebtables chain this way has no effect on the structure or functioning of the ebtables kernel table.
  • --init-table — replaces the current table data with the initial table data. fresh start bestie 🌸
  • --atomic-init — copies the kernel's initial data of the table into the file you specify. Use it as the first action, then add rules to the file after. The file can be specified with the --atomic-file command or through the EBTABLES_ATOMIC_FILE environment variable.
  • --atomic-save — copies the kernel's current data of the table into the file you specify. Same deal: use it as the first action, then add rules to the file. The file can be specified with the --atomic-file command or through the EBTABLES_ATOMIC_FILE environment variable.
  • --atomic-commit — replaces the kernel table data with the data sitting in the file you specify 🔥. This one is genuinely useful: it lets you load all your rules of a certain table into the kernel at once, which saves the kernel a whole lot of precious time and allows atomic updates of the tables. How you build that file: use either --atomic-init or --atomic-save to generate a starting file, then use the --atomic-file command when constructing rules (or set the EBTABLES_ATOMIC_FILE environment variable) so you can extend the file and build the complete table before committing it to the kernel. Boot scripts love this one for populating ebtables tables fast. 👑

🎀 MISCELLANEOUS COMMANDS 🎀

  • -V, --version — shows the version of the ebtables userspace program. simple as that 💖
  • -h, --help [list of module names] — gives a brief description of the command syntax. And here's the cute part: you can also pass names of extensions and ebtables will try to write help about those extensions. E.g. ebtables -h snat log ip arp. Wanna see everything? Pass list_extensions and it'll list all the extensions supported by the userspace utility. 🦋
  • -j, --jump target — the target of the rule. This is one of the following values: ACCEPT, DROP, CONTINUE, RETURN, a target extension (see TARGET EXTENSIONS) or a user-defined chain name.
  • --atomic-file file — tells the command to operate on the file you specify. The data of the table it's operating on gets extracted from that file, and the result of the operation gets saved back into the file. Important: if you specify this, it should come before the command specification. And ngl, there's a preferred alternative: setting the EBTABLES_ATOMIC_FILE environment variable instead.
  • -M, --modprobe program — when it's talking to the kernel, use this program to try to automatically load any missing kernel modules.
  • --concurrent — uses a file lock so that concurrent scripts can update the ebtables kernel tables without stepping on each other. 🫶

🌈 RULE SPECIFICATIONS 🌈

Okay so these command line arguments are what actually make up a rule specification (the ones you use in the add and delete commands). A "!" placed before a specification inverts the test for that specification — flip the vibe, invert the match. And apart from these standard rule specifications, there are some other command line arguments you'll wanna know about. Peep both the MATCH EXTENSIONS and the WATCHER EXTENSIONS below. 💜

  • -p, --protocol [!] protocol — the protocol that was responsible for creating the frame. This can be a hexadecimal number, above 0x0600, a name (e.g. ARP) or LENGTH. Here's the lore: the protocol field of the Ethernet frame can be used to denote the length of the header (802.2/802.3 networks). When the value of that field is below or equals 0x0600, that value equals the size of the header and shouldn't be used as a protocol number. Instead, all frames where the protocol field is used as the length field are assumed to be of the same 'protocol'. The protocol name ebtables uses for these frames is LENGTH. The file /etc/ethertypes can be used to show readable characters instead of hexadecimal numbers for the protocols — for example, 0x0800 will be represented by IPV4. Using that file is not case sensitive. See that file for more information. Also: the flag --proto is an alias for this option.
  • -i, --in-interface [!] name — the interface (bridge port) via which a frame is received. This option is useful in the INPUT, FORWARD, PREROUTING and BROUTING chains. Cute trick: if the interface name ends with +, then any interface name that begins with this name (disregarding the +) will match. The flag --in-if is an alias for this option. 🍓
  • --logical-in [!] name — the (logical) bridge interface via which a frame is received. Also useful in the INPUT, FORWARD, PREROUTING and BROUTING chains. And yes, if the interface name ends with +, then any interface name that begins with this name (disregarding the +) will match.
  • -o, --out-interface [!] name — the interface (bridge port) via which a frame is going to be sent. This one's useful in the OUTPUT, FORWARD and POSTROUTING chains. Same + magic: if the interface name ends with +, then any interface name that begins with this name (disregarding the +) will match. The flag --out-if is an alias for this option. ✨
  • --logical-out [!] name — the (logical) bridge interface via which a frame is going to be sent. Useful in the OUTPUT, FORWARD and POSTROUTING chains. And yep — if the interface name ends with +, then any interface name that begins with this name (disregarding the +) will match.
  • -s, --source [!] address[/mask] — the source MAC address. Both the mask and the address are written as 6 hexadecimal numbers separated by colons. Alternatively you can specify Unicast, Multicast, Broadcast or BGA (Bridge Group Address):
Unicast=00:00:00:00:00:00/01:00:00:00:00:00
Multicast=01:00:00:00:00:00/01:00:00:00:00:00
Broadcast=ff:ff:ff:ff:ff:ff/ff:ff:ff:ff:ff:ff
BGA=01:80:c2:00:00:00/ff:ff:ff:ff:ff:ff
Heads up: a broadcast address will also match the multicast specification. 😭

The flag --src is an alias for this option.

  • -d, --destination [!] address[/mask] — the destination MAC address. See -s (above) for more details on MAC addresses. The flag --dst is an alias for this option.
  • -c, --set-counter pcnt bcnt — if you use this with -A or -I, the packet and byte counters of the new rule get set to pcnt and bcnt respectively. But if you use it with the -C or -D commands, only rules with a packet and byte count equal to pcnt and bcnt respectively will match. 👑

🌈 MATCH EXTENSIONS 🌈

Little know-how moment: ebtables extensions are dynamically loaded into the userspace tool, so there is no need to explicitly load them with a -m option like you do in iptables. 💅 These extensions deal with functionality supported by kernel modules that are supplemental to the core ebtables code.

802_3

Specify 802.3 DSAP/SSAP fields or SNAP type. Note: the protocol must be specified as LENGTH (see the option -p above).

  • --802_3-sap [!] sap — DSAP and SSAP are two one byte 802.3 fields. The bytes are always equal, so only one byte (hexadecimal) is needed as an argument. 🌸
  • --802_3-type [!] type — bestie, if the 802.3 DSAP and SSAP values are 0xaa, then you gotta go check the SNAP type field to figure out what the payload protocol actually is. This arg is two bytes, hexadecimal. Only 802.3 frames rocking DSAP/SSAP 0xaa get their type checked, periodt. 💅

✨ among ✨

Okay so this one matches a MAC address, or a MAC/IP address pair, against a whole list of MAC addresses and MAC/IP address pairs. Frames from a list go like this:

xx:xx:xx:xx:xx:xx[=ip.ip.ip.ip][,]

You separate multiple list entries with a comma, and giving the IP address that corresponds to the MAC address is optional — no pressure. You can specify multiple MAC/IP address pairs that share the same MAC address but have different IP addresses (and vice versa, obviously 💁). And if the MAC address doesn't match any entry in the list, the frame doesn't match the rule — unless you used !. Iconic.

  • --among-dst [!] list — compares the MAC destination against your list. And if the Ethernet frame has type IPv4 or ARP, then you can also compare against the MAC/IP destination address pairs from the list. 🎀
  • --among-src [!] list — compares the MAC source against your list. Same deal: if the Ethernet frame has type IPv4 or ARP, you can compare against the MAC/IP source address pairs from the list. ✨
  • --among-dst-file [!] file — same as --among-dst but the list gets read in from the file you named. 📄
  • --among-src-file [!] file — same as --among-src but the list gets read in from the file you named. 📄

🌸 arp 🌸

Use this to specify (R)ARP fields. Heads up: the protocol must be specified as ARP or RARP.

  • --arp-opcode [!] opcode — the (R)ARP opcode, decimal or as a string. Want more deets? Peep ebtables -h arp.
  • --arp-htype [!] hardware type — the hardware type. It can be a decimal, or the string Ethernet (which sets the type to 1). Most (R)ARP packets have Ethernet as their hardware type, fyi.
  • --arp-ptype [!] protocol type — the protocol type that the (r)arp is used for, hexadecimal, or the string IPv4 which denotes 0x0800. Most (R)ARP packets have protocol type IPv4, slay.
  • --arp-ip-src [!] address[/mask] — the (R)ARP IP source address specification. 💜
  • --arp-ip-dst [!] address[/mask] — the (R)ARP IP destination address specification. 💜
  • --arp-mac-src [!] address[/mask] — the (R)ARP MAC source address specification. 💜
  • --arp-mac-dst [!] address[/mask] — the (R)ARP MAC destination address specification. 💜
  • [!] --arp-gratuitous — checks for ARP gratuitous packets: it checks that the IPv4 source address and the IPv4 destination address inside the ARP header are equal. 🫶

⭐ ip ⭐

This is where you specify IPv4 fields. The protocol must be specified as IPv4.

  • --ip-source [!] address[/mask] — the source IP address. And ooh, --ip-src is an alias for this option. 💖
  • --ip-destination [!] address[/mask] — the destination IP address. --ip-dst is an alias for this option. 💖
  • --ip-tos [!] tos — the IP type of service, in hexadecimal numbers. IPv4, obviously.
  • --ip-protocol [!] protocol — the IP protocol. --ip-proto is an alias for this option. 💖
  • --ip-source-port [!] port1[:port2] — the source port, or port range, for the IP protocols 6 (TCP), 17 (UDP), 33 (DCCP) or 132 (SCTP). And the --ip-protocol option must be specified as TCP, UDP, DCCP or SCTP. If port1 is omitted, 0:port2 gets used; if port2 is omitted but you did put a colon, then port1:65535 gets used. --ip-sport is an alias for this option. 🦋
  • --ip-destination-port [!] port1[:port2] — the destination port, or port range, for IP protocols 6 (TCP), 17 (UDP), 33 (DCCP) or 132 (SCTP). Again the --ip-protocol option must be specified as TCP, UDP, DCCP or SCTP. If port1 is omitted, 0:port2 is used; if port2 is omitted but a colon is specified, port1:65535 is used. --ip-dport is an alias for this option. 🦋

🌈 ip6 🌈

Specify IPv6 fields here. The protocol must be specified as IPv6.

  • --ip6-source [!] address[/mask] — the source IPv6 address. --ip6-src is an alias for this option. 💖
  • --ip6-destination [!] address[/mask] — the destination IPv6 address. --ip6-dst is an alias for this option. 💖
  • --ip6-tclass [!] tclass — the IPv6 traffic class, in hexadecimal numbers.
  • --ip6-protocol [!] protocol — the IP protocol. --ip6-proto is an alias for this option. 💖
  • --ip6-source-port [!] port1[:port2] — the source port, or port range, for the IPv6 protocols 6 (TCP), 17 (UDP), 33 (DCCP) or 132 (SCTP). The --ip6-protocol option must be specified as TCP, UDP, DCCP or SCTP. If port1 is omitted, 0:port2 is used; if port2 is omitted but a colon is specified, port1:65535 is used. --ip6-sport is an alias for this option. 🦋
  • --ip6-destination-port [!] port1[:port2] — the destination port, or port range, for IPv6 protocols 6 (TCP), 17 (UDP), 33 (DCCP) or 132 (SCTP). The --ip6-protocol option must be specified as TCP, UDP, DCCP or SCTP. If port1 is omitted, 0:port2 is used; if port2 is omitted but a colon is specified, port1:65535 is used. --ip6-dport is an alias for this option. 🦋
  • --ip6-icmp-type [!] {type[:type]/code[:code]|typename} — specifies the ipv6-icmp type and code you wanna match. Ranges work for both type and code, and type and code are separated by a slash. Valid numbers for type and range are 0 to 255. If you just wanna match a single type including all valid codes, you can use symbolic names instead of numbers. The list of known type names is shown by this command:
ebtables --help ip6
⚠️ This option is only valid for --ip6-prococol ipv6-icmp.

💫 limit 💫

This module matches at a limited rate using a token bucket filter. A rule that uses this extension will match until this limit is reached. You can pair it with the --log watcher to get yourself some limited logging, for example. Using it is the same as the limit match in iptables. No cap.

  • --limit [value] — maximum average matching rate. Specify it as a number, with an optional /second, /minute, /hour, or /day suffix. The default is 3/hour. ⏳
  • --limit-burst [number] — maximum initial number of packets to match. This number gets recharged by one every time the limit above is not reached, all the way up to this number. The default is 5. 🔋

🎀 mark_m 🎀

  • --mark [!] [value][/mask] — matches frames with the given unsigned mark value. If you specify both a value and a mask, the logical AND of the frame's mark value and your user-specified mask gets taken before comparing it with your user-specified mark value. When only a mark value is specified, the packet only matches when the frame's mark value equals your user-specified mark value. If you specify only a mask, the logical AND of the frame's mark value and your user-specified mask is taken, and the frame matches when the result of that logical AND is non-zero. Pro tip from the source material: only specifying a mask is useful for matching multiple mark values. 💅

🔥 pkttype 🔥

  • --pkttype-type [!] type — matches on the Ethernet "class" of the frame, which gets determined by the generic networking code. Possible values: broadcast (MAC destination is the broadcast address), multicast (MAC destination is a multicast address), host (MAC destination is the receiving network device), or otherhost (none of the above). 👑

🧚 stp 🧚

Specify stp BPDU (bridge protocol data unit) fields here. The destination address (-d) must be specified as the bridge group address (BGA). And for every option where you can specify a range of values, this rule holds: if the lower bound is omitted (but the colon is not), then the lowest possible lower bound for that option is used. While if the upper bound is omitted (but, again, the colon is not), the highest possible upper bound for that option is used. Ik, it's giving very specific, but we love that for us. ✨

  • --stp-type [!] type — the BPDU type (0-255). Recognized non-numerical types are config, denoting a configuration BPDU (=0), and tcn, denoting a topology change notification BPDU (=128).
  • --stp-flags [!] flag — the BPDU flag (0-255). Recognized non-numerical flags are topology-change, denoting the topology change flag (=1), and topology-change-ack, denoting the topology change acknowledgement flag (=128).
  • --stp-root-prio [!] [prio][:prio] — the root priority (0-65535) range.
  • --stp-root-addr [!] [address][/mask] — the root mac address. See the option -s for more details. 💜
  • --stp-root-cost [!] [cost][:cost] — the root path cost (0-4294967295) range.
  • --stp-sender-prio [!] [prio][:prio] — the BPDU's sender priority (0-65535) range.
  • --stp-sender-addr [!] [address][/mask] — the BPDU's sender mac address. See the option -s for more details. 💜
  • --stp-port [!] [port][:port] — the port identifier (0-65535) range.
  • --stp-msg-age [!] [age][:age] — the message age timer (0-65535) range.
  • --stp-max-age [!] [age][:age] — the max age timer (0-65535) range.
  • --stp-hello-time [!] [time][:time] — the hello time timer (0-65535) range.
  • --stp-forward-delay [!] [delay][:delay] — the forward delay timer (0-65535) range.

🍓 string 🍓

This module matches on a given string using some pattern matching strategy. Obsessed.

  • --string-algo algorithm — the pattern matching strategy. (bm = Boyer-Moore, kmp = Knuth-Pratt-Morris)
  • --string-from offset — the lowest offset from which a match can start. (default: 0)
  • --string-to offset — the highest offset from which a match can start. (default: size of frame)
  • --string [!] pattern — matches the given pattern.
  • --string-hex [!] pattern — matches the given pattern in hex notation, e.g. '|0D 0A|', '|0D0A|', 'www|09|netfilter|03|org|00|'
  • --string-icase — ignore case when searching. 🙈

🌟 vlan 🌟

Specify 802.1Q Tag Control Information fields here. The protocol must be specified as 802_1Q (0x8100).

  • --vlan-id [!] id — the VLAN identifier field (VID). A decimal number from 0 to 4095. 💖
  • --vlan-prio [!] prio — the user priority field, a decimal number from 0 to 7. The VID should be set to 0 ("null VID") or left unspecified (in that latter case the VID is deliberately set to 0).
  • --vlan-encap [!] type — the encapsulated Ethernet frame type/length. Specify it as a hexadecimal number from 0x0000 to 0xFFFF, or as a symbolic name from /etc/ethertypes. 📄

✨ WATCHER EXTENSIONS ✨

Okay so watchers are the softest lil angels in this whole operation 🫶 — they literally only look at frames passing by. They do not modify them, they do not decide whether the frames get accepted or not, none of that. And bestie, they only ever see the frame if the frame matches the rule, and they see it before the target is executed. Observers, not meddlers. 💅

🎀 log

The log watcher writes descriptive data about a frame to the syslog.

  • --log — logs with the default logging options: log-level= info, log-prefix="", no ip logging, no arp logging.
  • --log-level level — sets the logging level. For the possible values, go look at ebtables -h log. Default level is info.
  • --log-prefix text — sets the prefix text that gets printed at the beginning of the line with the logging info.
  • --log-ip — will log the ip information when a frame made by the ip protocol matches the rule. Default is no ip information logging.
  • --log-ip6 — will log the ipv6 information when a frame made by the ipv6 protocol matches the rule. Default is no ipv6 information logging.
  • --log-arp — will log the (r)arp information when a frame made by the (r)arp protocols matches the rule. Default is no (r)arp information logging.

🦋 nflog

The nflog watcher hands the packet over to whatever logging backend is loaded, so it can log the packet. Usually you pair this with nfnetlink_log as the logging backend — that one multicasts the packet through a netlink socket to the specified multicast group, and one or more userspace processes can subscribe to that group to receive the packets. Networking but make it ✨networking✨.

  • --nflog — log with the default logging options.
  • --nflog-group nlgroup — the netlink group (1 - 2^32-1) to which packets are sent (only applicable for nfnetlink_log). Default is 1.
  • --nflog-prefix prefix — a prefix string to include in the log message, up to 30 characters long, useful for telling messages apart in the logs. iykyk.
  • --nflog-range size — the number of bytes to be copied to userspace (only applicable for nfnetlink_log). nfnetlink_log instances may specify their own range, and this option overrides it.
  • --nflog-threshold size — number of packets to queue inside the kernel before sending them to userspace (only applicable for nfnetlink_log). Higher values mean less overhead per packet, but more delay until the packets reach userspace. Default is 1.

🌈 ulog

The ulog watcher passes the packet to a userspace logging daemon using netlink multicast sockets. How is this different from the log watcher, you ask? Bestie, two things: the complete packet gets sent to userspace instead of a descriptive text, and it uses netlink multicast sockets instead of the syslog. This watcher is what lets you parse packets with userspace programs, and the physical bridge in and out ports are also included in the netlink messages. 👑

The ulog watcher module takes 2 parameters when the module is loaded into the kernel (e.g. with modprobe):

  • nlbufsiz — specifies how big the buffer for each netlink multicast group is. If you say nlbufsiz=8192, for example, up to eight kB of packets will get accumulated in the kernel until they're sent to userspace. It is not possible to allocate more than 128kB. Also please keep in mind that this buffer size is allocated for each nlgroup you're using, so total kernel memory usage increases by that factor. The default is 4096.
  • flushtimeout — specifies after how many hundredths of a second the queue should be flushed, even if it's not full yet. The default is 10 (one tenth of a second).

Options:

  • --ulog — use the default settings: ulog-prefix="", ulog-nlgroup=1, ulog-cprange=4096, ulog-qthreshold=1.
  • --ulog-prefix text — defines the prefix included with the packets sent to userspace.
  • --ulog-nlgroup group — defines which netlink group number to use (a number from 1 to 32). Make sure the netlink group numbers used for the iptables ULOG target differ from those used for the ebtables ulog watcher. Default group number is 1.
  • --ulog-cprange range — defines the maximum copy range to userspace, for packets matching the rule. The default range is 0, which means the maximum copy range is given by nlbufsiz. A maximum copy range larger than 128*1024 is meaningless, since the packets sent to userspace have an upper size limit of 128*1024.
  • --ulog-qthreshold threshold — queue at most threshold number of packets before sending them to userspace with a netlink socket. Note that packets can be sent to userspace before the queue is full — that happens when the ulog kernel timer goes off (and how often that timer fires depends on flushtimeout).

🔥 TARGET EXTENSIONS 🔥

🌸 arpreply

The arpreply target can be used in the PREROUTING chain of the nat table. If this target sees an ARP request it will automatically reply with an ARP reply 💌 — and you can specify the MAC address used for the reply. The protocol must be specified as ARP.

When the ARP message is not an ARP request, or when the ARP request isn't for an IP address on an Ethernet network, it gets ignored by this target (CONTINUE). When the ARP request is malformed, it gets dropped (DROP). Sorry bestie, rules are rules. 💀

  • --arpreply-mac address — specifies the MAC address to reply with: the Ethernet source MAC and the ARP payload source MAC will be filled in with this address.
  • --arpreply-target target — specifies the standard target. After sending the ARP reply, the rule still has to give a standard target so ebtables knows what to do with the ARP request. The default target is DROP.

🦋 dnat

The dnat target can only be used in the BROUTING chain of the broute table and the PREROUTING and OUTPUT chains of the nat table. It says: the destination MAC address has to be changed. ✨glow up✨

  • --to-destination address — change the destination MAC address to the specified address. The flag --to-dst is an alias for this option.
  • --dnat-target target — specifies the standard target. After doing the dnat, the rule still has to give a standard target so ebtables knows what to do with the dnated frame. The default target is ACCEPT. Making it CONTINUE could let you use multiple target extensions on the same frame. Making it DROP only makes sense in the BROUTING chain, but using the redirect target is more logical there. RETURN is also allowed. Note that using RETURN in a base chain is not allowed (for obvious reasons).

💖 mark

The mark target can be used in every chain of every table. If the bridge-nf code is compiled into the kernel, it's possible to use the marking of a frame/packet in both ebtables and iptables — both put the marking at the same place. So it's basically a little communication channel between ebtables and iptables. 📬 iconic.

  • --mark-set value — mark the frame with the specified non-negative value.
  • --mark-or value — or the frame with the specified non-negative value.
  • --mark-and value — and the frame with the specified non-negative value.
  • --mark-xor value — xor the frame with the specified non-negative value.
  • --mark-target target — specifies the standard target. After marking the frame, the rule still has to give a standard target so ebtables knows what to do. The default target is ACCEPT. Making it CONTINUE can let you do other things with the frame in subsequent rules of the chain.

🎀 redirect

The redirect target will change the MAC target address to that of the bridge device the frame arrived on. This target can only be used in the BROUTING chain of the broute table and the PREROUTING chain of the nat table. In the BROUTING chain, the MAC address of the bridge port is used as destination address; in the PREROUTING chain, the MAC address of the bridge is used. Sending it right back where it came from, no cap. 🪃

  • --redirect-target target — specifies the standard target. After doing the MAC redirect, the rule still has to give a standard target so ebtables knows what to do. The default target is ACCEPT. Making it CONTINUE could let you use multiple target extensions on the same frame. Making it DROP in the BROUTING chain will let the frames be routed. RETURN is also allowed. Note that using RETURN in a base chain is not allowed.

⭐ snat

The snat target can only be used in the POSTROUTING chain of the nat table. It specifies that the source MAC address has to be changed.

  • --to-source address — changes the source MAC address to the specified address. The flag --to-src is an alias for this option.
  • --snat-target target — specifies the standard target. After doing the snat, the rule still has to give a standard target so ebtables knows what to do. The default target is ACCEPT. Making it CONTINUE could let you use multiple target extensions on the same frame. Making it DROP doesn't make sense, but you could do that too. RETURN is also allowed. Note that using RETURN in a base chain is not allowed.
  • --snat-arp — also change the hardware source address inside the arp header if the packet is an arp message and the hardware address length in the arp header is 6 bytes.

📁 FILES 📁

  • /etc/ethertypes
  • /var/lib/ebtables/lock

🌱 ENVIRONMENT VARIABLES 🌱

  • EBTABLES_ATOMIC_FILE

💌 MAILINGLISTS 💌

See http://netfilter.org/mailinglists.html

👀 SEE ALSO 👀

iptables(8), brctl(8), ifconfig(8), route(8)

See http://ebtables.sf.net

And that's the whole thing, bestie — you're officially an ebtables-legacy scholar now 🎓💅 This page is from December 2011, and it's the manual for version EBTABLES-LEGACY(8). Go forth and route responsibly. 💖✨

📦 where this page comes from