Interfaces: refine interface address assignment documentation

1 files changed, 115 insertions, 9 deletions

diff --git a/docs/ch05-network-interfaces.rst b/docs/ch05-network-interfaces.rst
index 555e4bbb..fb1aba3e 100644
--- a/docs/ch05-network-interfaces.rst
+++ b/docs/ch05-network-interfaces.rst
@@ -35,22 +35,126 @@ command.
           257276       1890          0          0          0          0
   vyos@vyos:~$
 
+Different network interfaces provide type-specific configuration. Ethernet
+interfaces, for example, allow the configuration of speed and duplex.
+
+Many services, such as network routing, firewall, and traffic policy also
+maintain interface-specific configuration. These will be covered in their
+respective sections.
+
+Interface Addresses
+-------------------
+
 Each interface can be configured with a description and address. Interface
-addresses might be a static address like `172.16.51.129/24`, `dhcp` (to
-retrieve the actual interface address from a DHCP server) or an IPv6 address
-like `2001:db8:1::ffff/64`.
+addresses might be:
+
+* Static IPv4 `address 172.16.51.129/24`
+* Static IPv6 `address 2001:db8:1::ffff/64`
+* DHCP IPv4 `address dhcp`
+* DHCP IPv6 `address dhcpv6`
+
+An interface description is assigned using the following command:
 
 .. code-block:: sh
 
   set interfaces ethernet eth0 description 'OUTSIDE'
-  set interfaces ethernet eth0 address 'dhcp'
 
-Different network interfaces provide type-specific configuration. Ethernet
-interfaces, for example, allow the configuration of speed and duplex.
+IPv4
+^^^^
 
-Many services, such as network routing, firewall, and traffic policy also
-maintain interface-specific configuration. These will be covered in their
-respective sections.
+Static Address
+**************
+
+This method is supported on all interfaces, apart from OpenVPN that uses
+different syntax and wireless modems that are always autoconfigured through
+PPP.
+
+The command is `set interfaces $type $name address $address`. Examples:
+
+.. code-block:: sh
+
+  set interfaces ethernet eth0 address 192.0.2.1/24
+  set interfaces tunnel tun0 address 10.0.0.1/30
+  set interfaces bridge br0 address 203.0.113.45/26
+  set interfaces ethernet eth0 vif 30 address 192.0.30.254/24
+
+DHCP
+****
+
+This method is supported on all physical interfaces, and those that are
+directly connected to a physical interface (ethernet, VLAN, bridge, bond,
+pseudo-ethernet, wireless).
+
+The command is `set interfaces $type $name address dhcp`. Examples:
+
+.. code-block:: sh
+
+  set interfaces ethernet eth0 vif 90 address dhcp
+  set interfaces bridge br0 address dhcp
+
+IPv6
+^^^^
+
+Static Address
+**************
+
+This method is supported on all interfaces, apart from OpenVPN that uses
+different syntax and wireless modems that are always autoconfigured through
+PPP. Static IPv6 addresses are supported on all interfaces except VTI.
+
+The command is `set interfaces $type $name address $address`. Examples:
+
+.. code-block:: sh
+
+  set interfaces ethernet eth0 address 2001:db8:100::ffff/64
+  set interfaces tunnel tun0 address 2001:db8::1/64
+  set interfaces bridge br0 address  2001:db8:200::1/64
+  set interfaces ethernet eth0 vif 30 address 2001:db8:3::ffff/64
+
+DHCP
+****
+
+This method is supported on all physical interfaces, and those that are
+directly connected to a physical interface (ethernet, VLAN, bridge, bond,
+pseudo-ethernet, wireless).
+
+The command is `set interfaces $type $name address dhcpv6`. Examples:
+
+.. code-block:: sh
+
+  set interfaces bonding bond1 address dhcpv6
+  set interfaces bridge br0 vif 56 address dhcpv6
+
+Autoconfiguration (SLAAC)
+*************************
+
+SLAAC is specified in RFC4862_. This method is supported on all physical
+interfaces, and those that are directly connected to a physical interface
+(ethernet, VLAN, bridge, bond, pseudo-ethernet, wireless).
+
+The command is `set interfaces $type $name ipv6 address autoconf`. Examples:
+
+.. code-block:: sh
+
+  set interfaces ethernet eth0 vif 90 ipv6 address autoconf
+  set interfaces bridge br0 ipv6 address autoconf
+
+**NOTE:** This method automatically disables IPv6 traffic forwarding on the
+interface in question.
+
+EUI-64
+******
+
+EUI-64 (64-Bit Extended Unique Identifier) as specified in RFC4291_. IPv6
+addresses in /64 networks can be automatically generated from the prefix and
+MAC address, if you specify the prefix.
+
+The command is `set interfaces $type $name ipv6 address eui64 $prefix`. Examples:
+
+.. code-block:: sh
+
+  set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64
+  set interfaces pseudo-ethernet peth0 ipv6 address eui64 2001:db8:aa::/64
 
 Ethernet Interfaces
 -------------------
@@ -464,4 +568,6 @@ your peer should have knowledge if its content.
   wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
   wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc='
 
+.. _RFC4862: https://tools.ietf.org/html/rfc4862
+.. _RFC4291: http://tools.ietf.org/html/rfc4291#section-2.5.1
 .. _WireGuard: https://www.wireguard.com