From 8c0190a6cc9b7ae2b0d2f26205ab3601b35fe0b7 Mon Sep 17 00:00:00 2001 From: LiudmylaNad Date: Tue, 23 Dec 2025 14:37:59 +0100 Subject: DOC: Proofreading bonding.rst (#1721) --- docs/_include/interface-address-with-dhcp.txt | 26 +-- docs/_include/interface-description.txt | 8 +- docs/_include/interface-dhcp-options.txt | 59 ++++--- docs/_include/interface-dhcpv6-options.txt | 60 +++++-- .../interface-dhcpv6-prefix-delegation.txt | 64 ++++--- docs/_include/interface-disable-flow-control.txt | 18 +- docs/_include/interface-disable-link-detect.txt | 6 +- docs/_include/interface-disable.txt | 4 +- docs/_include/interface-evpn-uplink.txt | 10 +- docs/_include/interface-ip.txt | 194 ++++++++++++--------- docs/_include/interface-ipv6.txt | 80 +++++---- docs/_include/interface-mac.txt | 3 +- docs/_include/interface-mirror.txt | 41 +++-- docs/_include/interface-mtu.txt | 6 +- docs/_include/interface-vlan-8021q.txt | 48 +++-- docs/_include/interface-vrf.txt | 7 +- 16 files changed, 366 insertions(+), 268 deletions(-) (limited to 'docs/_include') diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt index d454d051..c0afc203 100644 --- a/docs/_include/interface-address-with-dhcp.txt +++ b/docs/_include/interface-address-with-dhcp.txt @@ -2,18 +2,20 @@ {{ var5 }} {{ var6 }} address
- Configure 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. - - .. note:: When using DHCP to retrieve IPv4 address and if local - customizations are needed, they should be possible using the enter and - exit hooks provided. The hook dirs are: + **Configure the interface with one or more IP addresses.** + + The following options are available: + + * **address:** Assign one or more IPv4 or IPv6 addresses to the interface. + For example, use 192.0.2.1/24 for IPv4 or 2001:db8::1/64 for IPv6. + * **dhcp:** The interface obtains an IPv4 address from a DHCP server on the + same network segment. + * **dhcpv6:** The interface obtains an IPv6 address from a DHCPv6 server on + the same network segment. + + .. note:: If the interface obtains an IPv4 address via DHCP, and specific + adjustments are needed before/after the IP address is obtained, use the + provided hook scripts: * ``/config/scripts/dhcp-client/pre-hooks.d/`` * ``/config/scripts/dhcp-client/post-hooks.d/`` diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt index 064d9559..2de47fe3 100644 --- a/docs/_include/interface-description.txt +++ b/docs/_include/interface-description.txt @@ -1,11 +1,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} 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. + **Configure a clear, descriptive alias for the interface.** + + This alias appears in the :opcmd:`show interfaces` command and SNMP-based + monitoring tools. Example: .. code-block:: none - set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} description 'This is an awesome interface running on VyOS' \ No newline at end of file + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} description 'This is an interface running on VyOS.' \ No newline at end of file diff --git a/docs/_include/interface-dhcp-options.txt b/docs/_include/interface-dhcp-options.txt index c5683ca3..6cc715e7 100644 --- a/docs/_include/interface-dhcp-options.txt +++ b/docs/_include/interface-dhcp-options.txt @@ -1,12 +1,14 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options client-id - :rfc:`2131` states: The client MAY choose to explicitly provide the identifier - through the 'client identifier' option. If the client supplies a 'client - identifier', the client MUST use the same 'client identifier' in all - subsequent messages, and the server MUST use that identifier to identify the - client. - + **Configure a DHCP client identifier for the interface, as specified in** + :rfc:`2131`. + + The ``client-id`` is an identifier that the DHCP client sends to the DHCP + server to uniquely identify itself for IP address assignment. By default, + the client uses its MAC address. The ```` is a user-defined + string that will be sent to the DHCP server as the DHCP client identifier. + Example: .. code-block:: none @@ -16,8 +18,10 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options host-name - Instead of sending the real system hostname to the DHCP server, overwrite the - host-name with this given-value. + **Configure a specific hostname for the interface.** + + Instead of the real hostname, the DHCP client will send the specific hostname + to the DHCP server when requesting an IP address. Example: @@ -28,13 +32,12 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options vendor-class-id - This option is used by some DHCP clients to identify the vendor type and - possibly the configuration of a DHCP client. The information is a string of - bytes whose contents are specific to the vendor and are not specified in a - standard. + **Configure the DHCP client to include a vendor-class identifier in its DHCP + requests on this interface.** - The vendor-class-id option can be used to request a specific class of vendor - options from the server. + The vendor-class identifier is a vendor-specific byte string that enables + the DHCP server to identify the device and, in some cases, provide + configuration options. Example: @@ -45,8 +48,8 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options no-default-route - Only request an address from the DHCP server but do not request a default - gateway. + **Configure the DHCP client to obtain an IP address, but ignore any default + gateway provided by the DHCP server on this interface.** Example: @@ -57,7 +60,8 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options default-route-distance - Set the distance for the default gateway sent by the DHCP server. + **Configure the distance for the default route obtained from the DHCP server + on this interface.** Example: @@ -68,11 +72,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options reject
- Reject DHCP leases from a given address or range. - This is useful when a modem gives a local IP when first starting. + **Configure the DHCP client to reject the specific IP address or IP address + range from the DHCP server on this interface.** - * **address** can be specified multiple times, - e.g. 192.168.100.1 and/or 192.168.100.0/24 + This is useful when a modem assigns a local IP address upon start. To reject + multiple addresses, run this command multiple times with different values. + You can reject individual addresses (192.168.100.1) or entire subnets + (192.168.100.0/24). Example: @@ -83,10 +89,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcp-options user-class - This option is used by some DHCP clients as a way for users to specify - identifying information to the client. This can be used in a similar way to - the vendor-class-identifier option, but the value of the option is specified - by the user, not the vendor. + **Configure the DHCP client to send a specific user-class identifier in its + DHCP requests on this interface.** + + The DHCP server can interpret this identifier and provide specific + configuration options based on it (for example, default routes). + The user-class value typically groups DHCP clients with similar configuration + needs (for example, employees, guests, or printers). Example: diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt index e584f36b..4f4a1869 100644 --- a/docs/_include/interface-dhcpv6-options.txt +++ b/docs/_include/interface-dhcpv6-options.txt @@ -1,11 +1,23 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options duid - The DHCP unique identifier (DUID) is used by a client to get an IP address - from a DHCPv6 server. It has a 2-byte DUID type field, and a variable-length - identifier field up to 128 bytes. Its actual length depends on its type. The - server compares the DUID with its database and delivers configuration data - (address, lease times, DNS servers, etc.) to the client. + **Configure a specific** :abbr:`DUID (DHCP Unique Identifier)` **for the + DHCPv6 client on this interface.** + + The DUID is an identifier used by a DHCPv6 client to get an IPv6 address from + a DHCPv6 server. It consists of a 2-byte type field, followed by a + variable-length identifier field up to 128 bytes. The format of the identifier + part depends on the DUID type: + + * **DUID-LLT:** The most common type, which includes a hardware type, a timestamp, and a MAC address. + * **DUID-EN:** Is based on a vendor's enterprise number and a unique identifier assigned by the vendor. + * **DUID-LL:** Includes only a MAC address. + + The DHCP server matches the DUID against its database and provides + configuration data (such as address, lease times, DNS servers, etc.) + to the DHCP client. + + Example: .. code-block:: none @@ -14,8 +26,12 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options no-release - When no-release is specified, dhcp6c will avoid sending a release message on - client exit in order to prevent losing an assigned address or prefix. + **Configure the DHCP client not to send a release message when it stops + running on this interface.** + + This helps retain the assigned address or prefix. + + Example: .. code-block:: none @@ -25,10 +41,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options parameters-only - This statement specifies dhcp6c to only exchange informational configuration - parameters with servers. A list of DNS server addresses is an example of such - parameters. This statement is useful when the client does not need stateful - configuration parameters such as IPv6 addresses or prefixes. + **Enable a stateless DHCPv6 client mode on this interface.** + + In stateless mode, the DHCPv6 client requests only stateless configuration + parameters from the DHCP server (for example, DNS server addresses). It + doesn’t request a stateful configuration, such as IPv6 addresses or prefixes. + + Example: .. code-block:: none @@ -37,8 +56,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options rapid-commit - When rapid-commit is specified, dhcp6c will include a rapid-commit option in - solicit messages and wait for an immediate reply instead of advertisements. + **Enable DHCPv6 rapid commit on this interface.** + + When enabled, the DHCP client and server skip the negotiation steps + (Advertise and Request), completing the DHCPv6 configuration process + in just two messages (Solicit and final Reply). + + Example: .. code-block:: none @@ -47,8 +71,14 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options temporary - Request only a temporary address and not form an IA_NA (Identity Association - for Non-temporary Addresses) partnership. + **Configure the DHCPv6 client to request a temporary IPv6 address on this + interface.** + + When configured, the DHCP client doesn’t form an Identity Association for + Non-temporary Addresses (IA_NA) partnership. Consequently, it only obtains + a temporary IPv6 address and doesn’t obtain a permanent one. + + Example: .. code-block:: none diff --git a/docs/_include/interface-dhcpv6-prefix-delegation.txt b/docs/_include/interface-dhcpv6-prefix-delegation.txt index c6564092..dacb63a5 100644 --- a/docs/_include/interface-dhcpv6-prefix-delegation.txt +++ b/docs/_include/interface-dhcpv6-prefix-delegation.txt @@ -1,20 +1,24 @@ **DHCPv6 Prefix Delegation (PD)** -VyOS 1.3 (equuleus) supports DHCPv6-PD (:rfc:`3633`). DHCPv6 Prefix Delegation -is supported by most ISPs who provide native IPv6 for consumers on fixed -networks. +VyOS supports DHCPv6 Prefix Delegation (DHCPv6-PD) as described in :rfc:`3633`. +DHCPv6-PD is supported by most ISPs that provide native IPv6 for consumers on +fixed networks. + .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options pd length - Some ISPs by default only delegate a /64 prefix. To request for a specific - prefix size use this option to request for a bigger delegation for this pd - ``. This value is in the range from 32 - 64 so you could request up to a - /32 prefix (if your ISP allows this) down to a /64 delegation. + **Configure a specific prefix length for DHCPv6-PD requests on this + interface.** + + Some ISPs provide only a /64 prefix by default. Use this command to + request a different prefix length for a specific DHCPv6-PD request, + ranging from /32 (if allowed by your ISP) down to /64. is a + unique identifier for the DHCPv6-PD request. - The default value corresponds to 64. + The default value is 64. - To request a /56 prefix from your ISP use: + To request a /56 prefix from your ISP, use: .. code-block:: none @@ -24,18 +28,23 @@ networks. {{ var5 }} {{ var6 }} dhcpv6-options pd interface address
- Specify the interface address used locally on the interface where the prefix - has been delegated to. ID must be a decimal integer. + **Configure the IPv6 interface identifier (host portion) for the delegatee + interface.** + + The value must be a decimal integer. It is appended to the delegated prefix + and the configured :abbr:`SLA ID (Site-Level Aggregation ID)` to form the + final IPv6 address. + + By default, the host portion is generated based on the parent interface's + MAC address (EUI-64 format). - It will be combined with the delegated prefix and the sla-id to form a - complete interface address. The default is to use the EUI-64 address of the - interface. + .. stop_vyoslinter - .. stop_vyoslinter + **Example:** - Example: Delegate a /64 prefix to interface eth8 which will use a local - address on this router of ``::ffff``, as the address 65534 will - correspond to ``ffff`` in hexadecimal notation. + If a /64 prefix is delegated to interface eth8 and you configure the host + portion as 65535, the resulting IPv6 address will end with ::ffff, as + 65535 corresponds to ffff in hexadecimal notation. .. start_vyoslinter @@ -47,16 +56,19 @@ networks. .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} dhcpv6-options pd interface sla-id - Specify the identifier value of the site-level aggregator (SLA) on the - interface. ID must be a decimal number greater then 0 which fits in the - length of SLA IDs (see below). + **Configure the** :abbr:`SLA ID (Site-Level Aggregation ID)` **for the + delegatee interface.** - Example: If ID is 1 and the client is delegated an IPv6 prefix - 2001:db8:ffff::/48, dhcp6c will combine the two values into a single IPv6 - prefix, 2001:db8:ffff:1::/64, and will configure the prefix on the specified - interface. + The value must be a decimal integer greater than 0 and fit in the length of + SLA IDs. It is converted to hexadecimal and appended to the delegated prefix + to form the specific subnet prefix for the delegatee interface. + + **Example:** + + If SLA ID is 1 and the delegated prefix is ``2001:db8:ffff::/48``, the + resulting subnet prefix for the delegatee interface will be + ``2001:db8:ffff:1::/64``. .. code-block:: none set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} {{ var5 }} {{ var7 }} dhcpv6-options pd 0 interface eth8 sla-id 1 - diff --git a/docs/_include/interface-disable-flow-control.txt b/docs/_include/interface-disable-flow-control.txt index 347f1145..67cd0a2b 100644 --- a/docs/_include/interface-disable-flow-control.txt +++ b/docs/_include/interface-disable-flow-control.txt @@ -1,20 +1,14 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} disable-flow-control - Ethernet flow control is a mechanism for temporarily stopping the transmission - of data on Ethernet family computer networks. The goal of this mechanism is to - ensure zero packet loss in the presence of network congestion. + **Disable Ethernet flow control (IEEE 802.3x pause frames) on the interface.** - The first flow control mechanism, the pause frame, was defined by the IEEE - 802.3x standard. + Ethernet flow control, defined by the IEEE 802.3x standard, temporarily stops + data transmission to prevent packet loss during network congestion. For + example, when a sender transmits data faster than the receiver can process it. - A sending station (computer or network switch) may be transmitting data faster - than the other end of the link can accept it. Using flow control, the - receiving station can signal the sender requesting suspension of - transmissions until the receiver catches up. - - Use this command to disable the generation of Ethernet flow control (pause - frames). + Disabling Ethernet flow control means the interface will not signal the + connected device to pause transmission and will drop packets if overwhelmed. Example: diff --git a/docs/_include/interface-disable-link-detect.txt b/docs/_include/interface-disable-link-detect.txt index 1a766715..194bbadd 100644 --- a/docs/_include/interface-disable-link-detect.txt +++ b/docs/_include/interface-disable-link-detect.txt @@ -1,10 +1,10 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} disable-link-detect - Use this command to direct an interface to not detect any physical state - changes on a link, for example, when the cable is unplugged. + **Disable physical link-state change detection on the interface, such as + when a cable is unplugged.** - Default is to detects physical link state changes. + By default, the interface detects physical link-state changes. Example: diff --git a/docs/_include/interface-disable.txt b/docs/_include/interface-disable.txt index 774c1cdd..a1b53517 100644 --- a/docs/_include/interface-disable.txt +++ b/docs/_include/interface-disable.txt @@ -1,7 +1,9 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} disable - Disable given ``. It will be placed in administratively down + **Disable the interface.** + + The interface will be set to the administratively down (``A/D``) state. Example: diff --git a/docs/_include/interface-evpn-uplink.txt b/docs/_include/interface-evpn-uplink.txt index 3495361d..84b09727 100644 --- a/docs/_include/interface-evpn-uplink.txt +++ b/docs/_include/interface-evpn-uplink.txt @@ -1,10 +1,12 @@ .. cfgcmd:: set interfaces {{ var0 }} evpn uplink - When all the underlay links go down the PE no longer has access - to the VxLAN +overlay. To prevent blackholing of traffic the - server/ES links are protodowned on the PE. + **Configure this interface as an EVPN-MH uplink interface.** - A link can be setup for uplink tracking via the following example: + If all uplink interfaces on a PE device go down, this PE device loses access + to the VXLAN overlay. To prevent traffic blackholing, the PE device forces a + protocol shutdown (protodown) of its downstream EVPN-MH interfaces. + + The following example configures bond0 as an EVPN-MH uplink interface: .. code-block:: none diff --git a/docs/_include/interface-ip.txt b/docs/_include/interface-ip.txt index 5163edd8..7965115d 100644 --- a/docs/_include/interface-ip.txt +++ b/docs/_include/interface-ip.txt @@ -1,28 +1,34 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ip adjust-mss - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. + **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing + TCP SYN packets on the specified interface.** - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface adjust-mss `` + By clamping the MSS value in TCP SYN packets, you explicitly inform the + remote side not to send packets larger than that size. This prevents + connection issues that occur when Path MTU Discovery (PMTUD) fails. - .. hint:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in - 1452 bytes on a 1492 byte MTU. + The following options are available: + + * **mss:** Sets the MSS to a specific value, in bytes. Use this option if + you need to enforce a specific MSS, for example, to troubleshoot + connectivity issues or accommodate specific network requirements. + * **clamp-mss-to-pmtu:** The router automatically calculates the MSS to be + the interface's MTU minus 40 bytes for IPv4 traffic (20 bytes for the IPv4 + header and 20 bytes for the TCP header). This option is recommended to + automatically set the proper value. - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. .. cfgcmd:: set interfaces {{ var0 }} {{ 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 specific time. An entry's validity will be extended if it - receives positive feedback from higher level protocols. + **Configure how long an ARP entry remains valid after learning an IP-to-MAC + address mapping on this interface.** + + The default duration is 30 seconds. - This defaults to 30 seconds. + An ARP entry remains valid if it receives positive feedback from + higher-level protocols. Example: @@ -33,19 +39,17 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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. + **Configure ARP filtering on this interface.** - 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). + **Default behavior:** The kernel responds to ARP requests on this interface + only if the traffic would be routed back to the ARP sender through that + specific interface. - In other words it allows control of which cards (usually 1) will respond to an - arp request. + **If configured:** The kernel responds to ARP requests on this interface for any + IP address configured on the local host, regardless of which specific interface + that IP address is assigned to, and regardless of the routing table. This + reflects the Linux concept that IP addresses belong to the host, not individual + interfaces. Example: @@ -56,8 +60,12 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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. + **Configure the interface for host or router behavior.** + + If configured, the interface switches to host mode, and IPv4 forwarding is + disabled on it. + + Example: .. code-block:: none @@ -66,14 +74,15 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ip enable-directed-broadcast - Define different modes for IP directed broadcast forwarding as described in - :rfc:`1812` and :rfc:`2644`. + **Configure whether to forward IP-directed broadcast packets received on this + interface.** + + **Default behavior:** IP-directed broadcast packets are dropped. - If configured, incoming IP directed broadcast packets on this interface will - be forwarded. + **If configured:** IP-directed broadcast packets are forwarded to all hosts + on the destination subnet, as defined in :rfc:`1812` and :rfc:`2644`. - If this option is unset (default), incoming IP directed broadcast packets - will not be forwarded. + Example: .. code-block:: none @@ -82,14 +91,15 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ip enable-arp-accept - Define behavior for gratuitous ARP frames whose IP is not already present in - the ARP table. If configured create new entries in the ARP table. + **Configure how to process gratuitous ARPs on this interface.** + + If configured, an IP-to-MAC address mapping is added to the ARP table based + on gratuitous ARP requests or replies. - Both replies and requests type gratuitous arp will trigger the ARP table to be - updated, if this setting is on. + .. note:: If the ARP table already contains the IP address from a gratuitous + ARP, its entry is updated regardless of whether this setting is configured. - 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. + Example: .. code-block:: none @@ -98,18 +108,18 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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. + **Configure the source IP selection for ARP requests on this interface.** - Use any local address, configured on any interface if this is not set. + **Default behavior:** The kernel can use any IP address the host owns as + the source IP address in ARP requests on this interface. - 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. + **If configured:** The kernel first attempts to select a source IP address + configured on the interface that shares a common subnet with the target + IP address. If there is no such subnet, the kernel selects the IP address + it would normally use (based on the routing table to reach the target + destination). + + Example: .. code-block:: none @@ -118,14 +128,15 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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: + **Configure which ARP requests will be ignored on this interface.** + + **Default behavior:** The kernel responds to ARP requests for any local + IP addresses, regardless of which interface they are assigned to. - If configured, reply only if the target IP address is local address configured - on the incoming interface. + **If configured:** The kernel responds to ARP requests only if the target + IP address is assigned to this specific interface. - If this option is unset (default), reply for any local target IP address, - configured on any interface. + Example: .. code-block:: none @@ -134,12 +145,13 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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. + **Configure proxy ARP on this interface.** + + If configured, the router (kernel) intercepts ARP requests for non-local IP + addresses and replies with the :abbr:`MAC (Media Access Control)` address + of the interface that received the request. Subsequent packets destined + to these IP addresses are forwarded to their actual destinations on remote + subnets. Example: @@ -150,41 +162,53 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ 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). + **Configure local proxy ARP on the interface.** - 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. + If configured, the router (kernel) responds to ARP requests on this VLAN + interface even if the target IP address resides on the same subnet and + interface. - .. note:: Does not need to be used together with proxy_arp. + This is used to support network isolation requirements (RFC 3069) for private + VLANs (PVLANs). In PVLAN configurations, hosts on isolated ports are NOT + allowed to communicate directly with each other at Layer 2, but they can + communicate with the upstream router. - This technology is known by different names: + By replying to inter-host ARP requests with its own :abbr:`MAC (Media Access Control)` + address, the router (kernel) directs inter-host traffic through itself instead of + directly between hosts. - - In :rfc:`3069` it is called VLAN Aggregation + .. note:: This command works independently and does not require enabling + the standard proxy ARP on the interface. - - Cisco and Allied Telesyn call it Private VLAN + Local proxy ARP is also known as: - - Hewlett-Packard call it Source-Port filtering or port-isolation + - VLAN aggregation (:rfc:`3069`). - - Ericsson call it MAC-Forced Forwarding (RFC Draft) + - Private VLAN (Cisco, Allied Telesyn). + + - Source-port filtering or port isolation (Hewlett-Packard). + + - MAC-Forced Forwarding (Ericsson). .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ip source-validation - 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. + **Configure source IP address validation using** :abbr:`RPF (Reverse Path + Forwarding)` **on this interface, as specified in** :rfc:`3704`. + + The following options are available: + + - **strict:** Each incoming packet’s source IP address is checked against the + Forwarding Information Base (FIB). If the interface is not the best route + back to that source, validation fails, and the packet is dropped. - - 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 IP address is checked against the + FIB. If the source IP address is unreachable through any interface, validation + fails. - - 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 IP address validation is performed. All incoming + packets are accepted. - - disable: No source validation + RFC 3704 recommends enabling strict mode to prevent IP spoofing, such as + DDoS attacks. For asymmetric or other complex routing scenarios, use loose + mode. diff --git a/docs/_include/interface-ipv6.txt b/docs/_include/interface-ipv6.txt index 0c222d80..a122ae1a 100644 --- a/docs/_include/interface-ipv6.txt +++ b/docs/_include/interface-ipv6.txt @@ -1,16 +1,20 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 address autoconf - :abbr:`SLAAC (Stateless Address Autoconfiguration)` :rfc:`4862`. IPv6 hosts - can configure themselves automatically when connected to an IPv6 network using - the Neighbor Discovery Protocol via :abbr:`ICMPv6 (Internet Control Message - Protocol version 6)` router discovery messages. When first connected to a - network, a host sends a link-local router solicitation multicast request for - its configuration parameters; routers respond to such a request with a router - advertisement packet that contains Internet Layer configuration parameters. + **Configure the interface to automatically obtain an IPv6 address using** + :abbr:`SLAAC (Stateless Address Autoconfiguration)`, **as specified in** + :rfc:`4862`. - .. note:: This method automatically disables IPv6 traffic forwarding on the - interface in question. + + IPv6 hosts can configure themselves automatically when connected to an + IPv6 network using the Neighbor Discovery Protocol via ICMPv6 router + discovery messages. When first connected to a network, a host sends a + link-local router solicitation multicast request for its configuration + parameters. The router responds with a router advertisement packet + containing Internet Layer configuration parameters. + + .. note:: This method automatically disables IPv6 traffic forwarding + on the interface. Example: @@ -22,8 +26,9 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 address eui64 - :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in - :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. + **Configure the interface to assign itself an IPv6 address using the** + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` **method, as + specified** in :rfc:`4291`. Example: @@ -34,7 +39,8 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 address no-default-link-local - Do not assign a link-local IPv6 address to this interface. + **Disable the automatic assignment of a link-local IPv6 address to + this interface.** Example: @@ -45,8 +51,10 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 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. + **Configure the interface for host or router behavior.** + + If configured, the interface switches to host mode, and IPv6 forwarding is + disabled on it. Example: @@ -57,28 +65,36 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 adjust-mss - As Internet wide PMTU discovery rarely works, we sometimes need to clamp our - TCP MSS value to a specific value. This is a field in the TCP options part of - a SYN packet. By setting the MSS value, you are telling the remote side - unequivocally 'do not try to send me packets bigger than this value'. + **Configure the** :abbr:`MSS (Maximum Segment Size)` **advertised in outgoing + TCP SYN packets on the specified interface.** - .. note:: This command was introduced in VyOS 1.4 - it was previously called: - ``set firewall options interface adjust-mss6 `` + By clamping the MSS value in TCP SYN packets, you explicitly inform + the remote side not to send packets larger than that size. This prevents + connection issues when Path MTU Discovery (PMTUD) fails. - .. hint:: MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in - 1432 bytes on a 1492 byte MTU. + The following options are available: - Instead of a numerical MSS value `clamp-mss-to-pmtu` can be used to - automatically set the proper value. + * **mss:** Set the MSS to a specific value, in bytes. Use this option to + enforce a specific MSS, for example, to troubleshoot connectivity issues + or accommodate specific network requirements. + * **clamp-mss-to-pmtu:** The router calculates the MSS to be the interface's + MTU minus 60 bytes for IPv6 traffic (40 bytes for the IPv6 header and 20 + bytes for the TCP header). This option is recommended to automatically + set the proper value. .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} - {{ var5 }} {{ var6 }} ipv6 accept-dad <1-3> + {{ var5 }} {{ var6 }} ipv6 accept-dad <0 | 1 | 2> + + **Configure IPv6** :abbr:`DAD (Duplicate Address Detection)` **on the + interface.** - Whether to accept DAD (Duplicate Address Detection). + The following options are available: - - 0: Disable DAD - - 1: Enable DAD (default) - - 2: Enable DAD, and disable IPv6 operation if MAC-based duplicate link-local address has been found. + - **0:** Disables DAD. No duplicate address detection is performed. + - **1:** Enables DAD (default). Duplicate addresses are detected. The + interface's IPv6 operation continues for valid IPv6 addresses. + - **2:** Enables DAD and, if a MAC-based duplicate link-local address + is found, disables IPv6 operation on this interface. Example: @@ -89,9 +105,11 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} ipv6 dup-addr-detect-transmits - The amount of Duplicate Address Detection probes to send. + **Configure the number of** :abbr:`DAD (Duplicate Address Detection)` + **messages that the router (kernel) sends during IPv6 address assignment + on this interface.** - Default: 1 + The default value is 1. Example: diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt index 9c8c7de5..b8c84653 100644 --- a/docs/_include/interface-mac.txt +++ b/docs/_include/interface-mac.txt @@ -1,8 +1,7 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} mac - Configure user defined :abbr:`MAC (Media Access Control)` address on given - ``. + **Configure a custom MAC address on the interface.** Example: diff --git a/docs/_include/interface-mirror.txt b/docs/_include/interface-mirror.txt index 26594984..06a42ca5 100644 --- a/docs/_include/interface-mirror.txt +++ b/docs/_include/interface-mirror.txt @@ -1,22 +1,26 @@ -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 a behavior control system, intrusion detection system or -traffic collector, and can copy all related traffic from this port. -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. - -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. +:abbr:`SPAN (Switched Port Analyser)` port mirroring copies inbound and +outbound traffic from one interface to another specified interface. + +The destination interface is usually connected to specialized equipment, +such as a behavior control system, an intrusion detection system, or +a traffic collector, and copies all related traffic from this port. The +benefit of mirroring traffic is that the application is isolated from the +source traffic, so application processing does not affect the traffic or +system performance. + +To configure :abbr:`SPAN (Switched Port Analyser)` port mirroring, VyOS uses +the ``mirror`` parameter. You can mirror ingress traffic (traffic entering the +router) and egress traffic (traffic leaving the router) separately. Both +directions can be mirrored to the same destination interface or split to +different ones. .. cfgcmd:: set interfaces {{ var0 }} mirror ingress - Configure port mirroring for `interface` inbound traffic and copy the - traffic to `monitor-interface` - - Example: Mirror the inbound traffic of `{{ var1 }}` port to `{{ var2 }}` + **Mirror ingress traffic from a bonding interface to the specified monitoring + interface.** + + Example: Mirror the ingress traffic from `{{ var1 }}` to `{{ var2 }}`. .. code-block:: none @@ -25,10 +29,11 @@ for different traffic directions. .. cfgcmd:: set interfaces {{ var0 }} mirror egress - Configure port mirroring for `interface` outbound traffic and copy the - traffic to `monitor-interface` + **Mirror egress traffic from a bonding interface to the specified monitoring + interface.** + - Example: Mirror the outbound traffic of `{{ var1 }}` port to `{{ var2 }}` + Example: Mirror the egress traffic from `{{ var1 }}` to `{{ var2 }}`. .. code-block:: none diff --git a/docs/_include/interface-mtu.txt b/docs/_include/interface-mtu.txt index f3666179..a67a2d8c 100644 --- a/docs/_include/interface-mtu.txt +++ b/docs/_include/interface-mtu.txt @@ -1,8 +1,10 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} mtu - Configure :abbr:`MTU (Maximum Transmission Unit)` on given ``. It - is the size (in bytes) of the largest ethernet frame sent on this link. + **Configure the MTU on the interface.** + + This value defines the largest packet size, in bytes, that the interface + transmits without fragmentation. Example: diff --git a/docs/_include/interface-vlan-8021q.txt b/docs/_include/interface-vlan-8021q.txt index 1a527590..1a7a665f 100644 --- a/docs/_include/interface-vlan-8021q.txt +++ b/docs/_include/interface-vlan-8021q.txt @@ -1,33 +1,29 @@ -IEEE 802.1q_, often referred to as Dot1q, is the networking standard that -supports virtual LANs (VLANs) on an IEEE 802.3 Ethernet network. The standard -defines a system of VLAN tagging for Ethernet frames and the accompanying -procedures to be used by bridges and switches in handling such frames. -The standard also contains provisions for a quality-of-service prioritization -scheme commonly known as IEEE 802.1p and defines the -Generic Attribute Registration Protocol. - -Portions of the network which are VLAN-aware (i.e., IEEE 802.1q_ conformant) can -include VLAN tags. When a frame enters the VLAN-aware portion of the network, a -tag is added to represent the VLAN membership. Each frame must be -distinguishable as being within exactly one VLAN. A frame in the VLAN-aware -portion of the network that does not contain a VLAN tag is assumed to be -flowing on the native VLAN. - -The standard was developed by IEEE 802.1, a working group of the IEEE 802 -standards committee, and continues to be actively revised. One of the notable -revisions is 802.1Q-2014 which incorporated IEEE 802.1aq -(Shortest Path Bridging) and much of the IEEE 802.1d standard. - -802.1q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The -term used for this is ``vif``. +IEEE 802.1q_, often referred to as Dot1q, is the industry standard for +implementing VLANs on Ethernet networks. It defines VLAN tagging for +Ethernet frames and outlines procedures for bridges and switches. The +standard also includes quality-of-service prioritization (IEEE 802.1p) +and defines the Generic Attribute Registration Protocol. + +VLAN-aware network segments (i.e., IEEE 802.1q_ conformant) use VLAN tags. +When a frame enters such a segment, a tag is added to indicate VLAN membership. +Each frame can belong to only one VLAN. If a frame arrives without a tag, it +is assumed to be part of the native VLAN. + +IEEE 802.1, a working group of the IEEE 802 standards committee, has developed +the standard and continues to revise it. One notable revision is 802.1Q-2014, +which incorporated IEEE 802.1aq (Shortest Path Bridging) and much of the IEEE +802.1d standard. + +In VyOS, 802.1q VLAN interfaces are represented as virtual subinterfaces, +referred to as ``vif``. .. cfgcmd:: set interfaces {{ var0 }} vif - Create a new VLAN interface on interface `` using the VLAN number - provided via ``. + **Configure a VLAN interface with a unique VLAN ID.** + + VLAN ID identifies a specific VLAN and ranges from 0 to 4094. - You can create multiple VLAN interfaces on a physical interface. The VLAN ID - range is from 0 to 4094. + You can configure multiple VLAN interfaces on a single physical interface. .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. diff --git a/docs/_include/interface-vrf.txt b/docs/_include/interface-vrf.txt index 1fa94f9f..f6dfe47c 100644 --- a/docs/_include/interface-vrf.txt +++ b/docs/_include/interface-vrf.txt @@ -1,10 +1,11 @@ .. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} {{ var5 }} {{ var6 }} vrf - Place interface in given VRF instance. + **Assign the interface to a specific** :abbr:`VRF (Virtual Routing and + Forwarding)` **instance.** - .. seealso:: There is an entire chapter about how to configure a :ref:`vrf`, - please check this for additional information. + .. seealso:: For information on configuring a VRF, refer to the :ref:`vrf` + section. Example: -- cgit v1.2.3