From 4abded8025a47990e58cd0a5fe9b96e38f4a3715 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:52:28 +0100 Subject: arrange: interfaces --- docs/configuration/interfaces/ethernet.rst | 226 +++++++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 docs/configuration/interfaces/ethernet.rst (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..f2ab3f67 --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,226 @@ +.. _ethernet-interface: + +######## +Ethernet +######## + +This will be the most widely used interface on a router carrying traffic to the +real world. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 + +Ethernet options +================ + +.. cfgcmd:: set interfaces ethernet duplex + + Configure physical interface duplex setting. + + * auto - interface duplex setting is auto-negotiated + * full - always use full-duplex + * half - always use half-duplex + + VyOS default will be `auto`. + +.. cfgcmd:: set interfaces ethernet speed + + Configure physical interface speed setting. + + * auto - interface speed is auto-negotiated + * 10 - 10 MBit/s + * 100 - 100 MBit/s + * 1000 - 1 GBit/s + * 2500 - 2.5 GBit/s + * 5000 - 5 GBit/s + * 10000 - 10 GBit/s + * 25000 - 25 GBit/s + * 40000 - 40 GBit/s + * 50000 - 50 GBit/s + * 100000 - 100 GBit/s + + VyOS default will be `auto`. + + +.. cfgcmd:: set interfaces ethernet mirror + + Use this command to mirror the inbound traffic from one Ethernet interface to + another interface. This feature is typically used to provide a copy of traffic + inbound on one interface to a system running a monitoring or IPS application + on another interface. The benefit of mirroring the traffic is that the + application is isolated from the source traffic and so application processing + does not affect the traffic or the system performance. + + Example: + + .. code-block:: none + + set interfaces ethernet eth0 mirror eth1 + +VLAN +==== + +Regular VLANs (802.1q) +---------------------- + +.. cmdinclude:: ../_include/interface-vlan-8021q.txt + :var0: ethernet + :var1: eth0 + +QinQ (802.1ad) +-------------- + +.. cmdinclude:: ../_include/interface-vlan-8021ad.txt + :var0: ethernet + :var1: eth0 + +********* +Operation +********* + +.. opcmd:: show interfaces ethernet + + Show brief interface information. + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.18.201.10/24 u/u LAN + eth1 172.18.202.11/24 u/u WAN + eth2 - u/D + +.. opcmd:: show interfaces ethernet + + Show detailed information on given `` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 + eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:44:00:f5:c9 brd ff:ff:ff:ff:ff:ff + inet6 fe80::250:44ff:fe00:f5c9/64 scope link + valid_lft forever preferred_lft forever + + RX: bytes packets errors dropped overrun mcast + 56735451 179841 0 0 0 142380 + TX: bytes packets errors dropped carrier collisions + 5601460 62595 0 0 0 0 + +.. opcmd:: show interfaces ethernet physical + + Show information about physical `` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 1000baseT/Full + 10000baseT/Full + Supported pause frame use: No + Supports auto-negotiation: No + Supported FEC modes: Not reported + Advertised link modes: Not reported + Advertised pause frame use: No + Advertised auto-negotiation: No + Advertised FEC modes: Not reported + Speed: 10000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: off + MDI-X: Unknown + Supports Wake-on: uag + Wake-on: d + Link detected: yes + driver: vmxnet3 + version: 1.4.16.0-k-NAPI + firmware-version: + expansion-rom-version: + bus-info: 0000:0b:00.0 + supports-statistics: yes + supports-test: no + supports-eeprom-access: no + supports-register-dump: yes + supports-priv-flags: no + +.. opcmd:: show interfaces ethernet physical offload + + Show available offloading functions on given `` + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical offload + rx-checksumming on + tx-checksumming on + tx-checksum-ip-generic on + scatter-gather off + tx-scatter-gather off + tcp-segmentation-offload off + tx-tcp-segmentation off + tx-tcp-mangleid-segmentation off + tx-tcp6-segmentation off + udp-fragmentation-offload off + generic-segmentation-offload off + generic-receive-offload off + large-receive-offload off + rx-vlan-offload on + tx-vlan-offload on + ntuple-filters off + receive-hashing on + tx-gre-segmentation on + tx-gre-csum-segmentation on + tx-udp_tnl-segmentation on + tx-udp_tnl-csum-segmentation on + tx-gso-partial on + tx-nocache-copy off + rx-all off + +.. opcmd:: show interfaces ethernet transceiver + + Show transceiver information from plugin modules, e.g SFP+, QSFP + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth5 transceiver + Identifier : 0x03 (SFP) + Extended identifier : 0x04 (GBIC/SFP defined by 2-wire interface ID) + Connector : 0x07 (LC) + Transceiver codes : 0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x00 0x00 + Transceiver type : Ethernet: 1000BASE-SX + Encoding : 0x01 (8B/10B) + BR, Nominal : 1300MBd + Rate identifier : 0x00 (unspecified) + Length (SMF,km) : 0km + Length (SMF) : 0m + Length (50um) : 550m + Length (62.5um) : 270m + Length (Copper) : 0m + Length (OM3) : 0m + Laser wavelength : 850nm + Vendor name : CISCO-FINISAR + Vendor OUI : 00:90:65 + Vendor PN : FTRJ-8519-7D-CS4 + Vendor rev : A + Option values : 0x00 0x1a + Option : RX_LOS implemented + Option : TX_FAULT implemented + Option : TX_DISABLE implemented + BR margin, max : 0% + BR margin, min : 0% + Vendor SN : FNS092xxxxx + Date code : 0506xx + -- cgit v1.2.3 From e33e1268f944be445b5a771df0e97e913487512f Mon Sep 17 00:00:00 2001 From: rebortg Date: Mon, 30 Nov 2020 19:46:59 +0100 Subject: change include to absolute path --- docs/_ext/vyos.py | 9 ++++++-- docs/_include/interface-common-with-dhcp.txt | 8 +++---- docs/_include/interface-common-without-dhcp.txt | 4 ++-- docs/_include/interface-common.txt | 18 ++++++++-------- docs/_include/interface-dhcpv6-options.txt | 2 +- docs/_include/interface-vlan-8021ad.txt | 26 +++++++++++------------ docs/_include/interface-vlan-8021q.txt | 24 ++++++++++----------- docs/configuration/firewall/index.rst | 1 + docs/configuration/interfaces/bonding.rst | 4 ++-- docs/configuration/interfaces/bridge.rst | 4 ++-- docs/configuration/interfaces/dummy.rst | 8 +++---- docs/configuration/interfaces/ethernet.rst | 6 +++--- docs/configuration/interfaces/geneve.rst | 2 +- docs/configuration/interfaces/l2tpv3.rst | 4 ++-- docs/configuration/interfaces/loopback.rst | 4 ++-- docs/configuration/interfaces/macsec.rst | 2 +- docs/configuration/interfaces/openvpn.rst | 2 +- docs/configuration/interfaces/pppoe.rst | 8 +++---- docs/configuration/interfaces/pseudo-ethernet.rst | 4 ++-- docs/configuration/interfaces/tunnel.rst | 2 +- docs/configuration/interfaces/vxlan.rst | 2 +- docs/configuration/interfaces/wireless.rst | 6 +++--- docs/configuration/interfaces/wirelessmodem.rst | 6 +++--- docs/configuration/nat/nptv6.rst | 2 +- docs/configuration/policy/index.rst | 4 ++-- docs/contributing/debugging.rst | 2 +- docs/contributing/development.rst | 2 +- docs/contributing/documentation.rst | 2 +- docs/contributing/issues-features.rst | 2 +- docs/interfaces/advanced-index.rst | 23 -------------------- docs/interfaces/basic-index.rst | 12 ----------- docs/routing/bfd.rst | 2 +- docs/routing/ospf.rst | 2 +- docs/routing/rip.rst | 2 +- docs/services/conntrack.rst | 2 +- docs/services/ipoe-server.rst | 4 ++-- docs/services/pppoe-server.rst | 2 +- docs/system/lcd.rst | 2 +- docs/vpn/sstp.rst | 2 +- 39 files changed, 97 insertions(+), 126 deletions(-) delete mode 100644 docs/interfaces/advanced-index.rst delete mode 100644 docs/interfaces/basic-index.rst (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 89cc8ab7..4a974b46 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -3,7 +3,7 @@ import json import os from docutils import io, nodes, utils, statemachine from docutils.parsers.rst.roles import set_classes -from docutils.parsers.rst import Directive, directives +from docutils.parsers.rst import Directive, directives, states from sphinx.util.docutils import SphinxDirective @@ -173,7 +173,7 @@ class inlinecmd(nodes.inline): #self.literal_whitespace -= 1 -class CfgInclude(Directive): +class CfgInclude(SphinxDirective): required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True @@ -189,10 +189,15 @@ class CfgInclude(Directive): 'var8': str, 'var9': str } + standard_include_path = os.path.join(os.path.dirname(states.__file__), + 'include') def run(self): ### Copy from include directive docutils """Include a file as part of the content of this reST file.""" + rel_filename, filename = self.env.relfn2path(self.arguments[0]) + self.arguments[0] = filename + self.env.note_included(filename) if not self.state.document.settings.file_insertion_enabled: raise self.warning('"%s" directive disabled.' % self.name) source = self.state_machine.input_lines.source( diff --git a/docs/_include/interface-common-with-dhcp.txt b/docs/_include/interface-common-with-dhcp.txt index 3e1394a3..1cacdd53 100644 --- a/docs/_include/interface-common-with-dhcp.txt +++ b/docs/_include/interface-common-with-dhcp.txt @@ -1,17 +1,17 @@ -.. cmdinclude:: ../_include/interface-address-with-dhcp.txt +.. cmdinclude:: /_include/interface-address-with-dhcp.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-common.txt +.. cmdinclude:: /_include/interface-common.txt :var0: {{ var0 }} :var1: {{ var1 }} **DHCP(v6)** -.. cmdinclude:: ../_include/interface-dhcp-options.txt +.. cmdinclude:: /_include/interface-dhcp-options.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-dhcpv6-options.txt +.. cmdinclude:: /_include/interface-dhcpv6-options.txt :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-common-without-dhcp.txt b/docs/_include/interface-common-without-dhcp.txt index d861f003..73d39dd0 100644 --- a/docs/_include/interface-common-without-dhcp.txt +++ b/docs/_include/interface-common-without-dhcp.txt @@ -1,7 +1,7 @@ -.. cmdinclude:: ../_include/interface-address.txt +.. cmdinclude:: /_include/interface-address.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-common.txt +.. cmdinclude:: /_include/interface-common.txt :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-common.txt b/docs/_include/interface-common.txt index de29356f..68c9c448 100644 --- a/docs/_include/interface-common.txt +++ b/docs/_include/interface-common.txt @@ -1,36 +1,36 @@ -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-disable-flow-control.txt +.. cmdinclude:: /_include/interface-disable-flow-control.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-disable-link-detect.txt +.. cmdinclude:: /_include/interface-disable-link-detect.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-mac.txt +.. cmdinclude:: /_include/interface-mac.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-mtu.txt +.. cmdinclude:: /_include/interface-mtu.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt +.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt +.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt :var0: {{ var0 }} :var1: {{ var1 }} -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: {{ var0 }} :var1: {{ var1 }} diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt index a54a7dce..a47d9f32 100644 --- a/docs/_include/interface-dhcpv6-options.txt +++ b/docs/_include/interface-dhcpv6-options.txt @@ -30,7 +30,7 @@ set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options temporary -.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: {{ var2 }} diff --git a/docs/_include/interface-vlan-8021ad.txt b/docs/_include/interface-vlan-8021ad.txt index a1e971be..12925ad4 100644 --- a/docs/_include/interface-vlan-8021ad.txt +++ b/docs/_include/interface-vlan-8021ad.txt @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt IEEE 802.1ad_ was an Ethernet networking standard informally known as QinQ as an amendment to IEEE standard 802.1q VLAN interfaces as described above. @@ -28,7 +28,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG (service tag with Ethernet Type = 0x88a8). -.. cmdinclude:: ../_include/interface-address-with-dhcp.txt +.. cmdinclude:: /_include/interface-address-with-dhcp.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -38,7 +38,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -48,7 +48,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -58,7 +58,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-disable-link-detect.txt +.. cmdinclude:: /_include/interface-disable-link-detect.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -68,7 +68,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-mac.txt +.. cmdinclude:: /_include/interface-mac.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -78,7 +78,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-mtu.txt +.. cmdinclude:: /_include/interface-mtu.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -88,7 +88,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt +.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -98,7 +98,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt +.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -108,7 +108,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -120,7 +120,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG **DHCP(v6)** -.. cmdinclude:: ../_include/interface-dhcp-options.txt +.. cmdinclude:: /_include/interface-dhcp-options.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -130,7 +130,7 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. cmdinclude:: ../_include/interface-dhcpv6-options.txt +.. cmdinclude:: /_include/interface-dhcpv6-options.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif-s @@ -140,4 +140,4 @@ tag is the one closer/closest to the Ethernet header, its name is S-TAG :var6: :var7: 20 -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt index 2c7e58f7..37f652f3 100644 --- a/docs/_include/interface-vlan-8021q.txt +++ b/docs/_include/interface-vlan-8021q.txt @@ -29,63 +29,63 @@ term used for this is ``vif``. .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. -.. cmdinclude:: ../_include/interface-address-with-dhcp.txt +.. cmdinclude:: /_include/interface-address-with-dhcp.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-disable-link-detect.txt +.. cmdinclude:: /_include/interface-disable-link-detect.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-mac.txt +.. cmdinclude:: /_include/interface-mac.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-mtu.txt +.. cmdinclude:: /_include/interface-mtu.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt +.. cmdinclude:: /_include/interface-ipv6-addr-autoconf.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt +.. cmdinclude:: /_include/interface-ipv6-addr-eui64.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif @@ -94,18 +94,18 @@ term used for this is ``vif``. **DHCP(v6)** -.. cmdinclude:: ../_include/interface-dhcp-options.txt +.. cmdinclude:: /_include/interface-dhcp-options.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. cmdinclude:: ../_include/interface-dhcpv6-options.txt +.. cmdinclude:: /_include/interface-dhcpv6-options.txt :var0: {{ var0 }} :var1: {{ var1 }} :var2: vif :var3: :var4: 10 -.. include:: ../common-references.rst \ No newline at end of file +.. include:: /common-references.rst \ No newline at end of file diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index 870e9a08..d9a3ebe3 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -3,6 +3,7 @@ Firewall ======== + Overview -------- diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 7faddd6f..8ec8f34d 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -17,7 +17,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: bond :var1: bond0 @@ -259,7 +259,7 @@ Bond options VLAN ==== -.. cmdinclude:: ../_include/interface-vlan-8021q.txt +.. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: bond :var1: bond0 diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index dc94a761..766d2aa5 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -21,7 +21,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: bridge :var1: br0 @@ -116,7 +116,7 @@ links providing fault tolerance if an active link fails. VLAN ==== -.. cmdinclude:: ../_include/interface-vlan-8021q.txt +.. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: bridge :var1: br0 diff --git a/docs/configuration/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index c36d0024..c9845230 100644 --- a/docs/configuration/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst @@ -25,19 +25,19 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-address.txt +.. cmdinclude:: /_include/interface-address.txt :var0: dummy :var1: dum0 -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: dummy :var1: dum0 -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: dummy :var1: dum0 -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: dummy :var1: dum0 diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index f2ab3f67..9311c947 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -14,7 +14,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: ethernet :var1: eth0 @@ -72,14 +72,14 @@ VLAN Regular VLANs (802.1q) ---------------------- -.. cmdinclude:: ../_include/interface-vlan-8021q.txt +.. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: ethernet :var1: eth0 QinQ (802.1ad) -------------- -.. cmdinclude:: ../_include/interface-vlan-8021ad.txt +.. cmdinclude:: /_include/interface-vlan-8021ad.txt :var0: ethernet :var1: eth0 diff --git a/docs/configuration/interfaces/geneve.rst b/docs/configuration/interfaces/geneve.rst index 47068687..9e00d621 100644 --- a/docs/configuration/interfaces/geneve.rst +++ b/docs/configuration/interfaces/geneve.rst @@ -39,7 +39,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp.txt :var0: geneve :var1: gnv0 diff --git a/docs/configuration/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index 4c9cbf9b..a4b7be36 100644 --- a/docs/configuration/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _l2tpv3-interface: @@ -31,7 +31,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp.txt :var0: l2tpv3 :var1: l2tpeth0 diff --git a/docs/configuration/interfaces/loopback.rst b/docs/configuration/interfaces/loopback.rst index a6d659b5..f7386c62 100644 --- a/docs/configuration/interfaces/loopback.rst +++ b/docs/configuration/interfaces/loopback.rst @@ -26,11 +26,11 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-address.txt +.. cmdinclude:: /_include/interface-address.txt :var0: loopback :var1: lo -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: loopback :var1: lo diff --git a/docs/configuration/interfaces/macsec.rst b/docs/configuration/interfaces/macsec.rst index ebc8f151..2bf643aa 100644 --- a/docs/configuration/interfaces/macsec.rst +++ b/docs/configuration/interfaces/macsec.rst @@ -20,7 +20,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: macsec :var1: macsec0 diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index c6934335..7646959c 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -581,4 +581,4 @@ The following commands let you reset OpenVPN. -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index 313edd84..decfd348 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -59,15 +59,15 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: pppoe :var1: pppoe0 -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: pppoe :var1: pppoe0 -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: pppoe :var1: pppoe0 @@ -177,7 +177,7 @@ IPv6 Use this command to enable acquisition of IPv6 address using stateless autoconfig (SLAAC). -.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt +.. cmdinclude:: /_include/interface-dhcpv6-prefix-delegation.txt :var0: pppoe :var1: pppoe0 diff --git a/docs/configuration/interfaces/pseudo-ethernet.rst b/docs/configuration/interfaces/pseudo-ethernet.rst index c2baca39..0471d2e1 100644 --- a/docs/configuration/interfaces/pseudo-ethernet.rst +++ b/docs/configuration/interfaces/pseudo-ethernet.rst @@ -45,7 +45,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: pseudo-ethernet :var1: peth0 @@ -60,6 +60,6 @@ Pseudo Ethernet/MACVLAN options VLAN ==== -.. cmdinclude:: ../_include/interface-vlan-8021q.txt +.. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: pseudo-ethernet :var1: peth0 diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 4b9da26b..7b1502f8 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -16,7 +16,7 @@ a closer look at the protocols and options currently supported by VyOS. Common interface configuration ------------------------------ -.. cmdinclude:: ../_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp.txt :var0: tunnel :var1: tun0 diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index 40dc5400..95f8de35 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -39,7 +39,7 @@ Configuration Common interface configuration ------------------------------ -.. cmdinclude:: ../_include/interface-common-without-dhcp.txt +.. cmdinclude:: /_include/interface-common-without-dhcp.txt :var0: vxlan :var1: vxlan0 diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index 2de3b126..82f66cf4 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -30,7 +30,7 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-common-with-dhcp.txt +.. cmdinclude:: /_include/interface-common-with-dhcp.txt :var0: wireless :var1: wlan0 @@ -378,14 +378,14 @@ VLAN Regular VLANs (802.1q) ---------------------- -.. cmdinclude:: ../_include/interface-vlan-8021q.txt +.. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: wireless :var1: wlan0 QinQ (802.1ad) -------------- -.. cmdinclude:: ../_include/interface-vlan-8021ad.txt +.. cmdinclude:: /_include/interface-vlan-8021ad.txt :var0: wireless :var1: wlan0 diff --git a/docs/configuration/interfaces/wirelessmodem.rst b/docs/configuration/interfaces/wirelessmodem.rst index f9dfa228..a65a47f4 100644 --- a/docs/configuration/interfaces/wirelessmodem.rst +++ b/docs/configuration/interfaces/wirelessmodem.rst @@ -15,15 +15,15 @@ Configuration Common interface configuration ============================== -.. cmdinclude:: ../_include/interface-description.txt +.. cmdinclude:: /_include/interface-description.txt :var0: wirelessmodem :var1: wlm0 -.. cmdinclude:: ../_include/interface-disable.txt +.. cmdinclude:: /_include/interface-disable.txt :var0: wirelessmodem :var1: wlm0 -.. cmdinclude:: ../_include/interface-vrf.txt +.. cmdinclude:: /_include/interface-vrf.txt :var0: wirelessmodem :var1: wlm0 diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst index f4e08325..c09c8336 100644 --- a/docs/configuration/nat/nptv6.rst +++ b/docs/configuration/nat/nptv6.rst @@ -1,4 +1,4 @@ -.. include:: _include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _nptv6: diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst index 4be494e5..557911d9 100644 --- a/docs/configuration/policy/index.rst +++ b/docs/configuration/policy/index.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt ###### Policy @@ -65,7 +65,7 @@ neighbor. You now see the longer AS path. -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _routing-pbr: diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index ac2e0510..fcd62c89 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -143,4 +143,4 @@ order of the scripts. .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg .. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 86371845..0a7fecb5 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -711,4 +711,4 @@ http://dev.packages.vyos.net/repositories/. .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 9dd0c495..0276a7d2 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -325,4 +325,4 @@ predefined structure. .. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 60e49974..473d49d9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -77,4 +77,4 @@ the left side under the specific project. .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst deleted file mode 100644 index 7b9bde1e..00000000 --- a/docs/interfaces/advanced-index.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _advanced_network-interfaces: - -################## -Network Interfaces -################## - -.. toctree:: - :maxdepth: 1 - - bond - bridge - dummy - ethernet - geneve - loopback - l2tpv3 - macsec - pppoe - pseudo-ethernet - tunnel - vxlan - wireless - wirelessmodem diff --git a/docs/interfaces/basic-index.rst b/docs/interfaces/basic-index.rst deleted file mode 100644 index 425792a2..00000000 --- a/docs/interfaces/basic-index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _basic_network-interfaces: - -######################## -Basic Network Interfaces -######################## - -.. toctree:: - :maxdepth: 1 - - ethernet - loopback - pppoe diff --git a/docs/routing/bfd.rst b/docs/routing/bfd.rst index 1d494332..b8fdf489 100644 --- a/docs/routing/bfd.rst +++ b/docs/routing/bfd.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _routing-bfd: diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index fe05178b..19787b11 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _routing-ospf: diff --git a/docs/routing/rip.rst b/docs/routing/rip.rst index 68868e37..0d73ad34 100644 --- a/docs/routing/rip.rst +++ b/docs/routing/rip.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _rip: diff --git a/docs/services/conntrack.rst b/docs/services/conntrack.rst index c361d293..55cd088e 100644 --- a/docs/services/conntrack.rst +++ b/docs/services/conntrack.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt Conntrack --------- diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst index 3aedf966..279f0c6d 100644 --- a/docs/services/ipoe-server.rst +++ b/docs/services/ipoe-server.rst @@ -1,4 +1,4 @@ -.. include:: ../_include/need_improvement.txt +.. include:: /_include/need_improvement.txt .. _ipoe_server: @@ -146,4 +146,4 @@ The rate-limit is set in kbit/sec. -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/services/pppoe-server.rst b/docs/services/pppoe-server.rst index e710ba6a..4deb6c7e 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/services/pppoe-server.rst @@ -394,4 +394,4 @@ a /56 subnet for the clients internal use. --------+----------+-------------+--------------------------+---------------------+-------------------+------------+--------+----------+----------+---------- ppp0 | test | 192.168.0.1 | 2001:db8:8002:0:200::/64 | 2001:db8:8003::1/56 | 00:53:00:12:42:eb | | active | 00:00:49 | 875 B | 2.1 KiB -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/system/lcd.rst b/docs/system/lcd.rst index 441becf5..2509946e 100644 --- a/docs/system/lcd.rst +++ b/docs/system/lcd.rst @@ -41,5 +41,5 @@ Configuration .. note:: We can't support all displays from the beginning. If your display type is missing, please create a feature request via Phabricator_. -.. include:: ../common-references.rst +.. include:: /common-references.rst diff --git a/docs/vpn/sstp.rst b/docs/vpn/sstp.rst index e5567cb6..f5e4ad05 100644 --- a/docs/vpn/sstp.rst +++ b/docs/vpn/sstp.rst @@ -344,4 +344,4 @@ A connection attempt will be shown as: .. _sstpc: https://github.com/reliablehosting/sstp-client -.. include:: ../common-references.rst +.. include:: /common-references.rst -- cgit v1.2.3 From dd2b63e441ce0d48ae1cbe8d1abac9e4d55c2465 Mon Sep 17 00:00:00 2001 From: jack9603301 Date: Wed, 9 Dec 2020 16:53:33 +0800 Subject: interface: mirror: Upload Port Mirror(SPAN) Document --- docs/_include/interface-mirror.txt | 17 +++++++++++++++++ docs/configuration/interfaces/bonding.rst | 5 +++++ docs/configuration/interfaces/bridge.rst | 5 +++++ docs/configuration/interfaces/ethernet.rst | 5 +++++ 4 files changed, 32 insertions(+) create mode 100644 docs/_include/interface-mirror.txt (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt new file mode 100644 index 00000000..8cdbf77d --- /dev/null +++ b/docs/_include/interface-mirror.txt @@ -0,0 +1,17 @@ +SPAN port mirroring can copy the inbound/outbound traffic of the interface to the +specified interface, usually the interface can be connected to some special equipment, +such as behavior control system, intrusion detection system and traffic collector, +and can copy all related traffic from this port + +VyOS uses the `mirror` option to configure port mirroring. The configuration is divided +into 2 different directions. Destination ports should be configured for different traffic directions. + +.. cfgcmd:: set interfaces {{ var0 }} mirror ingress + + Configure port mirroring for `interface` inbound traffic and copy the traffic to `monitor-interface` + +.. cfgcmd:: set interfaces {{ var0 }} mirror egress + + Configure port mirroring for `interface` outbound traffic and copy the traffic to `monitor-interface` + + diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 8ec8f34d..547594e5 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -263,6 +263,11 @@ VLAN :var0: bond :var1: bond0 +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + ******* Example ******* diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index 766d2aa5..a471b8f8 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -135,6 +135,11 @@ VLAN can either be an individual VLAN id or a range of VLAN ids delimited by a hyphen. +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + ******* Example ******* diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 9311c947..562aeabc 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -83,6 +83,11 @@ QinQ (802.1ad) :var0: ethernet :var1: eth0 +Port Mirror (SPAN) +================== +.. cmdinclude:: ../../_include/interface-mirror.txt + :var0: ethernet + ********* Operation ********* -- cgit v1.2.3 From f293c1d880af2889e5e5cdd54a18779d9f755c73 Mon Sep 17 00:00:00 2001 From: rebortg Date: Fri, 11 Dec 2020 22:40:02 +0100 Subject: interfaces: fix lint errors --- docs/configuration/interfaces/bonding.rst | 4 +-- docs/configuration/interfaces/ethernet.rst | 4 +++ docs/configuration/interfaces/openvpn.rst | 48 +++++++++++++++------------- docs/configuration/interfaces/pppoe.rst | 4 +++ docs/configuration/interfaces/tunnel.rst | 8 +++-- docs/configuration/interfaces/vxlan.rst | 4 +-- docs/configuration/interfaces/wireguard.rst | 4 +++ docs/configuration/interfaces/wireless.rst | 49 +++++++++++++++++++---------- 8 files changed, 81 insertions(+), 44 deletions(-) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 547594e5..84f00132 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -352,8 +352,8 @@ interfaces from VyOS to a Juniper EX Switch system. Aruba/HP ======== -For a headstart you can use the below example on how to build a bond,port-channel -with two interfaces from VyOS to a Aruba/HP 2510G switch. +For a headstart you can use the below example on how to build a +bond,port-channel with two interfaces from VyOS to a Aruba/HP 2510G switch. .. code-block:: none diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 562aeabc..b4151dd2 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -123,6 +123,8 @@ Operation TX: bytes packets errors dropped carrier collisions 5601460 62595 0 0 0 0 +.. stop_vyoslinter + .. opcmd:: show interfaces ethernet physical Show information about physical `` @@ -162,6 +164,8 @@ Operation supports-register-dump: yes supports-priv-flags: no +.. start_vyoslinter + .. opcmd:: show interfaces ethernet physical offload Show available offloading functions on given `` diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index f503ae84..0e4e9d74 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -186,7 +186,8 @@ Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. Refer this section **Generate X.509 Certificate and Keys** to generate a CA certificate, a server certificate and key, a certificate revocation list, a Diffie-Hellman -key exchange parameters file. You do not need client certificates and keys for the server setup. +key exchange parameters file. You do not need client certificates and keys for +the server setup. In this example we will use the most complicated case: a setup where each client is a router that has its own subnet (think HQ and branch offices), since @@ -269,16 +270,16 @@ Copy the Easy-RSA scripts to a new directory to modify the values. cd /config/my-easy-rsa-config To ensure the consistent use of values when generating the PKI, set default -values to be used by the PKI generating scripts. Rename the vars.example filename -to vars +values to be used by the PKI generating scripts. Rename the vars.example +filename to vars .. code-block:: none mv vars.example vars -Following is the instance of the file after editing. You may also change other values in -the file at your discretion/need, though for most cases the defaults should be just fine. -(do not leave any of these parameters blank) +Following is the instance of the file after editing. You may also change other +values in the file at your discretion/need, though for most cases the defaults +should be just fine. (do not leave any of these parameters blank) .. code-block:: none @@ -292,9 +293,9 @@ the file at your discretion/need, though for most cases the defaults should be j set_var EASYRSA_KEY_SIZE 2048 -init-pki option will create a new pki directory or will delete any previously generated -certificates stored in that folder. The term 'central' is used to refer server and -'branch' for client +init-pki option will create a new pki directory or will delete any previously +generated certificates stored in that folder. The term 'central' is used to +refer server and 'branch' for client .. note:: Remember the “CA Key Passphrase” prompted in build-ca command, as it will be asked in signing the server/client certificate. @@ -308,7 +309,8 @@ certificates stored in that folder. The term 'central' is used to refer server a vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass -To generate a certificate revocation list for any client, execute these commands: +To generate a certificate revocation list for any client, execute these +commands: .. code-block:: none @@ -326,8 +328,8 @@ Copy the files to /config/auth/ovpn/ to use in OpenVPN tunnel creation vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/ovpn vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/ovpn -Additionally, each client needs a copy of ca.crt and its own client key and cert files. -The files are plaintext so they may be copied either manually, +Additionally, each client needs a copy of ca.crt and its own client key and +cert files. The files are plaintext so they may be copied either manually, or through a remote file transfer tool like scp. Whichever method you use, the files need to end up in the proper location on each router. For example, Branch 1's router might have the following files: @@ -344,12 +346,13 @@ LDAP ---- Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employees. VyOS and OpenVPN support using -LDAP/AD as single user backend. +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is -shipped with every VyOS installation. A dedicated configuration file is required. -It is best practise to store it in ``/config`` to survive image updates +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in ``/config`` to survive image +updates .. code-block:: none @@ -435,7 +438,8 @@ If you only want to check if the user account is enabled and can authenticate RequireGroup false -A complete LDAP auth OpenVPN configuration could look like the following example: +A complete LDAP auth OpenVPN configuration could look like the following +example: .. code-block:: none @@ -453,8 +457,8 @@ A complete LDAP auth OpenVPN configuration could look like the following example server { domain-name example.com max-connections 5 - name-server 1.1.1.1 - name-server 9.9.9.9 + name-server 203.0.113.0.10 + name-server 198.51.100.3 subnet 172.18.100.128/29 } tls { @@ -534,7 +538,8 @@ Will add ``persistent-key`` at the end of the generated OpenVPN configuration. Please use this only as last resort - things might break and OpenVPN won't start if you pass invalid options/syntax. -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'push "keepalive 1 10"' +.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option + 'push "keepalive 1 10"' Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. @@ -563,7 +568,8 @@ The following commands let you check tunnel status. .. opcmd:: show openvpn site-to-site - Use this command to check the tunnel status for OpenVPN site-to-site interfaces. + Use this command to check the tunnel status for OpenVPN site-to-site + interfaces. Reset OpenVPN diff --git a/docs/configuration/interfaces/pppoe.rst b/docs/configuration/interfaces/pppoe.rst index 393c71ed..9d10b91f 100644 --- a/docs/configuration/interfaces/pppoe.rst +++ b/docs/configuration/interfaces/pppoe.rst @@ -287,10 +287,14 @@ which is the default VLAN for Deutsche Telekom: IPv6 DHCPv6-PD Example ---------------------- +.. stop_vyoslinter + The following configuration will assign a /64 prefix out of a /56 delegation to eth0. The IPv6 address assigned to eth0 will be ::ffff/64. If you do not know the prefix size delegated to you, start with sla-len 0. +.. start_vyoslinter + .. code-block:: none set interfaces pppoe pppoe0 authentication user vyos diff --git a/docs/configuration/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 7b1502f8..b1e86edf 100644 --- a/docs/configuration/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst @@ -93,7 +93,8 @@ An example: set interfaces tunnel tun0 remote-ip 192.0.2.20 set interfaces tunnel tun0 address 2001:db8:bb::1/64 -A full example of a Tunnelbroker.net config can be found at :ref:`here `. +A full example of a Tunnelbroker.net config can be found at +:ref:`here `. Generic Routing Encapsulation (GRE) ----------------------------------- @@ -135,7 +136,10 @@ ip otherwise it would have to be configured as well. Tunnel keys ^^^^^^^^^^^ -GRE is also the only classic protocol that allows creating multiple tunnels with the same source and destination due to its support for tunnel keys. Despite its name, this feature has nothing to do with security: it's simply an identifier that allows routers to tell one tunnel from another. +GRE is also the only classic protocol that allows creating multiple tunnels +with the same source and destination due to its support for tunnel keys. +Despite its name, this feature has nothing to do with security: it's simply +an identifier that allows routers to tell one tunnel from another. An example: diff --git a/docs/configuration/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index 95f8de35..ca25d21e 100644 --- a/docs/configuration/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst @@ -240,8 +240,8 @@ advertised. set interfaces bridge br241 member interface 'eth1.241' set interfaces bridge br241 member interface 'vxlan241' -Binds eth1.241 and vxlan241 to each other by making them both member interfaces of -the same bridge. +Binds eth1.241 and vxlan241 to each other by making them both member +interfaces of the same bridge. .. code-block:: none diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index 3580fac3..c4dfbee7 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -262,4 +262,8 @@ Operational commands vyos@wg01# wireguard keypair default +.. stop_vyoslinter + .. _`WireGuard mailing list`: https://lists.zx2c4.com/pipermail/wireguard/2018-December/003704.html + +.. start_vyoslinter \ No newline at end of file diff --git a/docs/configuration/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index fca285eb..097d7c49 100644 --- a/docs/configuration/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst @@ -111,7 +111,8 @@ Wireless options SSID to be used in IEEE 802.11 management frames -.. cfgcmd:: set interfaces wireless type +.. cfgcmd:: set interfaces wireless type + Wireless device type for this interface @@ -137,7 +138,8 @@ HT (High Throughput) capabilities (802.11n) WMM-PS Unscheduled Automatic Power Save Delivery [U-APSD] -.. cfgcmd:: set interfaces wireless capabilities ht channel-set-width +.. cfgcmd:: set interfaces wireless capabilities ht + channel-set-width Supported channel width set. @@ -150,7 +152,8 @@ HT (High Throughput) capabilities (802.11n) Following table shows the channels that may be available for HT40- and HT40+ use per IEEE 802.11n Annex J: - Depending on the location, not all of these channels may be available for use! + Depending on the location, not all of these channels may be available for + use! .. code-block:: none @@ -163,7 +166,8 @@ HT (High Throughput) capabilities (802.11n) BSSes. These changes are done automatically when hostapd is setting up the 40 MHz channel. -.. cfgcmd:: set interfaces wireless capabilities ht delayed-block-ack +.. cfgcmd:: set interfaces wireless capabilities ht + delayed-block-ack Enable HT-delayed Block Ack ``[DELAYED-BA]`` @@ -183,15 +187,18 @@ HT (High Throughput) capabilities (802.11n) Enable L-SIG TXOP protection capability -.. cfgcmd:: set interfaces wireless capabilities ht max-amsdu <3839 | 7935> +.. cfgcmd:: set interfaces wireless capabilities ht max-amsdu + <3839 | 7935> Maximum A-MSDU length 3839 (default) or 7935 octets -.. cfgcmd:: set interfaces wireless capabilities ht short-gi <20 | 40> +.. cfgcmd:: set interfaces wireless capabilities ht + short-gi <20 | 40> Short GI capabilities for 20 and 40 MHz -.. cfgcmd:: set interfaces wireless capabilities ht smps +.. cfgcmd:: set interfaces wireless capabilities ht + smps Spatial Multiplexing Power Save (SMPS) settings @@ -210,7 +217,8 @@ VHT (Very High Throughput) capabilities (802.11ac) Number of antennas on this card -.. cfgcmd:: set interfaces wireless capabilities vht antenna-pattern-fixed +.. cfgcmd:: set interfaces wireless capabilities vht + antenna-pattern-fixed Set if antenna pattern does not change during the lifetime of an association @@ -225,15 +233,19 @@ VHT (Very High Throughput) capabilities (802.11ac) * ``multi-user-beamformer`` - Support for operation as single user beamformer * ``multi-user-beamformee`` - Support for operation as single user beamformer -.. cfgcmd:: set interfaces wireless capabilities vht center-channel-freq +.. cfgcmd:: set interfaces wireless capabilities vht + center-channel-freq - VHT operating channel center frequency - center freq 1 (for use with 80, 80+80 and 160 modes) + VHT operating channel center frequency - center freq 1 + (for use with 80, 80+80 and 160 modes) - VHT operating channel center frequency - center freq 2 (for use with the 80+80 mode) + VHT operating channel center frequency - center freq 2 + (for use with the 80+80 mode) must be from 34 - 173. For 80 MHz channels it should be channel + 6. -.. cfgcmd:: set interfaces wireless capabilities vht channel-set-width <0 | 1 | 2 | 3> +.. cfgcmd:: set interfaces wireless capabilities vht + channel-set-width <0 | 1 | 2 | 3> * ``0`` - 20 or 40 MHz channel width (default) * ``1`` - 80 MHz channel width @@ -248,15 +260,18 @@ VHT (Very High Throughput) capabilities (802.11ac) VHT link adaptation capabilities -.. cfgcmd:: set interfaces wireless capabilities vht max-mpdu +.. cfgcmd:: set interfaces wireless capabilities vht + max-mpdu Increase Maximum MPDU length to 7991 or 11454 octets (default 3895 octets) -.. cfgcmd:: set interfaces wireless capabilities vht max-mpdu-exp +.. cfgcmd:: set interfaces wireless capabilities vht + max-mpdu-exp Set the maximum length of A-MPDU pre-EOF padding that the station can receive -.. cfgcmd:: set interfaces wireless capabilities vht short-gi <80 | 160> +.. cfgcmd:: set interfaces wireless capabilities vht + short-gi <80 | 160> Short GI capabilities @@ -440,8 +455,8 @@ information about all wireless interfaces. .. opcmd:: show interfaces wireless -This command shows both status and statistics on the specified wireless interface. -The wireless interface identifier can range from wlan0 to wlan999. +This command shows both status and statistics on the specified wireless +interface. The wireless interface identifier can range from wlan0 to wlan999. .. code-block:: none -- cgit v1.2.3 From 84ea67db630846210df983f4ab4cb966a550790a Mon Sep 17 00:00:00 2001 From: jack9603301 Date: Sun, 20 Dec 2020 22:24:48 +0800 Subject: Examples of adding VLAN awareness and port mirroring --- docs/_include/interface-mirror.txt | 12 ++++++++++++ docs/configuration/interfaces/bonding.rst | 4 +++- docs/configuration/interfaces/bridge.rst | 22 +++++++++++++++++++++- docs/configuration/interfaces/ethernet.rst | 2 ++ 4 files changed, 38 insertions(+), 2 deletions(-) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt index a3d12220..7903299a 100644 --- a/docs/_include/interface-mirror.txt +++ b/docs/_include/interface-mirror.txt @@ -12,11 +12,23 @@ for different traffic directions. Configure port mirroring for `interface` inbound traffic and copy the traffic to `monitor-interface` + + Example: Mirror the inbound traffic of `{{ var1 }}` port to `eth2` + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mirror ingress {{ var2 }} .. cfgcmd:: set interfaces {{ var0 }} mirror egress Configure port mirroring for `interface` outbound traffic and copy the traffic to `monitor-interface` + + Example: Mirror the outbound traffic of `{{ var1 }}` port to `eth2` + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mirror egress {{ var2 }} diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 84f00132..92601b37 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -266,7 +266,9 @@ VLAN Port Mirror (SPAN) ================== .. cmdinclude:: ../../_include/interface-mirror.txt - :var0: ethernet + :var0: bonding + :var1: bond1 + :var2: eth3 ******* Example diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index a471b8f8..17e3d50b 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -127,6 +127,12 @@ VLAN VLAN tag enters the port, the data packet will be forced to add a tag of a specific vlan id. When the vlan id flag flows out, the tag of the vlan id will be stripped + + Example: Set `eth0` member port to be native VLAN 2 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 native-vlan 2 .. cfgcmd:: set interfaces bridge member interface allowed-vlan @@ -134,11 +140,25 @@ VLAN Allows specific VLAN IDs to pass through the bridge member interface. This can either be an individual VLAN id or a range of VLAN ids delimited by a hyphen. + + Example: Set `eth0` member port to be allowed VLAN 4 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 4 + + Example: Set `eth0` member port to be allowed VLAN 6-8 + + .. code-block:: none + + set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 Port Mirror (SPAN) ================== .. cmdinclude:: ../../_include/interface-mirror.txt - :var0: ethernet + :var0: bridge + :var1: br1 + :var2: eth3 ******* Example diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index b4151dd2..c1ee724b 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -87,6 +87,8 @@ Port Mirror (SPAN) ================== .. cmdinclude:: ../../_include/interface-mirror.txt :var0: ethernet + :var1: eth1 + :var2: eth3 ********* Operation -- cgit v1.2.3 From c06ec85619a4c98342ab8791d73fd6ab5a9239db Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 20 Dec 2020 16:07:13 +0100 Subject: ethernet: document offloading --- docs/configuration/interfaces/ethernet.rst | 34 ++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index b4151dd2..2debed16 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -66,6 +66,40 @@ Ethernet options set interfaces ethernet eth0 mirror eth1 +Offloading +---------- + +.. cfgcmd:: set interfaces ethernet offload + + Enable different types of hardware offloading on the given NIC. + + Generic segmentation offload is a pure software offload that is meant to deal + with cases where device drivers cannot perform the offloads described above. + What occurs in GSO is that a given skbuff will have its data broken out over + multiple skbuffs that have been resized to match the MSS provided via + skb_shinfo()->gso_size. + + Before enabling any hardware segmentation offload a corresponding software + offload is required in GSO. Otherwise it becomes possible for a frame to be + re-routed between devices and end up being unable to be transmitted. + + Generic receive offload is the complement to GSO. Ideally any frame assembled + by GRO should be segmented to create an identical sequence of frames using + GSO, and any sequence of frames segmented by GSO should be able to be + reassembled back to the original by GRO. The only exception to this is IPv4 + ID in the case that the DF bit is set for a given IP header. If the value of + the IPv4 ID is not sequentially incrementing it will be altered so that it is + when a frame assembled via GRO is segmented via GSO. + + .. warning:: Recent 1.3 rolling images also support XDP offloading which + stands for eXpress Data Path in the Linux Kernel. You must enable it for + every interface which should participate in the XDP forwarding. + + Enabling this feature will break any form of NAT or Firewalling on this + interface, as XDP is handled way earlier in the driver then NfTables. + + VLAN ==== -- cgit v1.2.3 From 6cdae273512a3e78cef93c1227274fcf4733add0 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Wed, 23 Dec 2020 14:16:37 +0100 Subject: ethernet: xdp: adjust CLI node --- docs/configuration/interfaces/ethernet.rst | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 25eebf25..8c6bcc07 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -92,13 +92,24 @@ Offloading the IPv4 ID is not sequentially incrementing it will be altered so that it is when a frame assembled via GRO is segmented via GSO. - .. warning:: Recent 1.3 rolling images also support XDP offloading which - stands for eXpress Data Path in the Linux Kernel. You must enable it for - every interface which should participate in the XDP forwarding. +.. cfgcmd:: set interfaces ethernet xdp - Enabling this feature will break any form of NAT or Firewalling on this - interface, as XDP is handled way earlier in the driver then NfTables. + Enable support for Linux :abbr:`XDP (eXpress Data Path)` on recent 1.3 rolling + releases. You must enable it for every interface which should participate in + the XDP forwarding. + XDP is an eBPF based high performance data path merged in the Linux kernel + since version 4.8. The idea behind XDP is to add an early hook in the RX path + of the kernel, and let a user supplied eBPF program decide the fate of the + packet. The hook is placed in the NIC driver just after the interrupt + processing, and before any memory allocation needed by the network stack + itself, because memory allocation can be an expensive operation. + + .. warning:: This is highly experimental! + + .. note:: Enabling this feature will break any form of NAT or Firewalling on + this interface, as XDP is handled way earlier in the driver then iptables/ + nftables. VLAN ==== -- cgit v1.2.3 From 2b55a3a72fca5975724836df2d857de77fb12e7f Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Wed, 23 Dec 2020 14:30:45 +0100 Subject: xdp: use common include for both ethernet and bond --- docs/_include/interface-xdp.txt | 24 ++++++++++++++++++++++++ docs/configuration/interfaces/bonding.rst | 8 ++++++++ docs/configuration/interfaces/ethernet.rst | 21 +++------------------ 3 files changed, 35 insertions(+), 18 deletions(-) create mode 100644 docs/_include/interface-xdp.txt (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/_include/interface-xdp.txt b/docs/_include/interface-xdp.txt new file mode 100644 index 00000000..6f5f88c1 --- /dev/null +++ b/docs/_include/interface-xdp.txt @@ -0,0 +1,24 @@ +.. cfgcmd:: set interfaces {{ var0 }} xdp + + Enable support for Linux :abbr:`XDP (eXpress Data Path)` on recent 1.3 rolling + releases. You must enable it for every interface which should participate in + the XDP forwarding. + + XDP is an eBPF based high performance data path merged in the Linux kernel + since version 4.8. The idea behind XDP is to add an early hook in the RX path + of the kernel, and let a user supplied eBPF program decide the fate of the + packet. The hook is placed in the NIC driver just after the interrupt + processing, and before any memory allocation needed by the network stack + itself, because memory allocation can be an expensive operation. + + .. warning:: This is highly experimental! + + .. note:: Enabling this feature will break any form of NAT or Firewalling on + this interface, as XDP is handled way earlier in the driver then iptables/ + nftables. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} xdp \ No newline at end of file diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 92601b37..bf7cfc2c 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -256,6 +256,13 @@ Bond options The maximum number of targets that can be specified is 16. The default value is no IP addresses. +Offloading +---------- + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: bonding + :var1: bond0 + VLAN ==== @@ -265,6 +272,7 @@ VLAN Port Mirror (SPAN) ================== + .. cmdinclude:: ../../_include/interface-mirror.txt :var0: bonding :var1: bond1 diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 8c6bcc07..2eca130f 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -92,24 +92,9 @@ Offloading the IPv4 ID is not sequentially incrementing it will be altered so that it is when a frame assembled via GRO is segmented via GSO. -.. cfgcmd:: set interfaces ethernet xdp - - Enable support for Linux :abbr:`XDP (eXpress Data Path)` on recent 1.3 rolling - releases. You must enable it for every interface which should participate in - the XDP forwarding. - - XDP is an eBPF based high performance data path merged in the Linux kernel - since version 4.8. The idea behind XDP is to add an early hook in the RX path - of the kernel, and let a user supplied eBPF program decide the fate of the - packet. The hook is placed in the NIC driver just after the interrupt - processing, and before any memory allocation needed by the network stack - itself, because memory allocation can be an expensive operation. - - .. warning:: This is highly experimental! - - .. note:: Enabling this feature will break any form of NAT or Firewalling on - this interface, as XDP is handled way earlier in the driver then iptables/ - nftables. +.. cmdinclude:: /_include/interface-xdp.txt + :var0: ethernet + :var1: eth0 VLAN ==== -- cgit v1.2.3 From 9133eaa620cd81c450084c5952c4b9ac99c24313 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Wed, 23 Dec 2020 15:45:26 +0100 Subject: xdp: ethernet: show statistics --- docs/configuration/interfaces/ethernet.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 2eca130f..3eae0d95 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -265,3 +265,29 @@ Operation Vendor SN : FNS092xxxxx Date code : 0506xx +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet xdp + + Display XDP forwarding statistics + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth1 xdp + + Collecting stats from BPF map + - BPF map (bpf_map_type:6) id:176 name:xdp_stats_map key_size:4 value_size:16 max_entries:5 + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250340 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250317 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250314 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000410 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + -- cgit v1.2.3 From 1162e00071c9d28b2c86f6ba3a9e4e8b086e8783 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 29 Dec 2020 11:32:37 +0100 Subject: ethernet: add eapol documentation --- docs/configuration/interfaces/ethernet.rst | 38 ++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 3eae0d95..4392c1c8 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -96,6 +96,44 @@ Offloading :var0: ethernet :var1: eth0 +Authentication (EAPoL) +---------------------- + +:abbr:`EAP (Extensible Authentication Protocol)` over LAN (EAPoL) is a network +port authentication protocol used in IEEE 802.1X (Port Based Network Access +Control) developed to give a generic network sign-on to access network +resources. + +EAPoL comes with an identify option. We automatically use the interface MAC +address as identity parameter. + +.. cfgcmd:: set interfaces ethernet eapol ca-cert-file + + SSL :abbr:`CA (Certificate Authority)` x509 PEM file used afor authentication + of the remote side. + + .. code-block: none + + set interfaces ethernet eth0 eapol ca-cert-file /config/auth/ca.pem + +.. cfgcmd:: set interfaces ethernet eapol cert-file + + SSL/x509 public certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block: none + + set interfaces ethernet eth0 eapol cert-file /config/auth/public.pem + +.. cfgcmd:: set interfaces ethernet eapol key-file + + SSL/x509 private certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block: none + + set interfaces ethernet eth0 eapol key-file /config/auth/private.key + VLAN ==== -- cgit v1.2.3 From 91a07725badb093da149f35045ad40d9673ecbbd Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Tue, 29 Dec 2020 12:04:47 +0100 Subject: ethernet: eapol: use re-includable interface definition --- docs/_include/interface-eapol.txt | 37 ++++++++++++++++++++++++++++++ docs/configuration/interfaces/ethernet.rst | 36 +++-------------------------- 2 files changed, 40 insertions(+), 33 deletions(-) create mode 100644 docs/_include/interface-eapol.txt (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/_include/interface-eapol.txt b/docs/_include/interface-eapol.txt new file mode 100644 index 00000000..68e5073d --- /dev/null +++ b/docs/_include/interface-eapol.txt @@ -0,0 +1,37 @@ +:abbr:`EAP (Extensible Authentication Protocol)` over LAN (EAPoL) is a network +port authentication protocol used in IEEE 802.1X (Port Based Network Access +Control) developed to give a generic network sign-on to access network +resources. + +EAPoL comes with an identify option. We automatically use the interface MAC +address as identity parameter. + +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol ca-cert-file + + SSL :abbr:`CA (Certificate Authority)` x509 PEM file used afor authentication + of the remote side. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol ca-cert-file /config/auth/ca.pem + +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol cert-file + + SSL/x509 public certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol cert-file /config/auth/public.pem + +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} + {{ var5 }} {{ var6 }} eapol key-file + + SSL/x509 private certificate file provided by the client to authenticate + against the 802.1x system. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} eapol key-file /config/auth/private.key diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 4392c1c8..d7bc8518 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -99,40 +99,10 @@ Offloading Authentication (EAPoL) ---------------------- -:abbr:`EAP (Extensible Authentication Protocol)` over LAN (EAPoL) is a network -port authentication protocol used in IEEE 802.1X (Port Based Network Access -Control) developed to give a generic network sign-on to access network -resources. - -EAPoL comes with an identify option. We automatically use the interface MAC -address as identity parameter. - -.. cfgcmd:: set interfaces ethernet eapol ca-cert-file - - SSL :abbr:`CA (Certificate Authority)` x509 PEM file used afor authentication - of the remote side. - - .. code-block: none - - set interfaces ethernet eth0 eapol ca-cert-file /config/auth/ca.pem - -.. cfgcmd:: set interfaces ethernet eapol cert-file - - SSL/x509 public certificate file provided by the client to authenticate - against the 802.1x system. - - .. code-block: none - - set interfaces ethernet eth0 eapol cert-file /config/auth/public.pem - -.. cfgcmd:: set interfaces ethernet eapol key-file - - SSL/x509 private certificate file provided by the client to authenticate - against the 802.1x system. - - .. code-block: none +.. cmdinclude:: /_include/interface-eapol.txt + :var0: ethernet + :var1: eth0 - set interfaces ethernet eth0 eapol key-file /config/auth/private.key VLAN ==== -- cgit v1.2.3 From 4b4db5d2303817bb4fe6f0b85e9a97b018d81bb3 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 1 Jan 2021 20:08:55 +0100 Subject: ethernet: add rps (receive packet steering) support --- docs/configuration/interfaces/ethernet.rst | 42 ++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 14 deletions(-) (limited to 'docs/configuration/interfaces/ethernet.rst') diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index d7bc8518..1d99019c 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -69,28 +69,42 @@ Ethernet options Offloading ---------- -.. cfgcmd:: set interfaces ethernet offload +.. cfgcmd:: set interfaces ethernet offload Enable different types of hardware offloading on the given NIC. - Generic segmentation offload is a pure software offload that is meant to deal - with cases where device drivers cannot perform the offloads described above. - What occurs in GSO is that a given skbuff will have its data broken out over - multiple skbuffs that have been resized to match the MSS provided via - skb_shinfo()->gso_size. + :abbr:`GSO (Generic Segmentation Offload)` is a pure software offload that is + meant to deal with cases where device drivers cannot perform the offloads + described above. What occurs in GSO is that a given skbuff will have its data + broken out over multiple skbuffs that have been resized to match the MSS + provided via skb_shinfo()->gso_size. Before enabling any hardware segmentation offload a corresponding software offload is required in GSO. Otherwise it becomes possible for a frame to be re-routed between devices and end up being unable to be transmitted. - Generic receive offload is the complement to GSO. Ideally any frame assembled - by GRO should be segmented to create an identical sequence of frames using - GSO, and any sequence of frames segmented by GSO should be able to be - reassembled back to the original by GRO. The only exception to this is IPv4 - ID in the case that the DF bit is set for a given IP header. If the value of - the IPv4 ID is not sequentially incrementing it will be altered so that it is - when a frame assembled via GRO is segmented via GSO. + :abbr:`GRO (Generic receive offload)` is the complement to GSO. Ideally any + frame assembled by GRO should be segmented to create an identical sequence of + frames using GSO, and any sequence of frames segmented by GSO should be able + to be reassembled back to the original by GRO. The only exception to this is + IPv4 ID in the case that the DF bit is set for a given IP header. If the + value of the IPv4 ID is not sequentially incrementing it will be altered so + that it is when a frame assembled via GRO is segmented via GSO. + + :abbr:`RPS (Receive Packet Steering)` is logically a software implementation + of :abbr:`RSS (Receive Side Scaling)`. Being in software, it is necessarily + called later in the datapath. Whereas RSS selects the queue and hence CPU that + will run the hardware interrupt handler, RPS selects the CPU to perform + protocol processing above the interrupt handler. This is accomplished by + placing the packet on the desired CPU's backlog queue and waking up the CPU + for processing. RPS has some advantages over RSS: + + - it can be used with any NIC, + - software filters can easily be added to hash over new protocols, + - it does not increase hardware device interrupt rate (although it does + introduce inter-processor interrupts (IPIs)). + .. cmdinclude:: /_include/interface-xdp.txt :var0: ethernet -- cgit v1.2.3