interfaces: add common description include file

13 files changed, 116 insertions, 57 deletions

diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt
new file mode 100644
index 00000000..28968bea
--- /dev/null
+++ b/docs/_include/interface-address-with-dhcp.txt
@@ -0,0 +1,20 @@
+.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp |
+   dhcpv6>
+
+   Configure interface `<interface>` with one or more interface addresses.
+
+   * **address** can be specified multiple times as IPv4 and/or IPv6
+     address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
+   * **dhcp** interface address is received by DHCP from a DHCP server
+     on this segment.
+   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
+     server on this segment.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24
+     set interfaces {{ var0 }} {{ var1 }} address 2001:db8::1/64
+     set interfaces {{ var0 }} {{ var1 }} dhcp
+     set interfaces {{ var0 }} {{ var1 }} dhcpv6
\ No newline at end of file
diff --git a/docs/_include/interface-address.txt b/docs/_include/interface-address.txt
index 1de05c31..4ca75940 100644
--- a/docs/_include/interface-address.txt
+++ b/docs/_include/interface-address.txt
@@ -1,21 +1,14 @@
-.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp |
-   dhcpv6>
+.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address>
 
    Configure interface `<interface>` with one or more interface
    addresses.
 
    * **address** can be specified multiple times as IPv4 and/or IPv6
      address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
-   * **dhcp** interface address is received by DHCP from a DHCP server
-     on this segment.
-   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
-     server on this segment.
 
    Example:
 
    .. code-block:: none
 
      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24
-     set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24
-     set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64
-     set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64
\ No newline at end of file
+     set interfaces {{ var0 }} {{ var1 }} address 2001:db8::1/64
\ No newline at end of file
diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt
new file mode 100644
index 00000000..992d4945
--- /dev/null
+++ b/docs/_include/interface-description.txt
@@ -0,0 +1,10 @@
+.. cfgcmd:: set interfaces {{ var0 }} <interface> description <description>
+
+   Set a human readable, descriptive alias for this connection. Alias is used by
+   e.g. the :opcmd:`show interfaces` command or SNMP based monitoring tools.
+
+   Example:
+
+   .. code-block:: none
+
+     set interfaces {{ var0 }} {{ var1 }} description 'This is an awesome interface running on VyOS'
\ No newline at end of file
diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst
index 78099f01..e23d2c52 100644
--- a/docs/interfaces/bond.rst
+++ b/docs/interfaces/bond.rst
@@ -13,10 +13,14 @@ Additionally, link integrity monitoring may be performed.
 Configuration
 #############
 
-Address
--------
+Common interface configuration
+------------------------------
+
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: bonding
+   :var1: bond0
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: ../_include/interface-description.txt
    :var0: bonding
    :var1: bond0
 
diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst
index aec1c5d8..ec946041 100644
--- a/docs/interfaces/bridge.rst
+++ b/docs/interfaces/bridge.rst
@@ -17,10 +17,14 @@ standard.
 Configuration
 #############
 
-Address
--------
+Common interface configuration
+------------------------------
+
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: bridge
+   :var1: br0
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: ../_include/interface-description.txt
    :var0: bridge
    :var1: br0
 
diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst
index e452ae73..02680f90 100644
--- a/docs/interfaces/dummy.rst
+++ b/docs/interfaces/dummy.rst
@@ -22,23 +22,16 @@ you can have as many as you want.
 Configuration
 #############
 
-Address
--------
+Common interface configuration
+------------------------------
 
-.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6>
+.. cmdinclude:: ../_include/interface-address.txt
+   :var0: dummy
+   :var1: dum0
 
-   Configure dummy interface `<interface>` with one or more interface
-   addresses. Address can be specified multiple times as IPv4 and/or IPv6
-   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
-
-   Example:
-
-   .. code-block:: none
-
-     set interfaces dummy dum10 address 192.0.2.1/24
-     set interfaces dummy dum10 address 192.0.2.2/24
-     set interfaces dummy dum10 address 2001:db8::ffff/64
-     set interfaces dummy dum10 address 2001:db8:100::ffff/64
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: dummy
+   :var1: dum0
 
 Link Administration
 -------------------
diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst
index 6d7d049f..424f2766 100644
--- a/docs/interfaces/ethernet.rst
+++ b/docs/interfaces/ethernet.rst
@@ -7,10 +7,14 @@ Ethernet
 Configuration
 #############
 
-Address
--------
+Common interface configuration
+------------------------------
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: ethernet
+   :var1: eth0
+
+.. cmdinclude:: ../_include/interface-description.txt
    :var0: ethernet
    :var1: eth0
 
diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst
index a4bc22aa..acd22c84 100644
--- a/docs/interfaces/geneve.rst
+++ b/docs/interfaces/geneve.rst
@@ -35,21 +35,16 @@ Geneve Header:
 Configuration
 =============
 
-.. cfgcmd:: set interfaces geneve gnv0 address <address>
+Common interface configuration
+------------------------------
 
-   Configure interface `<interface>` with one or more interface addresses.
+.. cmdinclude:: ../_include/interface-address.txt
+   :var0: geneve
+   :var1: gnv0
 
-   **address** can be specified multiple times as IPv4 and/or IPv6 address,
-   e.g. 192.0.2.1/24 and/or 2001:db8::1/64
-
-   Example:
-
-   .. code-block:: none
-
-     set interfaces geneve gnv0 address 192.0.2.1/24
-     set interfaces geneve gnv0 address 192.0.2.2/24
-     set interfaces geneve gnv0 address 2001:db8::ffff/64
-     set interfaces geneve gnv0 address 2001:db8:100::ffff/64
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: geneve
+   :var1: gnv0
 
 .. cfgcmd:: set interfaces geneve gnv0 remote <address>
 
diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst
index e15062cf..06486faa 100644
--- a/docs/interfaces/loopback.rst
+++ b/docs/interfaces/loopback.rst
@@ -22,14 +22,16 @@ services on your local machine.
 Configuration
 =============
 
-Address
--------
+Common interface configuration
+------------------------------
 
-.. cfgcmd:: set interfaces loopback lo address <address>
+.. cmdinclude:: ../_include/interface-address.txt
+   :var0: loopback
+   :var1: lo
 
-   Configure Loopback interface `lo` with one or more interface addresses.
-   Address can be specified multiple times as IPv4 and/or IPv6 address, e.g.
-   192.0.2.1/24 and/or 2001:db8::1/64.
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: loopback
+   :var1: lo
 
 Link Administration
 -------------------
diff --git a/docs/interfaces/macsec.rst b/docs/interfaces/macsec.rst
index d7af0c16..8a613709 100644
--- a/docs/interfaces/macsec.rst
+++ b/docs/interfaces/macsec.rst
@@ -16,6 +16,25 @@ used for their own specific use cases.
 Configuration
 #############
 
+Common interface configuration
+------------------------------
+
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: macsec
+   :var1: macsec0
+
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: macsec
+   :var1: macsec0
+
+.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
+   :var0: macsec
+   :var1: macsec0
+
+.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt
+   :var0: macsec
+   :var1: macsec0
+
 .. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128]
 
   Select cipher suite used for cryptographic operations. This setting is
diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/interfaces/pseudo-ethernet.rst
index eec28981..7564ce76 100644
--- a/docs/interfaces/pseudo-ethernet.rst
+++ b/docs/interfaces/pseudo-ethernet.rst
@@ -41,10 +41,14 @@ Ethernet interfaces:
 Configuration
 =============
 
-Address
--------
+Common interface configuration
+------------------------------
 
-.. cmdinclude:: ../_include/interface-address.txt
+.. cmdinclude:: ../_include/interface-address-with-dhcp.txt
+   :var0: pseudo-ethernet
+   :var1: peth0
+
+.. cmdinclude:: ../_include/interface-description.txt
    :var0: pseudo-ethernet
    :var1: peth0
 
diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst
index dae08508..5229f81c 100644
--- a/docs/interfaces/vxlan.rst
+++ b/docs/interfaces/vxlan.rst
@@ -36,13 +36,17 @@ may be blocked by the hypervisor.
 Configuration
 =============
 
-Address
--------
+Common interface configuration
+------------------------------
 
 .. cmdinclude:: ../_include/interface-address.txt
    :var0: vxlan
    :var1: vxlan0
 
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: vxlan
+   :var1: vxlan0
+
 .. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt
    :var0: vxlan
    :var1: vxlan0
diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst
index c41e71bf..5e2eac40 100644
--- a/docs/interfaces/wirelessmodem.rst
+++ b/docs/interfaces/wirelessmodem.rst
@@ -11,6 +11,13 @@ The wirelessmodem interface provides access (through a wireless modem/wwan) to
 wireless networks provided by various cellular providers. VyOS uses the
 interfaces wirelessmodem subsystem for configuration.
 
+Common interface configuration
+------------------------------
+
+.. cmdinclude:: ../_include/interface-description.txt
+   :var0: wirelessmodem
+   :var1: wlm0
+
 Address
 -------