-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathebtables.8
1114 lines (1111 loc) · 39.9 KB
/
ebtables.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.TH EBTABLES 8 "$(DATE)"
.\"
.\" Man page written by Bart De Schuymer <[email protected]>
.\" It is based on the iptables man page.
.\"
.\" The man page was edited, February 25th 2003, by
.\" Greg Morgan <" dr_kludge_at_users_sourceforge_net >
.\"
.\" Iptables page by Herve Eychenne March 2000.
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\"
.SH NAME
ebtables (v$(VERSION)) \- Ethernet bridge frame table administration
.SH SYNOPSIS
.BR "ebtables " [ -t " table ] " - [ ACDI "] chain rule specification [match extensions] [watcher extensions] target"
.br
.BR "ebtables " [ -t " table ] " -P " chain " ACCEPT " | " DROP " | " RETURN
.br
.BR "ebtables " [ -t " table ] " -F " [chain]"
.br
.BR "ebtables " [ -t " table ] " -Z " [chain]"
.br
.BR "ebtables " [ -t " table ] " -L " [" -Z "] [chain] [ [" --Ln "] | [" --Lx "] ] [" --Lc "] [" --Lmac2 ]
.br
.BR "ebtables " [ -t " table ] " -N " chain [" "-P ACCEPT " | " DROP " | " RETURN" ]
.br
.BR "ebtables " [ -t " table ] " -X " [chain]"
.br
.BR "ebtables " [ -t " table ] " -E " old-chain-name new-chain-name"
.br
.BR "ebtables " [ -t " table ] " --init-table
.br
.BR "ebtables " [ -t " table ] [" --atomic-file " file] " --atomic-commit
.br
.BR "ebtables " [ -t " table ] [" --atomic-file " file] " --atomic-init
.br
.BR "ebtables " [ -t " table ] [" --atomic-file " file] " --atomic-save
.br
.SH DESCRIPTION
.B ebtables
is an application program used to set up and maintain the
tables of rules (inside the Linux kernel) that inspect
Ethernet frames.
It is analogous to the
.B iptables
application, but less complicated, due to the fact that the Ethernet protocol
is much simpler than the IP protocol.
.SS 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. The processing specification is
called a 'target'. However, 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.
.SS 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:
.BR ACCEPT ,
.BR DROP ,
.BR CONTINUE ,
.BR RETURN ,
an 'extension' (see below) or a jump to a user-defined chain.
.PP
.B ACCEPT
means to let the frame through.
.B DROP
means the frame has to be dropped. In the
.BR BROUTING " chain however, the " ACCEPT " and " DROP " target have different"
meanings (see the info provided for the
.BR -t " option)."
.B 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.
.B 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
.B "TARGET EXTENSIONS"
section of this man page.
.SS TABLES
As stated earlier, there are three ebtables tables in the Linux
kernel. The table names are
.BR 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.
.TP
.B "-t, --table"
.br
.B filter
is the default table and contains three built-in chains:
.B INPUT
(for frames destined for the bridge itself, on the level of the MAC destination address),
.B OUTPUT
(for locally-generated or (b)routed frames) and
.B FORWARD
(for frames being forwarded by the bridge).
.br
.br
.B nat
is mostly used to change the mac addresses and contains three built-in chains:
.B PREROUTING
(for altering frames as soon as they come in),
.B OUTPUT
(for altering locally generated or (b)routed frames before they are bridged) and
.B 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
.BR "" ( -E )
if you don't like the default.
.br
.br
.B broute
is used to make a brouter, it has one built-in chain:
.BR BROUTING .
The targets
.BR 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).
.B DROP
actually means the frame has to be routed, while
.B ACCEPT
means the frame has to be bridged. The
.B 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
.B redirect
target is very handy here.
.SH 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.
.SS 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
.BR -L " and " -Z
are combined, the commands
.BR -N " and " -P
are combined, or when
.B --atomic-file
is used.
.TP
.B "-A, --append"
Append a rule to the end of the selected chain.
.TP
.B "-D, --delete"
Delete the specified rule or rules from the selected chain. There are two ways to
use this command. The first is by specifying an interval of rule numbers
to delete (directly after
.BR -D ).
Syntax: \fIstart_nr\fP[\fI:end_nr\fP] (use
.B -L --Ln
to list the rules with their rule number). When \fIend_nr\fP is omitted, all rules starting
from \fIstart_nr\fP are deleted. Using negative numbers is allowed, for more
details about using negative numbers, see the
.B -I
command. 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.
.TP
.B "-C, --change-counters"
Change the counters of the specified rule or rules from the selected chain. There are two ways to
use this command. The first is by specifying an interval of rule numbers
to do the changes on (directly after
.BR -C ).
Syntax: \fIstart_nr\fP[\fI:end_nr\fP] (use
.B -L --Ln
to list the rules with their rule number). The details are the same as for the
.BR -D " command. 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
.BR -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.
.TP
.B "-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
.IR N ,
then the specified number can be
between
.IR -N " and " N+1 .
For a positive number
.IR i ,
it holds that
.IR 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
.BR -A " command."
Rule numbers structly smaller than 0 can be useful when more than one rule needs to be inserted
in a chain.
.TP
.B "-P, --policy"
Set the policy for the chain to the given target. The policy can be
.BR ACCEPT ", " DROP " or " RETURN .
.TP
.B "-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.
.TP
.B "-Z, --zero"
Set the counters of the selected chain to zero. If no chain is selected, all the counters
are set to zero. The
.B "-Z"
command can be used in conjunction with the
.B "-L"
command.
When both the
.B "-Z"
and
.B "-L"
commands are used together in this way, the rule counters are printed on the screen
before they are set to zero.
.TP
.B "-L, --list"
List all rules in the selected chain. If no chain is selected, all chains
are listed.
.br
The following options change the output of the
.B "-L"
command.
.br
.B "--Ln"
.br
Places the rule number in front of every rule. This option is incompatible with the
.BR --Lx " option."
.br
.B "--Lc"
.br
Shows the counters at the end of each rule displayed by the
.B "-L"
command. Both a frame counter (pcnt) and a byte counter (bcnt) are displayed.
The frame counter shows how many frames have matched the specific rule, the byte
counter shows the sum of the frame sizes of these matching frames. Using this option
.BR "" "in combination with the " --Lx " option causes the counters to be written out"
.BR "" "in the '" -c " <pcnt> <bcnt>' option format."
.br
.B "--Lx"
.br
Changes the output so that it produces a set of ebtables commands that construct
the contents of the chain, when specified.
If no chain is specified, ebtables commands to construct the contents of the
table are given, including commands for creating the user-defined chains (if any).
You can use this set of commands in an ebtables boot or reload
script. For example the output could be used at system startup.
The
.B "--Lx"
option is incompatible with the
.B "--Ln"
listing option. Using the
.BR --Lx " option together with the " --Lc " option will cause the counters to be written out"
.BR "" "in the '" -c " <pcnt> <bcnt>' option format."
.br
.B "--Lmac2"
.br
Shows all MAC addresses with the same length, adding leading zeroes
if necessary. The default representation omits leading zeroes in the addresses.
.TP
.B "-N, --new-chain"
Create a new user-defined chain with the given name. 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. The policy of the new chain can be initialized to a different standard
target by using the
.B -P
command together with the
.B -N
command. In this case, the chain name does not have to be specified for the
.B -P
command.
.TP
.B "-X, --delete-chain"
Delete the specified user-defined chain. There must be no remaining references (jumps)
to the specified chain, otherwise ebtables will refuse to delete it. If no chain is
specified, all user-defined chains that aren't referenced will be removed.
.TP
.B "-E, --rename-chain"
Rename the specified chain to a new name. Besides renaming a user-defined
chain, you can rename a standard chain to a name that suits your
taste. For example, if you like PREFORWARDING more than PREROUTING,
then you can use the -E command to rename the PREROUTING chain. If you do
rename one of the standard ebtables chain names, please be sure to mention
this fact should you post a question on the ebtables mailing lists.
It would be wise to use the standard name in your post. Renaming a standard
ebtables chain in this fashion has no effect on the structure or functioning
of the ebtables kernel table.
.TP
.B "--init-table"
Replace the current table data by the initial table data.
.TP
.B "--atomic-init"
Copy the kernel's initial data of the table to the specified
file. This can be used as the first action, after which rules are added
to the file. The file can be specified using the
.B --atomic-file
command or through the
.IR EBTABLES_ATOMIC_FILE " environment variable."
.TP
.B "--atomic-save"
Copy the kernel's current data of the table to the specified
file. This can be used as the first action, after which rules are added
to the file. The file can be specified using the
.B --atomic-file
command or through the
.IR EBTABLES_ATOMIC_FILE " environment variable."
.TP
.B "--atomic-commit"
Replace the kernel table data with the data contained in the specified
file. This is a useful command that allows you to load all your rules of a
certain table into the kernel at once, saving the kernel a lot of precious
time and allowing atomic updates of the tables. The file which contains
the table data is constructed by using either the
.B "--atomic-init"
or the
.B "--atomic-save"
command to generate a starting file. After that, using the
.B "--atomic-file"
command when constructing rules or setting the
.IR EBTABLES_ATOMIC_FILE " environment variable"
allows you to extend the file and build the complete table before
committing it to the kernel. This command can be very useful in boot scripts
to populate the ebtables tables in a fast way.
.SS MISCELLANOUS COMMANDS
.TP
.B "-V, --version"
Show the version of the ebtables userspace program.
.TP
.BR "-h, --help " "[\fIlist of module names\fP]"
Give a brief description of the command syntax. Here you can also specify
names of extensions and ebtables will try to write help about those
extensions. E.g.
.IR "ebtables -h snat log ip arp" .
Specify
.I list_extensions
to list all extensions supported by the userspace
utility.
.TP
.BR "-j, --jump " "\fItarget\fP"
The target of the rule. This is one of the following values:
.BR ACCEPT ,
.BR DROP ,
.BR CONTINUE ,
.BR RETURN ,
a target extension (see
.BR "TARGET EXTENSIONS" ")"
or a user-defined chain name.
.TP
.B --atomic-file "\fIfile\fP"
Let the command operate on the specified
.IR file .
The data of the table to
operate on will be extracted from the file and the result of the operation
will be saved back into the file. If specified, this option should come
before the command specification. An alternative that should be preferred,
is setting the
.IR EBTABLES_ATOMIC_FILE " environment variable."
.TP
.B -M, --modprobe "\fIprogram\fP"
When talking to the kernel, use this
.I program
to try to automatically load missing kernel modules.
.TP
.B --concurrent
Use a file lock to support concurrent scripts updating the ebtables kernel tables.
.SS
RULE SPECIFICATIONS
The following command line arguments make up a rule specification (as used
in the add and delete commands). A "!" option before the specification
inverts the test for that specification. Apart from these standard rule
specifications there are some other command line arguments of interest.
See both the
.BR "MATCH EXTENSIONS"
and the
.BR "WATCHER EXTENSIONS"
below.
.TP
.BR "-p, --protocol " "[!] \fIprotocol\fP"
The protocol that was responsible for creating the frame. This can be a
hexadecimal number, above
.IR 0x0600 ,
a name (e.g.
.I ARP
) or
.BR LENGTH .
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
.IR 0x0600 ,
the 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 used in ebtables for these frames is
.BR LENGTH .
.br
The file
.B /etc/ethertypes
can be used to show readable
characters instead of hexadecimal numbers for the protocols. For example,
.I 0x0800
will be represented by
.IR IPV4 .
The use of this file is not case sensitive.
See that file for more information. The flag
.B --proto
is an alias for this option.
.TP
.BR "-i, --in-interface " "[!] \fIname\fP"
The interface (bridge port) via which a frame is received (this option is useful in the
.BR INPUT ,
.BR FORWARD ,
.BR PREROUTING " and " BROUTING
chains). If the interface name ends with '+', then
any interface name that begins with this name (disregarding '+') will match.
The flag
.B --in-if
is an alias for this option.
.TP
.BR "--logical-in " "[!] \fIname\fP"
The (logical) bridge interface via which a frame is received (this option is useful in the
.BR INPUT ,
.BR FORWARD ,
.BR PREROUTING " and " BROUTING
chains).
If the interface name ends with '+', then
any interface name that begins with this name (disregarding '+') will match.
.TP
.BR "-o, --out-interface " "[!] \fIname\fP"
The interface (bridge port) via which a frame is going to be sent (this option is useful in the
.BR OUTPUT ,
.B FORWARD
and
.B POSTROUTING
chains). If the interface name ends with '+', then
any interface name that begins with this name (disregarding '+') will match.
The flag
.B --out-if
is an alias for this option.
.TP
.BR "--logical-out " "[!] \fIname\fP"
The (logical) bridge interface via which a frame is going to be sent (this option
is useful in the
.BR OUTPUT ,
.B FORWARD
and
.B POSTROUTING
chains).
If the interface name ends with '+', then
any interface name that begins with this name (disregarding '+') will match.
.TP
.BR "-s, --source " "[!] \fIaddress\fP[/\fImask\fP]"
The source MAC address. Both mask and address are written as 6 hexadecimal
numbers separated by colons. Alternatively one can specify Unicast,
Multicast, Broadcast or BGA (Bridge Group Address):
.br
.IR "Unicast" "=00:00:00:00:00:00/01:00:00:00:00:00,"
.IR "Multicast" "=01:00:00:00:00:00/01:00:00:00:00:00,"
.IR "Broadcast" "=ff:ff:ff:ff:ff:ff/ff:ff:ff:ff:ff:ff or"
.IR "BGA" "=01:80:c2:00:00:00/ff:ff:ff:ff:ff:ff."
Note that a broadcast
address will also match the multicast specification. The flag
.B --src
is an alias for this option.
.TP
.BR "-d, --destination " "[!] \fIaddress\fP[/\fImask\fP]"
The destination MAC address. See
.B -s
(above) for more details on MAC addresses. The flag
.B --dst
is an alias for this option.
.TP
.BR "-c, --set-counter " "\fIpcnt bcnt\fP"
If used with
.BR -A " or " -I ", then the packet and byte counters of the new rule will be set to
.IR pcnt ", resp. " bcnt ".
If used with the
.BR -C " or " -D " commands, only rules with a packet and byte count equal to"
.IR pcnt ", resp. " bcnt " will match."
.SS MATCH EXTENSIONS
Ebtables extensions are dynamically loaded into the userspace tool,
there is therefore no need to explicitly load them with a
-m option like is done in iptables.
These extensions deal with functionality supported by kernel modules supplemental to
the core ebtables code.
.SS 802_3
Specify 802.3 DSAP/SSAP fields or SNAP type. The protocol must be specified as
.IR "LENGTH " "(see the option " " -p " above).
.TP
.BR "--802_3-sap " "[!] \fIsap\fP"
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.
.TP
.BR "--802_3-type " "[!] \fItype\fP"
If the 802.3 DSAP and SSAP values are 0xaa then the SNAP type field must
be consulted to determine the payload protocol. This is a two byte
(hexadecimal) argument. Only 802.3 frames with DSAP/SSAP 0xaa are
checked for type.
.SS among
Match a MAC address or MAC/IP address pair versus a list of MAC addresses
and MAC/IP address pairs.
A list entry has the following format:
.IR xx:xx:xx:xx:xx:xx[=ip.ip.ip.ip][,] ". Multiple"
list entries are separated by a comma, specifying an IP address corresponding to
the MAC address is optional. Multiple MAC/IP address pairs with the same MAC address
but different IP address (and vice versa) can be specified. If the MAC address doesn't
match any entry from the list, the frame doesn't match the rule (unless "!" was used).
.TP
.BR "--among-dst " "[!] \fIlist\fP"
Compare the MAC destination to the given list. If the Ethernet frame has type
.IR IPv4 " or " ARP ,
then comparison with MAC/IP destination address pairs from the
list is possible.
.TP
.BR "--among-src " "[!] \fIlist\fP"
Compare the MAC source to the given list. If the Ethernet frame has type
.IR IPv4 " or " ARP ,
then comparison with MAC/IP source address pairs from the list
is possible.
.TP
.BR "--among-dst-file " "[!] \fIfile\fP"
Same as
.BR --among-dst " but the list is read in from the specified file."
.TP
.BR "--among-src-file " "[!] \fIfile\fP"
Same as
.BR --among-src " but the list is read in from the specified file."
.SS arp
Specify (R)ARP fields. The protocol must be specified as
.IR ARP " or " RARP .
.TP
.BR "--arp-opcode " "[!] \fIopcode\fP"
The (R)ARP opcode (decimal or a string, for more details see
.BR "ebtables -h arp" ).
.TP
.BR "--arp-htype " "[!] \fIhardware type\fP"
The hardware type, this can be a decimal or the string
.I Ethernet
(which sets
.I type
to 1). Most (R)ARP packets have Eternet as hardware type.
.TP
.BR "--arp-ptype " "[!] \fIprotocol type\fP"
The protocol type for which the (r)arp is used (hexadecimal or the string
.IR IPv4 ,
denoting 0x0800).
Most (R)ARP packets have protocol type IPv4.
.TP
.BR "--arp-ip-src " "[!] \fIaddress\fP[/\fImask\fP]"
The (R)ARP IP source address specification.
.TP
.BR "--arp-ip-dst " "[!] \fIaddress\fP[/\fImask\fP]"
The (R)ARP IP destination address specification.
.TP
.BR "--arp-mac-src " "[!] \fIaddress\fP[/\fImask\fP]"
The (R)ARP MAC source address specification.
.TP
.BR "--arp-mac-dst " "[!] \fIaddress\fP[/\fImask\fP]"
The (R)ARP MAC destination address specification.
.TP
.BR "" "[!]" " --arp-gratuitous"
Checks for ARP gratuitous packets: checks equality of IPv4 source
address and IPv4 destination address inside the ARP header.
.SS ip
Specify IPv4 fields. The protocol must be specified as
.IR IPv4 .
.TP
.BR "--ip-source " "[!] \fIaddress\fP[/\fImask\fP]"
The source IP address.
The flag
.B --ip-src
is an alias for this option.
.TP
.BR "--ip-destination " "[!] \fIaddress\fP[/\fImask\fP]"
The destination IP address.
The flag
.B --ip-dst
is an alias for this option.
.TP
.BR "--ip-tos " "[!] \fItos\fP"
The IP type of service, in hexadecimal numbers.
.BR IPv4 .
.TP
.BR "--ip-protocol " "[!] \fIprotocol\fP"
The IP protocol.
The flag
.B --ip-proto
is an alias for this option.
.TP
.BR "--ip-source-port " "[!] \fIport1\fP[:\fIport2\fP]"
The source port or port range for the IP protocols 6 (TCP), 17
(UDP), 33 (DCCP) or 132 (SCTP). The
.B --ip-protocol
option must be specified as
.IR TCP ", " UDP ", " DCCP " or " SCTP .
If
.IR port1 " is omitted, " 0:port2 " is used; if " port2 " is omitted but a colon is specified, " port1:65535 " is used."
The flag
.B --ip-sport
is an alias for this option.
.TP
.BR "--ip-destination-port " "[!] \fIport1\fP[:\fIport2\fP]"
The destination port or port range for ip protocols 6 (TCP), 17
(UDP), 33 (DCCP) or 132 (SCTP). The
.B --ip-protocol
option must be specified as
.IR TCP ", " UDP ", " DCCP " or " SCTP .
If
.IR port1 " is omitted, " 0:port2 " is used; if " port2 " is omitted but a colon is specified, " port1:65535 " is used."
The flag
.B --ip-dport
is an alias for this option.
.SS ip6
Specify IPv6 fields. The protocol must be specified as
.IR IPv6 .
.TP
.BR "--ip6-source " "[!] \fIaddress\fP[/\fImask\fP]"
The source IPv6 address.
The flag
.B --ip6-src
is an alias for this option.
.TP
.BR "--ip6-destination " "[!] \fIaddress\fP[/\fImask\fP]"
The destination IPv6 address.
The flag
.B --ip6-dst
is an alias for this option.
.TP
.BR "--ip6-tclass " "[!] \fItclass\fP"
The IPv6 traffic class, in hexadecimal numbers.
.TP
.BR "--ip6-protocol " "[!] \fIprotocol\fP"
The IP protocol.
The flag
.B --ip6-proto
is an alias for this option.
.TP
.BR "--ip6-source-port " "[!] \fIport1\fP[:\fIport2\fP]"
The source port or port range for the IPv6 protocols 6 (TCP), 17
(UDP), 33 (DCCP) or 132 (SCTP). The
.B --ip6-protocol
option must be specified as
.IR TCP ", " UDP ", " DCCP " or " SCTP .
If
.IR port1 " is omitted, " 0:port2 " is used; if " port2 " is omitted but a colon is specified, " port1:65535 " is used."
The flag
.B --ip6-sport
is an alias for this option.
.TP
.BR "--ip6-destination-port " "[!] \fIport1\fP[:\fIport2\fP]"
The destination port or port range for IPv6 protocols 6 (TCP), 17
(UDP), 33 (DCCP) or 132 (SCTP). The
.B --ip6-protocol
option must be specified as
.IR TCP ", " UDP ", " DCCP " or " SCTP .
If
.IR port1 " is omitted, " 0:port2 " is used; if " port2 " is omitted but a colon is specified, " port1:65535 " is used."
The flag
.B --ip6-dport
is an alias for this option.
.TP
.BR "--ip6-icmp-type " "[!] {\fItype\fP[:\fItype\fP]/\fIcode\fP[:\fIcode\fP]|\fItypename\fP}"
Specify ipv6\-icmp type and code to match.
Ranges for both type and code are supported. Type and code are
separated by a slash. Valid numbers for type and range are 0 to 255.
To match a single type including all valid codes, symbolic names can
be used instead of numbers. The list of known type names is shown by the command
.nf
ebtables \-\-help ip6
.fi
This option is only valid for \-\-ip6-prococol ipv6-icmp.
.SS limit
This module matches at a limited rate using a token bucket filter.
A rule using this extension will match until this limit is reached.
It can be used with the
.B --log
watcher to give limited logging, for example. Its use is the same
as the limit match of iptables.
.TP
.BR "--limit " "[\fIvalue\fP]"
Maximum average matching rate: specified as a number, with an optional
.IR /second ", " /minute ", " /hour ", or " /day " suffix; the default is " 3/hour .
.TP
.BR "--limit-burst " "[\fInumber\fP]"
Maximum initial number of packets to match: this number gets recharged by
one every time the limit specified above is not reached, up to this
number; the default is
.IR 5 .
.SS mark_m
.TP
.BR "--mark " "[!] [\fIvalue\fP][/\fImask\fP]"
Matches frames with the given unsigned mark value. If a
.IR value " and " mask " are specified, the logical AND of the mark value of the frame and"
the user-specified
.IR mask " is taken before comparing it with the"
user-specified mark
.IR value ". When only a mark "
.IR value " is specified, the packet"
only matches when the mark value of the frame equals the user-specified
mark
.IR value .
If only a
.IR mask " is specified, the logical"
AND of the mark value of the frame and the user-specified
.IR mask " is taken and the frame matches when the result of this logical AND is"
non-zero. Only specifying a
.IR mask " is useful to match multiple mark values."
.SS pkttype
.TP
.BR "--pkttype-type " "[!] \fItype\fP"
Matches on the Ethernet "class" of the frame, which is determined by the
generic networking code. Possible values:
.IR broadcast " (MAC destination is the broadcast address),"
.IR multicast " (MAC destination is a multicast address),"
.IR host " (MAC destination is the receiving network device), or "
.IR otherhost " (none of the above)."
.SS stp
Specify stp BPDU (bridge protocol data unit) fields. The destination
address
.BR "" ( -d ") must be specified as the bridge group address"
.IR "" ( BGA ).
For all options for which a range of values can be specified, it holds that
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 the colon again is not), the
highest possible upper bound for that option is used.
.TP
.BR "--stp-type " "[!] \fItype\fP"
The BPDU type (0-255), recognized non-numerical types are
.IR config ", denoting a configuration BPDU (=0), and"
.IR tcn ", denothing a topology change notification BPDU (=128)."
.TP
.BR "--stp-flags " "[!] \fIflag\fP"
The BPDU flag (0-255), recognized non-numerical flags are
.IR topology-change ", denoting the topology change flag (=1), and"
.IR topology-change-ack ", denoting the topology change acknowledgement flag (=128)."
.TP
.BR "--stp-root-prio " "[!] [\fIprio\fP][:\fIprio\fP]"
The root priority (0-65535) range.
.TP
.BR "--stp-root-addr " "[!] [\fIaddress\fP][/\fImask\fP]"
The root mac address, see the option
.BR -s " for more details."
.TP
.BR "--stp-root-cost " "[!] [\fIcost\fP][:\fIcost\fP]"
The root path cost (0-4294967295) range.
.TP
.BR "--stp-sender-prio " "[!] [\fIprio\fP][:\fIprio\fP]"
The BPDU's sender priority (0-65535) range.
.TP
.BR "--stp-sender-addr " "[!] [\fIaddress\fP][/\fImask\fP]"
The BPDU's sender mac address, see the option
.BR -s " for more details."
.TP
.BR "--stp-port " "[!] [\fIport\fP][:\fIport\fP]"
The port identifier (0-65535) range.
.TP
.BR "--stp-msg-age " "[!] [\fIage\fP][:\fIage\fP]"
The message age timer (0-65535) range.
.TP
.BR "--stp-max-age " "[!] [\fIage\fP][:\fIage\fP]"
The max age timer (0-65535) range.
.TP
.BR "--stp-hello-time " "[!] [\fItime\fP][:\fItime\fP]"
The hello time timer (0-65535) range.
.TP
.BR "--stp-forward-delay " "[!] [\fIdelay\fP][:\fIdelay\fP]"
The forward delay timer (0-65535) range.
.SS vlan
Specify 802.1Q Tag Control Information fields.
The protocol must be specified as
.IR 802_1Q " (0x8100)."
.TP
.BR "--vlan-id " "[!] \fIid\fP"
The VLAN identifier field (VID). Decimal number from 0 to 4095.
.TP
.BR "--vlan-prio " "[!] \fIprio\fP"
The user priority field, a decimal number from 0 to 7.
The VID should be set to 0 ("null VID") or unspecified
(in the latter case the VID is deliberately set to 0).
.TP
.BR "--vlan-encap " "[!] \fItype\fP"
The encapsulated Ethernet frame type/length.
Specified as a hexadecimal
number from 0x0000 to 0xFFFF or as a symbolic name
from
.BR /etc/ethertypes .
.SS WATCHER EXTENSIONS
Watchers only look at frames passing by, they don't modify them nor decide
to accept the frames or not. These watchers only
see the frame if the frame matches the rule, and they see it before the
target is executed.
.SS log
The log watcher writes descriptive data about a frame to the syslog.
.TP
.B "--log"
.br
Log with the default loggin options: log-level=
.IR info ,
log-prefix="", no ip logging, no arp logging.
.TP
.B --log-level "\fIlevel\fP"
.br
Defines the logging level. For the possible values, see
.BR "ebtables -h log" .
The default level is
.IR info .
.TP
.BR --log-prefix " \fItext\fP"
.br
Defines the prefix
.I text
to be printed at the beginning of the line with the logging information.
.TP
.B --log-ip
.br
Will log the ip information when a frame made by the ip protocol matches
the rule. The default is no ip information logging.
.TP
.B --log-ip6
.br
Will log the ipv6 information when a frame made by the ipv6 protocol matches
the rule. The default is no ipv6 information logging.
.TP
.B --log-arp
.br
Will log the (r)arp information when a frame made by the (r)arp protocols
matches the rule. The default is no (r)arp information logging.
.SS nflog
The nflog watcher passes the packet to the loaded logging backend
in order to log the packet. This is usually used in combination with
nfnetlink_log as logging backend, which will multicast the packet
through a
.IR netlink
socket to the specified multicast group. One or more userspace processes
may subscribe to the group to receive the packets.
.TP
.B "--nflog"
.br
Log with the default logging options
.TP
.B --nflog-group "\fInlgroup\fP"
.br
The netlink group (1 - 2^32-1) to which packets are (only applicable for
nfnetlink_log). The default value is 1.
.TP
.B --nflog-prefix "\fIprefix\fP"
.br
A prefix string to include in the log message, up to 30 characters
long, useful for distinguishing messages in the logs.
.TP
.B --nflog-range "\fIsize\fP"
.br
The number of bytes to be copied to userspace (only applicable for
nfnetlink_log). nfnetlink_log instances may specify their own
range, this option overrides it.
.TP
.B --nflog-threshold "\fIsize\fP"
.br
Number of packets to queue inside the kernel before sending them
to userspace (only applicable for nfnetlink_log). Higher values
result in less overhead per packet, but increase delay until the
packets reach userspace. The default value is 1.
.SS ulog
The ulog watcher passes the packet to a userspace
logging daemon using netlink multicast sockets. This differs
from the log watcher in the sense that the complete packet is
sent to userspace instead of a descriptive text and that
netlink multicast sockets are used instead of the syslog.
This watcher enables parsing of packets with userspace programs, the
physical bridge in and out ports are also included in the netlink messages.
The ulog watcher module accepts 2 parameters when the module is loaded
into the kernel (e.g. with modprobe):
.B nlbufsiz
specifies how big the buffer for each netlink multicast
group is. If you say
.IR nlbufsiz=8192 ,
for example, up to eight kB of packets will
get accumulated in the kernel until they are sent to userspace. It is
not possible to allocate more than 128kB. Please also keep in mind that
this buffer size is allocated for each nlgroup you are using, so the
total kernel memory usage increases by that factor. The default is 4096.
.B flushtimeout
specifies after how many hundredths of a second the queue should be
flushed, even if it is not full yet. The default is 10 (one tenth of
a second).
.TP
.B "--ulog"
.br
Use the default settings: ulog-prefix="", ulog-nlgroup=1,
ulog-cprange=4096, ulog-qthreshold=1.
.TP
.B --ulog-prefix "\fItext\fP"
.br
Defines the prefix included with the packets sent to userspace.
.TP
.BR --ulog-nlgroup " \fIgroup\fP"
.br
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.
The default group number is 1.
.TP
.BR --ulog-cprange " \fIrange\fP"
.br
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
.BR nlbufsiz .
A maximum copy range larger than
128*1024 is meaningless as the packets sent to userspace have an upper
size limit of 128*1024.
.TP
.BR --ulog-qthreshold " \fIthreshold\fP"
.br
Queue at most
.I 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, this happens when the ulog
kernel timer goes off (the frequency of this timer depends on
.BR flushtimeout ).
.SS TARGET EXTENSIONS
.SS arpreply
The
.B arpreply
target can be used in the
.BR PREROUTING " chain of the " nat " table."
If this target sees an ARP request it will automatically reply
with an ARP reply. The used MAC address for the reply can be specified.
The protocol must be specified as
.IR 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 is ignored by this target
.BR "" ( CONTINUE ).
When the ARP request is malformed, it is dropped
.BR "" ( DROP ).
.TP
.BR "--arpreply-mac " "\fIaddress\fP"
Specifies the MAC address to reply with: the Ethernet source MAC and the
ARP payload source MAC will be filled in with this address.
.TP
.BR "--arpreply-target " "\fItarget\fP"
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
.BR "" "is " DROP .
.SS dnat
The
.B dnat
target can only be used in the
.BR BROUTING " chain of the " broute " table and the "
.BR PREROUTING " and " OUTPUT " chains of the " nat " table."
It specifies that the destination MAC address has to be changed.
.TP