diff options
Diffstat (limited to 'docs')
42 files changed, 994 insertions, 517 deletions
diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index 4ee87d63..e42d4cf0 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -1,6 +1,10 @@ -from docutils import nodes, utils +import re +import io +import os +from docutils import io, nodes, utils, statemachine +from docutils.utils.error_reporting import SafeString, ErrorString from docutils.parsers.rst.roles import set_classes -from docutils.parsers.rst import Directive +from docutils.parsers.rst import Directive, directives from sphinx.util.docutils import SphinxDirective @@ -49,6 +53,7 @@ def setup(app): app.add_directive('cfgcmd', CfgCmdDirective) app.add_directive('opcmd', OpCmdDirective) + app.add_directive('cmdinclude', CfgInclude) app.connect('doctree-resolved', process_cmd_nodes) @@ -148,6 +153,156 @@ class inlinecmd(nodes.inline): #self.literal_whitespace -= 1 +class CfgInclude(Directive): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'var0': str, + 'var1': str, + 'var2': str, + 'var3': str, + 'var4': str, + 'var5': str, + 'var6': str, + 'var7': str, + 'var8': str, + 'var9': str + } + + def run(self): + ### Copy from include directive docutils + """Include a file as part of the content of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + source = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = os.path.dirname(os.path.abspath(source)) + path = directives.path(self.arguments[0]) + if path.startswith('<') and path.endswith('>'): + path = os.path.join(self.standard_include_path, path[1:-1]) + path = os.path.normpath(os.path.join(source_dir, path)) + path = utils.relative_path(None, path) + path = nodes.reprunicode(path) + encoding = self.options.get( + 'encoding', self.state.document.settings.input_encoding) + e_handler=self.state.document.settings.input_encoding_error_handler + tab_width = self.options.get( + 'tab-width', self.state.document.settings.tab_width) + try: + self.state.document.settings.record_dependencies.add(path) + include_file = io.FileInput(source_path=path, + encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError: + raise self.severe(u'Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError: + raise self.severe(u'Problems with "%s" directive path.' % + (self.name)) + startline = self.options.get('start-line', None) + endline = self.options.get('end-line', None) + try: + if startline or (endline is not None): + lines = include_file.readlines() + rawtext = ''.join(lines[startline:endline]) + else: + rawtext = include_file.read() + except UnicodeError: + raise self.severe(u'Problem with "%s" directive:\n%s' % + (self.name, ErrorString(error))) + # start-after/end-before: no restrictions on newlines in match-text, + # and no restrictions on matching inside lines vs. line boundaries + after_text = self.options.get('start-after', None) + if after_text: + # skip content in rawtext before *and incl.* a matching text + after_index = rawtext.find(after_text) + if after_index < 0: + raise self.severe('Problem with "start-after" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[after_index + len(after_text):] + before_text = self.options.get('end-before', None) + if before_text: + # skip content in rawtext after *and incl.* a matching text + before_index = rawtext.find(before_text) + if before_index < 0: + raise self.severe('Problem with "end-before" option of "%s" ' + 'directive:\nText not found.' % self.name) + rawtext = rawtext[:before_index] + + include_lines = statemachine.string2lines(rawtext, tab_width, + convert_whitespace=True) + if 'literal' in self.options: + # Convert tabs to spaces, if `tab_width` is positive. + if tab_width >= 0: + text = rawtext.expandtabs(tab_width) + else: + text = rawtext + literal_block = nodes.literal_block(rawtext, source=path, + classes=self.options.get('class', [])) + literal_block.line = 1 + self.add_name(literal_block) + if 'number-lines' in self.options: + try: + startline = int(self.options['number-lines'] or 1) + except ValueError: + raise self.error(':number-lines: with non-integer ' + 'start value') + endline = startline + len(include_lines) + if text.endswith('\n'): + text = text[:-1] + tokens = NumberLines([([], text)], startline, endline) + for classes, value in tokens: + if classes: + literal_block += nodes.inline(value, value, + classes=classes) + else: + literal_block += nodes.Text(value, value) + else: + literal_block += nodes.Text(text, text) + return [literal_block] + if 'code' in self.options: + self.options['source'] = path + codeblock = CodeBlock(self.name, + [self.options.pop('code')], # arguments + self.options, + include_lines, # content + self.lineno, + self.content_offset, + self.block_text, + self.state, + self.state_machine) + return codeblock.run() + + new_include_lines = [] + var_value0 = self.options.get('var0', '') + var_value1 = self.options.get('var1', '') + var_value2 = self.options.get('var2', '') + var_value3 = self.options.get('var3', '') + var_value4 = self.options.get('var4', '') + var_value5 = self.options.get('var5', '') + var_value6 = self.options.get('var6', '') + var_value7 = self.options.get('var7', '') + var_value8 = self.options.get('var8', '') + var_value9 = self.options.get('var9', '') + for line in include_lines: + line = re.sub('{{\s?var0\s?}}',var_value0,line) + line = re.sub('{{\s?var1\s?}}',var_value1,line) + line = re.sub('{{\s?var2\s?}}',var_value2,line) + line = re.sub('{{\s?var3\s?}}',var_value3,line) + line = re.sub('{{\s?var4\s?}}',var_value4,line) + line = re.sub('{{\s?var5\s?}}',var_value5,line) + line = re.sub('{{\s?var6\s?}}',var_value6,line) + line = re.sub('{{\s?var7\s?}}',var_value7,line) + line = re.sub('{{\s?var8\s?}}',var_value8,line) + line = re.sub('{{\s?var9\s?}}',var_value9,line) + new_include_lines.append(line) + self.state_machine.insert_input(new_include_lines, path) + return [] + + class CfgcmdlistDirective(Directive): def run(self): diff --git a/docs/_include/interface-address-with-dhcp.txt b/docs/_include/interface-address-with-dhcp.txt new file mode 100644 index 00000000..10838e72 --- /dev/null +++ b/docs/_include/interface-address-with-dhcp.txt @@ -0,0 +1,20 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::1/64 + set interfaces {{ var0 }} {{ var1 }} dhcp + set interfaces {{ var0 }} {{ var1 }} dhcpv6
\ No newline at end of file diff --git a/docs/_include/interface-address.txt b/docs/_include/interface-address.txt new file mode 100644 index 00000000..00a9ec09 --- /dev/null +++ b/docs/_include/interface-address.txt @@ -0,0 +1,14 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::1/64
\ No newline at end of file diff --git a/docs/_include/interface-common-with-dhcp.txt b/docs/_include/interface-common-with-dhcp.txt new file mode 100644 index 00000000..3e1394a3 --- /dev/null +++ b/docs/_include/interface-common-with-dhcp.txt @@ -0,0 +1,17 @@ +.. cmdinclude:: ../_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-common.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +**DHCP(v6)** + +.. cmdinclude:: ../_include/interface-dhcp-options.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. 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 new file mode 100644 index 00000000..d861f003 --- /dev/null +++ b/docs/_include/interface-common-without-dhcp.txt @@ -0,0 +1,7 @@ +.. cmdinclude:: ../_include/interface-address.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-common.txt + :var0: {{ var0 }} + :var1: {{ var1 }} diff --git a/docs/_include/interface-common.txt b/docs/_include/interface-common.txt new file mode 100644 index 00000000..de29356f --- /dev/null +++ b/docs/_include/interface-common.txt @@ -0,0 +1,36 @@ +.. cmdinclude:: ../_include/interface-description.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-disable.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-disable-flow-control.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-disable-link-detect.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-mac.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-mtu.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-ipv6-addr-autoconf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-ipv6-addr-eui64.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + diff --git a/docs/_include/interface-description.txt b/docs/_include/interface-description.txt new file mode 100644 index 00000000..1c6a870f --- /dev/null +++ b/docs/_include/interface-description.txt @@ -0,0 +1,10 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> description <description> + + Set a human readable, descriptive alias for this connection. Alias is used by + e.g. the :opcmd:`show interfaces` command or SNMP based monitoring tools. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} description 'This is an awesome interface running on VyOS'
\ No newline at end of file diff --git a/docs/_include/interface-dhcp-options.txt b/docs/_include/interface-dhcp-options.txt new file mode 100644 index 00000000..da1975fc --- /dev/null +++ b/docs/_include/interface-dhcp-options.txt @@ -0,0 +1,46 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcp-options client-id 'foo-bar' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcp-options host-name <hostname> + + Instead of sending the real system hostname to the DHCP server, overwrite the + host-name with this given-value. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcp-options host-name 'VyOS' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcp-options vendor-class-id <vendor-id> + + The vendor-class-id option can be used to request a specific class of vendor + options from the server. + + Example + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcp-options vendor-class-id 'VyOS' + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcp-options no-default-route + + Only request an address from the DHCP server but do not request a default + gateway. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcp-options no-default-route diff --git a/docs/_include/interface-dhcpv6-options.txt b/docs/_include/interface-dhcpv6-options.txt new file mode 100644 index 00000000..94e80309 --- /dev/null +++ b/docs/_include/interface-dhcpv6-options.txt @@ -0,0 +1,38 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-options parameters-only + +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-options rapid-commit + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcpv6-options temporary + + Request only a temporary address and not form an IA_NA (Identity Association + for Non-temporary Addresses) partnership. + + Example + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-options temporary + +.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt + :var0: {{ var0 }} + :var1: {{ var1 }} diff --git a/docs/_include/interface-dhcpv6-prefix-delegation.txt b/docs/_include/interface-dhcpv6-prefix-delegation.txt new file mode 100644 index 00000000..61e6aaa2 --- /dev/null +++ b/docs/_include/interface-dhcpv6-prefix-delegation.txt @@ -0,0 +1,54 @@ +**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. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcpv6-option 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. + + The default value corresponds to 64. + + Example: + + To request a /56 prefix from your ISP use: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-options pd 0 length 56 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcpv6-option pd <id> interface <delegatee> address <address> + + Specify the interface address used locally on the interfcae where the prefix + has been delegated to. ID must be a decimal integer. + + 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. + + Example: Delegate a /64 prefix to interface eth0.10 which will use a local + address on this router of ``<prefix>::ffff``, as the address 65534 will + correspond to ``ffff`` in hexadecimal notation. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-option pd 0 interface eth0.10 address 65534 + +.. cfgcmd:: set interfaces {{ var0 }} <interface> dhcpv6-option 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). + + 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. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} dhcpv6-option pd 0 interface eth0.10 sla-id 1 + diff --git a/docs/_include/interface-disable-flow-control.txt b/docs/_include/interface-disable-flow-control.txt new file mode 100644 index 00000000..2b319b22 --- /dev/null +++ b/docs/_include/interface-disable-flow-control.txt @@ -0,0 +1,22 @@ +.. 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. + + The first flow control mechanism, the pause frame, was defined by the IEEE + 802.3x standard. + + 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). + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} disable-flow-control
\ No newline at end of file diff --git a/docs/_include/interface-disable-link-detect.txt b/docs/_include/interface-disable-link-detect.txt new file mode 100644 index 00000000..a9c0e85f --- /dev/null +++ b/docs/_include/interface-disable-link-detect.txt @@ -0,0 +1,12 @@ +.. cfgcmd:: set interfaces {{ var0 }} {{ var2 }} {{ var3 }} <interface> 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. + + Default is to detects physical link state changes. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} {{ var2 }} {{ var4 }} disable-link-detect
\ No newline at end of file diff --git a/docs/_include/interface-disable.txt b/docs/_include/interface-disable.txt new file mode 100644 index 00000000..83ef3e53 --- /dev/null +++ b/docs/_include/interface-disable.txt @@ -0,0 +1,10 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} disable
\ No newline at end of file diff --git a/docs/_include/interface-ipv6-addr-autoconf.txt b/docs/_include/interface-ipv6-addr-autoconf.txt new file mode 100644 index 00000000..e16cff0e --- /dev/null +++ b/docs/_include/interface-ipv6-addr-autoconf.txt @@ -0,0 +1,18 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} ipv6 address autoconf diff --git a/docs/_include/interface-ipv6-addr-eui64.txt b/docs/_include/interface-ipv6-addr-eui64.txt new file mode 100644 index 00000000..5f32ccad --- /dev/null +++ b/docs/_include/interface-ipv6-addr-eui64.txt @@ -0,0 +1,8 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} ipv6 address eui64 2001:db8:beef::/64 diff --git a/docs/_include/interface-mac.txt b/docs/_include/interface-mac.txt new file mode 100644 index 00000000..de7f2d83 --- /dev/null +++ b/docs/_include/interface-mac.txt @@ -0,0 +1,10 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> mac <xx:xx:xx:xx:xx:xx> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mac '00:01:02:03:04:05'
\ No newline at end of file diff --git a/docs/_include/interface-mtu.txt b/docs/_include/interface-mtu.txt new file mode 100644 index 00000000..e727c3e9 --- /dev/null +++ b/docs/_include/interface-mtu.txt @@ -0,0 +1,10 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> 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. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} mtu 1450
\ No newline at end of file diff --git a/docs/_include/interface-vlan.txt b/docs/_include/interface-vlan.txt new file mode 100644 index 00000000..c1472018 --- /dev/null +++ b/docs/_include/interface-vlan.txt @@ -0,0 +1,50 @@ +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``. + +.. cfgcmd:: set interfaces {{ var0 }} <interface> vif <vlan-id> + + Create a new VLAN interface on interface `<interface>` using the VLAN number + provided via `<vlan-id>`. + + You can create multiple VLAN interfaces on a physical interface. The VLAN ID + range is from 0 to 4094. + + .. note:: Only 802.1Q-tagged packets are accepted on Ethernet vifs. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} vif 10 + +.. cmdinclude:: ../_include/interface-address-with-dhcp.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10 + +.. cmdinclude:: ../_include/interface-common.txt + :var0: {{ var0 }} + :var1: {{ var1 }} + :var2: vif + :var3: <vlan-id> + :var4: 10
\ No newline at end of file diff --git a/docs/_include/interface-vrf.txt b/docs/_include/interface-vrf.txt new file mode 100644 index 00000000..92bfae93 --- /dev/null +++ b/docs/_include/interface-vrf.txt @@ -0,0 +1,12 @@ +.. cfgcmd:: set interfaces {{ var0 }} <interface> vrf <vrf> + + Place interface in given VRF instance. + + .. seealso:: There is an entire chapter about how to configure a :ref:`vrf`, + please check this for additional information. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} vrf red
\ No newline at end of file diff --git a/docs/_static/images/Wan_load_balancing1.png b/docs/_static/images/Wan_load_balancing1.png Binary files differnew file mode 100644 index 00000000..bde1edb6 --- /dev/null +++ b/docs/_static/images/Wan_load_balancing1.png diff --git a/docs/_static/images/Wan_load_balancing_exclude1.png b/docs/_static/images/Wan_load_balancing_exclude1.png Binary files differnew file mode 100644 index 00000000..1111535d --- /dev/null +++ b/docs/_static/images/Wan_load_balancing_exclude1.png diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst index ca3a6251..58251378 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -3,7 +3,7 @@ Configuration Blueprints ======================== -This chapter contains various configuration Examples +This chapter contains various configuration examples: .. toctree:: @@ -18,3 +18,4 @@ This chapter contains various configuration Examples azure-vpn-dual-bgp tunnelbroker-ipv6 ha + wan-load-balancing diff --git a/docs/appendix/examples/wan-load-balancing.rst b/docs/appendix/examples/wan-load-balancing.rst new file mode 100644 index 00000000..7093defe --- /dev/null +++ b/docs/appendix/examples/wan-load-balancing.rst @@ -0,0 +1,170 @@ +.. _wan-load-balancing: + +WAN Load Balancer examples +========================== + + +Example 1: Distributing load evenly +----------------------------------- + +The setup used in this example is shown in the following diagram: + +.. image:: /_static/images/Wan_load_balancing1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + + +Overview +^^^^^^^^ + * All traffic coming in trough eth2 is balanced between eth0 and eth1 + on the router. + * Pings will be sent to four targets for health testing (33.44.55.66, + 44.55.66.77, 55.66.77.88 and 66.77.88.99). + * All outgoing packets are assigned the source address of the assigned + interface (SNAT). + * eth0 is set to be removed from the load balancer's interface pool + after 5 ping failures, eth1 will be removed after 4 ping failures. + +Create static routes to ping targets +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create static routes through the two ISPs towards the ping targets and +commit the changes: + +.. code-block:: none + + set protocols static route 33.44.55.66/32 next-hop 11.22.33.1 + set protocols static route 44.55.66.77/32 next-hop 11.22.33.1 + set protocols static route 55.66.77.88/32 next-hop 22.33.44.1 + set protocols static route 66.77.88.99/32 next-hop 22.33.44.1 + +Configure the load balancer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure the WAN load balancer with the parameters described above: + +.. code-block:: none + + set load-balancing wan interface-health eth0 failure-count 5 + set load-balancing wan interface-health eth0 nexthop 11.22.33.1 + set load-balancing wan interface-health eth0 test 10 type ping + set load-balancing wan interface-health eth0 test 10 target 33.44.55.66 + set load-balancing wan interface-health eth0 test 20 type ping + set load-balancing wan interface-health eth0 test 20 target 44.55.66.77 + set load-balancing wan interface-health eth1 failure-count 4 + set load-balancing wan interface-health eth1 nexthop 22.33.44.1 + set load-balancing wan interface-health eth1 test 10 type ping + set load-balancing wan interface-health eth1 test 10 target 55.66.77.88 + set load-balancing wan interface-health eth1 test 20 type ping + set load-balancing wan interface-health eth1 test 20 target 66.77.88.99 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 10 interface eth1 + +Example 2: Failover based on interface weights +---------------------------------------------- + +This examples uses the failover mode. + +Overview +^^^^^^^^ +In this example eth0 is the primary interface and eth1 is the secondary +interface to provide simple failover functionality. If eth0 fails, eth1 +takes over. + +Create interface weight based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The configuration steps are the same as in the previous example, except +rule 10 so we keep the configuration, remove rule 10 and add a new rule +for the failover mode: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 failover + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 weight 10 + set load-balancing wan rule 10 interface eth1 weight 1 + +Example 3: Failover based on rule order +--------------------------------------- + +The previous example used the failover command to send traffic thorugh +eth1 if eth0 fails. In this example failover functionality is provided +by rule order. + +Overview +^^^^^^^^ +Two rules will be created, the first rule directs traffic coming in +from eth2 to eth0 and the second rule directs the traffic to eth1. If +eth0 fails the first rule is bypassed and the second rule matches, +directing traffic to eth1. + +Create rule order based configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configurtation from the previous example, delete rule 10 +and create the two new rules as described: + +.. code-block:: none + + delete load-balancing wan rule 10 + set load-balancing wan rule 10 inbound-interface eth2 + set load-balancing wan rule 10 interface eth0 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + +Example 4: Failover based on rule order - priority traffic +---------------------------------------------------------- + +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Overview +^^^^^^^^ +A rule order for prioritising traffic is useful in scenarios where the +secondary link has a lower speed and should only carry high priority +traffic. It is assumed for this example that eth1 is connected to a +slower connection than eth0 and should prioritise VoIP traffic. + +Create rule order based configuration with low speed secondary link +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We keep the configuration from the previous example, delete rule 20 and +create a new rule as described: + +.. code-block:: none + + delete load-balancing wan rule 20 + set load-balancing wan rule 20 inbound-interface eth2 + set load-balancing wan rule 20 interface eth1 + set load-balancing wan rule 20 destination port sip + set load-balancing wan rule 20 protocol tcp + set protocols static route 0.0.0.0/0 next-hop 11.22.33.1 + +Example 5: Exclude traffic from load balancing +---------------------------------------------- + +In this example two LAN interfaces exist in different subnets instead +of one like in the previous examples: + +.. image:: /_static/images/Wan_load_balancing_exclude1.png + :width: 80% + :align: center + :alt: Network Topology Diagram + +Adding a rule for the second interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Based on the previous example, another rule for traffic from the second +interface eth3 can be added to the load balancer. However, traffic meant +to flow between the LAN subnets will be sent to eth0 and eth1 as well. +To prevent this, another rule is required. This rule excludes traffic +between the local subnets from the load balancer. It also excludes +locally-sources packets (required for web caching with load balancing). +eth+ is used as an alias that refers to all ethernet interfaces: + +.. code-block:: none + + set load-balancing wan rule 5 exclude + set load-balancing wan rule 5 inbound-interface eth+ + set load-balancing wan rule 5 destination address 10.0.0.0/8 diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 2b2d3ba7..e8d1dba5 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -46,7 +46,8 @@ access to the official codebase. (:ref:`prepare_commit`). This mainly applies to proper commit messages describing your change (how and why). Please check out the documentation of Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used - for writing our docs. + for writing our docs. Additional directives how to write in RST can be obtained + from reStructuredTextDirectives_. * Check your changes by locally building the documentation ``$ make html``. Sphinx will build the html files in the ``docs/_build`` folder. We provide @@ -175,7 +176,7 @@ descriptive way in the resulting HTML/PDF manual. For a inline configuration level command use ``:cfgcmd:`` .. code-block:: none - + :cfgcmd:`set interface ethernet eth0` opcmd @@ -196,9 +197,47 @@ descriptive way in the resulting HTML/PDF manual. For a inline operational level command use ``:opcmd:`` .. code-block:: none - + :opcmd:`add system image` +cmdinclude +"""""""""" + +To minimize redundancy there is a special include directive. It include a txt +file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value + +.. code-block:: none + + .. cmdinclude:: interface-address.txt + :var0: ethernet + :var1: eth1 + +the content of interface-address.txt looks like this + +.. code-block:: none + + .. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | + dhcpv6> + + Configure interface `<interface>` with one or more interface + addresses. + + * **address** can be specified multiple times as IPv4 and/or IPv6 + address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server + on this segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 + server on this segment. + + Example: + + .. code-block:: none + + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 + set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 + set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 + vytask """""" @@ -214,6 +253,7 @@ URL. This is heavily used in the :ref:`release-notes` section. .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _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 diff --git a/docs/interfaces/advanced-index.rst b/docs/interfaces/advanced-index.rst index c666f7ae..f955c6b1 100644 --- a/docs/interfaces/advanced-index.rst +++ b/docs/interfaces/advanced-index.rst @@ -10,7 +10,9 @@ Advanced Network Interfaces bond bridge dummy + ethernet geneve + loopback l2tpv3 macsec pseudo-ethernet diff --git a/docs/interfaces/bond.rst b/docs/interfaces/bond.rst index 9e67809a..859c25c3 100644 --- a/docs/interfaces/bond.rst +++ b/docs/interfaces/bond.rst @@ -13,62 +13,22 @@ Additionally, link integrity monitoring may be performed. Configuration ############# -Address -------- - -.. cfgcmd:: set interfaces bonding <interface> address <address | dhcp | dhcpv6> - - Configure interface `<interface>` with one or more interface addresses. - - * **address** can be specified multiple times as IPv4 and/or IPv6 address, - e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - * **dhcp** interface address is received by DHCP from a DHCP server on this - segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on - this segment. - - Example: - - .. code-block:: none - - set interfaces bonding bond0 address 192.0.2.1/24 - set interfaces bonding bond0 address 192.0.2.2/24 - set interfaces bonding bond0 address 2001:db8::ffff/64 - set interfaces bonding bond0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces bonding <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bonding <interface> 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. - - .. code-block:: none - - set interfaces bonding bond0 ipv6 address eui64 2001:db8:beef::/64 +Common interface configuration +------------------------------ +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 -Link Administration -------------------- - -.. cfgcmd:: set interfaces bonding <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - - -.. cfgcmd:: set interfaces bonding <interface> disable +Member Interfaces +----------------- - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. +.. cfgcmd:: set interfaces bonding <interface> member interface <member> -.. cfgcmd:: set interfaces bonding <interface> mac <mac-address> + Enslave `<member>` interface to bond `<interface>`. - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. +Bond options +------------ .. cfgcmd:: set interfaces bonding <interface> mode <mode> @@ -293,13 +253,6 @@ Link Administration The maximum number of targets that can be specified is 16. The default value is no IP addresses. -Member Interfaces ------------------ - -.. cfgcmd:: set interfaces bonding <interface> member interface <member> - - Enslave `<member>` interface to bond `<interface>`. - Example ------- diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index a7343a0d..144e5f6d 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -17,92 +17,12 @@ standard. Configuration ############# -Address -------- - -.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | - dhcpv6> - - Configure interface `<interface>` with one or more interface - addresses. - - * **address** can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - * **dhcp** interface address is received by DHCP from a DHCP server - on this segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 - server on this segment. - - Example: - - .. code-block:: none - - set interfaces bridge br0 address 192.0.2.1/24 - set interfaces bridge br0 address 192.0.2.2/24 - set interfaces bridge br0 address 2001:db8::ffff/64 - set interfaces bridge br0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces bridge <interface> 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. - - .. code-block:: none - - set interfaces bridge br0 ipv6 address eui64 2001:db8:beef::/64 - - -.. cfgcmd:: set interfaces bridge <interface> aging <time> - - MAC address aging `<time`> in seconds (default: 300). - - -.. cfgcmd:: set interfaces bridge <interface> max-age <time> - - Bridge maximum aging `<time>` in seconds (default: 20). - - If a another bridge in the spanning tree does not send out a hello - packet for a long period of time, it is assumed to be dead. - - -Link Administration -------------------- - -.. cfgcmd:: set interfaces bridge <interface> description <description> - - Assign given `<description>` to interface. Description will also be - passed to SNMP monitoring systems. - - -.. cfgcmd:: set interfaces bridge <interface> disable - - Disable given `<interface>`. It will be placed in administratively - down (``A/D``) state. - - -.. cfgcmd:: set interfaces bridge <interface> disable-flow-control - - Disable Ethernet flow control (pause frames). - - -.. cfgcmd:: set interfaces bridge <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on - given `<interface>`. - - -.. cfgcmd:: set interfaces bridge <interface> igmp querier - - Enable IGMP querier - +Common interface configuration +------------------------------ +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: bridge + :var1: br0 Member Interfaces ----------------- @@ -139,7 +59,6 @@ Member Interfaces deciding which link to use. Faster interfaces should have lower costs. - .. _stp: STP Parameter @@ -175,9 +94,26 @@ links providing fault tolerance if an active link fails. Designated Bridges. Hello packets are used to communicate information about the topology throughout the entire Bridged Local Area Network. +Additional Bridge Options +------------------------- + +.. cfgcmd:: set interfaces bridge <interface> aging <time> + + MAC address aging `<time`> in seconds (default: 300). + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a another bridge in the spanning tree does not send out a hello + packet for a long period of time, it is assumed to be dead. + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier Example -------- +####### Creating a bridge interface is very simple. In this example we will have: @@ -212,7 +148,7 @@ This results in the active configuration: Operation -========= +######### .. opcmd:: show bridge diff --git a/docs/interfaces/common-ip-ipv6-addr.txt b/docs/interfaces/common-ip-ipv6-addr.txt deleted file mode 100644 index f53eaeee..00000000 --- a/docs/interfaces/common-ip-ipv6-addr.txt +++ /dev/null @@ -1,8 +0,0 @@ -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. diff --git a/docs/interfaces/common-ipv6-addr-autoconf.txt b/docs/interfaces/common-ipv6-addr-autoconf.txt deleted file mode 100644 index 838b299f..00000000 --- a/docs/interfaces/common-ipv6-addr-autoconf.txt +++ /dev/null @@ -1,12 +0,0 @@ -: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.
-
-.. note:: This method automatically disables IPv6 traffic forwarding on the
- interface in question.
-
diff --git a/docs/interfaces/dummy.rst b/docs/interfaces/dummy.rst index e452ae73..e0557d1d 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/interfaces/dummy.rst @@ -22,36 +22,24 @@ you can have as many as you want. Configuration ############# -Address -------- +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces dummy <interface> address <address | dhcp | dhcpv6> +.. cmdinclude:: ../_include/interface-address.txt + :var0: dummy + :var1: dum0 - Configure dummy interface `<interface>` with one or more interface - addresses. Address can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 +.. cmdinclude:: ../_include/interface-description.txt + :var0: dummy + :var1: dum0 - Example: +.. cmdinclude:: ../_include/interface-disable.txt + :var0: dummy + :var1: dum0 - .. code-block:: none - - set interfaces dummy dum10 address 192.0.2.1/24 - set interfaces dummy dum10 address 192.0.2.2/24 - set interfaces dummy dum10 address 2001:db8::ffff/64 - set interfaces dummy dum10 address 2001:db8:100::ffff/64 - -Link Administration -------------------- - -.. cfgcmd:: set interfaces dummy <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces dummy <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - state. +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: dummy + :var1: dum0 Operation ========= diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst index 95aef851..1d3aeda3 100644 --- a/docs/interfaces/ethernet.rst +++ b/docs/interfaces/ethernet.rst @@ -7,34 +7,12 @@ Ethernet Configuration ############# -Address -------- +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces ethernet <interface> address <address | dhcp | dhcpv6> - - .. include:: common-ip-ipv6-addr.txt - - Example: - - .. code-block:: none - - set interfaces ethernet eth0 address 192.0.2.1/24 - set interfaces ethernet eth0 address 192.0.2.2/24 - set interfaces ethernet eth0 address 2001:db8::ffff/64 - set interfaces ethernet eth0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces ethernet <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -.. cfgcmd:: set interfaces ethernet <interface> 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. - - .. code-block:: none - - set interfaces ethernet eth0 ipv6 address eui64 2001:db8:beef::/64 +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: ethernet + :var1: eth0 Speed/Duplex ------------ @@ -67,71 +45,12 @@ Speed/Duplex VyOS default will be `auto`. -Link Administration -------------------- - -.. cfgcmd:: set interfaces ethernet <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces ethernet <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - -.. cfgcmd:: set interfaces ethernet <interface> disable-flow-control - - Disable Ethernet flow control (pause frames). - - -.. cfgcmd:: set interfaces ethernet <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. - -.. cfgcmd:: set interfaces ethernet <interface> 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. - -Prefix Delegation (DHCPv6-PD) ------------------------------ - -VyOS 1.3 (equuleus) supports DHCPv6-PD. DHCPv6 Prefix Delegation is supported -by most ISPs who provide native IPv6 for consumers on fixed networks. - -.. cfgcmd:: set interfaces ethernet <interface> dhcpv6-option 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 /32 down to a /64 - delegation. - - Default value is 64. - -.. cfgcmd:: set interfaces ethernet <interface> dhcpv6-option pd <id> interface <delegatee> address <address> - - Specify the interface address used locally on the interfcae where the prefix - has been delegated to. ID must be a decimal integer. - - 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. - - Example: - - Using ``<id>`` value 65535 will assign IPv6 address ``<prefix>::ffff`` to the - interface. - -.. cfgcmd:: set interfaces ethernet <interface> dhcpv6-option pd <id> interface <delegatee> sla-id <id> +VLAN (802.1q) configuration +--------------------------- - 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). For 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. +.. cmdinclude:: ../_include/interface-vlan.txt + :var0: ethernet + :var1: eth0 Operation ========= diff --git a/docs/interfaces/geneve.rst b/docs/interfaces/geneve.rst index a4bc22aa..b59bb311 100644 --- a/docs/interfaces/geneve.rst +++ b/docs/interfaces/geneve.rst @@ -35,21 +35,15 @@ Geneve Header: Configuration ============= -.. cfgcmd:: set interfaces geneve gnv0 address <address> +Common interface configuration +------------------------------ - Configure interface `<interface>` with one or more interface addresses. +.. cmdinclude:: ../_include/interface-common-without-dhcp.txt + :var0: geneve + :var1: gnv0 - **address** can be specified multiple times as IPv4 and/or IPv6 address, - e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - - Example: - - .. code-block:: none - - set interfaces geneve gnv0 address 192.0.2.1/24 - set interfaces geneve gnv0 address 192.0.2.2/24 - set interfaces geneve gnv0 address 2001:db8::ffff/64 - set interfaces geneve gnv0 address 2001:db8:100::ffff/64 +GENEVE specific options +----------------------- .. cfgcmd:: set interfaces geneve gnv0 remote <address> @@ -64,7 +58,3 @@ Configuration decisions or MAY be used as a mechanism to distinguish between overlapping address spaces contained in the encapsulated packet when load balancing across CPUs. - -.. cfgcmd:: set interfaces geneve gnv0 mtu <mtu> - - Set interface :abbr:`MTU (Maximum Transfer Unit)` size. diff --git a/docs/interfaces/l2tpv3.rst b/docs/interfaces/l2tpv3.rst index ea540c01..c456a58e 100644 --- a/docs/interfaces/l2tpv3.rst +++ b/docs/interfaces/l2tpv3.rst @@ -2,8 +2,9 @@ .. _l2tpv3-interface: +###### L2TPv3 ------- +###### L2TPv3 is a pseudowire protocol, you can read more about on `Wikipedia L2TPv3`_ or in :rfc:`3921` @@ -11,6 +12,16 @@ or in :rfc:`3921` L2TPv3 can transport any traffic including ethernet frames. L2TPv2 is limited to PPP. +Configuration +############# + +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-common-without-dhcp.txt + :var0: l2tpv3 + :var1: l2tpeth0 + Over IP ^^^^^^^ diff --git a/docs/interfaces/loopback.rst b/docs/interfaces/loopback.rst index e15062cf..ed241eb2 100644 --- a/docs/interfaces/loopback.rst +++ b/docs/interfaces/loopback.rst @@ -22,22 +22,16 @@ services on your local machine. Configuration ============= -Address -------- +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces loopback lo address <address> +.. cmdinclude:: ../_include/interface-address.txt + :var0: loopback + :var1: lo - Configure Loopback interface `lo` with one or more interface addresses. - Address can be specified multiple times as IPv4 and/or IPv6 address, e.g. - 192.0.2.1/24 and/or 2001:db8::1/64. - -Link Administration -------------------- - -.. cfgcmd:: set interfaces loopback lo description <description> - - Assign given `<description>` to interface `lo`. Description will also be - passed to SNMP monitoring systems. +.. cmdinclude:: ../_include/interface-description.txt + :var0: loopback + :var1: lo Operation ========= diff --git a/docs/interfaces/macsec.rst b/docs/interfaces/macsec.rst index d7af0c16..f841e17d 100644 --- a/docs/interfaces/macsec.rst +++ b/docs/interfaces/macsec.rst @@ -16,6 +16,16 @@ used for their own specific use cases. Configuration ############# +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: macsec + :var1: macsec0 + +MACsec specific options +----------------------- + .. cfgcmd:: set interfaces macsec <interface> security cipher [gcm-aes-128] Select cipher suite used for cryptographic operations. This setting is @@ -34,9 +44,8 @@ Configuration A physical interface is required to connect this MACsec instance to. Traffic leaving this interfac will now be authenticated/encrypted. - Key Management --------------- +^^^^^^^^^^^^^^ :abbr:`MKA (MACsec Key Agreement protocol)` is used to synchronize keys between individual peers. @@ -56,7 +65,7 @@ individual peers. distributing SAKs. Replay protection ------------------ +^^^^^^^^^^^^^^^^^ .. cfgcmd:: set interfaces macsec <interface> security replay-window <window> @@ -68,7 +77,7 @@ Replay protection - ``1-4294967295``: Number of packets that could be misordered Operation -========= +######### .. opcmd:: run generate macsec mka-cak @@ -115,7 +124,7 @@ Operation TXSC: 005056bfefaa0001 on SA 0 Examples -======== +######## * Two routers connected both via eth1 through an untrusted switch * R1 has 192.0.2.1/24 & 2001:db8::1/64 diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst index 8fa35492..e85c16aa 100644 --- a/docs/interfaces/pppoe.rst +++ b/docs/interfaces/pppoe.rst @@ -54,6 +54,24 @@ vDSL/aDSL understands. Configuration ============= +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-description.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: ../_include/interface-disable.txt + :var0: pppoe + :var1: pppoe0 + +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: pppoe + :var1: pppoe0 + +PPPoE specific configuration +---------------------------- + .. cfgcmd:: set interfaces pppoe <interface> access-concentrator <name> Use this command to restrict the PPPoE session on a given access @@ -102,16 +120,6 @@ Configuration **default:** A default route to the remote endpoint is automatically added when the link comes up (i.e. auto). -.. cfgcmd:: set interfaces pppoe <interface> description - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces pppoe <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - .. cfgcmd:: set interfaces pppoe <interface> idle-timeout <time> Use this command to set the idle timeout interval to be used with on-demand @@ -167,43 +175,9 @@ IPv6 Use this command to enable acquisition of IPv6 address using stateless autoconfig (SLAAC). -Prefix Delegation (DHCPv6-PD) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -VyOS 1.3 (equuleus) supports DHCPv6-PD. DHCPv6 Prefix Delegation is supported -by most ISPs who provide native IPv6 for consumers on fixed networks. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option 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 /32 down to a /64 - delegation. - - Default value is 64. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option pd <id> interface <delegatee> address <address> - - Specify the interface address used locally on the interfcae where the prefix - has been delegated to. ID must be a decimal integer. - - 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. - - Example: - - Using ``<id>`` value 65535 will assign IPv6 address ``<prefix>::ffff`` to the - interface. - -.. cfgcmd:: set interfaces pppoe <interface> dhcpv6-option 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). For 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. +.. cmdinclude:: ../_include/interface-dhcpv6-prefix-delegation.txt + :var0: pppoe + :var1: pppoe0 Operation ========= diff --git a/docs/interfaces/pseudo-ethernet.rst b/docs/interfaces/pseudo-ethernet.rst index a2066555..26d8a364 100644 --- a/docs/interfaces/pseudo-ethernet.rst +++ b/docs/interfaces/pseudo-ethernet.rst @@ -41,49 +41,17 @@ Ethernet interfaces: Configuration ============= -Address -------- +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces pseudo-ethernet <interface> address <address | dhcp | dhcpv6> +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: pseudo-ethernet + :var1: peth0 - .. include:: common-ip-ipv6-addr.txt - - Example: - - .. code-block:: none - - set interfaces pseudo-ethernet peth0 address 192.0.2.1/24 - set interfaces pseudo-ethernet peth0 address 192.0.2.2/24 - set interfaces pseudo-ethernet peth0 address 2001:db8::ffff/64 - set interfaces pseudo-ethernet peth0 address 2001:db8:100::ffff/64 - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt - -Physical Asignment ------------------- +Pseudo Ethernet/MACVLAN specific options +---------------------------------------- .. cfgcmd:: set interfaces pseudo-ethernet <interface> source-interface <ethX> Specifies the physical `<ethX>` Ethernet interface associated with a Pseudo Ethernet `<interface>`. - -Link Administration -------------------- - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. - -.. cfgcmd:: set interfaces pseudo-ethernet <interface> mac <mac-address> - - Configure user defined :abbr:`MAC (Media Access Control)` address on given - `<interface>`. - diff --git a/docs/interfaces/tunnel.rst b/docs/interfaces/tunnel.rst index f20127f5..c14314d1 100644 --- a/docs/interfaces/tunnel.rst +++ b/docs/interfaces/tunnel.rst @@ -13,6 +13,13 @@ GRE options that can be useful. All those protocols are grouped under ``interfaces tunnel`` in VyOS. Let's take a closer look at the protocols and options currently supported by VyOS. +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-common-without-dhcp.txt + :var0: tunnel + :var1: tun0 + IPIP ---- @@ -124,6 +131,29 @@ ip otherwise it would have to be configured as well. tunnel source 203.0.113.10 tunnel destination 198.51.100.2 + +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. + +An example: + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 10.40.50.60/24 + set interfaces tunnel tun0 parameters ip key 10 + +.. code-block:: none + + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 192.0.2.20 + set interfaces tunnel tun0 address 172.16.17.18/24 + set interfaces tunnel tun0 parameters ip key 20 + + Troubleshooting ^^^^^^^^^^^^^^^ diff --git a/docs/interfaces/vxlan.rst b/docs/interfaces/vxlan.rst index bf3b6dee..40dc5400 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/interfaces/vxlan.rst @@ -36,106 +36,58 @@ may be blocked by the hypervisor. Configuration ============= -Address -------- - -.. cfgcmd:: set interfaces vxlan <interface> address <address> - - Configure VXLAN interface `<interface>` with one or more interface - addresses. Address can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - - Example: - - .. code-block:: none - - set interfaces vxlan vxlan0 address 192.0.2.1/24 - set interfaces vxlan vxlan0 address 192.0.2.2/24 - set interfaces vxlan vxlan0 address 2001:db8::ffff/64 - set interfaces vxlan vxlan0 address 2001:db8:100::ffff/64 - - -.. cfgcmd:: set interfaces vxlan <interface> ipv6 address autoconf - - .. include:: common-ipv6-addr-autoconf.txt +Common interface configuration +------------------------------ -.. cfgcmd:: set interfaces vxlan <interface> 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. - - .. code-block:: none - - set interfaces vxlan vxlan0 ipv6 address eui64 2001:db8:beef::/64 +.. cmdinclude:: ../_include/interface-common-without-dhcp.txt + :var0: vxlan + :var1: vxlan0 +VXLAN specific options +----------------------- .. cfgcmd:: set interfaces vxlan <interface> vni <number> - Each VXLAN segment is identified through a 24-bit segment ID, termed the - :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows - up to 16M VXLAN segments to coexist within the same administrative domain. - -Multicast -^^^^^^^^^ - -.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> + Each VXLAN segment is identified through a 24-bit segment ID, termed the + :abbr:`VNI (VXLAN Network Identifier (or VXLAN Segment ID))`, This allows + up to 16M VXLAN segments to coexist within the same administrative domain. - Interface used for VXLAN underlay. This is mandatory when using VXLAN via - a multicast network. VXLAN traffic will always enter and exit this interface. +.. cfgcmd:: set interfaces vxlan <interface> port <port> + Configure port number of remote VXLAN endpoint. -.. cfgcmd:: set interfaces vxlan <interface> group <address> + .. note:: As VyOS is Linux based the default port used is not using 4789 + as the default IANA-assigned destination UDP port number. Instead VyOS + uses the Linux default port of 8472. - Multicast group address for VXLAN interface. VXLAN tunnels can be built - either via Multicast or via Unicast. +.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> - Both IPv4 and IPv6 multicast is possible. + Source IP address used for VXLAN underlay. This is mandatory when using VXLAN + via L2VPN/EVPN. Unicast ^^^^^^^ .. cfgcmd:: set interfaces vxlan <interface> remote <address> - IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the - remote IPv4/IPv6 address can set directly. - - -.. cfgcmd:: set interfaces vxlan <interface> port <port> - - Configure port number of remote VXLAN endpoint. - - .. note:: As VyOS is Linux based the default port used is not using 4789 - as the default IANA-assigned destination UDP port number. Instead VyOS - uses the Linux default port of 8472. - -L2VVPN / EVPN -^^^^^^^^^^^^^ + IPv4/IPv6 remote address of the VXLAN tunnel. Alternative to multicast, the + remote IPv4/IPv6 address can set directly. -.. cfgcmd:: set interfaces vxlan <interface> source-address <interface> - - Source IP address used for VXLAN underlay. This is mandatory when using - VXLAN via L2VPN/EVPN. - - -Link Administration -------------------- +Multicast +^^^^^^^^^ -.. cfgcmd:: set interfaces vxlan <interface> description <description> +.. cfgcmd:: set interfaces vxlan <interface> source-interface <interface> - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. + Interface used for VXLAN underlay. This is mandatory when using VXLAN via + a multicast network. VXLAN traffic will always enter and exit this interface. -.. cfgcmd:: set interfaces vxlan <interface> disable - Disable given `<interface>`. It will be placed in administratively down - (``A/D``) state. +.. cfgcmd:: set interfaces vxlan <interface> group <address> -.. cfgcmd:: set interfaces vxlan <interface> mtu <mtu> + Multicast group address for VXLAN interface. VXLAN tunnels can be built + either via Multicast or via Unicast. - Configure :abbr:`MTU (Maximum Transmission Unit)` on given `<interface>`. It - is the size (in bytes) of the largest ethernet frame sent on this link. - MTU ranges from 1450 to 9000 bytes. For best performance you should have - a MTU > 1550 bytes on your underlay. + Both IPv4 and IPv6 multicast is possible. Multicast VXLAN =============== diff --git a/docs/interfaces/wireless.rst b/docs/interfaces/wireless.rst index 8b1195fa..b146a21b 100644 --- a/docs/interfaces/wireless.rst +++ b/docs/interfaces/wireless.rst @@ -1,7 +1,10 @@ +.. include:: ../_include/need_improvement.txt + .. _wireless-interface: +################### Wireless LAN (WiFi) -------------------- +################### :abbr:`WLAN (Wireless LAN)` interface provide 802.11 (a/b/g/n/ac) wireless support (commonly referred to as Wi-Fi) by means of compatible hardware. If your @@ -22,17 +25,30 @@ If the system detects an unconfigured wireless device, it will be automatically added the configuration tree, specifying any detected settings (for example, its MAC address) and configured to run in monitor mode. +Configuration +############# + +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: wireless + :var1: wlan0 + +Wireless specific options +------------------------- + +Configuring Access-Point +^^^^^^^^^^^^^^^^^^^^^^^^ + To be able to use the wireless interfaces you will first need to set a regulatory domain with the country code of your location. -.. cfgcmd:: set system wifi-regulatory-domain DE +.. cfgcmd:: set interfaces wireless <interface> country-code <cc> Configure system wide Wi-Fi regulatory domain. A reboot is required for this change to be enabled. -Configuring Access-Point -^^^^^^^^^^^^^^^^^^^^^^^^ - The following example creates a WAP. When configuring multiple WAP interfaces, you must specify unique IP addresses, channels, Network IDs commonly referred to as :abbr:`SSID (Service Set Identifier)`, and MAC addresses. diff --git a/docs/interfaces/wirelessmodem.rst b/docs/interfaces/wirelessmodem.rst index c41e71bf..4590a3bb 100644 --- a/docs/interfaces/wirelessmodem.rst +++ b/docs/interfaces/wirelessmodem.rst @@ -11,8 +11,23 @@ The wirelessmodem interface provides access (through a wireless modem/wwan) to wireless networks provided by various cellular providers. VyOS uses the interfaces wirelessmodem subsystem for configuration. -Address -------- +Common interface configuration +------------------------------ + +.. cmdinclude:: ../_include/interface-description.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: ../_include/interface-disable.txt + :var0: wirelessmodem + :var1: wlm0 + +.. cmdinclude:: ../_include/interface-vrf.txt + :var0: wirelessmodem + :var1: wlm0 + +WWAN specific options +--------------------- .. cfgcmd:: set interfaces wirelessmodem <interface> apn <apn> @@ -44,24 +59,6 @@ Address connection is established at boot time and remains up. If the link fails for any reason, the link is brought back up immediately. -Link Administration -------------------- - -.. cfgcmd:: set interfaces wirelessmodem <interface> description <description> - - Assign given `<description>` to interface. Description will also be passed - to SNMP monitoring systems. - -.. cfgcmd:: set interfaces wirelessmodem <interface> disable - - Disable given `<interface>`. It will be placed in administratively down - state. - -.. cfgcmd:: set interfaces wirelessmodem <interface> 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. - Example ======= diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst index 8655d177..56316793 100644 --- a/docs/services/dhcp.rst +++ b/docs/services/dhcp.rst @@ -629,9 +629,7 @@ If you want your router to forward DHCP requests to an external DHCP server you can configure the system to act as a DHCP relay agent. The DHCP relay agent works with IPv4 and IPv6 addresses. -All interfaces used for the DHCP relay must be configured. See -https://wiki.vyos.net/wiki/Network_address_setup. - +All interfaces used for the DHCP relay must be configured. Configuration ------------- |
