summaryrefslogtreecommitdiff
path: root/docs/_include
diff options
context:
space:
mode:
Diffstat (limited to 'docs/_include')
-rw-r--r--docs/_include/interface-address-with-dhcp.txt26
-rw-r--r--docs/_include/interface-description.txt8
-rw-r--r--docs/_include/interface-dhcp-options.txt59
-rw-r--r--docs/_include/interface-dhcpv6-options.txt60
-rw-r--r--docs/_include/interface-dhcpv6-prefix-delegation.txt64
-rw-r--r--docs/_include/interface-disable-flow-control.txt18
-rw-r--r--docs/_include/interface-disable-link-detect.txt6
-rw-r--r--docs/_include/interface-disable.txt4
-rw-r--r--docs/_include/interface-evpn-uplink.txt10
-rw-r--r--docs/_include/interface-ip.txt194
-rw-r--r--docs/_include/interface-ipv6.txt80
-rw-r--r--docs/_include/interface-mac.txt3
-rw-r--r--docs/_include/interface-mirror.txt41
-rw-r--r--docs/_include/interface-mtu.txt6
-rw-r--r--docs/_include/interface-vlan-8021q.txt48
-rw-r--r--docs/_include/interface-vrf.txt7
16 files changed, 366 insertions, 268 deletions
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 <address | dhcp |
dhcpv6>
- Configure interface `<interface>` with one or more interface addresses.
-
- * **address** can be specified multiple times as IPv4 and/or IPv6
- address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
- * **dhcp** interface address is received by DHCP from a DHCP server
- on this segment.
- * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
- server on this segment.
-
- .. 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} description <description>
- Set a human readable, descriptive alias for this connection. Alias is used by
- e.g. the :opcmd:`show interfaces` command or SNMP based monitoring tools.
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options client-id <description>
- :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 ``<description>`` 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options host-name <hostname>
- 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options vendor-class-id <vendor-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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options default-route-distance <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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options reject <address>
- 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcp-options user-class <string>
- 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcpv6-options duid <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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcpv6-options pd <id> length <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
- `<id>`. 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. <id> 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 <id> interface <delegatee>
address <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 ``<prefix>::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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} dhcpv6-options pd <id> interface <delegatee> sla-id <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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} disable
- Disable given `<interface>`. 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 }} <interface> 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip adjust-mss <mss | clamp-mss-to-pmtu>
- 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 <name> adjust-mss <value>``
+ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip arp-cache-timeout
- Once a neighbor has been found, the entry is considered to be valid for at
- least for this 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip disable-arp-filter
- If set the kernel can respond to arp requests with addresses from other
- interfaces. This may seem wrong but it usually makes sense, because it
- increases the chance of successful communication. IP addresses are owned by
- the complete host on Linux, not by particular interfaces. Only for more
- complex setups like load-balancing, does this behaviour cause problems.
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip disable-forwarding
- Configure interface-specific Host/Router behaviour. If set, the interface will
- switch to host mode and IPv6 forwarding will be disabled on this interface.
+ **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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip enable-arp-announce
- Define different restriction levels for announcing the local source IP address
- from IP packets in ARP requests sent on interface.
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip enable-arp-ignore
- Define different modes for sending replies in response to received ARP
- requests that resolve local target IP addresses:
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip enable-proxy-arp
- Use this command to enable proxy Address Resolution Protocol (ARP) on this
- interface. Proxy ARP allows an Ethernet interface to respond with its own
- :abbr:`MAC (Media Access Control)` address to ARP requests for destination IP
- addresses on subnets attached to other interfaces on the system. Subsequent
- packets sent to those destination IP addresses are forwarded appropriately by
- the system.
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip proxy-arp-pvlan
- Private VLAN proxy arp. Basically allow proxy arp replies back to the same
- interface (from which the ARP request/solicitation was received).
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ip source-validation <strict | loose | disable>
- Enable policy for source validation by reversed path, as specified in
- :rfc:`3704`. Current recommended practice in :rfc:`3704` is to enable strict
- mode to prevent IP spoofing from DDos attacks. If using asymmetric routing
- or other complicated routing, then loose mode is recommended.
+ **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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ipv6 address eui64 <prefix>
- :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 }} <interface> {{ 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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ipv6 adjust-mss <mss | clamp-mss-to-pmtu>
- 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 <name> adjust-mss6 <value>``
+ 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 }} <interface> {{ 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} ipv6 dup-addr-detect-transmits <n>
- 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} mac <xx:xx:xx:xx:xx:xx>
- Configure user defined :abbr:`MAC (Media Access Control)` address on given
- `<interface>`.
+ **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 }} <interface> mirror
ingress <monitor-interface>
- 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 }} <interface> mirror egress
<monitor-interface>
- 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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} mtu <mtu>
- Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. 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 }} <interface> vif <vlan-id>
- Create a new VLAN interface on interface `<interface>` using the VLAN number
- provided via `<vlan-id>`.
+ **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 }} <interface> {{ var2 }} {{ var3 }}
{{ var5 }} {{ var6 }} vrf <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:
generated by cgit v1.2.3 (git 2.39.1) at 2026-07-14 16:47:54 +0000