diff options
| -rw-r--r-- | ebtables.8 | 395 |
1 files changed, 250 insertions, 145 deletions
@@ -1,8 +1,11 @@ -.TH EBTABLES 8 "03 December 2002" +.TH EBTABLES 8 "252 February 2003" .\" .\" Man page written by Bart De Schuymer <bdschuym@pandora.be> .\" It is based on the iptables man page. .\" +.\" The man page was edited 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 @@ -23,46 +26,61 @@ .SH NAME ebtables (v.2.0) \- Ethernet bridge frame table administration .SH SYNOPSIS -.BR "ebtables -[ADI] " "chain rule-specification " [ options ] +.BR "ebtables [-t table] -[ADI] " "chain rule-specification [match-extensions] [watcher-extensions] TARGET" +.br +.BR "ebtables [-t table] -P " "chain " "ACCEPT | DROP | RETURN" .br -.BR "ebtables -P " "chain target" +.BR "ebtables [-t table] -F [" "chain" "]" .br -.BR "ebtables -[FLZ] [" "chain" "]" +.BR "ebtables [-t table] -Z [" "chain" "]" .br -.BR "ebtables -[NX] " chain +.BR "ebtables [-t table] -L [-Z] [" chain "] [ [" --Ln "] [" --Lc "] ] " | " [" --Lx "]" .br -.BR "ebtables -E " "old-chain-name new-chain-name" +.BR "ebtables [-t table] -[NX] " chain .br -.BR "ebtables --init-table" +.BR "ebtables [-t table] -E " "old-chain-name new-chain-name" .br -.BR "ebtables --atomic-init " +.BR "ebtables [-t table] --init-table" .br -.BR "ebtables --atomic-save " +.BR "ebtables [-t table] [--atomic-file file] --atomic-commit .br -.BR "ebtables --atomic-commit " +.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 used to set up, maintain, and inspect the tables of Ethernet frame -rules in the Linux kernel. It works analogous as iptables, but is less -complicated. This man page is written with the man page of iptables -next to it, so don't be surprised to see copied sentences and structure. +is a user space tool, it is used to set up and maintain the +tables of Ethernet frame rules in the Linux kernel. These rules inspect +the Ethernet frames which they see. +.B ebtables +is analogous to the +.B iptables +user space tool, but +.B ebtables +is less complicated. -There are three tables with built-in chains. Each chain is a list -of rules which can match frames: each rule specifies what to do with a -frame which matches. This is called a 'target'. The tables are used to -divide functionality into different sets of chains. +.SS CHAINS +There are three Ethernet frame tables with built-in chains in the +Linux kernel. The kernel 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 which can be used as the 'target' of a rule. .SS TARGETS -A firewall rule specifies criteria for a frame, and a target. If the -frame does not match, the next rule in the chain is the examined one; if -it does match, then the next thing to do is specified by the target. -This target can be one of these values: +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: .IR ACCEPT , .IR DROP , .IR CONTINUE , .IR RETURN , -an extention. +an 'extension' (see below) or a user-defined chain. .PP .I ACCEPT means to let the frame through. @@ -74,26 +92,36 @@ frames pass a certain point in the chain or to log those frames. .I RETURN means stop traversing this chain and resume at the next rule in the previous (calling) chain. -For the -other targets see the +For the extension targets please see the .B "TARGET EXTENSIONS" -section. +section of this man page. .SS TABLES -There are three tables. +As stated earlier, there are three Ethernet frame tables in the Linux +kernel. The tables are +.BR filter ", " nat " and " broute . +Of these three tables, +the filter table is the default table that the +.B ebtables +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. The -t argument must be the +first argument on the ebtables command line, if used. .TP .B "-t, --table" -This option specifies the frame matching table which the command should -operate on. If specified it should be the first option. The tables are: +.br .BR filter , -this is the default table and contains three chains: +is the default table and contains three built-in chains: .B INPUT (for frames destined for the bridge itself), .B OUTPUT (for locally-generated frames) and .B FORWARD (for frames being bridged). +.br +.br .BR nat , -this table is used to change the mac addresses and contains three chains: +is 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 @@ -104,30 +132,38 @@ of chains POSTROUTING and PREROUTING: it would be more accurate to call them PREFORWARDING and POSTFORWARDING, but for all those who come from the .BR iptables " world to " ebtables it is easier to have the same names. +.br +.br .BR broute , -this table is used to make a brouter, it has one chain: +is used to make a brouter, it has one built-in chain: .BR BROUTING . The targets .BR DROP " and " ACCEPT -have special meaning in this table. +have special meaning in the broute table. .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. It is only traversed by frames entering on -a bridge enslaved nic that is in forwarding state. Normally those frames +a bridge enslaved NIC 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 OPTIONS -The options can be divided into several different groups. +.SH EBTABLES COMMAND LINE ARGUMENTS +After the initial ebtables -t, table command line argument, the remaining +arguments can be divided into several different groups. These groups +are commands, miscellaneous commands, rule-specifications, match-extensions, +and watcher-extensions. .SS COMMANDS -These options specify the specific actions to perform; only one of them -can be specified on the command line (the -.B -Z -command is an exception). All these options only apply to the selected -(or default) table. +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. +With the exception of both the +.B "-Z" +and +.B "--atomic-file" +commands, only one command may be used on the command line at a time. .TP .B "-A, --append" Append a rule to the end of the selected chain. @@ -139,71 +175,119 @@ to delete, syntax: start_nr[:end_nr]. The second usage is by specifying the complete rule as it would have been specified when it was added. .TP .B "-I, --insert" -Insert the specified rule into the selected chain at the specified rule number (1 meaning -the head of the chain). +Insert the specified rule into the selected chain at the specified rule number. +The number one, 1, means the head of the 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 the 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 three options change the output: +The following three options change the output of the +.B "-L" +list command: .br .B "--Ln" .br -Puts rule numbers in front of every rule. +Places the rule number in front of every rule. .br .B "--Lc" .br -Shows the counters at the end of every rule, there is a frame counter -(pcnt) and a byte counter (bcnt). +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. .br .B "--Lx" .br -The output is directly usable as executable commands in a script, to be -run f.e. at bootup. This option is incompatible with the previous two -options. When no chain name was specified for the +The output of the +.B "--Lx" +option may be used to create a set of +.B ebtables +commands. You may use this set of commands in an +.B ebtables +boot or reload +script. For example the output could be used at system startup. +The +.B "--Lx" +option is incompatible with both of the other +.B "--Ln" +and +.B "--Lc" +chain listing options, +.B "-L." +All necessary +.B ebtables +commands for making the current list of +user-defined chains in the kernel and any commands issued by the user to +rename the standard +.B ebtables +chains will be listed, when no chain name is +supplied for the .B "-L" -command, all necessary commands for making the user defined chains and -renaming the standard chains will be made. -.TP -.B "-F, --flush" -Flush the selected chain. If no chain is selected, every chain will be -flushed. This does not change the policy of the chain. -.TP -.B "--init-table" -Replace the current table data by the initial table data. -.TP -.B "-Z, --zero" -Put the counters of the selected chain on zero. If no chain is selected, all the counters -are put on zero. This can be used in conjunction with the -L command (see above). -This will cause the rule counters to be printed on the screen before they are put on zero. -.TP -.B "-P, --policy" -Set the policy for the chain to the given target. The policy can be -.BR ACCEPT ", " DROP " or " RETURN . +command while using the +.B "-Lx" +option. .TP .B "-N, --new-chain" -Create a new user-defined chain by the given name. The number of -user-defined chains is unlimited. A chain name has max length of 31. +Create a new user-defined chain with the given name. The number of +user-defined chains is unlimited. A user-defined chain name has maximum +length of 31 characters. .TP .B "-X, --delete-chain" -Delete the specified user-defined chain. There must be no references to the -chain, +Delete the specified user-defined chain. There must be no remaining references +to the to be deleted chain. Otherwise, .B ebtables will complain if there are. .TP .B "-E, --rename-chain" -Rename the specified chain to the new name. This has no effect on the -structure of the table. It is also allowed to rename a base chain, f.e. -if you like PREBRIDGING more than PREROUTING. Be sure to talk about the -standard chain names when you would ask a question on a mailing list. +Rename the specified chain to a new name. Besides renaming a user-defined +chain, you may rename a standard chain name to a name that suits your +taste. For example, if you like PREBRIDGING more than PREROUTING, +then you can use the -E command to rename the PREROUTING chain. If you do +rename one of the standard +.B ebtables +chain names, please be sure to mention +this fact should you post a question on the +.B ebtables +mailing lists. +It would be wise to use the standard name in your post. Renaming a standard +.B ebtables +chain in this fashion has no effect on the structure or function +of the +.B 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 -option or through the +command or through the .IR EBTABLES_ATOMIC_FILE " environment variable." .TP .B "--atomic-save" @@ -211,30 +295,81 @@ 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 -option or through the +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 put all your rules of a +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 get a starting file. After that, using the +command to generate a starting file. After that, using the .B "--atomic-file" -option when constructing rules or setting the +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 -commiting it to the kernel. +committing it to the kernel. +.TP +.B "--atomic-file -Z" +The counters stored in a file with, say, +.B "--atomic-init" +can be optionally zeroed by supplying the +.B "-Z" +command. You may also zero the counters by setting the +.IR EBTABLES_ATOMIC_FILE " environment variable." + +.SS MISCELLANOUS COMMANDS +.TP +.B "-V, --version" +Show the version of the ebtables userspace program. +.TP +.B "-h, --help" +Give a brief description of the command syntax. Here you can also specify +names of extensions and +.B ebtables +will try to write help about those extensions. E.g. 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 file +Let the command operate on the specified 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 program +When talking to the kernel, use this program to try to automatically load +missing kernel modules. + .SS -PARAMETERS -The following parameters make up a rule specification (as used in the add -and delete commands). A "!" argument before the specification inverts the -test for that specification. Apart from these standard parameters, there are others, see -.BR "MATCH EXTENSIONS" . +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-EXTENSION(S)" +below. .TP .BR "-p, --protocol " "[!] \fIprotocol\fP" The protocol that was responsible for creating the frame. This can be a @@ -305,7 +440,7 @@ chains). .TP .BR "-s, --source " "[!] \fIaddress\fP[/\fImask\fP]" The source mac address. Both mask and address are written as 6 hexadecimal -numbers seperated by colons. Alternatively one can specify Unicast, +numbers separated by colons. Alternatively one can specify Unicast, Multicast or Broadcast. .br Unicast=00:00:00:00:00:00/01:00:00:00:00:00, @@ -320,49 +455,15 @@ The destination mac address. See -s (above) for more details. The flag .B --dst is an alias for this option. -.SS OTHER OPTIONS -.TP -.B "-V, --version" -Show the version of the userprogram. -.TP -.B "-h, --help" -Give a brief description of the command syntax. Here you can also specify -names of extensions and -.B ebtables -will try to write help about those extensions. E.g. 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 file -Let the command operate on the specified 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 -.BR EBTABLES_ATOMIC_FILE " environment variable." -.TP -.B -M, --modprobe program -When talking to the kernel, use this program to try to automatically load -missing kernel modules. -.SH MATCH EXTENSIONS +.SS MATCH-EXTENSIONS .B ebtables extensions are precompiled into the userspace tool. So there is no need -to explicitly load them with a -m option like in iptables. However, these +to explicitly load them with a -m option like in +.BR iptables . +However, these extensions deal with functionality supported by supplemental kernel modules. .SS ip -Specify ip specific fields. These will only work if the protocol equals +Specify ip fields. These will only work if the protocol equals .BR IPv4 . .TP .BR "--ip-source " "[!] \fIaddress\fP[/\fImask\fP]" @@ -400,7 +501,7 @@ The destination port or port range for ip protocols 6 (TCP) and .B --ip-dport is an alias for this option. .SS arp -Specify arp specific fields. These will only work if the protocol equals +Specify arp fields. These will only work if the protocol equals .BR ARP " or " RARP . .TP .BR "--arp-opcode " "[!] \fIopcode\fP" @@ -421,37 +522,37 @@ The ARP IP source address specification. .BR "--arp-ip-dst " "[!] \fIaddress\fP[/\fImask\fP]" The ARP IP destination address specification. .SS vlan -Specify 802.1Q Tag Control Information fields. These will only work if the protocol equals -.BR 802_1Q. -Also see extension help by -.BR "ebtables -h vlan" . +Specify 802.1Q Tag Control Information fields. +The protocol rule specification (frame type) should be set to +.BR 802_1Q " (0x8100)." .TP .BR "--vlan-id " "[!] \fIid\fP" -The VLAN identifier field, VID (decimal number from 0 to 4094). +The VLAN identifier field (VID). Decimal number from 0 to 4095. .TP .BR "--vlan-prio " "[!] \fIprio\fP" -The user_priority field, this can be a decimal number from 0 to 7. -Required VID to be 0 (null VID) or not specified vlan-id parameter (in this case VID deliberately be set to 0). +The user_priority field. Decimal number from 0 to 7. +The VID should be set to 0 ("null VID") or unspecified +(for this case the VID is deliberately set to 0). .TP .BR "--vlan-encap " "[!] \fItype\fP" -The encapsulated Ethernet frame type/length, this can be a hexadecimal -number from 0x0000 to 0xFFFF. -Usually it's 0x0800 (IPv4). See also -.B /etc/ethertypes -file. +The encapsulated Ethernet frame type/length. +Specified as hexadecimal +number from 0x0000 to 0xFFFF or as a symbolic name +from +.BR /etc/ethertypes . .SS mark_m .TP .BR "--mark " "[!] [\fIvalue\fP][/\fImask\fP]" Matches frames with the given unsigned mark value. If a mark value and mask is specified, the logical AND of the mark value of the frame and -the user specified mask is taken before comparing with the user specified +the user-specified mask is taken before comparing it with the user-specified mark value. If only a mask is specified (start with '/') the logical AND -of the mark value of the frame and the user specified mark is taken and +of the mark value of the frame and the user-specified mark is taken and the result is compared with zero. -.SH WATCHER EXTENSION(S) +.SS WATCHER-EXTENSION(S) Watchers are things that only look at frames passing by. These watchers only -see the frame if the frame passes all the matches of the rule. +see the frame if the frame matches the rule. .SS log The fact that the log module is a watcher lets us log stuff while giving a target by choice. Note that the log module therefore is not a target. @@ -579,5 +680,9 @@ Mark the frame with the specified unsigned value. This won't work on an architecture with a user32/kernel64 situation like the Sparc64. .SH AUTHOR .IR "" "Bart De Schuymer <" bdschuym@pandora.be > +.br +.br +Edited by +.IR "" "Greg Morgan <" dr_kludge_at_users_sourceforge_net > .SH SEE ALSO -.BR iptables "(8), " brctl (8) +.BR iptables "(8), " brctl (8), ifconfig (8), route (8) |