interface: add documentation about interface 'ip' configuration node

1 files changed, 157 insertions, 0 deletions

diff --git a/docs/_include/interface-ip.txt b/docs/_include/interface-ip.txt
new file mode 100644
index 00000000..89937806
--- /dev/null
+++ b/docs/_include/interface-ip.txt
@@ -0,0 +1,157 @@
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip arp-cache-timeout
+
+  Once a neighbor has been found, the entry is considered to be valid for at
+  least for this specifc time. An entry's validity will be extended if it
+  receives positive feedback from higher level protocols.
+
+  This defaults to 30 seconds.
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip arp-cache-timeout 180
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip disable-arp-filter
+
+  If set the kernel can respond to arp requests with addresses from other
+  interfaces. This may seem wrong but it usually makes sense, because it
+  increases the chance of successful communication. IP addresses are owned by
+  the complete host on Linux, not by particular interfaces. Only for more
+  complex setups like load-balancing, does this behaviour cause problems.
+
+  If not set (default) allows you to have multiple network interfaces on the
+  same subnet, and have the ARPs for each interface be answered based on whether
+  or not the kernel would route a packet from the ARP'd IP out that interface
+  (therefore you must use source based routing for this to work).
+
+  In other words it allows control of which cards (usually 1) will respond to an
+  arp request.
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-arp-filter
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip disable-forwarding
+
+  Configure interface-specific Host/Router behaviour. If set, the interface will
+  switch to host mode and IPv6 forwarding will be disabled on this interface.
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip disable-forwarding
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip enable-arp-accept
+
+  Define behavior for gratuitous ARP frames who's IP is not already present in
+  the ARP table. If configured create new entries in the ARP table.
+
+  Both replies and requests type gratuitous arp will trigger the ARP table to be
+  updated, if this setting is on.
+
+  If the ARP table already contains the IP address of the gratuitous arp frame,
+  the arp table will be updated regardless if this setting is on or off.
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-accept
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip enable-arp-announce
+
+  Define different restriction levels for announcing the local source IP address
+  from IP packets in ARP requests sent on interface.
+
+  Use any local address, configured on any interface if this is not set.
+
+  If configured, try to avoid local addresses that are not in the target's
+  subnet for this interface. This mode is useful when target hosts reachable via
+  this interface require the source IP address in ARP requests to be part of
+  their logical network configured on the receiving interface. When we generate
+  the request we will check all our subnets that include the target IP and will
+  preserve the source address if it is from such subnet. If there is no such
+  subnet we select source address according to the rules for level 2.
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-announce
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip enable-arp-ignore
+
+  Define different modes for sending replies in response to received ARP
+  requests that resolve local target IP addresses:
+
+  If configured, reply only if the target IP address is local address configured
+  on the incoming interface.
+
+  If this option is unset (default), reply for any local target IP address,
+  configured on any interface.
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-arp-ignore
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip enable-proxy-arp
+
+  Use this command to enable proxy Address Resolution Protocol (ARP) on this
+  interface. Proxy ARP allows an Ethernet interface to respond with its own
+  :abbr:`MAC (Media Access Control)` address to ARP requests for destination IP
+  addresses on subnets attached to other interfaces on the system. Subsequent
+  packets sent to those destination IP addresses are forwarded appropriately by
+  the system.
+
+  Example:
+
+  .. code-block:: none
+
+    set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} ip enable-proxy-arp
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip proxy-arp-pvlan
+
+  Private VLAN proxy arp. Basically allow proxy arp replies back to the same
+  interface (from which the ARP request/solicitation was received).
+
+  This is done to support (ethernet) switch features, like :rfc:`3069`, where
+  the individual ports are NOT allowed to communicate with each other, but they
+  are allowed to talk to the upstream router. As described in :rfc:`3069`, it is
+  possible to allow these hosts to communicate through the upstream router by
+  proxy_arp'ing.
+
+  .. note:: Don't need to be used together with proxy_arp.
+
+  This technology is known by different names:
+
+  - In :rfc:`3069` it is called VLAN Aggregation
+
+  - Cisco and Allied Telesyn call it Private VLAN
+
+  - Hewlett-Packard call it Source-Port filtering or port-isolation
+
+  - Ericsson call it MAC-Forced Forwarding (RFC Draft)
+
+.. cfgcmd:: set interfaces {{ var0 }} <interface> {{ var2 }} {{ var3 }}
+  {{ var5 }} {{ var6 }} ip source-validation <strict | loose | disable>
+
+  Enable policy for source validation by reversed path, as specified in
+  :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict
+  mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
+  or other complicated routing, then loose mode is recommended.
+
+  - strict: Each incoming packet is tested against the FIB and if the interface
+    is not the best reverse path the packet check will fail. By default failed
+    packets are discarded.
+
+  - loose: Each incoming packet's source address is also tested against the FIB
+    and if the source address is not reachable via any interface the packet
+    check will fail.
+
+  - disable: No source validation