diff --git a/ChangeLog b/ChangeLog index 4e2782b..37e6ad8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,14 @@ CHANGES ======= +0.5.6 +----- + +* Added manual pages for \`ip\` and \`bridge\` command + +0.5.5 +----- + * Preserve compatibility with macOS Monterey 0.5.4 @@ -17,6 +25,10 @@ CHANGES ----- * Prevent empty Item/Items to raise exceptions + +0.5.2.dev1 +---------- + * Fixed \`ip route\` host entry 0.5.1 diff --git a/man/COPYING b/man/COPYING new file mode 100644 index 0000000..3912109 --- /dev/null +++ b/man/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + 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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/man/man8/bridge.8 b/man/man8/bridge.8 new file mode 100644 index 0000000..db83a2a --- /dev/null +++ b/man/man8/bridge.8 @@ -0,0 +1,944 @@ +.TH BRIDGE 8 "1 August 2012" "iproute2" "Linux" +.SH NAME +bridge \- show / manipulate bridge addresses and devices +.SH SYNOPSIS + +.ad l +.in +8 +.ti -8 +.B bridge +.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" +.sp + +.ti -8 +.IR OBJECT " := { " +.BR link " | " fdb " | " mdb " | " vlan " | " monitor " }" +.sp + +.ti -8 +.IR OPTIONS " := { " +\fB\-V\fR[\fIersion\fR] | +\fB\-s\fR[\fItatistics\fR] | +\fB\-n\fR[\fIetns\fR] name | +\fB\-b\fR[\fIatch\fR] filename | +\fB\-c\fR[\fIolor\fR] | +\fB\-p\fR[\fIretty\fR] | +\fB\-j\fR[\fIson\fR] | +\fB\-o\fR[\fIneline\fr] } + +.ti -8 +.B "bridge link set" +.B dev +.IR DEV " [ " +.B cost +.IR COST " ] [ " +.B priority +.IR PRIO " ] [ " +.B state +.IR STATE " ] [ " +.BR guard " { " on " | " off " } ] [ " +.BR hairpin " { " on " | " off " } ] [ " +.BR fastleave " { " on " | " off " } ] [ " +.BR root_block " { " on " | " off " } ] [ " +.BR learning " { " on " | " off " } ] [ " +.BR learning_sync " { " on " | " off " } ] [ " +.BR flood " { " on " | " off " } ] [ " +.BR hwmode " { " vepa " | " veb " } ] [ " +.BR mcast_flood " { " on " | " off " } ] [ " +.BR mcast_to_unicast " { " on " | " off " } ] [ " +.BR neigh_suppress " { " on " | " off " } ] [ " +.BR vlan_tunnel " { " on " | " off " } ] [ " +.BR isolated " { " on " | " off " } ] [ " +.B backup_port +.IR DEVICE " ] [" +.BR nobackup_port " ] [ " +.BR self " ] [ " master " ]" + +.ti -8 +.BR "bridge link" " [ " show " ] [ " +.B dev +.IR DEV " ]" + +.ti -8 +.BR "bridge fdb" " { " add " | " append " | " del " | " replace " } " +.I LLADDR +.B dev +.IR DEV " { " +.BR local " | " static " | " dynamic " } [ " +.BR self " ] [ " master " ] [ " router " ] [ " use " ] [ " extern_learn " ] [ " sticky " ] [ " +.B src_vni +.IR VNI " ] { [" +.B dst +.IR IPADDR " ] [ " +.B vni +.IR VNI " ] [" +.B port +.IR PORT " ] [" +.B via +.IR DEVICE " ] | " +.B nhid +.IR NHID " } " + +.ti -8 +.BR "bridge fdb" " [ [ " show " ] [ " +.B br +.IR BRDEV " ] [ " +.B brport +.IR DEV " ] [ " +.B vlan +.IR VID " ] [ " +.B state +.IR STATE " ] [" +.B dynamic +.IR "] ]" + +.ti -8 +.BR "bridge fdb get" " [" +.B to +.IR "]" +.I LLADDR "[ " +.B br +.IR BRDEV " ]" +.B { brport | dev } +.IR DEV " [ " +.B vlan +.IR VID " ] [ " +.B vni +.IR VNI " ] [" +.BR self " ] [ " master " ] [ " dynamic " ]" + +.ti -8 +.BR "bridge mdb" " { " add " | " del " } " +.B dev +.I DEV +.B port +.I PORT +.B grp +.IR GROUP " [ " +.B src +.IR SOURCE " ] [ " +.BR permanent " | " temp " ] [ " +.B vid +.IR VID " ] " + +.ti -8 +.BR "bridge mdb show " [ " +.B dev +.IR DEV " ]" + +.ti -8 +.BR "bridge vlan" " { " add " | " del " } " +.B dev +.I DEV +.B vid +.IR VID " [ " +.B tunnel_info +.IR TUNNEL_ID " ] [ " +.BR pvid " ] [ " untagged " ] [ " +.BR self " ] [ " master " ] " + +.ti -8 +.BR "bridge vlan set" +.B dev +.I DEV +.B vid +.IR VID " [ " +.B state +.IR STP_STATE " ] " + +.ti -8 +.BR "bridge vlan" " [ " show " | " tunnelshow " ] [ " +.B dev +.IR DEV " ]" + +.ti -8 +.BR "bridge monitor" " [ " all " | " neigh " | " link " | " mdb " | " vlan " ]" + +.SH OPTIONS + +.TP +.BR "\-V" , " -Version" +print the version of the +.B bridge +utility and exit. + +.TP +.BR "\-s" , " \-stats", " \-statistics" +output more information. If this option +is given multiple times, the amount of information increases. +As a rule, the information is statistics or some time values. + +.TP +.BR "\-d" , " \-details" +print detailed information about bridge vlan filter entries or MDB router ports. + +.TP +.BR "\-n" , " \-net" , " \-netns " +switches +.B bridge +to the specified network namespace +.IR NETNS . +Actually it just simplifies executing of: + +.B ip netns exec +.I NETNS +.B bridge +.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" + +to + +.B bridge +.RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" + +.TP +.BR "\-b", " \-batch " +Read commands from provided file or standard input and invoke them. +First failure will cause termination of bridge command. + +.TP +.B "\-force" +Don't terminate bridge command on errors in batch mode. +If there were any errors during execution of the commands, the application +return code will be non zero. + +.TP +.BR \-c [ color ][ = { always | auto | never } +Configure color output. If parameter is omitted or +.BR always , +color output is enabled regardless of stdout state. If parameter is +.BR auto , +stdout is checked to be a terminal before enabling color output. If parameter is +.BR never , +color output is disabled. If specified multiple times, the last one takes +precedence. This flag is ignored if +.B \-json +is also given. + +.TP +.BR "\-j", " \-json" +Output results in JavaScript Object Notation (JSON). + +.TP +.BR "\-p", " \-pretty" +When combined with -j generate a pretty JSON output. + +.TP +.BR "\-o", " \-oneline" +output each record on a single line, replacing line feeds +with the +.B '\e' +character. This is convenient when you want to count records +with +.BR wc (1) +or to +.BR grep (1) +the output. + + +.SH BRIDGE - COMMAND SYNTAX + +.SS +.I OBJECT + +.TP +.B link +- Bridge port. + +.TP +.B fdb +- Forwarding Database entry. + +.TP +.B mdb +- Multicast group database entry. + +.TP +.B vlan +- VLAN filter list. + +.SS +.I COMMAND + +Specifies the action to perform on the object. +The set of possible actions depends on the object type. +As a rule, it is possible to +.BR "add" , " delete" +and +.B show +(or +.B list +) objects, but some objects do not allow all of these operations +or have some additional commands. The +.B help +command is available for all objects. It prints +out a list of available commands and argument syntax conventions. +.sp +If no command is given, some default command is assumed. +Usually it is +.B list +or, if the objects of this class cannot be listed, +.BR "help" . + +.SH bridge link - bridge port + +.B link +objects correspond to the port devices of the bridge. + +.P +The corresponding commands set and display port status and bridge specific +attributes. + +.SS bridge link set - set bridge specific attributes on a port + +.TP +.BI dev " NAME " +interface name of the bridge port + +.TP +.BI cost " COST " +the STP path cost of the specified port. + +.TP +.BI priority " PRIO " +the STP port priority. The priority value is an unsigned 8-bit quantity +(number between 0 and 255). This metric is used in the designated port an +droot port selection algorithms. + +.TP +.BI state " STATE " +the operation state of the port. Except state 0 (disable STP or BPDU filter feature), +this is primarily used by user space STP/RSTP +implementation. One may enter port state name (case insensitive), or one of the +numbers below. Negative inputs are ignored, and unrecognized names return an +error. + +.B 0 +- port is in STP +.B DISABLED +state. Make this port completely inactive for STP. This is also called +BPDU filter and could be used to disable STP on an untrusted port, like +a leaf virtual devices. +.sp + +.B 1 +- port is in STP +.B LISTENING +state. Only valid if STP is enabled on the bridge. In this +state the port listens for STP BPDUs and drops all other traffic frames. +.sp + +.B 2 +- port is in STP +.B LEARNING +state. Only valid if STP is enabled on the bridge. In this +state the port will accept traffic only for the purpose of updating MAC +address tables. +.sp + +.B 3 +- port is in STP +.B FORWARDING +state. Port is fully active. +.sp + +.B 4 +- port is in STP +.B BLOCKING +state. Only valid if STP is enabled on the bridge. This state +is used during the STP election process. In this state, port will only process +STP BPDUs. +.sp + +.TP +.BR "guard on " or " guard off " +Controls whether STP BPDUs will be processed by the bridge port. By default, +the flag is turned off allowed BPDU processing. Turning this flag on will +disables +the bridge port if a STP BPDU packet is received. + +If running Spanning Tree on bridge, hostile devices on the network +may send BPDU on a port and cause network failure. Setting +.B guard on +will detect and stop this by disabling the port. +The port will be restarted if link is brought down, or +removed and reattached. For example if guard is enable on +eth0: + +.B ip link set dev eth0 down; ip link set dev eth0 up + +.TP +.BR "hairpin on " or " hairpin off " +Controls whether traffic may be send back out of the port on which it was +received. This option is also called reflective relay mode, and is used to support +basic VEPA (Virtual Ethernet Port Aggregator) capabilities. +By default, this flag is turned off and the bridge will not forward +traffic back out of the receiving port. + +.TP +.BR "fastleave on " or " fastleave off " +This flag allows the bridge to immediately stop multicast traffic on a port +that receives IGMP Leave message. It is only used with IGMP snooping is +enabled on the bridge. By default the flag is off. + +.TP +.BR "root_block on " or " root_block off " +Controls whether a given port is allowed to become root port or not. Only used +when STP is enabled on the bridge. By default the flag is off. + +This feature is also called root port guard. +If BPDU is received from a leaf (edge) port, it should not +be elected as root port. This could be used if using STP on a bridge and the downstream bridges are not fully +trusted; this prevents a hostile guest from rerouting traffic. + +.TP +.BR "learning on " or " learning off " +Controls whether a given port will learn MAC addresses from received traffic or +not. If learning if off, the bridge will end up flooding any traffic for which +it has no FDB entry. By default this flag is on. + +.TP +.BR "learning_sync on " or " learning_sync off " +Controls whether a given port will sync MAC addresses learned on device port to +bridge FDB. + +.TP +.BR "flood on " or " flood off " +Controls whether unicast traffic for which there is no FDB entry will be +flooded towards this given port. By default this flag is on. + +.TP +.B hwmode +Some network interface cards support HW bridge functionality and they may be +configured in different modes. Currently support modes are: + +.B vepa +- Data sent between HW ports is sent on the wire to the external +switch. + +.B veb +- bridging happens in hardware. + +.TP +.BR "mcast_flood on " or " mcast_flood off " +Controls whether multicast traffic for which there is no MDB entry will be +flooded towards this given port. By default this flag is on. + +.TP +.BR "mcast_to_unicast on " or " mcast_to_unicast off " +Controls whether a given port will replicate packets using unicast +instead of multicast. By default this flag is off. + +This is done by copying the packet per host and +changing the multicast destination MAC to a unicast one accordingly. + +.B mcast_to_unicast +works on top of the multicast snooping feature of +the bridge. Which means unicast copies are only delivered to hosts which +are interested in it and signalized this via IGMP/MLD reports +previously. + +This feature is intended for interface types which have a more reliable +and/or efficient way to deliver unicast packets than broadcast ones +(e.g. WiFi). + +However, it should only be enabled on interfaces where no IGMPv2/MLDv1 +report suppression takes place. IGMP/MLD report suppression issue is usually +overcome by the network daemon (supplicant) enabling AP isolation and +by that separating all STAs. + +Delivery of STA-to-STA IP multicast is made possible again by +enabling and utilizing the bridge hairpin mode, which considers the +incoming port as a potential outgoing port, too (see +.B hairpin +option). +Hairpin mode is performed after multicast snooping, therefore leading to +only deliver reports to STAs running a multicast router. + +.TP +.BR "neigh_suppress on " or " neigh_suppress off " +Controls whether neigh discovery (arp and nd) proxy and suppression is +enabled on the port. By default this flag is off. + +.TP +.BR "vlan_tunnel on " or " vlan_tunnel off " +Controls whether vlan to tunnel mapping is enabled on the port. By +default this flag is off. + +.TP +.BR "isolated on " or " isolated off " +Controls whether a given port will be isolated, which means it will be +able to communicate with non-isolated ports only. By default this +flag is off. + +.TP +.BI backup_port " DEVICE" +If the port loses carrier all traffic will be redirected to the +configured backup port + +.TP +.B nobackup_port +Removes the currently configured backup port + +.TP +.B self +link setting is configured on specified physical device + +.TP +.B master +link setting is configured on the software bridge (default) + +.TP +.BR "\-t" , " \-timestamp" +display current time when using monitor option. + +.SS bridge link show - list ports configuration for all bridges. + +This command displays port configuration and flags for all bridges. + +To display port configuration and flags for a specific bridge, use the +"ip link show master " command. + +.SH bridge fdb - forwarding database management + +.B fdb +objects contain known Ethernet addresses on a link. + +.P +The corresponding commands display fdb entries, add new entries, +append entries, +and delete old ones. + +.SS bridge fdb add - add a new fdb entry + +This command creates a new fdb entry. + +.TP +.B LLADDR +the Ethernet MAC address. + +.TP +.BI dev " DEV" +the interface to which this address is associated. + +.B local +- is a local permanent fdb entry, which means that the bridge will not forward +frames with this destination MAC address and VLAN ID, but terminate them +locally. This flag is default unless "static" or "dynamic" are explicitly +specified. +.sp + +.B permanent +- this is a synonym for "local" +.sp + +.B static +- is a static (no arp) fdb entry +.sp + +.B dynamic +- is a dynamic reachable age-able fdb entry +.sp + +.B self +- the operation is fulfilled directly by the driver for the specified network +device. If the network device belongs to a master like a bridge, then the +bridge is bypassed and not notified of this operation (and if the device does +notify the bridge, it is driver-specific behavior and not mandated by this +flag, check the driver for more details). The "bridge fdb add" command can also +be used on the bridge device itself, and in this case, the added fdb entries +will be locally terminated (not forwarded). In the latter case, the "self" flag +is mandatory. The flag is set by default if "master" is not specified. +.sp + +.B master +- if the specified network device is a port that belongs to a master device +such as a bridge, the operation is fulfilled by the master device's driver, +which may in turn notify the port driver too of the address. If the specified +device is a master itself, such as a bridge, this flag is invalid. +.sp + +.B router +- the destination address is associated with a router. +Valid if the referenced device is a VXLAN type device and has +route short circuit enabled. +.sp + +.B use +- the address is in use. User space can use this option to +indicate to the kernel that the fdb entry is in use. +.sp + +.B extern_learn +- this entry was learned externally. This option can be used to +indicate to the kernel that an entry was hardware or user-space +controller learnt dynamic entry. Kernel will not age such an entry. +.sp + +.B sticky +- this entry will not change its port due to learning. +.sp + +.in -8 +The next command line parameters apply only +when the specified device +.I DEV +is of type VXLAN. +.TP +.BI dst " IPADDR" +the IP address of the destination +VXLAN tunnel endpoint where the Ethernet MAC ADDRESS resides. + +.TP +.BI src_vni " VNI" +the src VNI Network Identifier (or VXLAN Segment ID) +this entry belongs to. Used only when the vxlan device is in +external or collect metadata mode. If omitted the value specified at +vxlan device creation will be used. + +.TP +.BI vni " VNI" +the VXLAN VNI Network Identifier (or VXLAN Segment ID) +to use to connect to the remote VXLAN tunnel endpoint. +If omitted the value specified at vxlan device creation +will be used. + +.TP +.BI port " PORT" +the UDP destination PORT number to use to connect to the +remote VXLAN tunnel endpoint. +If omitted the default value is used. + +.TP +.BI via " DEVICE" +device name of the outgoing interface for the +VXLAN device driver to reach the +remote VXLAN tunnel endpoint. + +.TP +.BI nhid " NHID " +ecmp nexthop group for the VXLAN device driver +to reach remote VXLAN tunnel endpoints. + +.SS bridge fdb append - append a forwarding database entry +This command adds a new fdb entry with an already known +.IR LLADDR . +Valid only for multicast link layer addresses. +The command adds support for broadcast and multicast +Ethernet MAC addresses. +The Ethernet MAC address is added multiple times into +the forwarding database and the vxlan device driver +sends a copy of the data packet to each entry found. + +.PP +The arguments are the same as with +.BR "bridge fdb add" . + +.SS bridge fdb delete - delete a forwarding database entry +This command removes an existing fdb entry. + +.PP +The arguments are the same as with +.BR "bridge fdb add" . + +.SS bridge fdb replace - replace a forwarding database entry +If no matching entry is found, a new one will be created instead. + +.PP +The arguments are the same as with +.BR "bridge fdb add" . + +.SS bridge fdb show - list forwarding entries. + +This command displays the current forwarding table. + +.PP +With the +.B -statistics +option, the command becomes verbose. It prints out the last updated +and last used time for each entry. + +.SS bridge fdb get - get bridge forwarding entry. + +lookup a bridge forwarding table entry. + +.TP +.B LLADDR +the Ethernet MAC address. + +.TP +.BI dev " DEV" +the interface to which this address is associated. + +.TP +.BI brport " DEV" +the bridge port to which this address is associated. same as dev above. + +.TP +.BI br " DEV" +the bridge to which this address is associated. + +.TP +.B self +- the address is associated with the port drivers fdb. Usually hardware. + +.TP +.B master +- the address is associated with master devices fdb. Usually software (default). +.sp + +.SH bridge mdb - multicast group database management + +.B mdb +objects contain known IP or L2 multicast group addresses on a link. + +.P +The corresponding commands display mdb entries, add new entries, +and delete old ones. + +.SS bridge mdb add - add a new multicast group database entry + +This command creates a new mdb entry. + +.TP +.BI dev " DEV" +the interface where this group address is associated. + +.TP +.BI port " PORT" +the port whose link is known to have members of this multicast group. + +.TP +.BI grp " GROUP" +the multicast group address (IPv4, IPv6 or L2 multicast) whose members reside +on the link connected to the port. + +.B permanent +- the mdb entry is permanent. Optional for IPv4 and IPv6, mandatory for L2. +.sp + +.B temp +- the mdb entry is temporary (default) +.sp + +.TP +.BI src " SOURCE" +optional source IP address of a sender for this multicast group. If IGMPv3 for IPv4, or +MLDv2 for IPv6 respectively, are enabled it will be included in the lookup when +forwarding multicast traffic. + +.TP +.BI vid " VID" +the VLAN ID which is known to have members of this multicast group. + +.in -8 +.SS bridge mdb delete - delete a multicast group database entry +This command removes an existing mdb entry. + +.PP +The arguments are the same as with +.BR "bridge mdb add" . + +.SS bridge mdb show - list multicast group database entries + +This command displays the current multicast group membership table. The table +is populated by IGMP and MLD snooping in the bridge driver automatically. It +can be altered by +.B bridge mdb add +and +.B bridge mdb del +commands manually too. + +.TP +.BI dev " DEV" +the interface only whose entries should be listed. Default is to list all +bridge interfaces. + +.PP +With the +.B -details +option, the command becomes verbose. It prints out the ports known to have +a connected router. + +.PP +With the +.B -statistics +option, the command displays timer values for mdb and router port entries. + +.SH bridge vlan - VLAN filter list + +.B vlan +objects contain known VLAN IDs for a link. + +.P +The corresponding commands display vlan filter entries, add new entries, +and delete old ones. + +.SS bridge vlan add - add a new vlan filter entry + +This command creates a new vlan filter entry. + +.TP +.BI dev " NAME" +the interface with which this vlan is associated. + +.TP +.BI vid " VID" +the VLAN ID that identifies the vlan. + +.TP +.BI tunnel_info " TUNNEL_ID" +the TUNNEL ID that maps to this vlan. The tunnel id is set in +dst_metadata for every packet that belongs to this vlan (applicable to +bridge ports with vlan_tunnel flag set). + +.TP +.B pvid +the vlan specified is to be considered a PVID at ingress. +Any untagged frames will be assigned to this VLAN. + +.TP +.B untagged +the vlan specified is to be treated as untagged on egress. + +.TP +.B self +the vlan is configured on the specified physical device. Required if the +device is the bridge device. + +.TP +.B master +the vlan is configured on the software bridge (default). + +.SS bridge vlan delete - delete a vlan filter entry +This command removes an existing vlan filter entry. + +.PP +The arguments are the same as with +.BR "bridge vlan add". +The +.BR "pvid " and " untagged" +flags are ignored. + +.SS bridge vlan set - change vlan filter entry's options + +This command changes vlan filter entry's options. + +.TP +.BI dev " NAME" +the interface with which this vlan is associated. + +.TP +.BI vid " VID" +the VLAN ID that identifies the vlan. + +.TP +.BI state " STP_STATE " +the operation state of the vlan. One may enter STP state name (case insensitive), or one of the +numbers below. Negative inputs are ignored, and unrecognized names return an +error. Note that the state is set only for the vlan of the specified device, e.g. if it is +a bridge port then the state will be set only for the vlan of the port. + +.B 0 +- vlan is in STP +.B DISABLED +state. Make this vlan completely inactive for STP. This is also called +BPDU filter and could be used to disable STP on an untrusted vlan. +.sp + +.B 1 +- vlan is in STP +.B LISTENING +state. Only valid if STP is enabled on the bridge. In this +state the vlan listens for STP BPDUs and drops all other traffic frames. +.sp + +.B 2 +- vlan is in STP +.B LEARNING +state. Only valid if STP is enabled on the bridge. In this +state the vlan will accept traffic only for the purpose of updating MAC +address tables. +.sp + +.B 3 +- vlan is in STP +.B FORWARDING +state. This is the default vlan state. +.sp + +.B 4 +- vlan is in STP +.B BLOCKING +state. Only valid if STP is enabled on the bridge. This state +is used during the STP election process. In this state, the vlan will only process +STP BPDUs. +.sp + +.SS bridge vlan show - list vlan configuration. + +This command displays the current VLAN filter table. + +.PP +With the +.B -details +option, the command becomes verbose. It displays the per-vlan options. + +.PP +With the +.B -statistics +option, the command displays per-vlan traffic statistics. + +.SS bridge vlan tunnelshow - list vlan tunnel mapping. + +This command displays the current vlan tunnel info mapping. + +.SH bridge monitor - state monitoring + +The +.B bridge +utility can monitor the state of devices and addresses +continuously. This option has a slightly different format. +Namely, the +.B monitor +command is the first in the command line and then the object list follows: + +.BR "bridge monitor" " [ " all " |" +.IR OBJECT-LIST " ]" + +.I OBJECT-LIST +is the list of object types that we want to monitor. +It may contain +.BR link ", " fdb ", " vlan " and " mdb "." +If no +.B file +argument is given, +.B bridge +opens RTNETLINK, listens on it and dumps state changes in the format +described in previous sections. + +.P +If a file name is given, it does not listen on RTNETLINK, +but opens the file containing RTNETLINK messages saved in binary format +and dumps them. + +.SH NOTES +This command uses facilities added in Linux 3.0. + +Although the forwarding table is maintained on a per-bridge device basis +the bridge device is not part of the syntax. This is a limitation of the +underlying netlink neighbour message protocol. When displaying the +forwarding table, entries for all bridges are displayed. +Add/delete/modify commands determine the underlying bridge device +based on the bridge to which the corresponding ethernet device is attached. + + +.SH SEE ALSO +.BR ip (8) +.SH BUGS +.RB "Please direct bugreports and patches to: " + +.SH AUTHOR +Original Manpage by Stephen Hemminger diff --git a/man/man8/ip-address.8.in b/man/man8/ip-address.8.in new file mode 100644 index 0000000..fe773c9 --- /dev/null +++ b/man/man8/ip-address.8.in @@ -0,0 +1,465 @@ +.TH "IP\-ADDRESS" 8 "20 Dec 2011" "iproute2" "Linux" +.SH "NAME" +ip-address \- protocol address management +.SH "SYNOPSIS" +.sp +.ad l +.in +8 +.ti -8 +.B ip +.RI "[ " OPTIONS " ]" +.B address +.RI " { " COMMAND " | " +.BR help " }" +.sp + +.ti -8 +.BR "ip address" " { " add " | " change " | " replace " } " +.IB IFADDR " dev " IFNAME +.RI "[ " LIFETIME " ] [ " CONFFLAG-LIST " ]" + +.ti -8 +.BR "ip address del" +.IB IFADDR " dev " IFNAME " [ " mngtmpaddr " ]" + +.ti -8 +.BR "ip address" " { " save " | " flush " } [ " dev +.IR IFNAME " ] [ " +.B scope +.IR SCOPE-ID " ] [ " +.B metric +.IR METRIC " ] [ " +.B to +.IR PREFIX " ] [ " FLAG-LIST " ] [ " +.B label +.IR PATTERN " ] [ " up " ]" + +.ti -8 +.BR "ip address" " [ " show " [ " dev +.IR IFNAME " ] [ " +.B scope +.IR SCOPE-ID " ] [ " +.B to +.IR PREFIX " ] [ " FLAG-LIST " ] [ " +.B label +.IR PATTERN " ] [ " +.B master +.IR DEVICE " ] [ " +.B type +.IR TYPE " ] [ " +.B vrf +.IR NAME " ] [ " +.BR up " ] ]" + +.ti -8 +.BR "ip address" " { " showdump " | " restore " }" + +.ti -8 +.IR IFADDR " := " PREFIX " | " ADDR +.B peer +.IR PREFIX " [ " +.B broadcast +.IR ADDR " ] [ " +.B anycast +.IR ADDR " ] [ " +.B label +.IR LABEL " ] [ " +.B scope +.IR SCOPE-ID " ]" + +.ti -8 +.IR SCOPE-ID " := " +.RB "[ " host " | " link " | " global " | " +.IR NUMBER " ]" + +.ti -8 +.IR FLAG-LIST " := [ " FLAG-LIST " ] " FLAG + +.ti -8 +.IR FLAG " := [" +.RB [ - ] permanent " |" +.RB [ - ] dynamic " |" +.RB [ - ] secondary " |" +.RB [ - ] primary " |" +.RB [ - ] tentative " |" +.RB [ - ] deprecated " |" +.RB [ - ] dadfailed " |" +.RB [ - ] temporary " |" +.IR CONFFLAG-LIST " ]" + +.ti -8 +.IR CONFFLAG-LIST " := [ " CONFFLAG-LIST " ] " CONFFLAG + +.ti -8 +.IR CONFFLAG " := " +.RB "[ " home " | " mngtmpaddr " | " nodad " | " optimstic " | " noprefixroute " | " autojoin " ]" + +.ti -8 +.IR LIFETIME " := [ " +.BI valid_lft " LFT" +.RB "] [ " preferred_lft +.IR LFT " ]" + +.ti -8 +.IR LFT " := [ " +.BR forever " |" +.IR SECONDS " ]" + +.ti -8 +.IR TYPE " := [ " +.BR bridge " | " +.BR bridge_slave " |" +.BR bond " | " +.BR bond_slave " |" +.BR can " | " +.BR dummy " | " +.BR hsr " | " +.BR ifb " | " +.BR ipoib " |" +.BR macvlan " | " +.BR macvtap " | " +.BR vcan " | " +.BR veth " | " +.BR vlan " | " +.BR vxlan " |" +.BR ip6tnl " |" +.BR ipip " |" +.BR sit " |" +.BR gre " |" +.BR gretap " |" +.BR erspan " |" +.BR ip6gre " |" +.BR ip6gretap " |" +.BR ip6erspan " |" +.BR vti " |" +.BR vrf " |" +.BR nlmon " |" +.BR ipvlan " |" +.BR lowpan " |" +.BR geneve " |" +.BR macsec " ]" + +.SH "DESCRIPTION" +The +.B address +is a protocol (IPv4 or IPv6) address attached +to a network device. Each device must have at least one address +to use the corresponding protocol. It is possible to have several +different addresses attached to one device. These addresses are not +discriminated, so that the term +.B alias +is not quite appropriate for them and we do not use it in this document. +.sp +The +.B ip address +command displays addresses and their properties, adds new addresses +and deletes old ones. + +.SS ip address add - add new protocol address. + +.TP +.BI dev " IFNAME " +the name of the device to add the address to. + +.TP +.BI local " ADDRESS " (default) +the address of the interface. The format of the address depends +on the protocol. It is a dotted quad for IP and a sequence of +hexadecimal halfwords separated by colons for IPv6. The +.I ADDRESS +may be followed by a slash and a decimal number which encodes +the network prefix length. + +.TP +.BI peer " ADDRESS" +the address of the remote endpoint for pointopoint interfaces. +Again, the +.I ADDRESS +may be followed by a slash and a decimal number, encoding the network +prefix length. If a peer address is specified, the local address +cannot have a prefix length. The network prefix is associated +with the peer rather than with the local address. + +.TP +.BI broadcast " ADDRESS" +the broadcast address on the interface. +.sp +It is possible to use the special symbols +.B '+' +and +.B '-' +instead of the broadcast address. In this case, the broadcast address +is derived by setting/resetting the host bits of the interface prefix. + +.TP +.BI label " LABEL" +Each address may be tagged with a label string. +In order to preserve compatibility with Linux-2.0 net aliases, +this string must coincide with the name of the device or must be prefixed +with the device name followed by colon. +The maximum allowed total length of label is 15 characters. + +.TP +.BI scope " SCOPE_VALUE" +the scope of the area where this address is valid. +The available scopes are listed in file +.BR "@SYSCONFDIR@/rt_scopes" . +Predefined scope values are: + +.in +8 +.B global +- the address is globally valid. +.sp +.B site +- (IPv6 only, deprecated) the address is site local, i.e. it is +valid inside this site. +.sp +.B link +- the address is link local, i.e. it is valid only on this device. +.sp +.B host +- the address is valid only inside this host. +.in -8 + +.TP +.BI metric " NUMBER" +priority of prefix route associated with address. + +.TP +.BI valid_lft " LFT" +the valid lifetime of this address; see section 5.5.4 of +RFC 4862. When it expires, the address is removed by the kernel. +Defaults to +.BR "forever" . + +.TP +.BI preferred_lft " LFT" +the preferred lifetime of this address; see section 5.5.4 +of RFC 4862. When it expires, the address is no longer used for new +outgoing connections. Defaults to +.BR "forever" . + +.TP +.B home +(IPv6 only) designates this address the "home address" as defined in +RFC 6275. + +.TP +.B mngtmpaddr +(IPv6 only) make the kernel manage temporary addresses created from this one as +template on behalf of Privacy Extensions (RFC3041). For this to become active, +the \fBuse_tempaddr\fP sysctl setting has to be set to a value greater than +zero. The given address needs to have a prefix length of 64. This flag allows +to use privacy extensions in a manually configured network, just like if +stateless auto-configuration was active. + +.TP +.B nodad +(IPv6 only) do not perform Duplicate Address Detection (RFC 4862) when +adding this address. + +.TP +.B optimistic +(IPv6 only) When performing Duplicate Address Detection, use the RFC 4429 +optimistic variant. + +.TP +.B noprefixroute +Do not automatically create a route for the network prefix of the added +address, and don't search for one to delete when removing the address. Changing +an address to add this flag will remove the automatically added prefix route, +changing it to remove this flag will create the prefix route automatically. + +.TP +.B autojoin +Joining multicast groups on Ethernet level via +.B "ip maddr" +command does not work if connected to an Ethernet switch that does IGMP +snooping since the switch would not replicate multicast packets on ports that +did not have IGMP reports for the multicast addresses. + +Linux VXLAN interfaces created via +.B "ip link add vxlan" +have the +.B group +option that enables them to do the required join. + +Using the +.B autojoin +flag when adding a multicast address enables similar functionality for +Openvswitch VXLAN interfaces as well as other tunneling mechanisms that need to +receive multicast traffic. + +.SS ip address delete - delete protocol address +.B Arguments: +coincide with the arguments of +.B ip addr add. +The device name is a required argument. The rest are optional. +If no arguments are given, the first address is deleted. + +.SS ip address show - look at protocol addresses + +.TP +.BI dev " IFNAME " (default) +name of device. + +.TP +.BI scope " SCOPE_VAL" +only list addresses with this scope. + +.TP +.BI to " PREFIX" +only list addresses matching this prefix. + +.TP +.BI label " PATTERN" +only list addresses with labels matching the +.IR "PATTERN" . +.I PATTERN +is a usual shell style pattern. + +.TP +.BI master " DEVICE" +only list interfaces enslaved to this master device. + +.TP +.BI vrf " NAME " +only list interfaces enslaved to this vrf. + +.TP +.BI type " TYPE" +only list interfaces of the given type. + +Note that the type name is not checked against the list of supported types - +instead it is sent as-is to the kernel. Later it is used to filter the returned +interface list by comparing it with the relevant attribute in case the kernel +didn't filter already. Therefore any string is accepted, but may lead to empty +output. + +.TP +.B up +only list running interfaces. + +.TP +.BR dynamic " and " permanent +(IPv6 only) only list addresses installed due to stateless +address configuration or only list permanent (not dynamic) +addresses. These two flags are inverses of each other, so +.BR -dynamic " is equal to " permanent " and " +.BR -permanent " is equal to " dynamic . + +.TP +.B tentative +(IPv6 only) only list addresses which have not yet passed duplicate +address detection. + +.TP +.B -tentative +(IPv6 only) only list addresses which are not in the process of +duplicate address detection currently. + +.TP +.B deprecated +(IPv6 only) only list deprecated addresses. + +.TP +.B -deprecated +(IPv6 only) only list addresses not being deprecated. + +.TP +.B dadfailed +(IPv6 only) only list addresses which have failed duplicate +address detection. + +.TP +.B -dadfailed +(IPv6 only) only list addresses which have not failed duplicate +address detection. + +.TP +.BR temporary " or " secondary +List temporary IPv6 or secondary IPv4 addresses only. The Linux kernel shares a +single bit for those, so they are actually aliases for each other although the +meaning differs depending on address family. + +.TP +.BR -temporary " or " -secondary +These flags are aliases for +.BR primary . + +.TP +.B primary +List only primary addresses, in IPv6 exclude temporary ones. This flag is the +inverse of +.BR temporary " and " secondary . + +.TP +.B -primary +This is an alias for +.BR temporary " or " secondary . + +.SS ip address flush - flush protocol addresses +This command flushes the protocol addresses selected by some criteria. + +.PP +This command has the same arguments as +.BR show " except that " type " and " master " selectors are not supported." +Another difference is that it does not run when no arguments are given. + +.PP +.B Warning: +This command and other +.B flush +commands are unforgiving. They will cruelly purge all the addresses. + +.PP +With the +.B -statistics +option, the command becomes verbose. It prints out the number of deleted +addresses and the number of rounds made to flush the address list. +If this option is given twice, +.B ip address flush +also dumps all the deleted addresses in the format described in the +previous subsection. + +.SH "EXAMPLES" +.PP +ip address show +.RS 4 +Shows IPv4 and IPv6 addresses assigned to all network interfaces. The 'show' +subcommand can be omitted. +.RE +.PP +ip address show up +.RS 4 +Same as above except that only addresses assigned to active network interfaces +are shown. +.RE +.PP +ip address show dev eth0 +.RS 4 +Shows IPv4 and IPv6 addresses assigned to network interface eth0. +.RE +.PP +ip address add 2001:0db8:85a3::0370:7334/64 dev eth1 +.RS 4 +Adds an IPv6 address to network interface eth1. +.RE +.PP +ip address delete 2001:0db8:85a3::0370:7334/64 dev eth1 +.RS 4 +Delete the IPv6 address added above. +.RE +.PP +ip address flush dev eth4 scope global +.RS 4 +Removes all global IPv4 and IPv6 addresses from device eth4. Without 'scope +global' it would remove all addresses including IPv6 link-local ones. +.RE + +.SH SEE ALSO +.br +.BR ip (8) + +.SH AUTHOR +Original Manpage by Michail Litvak diff --git a/man/man8/ip-link.8 b/man/man8/ip-link.8 new file mode 100644 index 0000000..6714ef6 --- /dev/null +++ b/man/man8/ip-link.8 @@ -0,0 +1,2655 @@ +.TH IP\-LINK 8 "13 Dec 2012" "iproute2" "Linux" +.SH "NAME" +ip-link \- network device configuration +.SH "SYNOPSIS" +.sp +.ad l +.in +8 +.ti -8 +.B ip link +.RI " { " COMMAND " | " +.BR help " }" +.sp + +.ti -8 +.BI "ip link add" +.RB "[ " link +.IR DEVICE " ]" +.RB "[ " name " ]" +.I NAME +.br +.RB "[ " txqueuelen +.IR PACKETS " ]" +.br +.RB "[ " address +.IR LLADDR " ]" +.RB "[ " broadcast +.IR LLADDR " ]" +.br +.RB "[ " mtu +.IR MTU " ]" +.RB "[ " index +.IR IDX " ]" +.br +.RB "[ " numtxqueues +.IR QUEUE_COUNT " ]" +.RB "[ " numrxqueues +.IR QUEUE_COUNT " ]" +.br +.BR "[ " gso_max_size +.IR BYTES " ]" +.RB "[ " gso_max_segs +.IR SEGMENTS " ]" +.br +.BI type " TYPE" +.RI "[ " ARGS " ]" + +.ti -8 +.BR "ip link delete " { +.IR DEVICE " | " +.BI "group " GROUP +} +.BI type " TYPE" +.RI "[ " ARGS " ]" + +.ti -8 +.BR "ip link set " { +.IR DEVICE " | " +.BI "group " GROUP +} +.br +.RB "[ { " up " | " down " } ]" +.br +.RB "[ " type +.IR "ETYPE TYPE_ARGS" " ]" +.br +.RB "[ " arp " { " on " | " off " } ]" +.br +.RB "[ " dynamic " { " on " | " off " } ]" +.br +.RB "[ " multicast " { " on " | " off " } ]" +.br +.RB "[ " allmulticast " { " on " | " off " } ]" +.br +.RB "[ " promisc " { " on " | " off " } ]" +.br +.RB "[ " protodown " { " on " | " off " } ]" +.br +.RB "[ " protodown_reason +.IR PREASON " { " on " | " off " } ]" +.br +.RB "[ " trailers " { " on " | " off " } ]" +.br +.RB "[ " txqueuelen +.IR PACKETS " ]" +.br +.RB "[ " name +.IR NEWNAME " ]" +.br +.RB "[ " address +.IR LLADDR " ]" +.br +.RB "[ " broadcast +.IR LLADDR " ]" +.br +.RB "[ " mtu +.IR MTU " ]" +.br +.RB "[ " netns " {" +.IR PID " | " NETNSNAME " } ]" +.br +.RB "[ " link-netnsid +.IR ID " ]" +.br +.RB "[ " alias +.IR NAME " ]" +.br +.RB "[ " vf +.IR NUM " [" +.B mac +.IR LLADDR " ]" +.br +.in +9 +.RI "[ " VFVLAN-LIST " ]" +.br +.RB "[ " rate +.IR TXRATE " ]" +.br +.RB "[ " max_tx_rate +.IR TXRATE " ]" +.br +.RB "[ " min_tx_rate +.IR TXRATE " ]" +.br +.RB "[ " spoofchk " { " on " | " off " } ]" +.br +.RB "[ " query_rss " { " on " | " off " } ]" +.br +.RB "[ " state " { " auto " | " enable " | " disable " } ]" +.br +.RB "[ " trust " { " on " | " off " } ]" +.br +.RB "[ " node_guid " eui64 ]" +.br +.RB "[ " port_guid " eui64 ] ]" +.br +.in -9 +.RB "[ { " xdp " | " xdpgeneric " | " xdpdrv " | " xdpoffload " } { " off " | " +.br +.in +8 +.BR object +.IR FILE +.RB "[ " section +.IR NAME " ]" +.RB "[ " verbose " ] |" +.br +.BR pinned +.IR FILE " } ]" +.br +.in -8 +.RB "[ " master +.IR DEVICE " ]" +.br +.RB "[ " nomaster " ]" +.br +.RB "[ " vrf +.IR NAME " ]" +.br +.RB "[ " addrgenmode " { " eui64 " | " none " | " stable_secret " | " random " } ]" +.br +.RB "[ " macaddr +.RI "[ " MACADDR " ]" +.br +.in +10 +.RB "[ { " flush " | " add " | " del " } " +.IR MACADDR " ]" +.br +.RB "[ " set +.IR MACADDR " ] ]" +.br + +.ti -8 +.B ip link show +.RI "[ " DEVICE " | " +.B group +.IR GROUP " ] [" +.BR up " ] [" +.B master +.IR DEVICE " ] [" +.B type +.IR ETYPE " ] [" +.B vrf +.IR NAME " ]" + +.ti -8 +.B ip link xstats +.BI type " TYPE" +.RI "[ " ARGS " ]" + +.ti -8 +.B ip link afstats +.RB "[ " dev +.IR DEVICE " ]" + +.ti -8 +.B ip link help +.RI "[ " TYPE " ]" + +.ti -8 +.IR TYPE " := [ " +.BR bridge " | " +.BR bond " | " +.BR can " | " +.BR dummy " | " +.BR hsr " | " +.BR ifb " | " +.BR ipoib " |" +.BR macvlan " | " +.BR macvtap " | " +.BR vcan " | " +.BR vxcan " | " +.BR veth " | " +.BR vlan " | " +.BR vxlan " |" +.BR ip6tnl " |" +.BR ipip " |" +.BR sit " |" +.BR gre " |" +.BR gretap " |" +.BR erspan " |" +.BR ip6gre " |" +.BR ip6gretap " |" +.BR ip6erspan " |" +.BR vti " |" +.BR nlmon " |" +.BR ipvlan " |" +.BR ipvtap " |" +.BR lowpan " |" +.BR geneve " |" +.BR bareudp " |" +.BR vrf " |" +.BR macsec " |" +.BR netdevsim " |" +.BR rmnet " |" +.BR xfrm " ]" + +.ti -8 +.IR ETYPE " := [ " TYPE " |" +.BR bridge_slave " | " bond_slave " ]" + +.ti -8 +.IR VFVLAN-LIST " := [ " VFVLAN-LIST " ] " VFVLAN + +.ti -8 +.IR VFVLAN " := " +.RB "[ " vlan +.IR VLANID " [ " +.B qos +.IR VLAN-QOS " ] [" +.B proto +.IR VLAN-PROTO " ] ]" +.in -8 + +.ti -8 +.BI "ip link property add dev " DEVICE +.RB "[ " altname +.IR NAME " .. ]" + +.ti -8 +.BI "ip link property del dev " DEVICE +.RB "[ " altname +.IR NAME " .. ]" + +.SH "DESCRIPTION" +.SS ip link add - add virtual link + +.TP +.BI link " DEVICE " +specifies the physical device to act operate on. + +.I NAME +specifies the name of the new virtual device. + +.I TYPE +specifies the type of the new device. +.sp +Link types: + +.in +8 +.B bridge +- Ethernet Bridge device +.sp +.B bond +- Bonding device +.sp +.B dummy +- Dummy network interface +.sp +.B hsr +- High-availability Seamless Redundancy device +.sp +.B ifb +- Intermediate Functional Block device +.sp +.B ipoib +- IP over Infiniband device +.sp +.B macvlan +- Virtual interface base on link layer address (MAC) +.sp +.B macvtap +- Virtual interface based on link layer address (MAC) and TAP. +.sp +.B vcan +- Virtual Controller Area Network interface +.sp +.B vxcan +- Virtual Controller Area Network tunnel interface +.sp +.B veth +- Virtual ethernet interface +.sp +.BR vlan +- 802.1q tagged virtual LAN interface +.sp +.BR vxlan +- Virtual eXtended LAN +.sp +.BR ip6tnl +- Virtual tunnel interface IPv4|IPv6 over IPv6 +.sp +.BR ipip +- Virtual tunnel interface IPv4 over IPv4 +.sp +.BR sit +- Virtual tunnel interface IPv6 over IPv4 +.sp +.BR gre +- Virtual tunnel interface GRE over IPv4 +.sp +.BR gretap +- Virtual L2 tunnel interface GRE over IPv4 +.sp +.BR erspan +- Encapsulated Remote SPAN over GRE and IPv4 +.sp +.BR ip6gre +- Virtual tunnel interface GRE over IPv6 +.sp +.BR ip6gretap +- Virtual L2 tunnel interface GRE over IPv6 +.sp +.BR ip6erspan +- Encapsulated Remote SPAN over GRE and IPv6 +.sp +.BR vti +- Virtual tunnel interface +.sp +.BR nlmon +- Netlink monitoring device +.sp +.BR ipvlan +- Interface for L3 (IPv6/IPv4) based VLANs +.sp +.BR ipvtap +- Interface for L3 (IPv6/IPv4) based VLANs and TAP +.sp +.BR lowpan +- Interface for 6LoWPAN (IPv6) over IEEE 802.15.4 / Bluetooth +.sp +.BR geneve +- GEneric NEtwork Virtualization Encapsulation +.sp +.BR bareudp +- Bare UDP L3 encapsulation support +.sp +.BR macsec +- Interface for IEEE 802.1AE MAC Security (MACsec) +.sp +.BR vrf +- Interface for L3 VRF domains +.sp +.BR netdevsim +- Interface for netdev API tests +.sp +.BR rmnet +- Qualcomm rmnet device +.sp +.BR xfrm +- Virtual xfrm interface +.in -8 + +.TP +.BI numtxqueues " QUEUE_COUNT " +specifies the number of transmit queues for new device. + +.TP +.BI numrxqueues " QUEUE_COUNT " +specifies the number of receive queues for new device. + +.TP +.BI gso_max_size " BYTES " +specifies the recommended maximum size of a Generic Segment Offload +packet the new device should accept. + +.TP +.BI gso_max_segs " SEGMENTS " +specifies the recommended maximum number of a Generic Segment Offload +segments the new device should accept. + +.TP +.BI index " IDX " +specifies the desired index of the new virtual device. The link +creation fails, if the index is busy. + +.TP +VLAN Type Support +For a link of type +.I VLAN +the following additional arguments are supported: + +.BI "ip link add +.BI link " DEVICE " +.BI name " NAME " +.B "type vlan" +[ +.BI protocol " VLAN_PROTO " +] +.BI id " VLANID " +[ +.BR reorder_hdr " { " on " | " off " } " +] +[ +.BR gvrp " { " on " | " off " } " +] +[ +.BR mvrp " { " on " | " off " } " +] +[ +.BR loose_binding " { " on " | " off " } " +] +[ +.BR bridge_binding " { " on " | " off " } " +] +[ +.BI ingress-qos-map " QOS-MAP " +] +[ +.BI egress-qos-map " QOS-MAP " +] + +.in +8 +.sp +.BI protocol " VLAN_PROTO " +- either 802.1Q or 802.1ad. + +.BI id " VLANID " +- specifies the VLAN Identifier to use. Note that numbers with a leading " 0 " or " 0x " are interpreted as octal or hexadecimal, respectively. + +.BR reorder_hdr " { " on " | " off " } " +- specifies whether ethernet headers are reordered or not (default is +.BR on ")." + +.in +4 +If +.BR reorder_hdr " is " on +then VLAN header will be not inserted immediately but only before +passing to the physical device (if this device does not support VLAN +offloading), the similar on the RX direction - by default the packet +will be untagged before being received by VLAN device. Reordering +allows to accelerate tagging on egress and to hide VLAN header on +ingress so the packet looks like regular Ethernet packet, at the same +time it might be confusing for packet capture as the VLAN header does +not exist within the packet. + +VLAN offloading can be checked by +.BR ethtool "(8):" +.in +4 +.sp +.B ethtool -k + | +.RB grep " tx-vlan-offload" +.sp +.in -4 +where is the physical device to which VLAN device is bound. +.in -4 + +.BR gvrp " { " on " | " off " } " +- specifies whether this VLAN should be registered using GARP VLAN + Registration Protocol. + +.BR mvrp " { " on " | " off " } " +- specifies whether this VLAN should be registered using Multiple VLAN + Registration Protocol. + +.BR loose_binding " { " on " | " off " } " +- specifies whether the VLAN device state is bound to the physical device state. + +.BR bridge_binding " { " on " | " off " } " +- specifies whether the VLAN device link state tracks the state of bridge ports +that are members of the VLAN. + +.BI ingress-qos-map " QOS-MAP " +- defines a mapping of VLAN header prio field to the Linux internal packet +priority on incoming frames. The format is FROM:TO with multiple mappings +separated by spaces. + +.BI egress-qos-map " QOS-MAP " +- defines a mapping of Linux internal packet priority to VLAN header prio field +but for outgoing frames. The format is the same as for ingress-qos-map. +.in +4 + +Linux packet priority can be set by +.BR iptables "(8)": +.in +4 +.sp +.B iptables +-t mangle -A POSTROUTING [...] -j CLASSIFY --set-class 0:4 +.sp +.in -4 +and this "4" priority can be used in the egress qos mapping to set +VLAN prio "5": +.sp +.in +4 +.B ip +link set veth0.10 type vlan egress 4:5 +.in -4 +.in -4 +.in -8 + +.TP +VXLAN Type Support +For a link of type +.I VXLAN +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BI type " vxlan " id " VNI" +[ +.BI dev " PHYS_DEV " +.RB " ] [ { " group " | " remote " } " +.I IPADDR +] [ +.B local +.RI "{ "IPADDR " | "any " } " +] [ +.BI ttl " TTL " +] [ +.BI tos " TOS " +] [ +.BI df " DF " +] [ +.BI flowlabel " FLOWLABEL " +] [ +.BI dstport " PORT " +] [ +.BI srcport " MIN MAX " +] [ +.RB [ no ] learning +] [ +.RB [ no ] proxy +] [ +.RB [ no ] rsc +] [ +.RB [ no ] l2miss +] [ +.RB [ no ] l3miss +] [ +.RB [ no ] udpcsum +] [ +.RB [ no ] udp6zerocsumtx +] [ +.RB [ no ] udp6zerocsumrx +] [ +.BI ageing " SECONDS " +] [ +.BI maxaddress " NUMBER " +] [ +.RB [ no ] external +] [ +.B gbp +] [ +.B gpe +] + +.in +8 +.sp +.BI id " VNI " +- specifies the VXLAN Network Identifier (or VXLAN Segment +Identifier) to use. + +.BI dev " PHYS_DEV" +- specifies the physical device to use for tunnel endpoint communication. + +.sp +.BI group " IPADDR" +- specifies the multicast IP address to join. +This parameter cannot be specified with the +.B remote +parameter. + +.sp +.BI remote " IPADDR" +- specifies the unicast destination IP address to use in outgoing packets +when the destination link layer address is not known in the VXLAN device +forwarding database. This parameter cannot be specified with the +.B group +parameter. + +.sp +.BI local " IPADDR" +- specifies the source IP address to use in outgoing packets. + +.sp +.BI ttl " TTL" +- specifies the TTL value to use in outgoing packets. + +.sp +.BI tos " TOS" +- specifies the TOS value to use in outgoing packets. + +.sp +.BI df " DF" +- specifies the usage of the Don't Fragment flag (DF) bit in outgoing packets +with IPv4 headers. The value +.B inherit +causes the bit to be copied from the original IP header. The values +.B unset +and +.B set +cause the bit to be always unset or always set, respectively. By default, the +bit is not set. + +.sp +.BI flowlabel " FLOWLABEL" +- specifies the flow label to use in outgoing packets. + +.sp +.BI dstport " PORT" +- specifies the UDP destination port to communicate to the remote + VXLAN tunnel endpoint. + +.sp +.BI srcport " MIN MAX" +- specifies the range of port numbers to use as UDP +source ports to communicate to the remote VXLAN tunnel endpoint. + +.sp +.RB [ no ] learning +- specifies if unknown source link layer addresses and IP addresses +are entered into the VXLAN device forwarding database. + +.sp +.RB [ no ] rsc +- specifies if route short circuit is turned on. + +.sp +.RB [ no ] proxy +- specifies ARP proxy is turned on. + +.sp +.RB [ no ] l2miss +- specifies if netlink LLADDR miss notifications are generated. + +.sp +.RB [ no ] l3miss +- specifies if netlink IP ADDR miss notifications are generated. + +.sp +.RB [ no ] udpcsum +- specifies if UDP checksum is calculated for transmitted packets over IPv4. + +.sp +.RB [ no ] udp6zerocsumtx +- skip UDP checksum calculation for transmitted packets over IPv6. + +.sp +.RB [ no ] udp6zerocsumrx +- allow incoming UDP packets over IPv6 with zero checksum field. + +.sp +.BI ageing " SECONDS" +- specifies the lifetime in seconds of FDB entries learnt by the kernel. + +.sp +.BI maxaddress " NUMBER" +- specifies the maximum number of FDB entries. + +.sp +.RB [ no ] external +- specifies whether an external control plane +.RB "(e.g. " "ip route encap" ) +or the internal FDB should be used. + +.sp +.B gbp +- enables the Group Policy extension (VXLAN-GBP). + +.in +4 +Allows to transport group policy context across VXLAN network peers. +If enabled, includes the mark of a packet in the VXLAN header for outgoing +packets and fills the packet mark based on the information found in the +VXLAN header for incoming packets. + +Format of upper 16 bits of packet mark (flags); + +.in +2 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.br +|-|-|-|-|-|-|-|-|-|D|-|-|A|-|-|-| +.br ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + +.B D := +Don't Learn bit. When set, this bit indicates that the egress +VTEP MUST NOT learn the source address of the encapsulated frame. + +.B A := +Indicates that the group policy has already been applied to +this packet. Policies MUST NOT be applied by devices when the A bit is set. +.in -2 + +Format of lower 16 bits of packet mark (policy ID): + +.in +2 ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.br +| Group Policy ID | +.br ++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +.in -2 + +Example: + iptables -A OUTPUT [...] -j MARK --set-mark 0x800FF + +.in -4 + +.sp +.B gpe +- enables the Generic Protocol extension (VXLAN-GPE). Currently, this is +only supported together with the +.B external +keyword. + +.in -8 + +.TP +VETH, VXCAN Type Support +For a link of types +.I VETH/VXCAN +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BR type " { " veth " | " vxcan " }" +[ +.BR peer +.BI "name " NAME +] + +.in +8 +.sp +.BR peer +.BI "name " NAME +- specifies the virtual pair device name of the +.I VETH/VXCAN +tunnel. + +.in -8 + +.TP +IPIP, SIT Type Support +For a link of type +.IR IPIP or SIT +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BR type " { " ipip " | " sit " }" +.BI " remote " ADDR " local " ADDR +[ +.BR encap " { " fou " | " gue " | " none " }" +] [ +.BR encap-sport " { " \fIPORT " | " auto " }" +] [ +.BI "encap-dport " PORT +] [ +.RB [ no ] encap-csum +] [ +.I " [no]encap-remcsum " +] [ +.I " mode " { ip6ip | ipip | mplsip | any } " +] [ +.BR external +] + +.in +8 +.sp +.BI remote " ADDR " +- specifies the remote address of the tunnel. + +.sp +.BI local " ADDR " +- specifies the fixed local address for tunneled packets. +It must be an address on another interface on this host. + +.sp +.BR encap " { " fou " | " gue " | " none " }" +- specifies type of secondary UDP encapsulation. "fou" indicates +Foo-Over-UDP, "gue" indicates Generic UDP Encapsulation. + +.sp +.BR encap-sport " { " \fIPORT " | " auto " }" +- specifies the source port in UDP encapsulation. +.IR PORT +indicates the port by number, "auto" +indicates that the port number should be chosen automatically +(the kernel picks a flow based on the flow hash of the +encapsulated packet). + +.sp +.RB [ no ] encap-csum +- specifies if UDP checksums are enabled in the secondary +encapsulation. + +.sp +.RB [ no ] encap-remcsum +- specifies if Remote Checksum Offload is enabled. This is only +applicable for Generic UDP Encapsulation. + +.sp +.BI mode " { ip6ip | ipip | mplsip | any } " +- specifies mode in which device should run. "ip6ip" indicates +IPv6-Over-IPv4, "ipip" indicates "IPv4-Over-IPv4", "mplsip" indicates +MPLS-Over-IPv4, "any" indicates IPv6, IPv4 or MPLS Over IPv4. Supported for +SIT where the default is "ip6ip" and IPIP where the default is "ipip". +IPv6-Over-IPv4 is not supported for IPIP. + +.sp +.BR external +- make this tunnel externally controlled +.RB "(e.g. " "ip route encap" ). + +.in -8 +.TP +GRE Type Support +For a link of type +.IR GRE " or " GRETAP +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BR type " { " gre " | " gretap " }" +.BI " remote " ADDR " local " ADDR +[ +.RB [ no ] "" [ i | o ] seq +] [ +.RB [ i | o ] key +.I KEY +| +.BR no [ i | o ] key +] [ +.RB [ no ] "" [ i | o ] csum +] [ +.BI ttl " TTL " +] [ +.BI tos " TOS " +] [ +.RB [ no ] pmtudisc +] [ +.RB [ no ] ignore-df +] [ +.BI dev " PHYS_DEV " +] [ +.BR encap " { " fou " | " gue " | " none " }" +] [ +.BR encap-sport " { " \fIPORT " | " auto " }" +] [ +.BI "encap-dport " PORT +] [ +.RB [ no ] encap-csum +] [ +.RB [ no ] encap-remcsum +] [ +.BR external +] + +.in +8 +.sp +.BI remote " ADDR " +- specifies the remote address of the tunnel. + +.sp +.BI local " ADDR " +- specifies the fixed local address for tunneled packets. +It must be an address on another interface on this host. + +.sp +.RB [ no ] "" [ i | o ] seq +- serialize packets. +The +.B oseq +flag enables sequencing of outgoing packets. +The +.B iseq +flag requires that all input packets are serialized. + +.sp +.RB [ i | o ] key +.I KEY +| +.BR no [ i | o ] key +- use keyed GRE with key +.IR KEY ". "KEY +is either a number or an IPv4 address-like dotted quad. +The +.B key +parameter specifies the same key to use in both directions. +The +.BR ikey " and " okey +parameters specify different keys for input and output. + +.sp +.RB [ no ] "" [ i | o ] csum +- generate/require checksums for tunneled packets. +The +.B ocsum +flag calculates checksums for outgoing packets. +The +.B icsum +flag requires that all input packets have the correct +checksum. The +.B csum +flag is equivalent to the combination +.B "icsum ocsum" . + +.sp +.BI ttl " TTL" +- specifies the TTL value to use in outgoing packets. + +.sp +.BI tos " TOS" +- specifies the TOS value to use in outgoing packets. + +.sp +.RB [ no ] pmtudisc +- enables/disables Path MTU Discovery on this tunnel. +It is enabled by default. Note that a fixed ttl is incompatible +with this option: tunneling with a fixed ttl always makes pmtu +discovery. + +.sp +.RB [ no ] ignore-df +- enables/disables IPv4 DF suppression on this tunnel. +Normally datagrams that exceed the MTU will be fragmented; the presence +of the DF flag inhibits this, resulting instead in an ICMP Unreachable +(Fragmentation Required) message. Enabling this attribute causes the +DF flag to be ignored. + +.sp +.BI dev " PHYS_DEV" +- specifies the physical device to use for tunnel endpoint communication. + +.sp +.BR encap " { " fou " | " gue " | " none " }" +- specifies type of secondary UDP encapsulation. "fou" indicates +Foo-Over-UDP, "gue" indicates Generic UDP Encapsulation. + +.sp +.BR encap-sport " { " \fIPORT " | " auto " }" +- specifies the source port in UDP encapsulation. +.IR PORT +indicates the port by number, "auto" +indicates that the port number should be chosen automatically +(the kernel picks a flow based on the flow hash of the +encapsulated packet). + +.sp +.RB [ no ] encap-csum +- specifies if UDP checksums are enabled in the secondary +encapsulation. + +.sp +.RB [ no ] encap-remcsum +- specifies if Remote Checksum Offload is enabled. This is only +applicable for Generic UDP Encapsulation. + +.sp +.BR external +- make this tunnel externally controlled +.RB "(e.g. " "ip route encap" ). + +.in -8 + +.TP +IP6GRE/IP6GRETAP Type Support +For a link of type +.I IP6GRE/IP6GRETAP +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BR type " { " ip6gre " | " ip6gretap " }" +.BI remote " ADDR " local " ADDR" +[ +.RB [ no ] "" [ i | o ] seq +] [ +.RB [ i | o ] key +.I KEY +| +.BR no [ i | o ] key +] [ +.RB [ no ] "" [ i | o ] csum +] [ +.BI hoplimit " TTL " +] [ +.BI encaplimit " ELIM " +] [ +.BI tclass " TCLASS " +] [ +.BI flowlabel " FLOWLABEL " +] [ +.BI "dscp inherit" +] [ +.BI "[no]allow-localremote" +] [ +.BI dev " PHYS_DEV " +] [ +.RB external +] + +.in +8 +.sp +.BI remote " ADDR " +- specifies the remote IPv6 address of the tunnel. + +.sp +.BI local " ADDR " +- specifies the fixed local IPv6 address for tunneled packets. +It must be an address on another interface on this host. + +.sp +.RB [ no ] "" [ i | o ] seq +- serialize packets. +The +.B oseq +flag enables sequencing of outgoing packets. +The +.B iseq +flag requires that all input packets are serialized. + +.sp +.RB [ i | o ] key +.I KEY +| +.BR no [ i | o ] key +- use keyed GRE with key +.IR KEY ". "KEY +is either a number or an IPv4 address-like dotted quad. +The +.B key +parameter specifies the same key to use in both directions. +The +.BR ikey " and " okey +parameters specify different keys for input and output. + +.sp +.RB [ no ] "" [ i | o ] csum +- generate/require checksums for tunneled packets. +The +.B ocsum +flag calculates checksums for outgoing packets. +The +.B icsum +flag requires that all input packets have the correct +checksum. The +.B csum +flag is equivalent to the combination +.BR "icsum ocsum" . + +.sp +.BI hoplimit " TTL" +- specifies Hop Limit value to use in outgoing packets. + +.sp +.BI encaplimit " ELIM" +- specifies a fixed encapsulation limit. Default is 4. + +.sp +.BI flowlabel " FLOWLABEL" +- specifies a fixed flowlabel. + +.sp +.BI [no]allow-localremote +- specifies whether to allow remote endpoint to have an address configured on +local host. + +.sp +.BI tclass " TCLASS" +- specifies the traffic class field on +tunneled packets, which can be specified as either a two-digit +hex value (e.g. c0) or a predefined string (e.g. internet). +The value +.B inherit +causes the field to be copied from the original IP header. The +values +.BI "inherit/" STRING +or +.BI "inherit/" 00 ".." ff +will set the field to +.I STRING +or +.IR 00 ".." ff +when tunneling non-IP packets. The default value is 00. + +.sp +.RB external +- make this tunnel externally controlled (or not, which is the default). +In the kernel, this is referred to as collect metadata mode. This flag is +mutually exclusive with the +.BR remote , +.BR local , +.BR seq , +.BR key, +.BR csum, +.BR hoplimit, +.BR encaplimit, +.BR flowlabel " and " tclass +options. + +.in -8 + +.TP +IPoIB Type Support +For a link of type +.I IPoIB +the following additional arguments are supported: + +.BI "ip link add " DEVICE " name " NAME +.BR "type ipoib " [ " pkey \fIPKEY" " ] [ " mode " \fIMODE \fR]" + +.in +8 +.sp +.BI pkey " PKEY " +- specifies the IB P-Key to use. + +.BI mode " MODE " +- specifies the mode (datagram or connected) to use. + +.TP +ERSPAN Type Support +For a link of type +.I ERSPAN/IP6ERSPAN +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BR type " { " erspan " | " ip6erspan " }" +.BI remote " ADDR " local " ADDR " seq +.RB key +.I KEY +.BR erspan_ver " \fIversion " +[ +.BR erspan " \fIIDX " +] [ +.BR erspan_dir " { " \fIingress " | " \fIegress " }" +] [ +.BR erspan_hwid " \fIhwid " +] [ +.BI "[no]allow-localremote" +] [ +.RB external +] + +.in +8 +.sp +.BI remote " ADDR " +- specifies the remote address of the tunnel. + +.sp +.BI local " ADDR " +- specifies the fixed local address for tunneled packets. +It must be an address on another interface on this host. + +.sp +.BR erspan_ver " \fIversion " +- specifies the ERSPAN version number. +.IR version +indicates the ERSPAN version to be created: 0 for version 0 type I, +1 for version 1 (type II) or 2 for version 2 (type III). + +.sp +.BR erspan " \fIIDX " +- specifies the ERSPAN v1 index field. +.IR IDX +indicates a 20 bit index/port number associated with the ERSPAN +traffic's source port and direction. + +.sp +.BR erspan_dir " { " \fIingress " | " \fIegress " }" +- specifies the ERSPAN v2 mirrored traffic's direction. + +.sp +.BR erspan_hwid " \fIhwid " +- an unique identifier of an ERSPAN v2 engine within a system. +.IR hwid +is a 6-bit value for users to configure. + +.sp +.BI [no]allow-localremote +- specifies whether to allow remote endpoint to have an address configured on +local host. + +.sp +.BR external +- make this tunnel externally controlled (or not, which is the default). +In the kernel, this is referred to as collect metadata mode. This flag is +mutually exclusive with the +.BR remote , +.BR local , +.BR erspan_ver , +.BR erspan , +.BR erspan_dir " and " erspan_hwid +options. + +.in -8 + +.TP +GENEVE Type Support +For a link of type +.I GENEVE +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BI type " geneve " id " VNI " remote " IPADDR" +[ +.BI ttl " TTL " +] [ +.BI tos " TOS " +] [ +.BI df " DF " +] [ +.BI flowlabel " FLOWLABEL " +] [ +.BI dstport " PORT" +] [ +.RB [ no ] external +] [ +.RB [ no ] udpcsum +] [ +.RB [ no ] udp6zerocsumtx +] [ +.RB [ no ] udp6zerocsumrx +] + +.in +8 +.sp +.BI id " VNI " +- specifies the Virtual Network Identifier to use. + +.sp +.BI remote " IPADDR" +- specifies the unicast destination IP address to use in outgoing packets. + +.sp +.BI ttl " TTL" +- specifies the TTL value to use in outgoing packets. "0" or "auto" means +use whatever default value, "inherit" means inherit the inner protocol's +ttl. Default option is "0". + +.sp +.BI tos " TOS" +- specifies the TOS value to use in outgoing packets. + +.sp +.BI df " DF" +- specifies the usage of the Don't Fragment flag (DF) bit in outgoing packets +with IPv4 headers. The value +.B inherit +causes the bit to be copied from the original IP header. The values +.B unset +and +.B set +cause the bit to be always unset or always set, respectively. By default, the +bit is not set. + +.sp +.BI flowlabel " FLOWLABEL" +- specifies the flow label to use in outgoing packets. + +.sp +.BI dstport " PORT" +- select a destination port other than the default of 6081. + +.sp +.RB [ no ] external +- make this tunnel externally controlled (or not, which is the default). This +flag is mutually exclusive with the +.BR id , +.BR remote , +.BR ttl , +.BR tos " and " flowlabel +options. + +.sp +.RB [ no ] udpcsum +- specifies if UDP checksum is calculated for transmitted packets over IPv4. + +.sp +.RB [ no ] udp6zerocsumtx +- skip UDP checksum calculation for transmitted packets over IPv6. + +.sp +.RB [ no ] udp6zerocsumrx +- allow incoming UDP packets over IPv6 with zero checksum field. + +.in -8 + +.TP +Bareudp Type Support +For a link of type +.I Bareudp +the following additional arguments are supported: + +.BI "ip link add " DEVICE +.BI type " bareudp " dstport " PORT " ethertype " PROTO" +[ +.BI srcportmin " PORT " +] [ +.RB [ no ] multiproto +] + +.in +8 +.sp +.BI dstport " PORT" +- specifies the destination port for the UDP tunnel. + +.sp +.BI ethertype " PROTO" +- specifies the ethertype of the L3 protocol being tunnelled. +.B ethertype +can be given as plain Ethernet protocol number or using the protocol name +("ipv4", "ipv6", "mpls_uc", etc.). + +.sp +.BI srcportmin " PORT" +- selects the lowest value of the UDP tunnel source port range. + +.sp +.RB [ no ] multiproto +- activates support for protocols similar to the one +.RB "specified by " ethertype . +When +.B ethertype +is "mpls_uc" (that is, unicast MPLS), this allows the tunnel to also handle +multicast MPLS. +When +.B ethertype +is "ipv4", this allows the tunnel to also handle IPv6. This option is disabled +by default. + +.TP +MACVLAN and MACVTAP Type Support +For a link of type +.I MACVLAN +or +.I MACVTAP +the following additional arguments are supported: + +.BI "ip link add link " DEVICE " name " NAME +.BR type " { " macvlan " | " macvtap " } " +.BR mode " { " private " | " vepa " | " bridge " | " passthru +.RB " [ " nopromisc " ] | " source " [ " nodst " ] } " +.RB " [ " bcqueuelen " { " LENGTH " } ] " + +.in +8 +.sp +.BR type " { " macvlan " | " macvtap " } " +- specifies the link type to use. +.BR macvlan " creates just a virtual interface, while " +.BR macvtap " in addition creates a character device " +.BR /dev/tapX " to be used just like a " tuntap " device." + +.B mode private +- Do not allow communication between +.B macvlan +instances on the same physical interface, even if the external switch supports +hairpin mode. + +.B mode vepa +- Virtual Ethernet Port Aggregator mode. Data from one +.B macvlan +instance to the other on the same physical interface is transmitted over the +physical interface. Either the attached switch needs to support hairpin mode, +or there must be a TCP/IP router forwarding the packets in order to allow +communication. This is the default mode. + +.B mode bridge +- In bridge mode, all endpoints are directly connected to each other, +communication is not redirected through the physical interface's peer. + +.BR mode " " passthru " [ " nopromisc " ] " +- This mode gives more power to a single endpoint, usually in +.BR macvtap " mode. It is not allowed for more than one endpoint on the same " +physical interface. All traffic will be forwarded to this endpoint, allowing +virtio guests to change MAC address or set promiscuous mode in order to bridge +the interface or create vlan interfaces on top of it. By default, this mode +forces the underlying interface into promiscuous mode. Passing the +.BR nopromisc " flag prevents this, so the promisc flag may be controlled " +using standard tools. + +.BR mode " " source " [ " nodst " ] " +- allows one to set a list of allowed mac address, which is used to match +against source mac address from received frames on underlying interface. This +allows creating mac based VLAN associations, instead of standard port or tag +based. The feature is useful to deploy 802.1x mac based behavior, +where drivers of underlying interfaces doesn't allows that. By default, packets +are also considered (duplicated) for destination-based MACVLAN. Passing the +.BR nodst " flag stops matching packets from also going through the " +destination-based flow. + +.BR bcqueuelen " { " LENGTH " } " +- Set the length of the RX queue used to process broadcast and multicast packets. +.BR LENGTH " must be a positive integer in the range [0-4294967295]." +Setting a length of 0 will effectively drop all broadcast/multicast traffic. +If not specified the macvlan driver default (1000) is used. +Note that all macvlans that share the same underlying device are using the same +.RB "queue. The parameter here is a " request ", the actual queue length used" +will be the maximum length that any macvlan interface has requested. +When listing device parameters both the bcqueuelen parameter +as well as the actual used bcqueuelen are listed to better help +the user understand the setting. +.in -8 + +.TP +High-availability Seamless Redundancy (HSR) Support +For a link of type +.I HSR +the following additional arguments are supported: + +.BI "ip link add link " DEVICE " name " NAME " type hsr" +.BI slave1 " SLAVE1-IF " slave2 " SLAVE2-IF " +.RB [ " supervision" +.IR ADDR-BYTE " ] [" +.BR version " { " 0 " | " 1 " } [" +.BR proto " { " 0 " | " 1 " } ]" + +.in +8 +.sp +.BR type " hsr " +- specifies the link type to use, here HSR. + +.BI slave1 " SLAVE1-IF " +- Specifies the physical device used for the first of the two ring ports. + +.BI slave2 " SLAVE2-IF " +- Specifies the physical device used for the second of the two ring ports. + +.BI supervision " ADDR-BYTE" +- The last byte of the multicast address used for HSR supervision frames. +Default option is "0", possible values 0-255. + +.BR version " { " 0 " | " 1 " }" +- Selects the protocol version of the interface. Default option is "0", which +corresponds to the 2010 version of the HSR standard. Option "1" activates the +2012 version. + +.BR proto " { " 0 " | " 1 " }" +- Selects the protocol at the interface. Default option is "0", which +corresponds to the HSR standard. Option "1" activates the Parallel +Redundancy Protocol (PRP). +. +.in -8 + +.TP +BRIDGE Type Support +For a link of type +.I BRIDGE +the following additional arguments are supported: + +.BI "ip link add " DEVICE " type bridge " +[ +.BI ageing_time " AGEING_TIME " +] [ +.BI group_fwd_mask " MASK " +] [ +.BI group_address " ADDRESS " +] [ +.BI forward_delay " FORWARD_DELAY " +] [ +.BI hello_time " HELLO_TIME " +] [ +.BI max_age " MAX_AGE " +] [ +.BI stp_state " STP_STATE " +] [ +.BI priority " PRIORITY " +] [ +.BI vlan_filtering " VLAN_FILTERING " +] [ +.BI vlan_protocol " VLAN_PROTOCOL " +] [ +.BI vlan_default_pvid " VLAN_DEFAULT_PVID " +] [ +.BI vlan_stats_enabled " VLAN_STATS_ENABLED " +] [ +.BI vlan_stats_per_port " VLAN_STATS_PER_PORT " +] [ +.BI mcast_snooping " MULTICAST_SNOOPING " +] [ +.BI mcast_router " MULTICAST_ROUTER " +] [ +.BI mcast_query_use_ifaddr " MCAST_QUERY_USE_IFADDR " +] [ +.BI mcast_querier " MULTICAST_QUERIER " +] [ +.BI mcast_hash_elasticity " HASH_ELASTICITY " +] [ +.BI mcast_hash_max " HASH_MAX " +] [ +.BI mcast_last_member_count " LAST_MEMBER_COUNT " +] [ +.BI mcast_startup_query_count " STARTUP_QUERY_COUNT " +] [ +.BI mcast_last_member_interval " LAST_MEMBER_INTERVAL " +] [ +.BI mcast_membership_interval " MEMBERSHIP_INTERVAL " +] [ +.BI mcast_querier_interval " QUERIER_INTERVAL " +] [ +.BI mcast_query_interval " QUERY_INTERVAL " +] [ +.BI mcast_query_response_interval " QUERY_RESPONSE_INTERVAL " +] [ +.BI mcast_startup_query_interval " STARTUP_QUERY_INTERVAL " +] [ +.BI mcast_stats_enabled " MCAST_STATS_ENABLED " +] [ +.BI mcast_igmp_version " IGMP_VERSION " +] [ +.BI mcast_mld_version " MLD_VERSION " +] [ +.BI nf_call_iptables " NF_CALL_IPTABLES " +] [ +.BI nf_call_ip6tables " NF_CALL_IP6TABLES " +] [ +.BI nf_call_arptables " NF_CALL_ARPTABLES " +] + +.in +8 +.sp +.BI ageing_time " AGEING_TIME " +- configure the bridge's FDB entries ageing time, ie the number of +seconds a MAC address will be kept in the FDB after a packet has been +received from that address. after this time has passed, entries are +cleaned up. + +.BI group_fwd_mask " MASK " +- set the group forward mask. This is the bitmask that is applied to +decide whether to forward incoming frames destined to link-local +addresses, ie addresses of the form 01:80:C2:00:00:0X (defaults to 0, +ie the bridge does not forward any link-local frames). + +.BI group_address " ADDRESS " +- set the MAC address of the multicast group this bridge uses for STP. +The address must be a link-local address in standard Ethernet MAC +address format, ie an address of the form 01:80:C2:00:00:0X, with X + in [0, 4..f]. + +.BI forward_delay " FORWARD_DELAY " +- set the forwarding delay in seconds, ie the time spent in LISTENING +state (before moving to LEARNING) and in LEARNING state (before +moving to FORWARDING). Only relevant if STP is enabled. Valid values +are between 2 and 30. + +.BI hello_time " HELLO_TIME " +- set the time in seconds between hello packets sent by the bridge, +when it is a root bridge or a designated bridges. +Only relevant if STP is enabled. Valid values are between 1 and 10. + +.BI max_age " MAX_AGE " +- set the hello packet timeout, ie the time in seconds until another +bridge in the spanning tree is assumed to be dead, after reception of +its last hello message. Only relevant if STP is enabled. Valid values +are between 6 and 40. + +.BI stp_state " STP_STATE " +- turn spanning tree protocol on +.RI ( STP_STATE " > 0) " +or off +.RI ( STP_STATE " == 0). " +for this bridge. + +.BI priority " PRIORITY " +- set this bridge's spanning tree priority, used during STP root +bridge election. +.I PRIORITY +is a 16bit unsigned integer. + +.BI vlan_filtering " VLAN_FILTERING " +- turn VLAN filtering on +.RI ( VLAN_FILTERING " > 0) " +or off +.RI ( VLAN_FILTERING " == 0). " +When disabled, the bridge will not consider the VLAN tag when handling packets. + +.BR vlan_protocol " { " 802.1Q " | " 802.1ad " } " +- set the protocol used for VLAN filtering. + +.BI vlan_default_pvid " VLAN_DEFAULT_PVID " +- set the default PVID (native/untagged VLAN ID) for this bridge. + +.BI vlan_stats_enabled " VLAN_STATS_ENABLED " +- enable +.RI ( VLAN_STATS_ENABLED " == 1) " +or disable +.RI ( VLAN_STATS_ENABLED " == 0) " +per-VLAN stats accounting. + +.BI vlan_stats_per_port " VLAN_STATS_PER_PORT " +- enable +.RI ( VLAN_STATS_PER_PORT " == 1) " +or disable +.RI ( VLAN_STATS_PER_PORT " == 0) " +per-VLAN per-port stats accounting. Can be changed only when there are no port VLANs configured. + +.BI mcast_snooping " MULTICAST_SNOOPING " +- turn multicast snooping on +.RI ( MULTICAST_SNOOPING " > 0) " +or off +.RI ( MULTICAST_SNOOPING " == 0). " + +.BI mcast_router " MULTICAST_ROUTER " +- set bridge's multicast router if IGMP snooping is enabled. +.I MULTICAST_ROUTER +is an integer value having the following meaning: +.in +8 +.sp +.B 0 +- disabled. + +.B 1 +- automatic (queried). + +.B 2 +- permanently enabled. +.in -8 + +.BI mcast_query_use_ifaddr " MCAST_QUERY_USE_IFADDR " +- whether to use the bridge's own IP address as source address for IGMP queries +.RI ( MCAST_QUERY_USE_IFADDR " > 0) " +or the default of 0.0.0.0 +.RI ( MCAST_QUERY_USE_IFADDR " == 0). " + +.BI mcast_querier " MULTICAST_QUERIER " +- enable +.RI ( MULTICAST_QUERIER " > 0) " +or disable +.RI ( MULTICAST_QUERIER " == 0) " +IGMP querier, ie sending of multicast queries by the bridge (default: disabled). + +.BI mcast_querier_interval " QUERIER_INTERVAL " +- interval between queries sent by other routers. if no queries are seen +after this delay has passed, the bridge will start to send its own queries +(as if +.BI mcast_querier +was enabled). + +.BI mcast_hash_elasticity " HASH_ELASTICITY " +- set multicast database hash elasticity, ie the maximum chain length +in the multicast hash table (defaults to 4). + +.BI mcast_hash_max " HASH_MAX " +- set maximum size of multicast hash table (defaults to 512, +value must be a power of 2). + +.BI mcast_last_member_count " LAST_MEMBER_COUNT " +- set multicast last member count, ie the number of queries the bridge +will send before stopping forwarding a multicast group after a "leave" +message has been received (defaults to 2). + +.BI mcast_last_member_interval " LAST_MEMBER_INTERVAL " +- interval between queries to find remaining members of a group, +after a "leave" message is received. + +.BI mcast_startup_query_count " STARTUP_QUERY_COUNT " +- set the number of IGMP queries to send during startup phase (defaults to 2). + +.BI mcast_startup_query_interval " STARTUP_QUERY_INTERVAL " +- interval between queries in the startup phase. + +.BI mcast_query_interval " QUERY_INTERVAL " +- interval between queries sent by the bridge after the end of the +startup phase. + +.BI mcast_query_response_interval " QUERY_RESPONSE_INTERVAL " +- set the Max Response Time/Maximum Response Delay for IGMP/MLD +queries sent by the bridge. + +.BI mcast_membership_interval " MEMBERSHIP_INTERVAL " +- delay after which the bridge will leave a group, +if no membership reports for this group are received. + +.BI mcast_stats_enabled " MCAST_STATS_ENABLED " +- enable +.RI ( MCAST_STATS_ENABLED " > 0) " +or disable +.RI ( MCAST_STATS_ENABLED " == 0) " +multicast (IGMP/MLD) stats accounting. + +.BI mcast_igmp_version " IGMP_VERSION " +- set the IGMP version. + +.BI mcast_mld_version " MLD_VERSION " +- set the MLD version. + +.BI nf_call_iptables " NF_CALL_IPTABLES " +- enable +.RI ( NF_CALL_IPTABLES " > 0) " +or disable +.RI ( NF_CALL_IPTABLES " == 0) " +iptables hooks on the bridge. + +.BI nf_call_ip6tables " NF_CALL_IP6TABLES " +- enable +.RI ( NF_CALL_IP6TABLES " > 0) " +or disable +.RI ( NF_CALL_IP6TABLES " == 0) " +ip6tables hooks on the bridge. + +.BI nf_call_arptables " NF_CALL_ARPTABLES " +- enable +.RI ( NF_CALL_ARPTABLES " > 0) " +or disable +.RI ( NF_CALL_ARPTABLES " == 0) " +arptables hooks on the bridge. + + +.in -8 + +.TP +MACsec Type Support +For a link of type +.I MACsec +the following additional arguments are supported: + +.BI "ip link add link " DEVICE " name " NAME " type macsec" +[ [ +.BI address " " +] +.BI port " PORT" +| +.BI sci " SCI" +] [ +.BI cipher " CIPHER_SUITE" +] [ +.BR icvlen " { " +.IR 8..16 " } ] [" +.BR encrypt " {" +.BR on " | " off " } ] [ " +.BR send_sci " { " on " | " off " } ] [" +.BR end_station " { " on " | " off " } ] [" +.BR scb " { " on " | " off " } ] [" +.BR protect " { " on " | " off " } ] [" +.BR replay " { " on " | " off " }" +.BR window " { " +.IR 0..2^32-1 " } ] [" +.BR validate " { " strict " | " check " | " disabled " } ] [" +.BR encodingsa " { " +.IR 0..3 " } ]" + +.in +8 +.sp +.BI address " " +- sets the system identifier component of secure channel for this MACsec device. + +.sp +.BI port " PORT " +- sets the port number component of secure channel for this MACsec +device, in a range from 1 to 65535 inclusive. Numbers with a leading " +0 " or " 0x " are interpreted as octal and hexadecimal, respectively. + +.sp +.BI sci " SCI " +- sets the secure channel identifier for this MACsec device. +.I SCI +is a 64bit wide number in hexadecimal format. + +.sp +.BI cipher " CIPHER_SUITE " +- defines the cipher suite to use. + +.sp +.BI icvlen " LENGTH " +- sets the length of the Integrity Check Value (ICV). + +.sp +.BR "encrypt on " or " encrypt off" +- switches between authenticated encryption, or authenticity mode only. + +.sp +.BR "send_sci on " or " send_sci off" +- specifies whether the SCI is included in every packet, +or only when it is necessary. + +.sp +.BR "end_station on " or " end_station off" +- sets the End Station bit. + +.sp +.BR "scb on " or " scb off" +- sets the Single Copy Broadcast bit. + +.sp +.BR "protect on " or " protect off" +- enables MACsec protection on the device. + +.sp +.BR "replay on " or " replay off" +- enables replay protection on the device. + +.in +8 + +.sp +.BI window " SIZE " +- sets the size of the replay window. + +.in -8 + +.sp +.BR "validate strict " or " validate check " or " validate disabled" +- sets the validation mode on the device. + +.sp +.BI encodingsa " AN " +- sets the active secure association for transmission. + +.in -8 + +.TP +VRF Type Support +For a link of type +.I VRF +the following additional arguments are supported: + +.BI "ip link add " DEVICE " type vrf table " TABLE + +.in +8 +.sp +.BR table " table id associated with VRF device" + +.in -8 + +.TP +RMNET Type Support +For a link of type +.I RMNET +the following additional arguments are supported: + +.BI "ip link add link " DEVICE " name " NAME " type rmnet mux_id " MUXID + +.in +8 +.sp +.BI mux_id " MUXID " +- specifies the mux identifier for the rmnet device, possible values 1-254. + +.in -8 + +.TP +XFRM Type Support +For a link of type +.I XFRM +the following additional arguments are supported: + +.BI "ip link add " DEVICE " type xfrm dev " PHYS_DEV " [ if_id " IF_ID " ]" + +.in +8 +.sp +.BI dev " PHYS_DEV " +- specifies the underlying physical interface from which transform traffic is sent and received. + +.sp +.BI if_id " IF-ID " +- specifies the hexadecimal lookup key used to send traffic to and from specific xfrm +policies. Policies must be configured with the same key. If not set, the key defaults to +0 and will match any policies which similarly do not have a lookup key configuration. + +.in -8 + +.SS ip link delete - delete virtual link + +.TP +.BI dev " DEVICE " +specifies the virtual device to act operate on. + +.TP +.BI group " GROUP " +specifies the group of virtual links to delete. Group 0 is not allowed to be +deleted since it is the default group. + +.TP +.BI type " TYPE " +specifies the type of the device. + +.SS ip link set - change device attributes + +.PP +.B Warning: +If multiple parameter changes are requested, +.B ip +aborts immediately after any of the changes have failed. +This is the only case when +.B ip +can move the system to an unpredictable state. The solution +is to avoid changing several parameters with one +.B ip link set +call. +The modifier +.B change +is equivalent to +.BR "set" . + + +.TP +.BI dev " DEVICE " +.I DEVICE +specifies network device to operate on. When configuring SR-IOV +Virtual Function (VF) devices, this keyword should specify the +associated Physical Function (PF) device. + +.TP +.BI group " GROUP " +.I GROUP +has a dual role: If both group and dev are present, then move the device to the +specified group. If only a group is specified, then the command operates on +all devices in that group. + +.TP +.BR up " and " down +change the state of the device to +.B UP +or +.BR "DOWN" . + +.TP +.BR "arp on " or " arp off" +change the +.B NOARP +flag on the device. + +.TP +.BR "multicast on " or " multicast off" +change the +.B MULTICAST +flag on the device. + +.TP +.BR "allmulticast on " or " allmulticast off" +change the +.B ALLMULTI +flag on the device. When enabled, instructs network driver to retrieve all +multicast packets from the network to the kernel for further processing. + +.TP +.BR "promisc on " or " promisc off" +change the +.B PROMISC +flag on the device. When enabled, activates promiscuous operation of the +network device. + +.TP +.BR "trailers on " or " trailers off" +change the +.B NOTRAILERS +flag on the device, +.B NOT +used by the Linux and exists for BSD compatibility. + +.TP +.BR "protodown on " or " protodown off" +change the +.B PROTODOWN +state on the device. Indicates that a protocol error has been detected +on the port. Switch drivers can react to this error by doing a phys +down on the switch port. + +.TP +.BR "protodown_reason PREASON on " or " off" +set +.B PROTODOWN +reasons on the device. protodown reason bit names can be enumerated under +/etc/iproute2/protodown_reasons.d/. possible reasons bits 0-31 + +.TP +.BR "dynamic on " or " dynamic off" +change the +.B DYNAMIC +flag on the device. Indicates that address can change when interface +goes down (currently +.B NOT +used by the Linux). + +.TP +.BI name " NAME" +change the name of the device. This operation is not +recommended if the device is running or has some addresses +already configured. + +.TP +.BI txqueuelen " NUMBER" +.TP +.BI txqlen " NUMBER" +change the transmit queue length of the device. + +.TP +.BI mtu " NUMBER" +change the +.I MTU +of the device. + +.TP +.BI address " LLADDRESS" +change the station address of the interface. + +.TP +.BI broadcast " LLADDRESS" +.TP +.BI brd " LLADDRESS" +.TP +.BI peer " LLADDRESS" +change the link layer broadcast address or the peer address when +the interface is +.IR "POINTOPOINT" . + +.TP +.BI netns " NETNSNAME " \fR| " PID" +move the device to the network namespace associated with name +.IR "NETNSNAME " or +.RI process " PID". + +Some devices are not allowed to change network namespace: loopback, bridge, +wireless. These are network namespace local devices. In such case +.B ip +tool will return "Invalid argument" error. It is possible to find out +if device is local to a single network namespace by checking +.B netns-local +flag in the output of the +.BR ethtool ":" + +.in +8 +.B ethtool -k +.I DEVICE +.in -8 + +To change network namespace for wireless devices the +.B iw +tool can be used. But it allows to change network namespace only for +physical devices and by process +.IR PID . + +.TP +.BI alias " NAME" +give the device a symbolic name for easy reference. + +.TP +.BI group " GROUP" +specify the group the device belongs to. +The available groups are listed in file +.BR "@SYSCONFDIR@/group" . + +.TP +.BI vf " NUM" +specify a Virtual Function device to be configured. The associated PF device +must be specified using the +.B dev +parameter. + +.in +8 +.BI mac " LLADDRESS" +- change the station address for the specified VF. The +.B vf +parameter must be specified. + +.sp +.BI vlan " VLANID" +- change the assigned VLAN for the specified VF. When specified, all traffic +sent from the VF will be tagged with the specified VLAN ID. Incoming traffic +will be filtered for the specified VLAN ID, and will have all VLAN tags +stripped before being passed to the VF. Setting this parameter to 0 disables +VLAN tagging and filtering. The +.B vf +parameter must be specified. + +.sp +.BI qos " VLAN-QOS" +- assign VLAN QOS (priority) bits for the VLAN tag. When specified, all VLAN +tags transmitted by the VF will include the specified priority bits in the +VLAN tag. If not specified, the value is assumed to be 0. Both the +.B vf +and +.B vlan +parameters must be specified. Setting both +.B vlan +and +.B qos +as 0 disables VLAN tagging and filtering for the VF. + +.sp +.BI proto " VLAN-PROTO" +- assign VLAN PROTOCOL for the VLAN tag, either 802.1Q or 802.1ad. +Setting to 802.1ad, all traffic sent from the VF will be tagged with +VLAN S-Tag. Incoming traffic will have VLAN S-Tags stripped before +being passed to the VF. Setting to 802.1ad also enables an option to +concatenate another VLAN tag, so both S-TAG and C-TAG will be +inserted/stripped for outgoing/incoming traffic, respectively. If not +specified, the value is assumed to be 802.1Q. Both the +.B vf +and +.B vlan +parameters must be specified. + +.sp +.BI rate " TXRATE" +-- change the allowed transmit bandwidth, in Mbps, for the specified VF. +Setting this parameter to 0 disables rate limiting. +.B vf +parameter must be specified. +Please use new API +.B "max_tx_rate" +option instead. + +.sp +.BI max_tx_rate " TXRATE" +- change the allowed maximum transmit bandwidth, in Mbps, for the +specified VF. Setting this parameter to 0 disables rate limiting. +.B vf +parameter must be specified. + +.sp +.BI min_tx_rate " TXRATE" +- change the allowed minimum transmit bandwidth, in Mbps, for the specified VF. +Minimum TXRATE should be always <= Maximum TXRATE. +Setting this parameter to 0 disables rate limiting. +.B vf +parameter must be specified. + +.sp +.BI spoofchk " on|off" +- turn packet spoof checking on or off for the specified VF. +.sp +.BI query_rss " on|off" +- toggle the ability of querying the RSS configuration of a specific + VF. VF RSS information like RSS hash key may be considered sensitive + on some devices where this information is shared between VF and PF + and thus its querying may be prohibited by default. +.sp +.BI state " auto|enable|disable" +- set the virtual link state as seen by the specified VF. Setting to +auto means a reflection of the PF link state, enable lets the VF to +communicate with other VFs on this host even if the PF link state is +down, disable causes the HW to drop any packets sent by the VF. +.sp +.BI trust " on|off" +- trust the specified VF user. This enables that VF user can set a +specific feature which may impact security and/or +performance. (e.g. VF multicast promiscuous mode) +.sp +.BI node_guid " eui64" +- configure node GUID for Infiniband VFs. +.sp +.BI port_guid " eui64" +- configure port GUID for Infiniband VFs. +.in -8 + +.TP +.B xdp object "|" pinned "|" off +set (or unset) a XDP ("eXpress Data Path") BPF program to run on every +packet at driver level. +.B ip link +output will indicate a +.B xdp +flag for the networking device. If the driver does not have native XDP +support, the kernel will fall back to a slower, driver-independent "generic" +XDP variant. The +.B ip link +output will in that case indicate +.B xdpgeneric +instead of +.B xdp +only. If the driver does have native XDP support, but the program is +loaded under +.B xdpgeneric object "|" pinned +then the kernel will use the generic XDP variant instead of the native one. +.B xdpdrv +has the opposite effect of requestsing that the automatic fallback to the +generic XDP variant be disabled and in case driver is not XDP-capable error +should be returned. +.B xdpdrv +also disables hardware offloads. +.B xdpoffload +in ip link output indicates that the program has been offloaded to hardware +and can also be used to request the "offload" mode, much like +.B xdpgeneric +it forces program to be installed specifically in HW/FW of the apater. + +.B off +(or +.B none +) +- Detaches any currently attached XDP/BPF program from the given device. + +.BI object " FILE " +- Attaches a XDP/BPF program to the given device. The +.I FILE +points to a BPF ELF file (f.e. generated by LLVM) that contains the BPF +program code, map specifications, etc. If a XDP/BPF program is already +attached to the given device, an error will be thrown. If no XDP/BPF +program is currently attached, the device supports XDP and the program +from the BPF ELF file passes the kernel verifier, then it will be attached +to the device. If the option +.I -force +is passed to +.B ip +then any prior attached XDP/BPF program will be atomically overridden and +no error will be thrown in this case. If no +.B section +option is passed, then the default section name ("prog") will be assumed, +otherwise the provided section name will be used. If no +.B verbose +option is passed, then a verifier log will only be dumped on load error. +See also +.B EXAMPLES +section for usage examples. + +.BI section " NAME " +- Specifies a section name that contains the BPF program code. If no section +name is specified, the default one ("prog") will be used. This option is +to be passed with the +.B object +option. + +.BI verbose +- Act in verbose mode. For example, even in case of success, this will +print the verifier log in case a program was loaded from a BPF ELF file. + +.BI pinned " FILE " +- Attaches a XDP/BPF program to the given device. The +.I FILE +points to an already pinned BPF program in the BPF file system. The option +.B section +doesn't apply here, but otherwise semantics are the same as with the option +.B object +described already. + +.TP +.BI master " DEVICE" +set master device of the device (enslave device). + +.TP +.BI nomaster +unset master device of the device (release device). + +.TP +.BI addrgenmode " eui64|none|stable_secret|random" +set the IPv6 address generation mode + +.I eui64 +- use a Modified EUI-64 format interface identifier + +.I none +- disable automatic address generation + +.I stable_secret +- generate the interface identifier based on a preset + /proc/sys/net/ipv6/conf/{default,DEVICE}/stable_secret + +.I random +- like stable_secret, but auto-generate a new random secret if none is set + +.TP +.BR "link-netnsid " +set peer netnsid for a cross-netns interface + +.TP +.BI type " ETYPE TYPE_ARGS" +Change type-specific settings. For a list of supported types and arguments refer +to the description of +.B "ip link add" +above. In addition to that, it is possible to manipulate settings to slave +devices: + +.TP +Bridge Slave Support +For a link with master +.B bridge +the following additional arguments are supported: + +.B "ip link set type bridge_slave" +[ +.B fdb_flush +] [ +.BI state " STATE" +] [ +.BI priority " PRIO" +] [ +.BI cost " COST" +] [ +.BR guard " { " on " | " off " }" +] [ +.BR hairpin " { " on " | " off " }" +] [ +.BR fastleave " { " on " | " off " }" +] [ +.BR root_block " { " on " | " off " }" +] [ +.BR learning " { " on " | " off " }" +] [ +.BR flood " { " on " | " off " }" +] [ +.BR proxy_arp " { " on " | " off " }" +] [ +.BR proxy_arp_wifi " { " on " | " off " }" +] [ +.BI mcast_router " MULTICAST_ROUTER" +] [ +.BR mcast_fast_leave " { " on " | " off "}" +] [ +.BR mcast_flood " { " on " | " off " }" +] [ +.BR mcast_to_unicast " { " on " | " off " }" +] [ +.BR group_fwd_mask " MASK" +] [ +.BR neigh_suppress " { " on " | " off " }" +] [ +.BR vlan_tunnel " { " on " | " off " }" +] [ +.BR isolated " { " on " | " off " }" +] [ +.BR backup_port " DEVICE" +] [ +.BR nobackup_port " ]" + +.in +8 +.sp +.B fdb_flush +- flush bridge slave's fdb dynamic entries. + +.BI state " STATE" +- Set port state. +.I STATE +is a number representing the following states: +.BR 0 " (disabled)," +.BR 1 " (listening)," +.BR 2 " (learning)," +.BR 3 " (forwarding)," +.BR 4 " (blocking)." + +.BI priority " PRIO" +- set port priority (allowed values are between 0 and 63, inclusively). + +.BI cost " COST" +- set port cost (allowed values are between 1 and 65535, inclusively). + +.BR guard " { " on " | " off " }" +- block incoming BPDU packets on this port. + +.BR hairpin " { " on " | " off " }" +- enable hairpin mode on this port. This will allow incoming packets on this +port to be reflected back. + +.BR fastleave " { " on " | " off " }" +- enable multicast fast leave on this port. + +.BR root_block " { " on " | " off " }" +- block this port from becoming the bridge's root port. + +.BR learning " { " on " | " off " }" +- allow MAC address learning on this port. + +.BR flood " { " on " | " off " }" +- open the flood gates on this port, i.e. forward all unicast frames to this +port also. Requires +.BR proxy_arp " and " proxy_arp_wifi +to be turned off. + +.BR proxy_arp " { " on " | " off " }" +- enable proxy ARP on this port. + +.BR proxy_arp_wifi " { " on " | " off " }" +- enable proxy ARP on this port which meets extended requirements by IEEE +802.11 and Hotspot 2.0 specifications. + +.BI mcast_router " MULTICAST_ROUTER" +- configure this port for having multicast routers attached. A port with a +multicast router will receive all multicast traffic. +.I MULTICAST_ROUTER +may be either +.B 0 +to disable multicast routers on this port, +.B 1 +to let the system detect the presence of routers (this is the default), +.B 2 +to permanently enable multicast traffic forwarding on this port or +.B 3 +to enable multicast routers temporarily on this port, not depending on incoming +queries. + +.BR mcast_fast_leave " { " on " | " off " }" +- this is a synonym to the +.B fastleave +option above. + +.BR mcast_flood " { " on " | " off " }" +- controls whether a given port will flood multicast traffic for which + there is no MDB entry. + +.BR mcast_to_unicast " { " on " | " off " }" +- controls whether a given port will replicate packets using unicast + instead of multicast. By default this flag is off. + +.BI group_fwd_mask " MASK " +- set the group forward mask. This is the bitmask that is applied to +decide whether to forward incoming frames destined to link-local +addresses, ie addresses of the form 01:80:C2:00:00:0X (defaults to +0, ie the bridge does not forward any link-local frames coming on +this port). + +.BR neigh_suppress " { " on " | " off " }" +- controls whether neigh discovery (arp and nd) proxy and suppression +is enabled on the port. By default this flag is off. + +.BR vlan_tunnel " { " on " | " off " }" +- controls whether vlan to tunnel mapping is enabled on the port. By +default this flag is off. + +.BI backup_port " DEVICE" +- if the port loses carrier all traffic will be redirected to the +configured backup port + +.BR nobackup_port +- removes the currently configured backup port + +.in -8 + +.TP +Bonding Slave Support +For a link with master +.B bond +the following additional arguments are supported: + +.B "ip link set type bond_slave" +[ +.BI queue_id " ID" +] + +.in +8 +.sp +.BI queue_id " ID" +- set the slave's queue ID (a 16bit unsigned value). + +.in -8 + +.TP +MACVLAN and MACVTAP Support +Modify list of allowed macaddr for link in source mode. + +.B "ip link set type { macvlan | macvap } " +[ +.BI macaddr " " "" COMMAND " " MACADDR " ..." +] + +Commands: +.in +8 +.B add +- add MACADDR to allowed list +.sp +.B set +- replace allowed list +.sp +.B del +- remove MACADDR from allowed list +.sp +.B flush +- flush whole allowed list +.sp +.in -8 + +Update the broadcast/multicast queue length. + +.B "ip link set type { macvlan | macvap } " +[ +.BI bcqueuelen " LENGTH " +] + +.in +8 +.BI bcqueuelen " LENGTH " +- Set the length of the RX queue used to process broadcast and multicast packets. +.IR LENGTH " must be a positive integer in the range [0-4294967295]." +Setting a length of 0 will effectively drop all broadcast/multicast traffic. +If not specified the macvlan driver default (1000) is used. +Note that all macvlans that share the same underlying device are using the same +.RB "queue. The parameter here is a " request ", the actual queue length used" +will be the maximum length that any macvlan interface has requested. +When listing device parameters both the bcqueuelen parameter +as well as the actual used bcqueuelen are listed to better help +the user understand the setting. +.in -8 + +.SS ip link show - display device attributes + +.TP +.BI dev " NAME " (default) +.I NAME +specifies the network device to show. + +.TP +.BI group " GROUP " +.I GROUP +specifies what group of devices to show. + +.TP +.B up +only display running interfaces. + +.TP +.BI master " DEVICE " +.I DEVICE +specifies the master device which enslaves devices to show. + +.TP +.BI vrf " NAME " +.I NAME +specifies the VRF which enslaves devices to show. + +.TP +.BI type " TYPE " +.I TYPE +specifies the type of devices to show. + +Note that the type name is not checked against the list of supported types - +instead it is sent as-is to the kernel. Later it is used to filter the returned +interface list by comparing it with the relevant attribute in case the kernel +didn't filter already. Therefore any string is accepted, but may lead to empty +output. + +.SS ip link xstats - display extended statistics + +.TP +.BI type " TYPE " +.I TYPE +specifies the type of devices to display extended statistics for. + +.SS ip link afstats - display address-family specific statistics + +.TP +.BI dev " DEVICE " +.I DEVICE +specifies the device to display address-family statistics for. + +.SS ip link help - display help + +.PP +.I "TYPE" +specifies which help of link type to display. + +.SS +.I GROUP +may be a number or a string from the file +.B @SYSCONFDIR@/group +which can be manually filled. + +.SH "EXAMPLES" +.PP +ip link show +.RS 4 +Shows the state of all network interfaces on the system. +.RE +.PP +ip link show type bridge +.RS 4 +Shows the bridge devices. +.RE +.PP +ip link show type vlan +.RS 4 +Shows the vlan devices. +.RE +.PP +ip link show master br0 +.RS 4 +Shows devices enslaved by br0 +.RE +.PP +ip link set dev ppp0 mtu 1400 +.RS 4 +Change the MTU the ppp0 device. +.RE +.PP +ip link add link eth0 name eth0.10 type vlan id 10 +.RS 4 +Creates a new vlan device eth0.10 on device eth0. +.RE +.PP +ip link delete dev eth0.10 +.RS 4 +Removes vlan device. +.RE + +ip link help gre +.RS 4 +Display help for the gre link type. +.RE +.PP +ip link add name tun1 type ipip remote 192.168.1.1 +local 192.168.1.2 ttl 225 encap gue encap-sport auto +encap-dport 5555 encap-csum encap-remcsum +.RS 4 +Creates an IPIP that is encapsulated with Generic UDP Encapsulation, +and the outer UDP checksum and remote checksum offload are enabled. +.RE +.PP +ip link set dev eth0 xdp obj prog.o +.RS 4 +Attaches a XDP/BPF program to device eth0, where the program is +located in prog.o, section "prog" (default section). In case a +XDP/BPF program is already attached, throw an error. +.RE +.PP +ip -force link set dev eth0 xdp obj prog.o sec foo +.RS 4 +Attaches a XDP/BPF program to device eth0, where the program is +located in prog.o, section "foo". In case a XDP/BPF program is +already attached, it will be overridden by the new one. +.RE +.PP +ip -force link set dev eth0 xdp pinned /sys/fs/bpf/foo +.RS 4 +Attaches a XDP/BPF program to device eth0, where the program was +previously pinned as an object node into BPF file system under +name foo. +.RE +.PP +ip link set dev eth0 xdp off +.RS 4 +If a XDP/BPF program is attached on device eth0, detach it and +effectively turn off XDP for device eth0. +.RE +.PP +ip link add link wpan0 lowpan0 type lowpan +.RS 4 +Creates a 6LoWPAN interface named lowpan0 on the underlying +IEEE 802.15.4 device wpan0. +.RE +.PP +ip link add dev ip6erspan11 type ip6erspan seq key 102 +local fc00:100::2 remote fc00:100::1 +erspan_ver 2 erspan_dir ingress erspan_hwid 17 +.RS 4 +Creates a IP6ERSPAN version 2 interface named ip6erspan00. +.RE + +.SH SEE ALSO +.br +.BR ip (8), +.BR ip-netns (8), +.BR ethtool (8), +.BR iptables (8) + +.SH AUTHOR +Original Manpage by Michail Litvak diff --git a/man/man8/ip-neighbour.8 b/man/man8/ip-neighbour.8 new file mode 100644 index 0000000..a27f9ef --- /dev/null +++ b/man/man8/ip-neighbour.8 @@ -0,0 +1,281 @@ +.TH IP\-NEIGHBOUR 8 "20 Dec 2011" "iproute2" "Linux" +.SH "NAME" +ip-neighbour \- neighbour/arp tables management. +.SH "SYNOPSIS" +.sp +.ad l +.in +8 +.ti -8 +.B ip +.RI "[ " OPTIONS " ]" +.B neigh +.RI " { " COMMAND " | " +.BR help " }" +.sp + +.ti -8 +.BR "ip neigh" " { " add " | " del " | " change " | " replace " } { " +.IR ADDR " [ " +.B lladdr +.IR LLADDR " ] [ " +.B nud +.IR STATE " ] |" +.B proxy +.IR ADDR " } [ " +.B dev +.IR DEV " ] [ " +.BR router " ] [ " +.BR extern_learn " ]" + +.ti -8 +.BR "ip neigh" " { " show " | " flush " } [ " proxy " ] [ " to +.IR PREFIX " ] [ " +.B dev +.IR DEV " ] [ " +.B nud +.IR STATE " ] [ " +.B vrf +.IR NAME " ] " + +.ti -8 +.B ip neigh get +.IR ADDR +.B dev +.IR DEV + +.ti -8 +.IR STATE " := {" +.BR permanent " | " noarp " | " stale " | " reachable " | " none " |" +.BR incomplete " | " delay " | " probe " | " failed " }" + +.SH DESCRIPTION +The +.B ip neigh +command manipulates +.I neighbour +objects that establish bindings between protocol addresses and +link layer addresses for hosts sharing the same link. +Neighbour entries are organized into tables. The IPv4 neighbour table +is also known by another name - the ARP table. + +.P +The corresponding commands display neighbour bindings +and their properties, add new neighbour entries and delete old ones. + +.TP +ip neighbour add +add a new neighbour entry +.TP +ip neighbour change +change an existing entry +.TP +ip neighbour replace +add a new entry or change an existing one +.RS +.PP +These commands create new neighbour records or update existing ones. + +.TP +.BI to " ADDRESS " (default) +the protocol address of the neighbour. It is either an IPv4 or IPv6 address. + +.TP +.BI dev " NAME" +the interface to which this neighbour is attached. + +.TP +.BI proxy +indicates whether we are proxying for this neighbour entry + +.TP +.BI router +indicates whether neighbour is a router + +.TP +.BI extern_learn +this neigh entry was learned externally. This option can be used to +indicate to the kernel that this is a controller learnt dynamic entry. +Kernel will not gc such an entry. + +.TP +.BI lladdr " LLADDRESS" +the link layer address of the neighbour. +.I LLADDRESS +can also be +.BR "null" . + +.TP +.BI nud " STATE" +the state of the neighbour entry. +.B nud +is an abbreviation for 'Neighbour Unreachability Detection'. +The state can take one of the following values: + +.RS +.TP +.B permanent +the neighbour entry is valid forever and can be only +be removed administratively. +.TP +.B noarp +the neighbour entry is valid. No attempts to validate +this entry will be made but it can be removed when its lifetime expires. +.TP +.B reachable +the neighbour entry is valid until the reachability +timeout expires. +.TP +.B stale +the neighbour entry is valid but suspicious. +This option to +.B ip neigh +does not change the neighbour state if it was valid and the address +is not changed by this command. +.TP +.B none +this is a pseudo state used when initially creating a neighbour entry or after +trying to remove it before it becomes free to do so. +.TP +.B incomplete +the neighbour entry has not (yet) been validated/resolved. +.TP +.B delay +neighbor entry validation is currently delayed. +.TP +.B probe +neighbor is being probed. +.TP +.B failed +max number of probes exceeded without success, neighbor validation has +ultimately failed. +.RE +.RE + +.TP +ip neighbour delete +delete a neighbour entry +.RS +.PP +The arguments are the same as with +.BR "ip neigh add" , +except that +.B lladdr +and +.B nud +are ignored. + +.PP +.B Warning: +Attempts to delete or manually change a +.B noarp +entry created by the kernel may result in unpredictable behaviour. +Particularly, the kernel may try to resolve this address even +on a +.B NOARP +interface or if the address is multicast or broadcast. +.RE + +.TP +ip neighbour show +list neighbour entries +.RS +.TP +.BI to " ADDRESS " (default) +the prefix selecting the neighbours to list. + +.TP +.BI dev " NAME" +only list the neighbours attached to this device. + +.TP +.BI vrf " NAME" +only list the neighbours for given VRF. + +.TP +.BI proxy +list neighbour proxies. + +.TP +.B unused +only list neighbours which are not currently in use. + +.TP +.BI nud " STATE" +only list neighbour entries in this state. +.I NUD_STATE +takes values listed below or the special value +.B all +which means all states. This option may occur more than once. +If this option is absent, +.B ip +lists all entries except for +.B none +and +.BR "noarp" . +.RE + +.TP +ip neighbour flush +flush neighbour entries +.RS +This command has the same arguments as +.B show. +The differences are that it does not run when no arguments are given, +and that the default neighbour states to be flushed do not include +.B permanent +and +.BR "noarp" . + +.PP +With the +.B -statistics +option, the command becomes verbose. It prints out the number of +deleted neighbours and the number of rounds made to flush the +neighbour table. If the option is given +twice, +.B ip neigh flush +also dumps all the deleted neighbours. +.RE + +.TP +ip neigh get +lookup a neighbour entry to a destination given a device +.RS + +.TP +.BI proxy +indicates whether we should lookup a proxy neighbour entry + +.TP +.BI to " ADDRESS " (default) +the prefix selecting the neighbour to query. + +.TP +.BI dev " NAME" +get neighbour entry attached to this device. +.RE + +.SH EXAMPLES +.PP +ip neighbour +.RS +Shows the current neighbour table in kernel. +.RE +.PP +ip neigh flush dev eth0 +.RS +Removes entries in the neighbour table on device eth0. +.RE +.PP +ip neigh get 10.0.1.10 dev eth0 +.RS +Performs a neighbour lookup in the kernel and returns +a neighbour entry. +.RE + +.SH SEE ALSO +.br +.BR ip (8) + +.SH AUTHOR +Original Manpage by Michail Litvak diff --git a/man/man8/ip-route.8 b/man/man8/ip-route.8 new file mode 100644 index 0000000..c9a9cbf --- /dev/null +++ b/man/man8/ip-route.8 @@ -0,0 +1,1266 @@ +.TH IP\-ROUTE 8 "13 Dec 2012" "iproute2" "Linux" +.SH "NAME" +ip-route \- routing table management +.SH "SYNOPSIS" +.sp +.ad l +.in +8 +.ti -8 +.B ip +.RI "[ " ip-OPTIONS " ]" +.B route +.RI " { " COMMAND " | " +.BR help " }" +.sp +.ti -8 + +.ti -8 +.BR "ip route" " { " +.BR show " | " flush " } " +.I SELECTOR + +.ti -8 +.BR "ip route save" +.I SELECTOR + +.ti -8 +.BR "ip route restore" + +.ti -8 +.B ip route get +.I ROUTE_GET_FLAGS +.IR ADDRESS " [ " +.BI from " ADDRESS " iif " STRING" +.RB " ] [ " oif +.IR STRING " ] [ " +.B mark +.IR MARK " ] [ " +.B tos +.IR TOS " ] [ " +.B vrf +.IR NAME " ] [ " +.B ipproto +.IR PROTOCOL " ] [ " +.B sport +.IR NUMBER " ] [ " +.B dport +.IR NUMBER " ] " + +.ti -8 +.BR "ip route" " { " add " | " del " | " change " | " append " | "\ +replace " } " +.I ROUTE + +.ti -8 +.IR SELECTOR " := " +.RB "[ " root +.IR PREFIX " ] [ " +.B match +.IR PREFIX " ] [ " +.B exact +.IR PREFIX " ] [ " +.B table +.IR TABLE_ID " ] [ " +.B vrf +.IR NAME " ] [ " +.B proto +.IR RTPROTO " ] [ " +.B type +.IR TYPE " ] [ " +.B scope +.IR SCOPE " ]" + +.ti -8 +.IR ROUTE " := " NODE_SPEC " [ " INFO_SPEC " ]" + +.ti -8 +.IR NODE_SPEC " := [ " TYPE " ] " PREFIX " [" +.B tos +.IR TOS " ] [ " +.B table +.IR TABLE_ID " ] [ " +.B proto +.IR RTPROTO " ] [ " +.B scope +.IR SCOPE " ] [ " +.B metric +.IR METRIC " ] [ " +.B ttl-propagate +.RB "{ " enabled " | " disabled " } ]" + +.ti -8 +.IR INFO_SPEC " := { " NH " | " +.B nhid +.IR ID " } " "OPTIONS FLAGS" " [" +.B nexthop +.IR NH " ] ..." + +.ti -8 +.IR NH " := [ " +.B encap +.IR ENCAP " ] [ " +.B via +[ +.IR FAMILY " ] " ADDRESS " ] [ " +.B dev +.IR STRING " ] [ " +.B weight +.IR NUMBER " ] " NHFLAGS + +.ti -8 +.IR FAMILY " := [ " +.BR inet " | " inet6 " | " mpls " | " bridge " | " link " ]" + +.ti -8 +.IR OPTIONS " := " FLAGS " [ " +.B mtu +.IR NUMBER " ] [ " +.B advmss +.IR NUMBER " ] [ " +.B as +[ +.B to +] +.IR ADDRESS " ]" +.B rtt +.IR TIME " ] [ " +.B rttvar +.IR TIME " ] [ " +.B reordering +.IR NUMBER " ] [ " +.B window +.IR NUMBER " ] [ " +.B cwnd +.IR NUMBER " ] [ " +.B ssthresh +.IR NUMBER " ] [ " +.B realms +.IR REALM " ] [ " +.B rto_min +.IR TIME " ] [ " +.B initcwnd +.IR NUMBER " ] [ " +.B initrwnd +.IR NUMBER " ] [ " +.B features +.IR FEATURES " ] [ " +.B quickack +.IR BOOL " ] [ " +.B congctl +.IR NAME " ] [ " +.B pref +.IR PREF " ] [ " +.B expires +.IR TIME " ] [" +.B fastopen_no_cookie +.IR BOOL " ]" + +.ti -8 +.IR TYPE " := [ " +.BR unicast " | " local " | " broadcast " | " multicast " | "\ +throw " | " unreachable " | " prohibit " | " blackhole " | " nat " ]" + +.ti -8 +.IR TABLE_ID " := [ " +.BR local "| " main " | " default " | " all " |" +.IR NUMBER " ]" + +.ti -8 +.IR SCOPE " := [ " +.BR host " | " link " | " global " |" +.IR NUMBER " ]" + +.ti -8 +.IR NHFLAGS " := [ " +.BR onlink " | " pervasive " ]" + +.ti -8 +.IR RTPROTO " := [ " +.BR kernel " | " boot " | " static " |" +.IR NUMBER " ]" + +.ti -8 +.IR FEATURES " := [ " +.BR ecn " | ]" + +.ti -8 +.IR PREF " := [ " +.BR low " | " medium " | " high " ]" + +.ti -8 +.IR ENCAP " := [ " +.IR ENCAP_MPLS " | " ENCAP_IP " | " ENCAP_BPF " | " +.IR ENCAP_SEG6 " | " ENCAP_SEG6LOCAL " | " ENCAP_IOAM6 " ] " + +.ti -8 +.IR ENCAP_MPLS " := " +.BR mpls " [ " +.IR LABEL " ] [" +.B ttl +.IR TTL " ]" + +.ti -8 +.IR ENCAP_IP " := " +.B ip +.B id +.IR TUNNEL_ID +.B dst +.IR REMOTE_IP " [ " +.B src +.IR SRC " ] [" +.B tos +.IR TOS " ] [" +.B ttl +.IR TTL " ]" + +.ti -8 +.IR ENCAP_BPF " := " +.BR bpf " [ " +.B in +.IR PROG " ] [" +.B out +.IR PROG " ] [" +.B xmit +.IR PROG " ] [" +.B headroom +.IR SIZE " ]" + +.ti -8 +.IR ENCAP_SEG6 " := " +.B seg6 +.BR mode " [ " +.BR encap " | " inline " | " l2encap " ] " +.B segs +.IR SEGMENTS " [ " +.B hmac +.IR KEYID " ]" + +.ti -8 +.IR ENCAP_SEG6LOCAL " := " +.B seg6local +.BR action +.IR SEG6_ACTION " [ " +.IR SEG6_ACTION_PARAM " ] [ " +.BR count " ] " + +.ti -8 +.IR ENCAP_IOAM6 " := " +.B ioam6 +.BR trace +.BR prealloc +.BR type +.IR IOAM6_TRACE_TYPE +.BR ns +.IR IOAM6_NAMESPACE +.BR size +.IR IOAM6_TRACE_SIZE + +.ti -8 +.IR ROUTE_GET_FLAGS " := " +.BR " [ " +.BR fibmatch +.BR " ] " + +.SH DESCRIPTION +.B ip route +is used to manipulate entries in the kernel routing tables. +.sp +.B Route types: + +.in +8 +.B unicast +- the route entry describes real paths to the destinations covered +by the route prefix. + +.sp +.B unreachable +- these destinations are unreachable. Packets are discarded and the +ICMP message +.I host unreachable +is generated. +The local senders get an +.I EHOSTUNREACH +error. + +.sp +.B blackhole +- these destinations are unreachable. Packets are discarded silently. +The local senders get an +.I EINVAL +error. + +.sp +.B prohibit +- these destinations are unreachable. Packets are discarded and the +ICMP message +.I communication administratively prohibited +is generated. The local senders get an +.I EACCES +error. + +.sp +.B local +- the destinations are assigned to this host. The packets are looped +back and delivered locally. + +.sp +.B broadcast +- the destinations are broadcast addresses. The packets are sent as +link broadcasts. + +.sp +.B throw +- a special control route used together with policy rules. If such a +route is selected, lookup in this table is terminated pretending that +no route was found. Without policy routing it is equivalent to the +absence of the route in the routing table. The packets are dropped +and the ICMP message +.I net unreachable +is generated. The local senders get an +.I ENETUNREACH +error. + +.sp +.B nat +- a special NAT route. Destinations covered by the prefix +are considered to be dummy (or external) addresses which require translation +to real (or internal) ones before forwarding. The addresses to translate to +are selected with the attribute +.BR "via" . +.B Warning: +Route NAT is no longer supported in Linux 2.6. + +.sp +.B anycast +.RI "- " "not implemented" +the destinations are +.I anycast +addresses assigned to this host. They are mainly equivalent +to +.B local +with one difference: such addresses are invalid when used +as the source address of any packet. + +.sp +.B multicast +- a special type used for multicast routing. It is not present in +normal routing tables. +.in -8 + +.P +.B Route tables: +Linux-2.x can pack routes into several routing tables identified +by a number in the range from 1 to 2^32-1 or by name from the file +.B @SYSCONFDIR@/rt_tables +By default all normal routes are inserted into the +.B main +table (ID 254) and the kernel only uses this table when calculating routes. +Values (0, 253, 254, and 255) are reserved for built-in use. + +.sp +Actually, one other table always exists, which is invisible but +even more important. It is the +.B local +table (ID 255). This table +consists of routes for local and broadcast addresses. The kernel maintains +this table automatically and the administrator usually need not modify it +or even look at it. + +The multiple routing tables enter the game when +.I policy routing +is used. + +.TP +ip route add +add new route +.TP +ip route change +change route +.TP +ip route replace +change or add new one +.RS +.TP +.BI to " TYPE PREFIX " (default) +the destination prefix of the route. If +.I TYPE +is omitted, +.B ip +assumes type +.BR "unicast" . +Other values of +.I TYPE +are listed above. +.I PREFIX +is an IP or IPv6 address optionally followed by a slash and the +prefix length. If the length of the prefix is missing, +.B ip +assumes a full-length host route. There is also a special +.I PREFIX +.B default +- which is equivalent to IP +.B 0/0 +or to IPv6 +.BR "::/0" . + +.TP +.BI tos " TOS" +.TP +.BI dsfield " TOS" +the Type Of Service (TOS) key. This key has no associated mask and +the longest match is understood as: First, compare the TOS +of the route and of the packet. If they are not equal, then the packet +may still match a route with a zero TOS. +.I TOS +is either an 8 bit hexadecimal number or an identifier +from +.BR "@SYSCONFDIR@/rt_dsfield" . + +.TP +.BI metric " NUMBER" +.TP +.BI preference " NUMBER" +the preference value of the route. +.I NUMBER +is an arbitrary 32bit number, where routes with lower values are preferred. + +.TP +.BI table " TABLEID" +the table to add this route to. +.I TABLEID +may be a number or a string from the file +.BR "@SYSCONFDIR@/rt_tables" . +If this parameter is omitted, +.B ip +assumes the +.B main +table, with the exception of +.BR local ", " broadcast " and " nat +routes, which are put into the +.B local +table by default. + +.TP +.BI vrf " NAME" +the vrf name to add this route to. Implicitly means the table +associated with the VRF. + +.TP +.BI dev " NAME" +the output device name. + +.TP +.BI via " [ FAMILY ] ADDRESS" +the address of the nexthop router, in the address family FAMILY. +Actually, the sense of this field depends on the route type. For +normal +.B unicast +routes it is either the true next hop router or, if it is a direct +route installed in BSD compatibility mode, it can be a local address +of the interface. For NAT routes it is the first address of the block +of translated IP destinations. + +.TP +.BI src " ADDRESS" +the source address to prefer when sending to the destinations +covered by the route prefix. + +.TP +.BI realm " REALMID" +the realm to which this route is assigned. +.I REALMID +may be a number or a string from the file +.BR "@SYSCONFDIR@/rt_realms" . + +.TP +.BI mtu " MTU" +.TP +.BI "mtu lock" " MTU" +the MTU along the path to the destination. If the modifier +.B lock +is not used, the MTU may be updated by the kernel due to +Path MTU Discovery. If the modifier +.B lock +is used, no path MTU discovery will be tried, all packets +will be sent without the DF bit in IPv4 case or fragmented +to MTU for IPv6. + +.TP +.BI window " NUMBER" +the maximal window for TCP to advertise to these destinations, +measured in bytes. It limits maximal data bursts that our TCP +peers are allowed to send to us. + +.TP +.BI rtt " TIME" +the initial RTT ('Round Trip Time') estimate. If no suffix is +specified the units are raw values passed directly to the +routing code to maintain compatibility with previous releases. +Otherwise if a suffix of s, sec or secs is used to specify +seconds and ms, msec or msecs to specify milliseconds. + + +.TP +.BI rttvar " TIME " "(Linux 2.3.15+ only)" +the initial RTT variance estimate. Values are specified as with +.BI rtt +above. + +.TP +.BI rto_min " TIME " "(Linux 2.6.23+ only)" +the minimum TCP Retransmission TimeOut to use when communicating with this +destination. Values are specified as with +.BI rtt +above. + +.TP +.BI ssthresh " NUMBER " "(Linux 2.3.15+ only)" +an estimate for the initial slow start threshold. + +.TP +.BI cwnd " NUMBER " "(Linux 2.3.15+ only)" +the clamp for congestion window. It is ignored if the +.B lock +flag is not used. + +.TP +.BI initcwnd " NUMBER " "(Linux 2.5.70+ only)" +the initial congestion window size for connections to this destination. +Actual window size is this value multiplied by the MSS +(``Maximal Segment Size'') for same connection. The default is +zero, meaning to use the values specified in RFC2414. + +.TP +.BI initrwnd " NUMBER " "(Linux 2.6.33+ only)" +the initial receive window size for connections to this destination. +Actual window size is this value multiplied by the MSS of the connection. +The default value is zero, meaning to use Slow Start value. + +.TP +.BI features " FEATURES " (Linux 3.18+ only) +Enable or disable per-route features. Only available feature at this +time is +.B ecn +to enable explicit congestion notification when initiating connections to the +given destination network. +When responding to a connection request from the given network, ecn will +also be used even if the +.B net.ipv4.tcp_ecn +sysctl is set to 0. + +.TP +.BI quickack " BOOL " "(Linux 3.11+ only)" +Enable or disable quick ack for connections to this destination. + +.TP +.BI fastopen_no_cookie " BOOL " "(Linux 4.15+ only)" +Enable TCP Fastopen without a cookie for connections to this destination. + +.TP +.BI congctl " NAME " "(Linux 3.20+ only)" +.TP +.BI "congctl lock" " NAME " "(Linux 3.20+ only)" +Sets a specific TCP congestion control algorithm only for a given destination. +If not specified, Linux keeps the current global default TCP congestion control +algorithm, or the one set from the application. If the modifier +.B lock +is not used, an application may nevertheless overwrite the suggested congestion +control algorithm for that destination. If the modifier +.B lock +is used, then an application is not allowed to overwrite the specified congestion +control algorithm for that destination, thus it will be enforced/guaranteed to +use the proposed algorithm. + +.TP +.BI advmss " NUMBER " "(Linux 2.3.15+ only)" +the MSS ('Maximal Segment Size') to advertise to these +destinations when establishing TCP connections. If it is not given, +Linux uses a default value calculated from the first hop device MTU. +(If the path to these destination is asymmetric, this guess may be wrong.) + +.TP +.BI reordering " NUMBER " "(Linux 2.3.15+ only)" +Maximal reordering on the path to this destination. +If it is not given, Linux uses the value selected with +.B sysctl +variable +.BR "net/ipv4/tcp_reordering" . + +.TP +.BI nexthop " NEXTHOP" +the nexthop of a multipath route. +.I NEXTHOP +is a complex value with its own syntax similar to the top level +argument lists: + +.in +8 +.BI via " [ FAMILY ] ADDRESS" +- is the nexthop router. +.sp + +.BI dev " NAME" +- is the output device. +.sp + +.BI weight " NUMBER" +- is a weight for this element of a multipath +route reflecting its relative bandwidth or quality. +.in -8 + +The internal buffer used in iproute2 limits the maximum number of nexthops that +may be specified in one go. If only +.I ADDRESS +is given, the current buffer size allows for 144 IPv6 nexthops and 253 IPv4 +ones. For IPv4, this effectively limits the number of nexthops possible per +route. With IPv6, further nexthops may be appended to the same route via +.B "ip route append" +command. + +.TP +.BI scope " SCOPE_VAL" +the scope of the destinations covered by the route prefix. +.I SCOPE_VAL +may be a number or a string from the file +.BR "@SYSCONFDIR@/rt_scopes" . +If this parameter is omitted, +.B ip +assumes scope +.B global +for all gatewayed +.B unicast +routes, scope +.B link +for direct +.BR unicast " and " broadcast +routes and scope +.BR host " for " local +routes. + +.TP +.BI protocol " RTPROTO" +the routing protocol identifier of this route. +.I RTPROTO +may be a number or a string from the file +.BR "@SYSCONFDIR@/rt_protos" . +If the routing protocol ID is not given, +.B ip assumes protocol +.B boot +(i.e. it assumes the route was added by someone who doesn't +understand what they are doing). Several protocol values have +a fixed interpretation. +Namely: + +.in +8 +.B redirect +- the route was installed due to an ICMP redirect. +.sp + +.B kernel +- the route was installed by the kernel during autoconfiguration. +.sp + +.B boot +- the route was installed during the bootup sequence. +If a routing daemon starts, it will purge all of them. +.sp + +.B static +- the route was installed by the administrator +to override dynamic routing. Routing daemon will respect them +and, probably, even advertise them to its peers. +.sp + +.B ra +- the route was installed by Router Discovery protocol. +.in -8 + +.sp +The rest of the values are not reserved and the administrator is free +to assign (or not to assign) protocol tags. + +.TP +.B onlink +pretend that the nexthop is directly attached to this link, +even if it does not match any interface prefix. + +.TP +.BI pref " PREF" +the IPv6 route preference. +.I PREF +is a string specifying the route preference as defined in RFC4191 for Router +Discovery messages. Namely: + +.in +8 +.B low +- the route has a lowest priority +.sp + +.B medium +- the route has a default priority +.sp + +.B high +- the route has a highest priority +.sp + +.TP +.BI nhid " ID" +use nexthop object with given id as nexthop specification. +.sp +.TP +.BI encap " ENCAPTYPE ENCAPHDR" +attach tunnel encapsulation attributes to this route. +.sp +.I ENCAPTYPE +is a string specifying the supported encapsulation type. Namely: + +.in +8 +.BI mpls +- encapsulation type MPLS +.sp +.BI ip +- IP encapsulation (Geneve, GRE, VXLAN, ...) +.sp +.BI bpf +- Execution of BPF program +.sp +.BI seg6 +- encapsulation type IPv6 Segment Routing +.sp +.BI seg6local +- local SRv6 segment processing +.sp +.BI ioam6 +- encapsulation type IPv6 IOAM + +.in -8 +.I ENCAPHDR +is a set of encapsulation attributes specific to the +.I ENCAPTYPE. + +.in +8 +.B mpls +.in +2 +.I MPLSLABEL +- mpls label stack with labels separated by +.I "/" +.sp + +.B ttl +.I TTL +- TTL to use for MPLS header or 0 to inherit from IP header +.in -2 +.sp + +.B ip +.in +2 +.B id +.I TUNNEL_ID +.B dst +.IR REMOTE_IP " [ " +.B src +.IR SRC " ] [" +.B tos +.IR TOS " ] [" +.B ttl +.IR TTL " ] [ " +.BR key " ] [ " csum " ] [ " seq " ] " +.in -2 +.sp + +.B bpf +.in +2 +.B in +.I PROG +- BPF program to execute for incoming packets +.sp + +.B out +.I PROG +- BPF program to execute for outgoing packets +.sp + +.B xmit +.I PROG +- BPF program to execute for transmitted packets +.sp + +.B headroom +.I SIZE +- Size of header BPF program will attach (xmit) +.in -2 +.sp + +.B seg6 +.in +2 +.B mode inline +- Directly insert Segment Routing Header after IPv6 header +.sp + +.B mode encap +- Encapsulate packet in an outer IPv6 header with SRH +.sp + +.B mode l2encap +- Encapsulate ingress L2 frame within an outer IPv6 header and SRH +.sp + +.I SEGMENTS +- List of comma-separated IPv6 addresses +.sp + +.I KEYID +- Numerical value in decimal representation. See \fBip-sr\fR(8). +.in -2 +.sp + +.B seg6local +.in +2 +.IR SEG6_ACTION " [ " +.IR SEG6_ACTION_PARAM " ] [ " +.BR count " ] " +- Operation to perform on matching packets. The optional \fBcount\fR +attribute is used to collect statistics on the processing of actions. +Three counters are implemented: 1) packets correctly processed; +2) bytes correctly processed; 3) packets that cause a processing error +(i.e., missing SID List, wrong SID List, etc). To retrieve the counters +related to an action use the \fB-s\fR flag in the \fBshow\fR command. +The following actions are currently supported (\fBLinux 4.14+ only\fR). +.in +2 + +.B End +- Regular SRv6 processing as intermediate segment endpoint. +This action only accepts packets with a non-zero Segments Left +value. Other matching packets are dropped. + +.B End.X nh6 +.I NEXTHOP +- Regular SRv6 processing as intermediate segment endpoint. +Additionally, forward processed packets to given next-hop. +This action only accepts packets with a non-zero Segments Left +value. Other matching packets are dropped. + +.B End.DX6 nh6 +.I NEXTHOP +- Decapsulate inner IPv6 packet and forward it to the +specified next-hop. If the argument is set to ::, then +the next-hop is selected according to the local selection +rules. This action only accepts packets with either a zero Segments +Left value or no SRH at all, and an inner IPv6 packet. Other +matching packets are dropped. + +.BR End.DT6 " { " table " | " vrftable " } " +.I TABLEID +- Decapsulate the inner IPv6 packet and forward it according to the +specified lookup table. +.I TABLEID +is either a number or a string from the file +.BR "@SYSCONFDIR@/rt_tables" . +If +.B vrftable +is used, the argument must be a VRF device associated with +the table id. Moreover, the VRF table associated with the +table id must be configured with the VRF strict mode turned +on (net.vrf.strict_mode=1). This action only accepts packets +with either a zero Segments Left value or no SRH at all, +and an inner IPv6 packet. Other matching packets are dropped. + +.B End.DT4 vrftable +.I TABLEID +- Decapsulate the inner IPv4 packet and forward it according to the +specified lookup table. +.I TABLEID +is either a number or a string from the file +.BR "@SYSCONFDIR@/rt_tables" . +The argument must be a VRF device associated with the table id. +Moreover, the VRF table associated with the table id must be configured +with the VRF strict mode turned on (net.vrf.strict_mode=1). This action +only accepts packets with either a zero Segments Left value or no SRH +at all, and an inner IPv4 packet. Other matching packets are dropped. + +.B End.DT46 vrftable +.I TABLEID +- Decapsulate the inner IPv4 or IPv6 packet and forward it according +to the specified lookup table. +.I TABLEID +is either a number or a string from the file +.BR "@SYSCONFDIR@/rt_tables" . +The argument must be a VRF device associated with the table id. +Moreover, the VRF table associated with the table id must be configured +with the VRF strict mode turned on (net.vrf.strict_mode=1). This action +only accepts packets with either a zero Segments Left value or no SRH +at all, and an inner IPv4 or IPv6 packet. Other matching packets are +dropped. + +.B End.B6 srh segs +.IR SEGMENTS " [ " +.B hmac +.IR KEYID " ] " +- Insert the specified SRH immediately after the IPv6 header, +update the DA with the first segment of the newly inserted SRH, +then forward the resulting packet. The original SRH is not +modified. This action only accepts packets with a non-zero +Segments Left value. Other matching packets are dropped. + +.B End.B6.Encaps srh segs +.IR SEGMENTS " [ " +.B hmac +.IR KEYID " ] " +- Regular SRv6 processing as intermediate segment endpoint. +Additionally, encapsulate the matching packet within an outer IPv6 header +followed by the specified SRH. The destination address of the outer IPv6 +header is set to the first segment of the new SRH. The source +address is set as described in \fBip-sr\fR(8). +.in -2 + +.B ioam6 +.in +2 +.I IOAM6_TRACE_TYPE +- List of IOAM data required in the trace, represented by a bitfield (24 bits). +.sp + +.I IOAM6_NAMESPACE +- Numerical value to represent an IOAM namespace. See \fBip-ioam\fR(8). +.sp + +.I IOAM6_TRACE_SIZE +- Size, in octets, of the pre-allocated trace data block. +.in -4 + +.in -8 + +.TP +.BI expires " TIME " "(Linux 4.4+ only)" +the route will be deleted after the expires time. +.B Only +support IPv6 at present. + +.TP +.BR ttl-propagate " { " enabled " | " disabled " } " +Control whether TTL should be propagated from any encap into the +un-encapsulated packet, overriding any global configuration. Only +supported for MPLS at present. +.RE + +.TP +ip route delete +delete route +.RS +.B ip route del +has the same arguments as +.BR "ip route add" , +but their semantics are a bit different. + +Key values +.RB "(" to ", " tos ", " preference " and " table ")" +select the route to delete. If optional attributes are present, +.B ip +verifies that they coincide with the attributes of the route to delete. +If no route with the given key and attributes was found, +.B ip route del +fails. +.RE + +.TP +ip route show +list routes +.RS +the command displays the contents of the routing tables or the route(s) +selected by some criteria. + +.TP +.BI to " SELECTOR " (default) +only select routes from the given range of destinations. +.I SELECTOR +consists of an optional modifier +.RB "(" root ", " match " or " exact ")" +and a prefix. +.BI root " PREFIX" +selects routes with prefixes not shorter than +.IR PREFIX "." +F.e. +.BI root " 0/0" +selects the entire routing table. +.BI match " PREFIX" +selects routes with prefixes not longer than +.IR PREFIX "." +F.e. +.BI match " 10.0/16" +selects +.IR 10.0/16 "," +.IR 10/8 " and " 0/0 , +but it does not select +.IR 10.1/16 " and " 10.0.0/24 . +And +.BI exact " PREFIX" +(or just +.IR PREFIX ")" +selects routes with this exact prefix. If neither of these options +are present, +.B ip +assumes +.BI root " 0/0" +i.e. it lists the entire table. + +.TP +.BI tos " TOS" +.TP +.BI dsfield " TOS" +only select routes with the given TOS. + +.TP +.BI table " TABLEID" +show the routes from this table(s). The default setting is to show table +.BR main "." +.I TABLEID +may either be the ID of a real table or one of the special values: +.sp +.in +8 +.B all +- list all of the tables. +.sp +.B cache +- dump the routing cache. +.in -8 + +.TP +.BI vrf " NAME" +show the routes for the table associated with the vrf name + +.TP +.B cloned +.TP +.B cached +list cloned routes i.e. routes which were dynamically forked from +other routes because some route attribute (f.e. MTU) was updated. +Actually, it is equivalent to +.BR "table cache" "." + +.TP +.BI from " SELECTOR" +the same syntax as for +.BR to "," +but it binds the source address range rather than destinations. +Note that the +.B from +option only works with cloned routes. + +.TP +.BI protocol " RTPROTO" +only list routes of this protocol. + +.TP +.BI scope " SCOPE_VAL" +only list routes with this scope. + +.TP +.BI type " TYPE" +only list routes of this type. + +.TP +.BI dev " NAME" +only list routes going via this device. + +.TP +.BI via " [ FAMILY ] PREFIX" +only list routes going via the nexthop routers selected by +.IR PREFIX "." + +.TP +.BI src " PREFIX" +only list routes with preferred source addresses selected +by +.IR PREFIX "." + +.TP +.BI realm " REALMID" +.TP +.BI realms " FROMREALM/TOREALM" +only list routes with these realms. +.RE + +.TP +ip route flush +flush routing tables +.RS +this command flushes routes selected by some criteria. + +.sp +The arguments have the same syntax and semantics as the arguments of +.BR "ip route show" , +but routing tables are not listed but purged. The only difference is +the default action: +.B show +dumps all the IP main routing table but +.B flush +prints the helper page. + +.sp +With the +.B -statistics +option, the command becomes verbose. It prints out the number of +deleted routes and the number of rounds made to flush the routing +table. If the option is given +twice, +.B ip route flush +also dumps all the deleted routes in the format described in the +previous subsection. +.RE + +.TP +ip route get +get a single route +.RS +this command gets a single route to a destination and prints its +contents exactly as the kernel sees it. + +.TP +.BI fibmatch +Return full fib lookup matched route. Default is to return the resolved +dst entry + +.TP +.BI to " ADDRESS " (default) +the destination address. + +.TP +.BI from " ADDRESS" +the source address. + +.TP +.BI tos " TOS" +.TP +.BI dsfield " TOS" +the Type Of Service. + +.TP +.BI iif " NAME" +the device from which this packet is expected to arrive. + +.TP +.BI oif " NAME" +force the output device on which this packet will be routed. + +.TP +.BI mark " MARK" +the firewall mark +.RB ( "fwmark" ) + +.TP +.BI vrf " NAME" +force the vrf device on which this packet will be routed. + +.TP +.BI ipproto " PROTOCOL" +ip protocol as seen by the route lookup + +.TP +.BI sport " NUMBER" +source port as seen by the route lookup + +.TP +.BI dport " NUMBER" +destination port as seen by the route lookup + +.TP +.B connected +if no source address +.RB "(option " from ")" +was given, relookup the route with the source set to the preferred +address received from the first lookup. +If policy routing is used, it may be a different route. + +.P +Note that this operation is not equivalent to +.BR "ip route show" . +.B show +shows existing routes. +.B get +resolves them and creates new clones if necessary. Essentially, +.B get +is equivalent to sending a packet along this path. +If the +.B iif +argument is not given, the kernel creates a route +to output packets towards the requested destination. +This is equivalent to pinging the destination +with a subsequent +.BR "ip route ls cache" , +however, no packets are actually sent. With the +.B iif +argument, the kernel pretends that a packet arrived from this interface +and searches for a path to forward the packet. +.RE + +.TP +ip route save +save routing table information to stdout +.RS +This command behaves like +.BR "ip route show" +except that the output is raw data suitable for passing to +.BR "ip route restore" . +.RE + +.TP +ip route restore +restore routing table information from stdin +.RS +This command expects to read a data stream as returned from +.BR "ip route save" . +It will attempt to restore the routing table information exactly as +it was at the time of the save, so any translation of information +in the stream (such as device indexes) must be done first. Any existing +routes are left unchanged. Any routes specified in the data stream that +already exist in the table will be ignored. +.RE + +.SH NOTES +Starting with Linux kernel version 3.6, there is no routing cache for IPv4 +anymore. Hence +.B "ip route show cached" +will never print any entries on systems with this or newer kernel versions. + +.SH EXAMPLES +.PP +ip ro +.RS 4 +Show all route entries in the kernel. +.RE +.PP +ip route add default via 192.168.1.1 dev eth0 +.RS 4 +Adds a default route (for all addresses) via the local gateway 192.168.1.1 that can +be reached on device eth0. +.RE +.PP +ip route add 10.1.1.0/30 encap mpls 200/300 via 10.1.1.1 dev eth0 +.RS 4 +Adds an ipv4 route with mpls encapsulation attributes attached to it. +.RE +.PP +ip -6 route add 2001:db8:1::/64 encap seg6 mode encap segs 2001:db8:42::1,2001:db8:ffff::2 dev eth0 +.RS 4 +Adds an IPv6 route with SRv6 encapsulation and two segments attached. +.RE +.PP +ip -6 route add 2001:db8:1::/64 encap seg6local action End.DT46 vrftable 100 dev vrf100 +.RS 4 +Adds an IPv6 route with SRv6 decapsulation and forward with lookup in VRF table. +.RE +.PP +ip -6 route add 2001:db8:1::/64 encap ioam6 trace prealloc type 0x800000 ns 1 size 12 dev eth0 +.RS 4 +Adds an IPv6 route with an IOAM Pre-allocated Trace encapsulation that only includes the hop limit and the node id, configured for the IOAM namespace 1 and a pre-allocated data block of 12 octets. +.RE +.PP +ip route add 10.1.1.0/30 nhid 10 +.RS 4 +Adds an ipv4 route using nexthop object with id 10. +.RE +.SH SEE ALSO +.br +.BR ip (8) + +.SH AUTHOR +Original Manpage by Michail Litvak diff --git a/man/man8/ip.8 b/man/man8/ip.8 new file mode 100644 index 0000000..2a4848b --- /dev/null +++ b/man/man8/ip.8 @@ -0,0 +1,436 @@ +.TH IP 8 "20 Dec 2011" "iproute2" "Linux" +.SH NAME +ip \- show / manipulate routing, network devices, interfaces and tunnels +.SH SYNOPSIS + +.ad l +.in +8 +.ti -8 +.B ip +.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" +.sp + +.ti -8 +.B ip +.RB "[ " -force " ] " +.BI "-batch " filename +.sp + +.ti -8 +.IR OBJECT " := { " +.BR link " | " address " | " addrlabel " | " route " | " rule " | " neigh " | "\ + ntable " | " tunnel " | " tuntap " | " maddress " | " mroute " | " mrule " | "\ + monitor " | " xfrm " | " netns " | " l2tp " | " tcp_metrics " | " token " | "\ + macsec " | " vrf " | " mptcp " | " ioam " }" +.sp + +.ti -8 +.IR OPTIONS " := { " +\fB\-V\fR[\fIersion\fR] | +\fB\-h\fR[\fIuman-readable\fR] | +\fB\-s\fR[\fItatistics\fR] | +\fB\-d\fR[\fIetails\fR] | +\fB\-r\fR[\fIesolve\fR] | +\fB\-iec\fR | +\fB\-f\fR[\fIamily\fR] { +.BR inet " | " inet6 " | " link " } | " +\fB-4\fR | +\fB-6\fR | +\fB-B\fR | +\fB-0\fR | +\fB-l\fR[\fIoops\fR] { \fBmaximum-addr-flush-attempts\fR } | +\fB\-o\fR[\fIneline\fR] | +\fB\-rc\fR[\fIvbuf\fR] [\fBsize\fR] | +\fB\-t\fR[\fIimestamp\fR] | +\fB\-ts\fR[\fIhort\fR] | +\fB\-n\fR[\fIetns\fR] name | +\fB\-N\fR[\fIumeric\fR] | +\fB\-a\fR[\fIll\fR] | +\fB\-c\fR[\fIolor\fR] | +\fB\-br\fR[\fIief\fR] | +\fB\-j\fR[son\fR] | +\fB\-p\fR[retty\fR] } + +.SH OPTIONS + +.TP +.BR "\-V" , " -Version" +Print the version of the +.B ip +utility and exit. + +.TP +.BR "\-h", " \-human", " \-human-readable" +output statistics with human readable values followed by suffix. + +.TP +.BR "\-b", " \-batch " +Read commands from provided file or standard input and invoke them. +First failure will cause termination of ip. + +.TP +.BR "\-force" +Don't terminate ip on errors in batch mode. If there were any errors +during execution of the commands, the application return code will be +non zero. + +.TP +.BR "\-s" , " \-stats" , " \-statistics" +Output more information. If the option +appears twice or more, the amount of information increases. +As a rule, the information is statistics or some time values. + +.TP +.BR "\-d" , " \-details" +Output more detailed information. + +.TP +.BR "\-l" , " \-loops " +Specify maximum number of loops the 'ip address flush' logic +will attempt before giving up. The default is 10. +Zero (0) means loop until all addresses are removed. + +.TP +.BR "\-f" , " \-family " +Specifies the protocol family to use. The protocol family identifier +can be one of +.BR "inet" , " inet6" , " bridge" , " mpls" +or +.BR link . +If this option is not present, +the protocol family is guessed from other arguments. If the rest +of the command line does not give enough information to guess the +family, +.B ip +falls back to the default one, usually +.B inet +or +.BR "any" . +.B link +is a special family identifier meaning that no networking protocol +is involved. + +.TP +.B \-4 +shortcut for +.BR "-family inet" . + +.TP +.B \-6 +shortcut for +.BR "\-family inet6" . + +.TP +.B \-B +shortcut for +.BR "\-family bridge" . + +.TP +.B \-M +shortcut for +.BR "\-family mpls" . + +.TP +.B \-0 +shortcut for +.BR "\-family link" . + +.TP +.BR "\-o" , " \-oneline" +output each record on a single line, replacing line feeds +with the +.B '\e' +character. This is convenient when you want to count records +with +.BR wc (1) +or to +.BR grep (1) +the output. + +.TP +.BR "\-r" , " \-resolve" +use the system's name resolver to print DNS names instead of +host addresses. + +.TP +.BR "\-n" , " \-netns " +switches +.B ip +to the specified network namespace +.IR NETNS . +Actually it just simplifies executing of: + +.B ip netns exec +.IR NETNS +.B ip +.RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" + +to + +.B ip +.RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | " +.BR help " }" + +.TP +.BR "\-N" , " \-Numeric" +Print the number of protocol, scope, dsfield, etc directly instead of +converting it to human readable name. + +.TP +.BR "\-a" , " \-all" +executes specified command over all objects, it depends if command +supports this option. + +.TP +.BR \-c [ color ][ = { always | auto | never } +Configure color output. If parameter is omitted or +.BR always , +color output is enabled regardless of stdout state. If parameter is +.BR auto , +stdout is checked to be a terminal before enabling color output. If +parameter is +.BR never , +color output is disabled. If specified multiple times, the last one takes +precedence. This flag is ignored if +.B \-json +is also given. + +Used color palette can be influenced by +.BR COLORFGBG +environment variable +(see +.BR ENVIRONMENT ). + +.TP +.BR "\-t" , " \-timestamp" +display current time when using monitor option. + +.TP +.BR "\-ts" , " \-tshort" +Like +.BR \-timestamp , +but use shorter format. + +.TP +.BR "\-rc" , " \-rcvbuf" +Set the netlink socket receive buffer size, defaults to 1MB. + +.TP +.BR "\-iec" +print human readable rates in IEC units (e.g. 1Ki = 1024). + +.TP +.BR "\-br" , " \-brief" +Print only basic information in a tabular format for better +readability. This option is currently only supported by +.BR "ip addr show ", " ip link show " & " ip neigh show " commands. + +.TP +.BR "\-j", " \-json" +Output results in JavaScript Object Notation (JSON). + +.TP +.BR "\-p", " \-pretty" +The default JSON format is compact and more efficient to parse but +hard for most users to read. This flag adds indentation for +readability. + +.SH IP - COMMAND SYNTAX + +.SS +.I OBJECT + +.TP +.B address +- protocol (IP or IPv6) address on a device. + +.TP +.B addrlabel +- label configuration for protocol address selection. + +.TP +.B ioam +- manage IOAM namespaces and IOAM schemas. + +.TP +.B l2tp +- tunnel ethernet over IP (L2TPv3). + +.TP +.B link +- network device. + +.TP +.B maddress +- multicast address. + +.TP +.B monitor +- watch for netlink messages. + +.TP +.B mptcp +- manage MPTCP path manager. + +.TP +.B mroute +- multicast routing cache entry. + +.TP +.B mrule +- rule in multicast routing policy database. + +.TP +.B neighbour +- manage ARP or NDISC cache entries. + +.TP +.B netns +- manage network namespaces. + +.TP +.B ntable +- manage the neighbor cache's operation. + +.TP +.B route +- routing table entry. + +.TP +.B rule +- rule in routing policy database. + +.TP +.B tcp_metrics/tcpmetrics +- manage TCP Metrics + +.TP +.B token +- manage tokenized interface identifiers. + +.TP +.B tunnel +- tunnel over IP. + +.TP +.B tuntap +- manage TUN/TAP devices. + +.TP +.B vrf +- manage virtual routing and forwarding devices. + +.TP +.B xfrm +- manage IPSec policies. + +.PP +The names of all objects may be written in full or +abbreviated form, for example +.B address +can be abbreviated as +.B addr +or just +.B a. + +.SS +.I COMMAND + +Specifies the action to perform on the object. +The set of possible actions depends on the object type. +As a rule, it is possible to +.BR "add" , " delete" +and +.B show +(or +.B list +) objects, but some objects do not allow all of these operations +or have some additional commands. The +.B help +command is available for all objects. It prints +out a list of available commands and argument syntax conventions. +.sp +If no command is given, some default command is assumed. +Usually it is +.B list +or, if the objects of this class cannot be listed, +.BR "help" . + +.SH ENVIRONMENT +.TP +.B COLORFGBG +If set, it's value is used for detection whether background is dark or +light and use contrast colors for it. + +COLORFGBG environment variable usually contains either two or three +values separated by semicolons; we want the last value in either case. +If this value is 0-6 or 8, chose colors suitable for dark background: + +COLORFGBG=";0" ip -c a + +.SH EXIT STATUS +Exit status is 0 if command was successful, and 1 if there is a syntax error. +If an error was reported by the kernel exit status is 2. + +.SH "EXAMPLES" +.PP +ip addr +.RS 4 +Shows addresses assigned to all network interfaces. +.RE +.PP +ip neigh +.RS 4 +Shows the current neighbour table in kernel. +.RE +.PP +ip link set x up +.RS 4 +Bring up interface x. +.RE +.PP +ip link set x down +.RS 4 +Bring down interface x. +.RE +.PP +ip route +.RS 4 +Show table routes. +.RE + +.SH HISTORY +.B ip +was written by Alexey N. Kuznetsov and added in Linux 2.2. +.SH SEE ALSO +.BR ip-address (8), +.BR ip-addrlabel (8), +.BR ip-ioam (8), +.BR ip-l2tp (8), +.BR ip-link (8), +.BR ip-maddress (8), +.BR ip-monitor (8), +.BR ip-mptcp (8), +.BR ip-mroute (8), +.BR ip-neighbour (8), +.BR ip-netns (8), +.BR ip-ntable (8), +.BR ip-route (8), +.BR ip-rule (8), +.BR ip-tcp_metrics (8), +.BR ip-token (8), +.BR ip-tunnel (8), +.BR ip-vrf (8), +.BR ip-xfrm (8) +.br +.RB "IP Command reference " ip-cref.ps +.SH REPORTING BUGS +Report any bugs to the Network Developers mailing list +.B +where the development and maintenance is primarily done. +You do not have to be subscribed to the list to send a message there. + +.SH AUTHOR +Original Manpage by Michail Litvak diff --git a/setup.cfg b/setup.cfg index f54f36e..eed9f38 100644 --- a/setup.cfg +++ b/setup.cfg @@ -28,6 +28,8 @@ install_requires = [files] packages = iproute4mac +data_files = + share/man = man/* [entry_points] console_scripts =