From de9eaec2cf26bb67738d953fbc87a3f3320aa3d7 Mon Sep 17 00:00:00 2001 From: rebortg Date: Thu, 26 Nov 2020 22:12:04 +0100 Subject: prepare coverage.rst --- docs/_ext/testcoverage.py | 351 ++++++++++++++++++++++++++++++++++++++++++++++ docs/_ext/vyos.py | 264 +++++++++++++++++++++++++++++----- docs/coverage.rst | 43 ++++++ 3 files changed, 626 insertions(+), 32 deletions(-) create mode 100644 docs/_ext/testcoverage.py create mode 100644 docs/coverage.rst (limited to 'docs') diff --git a/docs/_ext/testcoverage.py b/docs/_ext/testcoverage.py new file mode 100644 index 00000000..70714d6b --- /dev/null +++ b/docs/_ext/testcoverage.py @@ -0,0 +1,351 @@ +''' +generate json with all commands from xml for vyos documentation coverage + +''' + + +import sys +import os +import json +import re +import logging + +from io import BytesIO +from lxml import etree as ET +import shutil + +default_constraint_err_msg = "Invalid value" +validator_dir = "" + + +input_data = [ + { + "kind": "cfgcmd", + "input_dir": "_include/vyos-1x/interface-definitions/", + "schema_file": "_include/vyos-1x/schema/interface_definition.rng", + "files": [] + }, + { + "kind": "opcmd", + "input_dir": "_include/vyos-1x/op-mode-definitions/", + "schema_file": "_include/vyos-1x/schema/op-mode-definition.rng", + "files": [] + } +] + +node_data = { + 'cfgcmd': {}, + 'opcmd': {}, +} + +def get_properties(p): + props = {} + props['valueless'] = False + + try: + if p.find("valueless") is not None: + props['valueless'] = True + except: + pass + + if p is None: + return props + + # Get the help string + try: + props["help"] = p.find("help").text + except: + pass + + # Get value help strings + try: + vhe = p.findall("valueHelp") + vh = [] + for v in vhe: + vh.append( (v.find("format").text, v.find("description").text) ) + props["val_help"] = vh + except: + props["val_help"] = [] + + # Get the constraint statements + error_msg = default_constraint_err_msg + # Get the error message if it's there + try: + error_msg = p.find("constraintErrorMessage").text + except: + pass + + + vce = p.find("constraint") + vc = [] + if vce is not None: + # The old backend doesn't support multiple validators in OR mode + # so we emulate it + + regexes = [] + regex_elements = vce.findall("regex") + if regex_elements is not None: + regexes = list(map(lambda e: e.text.strip(), regex_elements)) + if "" in regexes: + print("Warning: empty regex, node will be accepting any value") + + validator_elements = vce.findall("validator") + validators = [] + if validator_elements is not None: + for v in validator_elements: + v_name = os.path.join(validator_dir, v.get("name")) + + # XXX: lxml returns None for empty arguments + v_argument = None + try: + v_argument = v.get("argument") + except: + pass + if v_argument is None: + v_argument = "" + + validators.append("{0} {1}".format(v_name, v_argument)) + + + regex_args = " ".join(map(lambda s: "--regex \\\'{0}\\\'".format(s), regexes)) + validator_args = " ".join(map(lambda s: "--exec \\\"{0}\\\"".format(s), validators)) + validator_script = '${vyos_libexec_dir}/validate-value.py' + validator_string = "exec \"{0} {1} {2} --value \\\'$VAR(@)\\\'\"; \"{3}\"".format(validator_script, regex_args, validator_args, error_msg) + + props["constraint"] = validator_string + + # Get the completion help strings + try: + che = p.findall("completionHelp") + ch = "" + for c in che: + scripts = c.findall("script") + paths = c.findall("path") + lists = c.findall("list") + + # Current backend doesn't support multiple allowed: tags + # so we get to emulate it + comp_exprs = [] + for i in lists: + comp_exprs.append("echo \"{0}\"".format(i.text)) + for i in paths: + comp_exprs.append("/bin/cli-shell-api listNodes {0}".format(i.text)) + for i in scripts: + comp_exprs.append("sh -c \"{0}\"".format(i.text)) + comp_help = " && ".join(comp_exprs) + props["comp_help"] = comp_help + except: + props["comp_help"] = [] + + # Get priority + try: + props["priority"] = p.find("priority").text + except: + pass + + # Get "multi" + if p.find("multi") is not None: + props["multi"] = True + + # Get "valueless" + if p.find("valueless") is not None: + props["valueless"] = True + + return props + +def process_node(n, f): + + props_elem = n.find("properties") + children = n.find("children") + command = n.find("command") + children_nodes = [] + owner = n.get("owner") + node_type = n.tag + + name = n.get("name") + props = get_properties(props_elem) + + if node_type != "node": + if "valueless" not in props.keys(): + props["type"] = "txt" + if node_type == "tagNode": + props["tag"] = "True" + + if node_type == "node" and children is not None: + inner_nodes = children.iterfind("*") + index_child = 0 + for inner_n in inner_nodes: + children_nodes.append(process_node(inner_n, f)) + index_child = index_child + 1 + + if node_type == "tagNode" and children is not None: + inner_nodes = children.iterfind("*") + index_child = 0 + for inner_n in inner_nodes: + children_nodes.append(process_node(inner_n, f)) + index_child = index_child + 1 + else: + # This is a leaf node + pass + + if command is not None: + test_command = True + else: + test_command = False + node = { + 'name': name, + 'type': node_type, + 'children': children_nodes, + 'props': props, + 'command': test_command, + 'filename': f + } + return node + + + +def create_commands(data, parent_list=[], level=0): + result = [] + command = { + 'name': [], + 'help': None, + 'tag_help': [], + 'level': level, + 'no_childs': False, + 'filename': None + } + command['filename'] = data['filename'] + command['name'].extend(parent_list) + command['name'].append(data['name']) + + if data['type'] == 'tagNode': + command['name'].append("<" + data['name'] + ">") + + if 'val_help' in data['props'].keys(): + for val_help in data['props']['val_help']: + command['tag_help'].append(val_help) + + if len(data['children']) == 0: + command['no_childs'] = True + + if data['command']: + command['no_childs'] = True + + try: + help_text = data['props']['help'] + command['help'] = re.sub(r"[\n\t]*", "", help_text) + + except: + command['help'] = "" + + command['valueless'] = data['props']['valueless'] + + if 'children' in data.keys(): + children_bool = True + for child in data['children']: + result.extend(create_commands(child, command['name'], level + 1)) + + if command['no_childs']: + result.append(command) + + + + return result + + +def include_file(line, input_dir): + string = "" + if "#include ','',cmd) + cmd = re.sub('\[\S\]','',cmd) + cmd = re.sub('\s+','',cmd) + return cmd + +def build_row(app, fromdocname, rowdata): + row = nodes.row() + for cell in rowdata: + entry = nodes.entry() + row += entry + if isinstance(cell, list): + for item in cell: + if isinstance(item, dict): + entry += process_cmd_node(app, item, fromdocname, '') + else: + entry += nodes.paragraph(text=item) + elif isinstance(cell, bool): + if cell: + entry += nodes.paragraph(text="") + entry['classes'] = ['coverage-ok'] + else: + entry += nodes.paragraph(text="") + entry['classes'] = ['coverage-fail'] + else: + entry += nodes.paragraph(text=cell) + return row + + + +def process_coverage(app, fromdocname, doccmd, xmlcmd, cli_type): + coverage_list = {} + int_docs = 0 + int_xml = 0 + for cmd in doccmd: + coverage_item = { + 'doccmd': None, + 'xmlcmd': None, + 'doccmd_item': None, + 'xmlcmd_item': None, + 'indocs': False, + 'inxml': False, + 'xmlfilename': None + } + coverage_item['doccmd'] = cmd['cmd'] + coverage_item['doccmd_item'] = cmd + coverage_item['indocs'] = True + int_docs += 1 + coverage_list[strip_cmd(cmd['cmd'])] = dict(coverage_item) + + for cmd in xmlcmd: + + strip = strip_cmd(cmd['cmd']) + if strip not in coverage_list.keys(): + coverage_item = { + 'doccmd': None, + 'xmlcmd': None, + 'doccmd_item': None, + 'xmlcmd_item': None, + 'indocs': False, + 'inxml': False, + 'xmlfilename': None + } + coverage_item['xmlcmd'] = cmd['cmd'] + coverage_item['xmlcmd_item'] = cmd + coverage_item['inxml'] = True + coverage_item['xmlfilename'] = cmd['filename'] + int_xml += 1 + coverage_list[strip] = dict(coverage_item) + else: + #print("===BEGIN===") + #print(cmd) + #print(coverage_list[strip]) + #print(strip) + #print("===END====") + coverage_list[strip]['xmlcmd'] = cmd['cmd'] + coverage_list[strip]['xmlcmd_item'] = cmd + coverage_list[strip]['inxml'] = True + coverage_list[strip]['xmlfilename'] = cmd['filename'] + int_xml += 1 + + + + + table = nodes.table() + tgroup = nodes.tgroup(cols=3) + table += tgroup + + header = (f'{int_docs}/{len(coverage_list)} in Docs', f'{int_xml}/{len(coverage_list)} in XML', 'Command') + colwidths = (1, 1, 8) + table = nodes.table() + tgroup = nodes.tgroup(cols=len(header)) + table += tgroup + for colwidth in colwidths: + tgroup += nodes.colspec(colwidth=colwidth) + thead = nodes.thead() + tgroup += thead + thead += build_row(app, fromdocname, header) + tbody = nodes.tbody() + tgroup += tbody + for entry in sorted(coverage_list): + body_text_list = [] + if coverage_list[entry]['indocs']: + body_text_list.append(coverage_list[entry]['doccmd_item']) + else: + body_text_list.append('Not documented yet') + + if coverage_list[entry]['inxml']: + body_text_list.append("------------------") + body_text_list.append(str(coverage_list[entry]['xmlfilename']) + ":") + body_text_list.append(coverage_list[entry]['xmlcmd']) + else: + body_text_list.append('Nothing found in XML Definitions') + + + tbody += build_row(app, fromdocname, + ( + coverage_list[entry]['indocs'], + coverage_list[entry]['inxml'], + body_text_list + ) + ) + + return table + +def process_cmd_node(app, cmd, fromdocname, cli_type): para = nodes.paragraph() newnode = nodes.reference('', '') innernode = cmd['cmdnode'] @@ -401,21 +577,45 @@ def process_cmd_node(app, cmd, fromdocname): def process_cmd_nodes(app, doctree, fromdocname): - env = app.builder.env - - for node in doctree.traverse(CfgcmdList): - content = [] - - for cmd in sorted(env.vyos_cfgcmd, key=lambda i: i['cmd']): - content.append(process_cmd_node(app, cmd, fromdocname)) - node.replace_self(content) - - for node in doctree.traverse(OpcmdList): - content = [] + try: + env = app.builder.env + + for node in doctree.traverse(CfgcmdList): + content = [] + if node.attributes['coverage']: + node.replace_self( + process_coverage( + app, + fromdocname, + env.vyos_cfgcmd, + app.config.vyos_working_commands['cfgcmd'], + 'cfgcmd' + ) + ) + else: + for cmd in sorted(env.vyos_cfgcmd, key=lambda i: i['cmd']): + content.append(process_cmd_node(app, cmd, fromdocname, 'cfgcmd')) + node.replace_self(content) + + for node in doctree.traverse(OpcmdList): + content = [] + if node.attributes['coverage']: + node.replace_self( + process_coverage( + app, + fromdocname, + env.vyos_opcmd, + app.config.vyos_working_commands['opcmd'], + 'opcmd' + ) + ) + else: + for cmd in sorted(env.vyos_opcmd, key=lambda i: i['cmd']): + content.append(process_cmd_node(app, cmd, fromdocname, 'opcmd')) + node.replace_self(content) - for cmd in sorted(env.vyos_opcmd, key=lambda i: i['cmd']): - content.append(process_cmd_node(app, cmd, fromdocname)) - node.replace_self(content) + except Exception as inst: + print(inst) def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): @@ -430,4 +630,4 @@ def vytask_role(name, rawtext, text, lineno, inliner, options={}, content=[]): def cmd_role(name, rawtext, text, lineno, inliner, options={}, content=[]): node = nodes.literal(text, text) - return [node], [] + return [node], [] \ No newline at end of file diff --git a/docs/coverage.rst b/docs/coverage.rst new file mode 100644 index 00000000..f003f9ff --- /dev/null +++ b/docs/coverage.rst @@ -0,0 +1,43 @@ +:orphan: + +######## +Coverage +######## + +Overview over all commands, which are documented in the ``.. cfgcmd::`` or ``.. opcmd::`` Directives. + +| The build process take all xml definition files from `vyos-1x `_ and extract each leaf command or executable command. +| After this the commands are compare and shown in the follwoing two tables. +| The script compare only the fixed part of a command. All varables or values will be erase and then compare: + +for example there are these two commands: + + * documentation: ``interfaces ethernet address
``` + * xml: ``interface ethernet address
`` + +Now the script earse all in between ``<`` and ``>`` and simply compare the strings. + +**There are 2 kind of problems:** + +| ``Not documented yet`` +| A XML command are not found in ``.. cfgcmd::`` or ``.. opcmd::`` Commands +| The command should be documented + +| ``Nothing found in XML Definitions``: +| ``.. cfgcmd::`` or ``.. opcmd::`` Command are not found in a XML command +| Maybe the command where changed in the XML Definition, or the feature is not anymore in VyOS +| Some commands are not yet translated to XML + + +Configuration Commands +====================== + +.. cfgcmdlist:: + :show-coverage: + + +Operational Commands +==================== + +.. opcmdlist:: + :show-coverage: \ No newline at end of file -- cgit v1.2.3 From d4863cc15079682634ecca21dd87442ae3cb5666 Mon Sep 17 00:00:00 2001 From: rebortg Date: Thu, 26 Nov 2020 22:32:45 +0100 Subject: add vyos-1x submodule --- .gitmodules | 4 ++++ docs/_include/vyos-1x | 1 + 2 files changed, 5 insertions(+) create mode 100644 .gitmodules create mode 160000 docs/_include/vyos-1x (limited to 'docs') diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..d3d92138 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "docs/_include/vyos-1x"] + path = docs/_include/vyos-1x + url = https://github.com/vyos/vyos-1x + branch = current diff --git a/docs/_include/vyos-1x b/docs/_include/vyos-1x new file mode 160000 index 00000000..64d6e689 --- /dev/null +++ b/docs/_include/vyos-1x @@ -0,0 +1 @@ +Subproject commit 64d6e689a8274845a49e6931eda6cda04615de42 -- cgit v1.2.3 From bee2a84c89fc24a54b3687027ff0ed9dd951082f Mon Sep 17 00:00:00 2001 From: rebortg Date: Thu, 26 Nov 2020 22:37:40 +0100 Subject: increase version --- docs/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index bb32aa33..4bb2da3c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -26,10 +26,10 @@ copyright = u'2020, VyOS maintainers and contributors' author = u'VyOS maintainers and contributors' # The short X.Y version -version = u'1.3' +version = u'1.4' # The full version, including alpha/beta/rc tags -release = u'1.3.x (equuleus)' +release = u'1.4.x (sagitta)' # -- General configuration --------------------------------------------------- @@ -70,7 +70,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', '_include/vyos-1x'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -- cgit v1.2.3 From c4b2276ec861a23edba12541eb39b27891f5d057 Mon Sep 17 00:00:00 2001 From: rebortg Date: Fri, 27 Nov 2020 20:10:44 +0100 Subject: coverage: add 'set' detection --- docs/_ext/vyos.py | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/_ext/vyos.py b/docs/_ext/vyos.py index cc408784..4b4b1a89 100644 --- a/docs/_ext/vyos.py +++ b/docs/_ext/vyos.py @@ -297,16 +297,6 @@ class CfgInclude(Directive): 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: for i in range(10): value = self.options.get(f'var{i}','') @@ -436,7 +426,7 @@ class CfgCmdDirective(CmdDirective): def strip_cmd(cmd): - #cmd = re.sub('set','',cmd) + cmd = re.sub('set','',cmd) cmd = re.sub('\s\|\s','',cmd) cmd = re.sub('<\S*>','',cmd) cmd = re.sub('\[\S\]','',cmd) -- cgit v1.2.3 From aacb7a54ec88ee3f8eea1e669f6f31c795cc96db Mon Sep 17 00:00:00 2001 From: rebortg Date: Fri, 27 Nov 2020 20:12:12 +0100 Subject: CSS: refresh desgin --- docs/_static/css/custom.css | 74 ++++++++++++++++++++++++++++++++++---- docs/_static/images/vyos-logo.png | Bin 118757 -> 68746 bytes 2 files changed, 67 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 7faf7b7f..6d36283d 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -10,8 +10,45 @@ span.cfgcmd { font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace; } -.opcmd-heading, +span.cfgcmd:before { + content: "#"; + margin-right: 0px; +} + +td p a.cmdlink span.cfgcmd:before, +td p a.cmdlink span.opcmd:before { + content: ""; +} + +td p a.cmdlink, +td p a.cmdlink { + margin-left: 0px; +} + +tr td p { + margin-bottom:0px + } + +span.opcmd:before { + content: "$"; + margin-right: 0px; +} + .cfgcmd-heading { + display: inline-block; + margin: 6px 0; + font-size: 90%; + line-height: normal; + background: #f0d481; + color: #2980B9; + border-top: solid 3px #6ab0de; + border-top-width: 3px; + border-top-style: solid; + border-top-color: #FF9302; + padding: 6px; +} + +.opcmd-heading { display: inline-block; margin: 6px 0; font-size: 90%; @@ -34,7 +71,7 @@ span.cfgcmd { .cfgcmd-heading .cmdlink:after, -.opcmd-heading .cmdlink:after { +.opcmd-heading .cmdlink:after{ content: ""; font-family: FontAwesome } @@ -97,21 +134,44 @@ a.cmdlink span:hover{ } .wy-side-nav-search { - background-color : #FF0000 !important; + background-color : #ffffff !important; } .wy-side-nav-search img { - background-color : #FF0000 !important; + background-color : #ffffff !important; } .wy-side-nav-search > div.version { - color : rgba(255, 255, 255, 0.7) !important; + color : #000000 !important; +} + +.wy-side-nav-search>a, +.wy-side-nav-search .wy-dropdown>a { + color:#000000; + font-size:100%; + font-weight:bold; + display:inline-block; + padding:4px 6px; + margin-bottom:.809em } .wy-nav-top { - background-color : #FF0000 !important; + background-color : #ffffff !important; } .wy-nav-top img { - background-color : #FF0000 !important; + background-color : #000000 !important; +} + +.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td.coverage-ok, +.rst-content table.docutils td.coverage-ok { + background-color: green; + color: black; } + + +.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td.coverage-fail, +.rst-content table.docutils td.coverage-fail { + background-color: red; + color: black; +} \ No newline at end of file diff --git a/docs/_static/images/vyos-logo.png b/docs/_static/images/vyos-logo.png index bc1abe15..e3d6f68b 100644 Binary files a/docs/_static/images/vyos-logo.png and b/docs/_static/images/vyos-logo.png differ -- cgit v1.2.3 From adf00431bcc81e270687882e672d59dd2c65515a Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:05:51 +0100 Subject: Templates: move draw.io template to _inlcude folder --- docs/.gitignore | 1 - docs/_include/draw.io/pbr_example_1.drawio | 1 + docs/_include/draw.io/vpn_s2s_ikev2.drawio | 1 + 3 files changed, 2 insertions(+), 1 deletion(-) delete mode 100644 docs/.gitignore create mode 100644 docs/_include/draw.io/pbr_example_1.drawio create mode 100644 docs/_include/draw.io/vpn_s2s_ikev2.drawio (limited to 'docs') diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 69fa449d..00000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build/ diff --git a/docs/_include/draw.io/pbr_example_1.drawio b/docs/_include/draw.io/pbr_example_1.drawio new file mode 100644 index 00000000..0d496572 --- /dev/null +++ b/docs/_include/draw.io/pbr_example_1.drawio @@ -0,0 +1 @@ +7VrbcqM4EP0aP4ZCgLk8xkk8u1UzW97K7FyepmRQsGoEYoUc2/P1K4G4CLBNJo7j2rLzAGpJrVafPq2WnYl9l2w/MJitPtEIkYllRtuJfT+xLMtzTPGQkl0pCQKnFMQMR6UINIJH/AspoZoXr3GEcm0gp5RwnOnCkKYpCrkmg4zRjT7siRJ91QzGqCd4DCHpS7/iiK+UFJhm0/EHwvFKLe1PVccShj9jRtepWm9i2U/Fp+xOYKVLjc9XMKKblsh+mNh3jFJeviXbO0Skbyu3lfPme3pruxlK+ZgJn4MU/ArY39bX3eKfT37yffHh8w2wSzXPkKxRtQ+XCIWzCD9Lq/lOecr9dy1NnXG05TeQ4Did2LdiBEFPXDxET+H+lN/kBciyD9jZtpkp3mL1LFbIM5h2ZcuuQGoctGPUUn8+LkClSbimVKYvIMS9RYVsyDghLryiS9/HUa/zCwgswzSAMcI5YxxhaZZYK54Q8QZE3zNiHAu2fYRLRBY0xxxT4Y/7JeWcJmKActB9KMIYMSEgcuSsJtcdJZQVait6NUpv1VxOM+klzujPmsRWLWlpME3fnEsEnjAhQ5prkspBEcxXKFIN0ZPJ7SXbWCZCA9PcM7DISrkRErqOaj9I49B2L0lBTX2RUhFNEGc7MURNuAkCv5yj0qkTlM1NKzf5SrZqpSVgqbQLVT6Ma91NThAvKi28JEU4r04RrLDzgnOEdZwG58kRJ/bUKZKEZYzwzjVJnDNJeO6lJQnLHUgSHcBRJAov1cxRnIjdPjSiGUqjW1nPSZgJzHMcCmErSNAW82+t9+/S58ZUte63CoKisVMNGa0tBGf2fO66fWSjKfIjZygWXHdmzee9uLFrIOWmDsMofEDXLEQHvBcMw92Csyo622hWMoYI5PhZN2MIYbXCguIiK1TR5HeiyfV94VZNS7kDNbFdY/Z0TXVdoK+LQxYj3tMlsIe71rBMDsgPmd1Zyp0GaqnR1gnz9CnipbSjYUKNxyvIEZyNHOb/jxzWu5LD87wqgOs48w3fbj6/SxXPORtVukv1qPI2cQ+s43HfPTFDnIfUEIe6OOdz9dRDXTtwO7Fq2q4feEOx2hzevQLgaPUxXEkUhUf75G9qgpAmkqA1y+YwwUT6/gtiEUyhEqsvQ4B1qruDr0eq5Vcwt9li+85AZVCVCyevDGxwPAhkEZft9YD65gcuq+Hmiz3jAZ0AU98Z8AzwBxIJqDLJ6WumnmO+fLz9C9RX8iUbLvH3lfMbZbUs6FPKEkiGS3rg+obA2xD7msuCcE8R38Fos8IcPWawyNUbwVWdlSPZoLMPjOOHM1CLT+Vfj+gpTVE1WZkO9hJ4FOUOxPTBM+nMsTR0Rx+VaQU4WZFrf8A0+pEhhrMVYpDkRtYpMS4j754cM6XGcbUEMXCj8vw+oN5b4TniOnXF8xCeUx3P6TvjaY8ohd78FARmtb9LOgb7l6PiGDTPcwz612Pw9yl4/Gp25liqflS85s0Xg3aZ5yAYcXu4AnoRB6FoNj9ml18hNP8xYD/8Bw== \ No newline at end of file diff --git a/docs/_include/draw.io/vpn_s2s_ikev2.drawio b/docs/_include/draw.io/vpn_s2s_ikev2.drawio new file mode 100644 index 00000000..b240c191 --- /dev/null +++ b/docs/_include/draw.io/vpn_s2s_ikev2.drawio @@ -0,0 +1 @@ +7Zrdk6I4EMD/Gh+lSMLn4zgz7j7cVk3V1H3svWxFiJhaIB7EUfevv4QEIYCje6eOW4XzIOmQTtL5ddP0OEGP2e5TgderLywm6QTa8W6CniYQIoCA+JKSvZJA2/WVJClorGSgEbzSH0QLbS3d0JiUxo2csZTTtSmMWJ6TiBsyXBRsa962ZKk56xonpCd4jXDal/5JY77SUmDbTcdnQpOVnjpwdccCR9+Tgm1yPd8EomX1Ud0ZrnXp+8sVjtm2JULPE/RYMMbVVbZ7JKk0bm02NW5+pPew7oLk/JwBv/tf4d9PP749rV+/8DAihK2iqRwg1bzhdEPqfVSr5fvaQtUeidQCJmi2XVFOXtc4kr1bAYWQrXiW6m6tjhSc7I4uFBy2L7giLCO82Itb9ICp43pqjGZqilytZNuckOM4SrZqHQ6qccSaiuSgvbGMuNDG+RlDgTs0FLADdHeWOsNQwhXW8jLbJTKqWBEtI2YJ83FSlPrbtFaMy1VlWVs0ljRNH1nKikobspEXhL6Ql7xg30mrR/tj3VP7tzDpTBqeiijwG16Q9IWVlFOWi74F45xlrRseUprIDs7kATZHLBdycGnZiFhGo3qFLOdznNFUnssfpIhxjrVYR0AAL8aA65gMwNDtMYCCAQZAEF7LW0YGbsmAg+4PATQicEsEfMe3XBOCAKCPhsA5DQGJRTqmmyVJMrHh50Y0I3n8ILM80ZuznJg4kB3lf0lbi62r1ldteXn9tGs39q0zabExQ/O55/Vpil0SxM4QTZ43g/N5jyakJ3ohBRXGk+SqyXNhSLXI6rCrdrVMK6ybzUqr1r7d6uuL51SeQtVS5pQ2fB8cYXK2KSJy+rnNcZEQfsqx+yC2IKsz5DZjtawgKeb0zVzuEHd6hhdGxUYazgMPWQFqPp30B3qmRrVrraSdHPf0hu/p9UPf8lof15xF2aw3iwAX71u3reUN5bubOxLHjy+7O8LxT4zwbfDuCHGh1t14/eGU/3sgcMdA0AoEQXDPgQD+EoHA8aDhsHbHZcWbutVx07ODAfKBBfruXqt2PTAQKy4dDKADf9K1nbqmclPXBkOZnpeK454txEXCKzqVQPqc4fXePxtWd0zLKid6EDeAYL1rOmstwIcWCCzRbYmNzqFTqxUNpdmcTYhbK+iEG5FrcTOImA6ug0w7GmgR1qlgJDyrSlC7OWJG47iKWUMlADN1vETq13sGuHY/+weO2/fFujR1+RrAUOJ3FSYs6I4YqAd7FwOvrvu0a0H+LSkYeupfhwIZ+UYI4DSEdvc1EDWiDwPBG8PBrUlw7LsLB/4YDm4MAewWBg9l/w+DILh5tgjHbLH9bhPeXbYYHkXi/xHwxmkTCBZF98DLNc6PK9/qnUv1OSsynA4gZlvyT25f+tWBI6W5h5dJXYewE/8uPLPibJYiwOSsGrQz6VU9lq78O4q5HKyXDgaQVkXyS9AK7O7LdwgGshlYv/0blQZ0JV5rR/hlgUUjsNcCtle1Ce2PpvUK7+LQGcK3qHYzPmWrUlwv8Rp8CxsokF7tMQuv8Do+DEJKliMH+vnldP9FNZSBXwYD0Wx+TqbKu82P9tDzvw== \ No newline at end of file -- cgit v1.2.3 From 371bf8185f3cd0628969a8603aa92503b2fc3853 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:08:35 +0100 Subject: rearange changelog, cli, contributing --- .gitignore | 3 + docs/about.rst | 27 -- docs/automation/index.rst | 9 + docs/changelog/1.2.1.rst | 52 ++++ docs/changelog/1.2.2.rst | 46 ++++ docs/changelog/1.2.3.rst | 62 +++++ docs/changelog/1.2.4.rst | 65 +++++ docs/changelog/1.2.5.rst | 60 +++++ docs/changelog/index.rst | 14 + docs/cli.rst | 10 +- docs/contributing/documentation.rst | 89 ++++++- docs/contributing/index.rst | 13 + docs/copyright.rst | 19 ++ docs/draw.io/pbr_example_1.drawio | 1 - docs/draw.io/vpn_s2s_ikev2.drawio | 1 - docs/history.rst | 47 ---- docs/index.rst | 108 ++------ docs/install.rst | 514 ------------------------------------ docs/installation/index.rst | 18 ++ docs/installation/install.rst | 514 ++++++++++++++++++++++++++++++++++++ docs/introducing/about.rst | 27 ++ docs/introducing/history.rst | 47 ++++ docs/introducing/releases.rst | 29 ++ docs/troubleshooting.rst | 446 ------------------------------- docs/troubleshooting/index.rst | 446 +++++++++++++++++++++++++++++++ 25 files changed, 1533 insertions(+), 1134 deletions(-) delete mode 100644 docs/about.rst create mode 100644 docs/automation/index.rst create mode 100644 docs/changelog/1.2.1.rst create mode 100644 docs/changelog/1.2.2.rst create mode 100644 docs/changelog/1.2.3.rst create mode 100644 docs/changelog/1.2.4.rst create mode 100644 docs/changelog/1.2.5.rst create mode 100644 docs/changelog/index.rst create mode 100644 docs/contributing/index.rst create mode 100644 docs/copyright.rst delete mode 100644 docs/draw.io/pbr_example_1.drawio delete mode 100644 docs/draw.io/vpn_s2s_ikev2.drawio delete mode 100644 docs/history.rst delete mode 100644 docs/install.rst create mode 100644 docs/installation/index.rst create mode 100644 docs/installation/install.rst create mode 100644 docs/introducing/about.rst create mode 100644 docs/introducing/history.rst create mode 100644 docs/introducing/releases.rst delete mode 100644 docs/troubleshooting.rst create mode 100644 docs/troubleshooting/index.rst (limited to 'docs') diff --git a/.gitignore b/.gitignore index 06d7c4cd..27188bd2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# Sphinx +_build/ + # python virtualenv venv/ ENV/ diff --git a/docs/about.rst b/docs/about.rst deleted file mode 100644 index 383c95eb..00000000 --- a/docs/about.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _about: - -##### -About -##### - -VyOS is an open source network operating system based on Debian GNU/Linux. - -VyOS provides a free routing platform that competes directly with other -commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it can be used -as a router and firewall platform for cloud deployments. - -We use multiple live versions of our manual hosted thankfully by -https://readthedocs.org. We will provide one version of the manual for every -VyOS major version starting with VyOS 1.2 which will receive Long-term support -(LTS). - -The manual version is selected/specified by its Git branch name. You can -switch between versions of the documentation by selecting the appropriate -branch on the bottom left corner. - -VyOS CLI syntax may change between major (and sometimes minor) versions. Please -always refer to the documentation matching your current, running installation. -If a change in the CLI is required, VyOS will ship a so called migration script -which will take care of adjusting the syntax. No action needs to be taken by -you. diff --git a/docs/automation/index.rst b/docs/automation/index.rst new file mode 100644 index 00000000..a3df9bc0 --- /dev/null +++ b/docs/automation/index.rst @@ -0,0 +1,9 @@ +############### +VyOS Automation +############### + + + * Ansible + * Saltstack + * HTTP-API + * startup scripts \ No newline at end of file diff --git a/docs/changelog/1.2.1.rst b/docs/changelog/1.2.1.rst new file mode 100644 index 00000000..4f22dd0a --- /dev/null +++ b/docs/changelog/1.2.1.rst @@ -0,0 +1,52 @@ +1.2.1 +===== + +VyOS 1.2.1 is a maintenance release made in April 2019. + +Resolved issues +--------------- + +* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers +* :vytask:`T1326` The kernel now includes drivers for various USB serial + adapters, which allows people to add a serial console to a machine without + onboard RS232, or connect to something else from the router +* The collection of network card firmware is now much more extensive +* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC + addresses in the RFC-compliant mode +* :vytask:`T1330` DHCP WPAD URL option works correctly again +* :vytask:`T1312` Many to many NAT rules now can use source/destination and + translation networks of non-matching size. If 1:1 network bits translation is + desired, it's now users responsibility to check if prefix length matches. +* :vytask:`T1290` IPv6 network prefix translation is fixed +* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely + used in PPPoE passwords +* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends + with a leaf node such as ``timezone`` in ``show system | commands`` +* :vytask:`T1235` ``show | commands`` correctly works in config mode now +* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option +* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest + Crux +* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses + other than loopback was fixed +* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to + start is fixed +* :vytask:`T1067` VXLAN value validation is improved +* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS + forwarding +* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with + more than one upstream interface +* :vytask:`T1234` ``relay-agents-packets`` option works correctly now +* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change +* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name +* :vytask:`T1279` ACPI power off works again +* :vytask:`T1247` Negation in WAN load balancing rules works again +* :vytask:`T1218` FRR staticd now starts on boot correctly +* :vytask:`T1296` The installer now correctly detects SD card devices +* :vytask:`T1225` Wireguard peers can be disabled now +* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete + is fixed +* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration +* :vytask:`T1060` It's now possible to exclude hosts from the transparent + web proxy +* :vytask:`T484` An issue with rules impossible to delete from the zone-based + firewall is fixed \ No newline at end of file diff --git a/docs/changelog/1.2.2.rst b/docs/changelog/1.2.2.rst new file mode 100644 index 00000000..17ba941f --- /dev/null +++ b/docs/changelog/1.2.2.rst @@ -0,0 +1,46 @@ +1.2.2 +===== + +1.2.2 is a maintenance release made in July 2019. + +New features +------------ + +* Options for per-interface MSS clamping. +* BGP extended next-hop capability +* Relaxed BGP multipath option +* Internal and external options for "remote-as" (accept any AS as long as it's + the same to this router or different, respectively) +* "Unnumbered" (interface-based) BGP peers +* BGP no-prepend option +* Additive BGP community option +* OSPFv3 network type option +* Custom arguments for VRRP scripts +* A script for querying values from config files + +Resolved issues +--------------- + +* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability +* :vytask:`T1371` VRRP health-check scripts now can use arguments +* :vytask:`T1497` DNS server addresses coming from a DHCP server are now + correctly propagated to resolv.conf +* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used + for recursive queries +* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly +* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors +* :vytask:`T1458` Correct hostname is sent to remote syslog again +* :vytask:`T1438` Board serial number from DMI is correctly displayed in + ``show version`` +* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in + remote syslog config +* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` +* :vytask:`T1174` ``system domain-name`` is correctly included in + ``/etc/resolv.conf`` +* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` + settings +* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines +* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address +* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU +* :vytask:`T1505` vyos.config ``return_effective_values()`` function now + correctly returns a list rather than a string \ No newline at end of file diff --git a/docs/changelog/1.2.3.rst b/docs/changelog/1.2.3.rst new file mode 100644 index 00000000..653beec1 --- /dev/null +++ b/docs/changelog/1.2.3.rst @@ -0,0 +1,62 @@ +1.2.3 +===== + +1.2.3 is a maintenance and feature backport release made in September 2019. + +New features +------------ + +* HTTP API +* :vytask:`T1524` "set service dns forwarding allow-from " + option for limiting queries to specific client networks +* :vytask:`T1503` Functions for checking if a commit is in progress +* :vytask:`T1543` "set system contig-mangement commit-archive source-address" + option +* :vytask:`T1554` Intel NIC drivers now support receive side scaling and + multiqueue + +Resolved issues +--------------- + +* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit + errors +* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive + lookups on domain specific forwarders +* :vytask:`T1362` Special characters in VRRP passwords are handled correctly +* :vytask:`T1377` BGP weight is applied properly +* :vytask:`T1420` Fixed permission for log files +* :vytask:`T1425` Wireguard interfaces now support /31 addresses +* :vytask:`T1428` Wireguard correctly handles firewall marks +* :vytask:`T1439` DHCPv6 static mappings now work correctly +* :vytask:`T1450` Flood ping commands now works correctly +* :vytask:`T1460` Op mode "show firewall" commands now support counters longer + than 8 digits (T1460) +* :vytask:`T1465` Fixed priority inversion in VTI commands +* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option +* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC + compatibility mode enabled +* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings +* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces +* :vytask:`T1530` Fixed "set system syslog global archive file" command +* :vytask:`T1531` Multiple fixes in cluster configuration scripts +* :vytask:`T1537` Fixed missing help text for "service dns" +* :vytask:`T1541` Fixed input validation in DHCPv6 relay options +* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall + assigned to it in one commit +* :vytask:`T1559` URL filtering now uses correct rule database path and works + again +* :vytask:`T1579` "show log vpn ipsec" command works again +* :vytask:`T1576` "show arp interface " command works again +* :vytask:`T1605` Fixed regression in L2TP/IPsec server +* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +* :vytask:`T1616` "renew dhcpv6" command now works from op mode +* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works + correctly now +* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple + improvements in name servers and hosts configuration handling + +Internals +--------- + +``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the +*vyos-hostsd* service that listens on a ZMQ socket for update messages. \ No newline at end of file diff --git a/docs/changelog/1.2.4.rst b/docs/changelog/1.2.4.rst new file mode 100644 index 00000000..397c9bb9 --- /dev/null +++ b/docs/changelog/1.2.4.rst @@ -0,0 +1,65 @@ +1.2.4 +===== + +1.2.4 is a maintenance release made in December 2019. + +Resolved issues +--------------- + +* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 +* :vytask:`T818` SNMP v3 - remove required engineid from user node +* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) +* :vytask:`T1183` BFD Support via FRR +* :vytask:`T1299` Allow SNMPd to be extended with custom scripts +* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option +* :vytask:`T1391` In route-map set community additive +* :vytask:`T1394` syslog systemd and host_name.py race condition +* :vytask:`T1401` Copying files with the FTP protocol fails if the password contains special characters +* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes to fix +* :vytask:`T1430` Add options for custom DHCP client-id and hostname +* :vytask:`T1447` Python subprocess called without import in host_name.py +* :vytask:`T1470` improve output of "show dhcpv6 server leases" +* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf +* :vytask:`T1496` Separate rolling release and LTS kernel builds +* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting +* :vytask:`T1568` strip-private command improvement for additional masking of IPv6 and MAC address +* :vytask:`T1578` completion offers "show table", but show table does not exist +* :vytask:`T1593` Support ip6gre +* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" +* :vytask:`T1638` vyos-hostsd not setting system domain name +* :vytask:`T1678` hostfile-update missing line feed +* :vytask:`T1694` NTPd: Do not listen on all interfaces by default +* :vytask:`T1701` Delete domain-name and domain-search won't work +* :vytask:`T1705` High CPU usage by bgpd when snmp is active +* :vytask:`T1707` DHCP static mapping and exclude address not working +* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 +* :vytask:`T1709` Update WireGuard to 0.0.20190913 +* :vytask:`T1716` Update Intel NIC drivers to recent versions +* :vytask:`T1726` Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 +* :vytask:`T1728` Update Linux Kernel to 4.19.79 +* :vytask:`T1737` SNMP tab completion missing +* :vytask:`T1738` Copy SNMP configuration from node to node raises exception +* :vytask:`T1740` Broken OSPFv2 virtual-link authentication +* :vytask:`T1742` NHRP unable to commit. +* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must be greater or equal to the range start address y!" when static mapping has same IP as range stop +* :vytask:`T1749` numeric validator doesn't support multiple ranges +* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) +* :vytask:`T1772` constraints in XML are partially broken +* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR +* :vytask:`T1780` Adding ipsec ike closeaction +* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py implementation +* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation +* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 +* :vytask:`T1800` Update Linux Kernel to v4.19.84 +* :vytask:`T1809` Wireless: SSID scan does not work in AP mode +* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp +* :vytask:`T1812` DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling +* :vytask:`T1819` Reboot kills SNMPv3 configuration +* :vytask:`T1822` Priority inversion wireless interface dhcpv6 +* :vytask:`T1825` Improve DHCP configuration error message +* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails to create an xml +* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" +* :vytask:`T1841` PPP ipv6-up.d direcotry missing +* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface +* :vytask:`T1903` Implementation udev predefined interface naming +* :vytask:`T1904` update eth1 and eth2 link files for the vep4600 \ No newline at end of file diff --git a/docs/changelog/1.2.5.rst b/docs/changelog/1.2.5.rst new file mode 100644 index 00000000..231e92f2 --- /dev/null +++ b/docs/changelog/1.2.5.rst @@ -0,0 +1,60 @@ +1.2.5 +===== + +1.2.5 is a maintenance release made in April 2020. + +Resolved issues +--------------- + +* :vytask:`1020` OSPF Stops distributing default route after a while +* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) +* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. +* :vytask:`1341` Adding rate-limiter for pppoe server users +* :vytask:`1376` Incorrect DHCP lease counting +* :vytask:`1392` Large firewall rulesets cause the system to lose configuration and crash at startup +* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with each other +* :vytask:`1452` accel-pppoe - add vendor option to shaper +* :vytask:`1490` BGP configuration (is lost|not applied) when updating 1.1.8 -> 1.2.1 +* :vytask:`1780` Adding ipsec ike closeaction +* :vytask:`1803` Unbind NTP while it's not requested... +* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server +* :vytask:`1827` Increase default gc_thresh +* :vytask:`1828` Missing completion helper for "set system syslog host 192.0.2.1 facility all protocol" +* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to existing package +* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' +* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to destroy the running config. +* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address +* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s +* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and validators +* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at commit time +* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding stop-script +* :vytask:`1891` Router announcements broken on boot +* :vytask:`1900` Enable SNMP for VRRP. +* :vytask:`1902` Add redistribute non main table in bgp +* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks +* :vytask:`1913` "system ipv6 blacklist" command has no effect +* :vytask:`1914` IPv6 multipath hash policy does not apply +* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 +* :vytask:`1934` Change default hostname when deploy from OVA without params. +* :vytask:`1935` NIC identification and usage problem in Hyper-V environments +* :vytask:`1936` pppoe-server CLI control features +* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit fails +* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore +* :vytask:`1970` Correct adding interfaces on boot +* :vytask:`1971` Missing modules in initrd.img for PXE boot +* :vytask:`1998` Update FRR to 7.3 +* :vytask:`2001` Error when router reboot +* :vytask:`2032` Monitor bandwidth bits +* :vytask:`2059` Set source-validation on bond vif don't work +* :vytask:`2066` PPPoE interface can be created multiple times - last wins +* :vytask:`2069` PPPoE-client does not works with service-name option +* :vytask:`2077` ISO build from crux branch is failing +* :vytask:`2079` Update Linux Kernel to v4.19.106 +* :vytask:`2087` Add maxfail 0 option to pppoe configuration. +* :vytask:`2100` BGP route adverisement wih checks rib +* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers +* :vytask:`2197` Cant add vif-s interface into a bridge +* :vytask:`2228` WireGuard does not allow ports < 1024 to be used +* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' +* :vytask:`2272` Set system flow-accounting disable-imt has syntax error +* :vytask:`2276` PPPoE server vulnerability \ No newline at end of file diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst new file mode 100644 index 00000000..26262932 --- /dev/null +++ b/docs/changelog/index.rst @@ -0,0 +1,14 @@ +######### +Changelog +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + 1.2.5 + 1.2.4 + 1.2.3 + 1.2.2 + 1.2.1 diff --git a/docs/cli.rst b/docs/cli.rst index 4694cc5d..b138b18b 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,14 +1,14 @@ .. _cli: -### -CLI -### +##################### +Comand Line Interface +##################### The VyOS :abbr:`CLI (Command-Line Interface)` comprises an operational and a configuration mode. Operational Mode -================ +################ Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the @@ -73,7 +73,7 @@ When viewing in page mode the following commands are available: in the event that the output has lines which exceed the terminal size. Configuration Mode -================== +################## The list of all operational level commands is available at :ref:`configuration_level_commands`. diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index e8d1dba5..9dd0c495 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -1,7 +1,8 @@ .. _documentation: +############# Documentation -============= +############# As most software projects we also have a lack in documentation. We encourage every VyOS user to help us improve our documentation. This will not only be @@ -15,7 +16,7 @@ guide how to do so. documentation. Forking Workflow ----------------- +================ The Forking Workflow is fundamentally different than other popular Git workflows. Instead of using a single server-side repository to act as the @@ -102,17 +103,20 @@ access to the official codebase. push origin master`` Style Guide ------------ +=========== -Sections -^^^^^^^^ +Formating and Sphinxmarkup +-------------------------- + +TOC Level +^^^^^^^^^^ We use the following syntax for Headlines. .. code-block:: none ##### - Parts + Title ##### ******** @@ -159,16 +163,17 @@ render the documentation. cfgcmd """""" -When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. An explanation of the described command should be -added below this statement. +When documenting CLI commands use the ``.. cfgcmd::`` directive +for all configuration mode commands. An explanation of the described command +should be added below this statement. +Replace all variable contents with or somthing similar. With those custom commands it will be possible to render them in a more descriptive way in the resulting HTML/PDF manual. .. code-block:: none - .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa + .. cfgcmd:: protocols static arp hwaddr This will configure a static ARP entry always resolving `192.0.2.100` to `00:53:27:de:23:aa`. @@ -250,6 +255,70 @@ URL. This is heavily used in the :ref:`release-notes` section. * :vytask:`T1605` Fixed regression in L2TP/IPsec server * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +Page content +------------ + +The documentation have 3 different types of pages, the same kind of pages must +have the same structure to achieve a recognition factor. + +For all *.rst files must follow the same TOC Level syntax and have to start with + +.. code-block:: + + ##### + Titel + ##### + +Configuration mode pages +^^^^^^^^^^^^^^^^^^^^^^^^ + +A configuration mode article covers a specific level of a command. +The exact level depends on the command. + +For example: + + * ``set zone-policy`` is written in ``zone-policy/index.rst`` + * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst`` + +The article starts with a short intruducing about the command or the technologie. +Include some helpfull links or background informations. + +After this a optional section follows. Some commands have requirements like the +compatible hardware (e.g. Wifi) or some commands you have to set before. For +example it is recommended to set a route-map before configure bgp. + +In the configuration part of the page all possible confiuration options +should be documented. Use ``.. cfgcmd::`` like described above. + +Related Operation command must be documented in the next part of the articel. +Use ``::opcmd..`` for these commands. + +If there some troubleshooting guides releated to the commands. Explain it in the +next optional part. + +Examples: + + * ssh + + + +Operation mode pages +^^^^^^^^^^^^^^^^^^^^ + +Operation mode commands, which didn't fit in a related configuraton mode command +must documented in this part of the documentation. + +.. todo:: + + create structure + + +Anything else +^^^^^^^^^^^^^ + +Anything else what is not a configuration or a operation command have no +predefined structure. + .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..c3bb2688 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,13 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 2 + + build-vyos + debugging + development + documentation + issues-features + upstream-packages \ No newline at end of file diff --git a/docs/copyright.rst b/docs/copyright.rst new file mode 100644 index 00000000..beebc2a2 --- /dev/null +++ b/docs/copyright.rst @@ -0,0 +1,19 @@ +################ +Copyright Notice +################ + +Copyright (C) 2018-2020 VyOS maintainers and contributors + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on all +copies. + +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided that the entire resulting +derived work is distributed under the terms of a permission notice identical +to this one. + +Permission is granted to copy and distribute translations of this manual into +another language, under the above conditions for modified versions, except that +this permission notice may be stated in a translation approved by the VyOS +maintainers. \ No newline at end of file diff --git a/docs/draw.io/pbr_example_1.drawio b/docs/draw.io/pbr_example_1.drawio deleted file mode 100644 index 0d496572..00000000 --- a/docs/draw.io/pbr_example_1.drawio +++ /dev/null @@ -1 +0,0 @@ -7VrbcqM4EP0aP4ZCgLk8xkk8u1UzW97K7FyepmRQsGoEYoUc2/P1K4G4CLBNJo7j2rLzAGpJrVafPq2WnYl9l2w/MJitPtEIkYllRtuJfT+xLMtzTPGQkl0pCQKnFMQMR6UINIJH/AspoZoXr3GEcm0gp5RwnOnCkKYpCrkmg4zRjT7siRJ91QzGqCd4DCHpS7/iiK+UFJhm0/EHwvFKLe1PVccShj9jRtepWm9i2U/Fp+xOYKVLjc9XMKKblsh+mNh3jFJeviXbO0Skbyu3lfPme3pruxlK+ZgJn4MU/ArY39bX3eKfT37yffHh8w2wSzXPkKxRtQ+XCIWzCD9Lq/lOecr9dy1NnXG05TeQ4Did2LdiBEFPXDxET+H+lN/kBciyD9jZtpkp3mL1LFbIM5h2ZcuuQGoctGPUUn8+LkClSbimVKYvIMS9RYVsyDghLryiS9/HUa/zCwgswzSAMcI5YxxhaZZYK54Q8QZE3zNiHAu2fYRLRBY0xxxT4Y/7JeWcJmKActB9KMIYMSEgcuSsJtcdJZQVait6NUpv1VxOM+klzujPmsRWLWlpME3fnEsEnjAhQ5prkspBEcxXKFIN0ZPJ7SXbWCZCA9PcM7DISrkRErqOaj9I49B2L0lBTX2RUhFNEGc7MURNuAkCv5yj0qkTlM1NKzf5SrZqpSVgqbQLVT6Ma91NThAvKi28JEU4r04RrLDzgnOEdZwG58kRJ/bUKZKEZYzwzjVJnDNJeO6lJQnLHUgSHcBRJAov1cxRnIjdPjSiGUqjW1nPSZgJzHMcCmErSNAW82+t9+/S58ZUte63CoKisVMNGa0tBGf2fO66fWSjKfIjZygWXHdmzee9uLFrIOWmDsMofEDXLEQHvBcMw92Csyo622hWMoYI5PhZN2MIYbXCguIiK1TR5HeiyfV94VZNS7kDNbFdY/Z0TXVdoK+LQxYj3tMlsIe71rBMDsgPmd1Zyp0GaqnR1gnz9CnipbSjYUKNxyvIEZyNHOb/jxzWu5LD87wqgOs48w3fbj6/SxXPORtVukv1qPI2cQ+s43HfPTFDnIfUEIe6OOdz9dRDXTtwO7Fq2q4feEOx2hzevQLgaPUxXEkUhUf75G9qgpAmkqA1y+YwwUT6/gtiEUyhEqsvQ4B1qruDr0eq5Vcwt9li+85AZVCVCyevDGxwPAhkEZft9YD65gcuq+Hmiz3jAZ0AU98Z8AzwBxIJqDLJ6WumnmO+fLz9C9RX8iUbLvH3lfMbZbUs6FPKEkiGS3rg+obA2xD7msuCcE8R38Fos8IcPWawyNUbwVWdlSPZoLMPjOOHM1CLT+Vfj+gpTVE1WZkO9hJ4FOUOxPTBM+nMsTR0Rx+VaQU4WZFrf8A0+pEhhrMVYpDkRtYpMS4j754cM6XGcbUEMXCj8vw+oN5b4TniOnXF8xCeUx3P6TvjaY8ohd78FARmtb9LOgb7l6PiGDTPcwz612Pw9yl4/Gp25liqflS85s0Xg3aZ5yAYcXu4AnoRB6FoNj9ml18hNP8xYD/8Bw== \ No newline at end of file diff --git a/docs/draw.io/vpn_s2s_ikev2.drawio b/docs/draw.io/vpn_s2s_ikev2.drawio deleted file mode 100644 index b240c191..00000000 --- a/docs/draw.io/vpn_s2s_ikev2.drawio +++ /dev/null @@ -1 +0,0 @@ -7Zrdk6I4EMD/Gh+lSMLn4zgz7j7cVk3V1H3svWxFiJhaIB7EUfevv4QEIYCje6eOW4XzIOmQTtL5ddP0OEGP2e5TgderLywm6QTa8W6CniYQIoCA+JKSvZJA2/WVJClorGSgEbzSH0QLbS3d0JiUxo2csZTTtSmMWJ6TiBsyXBRsa962ZKk56xonpCd4jXDal/5JY77SUmDbTcdnQpOVnjpwdccCR9+Tgm1yPd8EomX1Ud0ZrnXp+8sVjtm2JULPE/RYMMbVVbZ7JKk0bm02NW5+pPew7oLk/JwBv/tf4d9PP749rV+/8DAihK2iqRwg1bzhdEPqfVSr5fvaQtUeidQCJmi2XVFOXtc4kr1bAYWQrXiW6m6tjhSc7I4uFBy2L7giLCO82Itb9ICp43pqjGZqilytZNuckOM4SrZqHQ6qccSaiuSgvbGMuNDG+RlDgTs0FLADdHeWOsNQwhXW8jLbJTKqWBEtI2YJ83FSlPrbtFaMy1VlWVs0ljRNH1nKikobspEXhL6Ql7xg30mrR/tj3VP7tzDpTBqeiijwG16Q9IWVlFOWi74F45xlrRseUprIDs7kATZHLBdycGnZiFhGo3qFLOdznNFUnssfpIhxjrVYR0AAL8aA65gMwNDtMYCCAQZAEF7LW0YGbsmAg+4PATQicEsEfMe3XBOCAKCPhsA5DQGJRTqmmyVJMrHh50Y0I3n8ILM80ZuznJg4kB3lf0lbi62r1ldteXn9tGs39q0zabExQ/O55/Vpil0SxM4QTZ43g/N5jyakJ3ohBRXGk+SqyXNhSLXI6rCrdrVMK6ybzUqr1r7d6uuL51SeQtVS5pQ2fB8cYXK2KSJy+rnNcZEQfsqx+yC2IKsz5DZjtawgKeb0zVzuEHd6hhdGxUYazgMPWQFqPp30B3qmRrVrraSdHPf0hu/p9UPf8lof15xF2aw3iwAX71u3reUN5bubOxLHjy+7O8LxT4zwbfDuCHGh1t14/eGU/3sgcMdA0AoEQXDPgQD+EoHA8aDhsHbHZcWbutVx07ODAfKBBfruXqt2PTAQKy4dDKADf9K1nbqmclPXBkOZnpeK454txEXCKzqVQPqc4fXePxtWd0zLKid6EDeAYL1rOmstwIcWCCzRbYmNzqFTqxUNpdmcTYhbK+iEG5FrcTOImA6ug0w7GmgR1qlgJDyrSlC7OWJG47iKWUMlADN1vETq13sGuHY/+weO2/fFujR1+RrAUOJ3FSYs6I4YqAd7FwOvrvu0a0H+LSkYeupfhwIZ+UYI4DSEdvc1EDWiDwPBG8PBrUlw7LsLB/4YDm4MAewWBg9l/w+DILh5tgjHbLH9bhPeXbYYHkXi/xHwxmkTCBZF98DLNc6PK9/qnUv1OSsynA4gZlvyT25f+tWBI6W5h5dJXYewE/8uPLPibJYiwOSsGrQz6VU9lq78O4q5HKyXDgaQVkXyS9AK7O7LdwgGshlYv/0blQZ0JV5rR/hlgUUjsNcCtle1Ce2PpvUK7+LQGcK3qHYzPmWrUlwv8Rp8CxsokF7tMQuv8Do+DEJKliMH+vnldP9FNZSBXwYD0Wx+TqbKu82P9tDzvw== \ No newline at end of file diff --git a/docs/history.rst b/docs/history.rst deleted file mode 100644 index 9a13e2b3..00000000 --- a/docs/history.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _history: - -####### -History -####### - -VyOS is a Linux-based network operating system that provides software-based -network routing, firewall, and VPN functionality. - -The VyOS project was started in late 2013 as a community fork of the -`GPL `_ portions of -Vyatta Core 6.6R1 with the goal of maintaining a free and open source network -operating system in response to the decision to discontinue the community -edition of Vyatta. Here everyone loves learning, older managers and new users. - -VyOS is primarily based on `Debian GNU/Linux `_ and -the `Quagga `_ routing engine. Its configuration -syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the -`XORP project `_, which was the original routing engine -for Vyatta. - -In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of -VyOS version 1.2, VyOS now uses `FRRouting `_ as the -routing engine. - -How is VyOS different from any other router distributions and platform? - -- It's more than just a firewall and VPN, VyOS includes extended routing - capabilities like OSPFv2, OSPFv3, BGP, VRRP, and extensive route policy - mapping and filtering -- Unified command line interface in the style of hardware routers. -- Scriptable CLI -- Stateful configuration system: prepare changes and commit at once or discard, - view previous revisions or rollback to them, archive revisions to remote - server and execute hooks at commit time -- Image-based upgrade: keep multiple versions on the same system and revert to - previous image if a problem arises -- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard, DPMVPN, IKEv2 and more -- DHCP, TFTP, mDNS repeater, broadcast relay and DNS forwarding support -- Both IPv4 and IPv6 support -- Runs on physical and virtual platforms alike: small x86 boards, big servers, - KVM, Xen, VMware, Hyper-V, and more -- Completely free and open source, with documented internal APIs and build - procedures -- Community driven. Patches are welcome and all code, bugs, and nightly builds - are publicly accessible - diff --git a/docs/index.rst b/docs/index.rst index ab9d3f66..3322bf8d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,102 +6,44 @@ VyOS User Guide .. toctree:: - :caption: Introduction - :name: intro :maxdepth: 2 + :hidden: + :caption: FIND CAPTION NAME - about - history - install - cli - quick-start - + introducing/about + introducing/history + introducing/releases + changelog/index .. toctree:: - :caption: Basic Configuration - :name: basics :maxdepth: 2 + :hidden: + :includehidden: + :caption: first steps - configuration-overview - interfaces/basic-index - system/basic-index - image-mgmt - - -.. toctree:: - :caption: Advanced Configuration - :name: advanced - :maxdepth: 2 - - interfaces/advanced-index - system/advanced-index - services/index - firewall - routing/index - vrf - nat - nptv6 - qos - high-availability - vpn/index - load-balancing - command-list-configuration - + installation/index + quick-start + cli + .. toctree:: - :caption: System Operation - :name: system-operation :maxdepth: 2 + :hidden: + :includehidden: + :caption: Adminguide - information - troubleshooting - command-list-operation + configuration/index + operation/index + automation/index + troubleshooting/index + configexamples/index .. toctree:: - :caption: Appendix - :name: appendix :maxdepth: 2 - - appendix/release-notes - appendix/examples/index - appendix/vyos-on-baremetal - appendix/virtual/index - appendix/vyos-on-clouds - appendix/migrate-from-vyatta - appendix/command-scripting - appendix/http-api - - -.. toctree:: + :hidden: + :includehidden: :caption: Contributing - :name: contributing - :maxdepth: 2 - - contributing/build-vyos - contributing/upstream-packages - contributing/issues-features - contributing/development - contributing/debugging - contributing/documentation - - -################ -Copyright Notice -################ - -Copyright (C) 2018-2020 VyOS maintainers and contributors - -Permission is granted to make and distribute verbatim copies of this manual -provided the copyright notice and this permission notice are preserved on all -copies. - -Permission is granted to copy and distribute modified versions of this manual -under the conditions for verbatim copying, provided that the entire resulting -derived work is distributed under the terms of a permission notice identical -to this one. -Permission is granted to copy and distribute translations of this manual into -another language, under the above conditions for modified versions, except that -this permission notice may be stated in a translation approved by the VyOS -maintainers. + contributing/index + copyright diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index 11d0fc88..00000000 --- a/docs/install.rst +++ /dev/null @@ -1,514 +0,0 @@ -.. _installation: - -############ -Installation -############ - -VyOS installation requires to download a VyOS .iso file. That file is -a live install image that lets you boot a live VyOS. From that live -system you can proceed to the permanent installation on a hard drive or -any other type of storage. - - -Hardware requirements -===================== - -The minimum system requirements are 512 MiB RAM and 2 GiB storage. -Depending on your use you might need additional RAM and CPU resources e.g. -when having multiple BGP full tables in your system. - -Download -======== - -Registered Subscribers ----------------------- - -Registered subscribers can log into https://support.vyos.io/ to have access to -a variety of different downloads via the "Downloads" link. These downloads -include LTS (Long-Term-Support) and associated hot-fix releases, early public -access releases, pre-built VM images, as well as device specific installation -ISOs. - -.. figure:: /_static/images/vyos-downloads.png - -Building from source ----------------------- - -Non-subscribers can always get the LTS release by building it from source. -Instruction can be found in the :ref:`build` section of this manual. VyOS -source code repository is available for everyone at -https://github.com/vyos/vyos-build. - -Rolling Release ---------------- - -Everyone can download bleeding-edge VyOS rolling images from: -https://downloads.vyos.io/ - -.. note:: Rolling releases contain all the latest enhancements and fixes. This - means that there will be new bugs of course. If you think you hit a bug - please follow the guide at :ref:`bug_report`. To improve VyOS we depend on - your feedback! - -The following link will always fetch the most recent VyOS build for AMD64 -systems from the current branch: -https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - - -Download Verification ---------------------- - -LTS images are signed by VyOS lead package-maintainer private key. With -the official public key, the authenticity of the package can be -verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. - -.. note:: This subsection only applies e applies to LTS images, for - Rolling images please jump to :ref:`live_installation`. - -Preparing for the verification -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -First, install GPG or another OpenPGP implementation. On most GNU+Linux -distributions it is installed by default as package managers use it to -verify package signatures. If not pre-installed, it will need to be -downloaded and installed. - -The official VyOS public key can be retrieved in a number of ways. Skip -to :ref:`gpg-verification` if the key is already present. - -It can be retrieved directly from a key server: - -``gpg --recv-keys FD220285A0FE6D7E`` - -Or it can be accessed via a web browser: - -https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E - -Or from the following block: - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - mQINBFXKsiIBEACyid9PR/v56pSRG8VgQyRwvzoI7rLErZ8BCQA2WFxA6+zNy+6G - +0E/6XAOzE+VHli+wtJpiVJwAh+wWuqzOmv9css2fdJxpMW87pJAS2i3EVVVf6ab - wU848JYLGzc9y7gZrnT1m2fNh4MXkZBNDp780WpOZx8roZq5X+j+Y5hk5KcLiBn/ - lh9Zoh8yzrWDSXQsz0BGoAbVnLUEWyo0tcRcHuC0eLx6oNG/IHvd/+kxWB1uULHU - SlB/6vcx56lLqgzywkmhP01050ZDyTqrFRIfrvw6gLQaWlgR3lB93txvF/sz87Il - VblV7e6HEyVUQxedDS8ikOyzdb5r9a6Zt/j8ZPSntFNM6OcKAI7U1nDD3FVOhlVn - 7lhUiNc+/qjC+pR9CrZjr/BTWE7Zpi6/kzeH4eAkfjyALj18oC5udJDjXE5daTL3 - k9difHf74VkZm29Cy9M3zPckOZpsGiBl8YQsf+RXSBMDVYRKZ1BNNLDofm4ZGijK - mriXcaY+VIeVB26J8m8y0zN4/ZdioJXRcy72c1KusRt8e/TsqtC9UFK05YpzRm5R - /nwxDFYb7EdY/vHUFOmfwXLaRvyZtRJ9LwvRUAqgRbbRZg3ET/tn6JZk8hqx3e1M - IxuskOB19t5vWyAo/TLGIFw44SErrq9jnpqgclTSRgFjcjHEm061r4vjoQARAQAB - tDZWeU9TIE1haW50YWluZXJzIChWeU9TIFJlbGVhc2UpIDxtYWludGFpbmVyc0B2 - eW9zLm5ldD6JAjgEEwECACIFAlXKsiICGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4B - AheAAAoJEP0iAoWg/m1+xbgP+QEDYZi5dA4IPY+vU1L95Bavju2m2o35TSUDPg5B - jfAGuhbsNUceU+l/yUlxjpKEmvshyW3GHR5QzUaKGup/ZDBo1CBxZNhpSlFida2E - KAYTx4vHk3MRXcntiAj/hIJwRtzCUp5UQIqHoU8dmHoHOkKEP+zhJuR6E2s+WwDr - nTwE6eRa0g/AHY+chj2Je6flpPm2CKoTfUE7a2yBBU3wPq3rGtsQgVxPAxHRZz7A - w4AjH3NM1Uo3etuiDnGkJAuoKKb1J4X3w2QlbwlR4cODLKhJXHIufwaGtRwEin9S - 1l2bL8V3gy2Hv3D2t9TQZuR5NUHsibJRXLSa8WnSCcc6Bij5aqfdpYB+YvKH/rIm - GvYPmLZDfKGkx0JE4/qtfFjiPJ5VE7BxNyliEw/rnQsxWAGPqLlL61SD8w5jGkw3 - CinwO3sccTVcPz9b6A1RsbBVhTJJX5lcPn1lkOEVwQ7l8bRhOKCMe0P53qEDcLCd - KcXNnAFbVes9u+kfUQ4oxS0G2JS9ISVNmune+uv+JR7KqSdOuRYlyXA9uTjgWz4y - Cs7RS+CpkJFqrqOtS1rmuDW9Ea4PA8ygGlisM5d/AlVkniHz/2JYtgetiLCj9mfE - MzQpgnldNSPumKqJ3wwmCNisE+lXQ5UXCaoaeqF/qX1ykybQn41LQ+0xT5Uvy7sL - 9IwGuQINBFXKsiIBEACg2mP3QYkXdgWTK5JyTGyttE6bDC9uqsK8dc1J66Tjd5Ly - Be0amO+88GHXa0o5Smwk2QNoxsRR41G/D/eAeGsuOEYnePROEr3tcLnDjo4KLgQ+ - H69zRPn77sdP3A34Jgp+QIzByJWM7Cnim31quQP3qal2QdpGJcT/jDJWdticN76a - Biaz+HN13LyvZM+DWhUDttbjAJc+TEwF9YzIrU+3AzkTRDWkRh4kNIQxjlpNzvho - 9V75riVqg2vtgPwttPEhOLb0oMzy4ADdfezrfVvvMb4M4kY9npu4MlSkNTM97F/I - QKy90JuSUIjE05AO+PDXJF4Fd5dcpmukLV/2nV0WM2LAERpJUuAgkZN6pNUFVISR - +nSfgR7wvqeDY9NigHrJqJbSEgaBUs6RTk5hait2wnNKLJajlu3aQ2/QfRT/kG3h - ClKUz3Ju7NCURmFE6mfsdsVrlIsEjHr/dPbXRswXgC9FLlXpWgAEDYi9Wdxxz8o9 - JDWrVYdKRGG+OpLFh8AP6QL3YnZF+p1oxGUQ5ugXauAJ9YS55pbzaUFP8oOO2P1Q - BeYnKRs1GcMI8KWtE/fze9C9gZ7Dqju7ZFEyllM4v3lzjhT8muMSAhw41J22mSx6 - VRkQVRIAvPDFES45IbB6EEGhDDg4pD2az8Q7i7Uc6/olEmpVONSOZEEPsQe/2wAR - AQABiQIfBBgBAgAJBQJVyrIiAhsMAAoJEP0iAoWg/m1+niUQAKTxwJ9PTAfB+XDk - 3qH3n+T49O2wP3fhBI0EGhJp9Xbx29G7qfEeqcQm69/qSq2/0HQOc+w/g8yy71jA - 6rPuozCraoN7Im09rQ2NqIhPK/1w5ZvgNVC0NtcMigX9MiSARePKygAHOPHtrhyO - rJQyu8E3cV3VRT4qhqIqXs8Ydc9vL3ZrJbhcHQuSLdZxM1k+DahCJgwWabDCUizm - sVP3epAP19FP8sNtHi0P1LC0kq6/0qJot+4iBiRwXMervCD5ExdOm2ugvSgghdYN - BikFHvmsCxbZAQjykQ6TMn+vkmcEz4fGAn4L7Nx4paKEtXaAFO8TJmFjOlGUthEm - CtHDKjCTh9WV4pwG2WnXuACjnJcs6LcK377EjWU25H4y1ff+NDIUg/DWfSS85iIc - UgkOlQO6HJy0O96L5uxn7VJpXNYFa20lpfTVZv7uu3BC3RW/FyOYsGtSiUKYq6cb - CMxGTfFxGeynwIlPRlH68BqH6ctR/mVdo+5UIWsChSnNd1GreIEI6p2nBk3mc7jZ - 7pTEHpjarwOjs/S/lK+vLW53CSFimmW4lw3MwqiyAkxl0tHAT7QMHH9Rgw2HF/g6 - XD76fpFdMT856dsuf+j2uuJFlFe5B1fERBzeU18MxML0VpDmGFEaxxypfACeI/iu - 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb - =Ld8S - -----END PGP PUBLIC KEY BLOCK----- - -Store the key in a new text file and import it into GPG via: ``gpg --import -file_with_the_public_key`` - -The import can be verified with: - -.. code-block:: none - - $ gpg --list-keys - ... - pub rsa4096 2015-08-12 [SC] - 0694A9230F5139BF834BA458FD220285A0FE6D7E - uid [ unknown] VyOS Maintainers (VyOS Release) - sub rsa4096 2015-08-12 [E] - -.. _gpg-verification: - -GPG verification -^^^^^^^^^^^^^^^^ - -With the public key imported, the signature for the desired image needs -to be downloaded. - -.. note:: The signature can be downloaded by appending `.asc` to the URL of the - downloaded VyOS image. That small *.asc* file is the signature for the - associated image. - -Finally, verify the authenticity of the downloaded image: - -.. code-block:: none - - $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso - gpg: Signature made So 14 Apr 12:58:07 2019 CEST - gpg: using RSA key FD220285A0FE6D7E - gpg: Good signature from "VyOS Maintainers (VyOS Release) " [unknown] - Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E - -.. _live_installation: - -Live installation -================= - -.. note:: A permanent VyOS installation always requires to go first - through a live installation. - -VyOS, as other GNU+Linux distributions, can be tasted without installing -it in your hard drive. **With your downloaded VyOS .iso file you can -create a bootable USB drive that will let you boot into a fully -functional VyOS system**. Once you have tested it, you can either decide -to begin a :ref:`permanent_installation` in your hard drive or power -your system off, remove the USB drive, and leave everythng as it was. - - -If you have a GNU+Linux system, you can create your VyOS bootable USB -stick with with the ``dd`` command: - - 1. Open your terminal emulator. - - 2. Find out the device name of your USB drive (you can use the ``lsblk`` - command) - - 3. Unmount the USB drive. Replace X in the example below with the - letter of your device and keep the asterisk (wildcard) to unmount - all partitions. - - .. code-block:: none - - $ umount /dev/sdX* - - 4. Write the image (your VyOS .iso file) to the USB drive. - Note that here you want to use the device name (e.g. /dev/sdb), not - the partition name (e.g. /dev/sdb1). - - **Warning**: This will destroy all data on the USB drive! - - .. code-block:: none - - # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync - - 5. Wait until you get the outcome (bytes copied). Be patient, in some - computers it might take more than one minute. - - 6. Once ``dd`` has finished, pull the USB drive out and plug it into - the powered-off computer where you want to install (or test) VyOS. - - 7. Power the computer on, making sure it boots from the USB drive (you - might need to select booting device or change booting settings). - - 8. Once VyOS is completely loaded, enter the default credentials - (login: vyos, password: vyos). - - -If you find difficulties with this method, prefer to use a GUI program, -or have a different operating system, there are other programs you can -use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, -macOS and Windows), Rufus_ (for Windows) and `many others`_. You can -follow their instructions to create a bootable USB drive from an .iso -file. - -.. hint:: The default username and password for the live system is *vyos*. - - -.. _permanent_installation: - -Permanent installation -====================== - -.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`. - -Unlike general purpose Linux distributions, VyOS uses "image installation" that -mimics the user experience of traditional hardware routers and allows keeping -multiple VyOS versions installed simultaneously. This makes it possible to -switch to a previous version if something breaks or miss-behaves after an image -upgrade. - -Every version is contained in its own squashfs image that is mounted in a union -filesystem together with a directory for mutable data such as configurations, -keys, or custom scripts. - -.. note:: Older versions (prior to VyOS 1.1) used to support non-image - installation (``install system`` command). Support for this has been removed - from VyOS 1.2 and newer releases. Older releases can still be upgraded via - the general ``add system image `` upgrade command (consult - :ref:`image-mgmt` for further information). - - -In order to proceed with a permanent installation: - - 1. Log into the VyOS live system (use the default credentials: vyos, - vyos) - - 2. Run the ``install image`` command and follow the wizard: - - .. code-block:: none - - vyos@vyos:~$ install image - Welcome to the VyOS install program. This script - will walk you through the process of installing the - VyOS image to a local hard drive. - Would you like to continue? (Yes/No) [Yes]: Yes - Probing drives: OK - Looking for pre-existing RAID groups...none found. - The VyOS image will require a minimum 2000MB root. - Would you like me to try to partition a drive automatically - or would you rather partition it manually with parted? If - you have already setup your partitions, you may skip this step - - Partition (Auto/Parted/Skip) [Auto]: - - I found the following drives on your system: - sda 4294MB - - Install the image on? [sda]: - - This will destroy all data on /dev/sda. - Continue? (Yes/No) [No]: Yes - - How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: - - Creating filesystem on /dev/sda1: OK - Done! - Mounting /dev/sda1... - What would you like to name this image? [1.2.0-rolling+201809210337]: - OK. This image will be named: 1.2.0-rolling+201809210337 - Copying squashfs image... - Copying kernel and initrd images... - Done! - I found the following configuration files: - /opt/vyatta/etc/config.boot.default - Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: - - Copying /opt/vyatta/etc/config.boot.default to sda. - Enter password for administrator account - Enter password for user 'vyos': - Retype password for user 'vyos': - I need to install the GRUB boot loader. - I found the following drives on your system: - sda 4294MB - - Which drive should GRUB modify the boot partition on? [sda]: - - Setting up grub: OK - Done! - - - 3. After the installation is complete, remove the live USB stick or - CD. - - 4. Reboot the system. - - .. code-block:: none - - vyos@vyos:~$ reboot - Proceed with reboot? (Yes/No) [No] Yes - - You will boot now into a permanent VyOS system. - - -PXE Boot -======== - -VyOS can also be installed through PXE. This is a more complex -installation method which allows deploying VyOS through the network. - -**Requirements** - -* Clients (where VyOS is to be installed) with a PXE-enabled NIC -* :ref:`dhcp-server` -* :ref:`tftp-server` -* Webserver (HTTP) - optional, but we will use it to speed up installation -* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) -* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution `_ - -Configuration -------------- - -Step 1: DHCP -^^^^^^^^^^^^ - -Configure a DHCP server to provide the client with: - -* An IP address -* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* -* The *bootfile name* (DHCP option 67), which is *pxelinux.0* - -In this example we configured an existent VyOS as the DHCP server: - -.. code-block:: none - - vyos@vyos# show service dhcp-server - shared-network-name mydhcp { - subnet 192.168.1.0/24 { - bootfile-name pxelinux.0 - bootfile-server 192.168.1.50 - default-router 192.168.1.50 - range 0 { - start 192.168.1.70 - stop 192.168.1.100 - } - } - } - -.. _install_from_tftp: - -Step 2: TFTP -^^^^^^^^^^^^ - -Configure a TFTP server so that it serves the following: - -* The *pxelinux.0* file from the Syslinux distribution -* The *ldlinux.c32* file from the Syslinux distribution -* The kernel of the VyOS software you want to deploy. That is the - *vmlinuz* file inside the */live* directory of the extracted - contents from the ISO file. -* The initial ramdisk of the VyOS ISO you want to deploy. That is the - *initrd.img* file inside the */live* directory of the extracted - contents from the ISO file. Do not use an empty (0 bytes) initrd.img - file you might find, the correct file may have a longer name. -* A directory named pxelinux.cfg which must contain the configuration - file. We will use the configuration_ file shown below, which we named - default_. - -.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config -.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration - -In the example we configured our existent VyOS as the TFTP server too: - -.. code-block:: none - - vyos@vyos# show service tftp-server - directory /config/tftpboot - listen-address 192.168.1.50 - -Example of the contents of the TFTP server: - -.. code-block:: none - - vyos@vyos# ls -hal /config/tftpboot/ - total 29M - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . - drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. - -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos - -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 - -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg - -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz - - vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg - total 12K - drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . - drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. - -rw-r--r-- 1 root root 191 Oct 14 01:10 default - -Example of simple (no menu) configuration file: - -.. code-block:: none - - vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default - DEFAULT VyOS123 - - LABEL VyOS123 - KERNEL vmlinuz - APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs - -Step 3: HTTP -^^^^^^^^^^^^ - -We also need to provide the *filesystem.squashfs* file. That is a heavy -file and TFTP is slow, so you could send it through HTTP to speed up the -transfer. That is how it is done in our example, you can find that in -the configuration file above. - -**First** run a web server - you can use a simple one like -`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` -file. The file can be found inside the `/live` directory of the -extracted contents of the ISO file. - -**Second**, edit the configuration file of the :ref:`install_from_tftp` -so that it shows the correct URL at -``fetch=http:///filesystem.squashfs``. - -.. note:: Do not change the name of the *filesystem.squashfs* file. If - you are working with different versions, you can create different - directories instead. - -And **third**, restart the TFTP service. If you are using VyOS as your -TFTP Server, you can restart the service with -``sudo service tftpd-hpa restart``. - -.. note:: Make sure the available directories and files in both TFTP - and HTTP server have the right permissions to be accessed from the - booting clients. - -.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html - -Client Boot ------------ - -Finally, turn on your PXE-enabled client or clients. They will -automatically get an IP address from the DHCP server and start booting -into VyOS live from the files automatically taken from the TFTP and HTTP -servers. - -Once finished you will be able to proceed with the ``install image`` -command as in a regular VyOS installation. - - - -Known Issues -============ - -This is a list of known issues that can arise during installation. - -Black screen on install ------------------------ - -GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. -This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a -black screen after selecting the `Live system` option from the installation image. - -The workaround is to type `e` when the boot menu appears and edit the GRUB boot options. Specifically, remove the: - -`console=ttyS0,115200` - -option, and type CTRL-X to boot. - -Installation can then continue as outlined above. - -.. _SYSLINUX: http://www.syslinux.org/ -.. _balenaEtcher: https://www.balena.io/etcher/ -.. _Rufus: https://rufus.ie/ -.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems diff --git a/docs/installation/index.rst b/docs/installation/index.rst new file mode 100644 index 00000000..af265121 --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,18 @@ +################################# +Installation and Image Management +################################# + + + +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + iso + virtual/index + cloud/index + update + image + migrate-from-vyatta + ../vyos-on-baremetal \ No newline at end of file diff --git a/docs/installation/install.rst b/docs/installation/install.rst new file mode 100644 index 00000000..11d0fc88 --- /dev/null +++ b/docs/installation/install.rst @@ -0,0 +1,514 @@ +.. _installation: + +############ +Installation +############ + +VyOS installation requires to download a VyOS .iso file. That file is +a live install image that lets you boot a live VyOS. From that live +system you can proceed to the permanent installation on a hard drive or +any other type of storage. + + +Hardware requirements +===================== + +The minimum system requirements are 512 MiB RAM and 2 GiB storage. +Depending on your use you might need additional RAM and CPU resources e.g. +when having multiple BGP full tables in your system. + +Download +======== + +Registered Subscribers +---------------------- + +Registered subscribers can log into https://support.vyos.io/ to have access to +a variety of different downloads via the "Downloads" link. These downloads +include LTS (Long-Term-Support) and associated hot-fix releases, early public +access releases, pre-built VM images, as well as device specific installation +ISOs. + +.. figure:: /_static/images/vyos-downloads.png + +Building from source +---------------------- + +Non-subscribers can always get the LTS release by building it from source. +Instruction can be found in the :ref:`build` section of this manual. VyOS +source code repository is available for everyone at +https://github.com/vyos/vyos-build. + +Rolling Release +--------------- + +Everyone can download bleeding-edge VyOS rolling images from: +https://downloads.vyos.io/ + +.. note:: Rolling releases contain all the latest enhancements and fixes. This + means that there will be new bugs of course. If you think you hit a bug + please follow the guide at :ref:`bug_report`. To improve VyOS we depend on + your feedback! + +The following link will always fetch the most recent VyOS build for AMD64 +systems from the current branch: +https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + + +Download Verification +--------------------- + +LTS images are signed by VyOS lead package-maintainer private key. With +the official public key, the authenticity of the package can be +verified. :abbr:`GPG (GNU Privacy Guard)` is used for verification. + +.. note:: This subsection only applies e applies to LTS images, for + Rolling images please jump to :ref:`live_installation`. + +Preparing for the verification +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +First, install GPG or another OpenPGP implementation. On most GNU+Linux +distributions it is installed by default as package managers use it to +verify package signatures. If not pre-installed, it will need to be +downloaded and installed. + +The official VyOS public key can be retrieved in a number of ways. Skip +to :ref:`gpg-verification` if the key is already present. + +It can be retrieved directly from a key server: + +``gpg --recv-keys FD220285A0FE6D7E`` + +Or it can be accessed via a web browser: + +https://pgp.mit.edu/pks/lookup?op=get&search=0xFD220285A0FE6D7E + +Or from the following block: + +.. code-block:: none + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (GNU/Linux) + + mQINBFXKsiIBEACyid9PR/v56pSRG8VgQyRwvzoI7rLErZ8BCQA2WFxA6+zNy+6G + +0E/6XAOzE+VHli+wtJpiVJwAh+wWuqzOmv9css2fdJxpMW87pJAS2i3EVVVf6ab + wU848JYLGzc9y7gZrnT1m2fNh4MXkZBNDp780WpOZx8roZq5X+j+Y5hk5KcLiBn/ + lh9Zoh8yzrWDSXQsz0BGoAbVnLUEWyo0tcRcHuC0eLx6oNG/IHvd/+kxWB1uULHU + SlB/6vcx56lLqgzywkmhP01050ZDyTqrFRIfrvw6gLQaWlgR3lB93txvF/sz87Il + VblV7e6HEyVUQxedDS8ikOyzdb5r9a6Zt/j8ZPSntFNM6OcKAI7U1nDD3FVOhlVn + 7lhUiNc+/qjC+pR9CrZjr/BTWE7Zpi6/kzeH4eAkfjyALj18oC5udJDjXE5daTL3 + k9difHf74VkZm29Cy9M3zPckOZpsGiBl8YQsf+RXSBMDVYRKZ1BNNLDofm4ZGijK + mriXcaY+VIeVB26J8m8y0zN4/ZdioJXRcy72c1KusRt8e/TsqtC9UFK05YpzRm5R + /nwxDFYb7EdY/vHUFOmfwXLaRvyZtRJ9LwvRUAqgRbbRZg3ET/tn6JZk8hqx3e1M + IxuskOB19t5vWyAo/TLGIFw44SErrq9jnpqgclTSRgFjcjHEm061r4vjoQARAQAB + tDZWeU9TIE1haW50YWluZXJzIChWeU9TIFJlbGVhc2UpIDxtYWludGFpbmVyc0B2 + eW9zLm5ldD6JAjgEEwECACIFAlXKsiICGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4B + AheAAAoJEP0iAoWg/m1+xbgP+QEDYZi5dA4IPY+vU1L95Bavju2m2o35TSUDPg5B + jfAGuhbsNUceU+l/yUlxjpKEmvshyW3GHR5QzUaKGup/ZDBo1CBxZNhpSlFida2E + KAYTx4vHk3MRXcntiAj/hIJwRtzCUp5UQIqHoU8dmHoHOkKEP+zhJuR6E2s+WwDr + nTwE6eRa0g/AHY+chj2Je6flpPm2CKoTfUE7a2yBBU3wPq3rGtsQgVxPAxHRZz7A + w4AjH3NM1Uo3etuiDnGkJAuoKKb1J4X3w2QlbwlR4cODLKhJXHIufwaGtRwEin9S + 1l2bL8V3gy2Hv3D2t9TQZuR5NUHsibJRXLSa8WnSCcc6Bij5aqfdpYB+YvKH/rIm + GvYPmLZDfKGkx0JE4/qtfFjiPJ5VE7BxNyliEw/rnQsxWAGPqLlL61SD8w5jGkw3 + CinwO3sccTVcPz9b6A1RsbBVhTJJX5lcPn1lkOEVwQ7l8bRhOKCMe0P53qEDcLCd + KcXNnAFbVes9u+kfUQ4oxS0G2JS9ISVNmune+uv+JR7KqSdOuRYlyXA9uTjgWz4y + Cs7RS+CpkJFqrqOtS1rmuDW9Ea4PA8ygGlisM5d/AlVkniHz/2JYtgetiLCj9mfE + MzQpgnldNSPumKqJ3wwmCNisE+lXQ5UXCaoaeqF/qX1ykybQn41LQ+0xT5Uvy7sL + 9IwGuQINBFXKsiIBEACg2mP3QYkXdgWTK5JyTGyttE6bDC9uqsK8dc1J66Tjd5Ly + Be0amO+88GHXa0o5Smwk2QNoxsRR41G/D/eAeGsuOEYnePROEr3tcLnDjo4KLgQ+ + H69zRPn77sdP3A34Jgp+QIzByJWM7Cnim31quQP3qal2QdpGJcT/jDJWdticN76a + Biaz+HN13LyvZM+DWhUDttbjAJc+TEwF9YzIrU+3AzkTRDWkRh4kNIQxjlpNzvho + 9V75riVqg2vtgPwttPEhOLb0oMzy4ADdfezrfVvvMb4M4kY9npu4MlSkNTM97F/I + QKy90JuSUIjE05AO+PDXJF4Fd5dcpmukLV/2nV0WM2LAERpJUuAgkZN6pNUFVISR + +nSfgR7wvqeDY9NigHrJqJbSEgaBUs6RTk5hait2wnNKLJajlu3aQ2/QfRT/kG3h + ClKUz3Ju7NCURmFE6mfsdsVrlIsEjHr/dPbXRswXgC9FLlXpWgAEDYi9Wdxxz8o9 + JDWrVYdKRGG+OpLFh8AP6QL3YnZF+p1oxGUQ5ugXauAJ9YS55pbzaUFP8oOO2P1Q + BeYnKRs1GcMI8KWtE/fze9C9gZ7Dqju7ZFEyllM4v3lzjhT8muMSAhw41J22mSx6 + VRkQVRIAvPDFES45IbB6EEGhDDg4pD2az8Q7i7Uc6/olEmpVONSOZEEPsQe/2wAR + AQABiQIfBBgBAgAJBQJVyrIiAhsMAAoJEP0iAoWg/m1+niUQAKTxwJ9PTAfB+XDk + 3qH3n+T49O2wP3fhBI0EGhJp9Xbx29G7qfEeqcQm69/qSq2/0HQOc+w/g8yy71jA + 6rPuozCraoN7Im09rQ2NqIhPK/1w5ZvgNVC0NtcMigX9MiSARePKygAHOPHtrhyO + rJQyu8E3cV3VRT4qhqIqXs8Ydc9vL3ZrJbhcHQuSLdZxM1k+DahCJgwWabDCUizm + sVP3epAP19FP8sNtHi0P1LC0kq6/0qJot+4iBiRwXMervCD5ExdOm2ugvSgghdYN + BikFHvmsCxbZAQjykQ6TMn+vkmcEz4fGAn4L7Nx4paKEtXaAFO8TJmFjOlGUthEm + CtHDKjCTh9WV4pwG2WnXuACjnJcs6LcK377EjWU25H4y1ff+NDIUg/DWfSS85iIc + UgkOlQO6HJy0O96L5uxn7VJpXNYFa20lpfTVZv7uu3BC3RW/FyOYsGtSiUKYq6cb + CMxGTfFxGeynwIlPRlH68BqH6ctR/mVdo+5UIWsChSnNd1GreIEI6p2nBk3mc7jZ + 7pTEHpjarwOjs/S/lK+vLW53CSFimmW4lw3MwqiyAkxl0tHAT7QMHH9Rgw2HF/g6 + XD76fpFdMT856dsuf+j2uuJFlFe5B1fERBzeU18MxML0VpDmGFEaxxypfACeI/iu + 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb + =Ld8S + -----END PGP PUBLIC KEY BLOCK----- + +Store the key in a new text file and import it into GPG via: ``gpg --import +file_with_the_public_key`` + +The import can be verified with: + +.. code-block:: none + + $ gpg --list-keys + ... + pub rsa4096 2015-08-12 [SC] + 0694A9230F5139BF834BA458FD220285A0FE6D7E + uid [ unknown] VyOS Maintainers (VyOS Release) + sub rsa4096 2015-08-12 [E] + +.. _gpg-verification: + +GPG verification +^^^^^^^^^^^^^^^^ + +With the public key imported, the signature for the desired image needs +to be downloaded. + +.. note:: The signature can be downloaded by appending `.asc` to the URL of the + downloaded VyOS image. That small *.asc* file is the signature for the + associated image. + +Finally, verify the authenticity of the downloaded image: + +.. code-block:: none + + $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso + gpg: Signature made So 14 Apr 12:58:07 2019 CEST + gpg: using RSA key FD220285A0FE6D7E + gpg: Good signature from "VyOS Maintainers (VyOS Release) " [unknown] + Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E + +.. _live_installation: + +Live installation +================= + +.. note:: A permanent VyOS installation always requires to go first + through a live installation. + +VyOS, as other GNU+Linux distributions, can be tasted without installing +it in your hard drive. **With your downloaded VyOS .iso file you can +create a bootable USB drive that will let you boot into a fully +functional VyOS system**. Once you have tested it, you can either decide +to begin a :ref:`permanent_installation` in your hard drive or power +your system off, remove the USB drive, and leave everythng as it was. + + +If you have a GNU+Linux system, you can create your VyOS bootable USB +stick with with the ``dd`` command: + + 1. Open your terminal emulator. + + 2. Find out the device name of your USB drive (you can use the ``lsblk`` + command) + + 3. Unmount the USB drive. Replace X in the example below with the + letter of your device and keep the asterisk (wildcard) to unmount + all partitions. + + .. code-block:: none + + $ umount /dev/sdX* + + 4. Write the image (your VyOS .iso file) to the USB drive. + Note that here you want to use the device name (e.g. /dev/sdb), not + the partition name (e.g. /dev/sdb1). + + **Warning**: This will destroy all data on the USB drive! + + .. code-block:: none + + # dd if=/path/to/vyos.iso of=/dev/sdX bs=8M; sync + + 5. Wait until you get the outcome (bytes copied). Be patient, in some + computers it might take more than one minute. + + 6. Once ``dd`` has finished, pull the USB drive out and plug it into + the powered-off computer where you want to install (or test) VyOS. + + 7. Power the computer on, making sure it boots from the USB drive (you + might need to select booting device or change booting settings). + + 8. Once VyOS is completely loaded, enter the default credentials + (login: vyos, password: vyos). + + +If you find difficulties with this method, prefer to use a GUI program, +or have a different operating system, there are other programs you can +use to create a bootable USB drive, like balenaEtcher_ (for GNU/Linux, +macOS and Windows), Rufus_ (for Windows) and `many others`_. You can +follow their instructions to create a bootable USB drive from an .iso +file. + +.. hint:: The default username and password for the live system is *vyos*. + + +.. _permanent_installation: + +Permanent installation +====================== + +.. note:: Before a permanent installation, VyOS requires a :ref:`live_installation`. + +Unlike general purpose Linux distributions, VyOS uses "image installation" that +mimics the user experience of traditional hardware routers and allows keeping +multiple VyOS versions installed simultaneously. This makes it possible to +switch to a previous version if something breaks or miss-behaves after an image +upgrade. + +Every version is contained in its own squashfs image that is mounted in a union +filesystem together with a directory for mutable data such as configurations, +keys, or custom scripts. + +.. note:: Older versions (prior to VyOS 1.1) used to support non-image + installation (``install system`` command). Support for this has been removed + from VyOS 1.2 and newer releases. Older releases can still be upgraded via + the general ``add system image `` upgrade command (consult + :ref:`image-mgmt` for further information). + + +In order to proceed with a permanent installation: + + 1. Log into the VyOS live system (use the default credentials: vyos, + vyos) + + 2. Run the ``install image`` command and follow the wizard: + + .. code-block:: none + + vyos@vyos:~$ install image + Welcome to the VyOS install program. This script + will walk you through the process of installing the + VyOS image to a local hard drive. + Would you like to continue? (Yes/No) [Yes]: Yes + Probing drives: OK + Looking for pre-existing RAID groups...none found. + The VyOS image will require a minimum 2000MB root. + Would you like me to try to partition a drive automatically + or would you rather partition it manually with parted? If + you have already setup your partitions, you may skip this step + + Partition (Auto/Parted/Skip) [Auto]: + + I found the following drives on your system: + sda 4294MB + + Install the image on? [sda]: + + This will destroy all data on /dev/sda. + Continue? (Yes/No) [No]: Yes + + How big of a root partition should I create? (2000MB - 4294MB) [4294]MB: + + Creating filesystem on /dev/sda1: OK + Done! + Mounting /dev/sda1... + What would you like to name this image? [1.2.0-rolling+201809210337]: + OK. This image will be named: 1.2.0-rolling+201809210337 + Copying squashfs image... + Copying kernel and initrd images... + Done! + I found the following configuration files: + /opt/vyatta/etc/config.boot.default + Which one should I copy to sda? [/opt/vyatta/etc/config.boot.default]: + + Copying /opt/vyatta/etc/config.boot.default to sda. + Enter password for administrator account + Enter password for user 'vyos': + Retype password for user 'vyos': + I need to install the GRUB boot loader. + I found the following drives on your system: + sda 4294MB + + Which drive should GRUB modify the boot partition on? [sda]: + + Setting up grub: OK + Done! + + + 3. After the installation is complete, remove the live USB stick or + CD. + + 4. Reboot the system. + + .. code-block:: none + + vyos@vyos:~$ reboot + Proceed with reboot? (Yes/No) [No] Yes + + You will boot now into a permanent VyOS system. + + +PXE Boot +======== + +VyOS can also be installed through PXE. This is a more complex +installation method which allows deploying VyOS through the network. + +**Requirements** + +* Clients (where VyOS is to be installed) with a PXE-enabled NIC +* :ref:`dhcp-server` +* :ref:`tftp-server` +* Webserver (HTTP) - optional, but we will use it to speed up installation +* VyOS ISO image to be installed (do not use images prior to VyOS 1.2.3) +* Files *pxelinux.0* and *ldlinux.c32* `from the Syslinux distribution `_ + +Configuration +------------- + +Step 1: DHCP +^^^^^^^^^^^^ + +Configure a DHCP server to provide the client with: + +* An IP address +* The TFTP server address (DHCP option 66). Sometimes referred as *boot server* +* The *bootfile name* (DHCP option 67), which is *pxelinux.0* + +In this example we configured an existent VyOS as the DHCP server: + +.. code-block:: none + + vyos@vyos# show service dhcp-server + shared-network-name mydhcp { + subnet 192.168.1.0/24 { + bootfile-name pxelinux.0 + bootfile-server 192.168.1.50 + default-router 192.168.1.50 + range 0 { + start 192.168.1.70 + stop 192.168.1.100 + } + } + } + +.. _install_from_tftp: + +Step 2: TFTP +^^^^^^^^^^^^ + +Configure a TFTP server so that it serves the following: + +* The *pxelinux.0* file from the Syslinux distribution +* The *ldlinux.c32* file from the Syslinux distribution +* The kernel of the VyOS software you want to deploy. That is the + *vmlinuz* file inside the */live* directory of the extracted + contents from the ISO file. +* The initial ramdisk of the VyOS ISO you want to deploy. That is the + *initrd.img* file inside the */live* directory of the extracted + contents from the ISO file. Do not use an empty (0 bytes) initrd.img + file you might find, the correct file may have a longer name. +* A directory named pxelinux.cfg which must contain the configuration + file. We will use the configuration_ file shown below, which we named + default_. + +.. _configuration: https://wiki.syslinux.org/wiki/index.php?title=Config +.. _default: https://wiki.syslinux.org/wiki/index.php?title=PXELINUX#Configuration + +In the example we configured our existent VyOS as the TFTP server too: + +.. code-block:: none + + vyos@vyos# show service tftp-server + directory /config/tftpboot + listen-address 192.168.1.50 + +Example of the contents of the TFTP server: + +.. code-block:: none + + vyos@vyos# ls -hal /config/tftpboot/ + total 29M + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 . + drwxrwsr-x 9 root vyattacfg 4.0K Oct 18 00:05 .. + -r--r--r-- 1 root vyattacfg 25M Oct 13 23:24 initrd.img-4.19.54-amd64-vyos + -rwxr-xr-x 1 root vyattacfg 120K Oct 13 23:44 ldlinux.c32 + -rw-r--r-- 1 root vyattacfg 46K Oct 13 23:24 pxelinux.0 + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 pxelinux.cfg + -r--r--r-- 1 root vyattacfg 3.7M Oct 13 23:24 vmlinuz + + vyos@vyos# ls -hal /config/tftpboot/pxelinux.cfg + total 12K + drwxr-xr-x 2 root vyattacfg 4.0K Oct 14 01:10 . + drwxr-sr-x 3 tftp tftp 4.0K Oct 14 00:23 .. + -rw-r--r-- 1 root root 191 Oct 14 01:10 default + +Example of simple (no menu) configuration file: + +.. code-block:: none + + vyos@vyos# cat /config/tftpboot/pxelinux.cfg/default + DEFAULT VyOS123 + + LABEL VyOS123 + KERNEL vmlinuz + APPEND initrd=initrd.img-4.19.54-amd64-vyos boot=live nopersistence noautologin nonetworking fetch=http://address:8000/filesystem.squashfs + +Step 3: HTTP +^^^^^^^^^^^^ + +We also need to provide the *filesystem.squashfs* file. That is a heavy +file and TFTP is slow, so you could send it through HTTP to speed up the +transfer. That is how it is done in our example, you can find that in +the configuration file above. + +**First** run a web server - you can use a simple one like +`Python's SimpleHTTPServer`_ and start serving the `filesystem.squashfs` +file. The file can be found inside the `/live` directory of the +extracted contents of the ISO file. + +**Second**, edit the configuration file of the :ref:`install_from_tftp` +so that it shows the correct URL at +``fetch=http:///filesystem.squashfs``. + +.. note:: Do not change the name of the *filesystem.squashfs* file. If + you are working with different versions, you can create different + directories instead. + +And **third**, restart the TFTP service. If you are using VyOS as your +TFTP Server, you can restart the service with +``sudo service tftpd-hpa restart``. + +.. note:: Make sure the available directories and files in both TFTP + and HTTP server have the right permissions to be accessed from the + booting clients. + +.. _`Python's SimpleHTTPServer`: https://docs.python.org/2/library/simplehttpserver.html + +Client Boot +----------- + +Finally, turn on your PXE-enabled client or clients. They will +automatically get an IP address from the DHCP server and start booting +into VyOS live from the files automatically taken from the TFTP and HTTP +servers. + +Once finished you will be able to proceed with the ``install image`` +command as in a regular VyOS installation. + + + +Known Issues +============ + +This is a list of known issues that can arise during installation. + +Black screen on install +----------------------- + +GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. +This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a +black screen after selecting the `Live system` option from the installation image. + +The workaround is to type `e` when the boot menu appears and edit the GRUB boot options. Specifically, remove the: + +`console=ttyS0,115200` + +option, and type CTRL-X to boot. + +Installation can then continue as outlined above. + +.. _SYSLINUX: http://www.syslinux.org/ +.. _balenaEtcher: https://www.balena.io/etcher/ +.. _Rufus: https://rufus.ie/ +.. _many others: https://en.wikipedia.org/wiki/List_of_tools_to_create_Live_USB_systems diff --git a/docs/introducing/about.rst b/docs/introducing/about.rst new file mode 100644 index 00000000..0411344b --- /dev/null +++ b/docs/introducing/about.rst @@ -0,0 +1,27 @@ +.. _about: + +##### +About +##### + +VyOS is an open source network operating system based on Debian GNU/Linux. + +VyOS provides a free routing platform that competes directly with other +commercially available solutions from well known network providers. Because +VyOS is run on standard amd64, i586 and ARM systems, it is able to be used +as a router and firewall platform for cloud deployments. + +We use multiple live versions of our manual hosted thankfully by +https://readthedocs.org. We will provide one version of the manual for every +VyOS major version starting with VyOS 1.2 which will receive Long-term support +(LTS). + +The manual version is selected/specified by it's Git branch name. You can +switch between versions of the documentation by selecting the appropriate +branch on the bottom left corner. + +VyOS CLI syntax may change between major (and sometimes minor) versions. Please +always refer to the documentation matching your current, running installation. +If a change in the CLI is required, VyOS will ship a so called migration script +which will take care of adjusting the syntax. No action needs to be taken by +you. diff --git a/docs/introducing/history.rst b/docs/introducing/history.rst new file mode 100644 index 00000000..9a13e2b3 --- /dev/null +++ b/docs/introducing/history.rst @@ -0,0 +1,47 @@ +.. _history: + +####### +History +####### + +VyOS is a Linux-based network operating system that provides software-based +network routing, firewall, and VPN functionality. + +The VyOS project was started in late 2013 as a community fork of the +`GPL `_ portions of +Vyatta Core 6.6R1 with the goal of maintaining a free and open source network +operating system in response to the decision to discontinue the community +edition of Vyatta. Here everyone loves learning, older managers and new users. + +VyOS is primarily based on `Debian GNU/Linux `_ and +the `Quagga `_ routing engine. Its configuration +syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the +`XORP project `_, which was the original routing engine +for Vyatta. + +In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of +VyOS version 1.2, VyOS now uses `FRRouting `_ as the +routing engine. + +How is VyOS different from any other router distributions and platform? + +- It's more than just a firewall and VPN, VyOS includes extended routing + capabilities like OSPFv2, OSPFv3, BGP, VRRP, and extensive route policy + mapping and filtering +- Unified command line interface in the style of hardware routers. +- Scriptable CLI +- Stateful configuration system: prepare changes and commit at once or discard, + view previous revisions or rollback to them, archive revisions to remote + server and execute hooks at commit time +- Image-based upgrade: keep multiple versions on the same system and revert to + previous image if a problem arises +- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard, DPMVPN, IKEv2 and more +- DHCP, TFTP, mDNS repeater, broadcast relay and DNS forwarding support +- Both IPv4 and IPv6 support +- Runs on physical and virtual platforms alike: small x86 boards, big servers, + KVM, Xen, VMware, Hyper-V, and more +- Completely free and open source, with documented internal APIs and build + procedures +- Community driven. Patches are welcome and all code, bugs, and nightly builds + are publicly accessible + diff --git a/docs/introducing/releases.rst b/docs/introducing/releases.rst new file mode 100644 index 00000000..6d95c4bc --- /dev/null +++ b/docs/introducing/releases.rst @@ -0,0 +1,29 @@ +.. _release: + +######## +Releases +######## + +Rolling Release +############### + +rolling rolling + +LTS +### + +lts lts lts + + +old LTS +======= + +old LTSLTSLTSLTS + +even older LTS +-------------- + +even older LTS even older LTS +even older LTS even older LTS even older LTS even older LTS even older LTS + + diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst deleted file mode 100644 index 0b3420f4..00000000 --- a/docs/troubleshooting.rst +++ /dev/null @@ -1,446 +0,0 @@ -.. _troubleshooting: - -############### -Troubleshooting -############### - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -****************** -Connectivity Tests -****************** - -Basic Connectivity Tests -======================== - -Verifying connectivity can be done with the familiar `ping` and `traceroute` -commands. The options for each are shown (the options for each command were -displayed using the built-in help as described in the :ref:`cli` -section and are omitted from the output here): - -.. opcmd:: ping - - Send ICMP echo requests to destination host. There are multiple options to - ping, inkl. VRF support. - - .. code-block:: none - - vyos@vyos:~$ ping 10.1.1.1 - Possible completions: - Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - vrf - - -.. opcmd:: traceroute - - Trace path to target. - - .. code-block:: none - - vyos@vyos:~$ traceroute - Possible completions: - Track network path to specified node - - - ipv4 Track network path to - ipv6 Track network path to - - -Advanced Connectivity Tests -=========================== - -.. opcmd:: monitor traceroute - - However, another helper is available which combines ping and traceroute - into a single tool. An example of its output is shown: - - .. code-block:: none - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - Keys: Help Display mode Restart statistics Order of fields quit - Packets Pings - Host Loss% Snt Last Avg Best Wrst StDev - 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 - 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 - 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 - 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 - - .. note:: The output consumes the screen and will replace your command - prompt. - - Several options are available for changing the display output. Press `h` to - invoke the built in help system. To quit, just press `q` and you'll be - returned to the VyOS command prompt. - -IPv6 Topology Discovery -======================= - -IPv6 uses different techniques to discover its Neighbors/topology. - -Router Discovery ----------------- - -.. opcmd:: force ipv6-rd interface [address ] - - Discover routers via eth0. - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-rd interface eth0 - Soliciting ff02::2 (ff02::2) on eth0... - - Hop limit : 60 ( 0x3c) - Stateful address conf. : No - Stateful other conf. : No - Mobile home agent : No - Router preference : high - Neighbor discovery proxy : No - Router lifetime : 1800 (0x00000708) seconds - Reachable time : unspecified (0x00000000) - Retransmit time : unspecified (0x00000000) - Prefix : 240e:fe:8ca7:ea01::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Prefix : fc00:470:f1cd:101::/64 - On-link : Yes - Autonomous address conf.: Yes - Valid time : 2592000 (0x00278d00) seconds - Pref. time : 14400 (0x00003840) seconds - Recursive DNS server : fc00:470:f1cd::ff00 - DNS server lifetime : 600 (0x00000258) seconds - Source link-layer address: 00:98:2B:F8:3F:11 - from fe80::298:2bff:fef8:3f11 - -Neighbor Discovery ------------------- - -.. opcmd:: force ipv6-nd interface address - - - Example: - - .. code-block:: none - - vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 - - Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... - Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 - - -*************** -Interface names -*************** - -If you find the names of your interfaces have changed, this could be because your MAC addresses have changed. - -* For example, you have a VyOS VM with 4 Ethernet interfaces named eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different host and find your interfaces now are eth4, eth5, eth6 and eth7. - - One way to fix this issue **taking control of the MAC addresses** is: - - Log into VyOS and run this command to display your interface settings. - - .. code-block:: none - - show interfaces detail - - Take note of MAC addresses. - - Now, in order to update a MAC address in the configuration, run this command specifying the interface name and MAC address you want. - - .. code-block:: none - - set interfaces eth0 hw-id 00:0c:29:da:a4:fe - - If it is a VM, go into the settings of the host and set the MAC address to the settings found in the config.boot file. You can also set the MAC to static if the host allows so. - - -* Another example could be when cloning VyOS VMs in GNS3 and you get into the same issue: interface names have changed. - - And **a more generic way to fix it** is just deleting every MAC address at the configuration file of the cloned machine. They will be correctly regenerated automatically. - - -********** -Monitoring -********** - -VyOS features several monitoring tools. - -.. code-block:: none - - vyos@vyos:~$ monitor - Possible completions: - bandwidth Monitor interface bandwidth in real time - bandwidth-test - Initiate or wait for bandwidth test - cluster Monitor clustering service - command Monitor an operational mode command (refreshes every 2 seconds) - conntrack-sync - Monitor conntrack-sync - content-inspection - Monitor Content-Inspection - dhcp Monitor Dynamic Host Control Protocol (DHCP) - dns Monitor a Domain Name Service (DNS) daemon - firewall Monitor Firewall - https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service - lldp Monitor Link Layer Discovery Protocol (LLDP) daemon - log Monitor last lines of messages file - nat Monitor network address translation (NAT) - ndp Monitor the NDP information received by the router through the device - openvpn Monitor OpenVPN - protocol Monitor routing protocols - snmp Monitor Simple Network Management Protocol (SNMP) daemon - stop-all Stop all current background monitoring processes - traceroute Monitor the path to a destination in realtime - traffic Monitor traffic dumps - vpn Monitor VPN - vrrp Monitor Virtual Router Redundancy Protocol (VRRP) - webproxy Monitor Webproxy service - - -Traffic Dumps -============= - -To monitor interface traffic, issue the :code:`monitor traffic interface ` -command, replacing `` with your chosen interface. - -.. code-block:: none - - vyos@vyos:~$ monitor traffic interface eth0 - tcpdump: verbose output suppressed, use -v or -vv for full protocol decode - listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes - 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 - 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 - 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 - 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 - ^C - 4 packets captured - 4 packets received by filter - 0 packets dropped by kernel - vyos@vyos:~$ - -To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command -prompt. - -Traffic can be filtered and saved. - -.. code-block:: none - - vyos@vyos:~$ monitor traffic interface eth0 - Possible completions: - Execute the current command - filter Monitor traffic matching filter conditions - save Save traffic dump from an interface to a file - - -Interface Bandwidth Usage -========================= - -to take a quick view on the used bandwidth of an interface use the ``monitor -bandwidth`` command - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth interface eth0 - -show the following: - -.. code-block:: none - - B (RX Bytes/second) - 198.00 .|....|..................................................... - 165.00 .|....|..................................................... - 132.00 ||..|.|..................................................... - 99.00 ||..|.|..................................................... - 66.00 |||||||..................................................... - 33.00 |||||||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - - KiB (TX Bytes/second) - 3.67 ......|..................................................... - 3.06 ......|..................................................... - 2.45 ......|..................................................... - 1.84 ......|..................................................... - 1.22 ......|..................................................... - 0.61 :::::||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - -Interface Performance -===================== - -To take a look on the network bandwidth between two nodes, the ``monitor -bandwidth-test`` command is used to run iperf. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test - Possible completions: - accept Wait for bandwidth test connections (port TCP/5001) - initiate Initiate a bandwidth test - -* The ``accept`` command opens a listening iperf server on TCP Port 5001 -* The ``initiate`` command connects to that server to perform the test. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test initiate - Possible completions: - Initiate a bandwidth test to specified host (port TCP/5001) - - - - -Monitor command -=============== - -The ``monitor command`` command allows you to repeatedly run a command to view -a continuously refreshed output. The command is run and output every 2 seconds, -allowing you to monitor the output continuously without having to re-run the -command. This can be useful to follow routing adjacency formation. - -.. code-block:: none - - vyos@router:~$ monitor command "show interfaces" - -Will clear the screen and show you the output of ``show interfaces`` every -2 seconds. - -.. code-block:: none - - Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 - - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.168.1.1/24 u/u - eth0.5 198.51.100.4/24 u/u WAN - lo 127.0.0.1/8 u/u - ::1/128 - vti0 172.25.254.2/30 u/u - vti1 172.25.254.9/30 u/u - -**************** -Terminal/Console -**************** - -Sometimes you need to clear counters or statistics to troubleshoot better. - -To do this use the ``clear`` command in Operational mode. - -to clear the console output - -.. code-block:: none - - vyos@vyos:~$ clear console - -to clear interface counters - -.. code-block:: none - - # clear all interfaces - vyos@vyos:~$ clear interface ethernet counters - # clear specific interface - vyos@vyos:~$ clear interface ehternet eth0 counters - -The command follow the same logic as the ``set`` command in configuration mode. - -.. code-block:: none - - # clear all counters of a interface type - vyos@vyos:~$ clear interface counters - # clear counter of a interface in interface_type - vyos@vyos:~$ clear interface counters - - -to clear counters on firewall rulesets or single rules - -.. code-block:: none - - vyos@vyos:~$ clear firewall name counters - vyos@vyos:~$ clear firewall name rule counters - - vyos@vyos:~$ clear firewall ipv6-name counters - vyos@vyos:~$ clear firewall ipv6-name rule counters - - -****************** -System Information -****************** - -.. _boot-steps: - -Boot Steps -========== - -VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was -the first version of Debian that uses systemd_ as the default init system. - -These are the boot steps for VyOS 1.2 - -1. The BIOS loads Grub (or isolinux for the Live CD) -2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` -3. Kernel Launches Systemd ``/lib/systemd/systemd`` -4. Systemd loads the VyOS service file - ``/lib/systemd/system/vyos-router.service`` -5. The service file launches the VyOS router init script - ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ - Debian package - - 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ - - 2. Initialises the boot configuration file - copies over - ``config.boot.default`` if there is no configuration - 3. Runs the configuration migration, if the configuration is for an older - version of VyOS - 4. Runs The pre-config script, if there is one - ``/config/scripts/vyos-preconfig-bootup.script`` - 5. If the config file was upgraded, runs any post upgrade scripts - ``/config/scripts/post-upgrade.d`` - 6. Starts ``rl-system`` and ``firewall`` - 7. Mounts the ``/boot`` partition - 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ - vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` - - 1. The config loader script writes log entries to - ``/var/log/vyatta-config-loader.log`` - - 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` - 11. Finally it runs the post-config script - ``/config/scripts/vyos-postconfig-bootup.script`` - -.. _Quagga: https://www.quagga.net/ -.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ -.. _FRR: https://frrouting.org/ -.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg -.. _systemd: https://freedesktop.org/wiki/Software/systemd/ -.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst new file mode 100644 index 00000000..0b3420f4 --- /dev/null +++ b/docs/troubleshooting/index.rst @@ -0,0 +1,446 @@ +.. _troubleshooting: + +############### +Troubleshooting +############### + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +****************** +Connectivity Tests +****************** + +Basic Connectivity Tests +======================== + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the :ref:`cli` +section and are omitted from the output here): + +.. opcmd:: ping + + Send ICMP echo requests to destination host. There are multiple options to + ping, inkl. VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + + +.. opcmd:: traceroute + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + + +Advanced Connectivity Tests +=========================== + +.. opcmd:: monitor traceroute + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. + +IPv6 Topology Discovery +======================= + +IPv6 uses different techniques to discover its Neighbors/topology. + +Router Discovery +---------------- + +.. opcmd:: force ipv6-rd interface [address ] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 + +Neighbor Discovery +------------------ + +.. opcmd:: force ipv6-nd interface address + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 + + +*************** +Interface names +*************** + +If you find the names of your interfaces have changed, this could be because your MAC addresses have changed. + +* For example, you have a VyOS VM with 4 Ethernet interfaces named eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + .. code-block:: none + + show interfaces detail + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command specifying the interface name and MAC address you want. + + .. code-block:: none + + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + + If it is a VM, go into the settings of the host and set the MAC address to the settings found in the config.boot file. You can also set the MAC to static if the host allows so. + + +* Another example could be when cloning VyOS VMs in GNS3 and you get into the same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at the configuration file of the cloned machine. They will be correctly regenerated automatically. + + +********** +Monitoring +********** + +VyOS features several monitoring tools. + +.. code-block:: none + + vyos@vyos:~$ monitor + Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service + + +Traffic Dumps +============= + +To monitor interface traffic, issue the :code:`monitor traffic interface ` +command, replacing `` with your chosen interface. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + tcpdump: verbose output suppressed, use -v or -vv for full protocol decode + listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes + 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 + 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 + 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 + 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 + ^C + 4 packets captured + 4 packets received by filter + 0 packets dropped by kernel + vyos@vyos:~$ + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + Possible completions: + Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file + + +Interface Bandwidth Usage +========================= + +to take a quick view on the used bandwidth of an interface use the ``monitor +bandwidth`` command + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth interface eth0 + +show the following: + +.. code-block:: none + + B (RX Bytes/second) + 198.00 .|....|..................................................... + 165.00 .|....|..................................................... + 132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + +Interface Performance +===================== + +To take a look on the network bandwidth between two nodes, the ``monitor +bandwidth-test`` command is used to run iperf. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test + Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test + +* The ``accept`` command opens a listening iperf server on TCP Port 5001 +* The ``initiate`` command connects to that server to perform the test. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test initiate + Possible completions: + Initiate a bandwidth test to specified host (port TCP/5001) + + + + +Monitor command +=============== + +The ``monitor command`` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +.. code-block:: none + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every +2 seconds. + +.. code-block:: none + + Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.168.1.1/24 u/u + eth0.5 198.51.100.4/24 u/u WAN + lo 127.0.0.1/8 u/u + ::1/128 + vti0 172.25.254.2/30 u/u + vti1 172.25.254.9/30 u/u + +**************** +Terminal/Console +**************** + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the ``clear`` command in Operational mode. + +to clear the console output + +.. code-block:: none + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: none + + # clear all interfaces + vyos@vyos:~$ clear interface ethernet counters + # clear specific interface + vyos@vyos:~$ clear interface ehternet eth0 counters + +The command follow the same logic as the ``set`` command in configuration mode. + +.. code-block:: none + + # clear all counters of a interface type + vyos@vyos:~$ clear interface counters + # clear counter of a interface in interface_type + vyos@vyos:~$ clear interface counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: none + + vyos@vyos:~$ clear firewall name counters + vyos@vyos:~$ clear firewall name rule counters + + vyos@vyos:~$ clear firewall ipv6-name counters + vyos@vyos:~$ clear firewall ipv6-name rule counters + + +****************** +System Information +****************** + +.. _boot-steps: + +Boot Steps +========== + +VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was +the first version of Debian that uses systemd_ as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` +3. Kernel Launches Systemd ``/lib/systemd/systemd`` +4. Systemd loads the VyOS service file + ``/lib/systemd/system/vyos-router.service`` +5. The service file launches the VyOS router init script + ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ + Debian package + + 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ + + 2. Initialises the boot configuration file - copies over + ``config.boot.default`` if there is no configuration + 3. Runs the configuration migration, if the configuration is for an older + version of VyOS + 4. Runs The pre-config script, if there is one + ``/config/scripts/vyos-preconfig-bootup.script`` + 5. If the config file was upgraded, runs any post upgrade scripts + ``/config/scripts/post-upgrade.d`` + 6. Starts ``rl-system`` and ``firewall`` + 7. Mounts the ``/boot`` partition + 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ + vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` + + 1. The config loader script writes log entries to + ``/var/log/vyatta-config-loader.log`` + + 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` + 11. Finally it runs the post-config script + ``/config/scripts/vyos-postconfig-bootup.script`` + +.. _Quagga: https://www.quagga.net/ +.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ +.. _FRR: https://frrouting.org/ +.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg +.. _systemd: https://freedesktop.org/wiki/Software/systemd/ +.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html -- cgit v1.2.3 From a6c226d4b4e79c07121b0a609d2fb78cae70f3b0 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:24:16 +0100 Subject: arange installation and image management --- docs/appendix/migrate-from-vyatta.rst | 164 ------------ docs/appendix/virtual/index.rst | 12 - docs/appendix/virtual/libvirt.rst | 160 ------------ docs/appendix/virtual/vyos-on-gns3.rst | 176 ------------- docs/appendix/virtual/vyos-on-vmware.rst | 32 --- docs/appendix/vyos-on-baremetal.rst | 411 ------------------------------ docs/appendix/vyos-on-clouds.rst | 173 ------------- docs/image-mgmt.rst | 193 -------------- docs/installation/cloud/aws.rst | 54 ++++ docs/installation/cloud/azure.rst | 53 ++++ docs/installation/cloud/gcp.rst | 55 ++++ docs/installation/cloud/index.rst | 13 + docs/installation/cloud/oracel.rst | 8 + docs/installation/image.rst | 115 +++++++++ docs/installation/index.rst | 3 +- docs/installation/iso.rst | 2 + docs/installation/migrate-from-vyatta.rst | 164 ++++++++++++ docs/installation/upate.rst | 79 ++++++ docs/installation/virtual/eve-ng.rst | 8 + docs/installation/virtual/gns3.rst | 176 +++++++++++++ docs/installation/virtual/index.rst | 12 + docs/installation/virtual/libvirt.rst | 160 ++++++++++++ docs/installation/virtual/proxmox.rst | 8 + docs/installation/virtual/vmware.rst | 32 +++ docs/installation/vyos-on-baremetal.rst | 411 ++++++++++++++++++++++++++++++ 25 files changed, 1352 insertions(+), 1322 deletions(-) delete mode 100644 docs/appendix/migrate-from-vyatta.rst delete mode 100644 docs/appendix/virtual/index.rst delete mode 100644 docs/appendix/virtual/libvirt.rst delete mode 100644 docs/appendix/virtual/vyos-on-gns3.rst delete mode 100644 docs/appendix/virtual/vyos-on-vmware.rst delete mode 100644 docs/appendix/vyos-on-baremetal.rst delete mode 100644 docs/appendix/vyos-on-clouds.rst delete mode 100644 docs/image-mgmt.rst create mode 100644 docs/installation/cloud/aws.rst create mode 100644 docs/installation/cloud/azure.rst create mode 100644 docs/installation/cloud/gcp.rst create mode 100644 docs/installation/cloud/index.rst create mode 100644 docs/installation/cloud/oracel.rst create mode 100644 docs/installation/image.rst create mode 100644 docs/installation/iso.rst create mode 100644 docs/installation/migrate-from-vyatta.rst create mode 100644 docs/installation/upate.rst create mode 100644 docs/installation/virtual/eve-ng.rst create mode 100644 docs/installation/virtual/gns3.rst create mode 100644 docs/installation/virtual/index.rst create mode 100644 docs/installation/virtual/libvirt.rst create mode 100644 docs/installation/virtual/proxmox.rst create mode 100644 docs/installation/virtual/vmware.rst create mode 100644 docs/installation/vyos-on-baremetal.rst (limited to 'docs') diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/appendix/migrate-from-vyatta.rst deleted file mode 100644 index f15c3d5a..00000000 --- a/docs/appendix/migrate-from-vyatta.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _migrate_from_vyatta: - -Migrate from Vyatta Core -======================== - -VyOS 1.x line aims to preserve backward compatibility and provide a safe -upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as -VC7.0. - -Vyatta release compatibility ----------------------------- - -Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. - -Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the -"modify" firewall was removed and replaced with the ``set policy route`` -command family, old configs can not be automatically converted. You will have -to adapt it to post-6.5 Vyatta syntax manually. - -.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been - renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using - zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change - interface names in rules for remote access VPN. - -Upgrade procedure ------------------ - -You just use ``add system image``, as if it was a new VC release (see -:ref:`update_vyos` for additional information). The only thing you want to do -is to verify the new images digital signature. You will have to add the public -key manually once as it is not shipped the first time. - -.. code-block:: none - - vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key - Connecting to vyos.net (x.x.x.x:80) - so3group_maintainers 100% |*************************| 3125 --:--:-- ETA - vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key - OK - vyatta@vyatta:~$ - -For completion the key below corresponds to the key listed in the URL above. - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - mQINBFIIUZwBEADGl+wkZpYytQxd6LnjDZZScziBKYJbjInetYeS0SUrgpqnPkzL - 2CiGfPczLwpYY0zWxpUhTvqjFsE5yDpgs0sPXIgUTFE1qfZQE+WD1I1EUM6sp/38 - 2xKQ9QaNc8oHuYINLYYmNYra6ZjIGtQP9WOX//IDYB3fhdwlmiW2z0hux2OnPWdh - hPZAmSrx5AiXFEEREJ1cAQyvYk7hgIRvM/rdQMUm+u4/z+S4mxCHE10KzlqOGhRv - hA8WQxHCVusMFGwXoKHxYf9OQpV7lsfOCODfXOMP/L9kHQ5/gBsLL5hHst+o/3VG - ec0QuVrVkBBehgrqhfJW2noq+9gTooURGImQHEOyE0xpJdFrrgk5Ii9RqQwdVRzI - ZPbqbo8uuldZIRJRGnfx+vAR9812yo38NVZ/X0P/hkkrx+UeGVgpC/ao5XLRiOzL - 7ZBMWLA6FVmZ7mkpqdzuMXX5548ApACm6EKErULIhTYDGDzFxA3cf6gr5VVi4usD - wglVs+FHuiLehmuuPTMoVcT2R6+Ht44hG3BmQmKzh/SSEa1g9gKgrhZrMdIyK4hu - GvMqLw9z9BgJbWB3BgXOUdlkXLDwBvVpEcWsPJgxSjAvjAbLLE4YkKAdYU8bQ0Pd - JuN485tcXxgQCadFZB0gcipQAvVf4b810HrY88g6FldfauHxiACOlXscZwARAQAB - tDBTTzMgR3JvdXAgTWFpbnRhaW5lcnMgPG1haW50YWluZXJzQHNvM2dyb3VwLm5l - dD6JAjgEEwECACIFAlIIUZwCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJ - ELdE4lqkQubp8GsQAKntoRFG6bWX/4WPw7Vo7kIF5kWcmv3lVb0AQkacscWope7T - Iq0VcgpAycJue2bSS9LAsvNtpVkQmFawbwFjqB3CC5NbPNQ4Kf+gswKa+yaHwejo - 7dkslAwxgXHe5g76DG7CVLMsMg6zVDFYuzeksPywls/OJBIpkuGqeXy9tAHjQzjA - SlZV3Gsx7azESjiVQ73EUBt2OXkwN4TN9TEHAnVsrNIXHwFl1VfFsSG1Q6uZDtkk - CB4DZJKN4RzCY2QSwMAqRRC2OXdwk5IAk8wwCGoFpp0UV6CO9YCeOaqJderEcBA4 - MGHqdiPDIbH5wvckjZzFznU/Paz3MwPwBdtN+WSKvwf+JItSiUqm8Dy2Pl/1cnux - 1g1I4WQlXUVaS/MDusqL7tbS8k5A5a2+YVMxShWH9BhXZwNXzEihl4sm8Hrg5SvZ - givJj2y93WoL69Wq0/86wkkH2xcrz4gsiUcQf5YXU/RHXOLnPR29/pg8TS0L7sST - dv0X23C2IpfqYoqN7YZ3K0Wczhi0yLPCrc27IczuHgjt/8ICda11xhB1t/pUbvnX - oksehaLp8O3uU8GyAsTfUgpijZFc/3jIadOl0L9NGUbYYgPzFeaZTa/njeEbz3wX - PZMn278sbL9UhupI5Hx7eREbKzV4VPVKz81ndKNMXyuJHXv2R0xou3nvuo1WuQIN - BFIIUZwBEADAhoYPDCSogG41Naq+wFkG+IPszqe0dW/UWg0xrZDT0UblwDSd4OGY - 7FATMIhjOUyFxk6+XKA5CDCWP8Npkl0modTL59uVWNxU1vUKincc/j4ipHQeAhE6 - fvZkrprvADD8TYIGesl/3EGNc7bzc5ZqX71hKPHG+autRtgFSOR2PSXD9MlJXIBb - RzHAXxlh72zvsGadcxLJm4pSWXitkR/5Wc3e0IippKdzGwZnCDpNmcBGtSTFgixP - JqyRZFVCPWs7jr/oQeZnq65wJp1KD2HvhhKHJfsPrnNjLSm1SQVh8hXzE9odcv6N - mJB7tNXywuROBt6a01ojBa9J3zuMYQj3iQl2MhxtHylKVBjr7NjZ4evZbLsRMxY1 - hYk7sl+ZxCPFeOZ9D2ppU/CUDXCS095I1x+s+VuiUNf/3yd8ahCWDXVp9nsXyYjm - 2pHIxb2F6r8Vd4AjlD2MQwszECS88INF3l/9ksIHEMKuuW+JAC9FiZ7k4IGcIltv - If/V2TgE6t6qoWIlmLhMTjOyJpwnokY1nIuXHH7yp+HsuqnYnf/dgLnt4czPLeHO - +TdIDHhUym0AKlCcbdgn0C6EJVTnA8BFgFjiIOMAeT0rhATg0W/cND8KQcX4V9wM - nHSEsgSEuP9H+67xuRx5Imuh5ntecrcuCYSNuOneUXWPThDKQPO9lQARAQABiQIf - BBgBAgAJBQJSCFGcAhsMAAoJELdE4lqkQubpc+0P/0IzUx8nTpF0/ii2TA0YCOgj - tviM6PRTVPrFcxijNeXiIMHZYrALYUvXxXGp1IZBP3IcOyuZNp2WLqF/f9a3cIr1 - 9b/LJPrwopGqV3K30lormk7hH0s3IXbhd0ZYWvRj+5kQ8TFRAFfPwjlItzjYJmYX - AGJmM9PxJID/4LgWSfQ/ZfNu7MJ7+2goQLu9b6x7UC1FlE4q1lcjBvHjVPM//S9G - lGAHaysyTjVu88W2wwBpBrO1MQnDvqFRddXPOIWp0jecBMUd4E0fB36yuStsXZT3 - RN4V8vKRBYXuqHhiTwZeh153cHZk2EZBwz5A6DJubMaGdJTesHW5Qf2goph0pmjC - +XuXn8J6tc5nFDf8DP4AFVMtqa3Brj2fodWd0Zzxq3AVsbX144c1oqJUhO4t3+ie - 8fD/6/jx4iuPCQTfyhHG+zGfyUb2LQ+OVLW1WYTxH5tzHaZUmZFdV2I1kuhuvZ1t - WRlmTnHZOnEb3+t8KCRWzRMfweTzXfRRKBC0/QpeX1r5pbaMHH8zF/J5PKmL0+jg - +DS8JSbSfv7Ke6rplf7lHYaDumAFZfxXuQkajzLZbX0E5Xu5BNz4Vq6LGBj7LDXL - gswIK8FFgZB+W8zwOqUV1vjIr9wkdLifXXezKpTeYpFDGLdfsK+uNAtGyvI61TDi - Pr6fWpIruuc7Gg9rUF0L - =VQTr - -----END PGP PUBLIC KEY BLOCK----- - -Next add the VyOS image. - -This example uses VyOS 1.0.0, however, it's better to install the latest -release. - -.. code-block:: none - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - 1: VC6.6R1 (default boot) (running image) - - vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 - Found it. Checking digital signature... - gpg: directory `/root/.gnupg' created - gpg: new configuration file `/root/.gnupg/gpg.conf' created - gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run - gpg: keyring `/root/.gnupg/pubring.gpg' created - gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 - gpg: /root/.gnupg/trustdb.gpg: trustdb created - gpg: Good signature from "SO3 Group Maintainers " - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 - Digital signature is valid. - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.0.0]: [return] - OK. This image will be named: 1.0.0 - Installing "1.0.0" image. - Copying new release files... - - Would you like to save the current configuration - directory and config file? (Yes/No) [Yes]: [return] - Copying current configuration... - - Would you like to save the SSH host keys from your - current configuration? (Yes/No) [Yes]: [return] - Copying SSH keys... - Setting up grub configuration... - Done. - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.0.0 (default boot) - 2: VC6.6R1 (running image) - -Upon reboot, you should have a working installation of VyOS. - -You can go back to your Vyatta install using the ``set system image -default-boot`` command and selecting the your previous Vyatta Core image. - -.. note:: Future releases of VyOS will break the direct upgrade path from - Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS - 1.2. After this you can continue upgrading to newer releases once you bootet - into VyOS 1.2 once. diff --git a/docs/appendix/virtual/index.rst b/docs/appendix/virtual/index.rst deleted file mode 100644 index 7ede37b5..00000000 --- a/docs/appendix/virtual/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _virtual: - -Running on Virtual Environments -=============================== - - -.. toctree:: - :maxdepth: 2 - - libvirt - vyos-on-vmware - vyos-on-gns3 diff --git a/docs/appendix/virtual/libvirt.rst b/docs/appendix/virtual/libvirt.rst deleted file mode 100644 index 0d624b94..00000000 --- a/docs/appendix/virtual/libvirt.rst +++ /dev/null @@ -1,160 +0,0 @@ -.. _libvirt: - -*************************** -Running on Libvirt Qemu/KVM -*************************** - -Libvirt is an open-source API, daemon and management tool for managing platform virtualization. -There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. -In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. - -CLI -=== - -Deploy from ISO ---------------- - -Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. -The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. - -.. code-block:: none - - $ virt-install -n vyos_r1 \ - --ram 4096 \ - --vcpus 2 \ - --cdrom /var/lib/libvirt/images/vyos.iso \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r1`` - -.. code-block:: none - - $ virsh console vyos_r1 - - Connected to domain vyos_r1 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ install image - -After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. - -Deploy from qcow2 ------------------ -The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - -Create VM with ``import`` qcow2 disk option. - -.. code-block:: none - - $ virt-install -n vyos_r2 \ - --ram 4096 \ - --vcpus 2 \ - --os-type linux \ - --os-variant debian10 \ - --network network=default \ - --graphics vnc \ - --hvm \ - --virt-type kvm \ - --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ - --import \ - --noautoconsole - -Connect to VM with command ``virsh console vyos_r2`` - -.. code-block:: none - - $ virsh console vyos_r2 - - Connected to domain vyos_r2 - Escape character is ^] - - vyos login: vyos - Password: - - vyos@vyos:~$ - -The system is fully operational. - -Virt-manager -============ -The virt-manager application is a desktop user interface for managing virtual machines through libvirt. -On the linux open :abbr:`VMM (Virtual Machine Manager)`. - -Deploy from ISO ---------------- - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Local install media`` (ISO) - -.. figure:: /_static/images/virt-libvirt-01.png - -3. Choose path to iso vyos.iso. Operating System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Disk size - -.. figure:: /_static/images/virt-libvirt-04.png - -6. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -7. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-06.png - -Deploy from qcow2 ------------------ - -Download predefined VyOS.qcow2 image for ``KVM`` - -.. code-block:: none - - curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 - - -1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` - -2. Choose ``Import existing disk`` image - -.. figure:: /_static/images/virt-libvirt-qc-01.png - -3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. - -.. figure:: /_static/images/virt-libvirt-qc-02.png - -4. Choose Memory and CPU - -.. figure:: /_static/images/virt-libvirt-03.png - -5. Name of VM and network selection - -.. figure:: /_static/images/virt-libvirt-05.png - -6. Then you will be taken to the console. - -.. figure:: /_static/images/virt-libvirt-qc-03.png - - - diff --git a/docs/appendix/virtual/vyos-on-gns3.rst b/docs/appendix/virtual/vyos-on-gns3.rst deleted file mode 100644 index 93ea9ae2..00000000 --- a/docs/appendix/virtual/vyos-on-gns3.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _vyos-on-gns3: - -############### -Running on GNS3 -############### - -Sometimes you may want to test VyOS in a lab environment. -`GNS3 `__ is a network emulation software you -might use for it. - -This guide will provide the necessary steps for installing -and setting up VyOS on GNS3. - -Requirements ------------- - -The following items are required: - -* A VyOS installation image (.iso file). - `Here `__ you - can find how to get it. - -* A working GNS3 installation. For further information see the - `GNS3 documentation `__. - -.. _vm_setup: - -VM setup --------- - -First, a virtual machine (VM) for the VyOS installation must be created -in GNS3. - -Go to the GNS3 **File** menu, click **New template** and choose select -**Manually create a new Template**. - -.. figure:: /_static/images/gns3-01.png - -Select **Quemu VMs** and then click on the ``New`` button. - -.. figure:: /_static/images/gns3-02.png - -Write a name for your VM, for instance "VyOS", and click ``Next``. - -.. figure:: /_static/images/gns3-03.png - -Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM -and click ``Next``. - -.. figure:: /_static/images/gns3-04.png - -Select **telnet** as your console type and click ``Next``. - -.. figure:: /_static/images/gns3-05.png - -Select **New image** for the base disk image of your VM and click -``Create``. - -.. figure:: /_static/images/gns3-06.png - -Use the defaults in the **Binary and format** window and click -``Next``. - -.. figure:: /_static/images/gns3-07.png - -Use the defaults in the **Qcow2 options** window and click ``Next``. - -.. figure:: /_static/images/gns3-08.png - -Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu -image creator**. - -.. figure:: /_static/images/gns3-09.png - -Click ``Finish`` to end the **New QEMU VM template** wizard. - -.. figure:: /_static/images/gns3-10.png - -Now the VM settings have to be edited. - -Being again at the **Preferences** window, having **Qemu VMs** -selected and having our new VM selected, click the ``Edit`` button. - -.. figure:: /_static/images/gns3-11.png - -In the **General settings** tab of your **QEMU VM template -configuration**, do the following: - -* Click on the ``Browse...`` button to choose the **Symbol** you want to - have representing your VM. -* In **Category** select in which group you want to find your VM. -* Set the **Boot priority** to **CD/DVD-ROM**. - -.. figure:: /_static/images/gns3-12.png - -At the **HDD** tab, change the Disk interface to **sata** to speed up -the boot process. - -.. figure:: /_static/images/gns3-13.png - -At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image -you want to install. - -.. figure:: /_static/images/gns3-14.png - -.. note:: You probably will want to accept to copy the .iso file to your - default image directory when you are asked. - -In the **Network** tab, set **0** as the number of adapters, set the -**Name format** to **eth{0}** and the **Type** to **Paravirtualized -Network I/O (virtio-net-pci)**. - -.. figure:: /_static/images/gns3-15.png - -In the **Advanced** tab, unmark the checkbox **Use as a linked base -VM** and click ``OK``, which will save and close the **QEMU VM template -configuration** window. - -.. figure:: /_static/images/gns3-16.png - -At the general **Preferences** window, click ``OK`` to save and close. - -.. figure:: /_static/images/gns3-17.png - - -.. _vyos_installation: - -VyOS installation ------------------ - -* Create a new project. -* Drag the newly created VyOS VM into it. -* Start the VM. -* Open a console. - The console should show the system booting. It will ask for the login - credentials, you are at the VyOS live system. -* `Install VyOS `__ - as normal (that is, using the ``install image`` command). - -* After a successful installation, shutdown the VM with the ``poweroff`` - command. - -* **Delete the VM** from the GNS3 project. - -The *VyOS-hda.qcow2* file now contains a working VyOS image and can be -used as a template. But it still needs some fixes before we can deploy -VyOS in our labs. - -.. _vyos_vm_configuration: - -VyOS VM configuration ---------------------- - -To turn the template into a working VyOS machine, further steps are -necessary as outlined below: - -**General settings** tab: Set the boot priority to **HDD** - -.. figure:: /_static/images/gns3-20.png - -**CD/DVD** tab: Unmount the installation image file by clearing the -**Image** entry field. - -.. figure:: /_static/images/gns3-21.png - -Set the number of required network adapters, for example **4**. - -.. figure:: /_static/images/gns3-215.png - -**Advanced** settings tab: Mark the checkbox **Use as a linked -base VM** and click ``OK`` to save the changes. - -.. figure:: /_static/images/gns3-22.png - -The VyOS VM is now ready to be deployed. - diff --git a/docs/appendix/virtual/vyos-on-vmware.rst b/docs/appendix/virtual/vyos-on-vmware.rst deleted file mode 100644 index c4299cbf..00000000 --- a/docs/appendix/virtual/vyos-on-vmware.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _vyosonvmware: - -Running on VMware ESXi -###################### - -ESXi 5.5 or later -***************** - -.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO -using the normal process around `install image`. - -.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. - -Memory Contention Considerations --------------------------------- -When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. -This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to -force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of -guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted -lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. - -It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. - - - - - -References ----------- - -https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html - diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst deleted file mode 100644 index db618431..00000000 --- a/docs/appendix/vyos-on-baremetal.rst +++ /dev/null @@ -1,411 +0,0 @@ -.. _vyosonbaremetal: - -##################### -Running on Bare Metal -##################### - -Supermicro A2SDi (Atom C3000) -============================= - -I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. -Running VyOS on an UEFI only device is supported as of VyOS release 1.2. - -Shopping Cart -------------- - -* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) -* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) -* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN - with Intel C3000 SoC 1GbE) -* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) -* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) -* 1x Supermicro MCP-320-81302-0B (optional FAN tray) - -Optional (10GE) ---------------- -If you want to get additional ethernet ports or even 10GE connectivity -the following optional parts will be required: - -* 1x Supermicro RSC-RR1U-E8 (Riser Card) -* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) - -Latest VyOS rolling releases boot without any problem on this board. You also -receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no -information about `OpenBMC `_ so far on this -motherboard). - -Pictures --------- - -.. figure:: /_static/images/1u_vyos_back.jpg - :scale: 25 % - :alt: CSE-505-203B Back - -.. figure:: /_static/images/1u_vyos_front.jpg - :scale: 25 % - :alt: CSE-505-203B Front - -.. figure:: /_static/images/1u_vyos_front_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B Open 1 - -.. figure:: /_static/images/1u_vyos_front_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B Open 2 - -.. figure:: /_static/images/1u_vyos_front_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 1 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 2 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open 3 - -.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg - :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open - - -.. _pc-engines-apu4: - -PC Engines APU4 -================ - -As this platform seems to be quite common in terms of noise, cost, power and -performance it makes sense to write a small installation manual. - -This guide was developed using an APU4C4 board with the following specs: - -* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI - support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. -* 4 GB DDR3-1333 DRAM, with optional ECC support -* About 6 to 10W of 12V DC power depending on CPU load -* 2 miniPCI express (one with SIM socket for 3G modem). -* 4 Gigabit Ethernet channels using Intel i211AT NICs - -The board can be powered via 12V from the front or via a 5V onboard connector. - -Shopping Cart -------------- - -* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM -* 1x Kingston SUV500MS/120G -* 1x VARIA Group Item 326745 19" dual rack for APU4 - -The 19" enclosure can accommodate up to two APU4 boards - there is a single and -dual front cover. - -Extension Modules -^^^^^^^^^^^^^^^^^ - -WiFi -"""" - -Refer to :ref:`wireless-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform: - -* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. - -WWAN -"""" - -Refer to :ref:`wwan-interface` for additional information, below listed modules -have been tested successfully on this Hardware platform using VyOS 1.3 (equuleus): - -* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) -* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) -* Huawei ME909u-521 miniPCIe card (LTE) - -VyOS 1.2 (crux) ---------------- - -Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (:vytask:`T1327`). - -Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. - -Connect serial port to a PC through null modem cable (RXD / TXD crossed over). -Set terminal emulator to 115200 8N1. - -.. code-block:: none - - PC Engines apu4 - coreboot build 20171130 - BIOS version v4.6.4 - 4080 MB ECC DRAM - SeaBIOS (version rel-1.11.0.1-0-g90da88d) - - Press F10 key now for boot menu: - - Select boot device: - - 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) - 2. USB MSC Drive Generic Flash Disk 8.07 - 3. Payload [memtest] - 4. Payload [setup] - -Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing -``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` -to continue. - -.. code-block:: none - - lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk - x VyOS - Boot Menu x - tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu - x Live (amd64-vyos) x - x Live (amd64-vyos failsafe) x - x x - mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj - -The image will be loaded and the last lines you will get will be: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - -The Kernel will now spin up using a different console setting. Set terminal -emulator to 9600 8N1 and after a while your console will show: - -.. code-block:: none - - Loading /live/vmlinuz... ok - Loading /live/initrd.img... - Welcome to VyOS - vyos ttyS0 - - vyos login: - -You can now proceed with a regular image installation as described in -:ref:`installation`. - -As the APU board itself still used a serial setting of 115200 8N1 it is -strongly recommended that you change the VyOS serial interface settings after -your first successful boot. - -Use the following command to adjust the :ref:`serial-console` settings: - -.. code-block:: none - - set system console device ttyS0 speed 115200 - -.. note:: Once you ``commit`` the above changes access to the serial interface - is lost until you set your terminal emulator to 115200 8N1 again. - -.. code-block:: none - - vyos@vyos# show system console - device ttyS0 { - speed 115200 - } - -VyOS 1.2 (rolling) ------------------- - -Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as :vytask:`T1327` was successfully -implemented. - -Simply proceed with a regular image installation as described in -:ref:`installation`. - -Pictures --------- - -.. note:: Both device types operate without any moving parts and emit zero - noise. - -Rack Mount -^^^^^^^^^^ - -.. figure:: /_static/images/apu4_rack_1.jpg - :scale: 25 % - :alt: APU4 rack closed - -.. figure:: /_static/images/apu4_rack_2.jpg - :scale: 25 % - :alt: APU4 rack front - -.. figure:: /_static/images/apu4_rack_3.jpg - :scale: 25 % - :alt: APU4 rack module #1 - -.. figure:: /_static/images/apu4_rack_4.jpg - :scale: 25 % - :alt: APU4 rack module #2 - -.. figure:: /_static/images/apu4_rack_5.jpg - :scale: 25 % - :alt: APU4 rack module #3 with PSU - -VyOS custom print -""""""""""""""""" - -.. figure:: /_static/images/apu4_rack_vyos_print.jpg - :scale: 25 % - :alt: APU4 custom VyOS powder coat - -Desktop / Bench Top -^^^^^^^^^^^^^^^^^^^ - -.. figure:: /_static/images/apu4_desk_1.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_2.jpg - :scale: 25 % - :alt: APU4 desktop closed - -.. figure:: /_static/images/apu4_desk_3.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. figure:: /_static/images/apu4_desk_4.jpg - :scale: 25 % - :alt: APU4 desktop back - -.. _Rufus: https://rufus.ie/ - -Qotom Q355G4 -============ - -The install on this Q355G4 box is pretty much plug and play. The port numbering -the OS does might differ from the labels on the outside, but the UEFI firmware -has a port blink test built in with MAC addresses so you can very quickly -identify which is which. MAC labels are on the inside as well, and this test -can be done from VyOS or plain Linux too. Default settings in the UEFI will -make it boot, but depending on your installation wishes (i.e. storage type, -boot type, console type) you might want to adjust them. This Qotom company -seems to be the real OEM/ODM for many other relabelling companies like -Protectli. - -Hardware --------- - -There are a number of other options, but they all seem to be close to Intel -reference designs, with added features like more serial ports, more network -interfaces and the likes. Because they don't deviate too much from standard -designs all the hardware is well-supported by mainline. It accepts one LPDDR3 -SO-DIMM, but chances are that if you need more than that, you'll also want -something even beefier than an i5. There are options for antenna holes, and SIM -slots, so you could in theory add an LTE/Cell modem (not tested so far). - -The chassis is a U-shaped alu extrusion with removable I/O plates and removable -bottom plate. Cooling is completely passive with a heatsink on the SoC with -internal and external fins, a flat interface surface, thermal pad on top of -that, which then directly attaches to the chassis, which has fins as well. It -comes with mounting hardware and rubber feet, so you could place it like a -desktop model or mount it on a VESA mount, or even wall mount it with the -provided mounting plate. The closing plate doubles as internal 2.5" mounting -place for an HDD or SSD, and comes supplied with a small SATA cable and SATA -power cable. - -Power supply is a 12VDC barrel jack, and included switching power supply, which -is why SATA power regulation is on-board. Internally it has a NUC-board-style -on-board 12V input header as well, the molex locking style. - -There are WDT options and auto-boot on power enable, which is great for remote -setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled -in enforcement mode, which is good but also means no coreboot option), yet has -most options available to configure (so it's not locked out like most firmwares -are). - -An external RS232 serial port is available, internally a GPIO header as well. -It does have Realtek based audio on board for some reason, but you can disable -that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS -mode and HDMI BIOS mode depends on what is connected at startup; it goes into -serial mode if you disconnect HDMI and plug in serial, in all other cases it's -HDMI mode. - -Partaker i5 -=========== - -.. figure:: ../_static/images/600px-Partaker-i5.jpg - -I believe this is actually the same hardware as the Protectli. I purchased it -in June 2018. It came pre-loaded with pfSense. - -`Manufacturer product page `_. - -Installation ------------- - -* Write VyOS ISO to USB drive of some sort -* Plug in VGA, power, USB keyboard, and USB drive -* Press "SW" button on the front (this is the power button; I don't know what - "SW" is supposed to mean). -* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, - but with a few tries you should be able to get into the BIOS. -* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 - (EHCI) to Enabled. Without doing this, the USB drive won't boot. -* Boot to the VyOS installer and install as usual. - -Warning the interface labels on my device are backwards; the left-most "LAN4" -port is eth0 and the right-most "LAN1" port is eth3. - -Acrosser AND-J190N1 -=================== - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg - -.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg - -This microbox network appliance was build to create OpenVPN bridges. It can -saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN -http://www.acrosser.com/upload/AND-J190_J180N1-2.pdf - -You may have to add your own RAM and HDD/SSD. There is no VGA connector. But -Acrosser provides a DB25 adapter for the VGA header on the motherboard (not -used). - -BIOS Settings: --------------- - -First thing you want to do is getting a more user friendly console to configure -BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. - -For practical issues change speed from 115200 to 9600. 9600 is the default -speed at which both linux kernel and VyOS will reconfigure the serial port -when loading. - -Connect to serial (115200bps). Power on the appliance and press Del in the -console when requested to enter BIOS settings. - -Advanced > Serial Port Console Redirection > Console Redirection Settings: - -* Terminal Type : VT100+ -* Bits per second : 9600 - -Save, reboot and change serial speed to 9600 on your client. - -Some options have to be changed for VyOS to boot correctly. With XHCI enabled -the installer can’t access the USB key. Enable EHCI instead. - -Reboot into BIOS, Chipset > South Bridge > USB Configuration: - -* Disable XHCI -* Enable USB 2.0 (EHCI) Support - -Install VyOS: -------------- - -Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and -`LinuxLive USB Creator `_. - -I'm not sure if it helps the process but I changed default option to live-serial -(line “default xxxx”) on the USB key under syslinux/syslinux.cfg. - -I connected the key to one black USB port on the back and powered on. The first -VyOS screen has some readability issues. Press :kbd:`Enter` to continue. - -Then VyOS should boot and you can perform the ``install image`` diff --git a/docs/appendix/vyos-on-clouds.rst b/docs/appendix/vyos-on-clouds.rst deleted file mode 100644 index 33b7011e..00000000 --- a/docs/appendix/vyos-on-clouds.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. _vyos-on-clouds: - -Running on Clouds -################# - -Amazon AWS -********** - -Deploy VM ---------- - -Deploy VyOS on Amazon :abbr:`AWS (Amazon Web Services)` - -1. Click to ``Instances`` and ``Launch Instance`` - -.. figure:: /_static/images/cloud-aws-01.png - -2. On the marketplace search "VyOS" - -.. figure:: /_static/images/cloud-aws-02.png - -3. Choose the instance type. Minimum recommendation start from ``m3.medium`` - -.. figure:: /_static/images/cloud-aws-03.png - -4. Configure instance for your requirements. Select number of instances / network / subnet - -.. figure:: /_static/images/cloud-aws-04.png - -5. Additional storage. You can remove additional storage ``/dev/sdb``. First root device will be ``/dev/xvda``. You can skeep this step. - -.. figure:: /_static/images/cloud-aws-05.png - -6. Configure Security Group. It's recommended that you configure ssh access only from certain address sources. Or permit any (by default). - -.. figure:: /_static/images/cloud-aws-06.png - -7. Select SSH key pair and click ``Launch Instances`` - -.. figure:: /_static/images/cloud-aws-07.png - -8. Find out your public IP address. - -.. figure:: /_static/images/cloud-aws-08.png - -9. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 - vyos@ip-192-0-2-10:~$ - - - - -References ----------- -https://console.aws.amazon.com/ - -Azure -***** - -Deploy VM ---------- - -Deploy VyOS on Azure. - -1. Go to the Azure services and Click to **Add new Virtual machine** - -2. Choose vm name, resource group, region and click **Browse all public and private images** - -.. figure:: /_static/images/cloud-azure-01.png - -3. On the marketplace search ``VyOS`` - -.. figure:: /_static/images/cloud-azure-02.png - -4. Generate new SSH key pair or use existing. - -.. figure:: /_static/images/cloud-azure-03.png - -5. Define network, subnet, Public IP. Or it will be created by default. - -.. figure:: /_static/images/cloud-azure-04.png - -6. Click ``Review + create``. After fiew second your deployment will be complete - -.. figure:: /_static/images/cloud-azure-05.png - -7. Click to your new vm and find out your Public IP address. - -.. figure:: /_static/images/cloud-azure-06.png - -8. Connect to the instance by SSH key. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 - vyos@vyos-doc-r1:~$ - -Add interface -------------- - -If instance was deployed with one **eth0** ``WAN`` interface and want to add new one. -To add new interface an example **eth1** ``LAN`` you need shutdown the instance. Attach the interface in the Azure portal and then start the instance. - -.. NOTE:: Azure does not allow you attach interface when the instance in the **Running** state. - -References ----------- -https://azure.microsoft.com - -Google Cloud Platform -********************* - -Deploy VM ---------- - -To deploy VyOS on GCP (Google Cloud Platform) - -1. Generate SSH key pair type **ssh-rsa** from the host that will connect to VyOS. - - Example: - - .. code-block:: none - - ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" - - -.. NOTE:: In name "vyos@mypc" The first value must be "**vyos**". Because default user is vyos and google api uses this option. - - -2. Open GCP console and navigate to the menu **Metadata**. Choose **SSH Keys** and click ``edit``. - -.. figure:: /_static/images/cloud-gcp-01.png - - -Click **Add item** and paste your public ssh key. Click ``Save``. - -.. figure:: /_static/images/cloud-gcp-02.png - - -2. On marketplace search "VyOS" - -3. Change Deployment name/Zone/Machine type and click ``Deploy`` - -.. figure:: /_static/images/cloud-gcp-03.png - -4. After fiew seconds click to ``instance`` - -.. figure:: /_static/images/cloud-gcp-04.png - -5. Find out your external IP address - -.. figure:: /_static/images/cloud-gcp-05.png - -6. Connect to the instance. SSH key was generated in the first step. - - .. code-block:: none - - ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 - vyos@vyos-r1-vm:~$ - -References ----------- -https://console.cloud.google.com/ - -Oracle -***************** - -References ----------- -https://www.oracle.com/cloud/ diff --git a/docs/image-mgmt.rst b/docs/image-mgmt.rst deleted file mode 100644 index 143d02b2..00000000 --- a/docs/image-mgmt.rst +++ /dev/null @@ -1,193 +0,0 @@ -.. _image-mgmt: - -################ -Image Management -################ - -The VyOS image-based installation is implemented by creating a directory for -each image on the storage device selected during the install process. - -The directory structure of the boot device: - -.. code-block:: none - - / - /boot - /boot/grub - /boot/1.2.0-rolling+201810021347 - -The image directory contains the system kernel, a compressed image of the root -filesystem for the OS, and a directory for persistent storage, such as -configuration. On boot, the system will extract the OS image into memory and -mount the appropriate live-rw sub-directories to provide persistent storage -system configuration. - -This process allows for a system to always boot to a known working state, as -the OS image is fixed and non-persistent. It also allows for multiple releases -of VyOS to be installed on the same storage device. The image can be selected -manually at boot if needed, but the system will otherwise boot the image -configured to be the default. - -.. opcmd:: show system image - - List all available system images which can be bootet on the current system. - - .. code-block:: none - - vyos@vyos:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.2.0-rolling+201810021347 (default boot) - 2: 1.2.0-rolling+201810021217 - 3: 1.2.0-rolling+201809252218 - - -.. opcmd:: delete system image [image-name] - - Delete no longer needed images from the system. You can specify an optional - image name to delete, the image name can be retrieved via a list of available - images can be shown using the :opcmd:`show system image`. - - .. code-block:: none - - vyos@vyos:~$ delete system image - The following image(s) can be deleted: - - 1: 1.3-rolling-201912181733 (default boot) (running image) - 2: 1.3-rolling-201912180242 - 3: 1.2.2 - 4: 1.2.1 - - Select the image to delete: 2 - - Are you sure you want to delete the - "1.3-rolling-201912180242" image? (Yes/No) [No]: y - Deleting the "1.3-rolling-201912180242" image... - Done - -.. opcmd:: show version - - Show current system image version. - - .. code-block:: none - - vyos@vyos:~$ show version - Version: VyOS 1.3-rolling-201912181733 - Built by: autobuild@vyos.net - Built on: Wed 18 Dec 2019 17:33 UTC - Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c - Build Commit ID: f7ce0d8a692f2d - - Architecture: x86_64 - Boot via: installed image - System type: bare metal - - Hardware vendor: VMware, Inc. - Hardware model: VMware Virtual Platform - Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 - Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 - - Copyright: VyOS maintainers and contributors - - -.. _update_vyos: - -Update VyOS -=========== - -New system images can be added using the :opcmd:`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. - -.. note:: Only LTS releases are PGP-signed. - -.. opcmd:: add system image [vrf name] [username user [password pass]] - - Use this command to install a new system image. You can reach the - image from the web (http://, https://) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. - - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. - -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the :opcmd:`delete system image` -command. - -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. - -.. note:: If you have any personal files, like some scripts you created, - and you don't want them to be lost during the upgrade, make sure - those files are stored in ``/config`` as this directory is always copied - to newer installed images. - -You can access files from a previous installation and copy them to your -current image if they were located in the ``/config`` directory. This -can be done using the :opcmd:`copy` command. So, for instance, in order -to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the -following command: - -.. code:: - - copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 - - -Example -""""""" - -.. code-block:: none - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [vyos-1.3-rolling-201912201452]: - - OK. This image will be named: vyos-1.3-rolling-201912201452 - - -.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: - | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - -After reboot you might want to verify the version you are running with -the :opcmd:`show version` command. - - -System rollback -=============== - -If you need to rollback to a previous image, you can easily do so. First -check the available images through the :opcmd:`show system image` -command and then select your image with the following command: - -.. opcmd:: set system image default-boot [image-name] - - Select the default boot image which will be started on the next boot - of the system. - -Then reboot the system. - -.. note:: VyOS automatically associates the configuration to the image, - so you don't need to worry about that. Each image has a unique copy - of its configuration. - -If you have access to the console, there is a another way to select -your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/cloud/aws.rst b/docs/installation/cloud/aws.rst new file mode 100644 index 00000000..33684bb0 --- /dev/null +++ b/docs/installation/cloud/aws.rst @@ -0,0 +1,54 @@ +########## +Amazon AWS +########## + +Deploy VM +--------- + +Deploy VyOS on Amazon :abbr:`AWS (Amazon Web Services)` + +1. Click to ``Instances`` and ``Launch Instance`` + +.. figure:: /_static/images/cloud-aws-01.png + +2. On the marketplace search "VyOS" + +.. figure:: /_static/images/cloud-aws-02.png + +3. Choose the instance type. Minimum recommendation start from ``m3.medium`` + +.. figure:: /_static/images/cloud-aws-03.png + +4. Configure instance for your requirements. Select number of instances / network / subnet + +.. figure:: /_static/images/cloud-aws-04.png + +5. Additional storage. You can remove additional storage ``/dev/sdb``. First root device will be ``/dev/xvda``. You can skeep this step. + +.. figure:: /_static/images/cloud-aws-05.png + +6. Configure Security Group. It's recommended that you configure ssh access only from certain address sources. Or permit any (by default). + +.. figure:: /_static/images/cloud-aws-06.png + +7. Select SSH key pair and click ``Launch Instances`` + +.. figure:: /_static/images/cloud-aws-07.png + +8. Find out your public IP address. + +.. figure:: /_static/images/cloud-aws-08.png + +9. Connect to the instance by SSH key. + + .. code-block:: none + + ssh -i ~/.ssh/amazon.pem vyos@203.0.113.3 + vyos@ip-192-0-2-10:~$ + + + + +References +---------- +https://console.aws.amazon.com/ \ No newline at end of file diff --git a/docs/installation/cloud/azure.rst b/docs/installation/cloud/azure.rst new file mode 100644 index 00000000..39206f3b --- /dev/null +++ b/docs/installation/cloud/azure.rst @@ -0,0 +1,53 @@ +##### +Azure +##### + +Deploy VM +--------- + +Deploy VyOS on Azure. + +1. Go to the Azure services and Click to **Add new Virtual machine** + +2. Choose vm name, resource group, region and click **Browse all public and private images** + +.. figure:: /_static/images/cloud-azure-01.png + +3. On the marketplace search ``VyOS`` + +.. figure:: /_static/images/cloud-azure-02.png + +4. Generate new SSH key pair or use existing. + +.. figure:: /_static/images/cloud-azure-03.png + +5. Define network, subnet, Public IP. Or it will be created by default. + +.. figure:: /_static/images/cloud-azure-04.png + +6. Click ``Review + create``. After fiew second your deployment will be complete + +.. figure:: /_static/images/cloud-azure-05.png + +7. Click to your new vm and find out your Public IP address. + +.. figure:: /_static/images/cloud-azure-06.png + +8. Connect to the instance by SSH key. + + .. code-block:: none + + ssh -i ~/.ssh/vyos_azure vyos@203.0.113.3 + vyos@vyos-doc-r1:~$ + +Add interface +------------- + +If instance was deployed with one **eth0** ``WAN`` interface and want to add new one. +To add new interface an example **eth1** ``LAN`` you need shutdown the instance. Attach the interface in the Azure portal and then start the instance. + +.. NOTE:: Azure does not allow you attach interface when the instance in the **Running** state. + +References +---------- +https://azure.microsoft.com diff --git a/docs/installation/cloud/gcp.rst b/docs/installation/cloud/gcp.rst new file mode 100644 index 00000000..66e75704 --- /dev/null +++ b/docs/installation/cloud/gcp.rst @@ -0,0 +1,55 @@ +##################### +Google Cloud Platform +##################### + +Deploy VM +--------- + +To deploy VyOS on GCP (Google Cloud Platform) + +1. Generate SSH key pair type **ssh-rsa** from the host that will connect to VyOS. + + Example: + + .. code-block:: none + + ssh-keygen -t rsa -f ~/.ssh/vyos_gcp -C "vyos@mypc" + + +.. NOTE:: In name "vyos@mypc" The first value must be "**vyos**". Because default user is vyos and google api uses this option. + + +2. Open GCP console and navigate to the menu **Metadata**. Choose **SSH Keys** and click ``edit``. + +.. figure:: /_static/images/cloud-gcp-01.png + + +Click **Add item** and paste your public ssh key. Click ``Save``. + +.. figure:: /_static/images/cloud-gcp-02.png + + +2. On marketplace search "VyOS" + +3. Change Deployment name/Zone/Machine type and click ``Deploy`` + +.. figure:: /_static/images/cloud-gcp-03.png + +4. After fiew seconds click to ``instance`` + +.. figure:: /_static/images/cloud-gcp-04.png + +5. Find out your external IP address + +.. figure:: /_static/images/cloud-gcp-05.png + +6. Connect to the instance. SSH key was generated in the first step. + + .. code-block:: none + + ssh -i ~/.ssh/vyos_gcp vyos@203.0.113.3 + vyos@vyos-r1-vm:~$ + +References +---------- +https://console.cloud.google.com/ \ No newline at end of file diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst new file mode 100644 index 00000000..5236f092 --- /dev/null +++ b/docs/installation/cloud/index.rst @@ -0,0 +1,13 @@ +################################## +Running VyOS in Cloud Environments +################################## + + + +.. toctree:: + :caption: Content + + aws + azure + gcp + oracel \ No newline at end of file diff --git a/docs/installation/cloud/oracel.rst b/docs/installation/cloud/oracel.rst new file mode 100644 index 00000000..72c40127 --- /dev/null +++ b/docs/installation/cloud/oracel.rst @@ -0,0 +1,8 @@ +###### +Oracle +###### + + +References +---------- +https://www.oracle.com/cloud/ \ No newline at end of file diff --git a/docs/installation/image.rst b/docs/installation/image.rst new file mode 100644 index 00000000..074a0245 --- /dev/null +++ b/docs/installation/image.rst @@ -0,0 +1,115 @@ +.. _image-mgmt: + +################ +Image Management +################ + +The VyOS image-based installation is implemented by creating a directory for +each image on the storage device selected during the install process. + +The directory structure of the boot device: + +.. code-block:: none + + / + /boot + /boot/grub + /boot/1.2.0-rolling+201810021347 + +The image directory contains the system kernel, a compressed image of the root +filesystem for the OS, and a directory for persistent storage, such as +configuration. On boot, the system will extract the OS image into memory and +mount the appropriate live-rw sub-directories to provide persistent storage +system configuration. + +This process allows for a system to always boot to a known working state, as +the OS image is fixed and non-persistent. It also allows for multiple releases +of VyOS to be installed on the same storage device. The image can be selected +manually at boot if needed, but the system will otherwise boot the image +configured to be the default. + +.. opcmd:: show system image + + List all available system images which can be bootet on the current system. + + .. code-block:: none + + vyos@vyos:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.2.0-rolling+201810021347 (default boot) + 2: 1.2.0-rolling+201810021217 + 3: 1.2.0-rolling+201809252218 + + +.. opcmd:: delete system image [image-name] + + Delete no longer needed images from the system. You can specify an optional + image name to delete, the image name can be retrieved via a list of available + images can be shown using the :opcmd:`show system image`. + + .. code-block:: none + + vyos@vyos:~$ delete system image + The following image(s) can be deleted: + + 1: 1.3-rolling-201912181733 (default boot) (running image) + 2: 1.3-rolling-201912180242 + 3: 1.2.2 + 4: 1.2.1 + + Select the image to delete: 2 + + Are you sure you want to delete the + "1.3-rolling-201912180242" image? (Yes/No) [No]: y + Deleting the "1.3-rolling-201912180242" image... + Done + +.. opcmd:: show version + + Show current system image version. + + .. code-block:: none + + vyos@vyos:~$ show version + Version: VyOS 1.3-rolling-201912181733 + Built by: autobuild@vyos.net + Built on: Wed 18 Dec 2019 17:33 UTC + Build UUID: bccde2c3-261c-49cc-b421-9b257204e06c + Build Commit ID: f7ce0d8a692f2d + + Architecture: x86_64 + Boot via: installed image + System type: bare metal + + Hardware vendor: VMware, Inc. + Hardware model: VMware Virtual Platform + Hardware S/N: VMware-42 1d 83 b9 fe c1 bd b2-7d 3d 49 db 94 18 f5 c9 + Hardware UUID: b9831d42-c1fe-b2bd-7d3d-49db9418f5c9 + + Copyright: VyOS maintainers and contributors + + + + + +System rollback +=============== + +If you need to rollback to a previous image, you can easily do so. First +check the available images through the :opcmd:`show system image` +command and then select your image with the following command: + +.. opcmd:: set system image default-boot [image-name] + + Select the default boot image which will be started on the next boot + of the system. + +Then reboot the system. + +.. note:: VyOS automatically associates the configuration to the image, + so you don't need to worry about that. Each image has a unique copy + of its configuration. + +If you have access to the console, there is a another way to select +your booting image: reboot and use the GRUB menu at startup. diff --git a/docs/installation/index.rst b/docs/installation/index.rst index af265121..e5a2a6fd 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -12,7 +12,8 @@ Installation and Image Management iso virtual/index cloud/index + vyos-on-baremetal update image migrate-from-vyatta - ../vyos-on-baremetal \ No newline at end of file + \ No newline at end of file diff --git a/docs/installation/iso.rst b/docs/installation/iso.rst new file mode 100644 index 00000000..f48ad91c --- /dev/null +++ b/docs/installation/iso.rst @@ -0,0 +1,2 @@ +iso +### \ No newline at end of file diff --git a/docs/installation/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst new file mode 100644 index 00000000..f15c3d5a --- /dev/null +++ b/docs/installation/migrate-from-vyatta.rst @@ -0,0 +1,164 @@ +.. _migrate_from_vyatta: + +Migrate from Vyatta Core +======================== + +VyOS 1.x line aims to preserve backward compatibility and provide a safe +upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as +VC7.0. + +Vyatta release compatibility +---------------------------- + +Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. + +Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the +"modify" firewall was removed and replaced with the ``set policy route`` +command family, old configs can not be automatically converted. You will have +to adapt it to post-6.5 Vyatta syntax manually. + +.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been + renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using + zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change + interface names in rules for remote access VPN. + +Upgrade procedure +----------------- + +You just use ``add system image``, as if it was a new VC release (see +:ref:`update_vyos` for additional information). The only thing you want to do +is to verify the new images digital signature. You will have to add the public +key manually once as it is not shipped the first time. + +.. code-block:: none + + vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key + Connecting to vyos.net (x.x.x.x:80) + so3group_maintainers 100% |*************************| 3125 --:--:-- ETA + vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key + OK + vyatta@vyatta:~$ + +For completion the key below corresponds to the key listed in the URL above. + +.. code-block:: none + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (GNU/Linux) + + mQINBFIIUZwBEADGl+wkZpYytQxd6LnjDZZScziBKYJbjInetYeS0SUrgpqnPkzL + 2CiGfPczLwpYY0zWxpUhTvqjFsE5yDpgs0sPXIgUTFE1qfZQE+WD1I1EUM6sp/38 + 2xKQ9QaNc8oHuYINLYYmNYra6ZjIGtQP9WOX//IDYB3fhdwlmiW2z0hux2OnPWdh + hPZAmSrx5AiXFEEREJ1cAQyvYk7hgIRvM/rdQMUm+u4/z+S4mxCHE10KzlqOGhRv + hA8WQxHCVusMFGwXoKHxYf9OQpV7lsfOCODfXOMP/L9kHQ5/gBsLL5hHst+o/3VG + ec0QuVrVkBBehgrqhfJW2noq+9gTooURGImQHEOyE0xpJdFrrgk5Ii9RqQwdVRzI + ZPbqbo8uuldZIRJRGnfx+vAR9812yo38NVZ/X0P/hkkrx+UeGVgpC/ao5XLRiOzL + 7ZBMWLA6FVmZ7mkpqdzuMXX5548ApACm6EKErULIhTYDGDzFxA3cf6gr5VVi4usD + wglVs+FHuiLehmuuPTMoVcT2R6+Ht44hG3BmQmKzh/SSEa1g9gKgrhZrMdIyK4hu + GvMqLw9z9BgJbWB3BgXOUdlkXLDwBvVpEcWsPJgxSjAvjAbLLE4YkKAdYU8bQ0Pd + JuN485tcXxgQCadFZB0gcipQAvVf4b810HrY88g6FldfauHxiACOlXscZwARAQAB + tDBTTzMgR3JvdXAgTWFpbnRhaW5lcnMgPG1haW50YWluZXJzQHNvM2dyb3VwLm5l + dD6JAjgEEwECACIFAlIIUZwCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJ + ELdE4lqkQubp8GsQAKntoRFG6bWX/4WPw7Vo7kIF5kWcmv3lVb0AQkacscWope7T + Iq0VcgpAycJue2bSS9LAsvNtpVkQmFawbwFjqB3CC5NbPNQ4Kf+gswKa+yaHwejo + 7dkslAwxgXHe5g76DG7CVLMsMg6zVDFYuzeksPywls/OJBIpkuGqeXy9tAHjQzjA + SlZV3Gsx7azESjiVQ73EUBt2OXkwN4TN9TEHAnVsrNIXHwFl1VfFsSG1Q6uZDtkk + CB4DZJKN4RzCY2QSwMAqRRC2OXdwk5IAk8wwCGoFpp0UV6CO9YCeOaqJderEcBA4 + MGHqdiPDIbH5wvckjZzFznU/Paz3MwPwBdtN+WSKvwf+JItSiUqm8Dy2Pl/1cnux + 1g1I4WQlXUVaS/MDusqL7tbS8k5A5a2+YVMxShWH9BhXZwNXzEihl4sm8Hrg5SvZ + givJj2y93WoL69Wq0/86wkkH2xcrz4gsiUcQf5YXU/RHXOLnPR29/pg8TS0L7sST + dv0X23C2IpfqYoqN7YZ3K0Wczhi0yLPCrc27IczuHgjt/8ICda11xhB1t/pUbvnX + oksehaLp8O3uU8GyAsTfUgpijZFc/3jIadOl0L9NGUbYYgPzFeaZTa/njeEbz3wX + PZMn278sbL9UhupI5Hx7eREbKzV4VPVKz81ndKNMXyuJHXv2R0xou3nvuo1WuQIN + BFIIUZwBEADAhoYPDCSogG41Naq+wFkG+IPszqe0dW/UWg0xrZDT0UblwDSd4OGY + 7FATMIhjOUyFxk6+XKA5CDCWP8Npkl0modTL59uVWNxU1vUKincc/j4ipHQeAhE6 + fvZkrprvADD8TYIGesl/3EGNc7bzc5ZqX71hKPHG+autRtgFSOR2PSXD9MlJXIBb + RzHAXxlh72zvsGadcxLJm4pSWXitkR/5Wc3e0IippKdzGwZnCDpNmcBGtSTFgixP + JqyRZFVCPWs7jr/oQeZnq65wJp1KD2HvhhKHJfsPrnNjLSm1SQVh8hXzE9odcv6N + mJB7tNXywuROBt6a01ojBa9J3zuMYQj3iQl2MhxtHylKVBjr7NjZ4evZbLsRMxY1 + hYk7sl+ZxCPFeOZ9D2ppU/CUDXCS095I1x+s+VuiUNf/3yd8ahCWDXVp9nsXyYjm + 2pHIxb2F6r8Vd4AjlD2MQwszECS88INF3l/9ksIHEMKuuW+JAC9FiZ7k4IGcIltv + If/V2TgE6t6qoWIlmLhMTjOyJpwnokY1nIuXHH7yp+HsuqnYnf/dgLnt4czPLeHO + +TdIDHhUym0AKlCcbdgn0C6EJVTnA8BFgFjiIOMAeT0rhATg0W/cND8KQcX4V9wM + nHSEsgSEuP9H+67xuRx5Imuh5ntecrcuCYSNuOneUXWPThDKQPO9lQARAQABiQIf + BBgBAgAJBQJSCFGcAhsMAAoJELdE4lqkQubpc+0P/0IzUx8nTpF0/ii2TA0YCOgj + tviM6PRTVPrFcxijNeXiIMHZYrALYUvXxXGp1IZBP3IcOyuZNp2WLqF/f9a3cIr1 + 9b/LJPrwopGqV3K30lormk7hH0s3IXbhd0ZYWvRj+5kQ8TFRAFfPwjlItzjYJmYX + AGJmM9PxJID/4LgWSfQ/ZfNu7MJ7+2goQLu9b6x7UC1FlE4q1lcjBvHjVPM//S9G + lGAHaysyTjVu88W2wwBpBrO1MQnDvqFRddXPOIWp0jecBMUd4E0fB36yuStsXZT3 + RN4V8vKRBYXuqHhiTwZeh153cHZk2EZBwz5A6DJubMaGdJTesHW5Qf2goph0pmjC + +XuXn8J6tc5nFDf8DP4AFVMtqa3Brj2fodWd0Zzxq3AVsbX144c1oqJUhO4t3+ie + 8fD/6/jx4iuPCQTfyhHG+zGfyUb2LQ+OVLW1WYTxH5tzHaZUmZFdV2I1kuhuvZ1t + WRlmTnHZOnEb3+t8KCRWzRMfweTzXfRRKBC0/QpeX1r5pbaMHH8zF/J5PKmL0+jg + +DS8JSbSfv7Ke6rplf7lHYaDumAFZfxXuQkajzLZbX0E5Xu5BNz4Vq6LGBj7LDXL + gswIK8FFgZB+W8zwOqUV1vjIr9wkdLifXXezKpTeYpFDGLdfsK+uNAtGyvI61TDi + Pr6fWpIruuc7Gg9rUF0L + =VQTr + -----END PGP PUBLIC KEY BLOCK----- + +Next add the VyOS image. + +This example uses VyOS 1.0.0, however, it's better to install the latest +release. + +.. code-block:: none + + vyatta@vyatta:~$ show system image + The system currently has the following image(s) installed: + 1: VC6.6R1 (default boot) (running image) + + vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso + Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 + Found it. Checking digital signature... + gpg: directory `/root/.gnupg' created + gpg: new configuration file `/root/.gnupg/gpg.conf' created + gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run + gpg: keyring `/root/.gnupg/pubring.gpg' created + gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 + gpg: /root/.gnupg/trustdb.gpg: trustdb created + gpg: Good signature from "SO3 Group Maintainers " + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 + Digital signature is valid. + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [1.0.0]: [return] + OK. This image will be named: 1.0.0 + Installing "1.0.0" image. + Copying new release files... + + Would you like to save the current configuration + directory and config file? (Yes/No) [Yes]: [return] + Copying current configuration... + + Would you like to save the SSH host keys from your + current configuration? (Yes/No) [Yes]: [return] + Copying SSH keys... + Setting up grub configuration... + Done. + + vyatta@vyatta:~$ show system image + The system currently has the following image(s) installed: + + 1: 1.0.0 (default boot) + 2: VC6.6R1 (running image) + +Upon reboot, you should have a working installation of VyOS. + +You can go back to your Vyatta install using the ``set system image +default-boot`` command and selecting the your previous Vyatta Core image. + +.. note:: Future releases of VyOS will break the direct upgrade path from + Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS + 1.2. After this you can continue upgrading to newer releases once you bootet + into VyOS 1.2 once. diff --git a/docs/installation/upate.rst b/docs/installation/upate.rst new file mode 100644 index 00000000..a3a887f0 --- /dev/null +++ b/docs/installation/upate.rst @@ -0,0 +1,79 @@ +.. _update_vyos: + +Update VyOS +=========== + +New system images can be added using the :opcmd:`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image [vrf name] [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (http://, https://) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the :opcmd:`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +.. note:: If you have any personal files, like some scripts you created, + and you don't want them to be lost during the upgrade, make sure + those files are stored in ``/config`` as this directory is always copied + to newer installed images. + +You can access files from a previous installation and copy them to your +current image if they were located in the ``/config`` directory. This +can be done using the :opcmd:`copy` command. So, for instance, in order +to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the +following command: + +.. code:: + + copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 + + +Example +""""""" + +.. code-block:: none + + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [vyos-1.3-rolling-201912201452]: + + OK. This image will be named: vyos-1.3-rolling-201912201452 + + +.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: + | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + +After reboot you might want to verify the version you are running with +the :opcmd:`show version` command. \ No newline at end of file diff --git a/docs/installation/virtual/eve-ng.rst b/docs/installation/virtual/eve-ng.rst new file mode 100644 index 00000000..d5134838 --- /dev/null +++ b/docs/installation/virtual/eve-ng.rst @@ -0,0 +1,8 @@ +###### +EVE-NG +###### + +References +========== + +https://www.eve-ng.net/ \ No newline at end of file diff --git a/docs/installation/virtual/gns3.rst b/docs/installation/virtual/gns3.rst new file mode 100644 index 00000000..93ea9ae2 --- /dev/null +++ b/docs/installation/virtual/gns3.rst @@ -0,0 +1,176 @@ +.. _vyos-on-gns3: + +############### +Running on GNS3 +############### + +Sometimes you may want to test VyOS in a lab environment. +`GNS3 `__ is a network emulation software you +might use for it. + +This guide will provide the necessary steps for installing +and setting up VyOS on GNS3. + +Requirements +------------ + +The following items are required: + +* A VyOS installation image (.iso file). + `Here `__ you + can find how to get it. + +* A working GNS3 installation. For further information see the + `GNS3 documentation `__. + +.. _vm_setup: + +VM setup +-------- + +First, a virtual machine (VM) for the VyOS installation must be created +in GNS3. + +Go to the GNS3 **File** menu, click **New template** and choose select +**Manually create a new Template**. + +.. figure:: /_static/images/gns3-01.png + +Select **Quemu VMs** and then click on the ``New`` button. + +.. figure:: /_static/images/gns3-02.png + +Write a name for your VM, for instance "VyOS", and click ``Next``. + +.. figure:: /_static/images/gns3-03.png + +Select **qemu-system-x86_64** as Quemu binary, then **512MB** of RAM +and click ``Next``. + +.. figure:: /_static/images/gns3-04.png + +Select **telnet** as your console type and click ``Next``. + +.. figure:: /_static/images/gns3-05.png + +Select **New image** for the base disk image of your VM and click +``Create``. + +.. figure:: /_static/images/gns3-06.png + +Use the defaults in the **Binary and format** window and click +``Next``. + +.. figure:: /_static/images/gns3-07.png + +Use the defaults in the **Qcow2 options** window and click ``Next``. + +.. figure:: /_static/images/gns3-08.png + +Set the disk size to 2000 MiB, and click ``Finish`` to end the **Quemu +image creator**. + +.. figure:: /_static/images/gns3-09.png + +Click ``Finish`` to end the **New QEMU VM template** wizard. + +.. figure:: /_static/images/gns3-10.png + +Now the VM settings have to be edited. + +Being again at the **Preferences** window, having **Qemu VMs** +selected and having our new VM selected, click the ``Edit`` button. + +.. figure:: /_static/images/gns3-11.png + +In the **General settings** tab of your **QEMU VM template +configuration**, do the following: + +* Click on the ``Browse...`` button to choose the **Symbol** you want to + have representing your VM. +* In **Category** select in which group you want to find your VM. +* Set the **Boot priority** to **CD/DVD-ROM**. + +.. figure:: /_static/images/gns3-12.png + +At the **HDD** tab, change the Disk interface to **sata** to speed up +the boot process. + +.. figure:: /_static/images/gns3-13.png + +At the **CD/DVD** tab click on ``Browse...`` and locate the VyOS image +you want to install. + +.. figure:: /_static/images/gns3-14.png + +.. note:: You probably will want to accept to copy the .iso file to your + default image directory when you are asked. + +In the **Network** tab, set **0** as the number of adapters, set the +**Name format** to **eth{0}** and the **Type** to **Paravirtualized +Network I/O (virtio-net-pci)**. + +.. figure:: /_static/images/gns3-15.png + +In the **Advanced** tab, unmark the checkbox **Use as a linked base +VM** and click ``OK``, which will save and close the **QEMU VM template +configuration** window. + +.. figure:: /_static/images/gns3-16.png + +At the general **Preferences** window, click ``OK`` to save and close. + +.. figure:: /_static/images/gns3-17.png + + +.. _vyos_installation: + +VyOS installation +----------------- + +* Create a new project. +* Drag the newly created VyOS VM into it. +* Start the VM. +* Open a console. + The console should show the system booting. It will ask for the login + credentials, you are at the VyOS live system. +* `Install VyOS `__ + as normal (that is, using the ``install image`` command). + +* After a successful installation, shutdown the VM with the ``poweroff`` + command. + +* **Delete the VM** from the GNS3 project. + +The *VyOS-hda.qcow2* file now contains a working VyOS image and can be +used as a template. But it still needs some fixes before we can deploy +VyOS in our labs. + +.. _vyos_vm_configuration: + +VyOS VM configuration +--------------------- + +To turn the template into a working VyOS machine, further steps are +necessary as outlined below: + +**General settings** tab: Set the boot priority to **HDD** + +.. figure:: /_static/images/gns3-20.png + +**CD/DVD** tab: Unmount the installation image file by clearing the +**Image** entry field. + +.. figure:: /_static/images/gns3-21.png + +Set the number of required network adapters, for example **4**. + +.. figure:: /_static/images/gns3-215.png + +**Advanced** settings tab: Mark the checkbox **Use as a linked +base VM** and click ``OK`` to save the changes. + +.. figure:: /_static/images/gns3-22.png + +The VyOS VM is now ready to be deployed. + diff --git a/docs/installation/virtual/index.rst b/docs/installation/virtual/index.rst new file mode 100644 index 00000000..808439c7 --- /dev/null +++ b/docs/installation/virtual/index.rst @@ -0,0 +1,12 @@ +#################################### +Running VyOS in Virtual Environments +#################################### + +.. toctree:: + :caption: Content + + libvirt + proxmox + vmware + gns3 + eve-ng \ No newline at end of file diff --git a/docs/installation/virtual/libvirt.rst b/docs/installation/virtual/libvirt.rst new file mode 100644 index 00000000..0d624b94 --- /dev/null +++ b/docs/installation/virtual/libvirt.rst @@ -0,0 +1,160 @@ +.. _libvirt: + +*************************** +Running on Libvirt Qemu/KVM +*************************** + +Libvirt is an open-source API, daemon and management tool for managing platform virtualization. +There are several ways to deploy VyOS on libvirt kvm. Use Virt-manager and native CLI. +In an example we will be use use 4 gigabytes of memory, 2 cores CPU and default network virbr0. + +CLI +=== + +Deploy from ISO +--------------- + +Create VM name ``vyos_r1``. You must specify the path to the ``ISO`` image, the disk ``qcow2`` will be created automatically. +The ``default`` network is the virtual network (type Virtio) created by the hypervisor with NAT. + +.. code-block:: none + + $ virt-install -n vyos_r1 \ + --ram 4096 \ + --vcpus 2 \ + --cdrom /var/lib/libvirt/images/vyos.iso \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_r1.qcow2,bus=virtio,size=8 \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r1`` + +.. code-block:: none + + $ virsh console vyos_r1 + + Connected to domain vyos_r1 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ install image + +After installation - exit from the console using the key combination ``Ctrl + ]`` and reboot the system. + +Deploy from qcow2 +----------------- +The convenience of using :abbr:`KVM (Kernel-based Virtual Machine)` images is that they don't need to be installed. +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + +Create VM with ``import`` qcow2 disk option. + +.. code-block:: none + + $ virt-install -n vyos_r2 \ + --ram 4096 \ + --vcpus 2 \ + --os-type linux \ + --os-variant debian10 \ + --network network=default \ + --graphics vnc \ + --hvm \ + --virt-type kvm \ + --disk path=/var/lib/libvirt/images/vyos_kvm.qcow2,bus=virtio \ + --import \ + --noautoconsole + +Connect to VM with command ``virsh console vyos_r2`` + +.. code-block:: none + + $ virsh console vyos_r2 + + Connected to domain vyos_r2 + Escape character is ^] + + vyos login: vyos + Password: + + vyos@vyos:~$ + +The system is fully operational. + +Virt-manager +============ +The virt-manager application is a desktop user interface for managing virtual machines through libvirt. +On the linux open :abbr:`VMM (Virtual Machine Manager)`. + +Deploy from ISO +--------------- + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Local install media`` (ISO) + +.. figure:: /_static/images/virt-libvirt-01.png + +3. Choose path to iso vyos.iso. Operating System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Disk size + +.. figure:: /_static/images/virt-libvirt-04.png + +6. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +7. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-06.png + +Deploy from qcow2 +----------------- + +Download predefined VyOS.qcow2 image for ``KVM`` + +.. code-block:: none + + curl --url link_to_vyos_kvm.qcow2 --output /var/lib/libvirt/images/vyos_kvm.qcow2 + + +1. Open :abbr:`VMM (Virtual Machine Manager)` and Create a new :abbr:`VM (Virtual Machine)` + +2. Choose ``Import existing disk`` image + +.. figure:: /_static/images/virt-libvirt-qc-01.png + +3. Choose the path to the image ``vyos_kvm.qcow2`` that was previously downloaded . Operation System can be any Debian based. + +.. figure:: /_static/images/virt-libvirt-qc-02.png + +4. Choose Memory and CPU + +.. figure:: /_static/images/virt-libvirt-03.png + +5. Name of VM and network selection + +.. figure:: /_static/images/virt-libvirt-05.png + +6. Then you will be taken to the console. + +.. figure:: /_static/images/virt-libvirt-qc-03.png + + + diff --git a/docs/installation/virtual/proxmox.rst b/docs/installation/virtual/proxmox.rst new file mode 100644 index 00000000..3ee9d70a --- /dev/null +++ b/docs/installation/virtual/proxmox.rst @@ -0,0 +1,8 @@ +####### +Proxmox +####### + +References +========== + +https://www.proxmox.com/en/proxmox-ve \ No newline at end of file diff --git a/docs/installation/virtual/vmware.rst b/docs/installation/virtual/vmware.rst new file mode 100644 index 00000000..c4299cbf --- /dev/null +++ b/docs/installation/virtual/vmware.rst @@ -0,0 +1,32 @@ +.. _vyosonvmware: + +Running on VMware ESXi +###################### + +ESXi 5.5 or later +***************** + +.ova files are available for supporting users, and a VyOS can also be stood up using a generic Linux instance, and attaching the bootable ISO file and installing from the ISO +using the normal process around `install image`. + +.. NOTE:: There have been previous documented issues with GRE/IPSEC tunneling using the E1000 adapter on the VyOS guest, and use of the VMXNET3 has been advised. + +Memory Contention Considerations +-------------------------------- +When the underlying ESXi host is approaching ~92% memory utilisation it will start the balloon process in s a 'soft' state to start reclaiming memory from guest operating systems. +This causes an artificial pressure using the vmmemctl driver on memory usage on the virtual guest. As VyOS by default does not have a swap file, this vmmemctl pressure is unable to +force processes to move in memory data to the paging file, and blindly consumes memory forcing the virtual guest into a low memory state with no way to escape. The balloon can expand to 65% of +guest allocated memory, so a VyOS guest running >35% of memory usage, can encounter an out of memory situation, and trigger the kernel oom_kill process. At this point a weighted +lottery favouring memory hungry processes will be run with the unlucky winner being terminated by the kernel. + +It is advised that VyOS routers are configured in a resource group with adequate memory reservations so that ballooning is not inflicted on virtual VyOS guests. + + + + + +References +---------- + +https://muralidba.blogspot.com/2018/03/how-does-linux-out-of-memory-oom-killer.html + diff --git a/docs/installation/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst new file mode 100644 index 00000000..db618431 --- /dev/null +++ b/docs/installation/vyos-on-baremetal.rst @@ -0,0 +1,411 @@ +.. _vyosonbaremetal: + +##################### +Running on Bare Metal +##################### + +Supermicro A2SDi (Atom C3000) +============================= + +I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. +Running VyOS on an UEFI only device is supported as of VyOS release 1.2. + +Shopping Cart +------------- + +* 1x Supermicro CSE-505-203B (19" 1U chassis, inkl. 200W PSU) +* 1x Supermicro MCP-260-00085-0B (I/O Shield for A2SDi-2C-HLN4F) +* 1x Supermicro A2SDi-2C-HLN4F (Intel Atom C3338, 2C/2T, 4MB cache, Quad LAN + with Intel C3000 SoC 1GbE) +* 1x Crucial CT4G4DFS824A (4GB DDR4 RAM 2400 MT/s, PC4-19200) +* 1x SanDisk Ultra Fit 32GB (USB-A 3.0 SDCZ43-032G-G46 mass storage for OS) +* 1x Supermicro MCP-320-81302-0B (optional FAN tray) + +Optional (10GE) +--------------- +If you want to get additional ethernet ports or even 10GE connectivity +the following optional parts will be required: + +* 1x Supermicro RSC-RR1U-E8 (Riser Card) +* 1x Supermicro MCP-120-00063-0N (Riser Card Bracket) + +Latest VyOS rolling releases boot without any problem on this board. You also +receive a nice IPMI interface realized with an ASPEED AST2400 BMC (no +information about `OpenBMC `_ so far on this +motherboard). + +Pictures +-------- + +.. figure:: /_static/images/1u_vyos_back.jpg + :scale: 25 % + :alt: CSE-505-203B Back + +.. figure:: /_static/images/1u_vyos_front.jpg + :scale: 25 % + :alt: CSE-505-203B Front + +.. figure:: /_static/images/1u_vyos_front_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B Open 1 + +.. figure:: /_static/images/1u_vyos_front_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B Open 2 + +.. figure:: /_static/images/1u_vyos_front_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_1.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 1 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_2.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 2 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_3.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open 3 + +.. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg + :scale: 25 % + :alt: CSE-505-203B w/ 10GE Open + + +.. _pc-engines-apu4: + +PC Engines APU4 +================ + +As this platform seems to be quite common in terms of noise, cost, power and +performance it makes sense to write a small installation manual. + +This guide was developed using an APU4C4 board with the following specs: + +* AMD Embedded G series GX-412TC, 1 GHz quad Jaguar core with 64 bit and AES-NI + support, 32K data + 32K instruction cache per core, shared 2MB L2 cache. +* 4 GB DDR3-1333 DRAM, with optional ECC support +* About 6 to 10W of 12V DC power depending on CPU load +* 2 miniPCI express (one with SIM socket for 3G modem). +* 4 Gigabit Ethernet channels using Intel i211AT NICs + +The board can be powered via 12V from the front or via a 5V onboard connector. + +Shopping Cart +------------- + +* 1x apu4c4 = 4 i211AT LAN / AMD GX-412TC CPU / 4 GB DRAM / dual SIM +* 1x Kingston SUV500MS/120G +* 1x VARIA Group Item 326745 19" dual rack for APU4 + +The 19" enclosure can accommodate up to two APU4 boards - there is a single and +dual front cover. + +Extension Modules +^^^^^^^^^^^^^^^^^ + +WiFi +"""" + +Refer to :ref:`wireless-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform: + +* Compex WLE900VX mini-PCIe WiFi module, only supported in mPCIe slot 1. + +WWAN +"""" + +Refer to :ref:`wwan-interface` for additional information, below listed modules +have been tested successfully on this Hardware platform using VyOS 1.3 (equuleus): + +* Sierra Wireless AirPrime MC7304 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7430 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7455 miniPCIe card (LTE) +* Sierra Wireless AirPrime MC7710 miniPCIe card (LTE) +* Huawei ME909u-521 miniPCIe card (LTE) + +VyOS 1.2 (crux) +--------------- + +Depending on the VyOS versions you intend to install there is a difference in +the serial port settings (:vytask:`T1327`). + +Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. + +Connect serial port to a PC through null modem cable (RXD / TXD crossed over). +Set terminal emulator to 115200 8N1. + +.. code-block:: none + + PC Engines apu4 + coreboot build 20171130 + BIOS version v4.6.4 + 4080 MB ECC DRAM + SeaBIOS (version rel-1.11.0.1-0-g90da88d) + + Press F10 key now for boot menu: + + Select boot device: + + 1. ata0-0: KINGSTON SUV500MS120G ATA-11 Hard-Disk (111 GiBytes) + 2. USB MSC Drive Generic Flash Disk 8.07 + 3. Payload [memtest] + 4. Payload [setup] + +Now boot from the ``USB MSC Drive Generic Flash Disk 8.07`` media by pressing +``2``, the VyOS boot menu will appear, just wait 10 seconds or press ``Enter`` +to continue. + +.. code-block:: none + + lqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqk + x VyOS - Boot Menu x + tqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqu + x Live (amd64-vyos) x + x Live (amd64-vyos failsafe) x + x x + mqqqqqqPress ENAutomatic boot in 10 seconds...nu entryqqqqqqqj + +The image will be loaded and the last lines you will get will be: + +.. code-block:: none + + Loading /live/vmlinuz... ok + Loading /live/initrd.img... + +The Kernel will now spin up using a different console setting. Set terminal +emulator to 9600 8N1 and after a while your console will show: + +.. code-block:: none + + Loading /live/vmlinuz... ok + Loading /live/initrd.img... + Welcome to VyOS - vyos ttyS0 + + vyos login: + +You can now proceed with a regular image installation as described in +:ref:`installation`. + +As the APU board itself still used a serial setting of 115200 8N1 it is +strongly recommended that you change the VyOS serial interface settings after +your first successful boot. + +Use the following command to adjust the :ref:`serial-console` settings: + +.. code-block:: none + + set system console device ttyS0 speed 115200 + +.. note:: Once you ``commit`` the above changes access to the serial interface + is lost until you set your terminal emulator to 115200 8N1 again. + +.. code-block:: none + + vyos@vyos# show system console + device ttyS0 { + speed 115200 + } + +VyOS 1.2 (rolling) +------------------ + +Installing the rolling release on an APU2 board does not require any change +on the serial console from your host side as :vytask:`T1327` was successfully +implemented. + +Simply proceed with a regular image installation as described in +:ref:`installation`. + +Pictures +-------- + +.. note:: Both device types operate without any moving parts and emit zero + noise. + +Rack Mount +^^^^^^^^^^ + +.. figure:: /_static/images/apu4_rack_1.jpg + :scale: 25 % + :alt: APU4 rack closed + +.. figure:: /_static/images/apu4_rack_2.jpg + :scale: 25 % + :alt: APU4 rack front + +.. figure:: /_static/images/apu4_rack_3.jpg + :scale: 25 % + :alt: APU4 rack module #1 + +.. figure:: /_static/images/apu4_rack_4.jpg + :scale: 25 % + :alt: APU4 rack module #2 + +.. figure:: /_static/images/apu4_rack_5.jpg + :scale: 25 % + :alt: APU4 rack module #3 with PSU + +VyOS custom print +""""""""""""""""" + +.. figure:: /_static/images/apu4_rack_vyos_print.jpg + :scale: 25 % + :alt: APU4 custom VyOS powder coat + +Desktop / Bench Top +^^^^^^^^^^^^^^^^^^^ + +.. figure:: /_static/images/apu4_desk_1.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_2.jpg + :scale: 25 % + :alt: APU4 desktop closed + +.. figure:: /_static/images/apu4_desk_3.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. figure:: /_static/images/apu4_desk_4.jpg + :scale: 25 % + :alt: APU4 desktop back + +.. _Rufus: https://rufus.ie/ + +Qotom Q355G4 +============ + +The install on this Q355G4 box is pretty much plug and play. The port numbering +the OS does might differ from the labels on the outside, but the UEFI firmware +has a port blink test built in with MAC addresses so you can very quickly +identify which is which. MAC labels are on the inside as well, and this test +can be done from VyOS or plain Linux too. Default settings in the UEFI will +make it boot, but depending on your installation wishes (i.e. storage type, +boot type, console type) you might want to adjust them. This Qotom company +seems to be the real OEM/ODM for many other relabelling companies like +Protectli. + +Hardware +-------- + +There are a number of other options, but they all seem to be close to Intel +reference designs, with added features like more serial ports, more network +interfaces and the likes. Because they don't deviate too much from standard +designs all the hardware is well-supported by mainline. It accepts one LPDDR3 +SO-DIMM, but chances are that if you need more than that, you'll also want +something even beefier than an i5. There are options for antenna holes, and SIM +slots, so you could in theory add an LTE/Cell modem (not tested so far). + +The chassis is a U-shaped alu extrusion with removable I/O plates and removable +bottom plate. Cooling is completely passive with a heatsink on the SoC with +internal and external fins, a flat interface surface, thermal pad on top of +that, which then directly attaches to the chassis, which has fins as well. It +comes with mounting hardware and rubber feet, so you could place it like a +desktop model or mount it on a VESA mount, or even wall mount it with the +provided mounting plate. The closing plate doubles as internal 2.5" mounting +place for an HDD or SSD, and comes supplied with a small SATA cable and SATA +power cable. + +Power supply is a 12VDC barrel jack, and included switching power supply, which +is why SATA power regulation is on-board. Internally it has a NUC-board-style +on-board 12V input header as well, the molex locking style. + +There are WDT options and auto-boot on power enable, which is great for remote +setups. Firmware is reasonably secure (no backdoors found, BootGuard is enabled +in enforcement mode, which is good but also means no coreboot option), yet has +most options available to configure (so it's not locked out like most firmwares +are). + +An external RS232 serial port is available, internally a GPIO header as well. +It does have Realtek based audio on board for some reason, but you can disable +that. Booting works on both USB2 and USB3 ports. Switching between serial BIOS +mode and HDMI BIOS mode depends on what is connected at startup; it goes into +serial mode if you disconnect HDMI and plug in serial, in all other cases it's +HDMI mode. + +Partaker i5 +=========== + +.. figure:: ../_static/images/600px-Partaker-i5.jpg + +I believe this is actually the same hardware as the Protectli. I purchased it +in June 2018. It came pre-loaded with pfSense. + +`Manufacturer product page `_. + +Installation +------------ + +* Write VyOS ISO to USB drive of some sort +* Plug in VGA, power, USB keyboard, and USB drive +* Press "SW" button on the front (this is the power button; I don't know what + "SW" is supposed to mean). +* Begin rapidly pressing delete on the keyboard. The boot prompt is very quick, + but with a few tries you should be able to get into the BIOS. +* Chipset > South Bridge > USB Configuration: set XHCI to Disabled and USB 2.0 + (EHCI) to Enabled. Without doing this, the USB drive won't boot. +* Boot to the VyOS installer and install as usual. + +Warning the interface labels on my device are backwards; the left-most "LAN4" +port is eth0 and the right-most "LAN1" port is eth3. + +Acrosser AND-J190N1 +=================== + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Front.jpg + +.. figure:: ../_static/images/480px-Acrosser_ANDJ190N1_Back.jpg + +This microbox network appliance was build to create OpenVPN bridges. It can +saturate a 100Mbps link. It is a small (serial console only) PC with 6 Gb LAN +http://www.acrosser.com/upload/AND-J190_J180N1-2.pdf + +You may have to add your own RAM and HDD/SSD. There is no VGA connector. But +Acrosser provides a DB25 adapter for the VGA header on the motherboard (not +used). + +BIOS Settings: +-------------- + +First thing you want to do is getting a more user friendly console to configure +BIOS. Default VT100 brings a lot of issues. Configure VT100+ instead. + +For practical issues change speed from 115200 to 9600. 9600 is the default +speed at which both linux kernel and VyOS will reconfigure the serial port +when loading. + +Connect to serial (115200bps). Power on the appliance and press Del in the +console when requested to enter BIOS settings. + +Advanced > Serial Port Console Redirection > Console Redirection Settings: + +* Terminal Type : VT100+ +* Bits per second : 9600 + +Save, reboot and change serial speed to 9600 on your client. + +Some options have to be changed for VyOS to boot correctly. With XHCI enabled +the installer can’t access the USB key. Enable EHCI instead. + +Reboot into BIOS, Chipset > South Bridge > USB Configuration: + +* Disable XHCI +* Enable USB 2.0 (EHCI) Support + +Install VyOS: +------------- + +Create a VyOS bootable USB key. I used the 64-bit ISO (VyOS 1.1.7) and +`LinuxLive USB Creator `_. + +I'm not sure if it helps the process but I changed default option to live-serial +(line “default xxxx”) on the USB key under syslinux/syslinux.cfg. + +I connected the key to one black USB port on the back and powered on. The first +VyOS screen has some readability issues. Press :kbd:`Enter` to continue. + +Then VyOS should boot and you can perform the ``install image`` -- cgit v1.2.3 From a3f7e4ae450248bb5b28474d908e51e6560cb68d Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 19:36:16 +0100 Subject: arange http-api and command-scripting --- docs/appendix/command-scripting.rst | 127 -------------- docs/appendix/http-api.rst | 166 ------------------ docs/appendix/release-notes.rst | 305 ---------------------------------- docs/automation/command-scripting.rst | 127 ++++++++++++++ docs/automation/http-api.rst | 166 ++++++++++++++++++ docs/automation/index.rst | 9 +- 6 files changed, 301 insertions(+), 599 deletions(-) delete mode 100644 docs/appendix/command-scripting.rst delete mode 100644 docs/appendix/http-api.rst delete mode 100644 docs/appendix/release-notes.rst create mode 100644 docs/automation/command-scripting.rst create mode 100644 docs/automation/http-api.rst (limited to 'docs') diff --git a/docs/appendix/command-scripting.rst b/docs/appendix/command-scripting.rst deleted file mode 100644 index 7d0ab6c5..00000000 --- a/docs/appendix/command-scripting.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _command-scripting: - -Command Scripting -================= - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS specific functions and aliases you need to ``source -/opt/vyatta/etc/functions/script-template`` files at the top of your script. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - exit - -Run configuration commands --------------------------- - -Configuration commands are executed just like from a normal config session. For -example, if you want to disable a BGP peer on VRRP transition to backup: - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - set protocols bgp 65536 neighbor 192.168.2.1 shutdown - commit - exit - -Run operational commands ------------------------- - -Unlike a normal configuration sessions, all operational commands must be -prepended with ``run``, even if you haven't created a session with configure. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - run show interfaces - exit - -Other script language ---------------------- - -If you want to script the configs in a language other than bash you can have -your script output commands and then source them in a bash script. - -Here is a simple example: - -.. code-block:: python - - #!/usr/bin/env python - print "delete firewall group address-group somehosts" - print "set firewall group address-group somehosts address '192.0.2.3'" - print "set firewall group address-group somehosts address '203.0.113.55'" - - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - source < /config/scripts/setfirewallgroup.py - commit - - -Executing Configuration Scripts -------------------------------- - -There is a pitfall when working with configuration scripts. It is tempting to -call configuration scripts with "sudo" (i.e., temporary root permissions), -because that's the common way on most Linux platforms to call system commands. - -On VyOS this will cause the following problem: After modifying the configuration -via script like this once, it is not possible to manually modify the config -anymore: - -.. code-block:: none - - sudo ./myscript.sh # Modifies config - configure - set ... # Any configuration parameter - -This will result in the following error message: ``Set failed`` If this happens, -a reboot is required to be able to edit the config manually again. - -To avoid these problems, the proper way is to call a script with the -``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: - -.. code-block:: none - - sg vyattacfg -c ./myscript.sh - -To make sure that a script is not accidentally called without the ``vyattacfg`` -group, the script can be safeguarded like this: - -.. code-block:: none - - if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" - fi - -Postconfig on boot ------------------- - -The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot -after the VyOS configuration is fully applied. - -Any modifications done to work around unfixed bugs and implement enhancements -which are not complete in the VyOS system can be placed here. - -The default file looks like this: - -.. code-block:: none - - #!/bin/sh - # This script is executed at boot time after VyOS configuration is fully - # applied. Any modifications required to work around unfixed bugs or use - # services not available through the VyOS CLI system can be placed here. - -.. hint:: For configuration/upgrade management issues, modification of this - script should be the last option. Always try to find solutions based on CLI - commands first. diff --git a/docs/appendix/http-api.rst b/docs/appendix/http-api.rst deleted file mode 100644 index 49f2dbd9..00000000 --- a/docs/appendix/http-api.rst +++ /dev/null @@ -1,166 +0,0 @@ -.. _http-api: - -######## -HTTP-API -######## - -Enabling HTTP-API ------------------ - -VyOS HTTP API can be enabled through the ``set service https api`` command. - -.. code-block:: none - - set service https api debug - set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY - -The local API process listens on localhost:8080, and nginx exposes it on all -virtual servers, by default. For the purpose of illustration below, we will -assume nginx is running at https://192.168.122.127. - -One can limit proxying to specific listen addresses/ports/server-names by -defining a ``service https virtual-host ``, and setting ``service https -api-restrict virtual-host ``. - -.. code-block:: none - - set service https virtual-host example listen-address 192.168.122.127 - set service https virtual-host example listen-port 44302 - set service https virtual-host example server-name example.net - - set service https api-restrict virtual-host example - -In this example, nginx will proxy only those requests to -192.168.122.127:44302 or example.net:44302 (assuming the DNS record is -viable). Omitting any of listen-address, listen-port, or server-name, will -leave appropriate defaults in the nginx directive. Multiple instances of -``service https api-restrict virtual-host`` may be set. - -Configuration mode requests ---------------------------- - -In our example, we are creating a dummy interface and assigning an address to it: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself. - -Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure - -Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed. - -You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit. - -To retrieve a value: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -Use ``returnValues`` for multi-valued nodes. - - -Show config -""""""""""" - -To retrieve the full config under a path: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - -It will return: - -.. code-block:: none - - {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} - -Passing an empty path will return the full config: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve - - -Configuration management requests ---------------------------------- - -When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. - -If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example: - -.. code-block:: none - - # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file - -Image management requests -------------------------- - -One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: - -``add`` from ``url``. Here we use the URL of the latest rolling release: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -``delete`` by image ``name``. For example: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image - -To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be: - -.. code-block:: none - - # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Operational mode requests -------------------------- - -It is possible to run ``show`` and ``generate`` commands: - - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate - -Response: - -.. code-block:: none - - {"success": true, "data": "", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "=\n", "error": null} - -Request: - -.. code-block:: none - - curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show - -Response: - -.. code-block:: none - - {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} - diff --git a/docs/appendix/release-notes.rst b/docs/appendix/release-notes.rst deleted file mode 100644 index 89454fa0..00000000 --- a/docs/appendix/release-notes.rst +++ /dev/null @@ -1,305 +0,0 @@ -.. _release-notes: - -############# -Release Notes -############# - -1.2 (Crux) -========== - -1.2.5 ------ - -1.2.5 is a maintenance release made in April 2020. - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`1020` OSPF Stops distributing default route after a while -* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) -* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. -* :vytask:`1341` Adding rate-limiter for pppoe server users -* :vytask:`1376` Incorrect DHCP lease counting -* :vytask:`1392` Large firewall rulesets cause the system to lose configuration and crash at startup -* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with each other -* :vytask:`1452` accel-pppoe - add vendor option to shaper -* :vytask:`1490` BGP configuration (is lost|not applied) when updating 1.1.8 -> 1.2.1 -* :vytask:`1780` Adding ipsec ike closeaction -* :vytask:`1803` Unbind NTP while it's not requested... -* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server -* :vytask:`1827` Increase default gc_thresh -* :vytask:`1828` Missing completion helper for "set system syslog host 192.0.2.1 facility all protocol" -* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to existing package -* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' -* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to destroy the running config. -* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address -* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s -* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and validators -* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at commit time -* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding stop-script -* :vytask:`1891` Router announcements broken on boot -* :vytask:`1900` Enable SNMP for VRRP. -* :vytask:`1902` Add redistribute non main table in bgp -* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks -* :vytask:`1913` "system ipv6 blacklist" command has no effect -* :vytask:`1914` IPv6 multipath hash policy does not apply -* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 -* :vytask:`1934` Change default hostname when deploy from OVA without params. -* :vytask:`1935` NIC identification and usage problem in Hyper-V environments -* :vytask:`1936` pppoe-server CLI control features -* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit fails -* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore -* :vytask:`1970` Correct adding interfaces on boot -* :vytask:`1971` Missing modules in initrd.img for PXE boot -* :vytask:`1998` Update FRR to 7.3 -* :vytask:`2001` Error when router reboot -* :vytask:`2032` Monitor bandwidth bits -* :vytask:`2059` Set source-validation on bond vif don't work -* :vytask:`2066` PPPoE interface can be created multiple times - last wins -* :vytask:`2069` PPPoE-client does not works with service-name option -* :vytask:`2077` ISO build from crux branch is failing -* :vytask:`2079` Update Linux Kernel to v4.19.106 -* :vytask:`2087` Add maxfail 0 option to pppoe configuration. -* :vytask:`2100` BGP route adverisement wih checks rib -* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers -* :vytask:`2197` Cant add vif-s interface into a bridge -* :vytask:`2228` WireGuard does not allow ports < 1024 to be used -* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' -* :vytask:`2272` Set system flow-accounting disable-imt has syntax error -* :vytask:`2276` PPPoE server vulnerability - - -1.2.4 ------ - -1.2.4 is a maintenance release made in December 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 -* :vytask:`T818` SNMP v3 - remove required engineid from user node -* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) -* :vytask:`T1183` BFD Support via FRR -* :vytask:`T1299` Allow SNMPd to be extended with custom scripts -* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option -* :vytask:`T1391` In route-map set community additive -* :vytask:`T1394` syslog systemd and host_name.py race condition -* :vytask:`T1401` Copying files with the FTP protocol fails if the password contains special characters -* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes to fix -* :vytask:`T1430` Add options for custom DHCP client-id and hostname -* :vytask:`T1447` Python subprocess called without import in host_name.py -* :vytask:`T1470` improve output of "show dhcpv6 server leases" -* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf -* :vytask:`T1496` Separate rolling release and LTS kernel builds -* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting -* :vytask:`T1568` strip-private command improvement for additional masking of IPv6 and MAC address -* :vytask:`T1578` completion offers "show table", but show table does not exist -* :vytask:`T1593` Support ip6gre -* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" -* :vytask:`T1638` vyos-hostsd not setting system domain name -* :vytask:`T1678` hostfile-update missing line feed -* :vytask:`T1694` NTPd: Do not listen on all interfaces by default -* :vytask:`T1701` Delete domain-name and domain-search won't work -* :vytask:`T1705` High CPU usage by bgpd when snmp is active -* :vytask:`T1707` DHCP static mapping and exclude address not working -* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 -* :vytask:`T1709` Update WireGuard to 0.0.20190913 -* :vytask:`T1716` Update Intel NIC drivers to recent versions -* :vytask:`T1726` Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 -* :vytask:`T1728` Update Linux Kernel to 4.19.79 -* :vytask:`T1737` SNMP tab completion missing -* :vytask:`T1738` Copy SNMP configuration from node to node raises exception -* :vytask:`T1740` Broken OSPFv2 virtual-link authentication -* :vytask:`T1742` NHRP unable to commit. -* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address x must be greater or equal to the range start address y!" when static mapping has same IP as range stop -* :vytask:`T1749` numeric validator doesn't support multiple ranges -* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) -* :vytask:`T1772` constraints in XML are partially broken -* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR -* :vytask:`T1780` Adding ipsec ike closeaction -* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.py implementation -* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation -* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 -* :vytask:`T1800` Update Linux Kernel to v4.19.84 -* :vytask:`T1809` Wireless: SSID scan does not work in AP mode -* :vytask:`T1811` Upgrade from 1.1.8: Config file migration failed: module=l2tp -* :vytask:`T1812` DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling -* :vytask:`T1819` Reboot kills SNMPv3 configuration -* :vytask:`T1822` Priority inversion wireless interface dhcpv6 -* :vytask:`T1825` Improve DHCP configuration error message -* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails to create an xml -* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" -* :vytask:`T1841` PPP ipv6-up.d direcotry missing -* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface -* :vytask:`T1903` Implementation udev predefined interface naming -* :vytask:`T1904` update eth1 and eth2 link files for the vep4600 - - -1.2.3 ------ - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features -^^^^^^^^^^^^ - -* HTTP API -* :vytask:`T1524` "set service dns forwarding allow-from " - option for limiting queries to specific client networks -* :vytask:`T1503` Functions for checking if a commit is in progress -* :vytask:`T1543` "set system contig-mangement commit-archive source-address" - option -* :vytask:`T1554` Intel NIC drivers now support receive side scaling and - multiqueue - -Resolved issues -^^^^^^^^^^^^^^^ - -* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit - errors -* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive - lookups on domain specific forwarders -* :vytask:`T1362` Special characters in VRRP passwords are handled correctly -* :vytask:`T1377` BGP weight is applied properly -* :vytask:`T1420` Fixed permission for log files -* :vytask:`T1425` Wireguard interfaces now support /31 addresses -* :vytask:`T1428` Wireguard correctly handles firewall marks -* :vytask:`T1439` DHCPv6 static mappings now work correctly -* :vytask:`T1450` Flood ping commands now works correctly -* :vytask:`T1460` Op mode "show firewall" commands now support counters longer - than 8 digits (T1460) -* :vytask:`T1465` Fixed priority inversion in VTI commands -* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option -* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC - compatibility mode enabled -* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings -* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces -* :vytask:`T1530` Fixed "set system syslog global archive file" command -* :vytask:`T1531` Multiple fixes in cluster configuration scripts -* :vytask:`T1537` Fixed missing help text for "service dns" -* :vytask:`T1541` Fixed input validation in DHCPv6 relay options -* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall - assigned to it in one commit -* :vytask:`T1559` URL filtering now uses correct rule database path and works - again -* :vytask:`T1579` "show log vpn ipsec" command works again -* :vytask:`T1576` "show arp interface " command works again -* :vytask:`T1605` Fixed regression in L2TP/IPsec server -* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly -* :vytask:`T1616` "renew dhcpv6" command now works from op mode -* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works - correctly now -* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple - improvements in name servers and hosts configuration handling - -Internals -^^^^^^^^^ - -``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the -*vyos-hostsd* service that listens on a ZMQ socket for update messages. - -1.2.2 ------ - -1.2.2 is a maintenance release made in July 2019. - -New features -^^^^^^^^^^^^ - -* Options for per-interface MSS clamping. -* BGP extended next-hop capability -* Relaxed BGP multipath option -* Internal and external options for "remote-as" (accept any AS as long as it's - the same to this router or different, respectively) -* "Unnumbered" (interface-based) BGP peers -* BGP no-prepend option -* Additive BGP community option -* OSPFv3 network type option -* Custom arguments for VRRP scripts -* A script for querying values from config files - -Resolved issues -^^^^^^^^^^^^^^^ - -* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability -* :vytask:`T1371` VRRP health-check scripts now can use arguments -* :vytask:`T1497` DNS server addresses coming from a DHCP server are now - correctly propagated to resolv.conf -* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used - for recursive queries -* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly -* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors -* :vytask:`T1458` Correct hostname is sent to remote syslog again -* :vytask:`T1438` Board serial number from DMI is correctly displayed in - ``show version`` -* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in - remote syslog config -* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` -* :vytask:`T1174` ``system domain-name`` is correctly included in - ``/etc/resolv.conf`` -* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` - settings -* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines -* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address -* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU -* :vytask:`T1505` vyos.config ``return_effective_values()`` function now - correctly returns a list rather than a string - -1.2.1 ------ - -VyOS 1.2.1 is a maintenance release made in April 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers -* :vytask:`T1326` The kernel now includes drivers for various USB serial - adapters, which allows people to add a serial console to a machine without - onboard RS232, or connect to something else from the router -* The collection of network card firmware is now much more extensive -* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC - addresses in the RFC-compliant mode -* :vytask:`T1330` DHCP WPAD URL option works correctly again -* :vytask:`T1312` Many to many NAT rules now can use source/destination and - translation networks of non-matching size. If 1:1 network bits translation is - desired, it's now users responsibility to check if prefix length matches. -* :vytask:`T1290` IPv6 network prefix translation is fixed -* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely - used in PPPoE passwords -* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends - with a leaf node such as ``timezone`` in ``show system | commands`` -* :vytask:`T1235` ``show | commands`` correctly works in config mode now -* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option -* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest - Crux -* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses - other than loopback was fixed -* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to - start is fixed -* :vytask:`T1067` VXLAN value validation is improved -* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS - forwarding -* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with - more than one upstream interface -* :vytask:`T1234` ``relay-agents-packets`` option works correctly now -* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change -* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name -* :vytask:`T1279` ACPI power off works again -* :vytask:`T1247` Negation in WAN load balancing rules works again -* :vytask:`T1218` FRR staticd now starts on boot correctly -* :vytask:`T1296` The installer now correctly detects SD card devices -* :vytask:`T1225` Wireguard peers can be disabled now -* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete - is fixed -* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration -* :vytask:`T1060` It's now possible to exclude hosts from the transparent - web proxy -* :vytask:`T484` An issue with rules impossible to delete from the zone-based - firewall is fixed - -Earlier releases -================ - -Release notes for legacy versions (1.1.x, 1.0.x) can be found in the `archived wiki `_. diff --git a/docs/automation/command-scripting.rst b/docs/automation/command-scripting.rst new file mode 100644 index 00000000..7d0ab6c5 --- /dev/null +++ b/docs/automation/command-scripting.rst @@ -0,0 +1,127 @@ +.. _command-scripting: + +Command Scripting +================= + +VyOS supports executing configuration and operational commands non-interactively +from shell scripts. + +To include VyOS specific functions and aliases you need to ``source +/opt/vyatta/etc/functions/script-template`` files at the top of your script. + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + exit + +Run configuration commands +-------------------------- + +Configuration commands are executed just like from a normal config session. For +example, if you want to disable a BGP peer on VRRP transition to backup: + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + configure + set protocols bgp 65536 neighbor 192.168.2.1 shutdown + commit + exit + +Run operational commands +------------------------ + +Unlike a normal configuration sessions, all operational commands must be +prepended with ``run``, even if you haven't created a session with configure. + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + run show interfaces + exit + +Other script language +--------------------- + +If you want to script the configs in a language other than bash you can have +your script output commands and then source them in a bash script. + +Here is a simple example: + +.. code-block:: python + + #!/usr/bin/env python + print "delete firewall group address-group somehosts" + print "set firewall group address-group somehosts address '192.0.2.3'" + print "set firewall group address-group somehosts address '203.0.113.55'" + + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + configure + source < /config/scripts/setfirewallgroup.py + commit + + +Executing Configuration Scripts +------------------------------- + +There is a pitfall when working with configuration scripts. It is tempting to +call configuration scripts with "sudo" (i.e., temporary root permissions), +because that's the common way on most Linux platforms to call system commands. + +On VyOS this will cause the following problem: After modifying the configuration +via script like this once, it is not possible to manually modify the config +anymore: + +.. code-block:: none + + sudo ./myscript.sh # Modifies config + configure + set ... # Any configuration parameter + +This will result in the following error message: ``Set failed`` If this happens, +a reboot is required to be able to edit the config manually again. + +To avoid these problems, the proper way is to call a script with the +``vyattacfg`` group, e.g., by using the ``sg`` (switch group) command: + +.. code-block:: none + + sg vyattacfg -c ./myscript.sh + +To make sure that a script is not accidentally called without the ``vyattacfg`` +group, the script can be safeguarded like this: + +.. code-block:: none + + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi + +Postconfig on boot +------------------ + +The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot +after the VyOS configuration is fully applied. + +Any modifications done to work around unfixed bugs and implement enhancements +which are not complete in the VyOS system can be placed here. + +The default file looks like this: + +.. code-block:: none + + #!/bin/sh + # This script is executed at boot time after VyOS configuration is fully + # applied. Any modifications required to work around unfixed bugs or use + # services not available through the VyOS CLI system can be placed here. + +.. hint:: For configuration/upgrade management issues, modification of this + script should be the last option. Always try to find solutions based on CLI + commands first. diff --git a/docs/automation/http-api.rst b/docs/automation/http-api.rst new file mode 100644 index 00000000..49f2dbd9 --- /dev/null +++ b/docs/automation/http-api.rst @@ -0,0 +1,166 @@ +.. _http-api: + +######## +HTTP-API +######## + +Enabling HTTP-API +----------------- + +VyOS HTTP API can be enabled through the ``set service https api`` command. + +.. code-block:: none + + set service https api debug + set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY + +The local API process listens on localhost:8080, and nginx exposes it on all +virtual servers, by default. For the purpose of illustration below, we will +assume nginx is running at https://192.168.122.127. + +One can limit proxying to specific listen addresses/ports/server-names by +defining a ``service https virtual-host ``, and setting ``service https +api-restrict virtual-host ``. + +.. code-block:: none + + set service https virtual-host example listen-address 192.168.122.127 + set service https virtual-host example listen-port 44302 + set service https virtual-host example server-name example.net + + set service https api-restrict virtual-host example + +In this example, nginx will proxy only those requests to +192.168.122.127:44302 or example.net:44302 (assuming the DNS record is +viable). Omitting any of listen-address, listen-port, or server-name, will +leave appropriate defaults in the nginx directive. Multiple instances of +``service https api-restrict virtual-host`` may be set. + +Configuration mode requests +--------------------------- + +In our example, we are creating a dummy interface and assigning an address to it: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself. + +Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure + +Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed. + +You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit. + +To retrieve a value: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +Use ``returnValues`` for multi-valued nodes. + + +Show config +""""""""""" + +To retrieve the full config under a path: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + +It will return: + +.. code-block:: none + + {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null} + +Passing an empty path will return the full config: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve + + +Configuration management requests +--------------------------------- + +When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command. + +If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example: + +.. code-block:: none + + # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file + +Image management requests +------------------------- + +One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples: + +``add`` from ``url``. Here we use the URL of the latest rolling release: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +``delete`` by image ``name``. For example: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image + +To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be: + +.. code-block:: none + + # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Operational mode requests +------------------------- + +It is possible to run ``show`` and ``generate`` commands: + + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate + +Response: + +.. code-block:: none + + {"success": true, "data": "", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "=\n", "error": null} + +Request: + +.. code-block:: none + + curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show + +Response: + +.. code-block:: none + + {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n F - PBR, f - OpenFabric,\n > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null} + diff --git a/docs/automation/index.rst b/docs/automation/index.rst index a3df9bc0..1f2b40b1 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -6,4 +6,11 @@ VyOS Automation * Ansible * Saltstack * HTTP-API - * startup scripts \ No newline at end of file + * startup scripts + + +.. toctree:: + :maxdepth: 1 + + command-scripting + http-api \ No newline at end of file -- cgit v1.2.3 From 0abea04850dfdaa0b56fc6dec94e5303300ba712 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:18:33 +0100 Subject: arrange firewall --- docs/configuration/firewall/index.rst | 767 ++++++++++++++++++++++++++++++++++ docs/configuration/index.rst | 23 + docs/firewall.rst | 767 ---------------------------------- docs/index.rst | 1 - 4 files changed, 790 insertions(+), 768 deletions(-) create mode 100644 docs/configuration/firewall/index.rst create mode 100644 docs/configuration/index.rst delete mode 100644 docs/firewall.rst (limited to 'docs') diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst new file mode 100644 index 00000000..870e9a08 --- /dev/null +++ b/docs/configuration/firewall/index.rst @@ -0,0 +1,767 @@ +.. _firewall: + +Firewall +======== + +Overview +-------- + +VyOS makes use of Linux `netfilter `_ for packet +filtering. + +The firewall supports the creation of groups for ports, addresses, and +networks (implemented using netfilter ipset) and the option of interface +or zone based firewall policy. + +.. note:: **Important note on usage of terms:** + The firewall makes use of the terms `in`, `out`, and `local` + for firewall policy. Users experienced with netfilter often confuse + `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` + chain from netfilter. This is not the case. These instead indicate + the use of the `FORWARD` chain and either the input or output + interface. The `INPUT` chain, which is used for local traffic to the + OS, is a reference to as `local` with respect to its input interface. + + +Global settings +--------------- + +Some firewall settings are global and have a affect on the whole system. + +.. cfgcmd:: set firewall all-ping [enable | disable] + + By default, when VyOS receives an ICMP echo request packet destined for + itself, it will answer with an ICMP echo reply, unless you avoid it + through its firewall. + + With the firewall you can set rules to accept, drop or reject ICMP in, + out or local traffic. You can also use the general **firewall all-ping** + command. This command affects only to LOCAL (packets destined for your + VyOS system), not to IN or OUT traffic. + + .. note:: **firewall all-ping** affects only to LOCAL and it always + behaves in the most restrictive way + + .. code-block:: none + + set firewall all-ping enable + + When the command above is set, VyOS will answer every ICMP echo request + addressed to itself, but that will only happen if no other rule is + applied dropping or rejecting local echo requests. In case of conflict, + VyOS will not answer ICMP echo requests. + + .. code-block:: none + + set firewall all-ping disable + + When the command above is set, VyOS will answer no ICMP echo request + addressed to itself at all, no matter where it comes from or whether + more specific rules are being applied to accept them. + +.. cfgcmd:: set firewall broadcast-ping [enable | disable] + + This setting enable or disable the response of icmp broadcast + messages. The following system parameter will be altered: + + * ``net.ipv4.icmp_echo_ignore_broadcasts`` + +.. cfgcmd:: set firewall ip-src-route [enable | disable] +.. cfgcmd:: set firewall ipv6-src-route [enable | disable] + + This setting handle if VyOS accept packets with a source route + option. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_source_route`` + * ``net.ipv6.conf.all.accept_source_route`` + +.. cfgcmd:: set firewall receive-redirects [enable | disable] +.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] + + enable or disable of ICMPv4 or ICMPv6 redirect messages accepted + by VyOS. The following system parameter will be altered: + + * ``net.ipv4.conf.all.accept_redirects`` + * ``net.ipv6.conf.all.accept_redirects`` + +.. cfgcmd:: set firewall send-redirects [enable | disable] + + enable or disable of ICMPv4 redirect messages send by VyOS + The following system parameter will be altered: + + * ``net.ipv4.conf.all.send_redirects`` + +.. cfgcmd:: set firewall log-martians [enable | disable] + + enable or disable the logging of martian IPv4 packets. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.log_martians`` + +.. cfgcmd:: set firewall source-validation [strict | loose | disable] + + Set the IPv4 source validation mode. + The following system parameter will be altered: + + * ``net.ipv4.conf.all.rp_filter`` + +.. cfgcmd:: set firewall syn-cookies [enable | disable] + + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + The following system parameter will be altered: + + * ``net.ipv4.tcp_syncookies`` + +.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] + + Enable or Disable VyOS to be :rfc:`1337` conform. + The following system parameter will be altered: + + * ``net.ipv4.tcp_rfc1337`` + +.. cfgcmd:: set firewall state-policy established action [accept | drop | + reject] + +.. cfgcmd:: set firewall state-policy established log enable + + Set the global setting for a astablished connections. + +.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy invalid log enable + + Set the global setting for invalid packets. + +.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] + +.. cfgcmd:: set firewall state-policy related log enable + + Set the global setting for related connections. + + +Groups +------ + +Firewall groups represent collections of IP addresses, networks, or +ports. Once created, a group can be referenced by firewall rules as +either a source or destination. Members can be added or removed from a +group without changes to, or the need to reload, individual firewall +rules. + +.. note:: Groups can also be referenced by NAT configuration. + +Groups need to have unique names. Even though some contain IPv4 +addresses and others contain IPv6 addresses, they still need to have +unique names, so you may want to append "-v4" or "-v6" to your group +names. + + +Address Groups +************** + +In a **address group** a single IP adresses or IP address ranges are +definded. + +.. cfgcmd:: set firewall group address-group address [address | + address range] +.. cfgcmd:: set firewall group ipv6-address-group address
+ + Define a IPv4 or a IPv6 address group + + .. code-block:: none + + set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 + set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 + set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 + +.. cfgcmd:: set firewall group address-group description +.. cfgcmd:: set firewall group ipv6-address-group description + + Provide a IPv4 or IPv6 address group description + + +Network Groups +************** + +While **network groups** accept IP networks in CIDR notation, specific +IP addresses can be added as a 32-bit prefix. If you foresee the need +to add a mix of addresses and networks, the network group is +recommended. + +.. cfgcmd:: set firewall group network-group network +.. cfgcmd:: set firewall group ipv6-network-group network + + Define a IPv4 or IPv6 Network group. + + .. code-block:: none + + set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 + set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 + set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 + +.. cfgcmd:: set firewall group network-group description +.. cfgcmd:: set firewall group ipv6-network-group description + + Provide a IPv4 or IPv6 network group description. + + +Port Groups +*********** + +A **port group** represents only port numbers, not the protocol. Port +groups can be referenced for either TCP or UDP. It is recommended that +TCP and UDP groups are created separately to avoid accidentally +filtering unnecessary ports. Ranges of ports can be specified by using +`-`. + +.. cfgcmd:: set firewall group port-group port + [portname | portnumber | startport-endport] + + Define a port group. A port name are any name defined in + /etc/services. e.g.: http + + .. code-block:: none + + set firewall group port-group PORT-TCP-SERVER1 port http + set firewall group port-group PORT-TCP-SERVER1 port 443 + set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 + +.. cfgcmd:: set firewall group port-group description + + Provide a port group description. + + +Rule-Sets +---------- + +A rule-set is a named collection of firewall rules that can be applied +to an interface or zone. Each rule is numbered, has an action to apply +if the rule is matched, and the ability to specify the criteria to +match. Data packets go through the rules from 1 - 9999, at the first match +the action of the rule will executed. + +.. cfgcmd:: set firewall name description +.. cfgcmd:: set firewall ipv6-name description + + Provide a rule-set description. + +.. cfgcmd:: set firewall name default-action [drop | reject | accept] +.. cfgcmd:: set firewall ipv6-name default-action [drop | reject | + accept] + + This set the default action of the rule-set if no rule matched a paket + criteria. + +.. cfgcmd:: set firewall name enable-default-log +.. cfgcmd:: set firewall ipv6-name enable-default-log + + Use this command to enable the logging of the default action. + +.. cfgcmd:: set firewall name rule <1-9999> action [drop | reject | + accept] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> action [drop | reject | + accept] + + This required setting define the action of the current rule. + +.. cfgcmd:: set firewall name rule <1-9999> description +.. cfgcmd:: set firewall ipv6-name rule <1-9999> description + + Provide a description for each rule. + +.. cfgcmd:: set firewall name rule <1-9999> log [disable | enable] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> log [disable | enable] + + Enable or disable logging for the matched packet. + +.. cfgcmd:: set firewall name rule <1-9999> disable +.. cfgcmd:: set firewall ipv6-name rule <1-9999> disable + + If you want to disable a rule but let it in the configuration. + +Matching criteria +***************** + +There are a lot of matching criteria gainst which the package can be tested. + + +.. cfgcmd:: set firewall name rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall name rule <1-9999> destination address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source address + [address | addressrange | CIDR] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination address + [address | addressrange | CIDR] + + This is similiar to the network groups part, but here you are able to negate + the matching addresses. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 + # with a '!' the rule match everything except the specified subnet + set fitewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 + set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 + + +.. cfgcmd:: set firewall name rule <1-9999> source mac-address + +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source mac-address + + + Only in the source criteria you can specify a mac-address + + .. code-block:: none + + set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 + set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 + +.. cfgcmd:: set firewall name rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall name rule <1-9999> destination port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source port + [1-65535 | portname | start-end] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination port + [1-65535 | portname | start-end] + + A port can be set with a portnumber or a name which is here + defined: ``/etc/services``. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 source port '22' + set firewall name WAN-IN-v4 rule 11 source port '!http' + set firewall name WAN-IN-v4 rule 12 source port 'https' + + Multiple source ports can be specified as a comma-separated list. + The whole list can also be "negated" using '!'. For example: + + .. code-block:: none + + set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' + +.. cfgcmd:: set firewall name rule <1-9999> source group + address-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + address-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + address-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + address-group + + Use a specific address-group + +.. cfgcmd:: set firewall name rule <1-9999> source group + network-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + network-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + network-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + network-group + + Use a specific network-group + +.. cfgcmd:: set firewall name rule <1-9999> source group + port-group +.. cfgcmd:: set firewall name rule <1-9999> destination group + port-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group + port-group +.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group + port-group + + Use a specific port-group + +.. cfgcmd:: set firewall name rule <1-9999> protocol [ | + <0-255> | all | tcp_udp] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> protocol [ | + <0-255> | all | tcp_udp] + + Match a protocol criteria. A protocol number or a name which is here + defined: ``/etc/protocols``. + Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and upd + based pakets. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 protocol tcp_udp + set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp + set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp + +.. cfgcmd:: set firewall name rule <1-9999> tcp flags +.. cfgcmd:: set firewall ipv6-name rule <1-9999> tcp flags + + Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, + ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma + separated. The ``!`` negate the selected protocol. + + .. code-block:: none + + set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' + set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' + set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' + +.. cfgcmd:: set firewall name rule <1-9999> state [established | + invalid | new | related] [enable | disable ] +.. cfgcmd:: set firewall ipv6-name rule <1-9999> state [established | + invalid | new | related] [enable | disable ] + + Match against the state of a packet. + + +Applying a Rule-Set to an Interface +----------------------------------- + +A Rule-Set can be appliend to every inteface: + +* ``in``: Ruleset for forwarded packets on inbound interface +* ``out``: Ruleset for forwarded packets on outbound interface +* ``local``: Ruleset for packets destined for this router + +.. cfgcmd:: set interface ethernet firewall [in | out | local] + [name | ipv6-name] + + Here are some examples for applying a rule-set to an interface + + .. code-block:: none + + set interface ethernet eth1 vif 100 firewall in name LANv4-IN + set interface ethernet eth1 vif 100 firewall out name LANv4-OUT + set interface bonding bond0 firewall in name LANv4-IN + set interfaces openvpn vtun1 firewall in name Lanv4-IN + + .. note:: + As you can see in the example here, you can assign the same rule-set to + several interfaces. An interface can only have one rule-set per chain. + + +Zone-based Firewall Policy +-------------------------- + +As an alternative to applying policy to an interface directly, a +zone-based firewall can be created to simplify configuration when +multiple interfaces belong to the same security zone. Instead of +applying rulesets to interfaces, they are applied to source +zone-destination zone pairs. + +An basic introduction to zone-based firewalls can be found `here +`_, +and an example at :ref:`examples-zone-policy`. + +Define a Zone +************* + +To define a zone setup either one with interfaces or a local zone. + +.. cfgcmd:: set zone-policy zone interface + + Set a interfaces to a zone. A zone can have multiple interfaces. + But a interface can only be member in one zone. + +.. cfgcmd:: set zone-policy zone local-zone + + Define the Zone as a local zone. A local zone have no interfaces and + will be applied to the router itself. + +.. cfgcmd:: set zone-policy zone default-action [drop | reject] + + Change the default-action with this setting. + +.. cfgcmd:: set zone-policy zone description + + Set a meaningful description. + + +Applying a Rule-Set to a Zone +***************************** + +Before you are able to apply a rule-set to a zone you have to create the zones +first. + +.. cfgcmd:: set zone-policy zone from firewall name + +.. cfgcmd:: set zone-policy zone from firewall ipv6-name + + + You apply a rule-set always to a zone from a other zone, it is recommended + to create one rule-set for each zone pair. + + .. code-block:: none + + set zone-policy zone DMZ from LAN firewall name LANv4-to-DMZv4 + set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 + + +Operation-mode Firewall +----------------------- + +Rule-set overview +***************** + +.. opcmd:: show firewall + + This will show you a basic firewall overview + + .. code-block:: none + + vyos@vyos:~$ show firewall + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + established accept disabled + related accept disabled + + ----------------------------- + Rulesets Information + ----------------------------- + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-IN": + + Active on (eth0,IN) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept icmp 0 0 + condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "DMZv4-1-OUT": + + Active on (eth0,OUT) + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept tcp_udp 1 60 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* + DMZv4-1-OUT-10 */LOG enabled + + 11 accept icmp 1 84 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled + + 10000 drop all 6 360 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled + + -------------------------------------------------------------------------- + IPv4 Firewall "LANv4-IN": + + Inactive - Not applied to any interfaces or zones. + + rule action proto packets bytes + ---- ------ ----- ------- ----- + 10 accept all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ + + 10000 drop all 0 0 + condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 + +.. opcmd:: show firewall summary + + This will show you a summary about rule-sets and groups + + .. code-block:: none + + vyos@vyos:~$ show firewall summary + + ------------------------ + Firewall Global Settings + ------------------------ + + Firewall state-policy for all IPv4 and Ipv6 traffic + + state action log + ----- ------ --- + invalid accept disabled + related accept disabled + established accept disabled + + ------------------------ + Firewall Rulesets + ------------------------ + + IPv4 name: + + Rule-set name Description References + ------------- ----------- ---------- + DMZv4-1-OUT (eth0,OUT) + DMZv4-1-IN (eth0,IN) + + ------------------------ + Firewall Groups + ------------------------ + + Port Groups: + + Group name Description References + ---------- ----------- ---------- + DMZ-Ports DMZv4-1-OUT-10-destination + + Network Groups: + + Group name Description References + ---------- ----------- ---------- + LANv4 LANv4-IN-10-source, + DMZv4-1-OUT-10-source, + DMZv4-1-OUT-11-source + +.. opcmd:: show firewall statistics + + This will show you a statistic of all rule-sets since the last boot. + +.. opcmd:: show firewall [name | ipv6name] rule <1-9999> + + This command will give an overview about a rule in a single rule-set + +.. opcmd:: show firewall group + + Overview of defined groups. You see the type, the members, and where the + group is used. + + .. code-block:: none + + vyos@vyos:~$ show firewall group DMZ-Ports + Name : DMZ-Ports + Type : port + References : none + Members : + 80 + 443 + 8080 + 8443 + + vyos@vyos:~$ show firewall group LANv4 + Name : LANv4 + Type : network + References : LANv4-IN-10-source + Members : + 10.10.0.0/16 + +.. opcmd:: show firewall [name | ipv6name] + + This command will give an overview about a single rule-set + +.. opcmd:: show firewall [name | ipv6name] statistics + + This will show you a rule-set statistic since the last boot. + +.. opcmd:: show firewall [name | ipv6name] rule <1-9999> + + This command will give an overview about a rule in a single rule-set + + +Zone-Policy Overview +******************** + +.. opcmd:: show zone-policy zone + + Use this command to get an overview about a zone + + .. code-block:: none + + vyos@vyos:~$ show zone-policy zone DMZ + ------------------- + Name: DMZ + + Interfaces: eth0 eth1 + + From Zone: + name firewall + ---- -------- + LAN DMZv4-1-OUT + + +Show Firewall log +***************** + +.. opcmd:: show log firewall [name | ipv6name] + + Show the logs of a specific Rule-Set + +.. note:: + At the moment it not possible to look at the whole firewall log with VyOS + operational commands. All logs will save to ``/var/logs/messages``. + For example: ``grep '10.10.0.10' /var/log/messages`` + + + +Example Partial Config +---------------------- + +.. code-block:: none + + firewall { + all-ping enable + broadcast-ping disable + config-trap disable + group { + network-group BAD-NETWORKS { + network 198.51.100.0/24 + network 203.0.113.0/24 + } + network-group GOOD-NETWORKS { + network 192.0.2.0/24 + } + port-group BAD-PORTS { + port 65535 + } + } + name FROM-INTERNET { + default-action accept + description "From the Internet" + rule 10 { + action accept + description "Authorized Networks" + protocol all + source { + group { + network-group GOOD-NETWORKS + } + } + } + rule 11 { + action drop + description "Bad Networks" + protocol all + source { + group { + network-group BAD-NETWORKS + } + } + } + rule 30 { + action drop + description "BAD PORTS" + destination { + group { + port-group BAD-PORTS + } + } + log enable + protocol all + } + } + } + interfaces { + ethernet eth1 { + address dhcp + description OUTSIDE + duplex auto + firewall { + in { + name FROM-INTERNET + } + } + } + } diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst new file mode 100644 index 00000000..bce013cb --- /dev/null +++ b/docs/configuration/index.rst @@ -0,0 +1,23 @@ +################### +Configuration Guide +################### + +The following structure respresent the cli structure. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + vrf/index + zonepolicy/index \ No newline at end of file diff --git a/docs/firewall.rst b/docs/firewall.rst deleted file mode 100644 index 870e9a08..00000000 --- a/docs/firewall.rst +++ /dev/null @@ -1,767 +0,0 @@ -.. _firewall: - -Firewall -======== - -Overview --------- - -VyOS makes use of Linux `netfilter `_ for packet -filtering. - -The firewall supports the creation of groups for ports, addresses, and -networks (implemented using netfilter ipset) and the option of interface -or zone based firewall policy. - -.. note:: **Important note on usage of terms:** - The firewall makes use of the terms `in`, `out`, and `local` - for firewall policy. Users experienced with netfilter often confuse - `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` - chain from netfilter. This is not the case. These instead indicate - the use of the `FORWARD` chain and either the input or output - interface. The `INPUT` chain, which is used for local traffic to the - OS, is a reference to as `local` with respect to its input interface. - - -Global settings ---------------- - -Some firewall settings are global and have a affect on the whole system. - -.. cfgcmd:: set firewall all-ping [enable | disable] - - By default, when VyOS receives an ICMP echo request packet destined for - itself, it will answer with an ICMP echo reply, unless you avoid it - through its firewall. - - With the firewall you can set rules to accept, drop or reject ICMP in, - out or local traffic. You can also use the general **firewall all-ping** - command. This command affects only to LOCAL (packets destined for your - VyOS system), not to IN or OUT traffic. - - .. note:: **firewall all-ping** affects only to LOCAL and it always - behaves in the most restrictive way - - .. code-block:: none - - set firewall all-ping enable - - When the command above is set, VyOS will answer every ICMP echo request - addressed to itself, but that will only happen if no other rule is - applied dropping or rejecting local echo requests. In case of conflict, - VyOS will not answer ICMP echo requests. - - .. code-block:: none - - set firewall all-ping disable - - When the command above is set, VyOS will answer no ICMP echo request - addressed to itself at all, no matter where it comes from or whether - more specific rules are being applied to accept them. - -.. cfgcmd:: set firewall broadcast-ping [enable | disable] - - This setting enable or disable the response of icmp broadcast - messages. The following system parameter will be altered: - - * ``net.ipv4.icmp_echo_ignore_broadcasts`` - -.. cfgcmd:: set firewall ip-src-route [enable | disable] -.. cfgcmd:: set firewall ipv6-src-route [enable | disable] - - This setting handle if VyOS accept packets with a source route - option. The following system parameter will be altered: - - * ``net.ipv4.conf.all.accept_source_route`` - * ``net.ipv6.conf.all.accept_source_route`` - -.. cfgcmd:: set firewall receive-redirects [enable | disable] -.. cfgcmd:: set firewall ipv6-receive-redirects [enable | disable] - - enable or disable of ICMPv4 or ICMPv6 redirect messages accepted - by VyOS. The following system parameter will be altered: - - * ``net.ipv4.conf.all.accept_redirects`` - * ``net.ipv6.conf.all.accept_redirects`` - -.. cfgcmd:: set firewall send-redirects [enable | disable] - - enable or disable of ICMPv4 redirect messages send by VyOS - The following system parameter will be altered: - - * ``net.ipv4.conf.all.send_redirects`` - -.. cfgcmd:: set firewall log-martians [enable | disable] - - enable or disable the logging of martian IPv4 packets. - The following system parameter will be altered: - - * ``net.ipv4.conf.all.log_martians`` - -.. cfgcmd:: set firewall source-validation [strict | loose | disable] - - Set the IPv4 source validation mode. - The following system parameter will be altered: - - * ``net.ipv4.conf.all.rp_filter`` - -.. cfgcmd:: set firewall syn-cookies [enable | disable] - - Enable or Disable if VyOS use IPv4 TCP SYN Cookies. - The following system parameter will be altered: - - * ``net.ipv4.tcp_syncookies`` - -.. cfgcmd:: set firewall twa-hazards-protection [enable | disable] - - Enable or Disable VyOS to be :rfc:`1337` conform. - The following system parameter will be altered: - - * ``net.ipv4.tcp_rfc1337`` - -.. cfgcmd:: set firewall state-policy established action [accept | drop | - reject] - -.. cfgcmd:: set firewall state-policy established log enable - - Set the global setting for a astablished connections. - -.. cfgcmd:: set firewall state-policy invalid action [accept | drop | reject] - -.. cfgcmd:: set firewall state-policy invalid log enable - - Set the global setting for invalid packets. - -.. cfgcmd:: set firewall state-policy related action [accept | drop | reject] - -.. cfgcmd:: set firewall state-policy related log enable - - Set the global setting for related connections. - - -Groups ------- - -Firewall groups represent collections of IP addresses, networks, or -ports. Once created, a group can be referenced by firewall rules as -either a source or destination. Members can be added or removed from a -group without changes to, or the need to reload, individual firewall -rules. - -.. note:: Groups can also be referenced by NAT configuration. - -Groups need to have unique names. Even though some contain IPv4 -addresses and others contain IPv6 addresses, they still need to have -unique names, so you may want to append "-v4" or "-v6" to your group -names. - - -Address Groups -************** - -In a **address group** a single IP adresses or IP address ranges are -definded. - -.. cfgcmd:: set firewall group address-group address [address | - address range] -.. cfgcmd:: set firewall group ipv6-address-group address
- - Define a IPv4 or a IPv6 address group - - .. code-block:: none - - set firewall group address-group ADR-INSIDE-v4 address 192.168.0.1 - set firewall group address-group ADR-INSIDE-v4 address 10.0.0.1-10.0.0.8 - set firewall group ipv6-address-group ADR-INSIDE-v6 address 2001:db8::1 - -.. cfgcmd:: set firewall group address-group description -.. cfgcmd:: set firewall group ipv6-address-group description - - Provide a IPv4 or IPv6 address group description - - -Network Groups -************** - -While **network groups** accept IP networks in CIDR notation, specific -IP addresses can be added as a 32-bit prefix. If you foresee the need -to add a mix of addresses and networks, the network group is -recommended. - -.. cfgcmd:: set firewall group network-group network -.. cfgcmd:: set firewall group ipv6-network-group network - - Define a IPv4 or IPv6 Network group. - - .. code-block:: none - - set firewall group network-group NET-INSIDE-v4 network 192.168.0.0/24 - set firewall group network-group NET-INSIDE-v4 network 192.168.1.0/24 - set firewall group ipv6-network-group NET-INSIDE-v6 network 2001:db8::/64 - -.. cfgcmd:: set firewall group network-group description -.. cfgcmd:: set firewall group ipv6-network-group description - - Provide a IPv4 or IPv6 network group description. - - -Port Groups -*********** - -A **port group** represents only port numbers, not the protocol. Port -groups can be referenced for either TCP or UDP. It is recommended that -TCP and UDP groups are created separately to avoid accidentally -filtering unnecessary ports. Ranges of ports can be specified by using -`-`. - -.. cfgcmd:: set firewall group port-group port - [portname | portnumber | startport-endport] - - Define a port group. A port name are any name defined in - /etc/services. e.g.: http - - .. code-block:: none - - set firewall group port-group PORT-TCP-SERVER1 port http - set firewall group port-group PORT-TCP-SERVER1 port 443 - set firewall group port-group PORT-TCP-SERVER1 port 5000-5010 - -.. cfgcmd:: set firewall group port-group description - - Provide a port group description. - - -Rule-Sets ----------- - -A rule-set is a named collection of firewall rules that can be applied -to an interface or zone. Each rule is numbered, has an action to apply -if the rule is matched, and the ability to specify the criteria to -match. Data packets go through the rules from 1 - 9999, at the first match -the action of the rule will executed. - -.. cfgcmd:: set firewall name description -.. cfgcmd:: set firewall ipv6-name description - - Provide a rule-set description. - -.. cfgcmd:: set firewall name default-action [drop | reject | accept] -.. cfgcmd:: set firewall ipv6-name default-action [drop | reject | - accept] - - This set the default action of the rule-set if no rule matched a paket - criteria. - -.. cfgcmd:: set firewall name enable-default-log -.. cfgcmd:: set firewall ipv6-name enable-default-log - - Use this command to enable the logging of the default action. - -.. cfgcmd:: set firewall name rule <1-9999> action [drop | reject | - accept] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> action [drop | reject | - accept] - - This required setting define the action of the current rule. - -.. cfgcmd:: set firewall name rule <1-9999> description -.. cfgcmd:: set firewall ipv6-name rule <1-9999> description - - Provide a description for each rule. - -.. cfgcmd:: set firewall name rule <1-9999> log [disable | enable] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> log [disable | enable] - - Enable or disable logging for the matched packet. - -.. cfgcmd:: set firewall name rule <1-9999> disable -.. cfgcmd:: set firewall ipv6-name rule <1-9999> disable - - If you want to disable a rule but let it in the configuration. - -Matching criteria -***************** - -There are a lot of matching criteria gainst which the package can be tested. - - -.. cfgcmd:: set firewall name rule <1-9999> source address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall name rule <1-9999> destination address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source address - [address | addressrange | CIDR] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination address - [address | addressrange | CIDR] - - This is similiar to the network groups part, but here you are able to negate - the matching addresses. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 100 source address 192.0.2.10-192.0.2.11 - # with a '!' the rule match everything except the specified subnet - set fitewall name WAN-IN-v4 rule 101 source address !203.0.113.0/24 - set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 - - -.. cfgcmd:: set firewall name rule <1-9999> source mac-address - -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source mac-address - - - Only in the source criteria you can specify a mac-address - - .. code-block:: none - - set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 - set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 - -.. cfgcmd:: set firewall name rule <1-9999> source port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall name rule <1-9999> destination port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source port - [1-65535 | portname | start-end] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination port - [1-65535 | portname | start-end] - - A port can be set with a portnumber or a name which is here - defined: ``/etc/services``. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 source port '22' - set firewall name WAN-IN-v4 rule 11 source port '!http' - set firewall name WAN-IN-v4 rule 12 source port 'https' - - Multiple source ports can be specified as a comma-separated list. - The whole list can also be "negated" using '!'. For example: - - .. code-block:: none - - set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' - -.. cfgcmd:: set firewall name rule <1-9999> source group - address-group -.. cfgcmd:: set firewall name rule <1-9999> destination group - address-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group - address-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group - address-group - - Use a specific address-group - -.. cfgcmd:: set firewall name rule <1-9999> source group - network-group -.. cfgcmd:: set firewall name rule <1-9999> destination group - network-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group - network-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group - network-group - - Use a specific network-group - -.. cfgcmd:: set firewall name rule <1-9999> source group - port-group -.. cfgcmd:: set firewall name rule <1-9999> destination group - port-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> source group - port-group -.. cfgcmd:: set firewall ipv6-name rule <1-9999> destination group - port-group - - Use a specific port-group - -.. cfgcmd:: set firewall name rule <1-9999> protocol [ | - <0-255> | all | tcp_udp] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> protocol [ | - <0-255> | all | tcp_udp] - - Match a protocol criteria. A protocol number or a name which is here - defined: ``/etc/protocols``. - Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and upd - based pakets. The ``!`` negate the selected protocol. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 protocol tcp_udp - set firewall name WAN-IN-v4 rule 11 protocol !tcp_udp - set firewall ipv6-name WAN-IN-v6 rule 10 protocol tcp - -.. cfgcmd:: set firewall name rule <1-9999> tcp flags -.. cfgcmd:: set firewall ipv6-name rule <1-9999> tcp flags - - Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, - ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma - separated. The ``!`` negate the selected protocol. - - .. code-block:: none - - set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' - set firewall name WAN-IN-v4 rule 12 tcp flags 'SYN' - set firewall name WAN-IN-v4 rule 13 tcp flags 'SYN,!ACK,!FIN,!RST' - -.. cfgcmd:: set firewall name rule <1-9999> state [established | - invalid | new | related] [enable | disable ] -.. cfgcmd:: set firewall ipv6-name rule <1-9999> state [established | - invalid | new | related] [enable | disable ] - - Match against the state of a packet. - - -Applying a Rule-Set to an Interface ------------------------------------ - -A Rule-Set can be appliend to every inteface: - -* ``in``: Ruleset for forwarded packets on inbound interface -* ``out``: Ruleset for forwarded packets on outbound interface -* ``local``: Ruleset for packets destined for this router - -.. cfgcmd:: set interface ethernet firewall [in | out | local] - [name | ipv6-name] - - Here are some examples for applying a rule-set to an interface - - .. code-block:: none - - set interface ethernet eth1 vif 100 firewall in name LANv4-IN - set interface ethernet eth1 vif 100 firewall out name LANv4-OUT - set interface bonding bond0 firewall in name LANv4-IN - set interfaces openvpn vtun1 firewall in name Lanv4-IN - - .. note:: - As you can see in the example here, you can assign the same rule-set to - several interfaces. An interface can only have one rule-set per chain. - - -Zone-based Firewall Policy --------------------------- - -As an alternative to applying policy to an interface directly, a -zone-based firewall can be created to simplify configuration when -multiple interfaces belong to the same security zone. Instead of -applying rulesets to interfaces, they are applied to source -zone-destination zone pairs. - -An basic introduction to zone-based firewalls can be found `here -`_, -and an example at :ref:`examples-zone-policy`. - -Define a Zone -************* - -To define a zone setup either one with interfaces or a local zone. - -.. cfgcmd:: set zone-policy zone interface - - Set a interfaces to a zone. A zone can have multiple interfaces. - But a interface can only be member in one zone. - -.. cfgcmd:: set zone-policy zone local-zone - - Define the Zone as a local zone. A local zone have no interfaces and - will be applied to the router itself. - -.. cfgcmd:: set zone-policy zone default-action [drop | reject] - - Change the default-action with this setting. - -.. cfgcmd:: set zone-policy zone description - - Set a meaningful description. - - -Applying a Rule-Set to a Zone -***************************** - -Before you are able to apply a rule-set to a zone you have to create the zones -first. - -.. cfgcmd:: set zone-policy zone from firewall name - -.. cfgcmd:: set zone-policy zone from firewall ipv6-name - - - You apply a rule-set always to a zone from a other zone, it is recommended - to create one rule-set for each zone pair. - - .. code-block:: none - - set zone-policy zone DMZ from LAN firewall name LANv4-to-DMZv4 - set zone-policy zone LAN from DMZ firewall name DMZv4-to-LANv4 - - -Operation-mode Firewall ------------------------ - -Rule-set overview -***************** - -.. opcmd:: show firewall - - This will show you a basic firewall overview - - .. code-block:: none - - vyos@vyos:~$ show firewall - - ------------------------ - Firewall Global Settings - ------------------------ - - Firewall state-policy for all IPv4 and Ipv6 traffic - - state action log - ----- ------ --- - invalid accept disabled - established accept disabled - related accept disabled - - ----------------------------- - Rulesets Information - ----------------------------- - -------------------------------------------------------------------------- - IPv4 Firewall "DMZv4-1-IN": - - Active on (eth0,IN) - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept icmp 0 0 - condition - saddr 10.1.0.0/24 daddr 0.0.0.0/0 LOG enabled - - 10000 drop all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled - - -------------------------------------------------------------------------- - IPv4 Firewall "DMZv4-1-OUT": - - Active on (eth0,OUT) - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept tcp_udp 1 60 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 match-DST-PORT-GROUP DMZ-Ports /* - DMZv4-1-OUT-10 */LOG enabled - - 11 accept icmp 1 84 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* DMZv4-1-OUT-11 */LOG enabled - - 10000 drop all 6 360 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 LOG enabled - - -------------------------------------------------------------------------- - IPv4 Firewall "LANv4-IN": - - Inactive - Not applied to any interfaces or zones. - - rule action proto packets bytes - ---- ------ ----- ------- ----- - 10 accept all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 /* LANv4-IN-10 */ - - 10000 drop all 0 0 - condition - saddr 0.0.0.0/0 daddr 0.0.0.0/0 - -.. opcmd:: show firewall summary - - This will show you a summary about rule-sets and groups - - .. code-block:: none - - vyos@vyos:~$ show firewall summary - - ------------------------ - Firewall Global Settings - ------------------------ - - Firewall state-policy for all IPv4 and Ipv6 traffic - - state action log - ----- ------ --- - invalid accept disabled - related accept disabled - established accept disabled - - ------------------------ - Firewall Rulesets - ------------------------ - - IPv4 name: - - Rule-set name Description References - ------------- ----------- ---------- - DMZv4-1-OUT (eth0,OUT) - DMZv4-1-IN (eth0,IN) - - ------------------------ - Firewall Groups - ------------------------ - - Port Groups: - - Group name Description References - ---------- ----------- ---------- - DMZ-Ports DMZv4-1-OUT-10-destination - - Network Groups: - - Group name Description References - ---------- ----------- ---------- - LANv4 LANv4-IN-10-source, - DMZv4-1-OUT-10-source, - DMZv4-1-OUT-11-source - -.. opcmd:: show firewall statistics - - This will show you a statistic of all rule-sets since the last boot. - -.. opcmd:: show firewall [name | ipv6name] rule <1-9999> - - This command will give an overview about a rule in a single rule-set - -.. opcmd:: show firewall group - - Overview of defined groups. You see the type, the members, and where the - group is used. - - .. code-block:: none - - vyos@vyos:~$ show firewall group DMZ-Ports - Name : DMZ-Ports - Type : port - References : none - Members : - 80 - 443 - 8080 - 8443 - - vyos@vyos:~$ show firewall group LANv4 - Name : LANv4 - Type : network - References : LANv4-IN-10-source - Members : - 10.10.0.0/16 - -.. opcmd:: show firewall [name | ipv6name] - - This command will give an overview about a single rule-set - -.. opcmd:: show firewall [name | ipv6name] statistics - - This will show you a rule-set statistic since the last boot. - -.. opcmd:: show firewall [name | ipv6name] rule <1-9999> - - This command will give an overview about a rule in a single rule-set - - -Zone-Policy Overview -******************** - -.. opcmd:: show zone-policy zone - - Use this command to get an overview about a zone - - .. code-block:: none - - vyos@vyos:~$ show zone-policy zone DMZ - ------------------- - Name: DMZ - - Interfaces: eth0 eth1 - - From Zone: - name firewall - ---- -------- - LAN DMZv4-1-OUT - - -Show Firewall log -***************** - -.. opcmd:: show log firewall [name | ipv6name] - - Show the logs of a specific Rule-Set - -.. note:: - At the moment it not possible to look at the whole firewall log with VyOS - operational commands. All logs will save to ``/var/logs/messages``. - For example: ``grep '10.10.0.10' /var/log/messages`` - - - -Example Partial Config ----------------------- - -.. code-block:: none - - firewall { - all-ping enable - broadcast-ping disable - config-trap disable - group { - network-group BAD-NETWORKS { - network 198.51.100.0/24 - network 203.0.113.0/24 - } - network-group GOOD-NETWORKS { - network 192.0.2.0/24 - } - port-group BAD-PORTS { - port 65535 - } - } - name FROM-INTERNET { - default-action accept - description "From the Internet" - rule 10 { - action accept - description "Authorized Networks" - protocol all - source { - group { - network-group GOOD-NETWORKS - } - } - } - rule 11 { - action drop - description "Bad Networks" - protocol all - source { - group { - network-group BAD-NETWORKS - } - } - } - rule 30 { - action drop - description "BAD PORTS" - destination { - group { - port-group BAD-PORTS - } - } - log enable - protocol all - } - } - } - interfaces { - ethernet eth1 { - address dhcp - description OUTSIDE - duplex auto - firewall { - in { - name FROM-INTERNET - } - } - } - } diff --git a/docs/index.rst b/docs/index.rst index 3322bf8d..4612d5f8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,6 @@ VyOS User Guide .. toctree:: :maxdepth: 2 :hidden: - :caption: FIND CAPTION NAME introducing/about introducing/history -- cgit v1.2.3 From bfb3814cd120d1bb661af26b3c55341f1697b397 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:25:50 +0100 Subject: arrange loadbalancing, high availability, qos --- docs/configuration/highavailability/index.rst | 158 ++++ docs/configuration/loadbalancing/index.rst | 263 ++++++ docs/configuration/trafficpolicy/index.rst | 1202 +++++++++++++++++++++++++ docs/high-availability.rst | 158 ---- docs/load-balancing.rst | 263 ------ docs/qos.rst | 1197 ------------------------ 6 files changed, 1623 insertions(+), 1618 deletions(-) create mode 100644 docs/configuration/highavailability/index.rst create mode 100644 docs/configuration/loadbalancing/index.rst create mode 100644 docs/configuration/trafficpolicy/index.rst delete mode 100644 docs/high-availability.rst delete mode 100644 docs/load-balancing.rst delete mode 100644 docs/qos.rst (limited to 'docs') diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst new file mode 100644 index 00000000..ad714597 --- /dev/null +++ b/docs/configuration/highavailability/index.rst @@ -0,0 +1,158 @@ +.. _high-availability: + +High availability +================= + +VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. +Every VRRP router has a physical IP/IPv6 address, and a virtual address. +On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. +All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. +If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. + +VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. +You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). +If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. + +Basic setup +----------- + +VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. +The required parameters are interface, vrid, and virtual-address. + +minimal config + +.. code-block:: none + + set high-availability vrrp group Foo vrid 10 + set high-availability vrrp group Foo interface eth0 + set high-availability vrrp group Foo virtual-address 192.0.2.1/24 + +You can verify your VRRP group status with the operational mode ``run show vrrp`` command: + +.. code-block:: none + + vyos@vyos# run show vrrp + Name Interface VRID State Last Transition + ---------- ----------- ------ ------- ----------------- + Foo eth1 10 MASTER 2s + +IPv6 support +------------ + +The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. + +Disabling a VRRP group +---------------------- + +You can disable a VRRP group with ``disable`` option: + +.. code-block:: none + + set high-availability vrrp group Foo disable + +A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. + +Setting VRRP group priority +--------------------------- + +VRRP priority can be set with ``priority`` option: + +.. code-block:: none + + set high-availability vrrp group Foo priority 200 + +The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. + +Sync groups +----------- + +A sync group allows VRRP groups to transition together. + +.. code-block:: none + + edit high-availability vrrp + set sync-group MAIN member VLAN9 + set sync-group MAIN member VLAN20 + +In the following example, when VLAN9 transitions, VLAN20 will also transition: + +.. code-block:: none + + vrrp { + group VLAN9 { + interface eth0.9 + virtual-address 10.9.1.1/24 + priority 200 + vrid 9 + } + group VLAN20 { + interface eth0.20 + priority 200 + virtual-address 10.20.20.1/24 + vrid 20 + } + sync-group MAIN { + member VLAN20 + member VLAN9 + } + } + + +.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. + + +Preemption +---------- + +VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. + +By default VRRP uses preemption. You can disable it with the "no-preempt" option: + +.. code-block:: none + + set high-availability vrrp group Foo no-preempt + +You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: + +.. code-block:: none + + set high-availability vrrp group Foo preempt-delay 180 + +Unicast VRRP +------------ + +By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. + +.. code-block:: none + + set high-availability vrrp group Foo peer-address 192.0.2.10 + set high-availability vrrp group Foo hello-source-address 192.0.2.15 + +Scripting +--------- + +VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. +Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. + +Health check scripts +^^^^^^^^^^^^^^^^^^^^ + +This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: + +.. code-block:: none + + set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh + set high-availability vrrp group Foo health-check interval 60 + set high-availability vrrp group Foo health-check failure-count 3 + +Transition scripts +^^^^^^^^^^^^^^^^^^ + +Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. +This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: + +.. code-block:: none + + set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" + set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/configuration/loadbalancing/index.rst b/docs/configuration/loadbalancing/index.rst new file mode 100644 index 00000000..6b0bede9 --- /dev/null +++ b/docs/configuration/loadbalancing/index.rst @@ -0,0 +1,263 @@ +.. _load-balancing: + +WAN load balancing +================== + +Outbound traffic can be balanced between two or more outbound interfaces. +If a path fails, traffic is balanced across the remaining healthy paths, a recovered path is automatically added back to the routing table and used by the load balancer. +The load balancer automatically adds routes for each path to the routing table and balances traffic across the configured interfaces, determined by interface health and weight. + + +In a minimal, configuration the following must be provided: + + * a interface with a nexthop + * one rule with a LAN (inbound-interface) and the WAN (interface). + +Let's assume we have two DHCP WAN interfaces and one LAN (eth2): + +.. code-block:: none + + set load-balancing wan interface-health eth0 nexthop 'dhcp' + set load-balancing wan interface-health eth1 nexthop 'dhcp' + set load-balancing wan rule 1 inbound-interface 'eth2' + set load-balancing wan rule 1 interface eth0 + set load-balancing wan rule 1 interface eth1 + +Balancing Rules +--------------- + +Interfaces, their weight and the type of traffic to be balanced are defined in numbered balancing rule sets. +The rule sets are executed in numerical order against outgoing packets. In case of a match the packet is sent through an interface specified in the matching rule. +If a packet doesn't match any rule it is sent by using the system routing table. Rule numbers can't be changed. + +Create a load balancing rule, rule can be a number between 1 and 9999: + +.. code-block:: none + + vyos@vyos# set load-balancing wan rule 1 + Possible completions: + description Description for this rule + > destination Destination + exclude Exclude packets matching this rule from wan load balance + failover Enable failover for packets matching this rule from wan load balance + inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] + +> interface Interface name [REQUIRED] + > limit Enable packet limit for this rule + per-packet-balancing Option to match traffic per-packet instead of the default, per-flow + protocol Protocol to match + > source Source information + +Interface weight +**************** + +Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. +Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. + +.. code-block:: none + + set load-balancing wan rule 1 interface eth0 weight 2 + set load-balancing wan rule 1 interface eth1 weight 1 + +66% traffic is routed to eth0 and eth1 get 33% of traffic. + +Rate limit +********** + +A packet rate limit can be set for a rule to apply the rule to traffic above or below a specified threshold. +To configure the rate limiting use: + +.. code-block:: none + + set load-balancing wan rule limit + +* ``burst``: Number of packets allowed to overshoot the limit within ``period``. Default 5. +* ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. +* ``rate``: Number of packets. Default 5. +* ``threshold``: ``below`` or ``above`` the specified rate limit. + +Flow and packet-based balancing +******************************* + +Outgoing traffic is balanced in a flow-based manner. +A connection tracking table is used to track flows by their source address, destination address and port. +Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. +This has the advantage that packets always arrive in order if links with different speeds are in use. + +Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: + +.. code-block:: none + + set load-balancing wan rule per-packet-balancing + +Exclude traffic +*************** + +To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: + +.. code-block:: none + + set load-balancing wan rule exclude + + +Health checks +------------- + +The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. +If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health + Possible completions: + failure-count Failure count + nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] + success-count Success count + +> test Rule number + +Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` + +.. code-block:: none + + set load-balancing wan interface-health nexthop + +Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. +Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. + +.. code-block:: none + + set load-balancing wan interface-health failure-count + set load-balancing wan interface-health success-count + +Each health check is configured in its own test, tests are numbered and processed in numeric order. +For multi target health checking multiple tests can be defined: + +.. code-block:: none + + vyos@vyos# set load-balancing wan interface-health eth1 test 0 + Possible completions: + resp-time Ping response time (seconds) + target Health target address + test-script Path to user defined script + ttl-limit Ttl limit (hop count) + type WLB test type + +* ``resp-time``: the maximum response time for ping in seconds. Range 1...30, default 5 +* ``target``: the target to be sent ICMP packets to, address can be an IPv4 address or hostname +* ``test-script``: A user defined script must return 0 to be considered successful and non-zero to fail. Scripts are located in /config/scripts, for different locations the full path needs to be provided +* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be specified. The limit must be shorter than the path length, an ICMP time expired message is needed to be returned for a successful test. default 1 +* ``type``: Specify the type of test. type can be ping, ttl or a user defined script + +Source NAT rules +---------------- + +Per default, interfaces used in a load balancing pool replace the source IP of each outgoing packet with its own address to ensure that replies arrive on the same interface. +This works through automatically generated source NAT (SNAT) rules, these rules are only applied to balanced traffic. In cases where this behaviour is not desired, the automatic generation of SNAT rules can be disabled: + +.. code-block:: none + + set load-balancing wan disable-source-nat + +Sticky Connections +------------------ +Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. + +.. image:: /_static/images/sticky-connections.jpg + :width: 80% + :align: center + + +Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. +This can be achieved by enabling sticky connections in the load balancing: + +.. code-block:: none + + set load-balancing wan sticky-connections inbound + +Failover +-------- + +In failover mode, one interface is set to be the primary interface and other interfaces are secondary or spare. +Instead of balancing traffic across all healthy interfaces, only the primary interface is used and in case of failure, a secondary interface selected from the pool of available interfaces takes over. +The primary interface is selected based on its weight and health, others become secondary interfaces. +Secondary interfaces to take over a failed primary interface are chosen from the load balancer's interface pool, depending on their weight and health. +Interface roles can also be selected based on rule order by including interfaces in balancing rules and ordering those rules accordingly. To put the load balancer in failover mode, create a failover rule: + +.. code-block:: none + + set load-balancing wan rule failover + +Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: + +.. code-block:: none + + set load-balancing wan flush-connections + +.. warning:: + + Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. + +Script execution +---------------- + +A script can be run when an interface state change occurs. Scripts are run from /config/scripts, for a different location specify the full path: + +.. code-block:: none + + set load-balancing wan hook script-name + +Two environment variables are available: + +* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored +* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state + +.. warning:: + + Blocking call with no timeout. System will become unresponsive if script does not return! + +Handling and monitoring +----------------------- + + +Show WAN load balancer information including test types and targets. +A character at the start of each line depicts the state of the test + +* ``+`` successful +* ``-`` failed +* a blank indicates that no test has been carried out + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance + Interface: eth0 + Status: failed + Last Status Change: Tue Jun 11 20:12:19 2019 + -Test: ping Target: + Last Interface Success: 55s + Last Interface Failure: 0s + # Interface Failure(s): 5 + + Interface: eth1 + Status: active + Last Status Change: Tue Jun 11 20:06:42 2019 + +Test: ping Target: + Last Interface Success: 0s + Last Interface Failure: 6m26s + # Interface Failure(s): 0 + +Show connection data of load balanced traffic: + +.. code-block:: none + + vyos@vyos:~$ show wan-load-balance connection + conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. + Type State Src Dst Packets Bytes + tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 + udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 + udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 + +Restart +******* + +.. code-block:: none + + restart wan-load-balance diff --git a/docs/configuration/trafficpolicy/index.rst b/docs/configuration/trafficpolicy/index.rst new file mode 100644 index 00000000..babccd6f --- /dev/null +++ b/docs/configuration/trafficpolicy/index.rst @@ -0,0 +1,1202 @@ +.. _qos: + +############## +Traffic Policy +############## + + +*** +QoS +*** + +The generic name of Quality of Service or Traffic Control involves +things like shaping traffic, scheduling or dropping packets, which +are the kind of things you may want to play with when you have, for +instance, a bandwidth bottleneck in a link and you want to somehow +prioritize some type of traffic over another. + +tc_ is a powerful tool for Traffic Control found at the Linux kernel. +However, its configuration is often considered a cumbersome task. +Fortunately, VyOS eases the job through its CLI, while using ``tc`` as +backend. + + +How to make it work +=================== + +In order to have VyOS Traffic Control working you need to follow 2 +steps: + + 1. **Create a traffic policy**. + + 2. **Apply the traffic policy to an interface ingress or egress**. + + +But before learning to configure your policy, we will warn you +about the different units you can use and also show you what *classes* +are and how they work, as some policies may require you to configure +them. + + +Units +===== + +When configuring your traffic policy, you will have to set data rate +values, watch out the units you are managing, it is easy to get confused +with the different prefixes and suffixes you can use. VyOS will always +show you the different units you can use. + +Prefixes +-------- + +They can be **decimal** prefixes. + + .. code-block:: none + + kbit (10^3) kilobit per second + mbit (10^6) megabit per second + gbit (10^9) gigabit per second + tbit (10^12) terabit per second + + kbps (8*10^3) kilobyte per second + mbps (8*10^6) megabyte per second + gbps (8*10^9) gigabyte per second + tbps (8*10^12) terabyte per second + +Or **binary** prefixes. + + .. code-block:: none + + kibit (2^10 = 1024) kibibit per second + mibit (2^20 = 1024^2) mebibit per second + gibit (2^30 = 1024^3) gibibit per second + tbit (2^40 = 1024^4) tebibit per second + + kibps (1024*8) kibibyte (KiB) per second + mibps (1024^2*8) mebibyte (MiB) per second + gibps (1024^3*8) gibibyte (GiB) per second + tibps (1024^4*8) tebibyte (TiB) per second + + +Suffixes +-------- + +A *bit* is written as **bit**, + + .. code-block:: none + + kbit (kilobits per second) + mbit (megabits per second) + gbit (gigabits per second) + tbit (terabits per second) + +while a *byte* is written as a single **b**. + + .. code-block:: none + + kbps (kilobytes per second) + mbps (megabytes per second) + gbps (gigabytes per second) + + + + +.. _classes: + +Classes +======= + +In the :ref:`creating_a_traffic_policy` section you will see that +some of the policies use *classes*. Those policies let you distribute +traffic into different classes according to different parameters you can +choose. So, a class is just a specific type of traffic you select. + +The ultimate goal of classifying traffic is to give each class a +different treatment. + + +Matching traffic +---------------- + +In order to define which traffic goes into which class, you define +filters (that is, the matching criteria). Packets go through these matching rules +(as in the rules of a firewall) and, if a packet matches the filter, it +is assigned to that class. + +In VyOS, a class is identified by a number you can choose when +configuring it. + + +.. note:: The meaning of the Class ID is not the same for every type of + policy. Normally policies just need a meaningless number to identify + a class (Class ID), but that does not apply to every policy. + The the number of a class in a Priority Queue it does not only + identify it, it also defines its priority. + + +.. code-block:: none + + set traffic-policy class match + + +In the command above, we set the type of policy we are going to +work with and the name we choose for it; a class (so that we can +differentiate some traffic) and an identifiable number for that class; +then we configure a matching rule (or filter) and a name for it. + +A class can have multiple match filters: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP + set traffic-policy shaper MY-SHAPER class 30 match HTTPs + +A match filter can contain multiple criteria and will match traffic if +all those criteria are true. + +For example: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp + set traffic-policy shaper MY-SHAPER class 30 match HTTP ip source port 80 + +This will match TCP traffic with source port 80. + +There are many parameters you will be able to use in order to match the +traffic you want for a class: + + - **Ethernet (protocol, destination address or source address)** + - **Interface name** + - **IPv4 (DSCP value, maximum packet length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **IPv6 (DSCP value, maximum payload length, protocol, source address,** + **destination address, source port, destination port or TCP flags)** + - **Firewall mark** + - **VLAN ID** + +When configuring your filter, you can use the ``Tab`` key to see the many +different parameters you can configure. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + + +As shown in the example above, one of the possibilities to match packets +is based on marks done by the firewall, `that can give you a great deal of flexibility`_. + +You can also write a description for a filter: + +.. code-block:: none + + set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" + + + +.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of + 20 bytes (which is the majority of IPv4 packets anyway). + + +.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see + https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers + + +Default +------- + +Often you will also have to configure your *default* traffic in the same +way you do with a class. *Default* can be considered a class as it +behaves like that. It contains any traffic that did not match any +of the defined classes, so it is like an open class, a class without +matching filters. + + +Class treatment +--------------- + +Once a class has a filter configured, you will also have to define what +you want to do with the traffic of that class, what specific +Traffic-Control treatment you want to give it. You will have different +possibilities depending on the Traffic Policy you are configuring. + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + +For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` +you would be modifying the DSCP field value of packets in that class to +Expedite Forwarding. + + + DSCP values as per :rfc:`2474` and :rfc:`4595`: + + +---------+------------+--------+------------------------------+ + | Binary | Configured | Drop | Description | + | value | value | rate | | + +=========+============+========+==============================+ + | 101110 | 46 | - | Expedited forwarding (EF) | + +---------+------------+--------+------------------------------+ + | 000000 | 0 | - | Best effort traffic, default | + +---------+------------+--------+------------------------------+ + | 001010 | 10 | Low | Assured Forwarding(AF) 11 | + +---------+------------+--------+------------------------------+ + | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | + +---------+------------+--------+------------------------------+ + | 001110 | 14 | High | Assured Forwarding(AF) 13 | + +---------+------------+--------+------------------------------+ + | 010010 | 18 | Low | Assured Forwarding(AF) 21 | + +---------+------------+--------+------------------------------+ + | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | + +---------+------------+--------+------------------------------+ + | 010110 | 22 | High | Assured Forwarding(AF) 23 | + +---------+------------+--------+------------------------------+ + | 011010 | 26 | Low | Assured Forwarding(AF) 31 | + +---------+------------+--------+------------------------------+ + | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | + +---------+------------+--------+------------------------------+ + | 011110 | 30 | High | Assured Forwarding(AF) 33 | + +---------+------------+--------+------------------------------+ + | 100010 | 34 | Low | Assured Forwarding(AF) 41 | + +---------+------------+--------+------------------------------+ + | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | + +---------+------------+--------+------------------------------+ + | 100110 | 38 | High | Assured Forwarding(AF) 43 | + +---------+------------+--------+------------------------------+ + + + + +.. _embed: + +Embedding one policy into another one +------------------------------------- + +Often we need to embed one policy into another one. It is possible to do +so on classful policies, by attaching a new policy into a class. For +instance, you might want to apply different policies to the different +classes of a Round-Robin policy you have configured. + +A common example is the case of some policies which, in order to be +effective, they need to be applied to an interface that is directly +connected where the bottleneck is. If your router is not +directly connected to the bottleneck, but some hop before it, you can +emulate the bottleneck by embedding your non-shaping policy into a +classful shaping one so that it takes effect. + +You can configure a policy into a class through the ``queue-type`` +setting. + +.. code-block:: none + + set traffic-policy shaper FQ-SHAPER bandwidth 4gbit + set traffic-policy shaper FQ-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-SHAPER default queue-type fq-codel + +As shown in the last command of the example above, the `queue-type` +setting allows these combinations. You will be able to use it +in many policies. + +.. note:: Some policies already include other embedded policies inside. + That is the case of Shaper_: each of its classes use fair-queue + unless you change it. + +.. _creating_a_traffic_policy: + + +Creating a traffic policy +========================= + +VyOS lets you control traffic in many different ways, here we will cover +every possibility. You can configure as many policies as you want, but +you will only be able to apply one policy per interface and direction +(inbound or outbound). + +Some policies can be combined, you will be able to embed_ a different +policy that will be applied to a class of the main policy. + +.. hint:: **If you are looking for a policy for your outbound traffic** + but you don't know which one you need and you don't want to go + through every possible policy shown here, **our bet is that highly + likely you are looking for a** Shaper_ **policy and you want to** + :ref:`set its queues ` **as FQ-CoDel**. + +Drop Tail +--------- + +| **Queueing discipline:** PFIFO (Packet First In First Out). +| **Applies to:** Outbound traffic. + +This the simplest queue possible you can apply to your traffic. Traffic +must go through a finite queue before it is actually sent. You must +define how many packets that queue can contain. + +When a packet is to be sent, it will have to go through that queue, so +the packet will be placed at the tail of it. When the packet completely +goes through it, it will be dequeued emptying its place in the queue and +being eventually handed to the NIC to be actually sent out. + +Despite the Drop-Tail policy does not slow down packets, if many packets +are to be sent, they could get dropped when trying to get enqueued at +the tail. This can happen if the queue has still not been able to +release enough packets from its head. + +This is the policy that requieres the lowest resources for the same +amount of traffic. But **very likely you do not need it as you cannot +get much from it. Sometimes it is used just to enable logging.** + +.. cfgcmd:: set traffic-policy drop-tail queue-limit + + Use this command to configure a drop-tail policy (PFIFO). Choose a + unique name for this policy and the size of the queue by setting the + number of packets it can contain (maximum 4294967295). + + +Fair Queue +---------- + +| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). +| **Applies to:** Outbound traffic. + +Fair Queue is a work-conserving scheduler which schedules the +transmission of packets based on flows, that is, it balances traffic +distributing it through different sub-queues in order to ensure +fairness so that each flow is able to send data in turn, preventing any +single one from drowning out the rest. + + +.. cfgcmd:: set traffic-policy fair-queue + + Use this command to create a Fair-Queue policy and give it a name. + It is based on the Stochastic Fairness Queueing and can be applied to + outbound traffic. + +In order to separate traffic, Fair Queue uses a classifier based on +source address, destination address and source port. The algorithm +enqueues packets to hash buckets based on those tree parameters. +Each of these buckets should represent a unique flow. Because multiple +flows may get hashed to the same bucket, the hashing algorithm is +perturbed at configurable intervals so that the unfairness lasts only +for a short while. Perturbation may however cause some inadvertent +packet reordering to occur. An advisable value could be 10 seconds. + +One of the uses of Fair Queue might be the mitigation of Denial of +Service attacks. + +.. cfgcmd:: set traffic-policy fair-queue hash-interval ` + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of seconds at which + a new queue algorithm perturbation will occur (maximum 4294967295). + +When dequeuing, each hash-bucket with data is queried in a round robin +fashion. You can configure the length of the queue. + +.. cfgcmd:: set traffic-policy fair-queue queue-limit + + Use this command to define a Fair-Queue policy, based on the + Stochastic Fairness Queueing, and set the number of maximum packets + allowed to wait in the queue. Any other packet will be dropped. + +.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and Fair Queue will have no + effect. If there is bandwidth available on the physical link, you can + embed_ Fair-Queue into a classful shaping policy to make sure it owns + the queue. + + + +.. _FQ-CoDel: + +FQ-CoDel +-------- + +| **Queueing discipline** Fair/Flow Queue CoDel. +| **Applies to:** Outbound Traffic. + +The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and +tries to provide good service between all of them. It also tries to keep +the length of all the queues short. + +FQ-CoDel fights bufferbloat and reduces latency without the need of +complex configurations. It has become the new default Queueing +Discipline for the interfaces of some GNU/Linux distributions. + +It uses a stochastic model to classify incoming packets into +different flows and is used to provide a fair share of the bandwidth to +all the flows using the queue. Each flow is managed by the CoDel +queuing discipline. Reordering within a flow is avoided since Codel +internally uses a FIFO queue. + +FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue +scheduler with the CoDel Active Queue Management (AQM) algorithm +operating on each queue. + + +.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it + will only be useful if your outgoing interface is really full. If it + is not, VyOS will not own the queue and FQ-Codel will have no + effect. If there is bandwidth available on the physical link, you can + embed_ FQ-Codel into a classful shaping policy to make sure it owns + the queue. If you are not sure if you need to embed your FQ-CoDel + policy into a Shaper, do it. + + +FQ-CoDel is tuned to run ok with its default parameters at 10Gbit +speeds. It might work ok too at other speeds without configuring +anything, but here we will explain some cases when you might want to +tune its parameters. + +When running it at 1Gbit and lower, you may want to reduce the +`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may +want to set it to 600 packets. + +If you are using FQ-CoDel embedded into Shaper_ and you have large rates +(100Mbit and above), you may consider increasing `quantum` to 8000 or +higher so that the scheduler saves CPU. + +On low rates (below 40Mbit) you may want to tune `quantum` down to +something like 300 bytes. + +At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps +being ok) you may also want to increase `target` to something like 15ms +and increase `interval` to something around 150 ms. + + +.. cfgcmd:: set traffic-policy fq-codel codel-quantum + + Use this command to configure an fq-codel policy, set its name and + the maximum number of bytes (default: 1514) to be dequeued from a + queue at once. + +.. cfgcmd:: set traffic-policy fq-codel flows + + Use this command to configure an fq-codel policy, set its name and + the number of sub-queues (default: 1024) into which packets are + classified. + +.. cfgcmd:: set traffic-policy fq-codel interval + + Use this command to configure an fq-codel policy, set its name and + the time period used by the control loop of CoDel to detect when a + persistent queue is developing, ensuring that the measured minimum + delay does not become too stale (default: 100ms). + +.. cfgcmd:: set traffic-policy fq-codel queue-limit ` + + Use this command to configure an fq-codel policy, set its name, and + define a hard limit on the real queue size. When this limit is + reached, new packets are dropped (default: 10240 packets). + +.. cfgcmd:: set traffic-policy fq-codel target ` + + Use this command to configure an fq-codel policy, set its name, and + define the acceptable minimum standing/persistent queue delay. This + minimum delay is identified by tracking the local minimum queue delay + that packets experience (default: 5ms). + + +Example +^^^^^^^ + +A simple example of an FQ-CoDel policy working inside a Shaper one. + + +.. code-block:: none + + set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit + set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% + set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel + + + +Limiter +------- + +| **Queueing discipline:** Ingress policer. +| **Applies to:** Inbound traffic. + +Limiter is one of those policies that uses classes_ (Ingress qdisc is +actually a classless policy but filters do work in it). + +The limiter performs basic ingress policing of traffic flows. Multiple +classes of traffic can be defined and traffic limits can be applied to +each class. Although the policer uses a token bucket mechanism +internally, it does not have the capability to delay a packet as a +shaping mechanism does. Traffic exceeding the defined bandwidth limits +is directly dropped. A maximum allowed burst can be configured too. + +You can configure classes (up to 4090) with different settings and a +default policy which will be applied to any traffic not matching any of +the configured classes. + + +.. note:: In the case you want to apply some kind of **shaping** to your + **inbound** traffic, check the ingress-shaping_ section. + + +.. cfgcmd:: set traffic-policy limiter class match description + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), a class matching rule name and its + description. + + +Once the matching rules are set for a class, you can start configuring +how you want matching traffic to behave. + + +.. cfgcmd:: set traffic-policy limiter class bandwidth + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the maximum allowed bandwidth for + this class. + + +.. cfgcmd:: set traffic-policy limiter class burst + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090) and the burst size in bytes for this + class (default: 15). + + +.. cfgcmd:: set traffic-policy limiter default bandwidth + + Use this command to configure an Ingress Policer, defining its name + and the maximum allowed bandwidth for its default policy. + + +.. cfgcmd:: set traffic-policy limiter default burst + + Use this command to configure an Ingress Policer, defining its name + and the burst size in bytes (default: 15) for its default policy. + + +.. cfgcmd:: set traffic-policy limiter class priority + + Use this command to configure an Ingress Policer, defining its name, + a class identifier (1-4090), and the priority (0-20, default 20) in + which the rule is evaluated (the lower the number, the higher the + priority). + + + +Network Emulator +---------------- + +| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). +| **Applies to:** Outbound traffic. + +VyOS Network Emulator policy emulates the conditions you can suffer in a +real network. You will be able to configure things like rate, burst, +delay, packet loss, packet corruption or packet reordering. + +This could be helpful if you want to test how an application behaves +under certain network conditions. + + +.. cfgcmd:: set traffic-policy network-emulator bandwidth + + Use this command to configure the maximum rate at which traffic will + be shaped in a Network Emulator policy. Define the name of the policy + and the rate. + +.. cfgcmd:: set traffic-policy network-emulator burst + + Use this command to configure the burst size of the traffic in a + Network Emulator policy. Define the name of the Network Emulator + policy and its traffic burst size (it will be configured through the + Token Bucket Filter qdisc). Default:15kb. It will only take effect if + you have configured its bandwidth too. + +.. cfgcmd:: set traffic-policy network-emulator network-delay + + Use this command to configure a Network Emulator policy defining its + name and the fixed amount of time you want to add to all packet going + out of the interface. The latency will be added through the + Token Bucket Filter qdisc. It will only take effect if you have + configured its bandwidth too. You can use secs, ms and us. Default: + 50ms. + +.. cfgcmd:: set traffic-policy network-emulator packet-corruption + + Use this command to emulate noise in a Network Emulator policy. Set + the policy name and the percentage of corrupted packets you want. A + random error will be introduced in a random position for the chosen + percent of packets. + +.. cfgcmd:: set traffic-policy network-emulator packet-loss ` + + Use this command to emulate packet-loss conditions in a Network + Emulator policy. Set the policy name and the percentage of loss + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator packet-reordering ` + + Use this command to emulate packet-reordering conditions in a Network + Emulator policy. Set the policy name and the percentage of reordered + packets your traffic will suffer. + +.. cfgcmd:: set traffic-policy network-emulator queue-limit + + Use this command to define the length of the queue of your Network + Emulator policy. Set the policy name and the maximum number of + packets (1-4294967295) the queue may hold queued at a time. + + + +Priority Queue +-------------- + +| **Queueing discipline:** PRIO. +| **Applies to:** Outbound traffic. + + +The Priority Queue is a classful scheduling policy. It does not delay +packets (Priority Queue is not a shaping policy), it simply dequeues +packets according to their priority. + +.. note:: Priority Queue, as other non-shaping policies, is only useful + if your outgoing interface is really full. If it is not, VyOS will + not own the queue and Priority Queue will have no effect. If there is + bandwidth available on the physical link, you can embed_ Priority + Queue into a classful shaping policy to make sure it owns the queue. + In that case packets can be prioritized based on DSCP. + +Up to seven queues -defined as classes_ with different priorities- can +be configured. Packets are placed into queues based on associated match +criteria. Packets are transmitted from the queues in priority order. If +classes with a higher priority are being filled with packets +continuously, packets from lower priority classes will only be +transmitted after traffic volume from higher priority classes decreases. + + +.. note:: In Priority Queue we do not define clases with a meaningless + class ID number but with a class priority number (1-7). The lower the + number, the higher the priority. + + +As with other policies, you can define different type of matching rules +for your classes: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE + Possible completions: + description Description for this match + > ether Ethernet header match + interface Interface name for this match + > ip Match IP protocol header + > ipv6 Match IPV6 header + mark Match on mark applied by firewall + vif Virtual Local Area Network (VLAN) ID for this match + + +As with other policies, you can embed_ other policies into the classes +(and default) of your Priority Queue policy through the ``queue-type`` +setting: + +.. code-block:: none + + vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. cfgcmd:: set traffic-policy priority-queue class queue-limit ` + + Use this command to configure a Priority Queue policy, set its name, + set a class with a priority from 1 to 7 and define a hard limit on + the real queue size. When this limit is reached, new packets are + dropped. + + + +.. _Random-Detect: + +Random-Detect +------------- + + +| **Queueing discipline:** Generalized Random Early Drop. +| **Applies to:** Outbound traffic. + +A simple Random Early Detection (RED) policy would start randomly +dropping packets from a queue before it reaches its queue limit thus +avoiding congestion. That is good for TCP connections as the gradual +dropping of packets acts as a signal for the sender to decrease its +transmission rate. + +In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random +Early Detect policy that provides different virtual queues based on the +IP Precedence value so that some virtual queues can drop more packets +than others. + +This is achieved by using the first three bits of the ToS (Type of +Service) field to categorize data streams and, in accordance with the +defined precedence parameters, a decision is made. + +IP precedence as defined in :rfc:`791`: + + +------------+----------------------+ + | Precedence | Priority | + +============+======================+ + | 7 | Network Control | + +------------+----------------------+ + | 6 | Internetwork Control | + +------------+----------------------+ + | 5 | CRITIC/ECP | + +------------+----------------------+ + | 4 | Flash Override | + +------------+----------------------+ + | 3 | Flash | + +------------+----------------------+ + | 2 | Immediate | + +------------+----------------------+ + | 1 | Priority | + +------------+----------------------+ + | 0 | Routine | + +------------+----------------------+ + + +Random-Detect could be useful for heavy traffic. One use of this +algorithm might be to prevent a backbone overload. But only for TCP +(because dropped packets could be retransmitted), not for UDP. + + +.. cfgcmd:: set traffic-policy random-detect bandwidth + + Use this command to configure a Random-Detect policy, set its name + and set the available bandwidth for this policy. It is used for + calculating the average queue size after some idle time. It should be + set to the bandwidth of your interface. Random Detect is not a + shaping policy, this command will not shape. + +.. cfgcmd:: set traffic-policy random-detect precedence average-packet + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what the size of its average-packet should be + (in bytes, default: 1024). + +.. note:: When configuring a Random-Detect policy: **the higher the + precedence number, the higher the priority**. + +.. cfgcmd:: set traffic-policy random-detect precedence mark-probability + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its mark (drop) probability will be. Set the + probability by giving the N value of the fraction 1/N (default: 10). + + +.. cfgcmd:: set traffic-policy random-detect precedence maximum-threshold + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its maximum threshold for random detection will + be (from 0 to 4096 packets, default: 18). At this size, the marking + (drop) probability is maximal. + +.. cfgcmd:: set traffic-policy random-detect precedence minimum-threshold + + Use this command to configure a Random-Detect policy and set its + name, then state the IP Precedence for the virtual queue you are + configuring and what its minimum threshold for random detection will + be (from 0 to 4096 packets). If this value is exceeded, packets + start being eligible for being dropped. + + +The default values for the minimum-threshold depend on IP precedence: + + +------------+-----------------------+ + | Precedence | default min-threshold | + +============+=======================+ + | 7 | 16 | + +------------+-----------------------+ + | 6 | 15 | + +------------+-----------------------+ + | 5 | 14 | + +------------+-----------------------+ + | 4 | 13 | + +------------+-----------------------+ + | 3 | 12 | + +------------+-----------------------+ + | 2 | 11 | + +------------+-----------------------+ + | 1 | 10 | + +------------+-----------------------+ + | 0 | 9 | + +------------+-----------------------+ + + +.. cfgcmd:: set traffic-policy random-detect precedence queue-limit + + Use this command to configure a Random-Detect policy and set its + name, then name the IP Precedence for the virtual queue you are + configuring and what the maximum size of its queue will be (from 1 to + 1-4294967295 packets). Packets are dropped when the current queue + length reaches this value. + + +If the average queue size is lower than the **min-threshold**, an +arriving packet will be placed in the queue. + +In the case the average queue size is between **min-threshold** and +**max-threshold**, then an arriving packet would be either dropped or +placed in the queue, it will depend on the defined **mark-probability**. + +If the current queue size is larger than **queue-limit**, +then packets will be dropped. The average queue size depends on its +former average size and its current one. + +If **max-threshold** is set but **min-threshold is not, then +**min-threshold** is scaled to 50% of **max-threshold**. + +In principle, values must be +:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. + + + + +Rate Control +------------ + +| **Queueing discipline:** Tocken Bucket Filter. +| **Applies to:** Outbound traffic. + +Rate-Control is a classless policy that limits the packet flow to a set +rate. It is a pure shaper, it does not schedule traffic. Traffic is +filtered based on the expenditure of tokens. Tokens roughly correspond +to bytes. + +Short bursts can be allowed to exceed the limit. On creation, the +Rate-Control traffic is stocked with tokens which correspond to the +amount of traffic that can be burst in one go. Tokens arrive at a steady +rate, until the bucket is full. + +.. cfgcmd:: set traffic-policy rate-control bandwidth + + Use this command to configure a Rate-Control policy, set its name + and the rate limit you want to have. + +.. cfgcmd:: set traffic-policy rate-control burst + + Use this command to configure a Rate-Control policy, set its name + and the size of the bucket in bytes which will be available for + burst. + + +As a reference: for 10mbit/s on Intel, you might need at least 10kbyte +buffer if you want to reach your configured rate. + +A very small buffer will soon start dropping packets. + +.. cfgcmd:: set traffic-policy rate-control latency + + Use this command to configure a Rate-Control policy, set its name + and the maximum amount of time a packet can be queued (default: 50 + ms). + + +Rate-Control is a CPU-friendly policy. You might consider using it when +you just simply want to slow traffic down. + +.. _DRR: + +Round Robin +----------- + +| **Queueing discipline:** Deficit Round Robin. +| **Applies to:** Outbound traffic. + +The round-robin policy is a classful scheduler that divides traffic in +different classes_ you can configure (up to 4096). You can embed_ a +new policy into each of those classes (default included). + +Each class is assigned a deficit counter (the number of bytes that a +flow is allowed to transmit when it is its turn) initialized to quantum. +Quantum is a parameter you configure which acts like a credit of fix +bytes the counter receives on each round. Then the Round-Robin policy +starts moving its Round Robin pointer through the queues. If the deficit +counter is greater than the packet's size at the head of the queue, this +packet will be sent and the value of the counter will be decremented by +the packet size. Then, the size of the next packet will be compared to +the counter value again, repeating the process. Once the queue is empty +or the value of the counter is insufficient, the Round-Robin pointer +will move to the next queue. If the queue is empty, the value of the +deficit counter is reset to 0. + +At every round, the deficit counter adds the quantum so that even large +packets will have their opportunity to be dequeued. + + +.. cfgcmd:: set traffic-policy round-robin class + quantum + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the quantum for that class. The deficit counter will + add that value each round. + +.. cfgcmd:: set traffic-policy round-robin class + queue-limit + + Use this command to configure a Round-Robin policy, set its name, set + a class ID, and the queue size in packets. + +As with other policies, Round-Robin can embed_ another policy into a +class through the ``queue-type`` setting. + +.. code-block:: none + + vyos@vyos# set traffic-policy round-robin DRR class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + + + + +.. _Shaper: + +Shaper +------ + +| **Queueing discipline:** Hierarchical Token Bucket. +| **Applies to:** Outbound traffic. + + +The Shaper policy does not guarantee a low delay, but it does guarantee +bandwidth to different traffic classes and also lets you decide how to +allocate more traffic once the guarantees are met. + +Each class can have a guaranteed part of the total bandwidth defined for +the whole policy, so all those shares together should not be higher +than the policy's whole bandwidth. + +If guaranteed traffic for a class is met and there is room for more +traffic, the ceiling parameter can be used to set how much more +bandwidth could be used. If guaranteed traffic is met and there are +several classes willing to use their ceilings, the priority parameter +will establish the order in which that additional traffic will be +allocated. Priority can be any number from 0 to 7. The lower the number, +the higher the priority. + + +.. cfgcmd:: set traffic-policy shaper bandwidth + + Use this command to configure a Shaper policy, set its name + and the maximum bandwidth for all combined traffic. + + +.. cfgcmd:: set traffic-policy shaper class bandwidth + + Use this command to configure a Shaper policy, set its name, define + a class and set the guaranteed traffic you want to allocate to that + class. + +.. cfgcmd:: set traffic-policy shaper class burst + + Use this command to configure a Shaper policy, set its name, define + a class and set the size of the `tocken bucket`_ in bytes, which will + be available to be sent at ceiling speed (default: 15Kb). + +.. cfgcmd:: set traffic-policy shaper class ceiling + + Use this command to configure a Shaper policy, set its name, define + a class and set the maximum speed possible for this class. The + default ceiling value is the bandwidth value. + +.. cfgcmd:: set traffic-policy shaper class priority <0-7> + + Use this command to configure a Shaper policy, set its name, define + a class and set the priority for usage of available bandwidth once + guarantees have been met. The lower the priority number, the higher + the priority. The default priority value is 0, the highest priority. + + +As with other policies, Shaper can embed_ other policies into its +classes through the ``queue-type`` setting and then configure their +parameters. + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 queue-type + Possible completions: + fq-codel Fair Queue Codel + fair-queue Stochastic Fair Queue (SFQ) + drop-tail First-In-First-Out (FIFO) + priority Priority queueing based on DSCP + random-detect + Random Early Detection (RED) + + +.. code-block:: none + + vyos@vyos# set traffic-policy shaper HTB class 10 + Possible completions: + bandwidth Bandwidth used for this class + burst Burst size for this class (default: 15kb) + ceiling Bandwidth limit for this class + codel-quantum + fq-codel - Number of bytes used as 'deficit' (default 1514) + description Description for this traffic class + flows fq-codel - Number of flows (default 1024) + interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) + +> match Class matching rule name + priority Priority for usage of excess bandwidth + queue-limit Maximum queue size (packets) + queue-type Queue type for this class + set-dscp Change the Differentiated Services (DiffServ) field in the IP header + target fq-codel - Acceptable minimum queue delay (milliseconds) + + + +.. note:: If you configure a class for **VoIP traffic**, don't give it any + *ceiling*, otherwise new VoIP calls could start when the link is + available and get suddenly dropped when other classes start using + their assigned *bandwidth* share. + + +Example +^^^^^^^ + +A simple example of Shaper using priorities. + + +.. code-block:: none + + set traffic-policy shaper MY-HTB bandwidth '50mbit' + set traffic-policy shaper MY-HTB class 10 bandwidth '20%' + set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' + set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' + set traffic-policy shaper MY-HTB class 20 bandwidth '10%' + set traffic-policy shaper MY-HTB class 20 ceiling '50%' + set traffic-policy shaper MY-HTB class 20 match PORT666 ip destination port '666' + set traffic-policy shaper MY-HTB class 20 priority '3' + set traffic-policy shaper MY-HTB class 20 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB class 30 bandwidth '10%' + set traffic-policy shaper MY-HTB class 30 ceiling '50%' + set traffic-policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' + set traffic-policy shaper MY-HTB class 30 priority '5' + set traffic-policy shaper MY-HTB class 30 queue-type 'fair-queue' + set traffic-policy shaper MY-HTB default bandwidth '10%' + set traffic-policy shaper MY-HTB default ceiling '100%' + set traffic-policy shaper MY-HTB default priority '7' + set traffic-policy shaper MY-HTB default queue-type 'fair-queue' + + +Applying a traffic policy +========================= + +Once a traffic-policy is created, you can apply it to an interface: + +.. code-block:: none + + set interfaces etherhet eth0 traffic-policy out WAN-OUT + +You can only apply one policy per interface and direction, but you could +reuse a policy on different interfaces and directions: + +.. code-block:: none + + set interfaces ethernet eth0 traffic-policy in WAN-IN + set interfaces etherhet eth0 traffic-policy out WAN-OUT + set interfaces etherhet eth1 traffic-policy in LAN-IN + set interfaces etherhet eth1 traffic-policy out LAN-OUT + set interfaces ethernet eth2 traffic-policy in LAN-IN + set interfaces ethernet eth2 traffic-policy out LAN-OUT + set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY + set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY + +Getting queueing information +---------------------------- + +.. opcmd:: show queueing + + Use this command to see the queueing information for an interface. + You will be able to see a packet counter (Sent, Dropped, Overlimit + and Backlog) per policy and class configured. + + + +.. _ingress-shaping: + +The case of ingress shaping +=========================== + +| **Applies to:** Inbound traffic. + +For the ingress traffic of an interface, there is only one policy you +can directly apply, a **Limiter** policy. You cannot apply a shaping +policy directly to the ingress traffic of any interface because shaping +only works for outbound traffic. + +This workaround lets you apply a shaping policy to the ingress traffic +by first redirecting it to an in-between virtual interface +(`Intermediate Functional Block`_). There, in that virtual interface, +you will be able to apply any of the policies that work for outbound +traffic, for instance, a shaping one. + +That is how it is possible to do the so-called "ingress shaping". + + +.. code-block:: none + + set traffic-policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit + set traffic-policy shaper MY-INGRESS-SHAPING default queue-type fair-queue + + set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING + set interfaces ethernet eth0 redirect ifb0 + +.. warning:: + + Do not configure IFB as the first step. First create everything else + of your traffic-policy, and then you can configure IFB. + Otherwise you might get the ``RTNETLINK answer: File exists`` error, + which can be solved with ``sudo ip link delete ifb0``. + + +.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches +.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) +.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket +.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve +.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb diff --git a/docs/high-availability.rst b/docs/high-availability.rst deleted file mode 100644 index ad714597..00000000 --- a/docs/high-availability.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. _high-availability: - -High availability -================= - -VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for routers. -Every VRRP router has a physical IP/IPv6 address, and a virtual address. -On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. -All routers with lower priorities become backup routers. The master then starts sending keepalive packets to notify other routers that it's available. -If the master fails and stops sending keepalive packets, the router with the next highest priority becomes the new master and takes over the virtual address. - -VRRP keepalive packets use multicast, and VRRP setups are limited to a single datalink layer segment. -You can setup multiple VRRP groups (also called virtual routers). Virtual routers are identified by a VRID (Virtual Router IDentifier). -If you setup multiple groups on the same interface, their VRIDs must be unique, but it's possible (even if not recommended for readability reasons) to use duplicate VRIDs on different interfaces. - -Basic setup ------------ - -VRRP groups are created with the ``set high-availability vrrp group $GROUP_NAME`` commands. -The required parameters are interface, vrid, and virtual-address. - -minimal config - -.. code-block:: none - - set high-availability vrrp group Foo vrid 10 - set high-availability vrrp group Foo interface eth0 - set high-availability vrrp group Foo virtual-address 192.0.2.1/24 - -You can verify your VRRP group status with the operational mode ``run show vrrp`` command: - -.. code-block:: none - - vyos@vyos# run show vrrp - Name Interface VRID State Last Transition - ---------- ----------- ------ ------- ----------------- - Foo eth1 10 MASTER 2s - -IPv6 support ------------- - -The ``virtual-address`` parameter can be either an IPv4 or IPv6 address, but you cannot mix IPv4 and IPv6 in the same group, and will need to create groups with different VRIDs specially for IPv4 and IPv6. - -Disabling a VRRP group ----------------------- - -You can disable a VRRP group with ``disable`` option: - -.. code-block:: none - - set high-availability vrrp group Foo disable - -A disabled group will be removed from the VRRP process and your router will not participate in VRRP for that VRID. It will disappear from operational mode commands output, rather than enter the backup state. - -Setting VRRP group priority ---------------------------- - -VRRP priority can be set with ``priority`` option: - -.. code-block:: none - - set high-availability vrrp group Foo priority 200 - -The priority must be an integer number from 1 to 255. Higher priority value increases router's precedence in the master elections. - -Sync groups ------------ - -A sync group allows VRRP groups to transition together. - -.. code-block:: none - - edit high-availability vrrp - set sync-group MAIN member VLAN9 - set sync-group MAIN member VLAN20 - -In the following example, when VLAN9 transitions, VLAN20 will also transition: - -.. code-block:: none - - vrrp { - group VLAN9 { - interface eth0.9 - virtual-address 10.9.1.1/24 - priority 200 - vrid 9 - } - group VLAN20 { - interface eth0.20 - priority 200 - virtual-address 10.20.20.1/24 - vrid 20 - } - sync-group MAIN { - member VLAN20 - member VLAN9 - } - } - - -.. warning:: All items in a sync group should be similarly configured. If one VRRP group is set to a different premption delay or priority, it would result in an endless transition loop. - - -Preemption ----------- - -VRRP can use two modes: preemptive and non-preemptive. In the preemptive mode, if a router with a higher priority fails and then comes back, routers with lower priority will give up their master status. In non-preemptive mode, the newly elected master will keep the master status and the virtual address indefinitely. - -By default VRRP uses preemption. You can disable it with the "no-preempt" option: - -.. code-block:: none - - set high-availability vrrp group Foo no-preempt - -You can also configure the time interval for preemption with the "preempt-delay" option. For example, to set the higher priority router to take over in 180 seconds, use: - -.. code-block:: none - - set high-availability vrrp group Foo preempt-delay 180 - -Unicast VRRP ------------- - -By default VRRP uses multicast packets. If your network does not support multicast for whatever reason, you can make VRRP use unicast communication instead. - -.. code-block:: none - - set high-availability vrrp group Foo peer-address 192.0.2.10 - set high-availability vrrp group Foo hello-source-address 192.0.2.15 - -Scripting ---------- - -VRRP functionality can be extended with scripts. VyOS supports two kinds of scripts: health check scripts and transition scripts. Health check scripts execute custom checks in addition to the master router reachability. -Transition scripts are executed when VRRP state changes from master to backup or fault and vice versa and can be used to enable or disable certain services, for example. - -Health check scripts -^^^^^^^^^^^^^^^^^^^^ - -This setup will make the VRRP process execute the ``/config/scripts/vrrp-check.sh script`` every 60 seconds, and transition the group to the fault state if it fails (i.e. exits with non-zero status) three times: - -.. code-block:: none - - set high-availability vrrp group Foo health-check script /config/scripts/vrrp-check.sh - set high-availability vrrp group Foo health-check interval 60 - set high-availability vrrp group Foo health-check failure-count 3 - -Transition scripts -^^^^^^^^^^^^^^^^^^ - -Transition scripts can help you implement various fixups, such as starting and stopping services, or even modifying the VyOS config on VRRP transition. -This setup will make the VRRP process execute the ``/config/scripts/vrrp-fail.sh`` with argument ``Foo`` when VRRP fails, and the ``/config/scripts/vrrp-master.sh`` when the router becomes the master: - -.. code-block:: none - - set high-availability vrrp group Foo transition-script backup "/config/scripts/vrrp-fail.sh Foo" - set high-availability vrrp group Foo transition-script fault "/config/scripts/vrrp-fail.sh Foo" - set high-availability vrrp group Foo transition-script master "/config/scripts/vrrp-master.sh Foo" diff --git a/docs/load-balancing.rst b/docs/load-balancing.rst deleted file mode 100644 index 6b0bede9..00000000 --- a/docs/load-balancing.rst +++ /dev/null @@ -1,263 +0,0 @@ -.. _load-balancing: - -WAN load balancing -================== - -Outbound traffic can be balanced between two or more outbound interfaces. -If a path fails, traffic is balanced across the remaining healthy paths, a recovered path is automatically added back to the routing table and used by the load balancer. -The load balancer automatically adds routes for each path to the routing table and balances traffic across the configured interfaces, determined by interface health and weight. - - -In a minimal, configuration the following must be provided: - - * a interface with a nexthop - * one rule with a LAN (inbound-interface) and the WAN (interface). - -Let's assume we have two DHCP WAN interfaces and one LAN (eth2): - -.. code-block:: none - - set load-balancing wan interface-health eth0 nexthop 'dhcp' - set load-balancing wan interface-health eth1 nexthop 'dhcp' - set load-balancing wan rule 1 inbound-interface 'eth2' - set load-balancing wan rule 1 interface eth0 - set load-balancing wan rule 1 interface eth1 - -Balancing Rules ---------------- - -Interfaces, their weight and the type of traffic to be balanced are defined in numbered balancing rule sets. -The rule sets are executed in numerical order against outgoing packets. In case of a match the packet is sent through an interface specified in the matching rule. -If a packet doesn't match any rule it is sent by using the system routing table. Rule numbers can't be changed. - -Create a load balancing rule, rule can be a number between 1 and 9999: - -.. code-block:: none - - vyos@vyos# set load-balancing wan rule 1 - Possible completions: - description Description for this rule - > destination Destination - exclude Exclude packets matching this rule from wan load balance - failover Enable failover for packets matching this rule from wan load balance - inbound-interface Inbound interface name (e.g., "eth0") [REQUIRED] - +> interface Interface name [REQUIRED] - > limit Enable packet limit for this rule - per-packet-balancing Option to match traffic per-packet instead of the default, per-flow - protocol Protocol to match - > source Source information - -Interface weight -**************** - -Let's expand the example from above and add a weight to the interfaces. The bandwidth from eth0 is larger than eth1. -Per default outbound traffic is distributed randomly across available interfaces. Weights can be assigned to interfaces to influence the balancing. - -.. code-block:: none - - set load-balancing wan rule 1 interface eth0 weight 2 - set load-balancing wan rule 1 interface eth1 weight 1 - -66% traffic is routed to eth0 and eth1 get 33% of traffic. - -Rate limit -********** - -A packet rate limit can be set for a rule to apply the rule to traffic above or below a specified threshold. -To configure the rate limiting use: - -.. code-block:: none - - set load-balancing wan rule limit - -* ``burst``: Number of packets allowed to overshoot the limit within ``period``. Default 5. -* ``period``: Time window for rate calculation. Possible values: ``second`` (one second), ``minute`` (one minute), ``hour`` (one hour). Default is ``second``. -* ``rate``: Number of packets. Default 5. -* ``threshold``: ``below`` or ``above`` the specified rate limit. - -Flow and packet-based balancing -******************************* - -Outgoing traffic is balanced in a flow-based manner. -A connection tracking table is used to track flows by their source address, destination address and port. -Each flow is assigned to an interface according to the defined balancing rules and subsequent packets are sent through the same interface. -This has the advantage that packets always arrive in order if links with different speeds are in use. - -Packet-based balancing can lead to a better balance across interfaces when out of order packets are no issue. Per-packet-based balancing can be set for a balancing rule with: - -.. code-block:: none - - set load-balancing wan rule per-packet-balancing - -Exclude traffic -*************** - -To exclude traffic from load balancing, traffic matching an exclude rule is not balanced but routed through the system routing table instead: - -.. code-block:: none - - set load-balancing wan rule exclude - - -Health checks -------------- - -The health of interfaces and paths assigned to the load balancer is periodically checked by sending ICMP packets (ping) to remote destinations, a TTL test or the execution of a user defined script. -If an interface fails the health check it is removed from the load balancer's pool of interfaces. To enable health checking for an interface: - -.. code-block:: none - - vyos@vyos# set load-balancing wan interface-health - Possible completions: - failure-count Failure count - nexthop Outbound interface nexthop address. Can be 'dhcp or ip address' [REQUIRED] - success-count Success count - +> test Rule number - -Specify nexthop on the path to destination, ``ipv4-address`` can be set to ``dhcp`` - -.. code-block:: none - - set load-balancing wan interface-health nexthop - -Set the number of health check failures before an interface is marked as unavailable, range for number is 1 to 10, default 1. -Or set the number of successful health checks before an interface is added back to the interface pool, range for number is 1 to 10, default 1. - -.. code-block:: none - - set load-balancing wan interface-health failure-count - set load-balancing wan interface-health success-count - -Each health check is configured in its own test, tests are numbered and processed in numeric order. -For multi target health checking multiple tests can be defined: - -.. code-block:: none - - vyos@vyos# set load-balancing wan interface-health eth1 test 0 - Possible completions: - resp-time Ping response time (seconds) - target Health target address - test-script Path to user defined script - ttl-limit Ttl limit (hop count) - type WLB test type - -* ``resp-time``: the maximum response time for ping in seconds. Range 1...30, default 5 -* ``target``: the target to be sent ICMP packets to, address can be an IPv4 address or hostname -* ``test-script``: A user defined script must return 0 to be considered successful and non-zero to fail. Scripts are located in /config/scripts, for different locations the full path needs to be provided -* ``ttl-limit``: For the UDP TTL limit test the hop count limit must be specified. The limit must be shorter than the path length, an ICMP time expired message is needed to be returned for a successful test. default 1 -* ``type``: Specify the type of test. type can be ping, ttl or a user defined script - -Source NAT rules ----------------- - -Per default, interfaces used in a load balancing pool replace the source IP of each outgoing packet with its own address to ensure that replies arrive on the same interface. -This works through automatically generated source NAT (SNAT) rules, these rules are only applied to balanced traffic. In cases where this behaviour is not desired, the automatic generation of SNAT rules can be disabled: - -.. code-block:: none - - set load-balancing wan disable-source-nat - -Sticky Connections ------------------- -Inbound connections to a WAN interface can be improperly handled when the reply is sent back to the client. - -.. image:: /_static/images/sticky-connections.jpg - :width: 80% - :align: center - - -Upon reception of an incoming packet, when a response is sent, it might be desired to ensure that it leaves from the same interface as the inbound one. -This can be achieved by enabling sticky connections in the load balancing: - -.. code-block:: none - - set load-balancing wan sticky-connections inbound - -Failover --------- - -In failover mode, one interface is set to be the primary interface and other interfaces are secondary or spare. -Instead of balancing traffic across all healthy interfaces, only the primary interface is used and in case of failure, a secondary interface selected from the pool of available interfaces takes over. -The primary interface is selected based on its weight and health, others become secondary interfaces. -Secondary interfaces to take over a failed primary interface are chosen from the load balancer's interface pool, depending on their weight and health. -Interface roles can also be selected based on rule order by including interfaces in balancing rules and ordering those rules accordingly. To put the load balancer in failover mode, create a failover rule: - -.. code-block:: none - - set load-balancing wan rule failover - -Because existing sessions do not automatically fail over to a new path, the session table can be flushed on each connection state change: - -.. code-block:: none - - set load-balancing wan flush-connections - -.. warning:: - - Flushing the session table will cause other connections to fall back from flow-based to packet-based balancing until each flow is reestablished. - -Script execution ----------------- - -A script can be run when an interface state change occurs. Scripts are run from /config/scripts, for a different location specify the full path: - -.. code-block:: none - - set load-balancing wan hook script-name - -Two environment variables are available: - -* ``WLB_INTERFACE_NAME=[interfacename]``: Interface to be monitored -* ``WLB_INTERFACE_STATE=[ACTIVE|FAILED]``: Interface state - -.. warning:: - - Blocking call with no timeout. System will become unresponsive if script does not return! - -Handling and monitoring ------------------------ - - -Show WAN load balancer information including test types and targets. -A character at the start of each line depicts the state of the test - -* ``+`` successful -* ``-`` failed -* a blank indicates that no test has been carried out - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance - Interface: eth0 - Status: failed - Last Status Change: Tue Jun 11 20:12:19 2019 - -Test: ping Target: - Last Interface Success: 55s - Last Interface Failure: 0s - # Interface Failure(s): 5 - - Interface: eth1 - Status: active - Last Status Change: Tue Jun 11 20:06:42 2019 - +Test: ping Target: - Last Interface Success: 0s - Last Interface Failure: 6m26s - # Interface Failure(s): 0 - -Show connection data of load balanced traffic: - -.. code-block:: none - - vyos@vyos:~$ show wan-load-balance connection - conntrack v1.4.2 (conntrack-tools): 3 flow entries have been shown. - Type State Src Dst Packets Bytes - tcp TIME_WAIT 10.1.1.13:38040 203.0.113.2:80 203.0.113.2 192.168.188.71 - udp 10.1.1.13:41891 198.51.100.3:53 198.51.100.3 192.168.188.71 - udp 10.1.1.13:55437 198.51.100.3:53 198.51.100.3 192.168.188.71 - -Restart -******* - -.. code-block:: none - - restart wan-load-balance diff --git a/docs/qos.rst b/docs/qos.rst deleted file mode 100644 index 6826b83c..00000000 --- a/docs/qos.rst +++ /dev/null @@ -1,1197 +0,0 @@ -.. _qos: - -*** -QoS -*** - -The generic name of Quality of Service or Traffic Control involves -things like shaping traffic, scheduling or dropping packets, which -are the kind of things you may want to play with when you have, for -instance, a bandwidth bottleneck in a link and you want to somehow -prioritize some type of traffic over another. - -tc_ is a powerful tool for Traffic Control found at the Linux kernel. -However, its configuration is often considered a cumbersome task. -Fortunately, VyOS eases the job through its CLI, while using ``tc`` as -backend. - - -How to make it work -=================== - -In order to have VyOS Traffic Control working you need to follow 2 -steps: - - 1. **Create a traffic policy**. - - 2. **Apply the traffic policy to an interface ingress or egress**. - - -But before learning to configure your policy, we will warn you -about the different units you can use and also show you what *classes* -are and how they work, as some policies may require you to configure -them. - - -Units -===== - -When configuring your traffic policy, you will have to set data rate -values, watch out the units you are managing, it is easy to get confused -with the different prefixes and suffixes you can use. VyOS will always -show you the different units you can use. - -Prefixes --------- - -They can be **decimal** prefixes. - - .. code-block:: none - - kbit (10^3) kilobit per second - mbit (10^6) megabit per second - gbit (10^9) gigabit per second - tbit (10^12) terabit per second - - kbps (8*10^3) kilobyte per second - mbps (8*10^6) megabyte per second - gbps (8*10^9) gigabyte per second - tbps (8*10^12) terabyte per second - -Or **binary** prefixes. - - .. code-block:: none - - kibit (2^10 = 1024) kibibit per second - mibit (2^20 = 1024^2) mebibit per second - gibit (2^30 = 1024^3) gibibit per second - tbit (2^40 = 1024^4) tebibit per second - - kibps (1024*8) kibibyte (KiB) per second - mibps (1024^2*8) mebibyte (MiB) per second - gibps (1024^3*8) gibibyte (GiB) per second - tibps (1024^4*8) tebibyte (TiB) per second - - -Suffixes --------- - -A *bit* is written as **bit**, - - .. code-block:: none - - kbit (kilobits per second) - mbit (megabits per second) - gbit (gigabits per second) - tbit (terabits per second) - -while a *byte* is written as a single **b**. - - .. code-block:: none - - kbps (kilobytes per second) - mbps (megabytes per second) - gbps (gigabytes per second) - - - - -.. _classes: - -Classes -======= - -In the :ref:`creating_a_traffic_policy` section you will see that -some of the policies use *classes*. Those policies let you distribute -traffic into different classes according to different parameters you can -choose. So, a class is just a specific type of traffic you select. - -The ultimate goal of classifying traffic is to give each class a -different treatment. - - -Matching traffic ----------------- - -In order to define which traffic goes into which class, you define -filters (that is, the matching criteria). Packets go through these matching rules -(as in the rules of a firewall) and, if a packet matches the filter, it -is assigned to that class. - -In VyOS, a class is identified by a number you can choose when -configuring it. - - -.. note:: The meaning of the Class ID is not the same for every type of - policy. Normally policies just need a meaningless number to identify - a class (Class ID), but that does not apply to every policy. - The the number of a class in a Priority Queue it does not only - identify it, it also defines its priority. - - -.. code-block:: none - - set traffic-policy class match - - -In the command above, we set the type of policy we are going to -work with and the name we choose for it; a class (so that we can -differentiate some traffic) and an identifiable number for that class; -then we configure a matching rule (or filter) and a name for it. - -A class can have multiple match filters: - -.. code-block:: none - - set traffic-policy shaper MY-SHAPER class 30 match HTTP - set traffic-policy shaper MY-SHAPER class 30 match HTTPs - -A match filter can contain multiple criteria and will match traffic if -all those criteria are true. - -For example: - -.. code-block:: none - - set traffic-policy shaper MY-SHAPER class 30 match HTTP ip protocol tcp - set traffic-policy shaper MY-SHAPER class 30 match HTTP ip source port 80 - -This will match TCP traffic with source port 80. - -There are many parameters you will be able to use in order to match the -traffic you want for a class: - - - **Ethernet (protocol, destination address or source address)** - - **Interface name** - - **IPv4 (DSCP value, maximum packet length, protocol, source address,** - **destination address, source port, destination port or TCP flags)** - - **IPv6 (DSCP value, maximum payload length, protocol, source address,** - **destination address, source port, destination port or TCP flags)** - - **Firewall mark** - - **VLAN ID** - -When configuring your filter, you can use the ``Tab`` key to see the many -different parameters you can configure. - - -.. code-block:: none - - vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER - Possible completions: - description Description for this match - > ether Ethernet header match - interface Interface name for this match - > ip Match IP protocol header - > ipv6 Match IPV6 header - mark Match on mark applied by firewall - vif Virtual Local Area Network (VLAN) ID for this match - - - -As shown in the example above, one of the possibilities to match packets -is based on marks done by the firewall, `that can give you a great deal of flexibility`_. - -You can also write a description for a filter: - -.. code-block:: none - - set traffic-policy shaper MY-SHAPER class 30 match MY-FIRST-FILTER description "My filter description" - - - -.. note:: An IPv4 TCP filter will only match packets with an IPv4 header length of - 20 bytes (which is the majority of IPv4 packets anyway). - - -.. note:: IPv6 TCP filters will only match IPv6 packets with no header extension, see - https://en.wikipedia.org/wiki/IPv6_packet#Extension_headers - - -Default -------- - -Often you will also have to configure your *default* traffic in the same -way you do with a class. *Default* can be considered a class as it -behaves like that. It contains any traffic that did not match any -of the defined classes, so it is like an open class, a class without -matching filters. - - -Class treatment ---------------- - -Once a class has a filter configured, you will also have to define what -you want to do with the traffic of that class, what specific -Traffic-Control treatment you want to give it. You will have different -possibilities depending on the Traffic Policy you are configuring. - -.. code-block:: none - - vyos@vyos# set traffic-policy shaper MY-SHAPER class 30 - Possible completions: - bandwidth Bandwidth used for this class - burst Burst size for this class (default: 15kb) - ceiling Bandwidth limit for this class - codel-quantum - fq-codel - Number of bytes used as 'deficit' (default 1514) - description Description for this traffic class - flows fq-codel - Number of flows (default 1024) - interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) - +> match Class matching rule name - priority Priority for usage of excess bandwidth - queue-limit Maximum queue size (packets) - queue-type Queue type for this class - set-dscp Change the Differentiated Services (DiffServ) field in the IP header - target fq-codel - Acceptable minimum queue delay (milliseconds) - - -For instance, with :code:`set traffic-policy shaper MY-SHAPER class 30 set-dscp EF` -you would be modifying the DSCP field value of packets in that class to -Expedite Forwarding. - - - DSCP values as per :rfc:`2474` and :rfc:`4595`: - - +---------+------------+--------+------------------------------+ - | Binary | Configured | Drop | Description | - | value | value | rate | | - +=========+============+========+==============================+ - | 101110 | 46 | - | Expedited forwarding (EF) | - +---------+------------+--------+------------------------------+ - | 000000 | 0 | - | Best effort traffic, default | - +---------+------------+--------+------------------------------+ - | 001010 | 10 | Low | Assured Forwarding(AF) 11 | - +---------+------------+--------+------------------------------+ - | 001100 | 12 | Medium | Assured Forwarding(AF) 12 | - +---------+------------+--------+------------------------------+ - | 001110 | 14 | High | Assured Forwarding(AF) 13 | - +---------+------------+--------+------------------------------+ - | 010010 | 18 | Low | Assured Forwarding(AF) 21 | - +---------+------------+--------+------------------------------+ - | 010100 | 20 | Medium | Assured Forwarding(AF) 22 | - +---------+------------+--------+------------------------------+ - | 010110 | 22 | High | Assured Forwarding(AF) 23 | - +---------+------------+--------+------------------------------+ - | 011010 | 26 | Low | Assured Forwarding(AF) 31 | - +---------+------------+--------+------------------------------+ - | 011100 | 28 | Medium | Assured Forwarding(AF) 32 | - +---------+------------+--------+------------------------------+ - | 011110 | 30 | High | Assured Forwarding(AF) 33 | - +---------+------------+--------+------------------------------+ - | 100010 | 34 | Low | Assured Forwarding(AF) 41 | - +---------+------------+--------+------------------------------+ - | 100100 | 36 | Medium | Assured Forwarding(AF) 42 | - +---------+------------+--------+------------------------------+ - | 100110 | 38 | High | Assured Forwarding(AF) 43 | - +---------+------------+--------+------------------------------+ - - - - -.. _embed: - -Embedding one policy into another one -------------------------------------- - -Often we need to embed one policy into another one. It is possible to do -so on classful policies, by attaching a new policy into a class. For -instance, you might want to apply different policies to the different -classes of a Round-Robin policy you have configured. - -A common example is the case of some policies which, in order to be -effective, they need to be applied to an interface that is directly -connected where the bottleneck is. If your router is not -directly connected to the bottleneck, but some hop before it, you can -emulate the bottleneck by embedding your non-shaping policy into a -classful shaping one so that it takes effect. - -You can configure a policy into a class through the ``queue-type`` -setting. - -.. code-block:: none - - set traffic-policy shaper FQ-SHAPER bandwidth 4gbit - set traffic-policy shaper FQ-SHAPER default bandwidth 100% - set traffic-policy shaper FQ-SHAPER default queue-type fq-codel - -As shown in the last command of the example above, the `queue-type` -setting allows these combinations. You will be able to use it -in many policies. - -.. note:: Some policies already include other embedded policies inside. - That is the case of Shaper_: each of its classes use fair-queue - unless you change it. - -.. _creating_a_traffic_policy: - - -Creating a traffic policy -========================= - -VyOS lets you control traffic in many different ways, here we will cover -every possibility. You can configure as many policies as you want, but -you will only be able to apply one policy per interface and direction -(inbound or outbound). - -Some policies can be combined, you will be able to embed_ a different -policy that will be applied to a class of the main policy. - -.. hint:: **If you are looking for a policy for your outbound traffic** - but you don't know which one you need and you don't want to go - through every possible policy shown here, **our bet is that highly - likely you are looking for a** Shaper_ **policy and you want to** - :ref:`set its queues ` **as FQ-CoDel**. - -Drop Tail ---------- - -| **Queueing discipline:** PFIFO (Packet First In First Out). -| **Applies to:** Outbound traffic. - -This the simplest queue possible you can apply to your traffic. Traffic -must go through a finite queue before it is actually sent. You must -define how many packets that queue can contain. - -When a packet is to be sent, it will have to go through that queue, so -the packet will be placed at the tail of it. When the packet completely -goes through it, it will be dequeued emptying its place in the queue and -being eventually handed to the NIC to be actually sent out. - -Despite the Drop-Tail policy does not slow down packets, if many packets -are to be sent, they could get dropped when trying to get enqueued at -the tail. This can happen if the queue has still not been able to -release enough packets from its head. - -This is the policy that requieres the lowest resources for the same -amount of traffic. But **very likely you do not need it as you cannot -get much from it. Sometimes it is used just to enable logging.** - -.. cfgcmd:: set traffic-policy drop-tail queue-limit - - Use this command to configure a drop-tail policy (PFIFO). Choose a - unique name for this policy and the size of the queue by setting the - number of packets it can contain (maximum 4294967295). - - -Fair Queue ----------- - -| **Queueing discipline:** SFQ (Stochastic Fairness Queuing). -| **Applies to:** Outbound traffic. - -Fair Queue is a work-conserving scheduler which schedules the -transmission of packets based on flows, that is, it balances traffic -distributing it through different sub-queues in order to ensure -fairness so that each flow is able to send data in turn, preventing any -single one from drowning out the rest. - - -.. cfgcmd:: set traffic-policy fair-queue - - Use this command to create a Fair-Queue policy and give it a name. - It is based on the Stochastic Fairness Queueing and can be applied to - outbound traffic. - -In order to separate traffic, Fair Queue uses a classifier based on -source address, destination address and source port. The algorithm -enqueues packets to hash buckets based on those tree parameters. -Each of these buckets should represent a unique flow. Because multiple -flows may get hashed to the same bucket, the hashing algorithm is -perturbed at configurable intervals so that the unfairness lasts only -for a short while. Perturbation may however cause some inadvertent -packet reordering to occur. An advisable value could be 10 seconds. - -One of the uses of Fair Queue might be the mitigation of Denial of -Service attacks. - -.. cfgcmd:: set traffic-policy fair-queue hash-interval ` - - Use this command to define a Fair-Queue policy, based on the - Stochastic Fairness Queueing, and set the number of seconds at which - a new queue algorithm perturbation will occur (maximum 4294967295). - -When dequeuing, each hash-bucket with data is queried in a round robin -fashion. You can configure the length of the queue. - -.. cfgcmd:: set traffic-policy fair-queue queue-limit - - Use this command to define a Fair-Queue policy, based on the - Stochastic Fairness Queueing, and set the number of maximum packets - allowed to wait in the queue. Any other packet will be dropped. - -.. note:: Fair Queue is a non-shaping (work-conserving) policy, so it - will only be useful if your outgoing interface is really full. If it - is not, VyOS will not own the queue and Fair Queue will have no - effect. If there is bandwidth available on the physical link, you can - embed_ Fair-Queue into a classful shaping policy to make sure it owns - the queue. - - - -.. _FQ-CoDel: - -FQ-CoDel --------- - -| **Queueing discipline** Fair/Flow Queue CoDel. -| **Applies to:** Outbound Traffic. - -The FQ-CoDel policy distributes the traffic into 1024 FIFO queues and -tries to provide good service between all of them. It also tries to keep -the length of all the queues short. - -FQ-CoDel fights bufferbloat and reduces latency without the need of -complex configurations. It has become the new default Queueing -Discipline for the interfaces of some GNU/Linux distributions. - -It uses a stochastic model to classify incoming packets into -different flows and is used to provide a fair share of the bandwidth to -all the flows using the queue. Each flow is managed by the CoDel -queuing discipline. Reordering within a flow is avoided since Codel -internally uses a FIFO queue. - -FQ-CoDel is based on a modified Deficit Round Robin (DRR_) queue -scheduler with the CoDel Active Queue Management (AQM) algorithm -operating on each queue. - - -.. note:: FQ-Codel is a non-shaping (work-conserving) policy, so it - will only be useful if your outgoing interface is really full. If it - is not, VyOS will not own the queue and FQ-Codel will have no - effect. If there is bandwidth available on the physical link, you can - embed_ FQ-Codel into a classful shaping policy to make sure it owns - the queue. If you are not sure if you need to embed your FQ-CoDel - policy into a Shaper, do it. - - -FQ-CoDel is tuned to run ok with its default parameters at 10Gbit -speeds. It might work ok too at other speeds without configuring -anything, but here we will explain some cases when you might want to -tune its parameters. - -When running it at 1Gbit and lower, you may want to reduce the -`queue-limit` to 1000 packets or less. In rates like 10Mbit, you may -want to set it to 600 packets. - -If you are using FQ-CoDel embedded into Shaper_ and you have large rates -(100Mbit and above), you may consider increasing `quantum` to 8000 or -higher so that the scheduler saves CPU. - -On low rates (below 40Mbit) you may want to tune `quantum` down to -something like 300 bytes. - -At very low rates (below 3Mbit), besides tuning `quantum` (300 keeps -being ok) you may also want to increase `target` to something like 15ms -and increase `interval` to something around 150 ms. - - -.. cfgcmd:: set traffic-policy fq-codel codel-quantum - - Use this command to configure an fq-codel policy, set its name and - the maximum number of bytes (default: 1514) to be dequeued from a - queue at once. - -.. cfgcmd:: set traffic-policy fq-codel flows - - Use this command to configure an fq-codel policy, set its name and - the number of sub-queues (default: 1024) into which packets are - classified. - -.. cfgcmd:: set traffic-policy fq-codel interval - - Use this command to configure an fq-codel policy, set its name and - the time period used by the control loop of CoDel to detect when a - persistent queue is developing, ensuring that the measured minimum - delay does not become too stale (default: 100ms). - -.. cfgcmd:: set traffic-policy fq-codel queue-limit ` - - Use this command to configure an fq-codel policy, set its name, and - define a hard limit on the real queue size. When this limit is - reached, new packets are dropped (default: 10240 packets). - -.. cfgcmd:: set traffic-policy fq-codel target ` - - Use this command to configure an fq-codel policy, set its name, and - define the acceptable minimum standing/persistent queue delay. This - minimum delay is identified by tracking the local minimum queue delay - that packets experience (default: 5ms). - - -Example -^^^^^^^ - -A simple example of an FQ-CoDel policy working inside a Shaper one. - - -.. code-block:: none - - set traffic-policy shaper FQ-CODEL-SHAPER bandwidth 2gbit - set traffic-policy shaper FQ-CODEL-SHAPER default bandwidth 100% - set traffic-policy shaper FQ-CODEL-SHAPER default queue-type fq-codel - - - -Limiter -------- - -| **Queueing discipline:** Ingress policer. -| **Applies to:** Inbound traffic. - -Limiter is one of those policies that uses classes_ (Ingress qdisc is -actually a classless policy but filters do work in it). - -The limiter performs basic ingress policing of traffic flows. Multiple -classes of traffic can be defined and traffic limits can be applied to -each class. Although the policer uses a token bucket mechanism -internally, it does not have the capability to delay a packet as a -shaping mechanism does. Traffic exceeding the defined bandwidth limits -is directly dropped. A maximum allowed burst can be configured too. - -You can configure classes (up to 4090) with different settings and a -default policy which will be applied to any traffic not matching any of -the configured classes. - - -.. note:: In the case you want to apply some kind of **shaping** to your - **inbound** traffic, check the ingress-shaping_ section. - - -.. cfgcmd:: set traffic-policy limiter class match description - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090), a class matching rule name and its - description. - - -Once the matching rules are set for a class, you can start configuring -how you want matching traffic to behave. - - -.. cfgcmd:: set traffic-policy limiter class bandwidth - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090) and the maximum allowed bandwidth for - this class. - - -.. cfgcmd:: set traffic-policy limiter class burst - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090) and the burst size in bytes for this - class (default: 15). - - -.. cfgcmd:: set traffic-policy limiter default bandwidth - - Use this command to configure an Ingress Policer, defining its name - and the maximum allowed bandwidth for its default policy. - - -.. cfgcmd:: set traffic-policy limiter default burst - - Use this command to configure an Ingress Policer, defining its name - and the burst size in bytes (default: 15) for its default policy. - - -.. cfgcmd:: set traffic-policy limiter class priority - - Use this command to configure an Ingress Policer, defining its name, - a class identifier (1-4090), and the priority (0-20, default 20) in - which the rule is evaluated (the lower the number, the higher the - priority). - - - -Network Emulator ----------------- - -| **Queueing discipline:** netem (Network Emulator) + TBF (Token Bucket Filter). -| **Applies to:** Outbound traffic. - -VyOS Network Emulator policy emulates the conditions you can suffer in a -real network. You will be able to configure things like rate, burst, -delay, packet loss, packet corruption or packet reordering. - -This could be helpful if you want to test how an application behaves -under certain network conditions. - - -.. cfgcmd:: set traffic-policy network-emulator bandwidth - - Use this command to configure the maximum rate at which traffic will - be shaped in a Network Emulator policy. Define the name of the policy - and the rate. - -.. cfgcmd:: set traffic-policy network-emulator burst - - Use this command to configure the burst size of the traffic in a - Network Emulator policy. Define the name of the Network Emulator - policy and its traffic burst size (it will be configured through the - Token Bucket Filter qdisc). Default:15kb. It will only take effect if - you have configured its bandwidth too. - -.. cfgcmd:: set traffic-policy network-emulator network-delay - - Use this command to configure a Network Emulator policy defining its - name and the fixed amount of time you want to add to all packet going - out of the interface. The latency will be added through the - Token Bucket Filter qdisc. It will only take effect if you have - configured its bandwidth too. You can use secs, ms and us. Default: - 50ms. - -.. cfgcmd:: set traffic-policy network-emulator packet-corruption - - Use this command to emulate noise in a Network Emulator policy. Set - the policy name and the percentage of corrupted packets you want. A - random error will be introduced in a random position for the chosen - percent of packets. - -.. cfgcmd:: set traffic-policy network-emulator packet-loss ` - - Use this command to emulate packet-loss conditions in a Network - Emulator policy. Set the policy name and the percentage of loss - packets your traffic will suffer. - -.. cfgcmd:: set traffic-policy network-emulator packet-reordering ` - - Use this command to emulate packet-reordering conditions in a Network - Emulator policy. Set the policy name and the percentage of reordered - packets your traffic will suffer. - -.. cfgcmd:: set traffic-policy network-emulator queue-limit - - Use this command to define the length of the queue of your Network - Emulator policy. Set the policy name and the maximum number of - packets (1-4294967295) the queue may hold queued at a time. - - - -Priority Queue --------------- - -| **Queueing discipline:** PRIO. -| **Applies to:** Outbound traffic. - - -The Priority Queue is a classful scheduling policy. It does not delay -packets (Priority Queue is not a shaping policy), it simply dequeues -packets according to their priority. - -.. note:: Priority Queue, as other non-shaping policies, is only useful - if your outgoing interface is really full. If it is not, VyOS will - not own the queue and Priority Queue will have no effect. If there is - bandwidth available on the physical link, you can embed_ Priority - Queue into a classful shaping policy to make sure it owns the queue. - In that case packets can be prioritized based on DSCP. - -Up to seven queues -defined as classes_ with different priorities- can -be configured. Packets are placed into queues based on associated match -criteria. Packets are transmitted from the queues in priority order. If -classes with a higher priority are being filled with packets -continuously, packets from lower priority classes will only be -transmitted after traffic volume from higher priority classes decreases. - - -.. note:: In Priority Queue we do not define clases with a meaningless - class ID number but with a class priority number (1-7). The lower the - number, the higher the priority. - - -As with other policies, you can define different type of matching rules -for your classes: - -.. code-block:: none - - vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 match MY-MATCH-RULE - Possible completions: - description Description for this match - > ether Ethernet header match - interface Interface name for this match - > ip Match IP protocol header - > ipv6 Match IPV6 header - mark Match on mark applied by firewall - vif Virtual Local Area Network (VLAN) ID for this match - - -As with other policies, you can embed_ other policies into the classes -(and default) of your Priority Queue policy through the ``queue-type`` -setting: - -.. code-block:: none - - vyos@vyos# set traffic-policy priority-queue MY-PRIO class 3 queue-type - Possible completions: - fq-codel Fair Queue Codel - fair-queue Stochastic Fair Queue (SFQ) - drop-tail First-In-First-Out (FIFO) - priority Priority queueing based on DSCP - random-detect - Random Early Detection (RED) - - -.. cfgcmd:: set traffic-policy priority-queue class queue-limit ` - - Use this command to configure a Priority Queue policy, set its name, - set a class with a priority from 1 to 7 and define a hard limit on - the real queue size. When this limit is reached, new packets are - dropped. - - - -.. _Random-Detect: - -Random-Detect -------------- - - -| **Queueing discipline:** Generalized Random Early Drop. -| **Applies to:** Outbound traffic. - -A simple Random Early Detection (RED) policy would start randomly -dropping packets from a queue before it reaches its queue limit thus -avoiding congestion. That is good for TCP connections as the gradual -dropping of packets acts as a signal for the sender to decrease its -transmission rate. - -In contrast to simple RED, VyOS' Random-Detect uses a Generalized Random -Early Detect policy that provides different virtual queues based on the -IP Precedence value so that some virtual queues can drop more packets -than others. - -This is achieved by using the first three bits of the ToS (Type of -Service) field to categorize data streams and, in accordance with the -defined precedence parameters, a decision is made. - -IP precedence as defined in :rfc:`791`: - - +------------+----------------------+ - | Precedence | Priority | - +============+======================+ - | 7 | Network Control | - +------------+----------------------+ - | 6 | Internetwork Control | - +------------+----------------------+ - | 5 | CRITIC/ECP | - +------------+----------------------+ - | 4 | Flash Override | - +------------+----------------------+ - | 3 | Flash | - +------------+----------------------+ - | 2 | Immediate | - +------------+----------------------+ - | 1 | Priority | - +------------+----------------------+ - | 0 | Routine | - +------------+----------------------+ - - -Random-Detect could be useful for heavy traffic. One use of this -algorithm might be to prevent a backbone overload. But only for TCP -(because dropped packets could be retransmitted), not for UDP. - - -.. cfgcmd:: set traffic-policy random-detect bandwidth - - Use this command to configure a Random-Detect policy, set its name - and set the available bandwidth for this policy. It is used for - calculating the average queue size after some idle time. It should be - set to the bandwidth of your interface. Random Detect is not a - shaping policy, this command will not shape. - -.. cfgcmd:: set traffic-policy random-detect precedence average-packet - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what the size of its average-packet should be - (in bytes, default: 1024). - -.. note:: When configuring a Random-Detect policy: **the higher the - precedence number, the higher the priority**. - -.. cfgcmd:: set traffic-policy random-detect precedence mark-probability - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its mark (drop) probability will be. Set the - probability by giving the N value of the fraction 1/N (default: 10). - - -.. cfgcmd:: set traffic-policy random-detect precedence maximum-threshold - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its maximum threshold for random detection will - be (from 0 to 4096 packets, default: 18). At this size, the marking - (drop) probability is maximal. - -.. cfgcmd:: set traffic-policy random-detect precedence minimum-threshold - - Use this command to configure a Random-Detect policy and set its - name, then state the IP Precedence for the virtual queue you are - configuring and what its minimum threshold for random detection will - be (from 0 to 4096 packets). If this value is exceeded, packets - start being eligible for being dropped. - - -The default values for the minimum-threshold depend on IP precedence: - - +------------+-----------------------+ - | Precedence | default min-threshold | - +============+=======================+ - | 7 | 16 | - +------------+-----------------------+ - | 6 | 15 | - +------------+-----------------------+ - | 5 | 14 | - +------------+-----------------------+ - | 4 | 13 | - +------------+-----------------------+ - | 3 | 12 | - +------------+-----------------------+ - | 2 | 11 | - +------------+-----------------------+ - | 1 | 10 | - +------------+-----------------------+ - | 0 | 9 | - +------------+-----------------------+ - - -.. cfgcmd:: set traffic-policy random-detect precedence queue-limit - - Use this command to configure a Random-Detect policy and set its - name, then name the IP Precedence for the virtual queue you are - configuring and what the maximum size of its queue will be (from 1 to - 1-4294967295 packets). Packets are dropped when the current queue - length reaches this value. - - -If the average queue size is lower than the **min-threshold**, an -arriving packet will be placed in the queue. - -In the case the average queue size is between **min-threshold** and -**max-threshold**, then an arriving packet would be either dropped or -placed in the queue, it will depend on the defined **mark-probability**. - -If the current queue size is larger than **queue-limit**, -then packets will be dropped. The average queue size depends on its -former average size and its current one. - -If **max-threshold** is set but **min-threshold is not, then -**min-threshold** is scaled to 50% of **max-threshold**. - -In principle, values must be -:code:`min-threshold` < :code:`max-threshold` < :code:`queue-limit`. - - - - -Rate Control ------------- - -| **Queueing discipline:** Tocken Bucket Filter. -| **Applies to:** Outbound traffic. - -Rate-Control is a classless policy that limits the packet flow to a set -rate. It is a pure shaper, it does not schedule traffic. Traffic is -filtered based on the expenditure of tokens. Tokens roughly correspond -to bytes. - -Short bursts can be allowed to exceed the limit. On creation, the -Rate-Control traffic is stocked with tokens which correspond to the -amount of traffic that can be burst in one go. Tokens arrive at a steady -rate, until the bucket is full. - -.. cfgcmd:: set traffic-policy rate-control bandwidth - - Use this command to configure a Rate-Control policy, set its name - and the rate limit you want to have. - -.. cfgcmd:: set traffic-policy rate-control burst - - Use this command to configure a Rate-Control policy, set its name - and the size of the bucket in bytes which will be available for - burst. - - -As a reference: for 10mbit/s on Intel, you might need at least 10kbyte -buffer if you want to reach your configured rate. - -A very small buffer will soon start dropping packets. - -.. cfgcmd:: set traffic-policy rate-control latency - - Use this command to configure a Rate-Control policy, set its name - and the maximum amount of time a packet can be queued (default: 50 - ms). - - -Rate-Control is a CPU-friendly policy. You might consider using it when -you just simply want to slow traffic down. - -.. _DRR: - -Round Robin ------------ - -| **Queueing discipline:** Deficit Round Robin. -| **Applies to:** Outbound traffic. - -The round-robin policy is a classful scheduler that divides traffic in -different classes_ you can configure (up to 4096). You can embed_ a -new policy into each of those classes (default included). - -Each class is assigned a deficit counter (the number of bytes that a -flow is allowed to transmit when it is its turn) initialized to quantum. -Quantum is a parameter you configure which acts like a credit of fix -bytes the counter receives on each round. Then the Round-Robin policy -starts moving its Round Robin pointer through the queues. If the deficit -counter is greater than the packet's size at the head of the queue, this -packet will be sent and the value of the counter will be decremented by -the packet size. Then, the size of the next packet will be compared to -the counter value again, repeating the process. Once the queue is empty -or the value of the counter is insufficient, the Round-Robin pointer -will move to the next queue. If the queue is empty, the value of the -deficit counter is reset to 0. - -At every round, the deficit counter adds the quantum so that even large -packets will have their opportunity to be dequeued. - - -.. cfgcmd:: set traffic-policy round-robin class - quantum - - Use this command to configure a Round-Robin policy, set its name, set - a class ID, and the quantum for that class. The deficit counter will - add that value each round. - -.. cfgcmd:: set traffic-policy round-robin class - queue-limit - - Use this command to configure a Round-Robin policy, set its name, set - a class ID, and the queue size in packets. - -As with other policies, Round-Robin can embed_ another policy into a -class through the ``queue-type`` setting. - -.. code-block:: none - - vyos@vyos# set traffic-policy round-robin DRR class 10 queue-type - Possible completions: - fq-codel Fair Queue Codel - fair-queue Stochastic Fair Queue (SFQ) - drop-tail First-In-First-Out (FIFO) - priority Priority queueing based on DSCP - - - - -.. _Shaper: - -Shaper ------- - -| **Queueing discipline:** Hierarchical Token Bucket. -| **Applies to:** Outbound traffic. - - -The Shaper policy does not guarantee a low delay, but it does guarantee -bandwidth to different traffic classes and also lets you decide how to -allocate more traffic once the guarantees are met. - -Each class can have a guaranteed part of the total bandwidth defined for -the whole policy, so all those shares together should not be higher -than the policy's whole bandwidth. - -If guaranteed traffic for a class is met and there is room for more -traffic, the ceiling parameter can be used to set how much more -bandwidth could be used. If guaranteed traffic is met and there are -several classes willing to use their ceilings, the priority parameter -will establish the order in which that additional traffic will be -allocated. Priority can be any number from 0 to 7. The lower the number, -the higher the priority. - - -.. cfgcmd:: set traffic-policy shaper bandwidth - - Use this command to configure a Shaper policy, set its name - and the maximum bandwidth for all combined traffic. - - -.. cfgcmd:: set traffic-policy shaper class bandwidth - - Use this command to configure a Shaper policy, set its name, define - a class and set the guaranteed traffic you want to allocate to that - class. - -.. cfgcmd:: set traffic-policy shaper class burst - - Use this command to configure a Shaper policy, set its name, define - a class and set the size of the `tocken bucket`_ in bytes, which will - be available to be sent at ceiling speed (default: 15Kb). - -.. cfgcmd:: set traffic-policy shaper class ceiling - - Use this command to configure a Shaper policy, set its name, define - a class and set the maximum speed possible for this class. The - default ceiling value is the bandwidth value. - -.. cfgcmd:: set traffic-policy shaper class priority <0-7> - - Use this command to configure a Shaper policy, set its name, define - a class and set the priority for usage of available bandwidth once - guarantees have been met. The lower the priority number, the higher - the priority. The default priority value is 0, the highest priority. - - -As with other policies, Shaper can embed_ other policies into its -classes through the ``queue-type`` setting and then configure their -parameters. - - -.. code-block:: none - - vyos@vyos# set traffic-policy shaper HTB class 10 queue-type - Possible completions: - fq-codel Fair Queue Codel - fair-queue Stochastic Fair Queue (SFQ) - drop-tail First-In-First-Out (FIFO) - priority Priority queueing based on DSCP - random-detect - Random Early Detection (RED) - - -.. code-block:: none - - vyos@vyos# set traffic-policy shaper HTB class 10 - Possible completions: - bandwidth Bandwidth used for this class - burst Burst size for this class (default: 15kb) - ceiling Bandwidth limit for this class - codel-quantum - fq-codel - Number of bytes used as 'deficit' (default 1514) - description Description for this traffic class - flows fq-codel - Number of flows (default 1024) - interval fq-codel - Interval (milliseconds) used to measure the delay (default 100) - +> match Class matching rule name - priority Priority for usage of excess bandwidth - queue-limit Maximum queue size (packets) - queue-type Queue type for this class - set-dscp Change the Differentiated Services (DiffServ) field in the IP header - target fq-codel - Acceptable minimum queue delay (milliseconds) - - - -.. note:: If you configure a class for **VoIP traffic**, don't give it any - *ceiling*, otherwise new VoIP calls could start when the link is - available and get suddenly dropped when other classes start using - their assigned *bandwidth* share. - - -Example -^^^^^^^ - -A simple example of Shaper using priorities. - - -.. code-block:: none - - set traffic-policy shaper MY-HTB bandwidth '50mbit' - set traffic-policy shaper MY-HTB class 10 bandwidth '20%' - set traffic-policy shaper MY-HTB class 10 match DSCP ip dscp 'EF' - set traffic-policy shaper MY-HTB class 10 queue-type 'fq-codel' - set traffic-policy shaper MY-HTB class 20 bandwidth '10%' - set traffic-policy shaper MY-HTB class 20 ceiling '50%' - set traffic-policy shaper MY-HTB class 20 match PORT666 ip destination port '666' - set traffic-policy shaper MY-HTB class 20 priority '3' - set traffic-policy shaper MY-HTB class 20 queue-type 'fair-queue' - set traffic-policy shaper MY-HTB class 30 bandwidth '10%' - set traffic-policy shaper MY-HTB class 30 ceiling '50%' - set traffic-policy shaper MY-HTB class 30 match ADDRESS30 ip source address '192.168.30.0/24' - set traffic-policy shaper MY-HTB class 30 priority '5' - set traffic-policy shaper MY-HTB class 30 queue-type 'fair-queue' - set traffic-policy shaper MY-HTB default bandwidth '10%' - set traffic-policy shaper MY-HTB default ceiling '100%' - set traffic-policy shaper MY-HTB default priority '7' - set traffic-policy shaper MY-HTB default queue-type 'fair-queue' - - -Applying a traffic policy -========================= - -Once a traffic-policy is created, you can apply it to an interface: - -.. code-block:: none - - set interfaces etherhet eth0 traffic-policy out WAN-OUT - -You can only apply one policy per interface and direction, but you could -reuse a policy on different interfaces and directions: - -.. code-block:: none - - set interfaces ethernet eth0 traffic-policy in WAN-IN - set interfaces etherhet eth0 traffic-policy out WAN-OUT - set interfaces etherhet eth1 traffic-policy in LAN-IN - set interfaces etherhet eth1 traffic-policy out LAN-OUT - set interfaces ethernet eth2 traffic-policy in LAN-IN - set interfaces ethernet eth2 traffic-policy out LAN-OUT - set interfaces etherhet eth3 traffic-policy in TWO-WAY-POLICY - set interfaces etherhet eth3 traffic-policy out TWO-WAY-POLICY - set interfaces etherhet eth4 traffic-policy in TWO-WAY-POLICY - set interfaces etherhet eth4 traffic-policy out TWO-WAY-POLICY - -Getting queueing information ----------------------------- - -.. opcmd:: show queueing - - Use this command to see the queueing information for an interface. - You will be able to see a packet counter (Sent, Dropped, Overlimit - and Backlog) per policy and class configured. - - - -.. _ingress-shaping: - -The case of ingress shaping -=========================== - -| **Applies to:** Inbound traffic. - -For the ingress traffic of an interface, there is only one policy you -can directly apply, a **Limiter** policy. You cannot apply a shaping -policy directly to the ingress traffic of any interface because shaping -only works for outbound traffic. - -This workaround lets you apply a shaping policy to the ingress traffic -by first redirecting it to an in-between virtual interface -(`Intermediate Functional Block`_). There, in that virtual interface, -you will be able to apply any of the policies that work for outbound -traffic, for instance, a shaping one. - -That is how it is possible to do the so-called "ingress shaping". - - -.. code-block:: none - - set traffic-policy shaper MY-INGRESS-SHAPING bandwidth 1000kbit - set traffic-policy shaper MY-INGRESS-SHAPING default bandwidth 1000kbit - set traffic-policy shaper MY-INGRESS-SHAPING default queue-type fair-queue - - set interfaces input ifb0 traffic-policy out MY-INGRESS-SHAPING - set interfaces ethernet eth0 redirect ifb0 - -.. warning:: - - Do not configure IFB as the first step. First create everything else - of your traffic-policy, and then you can configure IFB. - Otherwise you might get the ``RTNETLINK answer: File exists`` error, - which can be solved with ``sudo ip link delete ifb0``. - - -.. _that can give you a great deal of flexibility: https://blog.vyos.io/using-the-policy-route-and-packet-marking-for-custom-qos-matches -.. _tc: https://en.wikipedia.org/wiki/Tc_(Linux) -.. _tocken bucket: https://en.wikipedia.org/wiki/Token_bucket -.. _HFSC: https://en.wikipedia.org/wiki/Hierarchical_fair-service_curve -.. _Intermediate Functional Block: https://www.linuxfoundation.org/collaborate/workgroups/networking/ifb -- cgit v1.2.3 From e7f01e6efc8578603592ff86c031d46f1f1f9d82 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:32:45 +0100 Subject: arrange: nat, PBR, policy --- docs/configuration/nat/index.rst | 739 ++++++++++++++++++++++++++++++++++++ docs/configuration/nat/nptv6.rst | 69 ++++ docs/configuration/policy/index.rst | 205 ++++++++++ docs/nat.rst | 733 ----------------------------------- docs/nptv6.rst | 69 ---- docs/routing/pbr.rst | 137 ------- docs/routing/policy.rst | 65 ---- 7 files changed, 1013 insertions(+), 1004 deletions(-) create mode 100644 docs/configuration/nat/index.rst create mode 100644 docs/configuration/nat/nptv6.rst create mode 100644 docs/configuration/policy/index.rst delete mode 100644 docs/nat.rst delete mode 100644 docs/nptv6.rst delete mode 100644 docs/routing/pbr.rst delete mode 100644 docs/routing/policy.rst (limited to 'docs') diff --git a/docs/configuration/nat/index.rst b/docs/configuration/nat/index.rst new file mode 100644 index 00000000..85bd41d5 --- /dev/null +++ b/docs/configuration/nat/index.rst @@ -0,0 +1,739 @@ +.. _nat: + +### +NAT +### + +.. toctree:: + :maxdepth: 1 + :includehidden: + + nptv6 + +:abbr:`NAT (Network Address Translation)` is a common method of +remapping one IP address space into another by modifying network address +information in the IP header of packets while they are in transit across +a traffic routing device. The technique was originally used as a +shortcut to avoid the need to readdress every host when a network was +moved. It has become a popular and essential tool in conserving global +address space in the face of IPv4 address exhaustion. One +Internet-routable IP address of a NAT gateway can be used for an entire +private network. + +IP masquerading is a technique that hides an entire IP address space, +usually consisting of private IP addresses, behind a single IP address +in another, usually public address space. The hidden addresses are +changed into a single (public) IP address as the source address of the +outgoing IP packets so they appear as originating not from the hidden +host but from the routing device itself. Because of the popularity of +this technique to conserve IPv4 address space, the term NAT has become +virtually synonymous with IP masquerading. + +As network address translation modifies the IP address information in +packets, NAT implementations may vary in their specific behavior in +various addressing cases and their effect on network traffic. The +specifics of NAT behavior are not commonly documented by vendors of +equipment containing NAT implementations. + +The computers on an internal network can use any of the addresses set +aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for +private addressing (see :rfc:`1918`). These reserved IP addresses are +not in use on the Internet, so an external machine will not directly +route to them. The following addresses are reserved for private use: + +* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) +* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) +* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) + + +If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses +:rfc:`1918` address space to number customer gateways, the risk of +address collision, and therefore routing failures, arises when the +customer network already uses an :rfc:`1918` address space. + +This prompted some ISPs to develop a policy within the :abbr:`ARIN +(American Registry for Internet Numbers)` to allocate new private +address space for CGNs, but ARIN deferred to the IETF before +implementing the policy indicating that the matter was not a typical +allocation issue but a reservation of addresses for technical purposes +(per :rfc:`2860`). + +IETF published :rfc:`6598`, detailing a shared address space for use in +ISP CGN deployments that can handle the same network prefixes occurring +both on inbound and outbound interfaces. ARIN returned address space to +the :abbr:`IANA (Internet Assigned Numbers Authority)` for this +allocation. + +The allocated address block is 100.64.0.0/10. + +Devices evaluating whether an IPv4 address is public must be updated to +recognize the new address space. Allocating more private IPv4 address +space for NAT devices might prolong the transition to IPv6. + +Overview +======== + +Different NAT Types +------------------- + +.. _source-nat: + +SNAT +^^^^ + +:abbr:`SNAT (Source Network Address Translation)` is the most common +form of :abbr:`NAT (Network Address Translation)` and is typically +referred to simply as NAT. To be more correct, what most people refer +to as :abbr:`NAT (Network Address Translation)` is actually the process +of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is +typically used by internal users/private hosts to access the Internet +- the source address is translated and thus kept private. + +.. _destination-nat: + +DNAT +^^^^ + +:abbr:`DNAT (Destination Network Address Translation)` changes the +destination address of packets passing through the router, while +:ref:`source-nat` changes the source address of packets. DNAT is +typically used when an external (public) host needs to initiate a +session with an internal (private) host. A customer needs to access a +private service behind the routers public IP. A connection is +established with the routers public IP address on a well known port and +thus all traffic for this port is rewritten to address the internal +(private) host. + +.. _bidirectional-nat: + +Bidirectional NAT +^^^^^^^^^^^^^^^^^ + +This is a common scenario where both :ref:`source-nat` and +:ref:`destination-nat` are configured at the same time. It's commonly +used then internal (private) hosts need to establish a connection with +external resources and external systems need to access internal +(private) resources. + +NAT, Routing, Firewall Interaction +---------------------------------- + +There is a very nice picture/explanation in the Vyatta documentation +which should be rewritten here. + +NAT Ruleset +----------- + +:abbr:`NAT (Network Address Translation)` is configured entirely on a +series of so called `rules`. Rules are numbered and evaluated by the +underlying OS in numerical order! The rule numbers can be changes by +utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. + +.. note:: Changes to the NAT system only affect newly established + connections. Already established connections are not affected. + +.. hint:: When designing your NAT ruleset leave some space between + consecutive rules for later extension. Your ruleset could start with + numbers 10, 20, 30. You thus can later extend the ruleset and place + new rules between existing ones. + +Rules will be created for both :ref:`source-nat` and +:ref:`destination-nat`. + +For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and +:ref:`destination-nat` needs to be created. + +.. _traffic-filters: + +Traffic Filters +--------------- + +Traffic Filters are used to control which packets will have the defined +NAT rules applied. Five different filters can be applied within a NAT +rule. + +* **outbound-interface** - applicable only to :ref:`source-nat`. It + configures the interface which is used for the outside traffic that + this translation rule applies to. + + Example: + + .. code-block:: none + + set nat source rule 20 outbound-interface eth0 + +* **inbound-interface** - applicable only to :ref:`destination-nat`. It + configures the interface which is used for the inside traffic the + translation rule applies to. + + Example: + + .. code-block:: none + + set nat destination rule 20 inbound-interface eth1 + +* **protocol** - specify which types of protocols this translation rule + applies to. Only packets matching the specified protocol are NATed. By default this + applies to `all` protocols. + + Example: + + * Set SNAT rule 20 to only NAT TCP and UDP packets + * Set DNAT rule 20 to only NAT UDP packets + + .. code-block:: none + + set nat source rule 20 protocol tcp_udp + set nat destination rule 20 protocol udp + +* **source** - specifies which packets the NAT translation rule applies + to based on the packets source IP address and/or source port. Only + matching packets are considered for NAT. + + Example: + + * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 + network + * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 + network with a source port of 80 and 443 + + .. code-block:: none + + set nat source rule 20 source address 192.0.2.0/24 + set nat source rule 30 source address 192.0.3.0/24 + set nat source rule 30 source port 80,443 + + +* **destination** - specify which packets the translation will be + applied to, only based on the destination address and/or port number + configured. + + .. note:: If no destination is specified the rule will match on any + destination address and port. + + Example: + + * Configure SNAT rule (40) to only NAT packets with a destination + address of 192.0.2.1. + + .. code-block:: none + + set nat source rule 40 destination address 192.0.2.1 + + +Address Conversion +------------------ + +Every NAT rule has a translation command defined. The address defined +for the translation is the address used when the address information in +a packet is replaced. + +Source Address +^^^^^^^^^^^^^^ + +For :ref:`source-nat` rules the packets source address will be replaced +with the address specified in the translation command. A port +translation can also be specified and is part of the translation +address. + +.. note:: The translation address must be set to one of the available + addresses on the configured `outbound-interface` or it must be set to + `masquerade` which will use the primary IP address of the + `outbound-interface` as its translation address. + +.. note:: When using NAT for a large number of host systems it + recommended that a minimum of 1 IP address is used to NAT every 256 + private host systems. This is due to the limit of 65,000 port numbers + available for unique translations and a reserving an average of + 200-300 sessions per host system. + +Example: + +* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 +* Use address `masquerade` (the interfaces primary address) on rule 30 +* For a large amount of private machines behind the NAT your address + pool might to be bigger. Use any address in the range 100.64.0.10 - + 100.64.0.20 on SNAT rule 40 when doing the translation + + +.. code-block:: none + + set nat source rule 20 translation address 100.64.0.1 + set nat source rule 30 translation address 'masquerade' + set nat source rule 40 translation address 100.64.0.10-100.64.0.20 + + +Destination Address +^^^^^^^^^^^^^^^^^^^ + +For :ref:`destination-nat` rules the packets destination address will be +replaced by the specified address in the `translation address` command. + +Example: + +* DNAT rule 10 replaces the destination address of an inbound packet + with 192.0.2.10 + +.. code-block:: none + + set nat destination rule 10 translation address 192.0.2.10 + + +Configuration Examples +====================== + +To setup SNAT, we need to know: + +* The internal IP addresses we want to translate +* The outgoing interface to perform the translation on +* The external IP address to translate to + +In the example used for the Quick Start configuration above, we +demonstrate the following configuration: + +.. code-block:: none + + set nat source rule 100 outbound-interface 'eth0' + set nat source rule 100 source address '192.168.0.0/24' + set nat source rule 100 translation address 'masquerade' + +Which generates the following configuration: + +.. code-block:: none + + rule 100 { + outbound-interface eth0 + source { + address 192.168.0.0/24 + } + translation { + address masquerade + } + } + +In this example, we use **masquerade** as the translation address +instead of an IP address. The **masquerade** target is effectively an +alias to say "use whatever IP address is on the outgoing interface", +rather than a statically configured IP address. This is useful if you +use DHCP for your outgoing interface and do not know what the external +address will be. + +When using NAT for a large number of host systems it recommended that a +minimum of 1 IP address is used to NAT every 256 host systems. This is +due to the limit of 65,000 port numbers available for unique +translations and a reserving an average of 200-300 sessions per host +system. + +Example: For an ~8,000 host network a source NAT pool of 32 IP addresses +is recommended. + +A pool of addresses can be defined by using a hyphen between two IP +addresses: + +.. code-block:: none + + set nat source rule 100 translation address '203.0.113.32-203.0.113.63' + +.. _avoidng_leaky_nat: + +Avoiding "leaky" NAT +-------------------- + +Linux netfilter will not NAT traffic marked as INVALID. This often +confuses people into thinking that Linux (or specifically VyOS) has a +broken NAT implementation because non-NATed traffic is seen leaving an +external interface. This is actually working as intended, and a packet +capture of the "leaky" traffic should reveal that the traffic is either +an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems +after Linux netfilter considers the connection closed. The most common +is the additional TCP RST some host implementations send after +terminating a connection (which is implementation-specific). + +In other words, connection tracking has already observed the connection +be closed and has transition the flow to INVALID to prevent attacks from +attempting to reuse the connection. + +You can avoid the "leaky" behavior by using a firewall policy that drops +"invalid" state packets. + +Having control over the matching of INVALID state traffic, e.g. the +ability to selectively log, is an important troubleshooting tool for +observing broken protocol behavior. For this reason, VyOS does not +globally drop invalid state traffic, instead allowing the operator to +make the determination on how the traffic is handled. + +.. _hairpin_nat_reflection: + +Hairpin NAT/NAT Reflection +-------------------------- + +A typical problem with using NAT and hosting public servers is the +ability for internal systems to reach an internal server using it's +external IP address. The solution to this is usually the use of +split-DNS to correctly point host systems to the internal address when +requests are made internally. Because many smaller networks lack DNS +infrastructure, a work-around is commonly deployed to facilitate the +traffic by NATing the request from internal hosts to the source address +of the internal interface on the firewall. + +This technique is commonly referred to as NAT Reflection or Hairpin NAT. + +Example: + +* Redirect Microsoft RDP traffic from the outside (WAN, external) world + via :ref:`destination-nat` in rule 100 to the internal, private host + 192.0.2.40. + +* Redirect Microsoft RDP traffic from the internal (LAN, private) + network via :ref:`destination-nat` in rule 110 to the internal, + private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for + the reverse path of the traffic. The internal network 192.0.2.0/24 is + reachable via interface `eth0.10`. + +.. code-block:: none + + set nat destination rule 100 description 'Regular destination NAT from external' + set nat destination rule 100 destination port '3389' + set nat destination rule 100 inbound-interface 'pppoe0' + set nat destination rule 100 protocol 'tcp' + set nat destination rule 100 translation address '192.0.2.40' + + set nat destination rule 110 description 'NAT Reflection: INSIDE' + set nat destination rule 110 destination port '3389' + set nat destination rule 110 inbound-interface 'eth0.10' + set nat destination rule 110 protocol 'tcp' + set nat destination rule 110 translation address '192.0.2.40' + + set nat source rule 110 description 'NAT Reflection: INSIDE' + set nat source rule 110 destination address '192.0.2.0/24' + set nat source rule 110 outbound-interface 'eth0.10' + set nat source rule 110 protocol 'tcp' + set nat source rule 110 source address '192.0.2.0/24' + set nat source rule 110 translation address 'masquerade' + +Which results in a configuration of: + +.. code-block:: none + + vyos@vyos# show nat + destination { + rule 100 { + description "Regular destination NAT from external" + destination { + port 3389 + } + inbound-interface pppoe0 + protocol tcp + translation { + address 192.0.2.40 + } + } + rule 110 { + description "NAT Reflection: INSIDE" + destination { + port 3389 + } + inbound-interface eth0.10 + protocol tcp + translation { + address 192.0.2.40 + } + } + } + source { + rule 110 { + description "NAT Reflection: INSIDE" + destination { + address 192.0.2.0/24 + } + outbound-interface eth0.10 + protocol tcp + source { + address 192.0.2.0/24 + } + translation { + address masquerade + } + } + } + + +Destination NAT +--------------- + +DNAT is typically referred to as a **Port Forward**. When using VyOS as +a NAT router and firewall, a common configuration task is to redirect +incoming traffic to a system behind the firewall. + +In this example, we will be using the example Quick Start configuration +above as a starting point. + +To setup a destination NAT rule we need to gather: + +* The interface traffic will be coming in on; +* The protocol and port we wish to forward; +* The IP address of the internal system we wish to forward traffic to. + +In our example, we will be forwarding web server traffic to an internal +web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol +on port 80. For other common port numbers, see: +https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers + +Our configuration commands would be: + +.. code-block:: none + + set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' + set nat destination rule 10 destination port '80' + set nat destination rule 10 inbound-interface 'eth0' + set nat destination rule 10 protocol 'tcp' + set nat destination rule 10 translation address '192.168.0.100' + +Which would generate the following NAT destination configuration: + +.. code-block:: none + + nat { + destination { + rule 10 { + description "Port Forward: HTTP to 192.168.0.100" + destination { + port 80 + } + inbound-interface eth0 + protocol tcp + translation { + address 192.168.0.100 + } + } + } + } + +.. note:: If forwarding traffic to a different port than it is arriving + on, you may also configure the translation port using + `set nat destination rule [n] translation port`. + +This establishes our Port Forward rule, but if we created a firewall +policy it will likely block the traffic. + +It is important to note that when creating firewall rules that the DNAT +translation occurs **before** traffic traverses the firewall. In other +words, the destination address has already been translated to +192.168.0.100. + +So in our firewall policy, we want to allow traffic coming in on the +outside interface, destined for TCP port 80 and the IP address of +192.168.0.100. + +.. code-block:: none + + set firewall name OUTSIDE-IN rule 20 action 'accept' + set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' + set firewall name OUTSIDE-IN rule 20 destination port '80' + set firewall name OUTSIDE-IN rule 20 protocol 'tcp' + set firewall name OUTSIDE-IN rule 20 state new 'enable' + +This would generate the following configuration: + +.. code-block:: none + + rule 20 { + action accept + destination { + address 192.168.0.100 + port 80 + } + protocol tcp + state { + new enable + } + } + +.. note:: + + If you have configured the `INSIDE-OUT` policy, you will need to add + additional rules to permit inbound NAT traffic. + +1-to-1 NAT +---------- + +Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT +configuration, both DNAT and SNAT are used to NAT all traffic from an +external IP address to an internal IP address and vice-versa. + +Typically, a 1-to-1 NAT rule omits the destination port (all ports) and +replaces the protocol with either **all** or **ip**. + +Then a corresponding SNAT rule is created to NAT outgoing traffic for +the internal IP to a reserved external IP. This dedicates an external IP +address to an internal IP address and is useful for protocols which +don't have the notion of ports, such as GRE. + +Here's an extract of a simple 1-to-1 NAT configuration with one internal +and one external interface: + +.. code-block:: none + + set interfaces ethernet eth0 address '192.168.1.1/24' + set interfaces ethernet eth0 description 'Inside interface' + set interfaces ethernet eth1 address '192.0.2.30/24' + set interfaces ethernet eth1 description 'Outside interface' + set nat destination rule 2000 description '1-to-1 NAT example' + set nat destination rule 2000 destination address '192.0.2.30' + set nat destination rule 2000 inbound-interface 'eth1' + set nat destination rule 2000 translation address '192.168.1.10' + set nat source rule 2000 description '1-to-1 NAT example' + set nat source rule 2000 outbound-interface 'eth1' + set nat source rule 2000 source address '192.168.1.10' + set nat source rule 2000 translation address '192.0.2.30' + +Firewall rules are written as normal, using the internal IP address as +the source of outbound rules and the destination of inbound rules. + +NAT before VPN +-------------- + +Some application service providers (ASPs) operate a VPN gateway to +provide access to their internal resources, and require that a +connecting organisation translate all traffic to the service provider +network to a source address provided by the ASP. + +Example Network +^^^^^^^^^^^^^^^ + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from +172.29.41.89 - an address that is assigned by the ASP and not in use at +the customer site. + +.. figure:: _static/images/nat_before_vpn_topology.png + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology + + +Configuration +^^^^^^^^^^^^^ + +The required configuration can be broken down into 4 major pieces: + +* A dummy interface for the provider-assigned IP; +* NAT (specifically, Source NAT); +* IPSec IKE and ESP Groups; +* IPSec VPN tunnels. + + +Dummy interface +""""""""""""""" + +The dummy interface allows us to have an equivalent of the Cisco IOS +Loopback interface - a router-internal interface we can use for IP +addresses the router must know about, but which are not actually +assigned to a real network. + +We only need a single step for this interface: + +.. code-block:: none + + set interfaces dummy dum0 address '172.29.41.89/32' + +NAT Configuration +""""""""""""""""" + +.. code-block:: none + + set nat source rule 110 description 'Internal to ASP' + set nat source rule 110 destination address '172.27.1.0/24' + set nat source rule 110 outbound-interface 'any' + set nat source rule 110 source address '192.168.43.0/24' + set nat source rule 110 translation address '172.29.41.89' + set nat source rule 120 description 'Internal to ASP' + set nat source rule 120 destination address '10.125.0.0/16' + set nat source rule 120 outbound-interface 'any' + set nat source rule 120 source address '192.168.43.0/24' + set nat source rule 120 translation address '172.29.41.89' + +IPSec IKE and ESP +""""""""""""""""" + +The ASP has documented their IPSec requirements: + +* IKE Phase: + + * aes256 Encryption + * sha256 Hashes + +* ESP Phase: + + * aes256 Encryption + * sha256 Hashes + * DH Group 14 + + +Additionally, we want to use VPNs only on our eth1 interface (the +external interface in the image above) + +.. code-block:: none + + set vpn ipsec ike-group my-ike ikev2-reauth 'no' + set vpn ipsec ike-group my-ike key-exchange 'ikev1' + set vpn ipsec ike-group my-ike lifetime '7800' + set vpn ipsec ike-group my-ike proposal 1 dh-group '14' + set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + + set vpn ipsec esp-group my-esp compression 'disable' + set vpn ipsec esp-group my-esp lifetime '3600' + set vpn ipsec esp-group my-esp mode 'tunnel' + set vpn ipsec esp-group my-esp pfs 'disable' + set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + + set vpn ipsec ipsec-interfaces interface 'eth1' + +IPSec VPN Tunnels +""""""""""""""""" + +We'll use the IKE and ESP groups created above for this VPN. Because we +need access to 2 different subnets on the far side, we will need two +different tunnels. If you changed the names of the ESP group and IKE +group in the previous step, make sure you use the correct names here +too. + +.. code-block:: none + + set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' + set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' + set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' + set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' + set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' + +Testing and Validation +"""""""""""""""""""""" + +If you've completed all the above steps you no doubt want to see if it's +all working. + +Start by checking for IPSec SAs (Security Associations) with: + +.. code-block:: none + + $ show vpn ipsec sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all + +That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/configuration/nat/nptv6.rst b/docs/configuration/nat/nptv6.rst new file mode 100644 index 00000000..f4e08325 --- /dev/null +++ b/docs/configuration/nat/nptv6.rst @@ -0,0 +1,69 @@ +.. include:: _include/need_improvement.txt + +.. _nptv6: + +##### +NPTv6 +##### + +:abbr:`NPTv6 (Network Prefix Translation)` is a form of NAT for IPv6. It's +described in :rfc:`6296`. + +**Usage** + +NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the +external IPv6 prefix is dynamic, as it prevents the need for renumbering of +internal hosts when the extern prefix changes. + +Let's assume the following network configuration: + +* eth0 : LAN +* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it +* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it + +Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over +2001:db8:e2::/48? What happens when you get a new provider with a different +routed IPv6 subnet? + +The solution here is to assign to your hosts ULAs_ and to prefix-translate +their address to the right subnet when going through your router. + +* LAN Subnet : fc00:dead:beef::/48 +* WAN 1 Subnet : 2001:db8:e1::/48 +* WAN 2 Subnet : 2001:db8:e2::/48 + +* eth0 addr : fc00:dead:beef::1/48 +* eth1 addr : 2001:db8:e1::1/48 +* eth2 addr : 2001:db8:e2::1/48 + +VyOS Support +^^^^^^^^^^^^ + +NPTv6 support has been added in VyOS 1.2 (Crux) and is available through +`nat nptv6` configuration nodes. + +.. code-block:: none + + set rule 10 source prefix 'fc00:dead:beef::/48' + set rule 10 outbound-interface 'eth1' + set rule 10 translation prefix '2001:db8:e1::/48' + set rule 20 source prefix 'fc00:dead:beef::/48' + set rule 20 outbound-interface 'eth2' + set rule 20 translation prefix '2001:db8:e2::/48' + +Resulting in the following ip6tables rules: + +.. code-block:: none + + Chain VYOS_DNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 NETMAP all eth1 any anywhere 2001:db8:e1::/48 to:fc00:dead:beef::/48 + 0 0 NETMAP all eth2 any anywhere 2001:db8:e2::/48 to:fc00:dead:beef::/48 + 0 0 RETURN all any any anywhere anywhere + Chain VYOS_SNPT_HOOK (1 references) + pkts bytes target prot opt in out source destination + 0 0 NETMAP all any eth1 fc00:dead:beef::/48 anywhere to:2001:db8:e1::/48 + 0 0 NETMAP all any eth2 fc00:dead:beef::/48 anywhere to:2001:db8:e2::/48 + 0 0 RETURN all any any anywhere anywhere + +.. _ULAs: https://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/configuration/policy/index.rst b/docs/configuration/policy/index.rst new file mode 100644 index 00000000..4be494e5 --- /dev/null +++ b/docs/configuration/policy/index.rst @@ -0,0 +1,205 @@ +.. include:: ../_include/need_improvement.txt + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what +routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + +* Set some metric to routes learned from a particular neighbor +* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors +* Prefer a specific routing protocol routes over another routing protocol running on the same router + +Example +======= + +**Policy definition:** + +.. code-block:: none + + # Create policy + set policy route-map setmet rule 2 action 'permit' + set policy route-map setmet rule 2 set as-path-prepend '2 2 2' + + # Apply policy to BGP + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' + +Using 'soft-reconfiguration' we get the policy update without bouncing the +neighbor. + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i + + Total number of prefixes 1 + vyos@vos1:~$ + +You now see the longer AS path. + + +.. include:: ../_include/need_improvement.txt + +.. _routing-pbr: + +### +PBR +### + +:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to +different routing tables. Traffic can be matched using standard 5-tuple +matching (source address, destination address, protocol, source port, +destination port). + +Transparent Proxy +================= + +The following example will show how VyOS can be used to redirect web +traffic to an external transparent proxy: + +.. code-block:: none + + set policy route FILTER-WEB rule 1000 destination port 80 + set policy route FILTER-WEB rule 1000 protocol tcp + set policy route FILTER-WEB rule 1000 set table 100 + +This creates a route policy called FILTER-WEB with one rule to set the +routing table for matching traffic (TCP port 80) to table ID 100 +instead of the default routing table. + +To create routing table 100 and add a new default gateway to be used by +traffic matching our route policy: + +.. code-block:: none + + set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 + +This can be confirmed using the ``show ip route table 100`` operational +command. + +Finally, to apply the policy route to ingress traffic on our LAN +interface, we use: + +.. code-block:: none + + set interfaces ethernet eth1 policy route FILTER-WEB + + +Multiple Uplinks +================ + +VyOS Policy-Based Routing (PBR) works by matching source IP address +ranges and forwarding the traffic using different routing tables. + +Routing tables that will be used in this example are: + +* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) +* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) +* ``main`` Routing table used by VyOS and other interfaces not + participating in PBR + +.. figure:: ../_static/images/pbr_example_1.png + :scale: 80 % + :alt: PBR multiple uplinks + + Policy-Based Routing with multiple ISP uplinks + (source ./draw.io/pbr_example_1.drawio) + +Add default routes for routing ``table 10`` and ``table 11`` + +.. code-block:: none + + set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 + set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 + +Add policy route matching VLAN source addresses + +.. code-block:: none + + set policy route PBR rule 20 set table '10' + set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' + set policy route PBR rule 20 source address '192.168.188.0/24' + + set policy route PBR rule 30 set table '11' + set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' + set policy route PBR rule 30 source address '192.168.189.0/24' + +Apply routing policy to **inbound** direction of out VLAN interfaces + +.. code-block:: none + + set interfaces ethernet eth0 vif 10 policy route 'PBR' + set interfaces ethernet eth0 vif 11 policy route 'PBR' + + +**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) +from PBR + +.. code-block:: none + + set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' + set policy route PBR rule 10 destination address '192.168.188.0/24' + set policy route PBR rule 10 destination address '192.168.189.0/24' + set policy route PBR rule 10 set table 'main' + +These commands allow the VLAN10 and VLAN20 hosts to communicate with +each other using the main routing table. + +Local route +=========== + +The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` for traffic, which originated from the router itself. +That solution for multiple ISP's and VyOS router will respond from the same interface that the packet was received. +Also, it used, if we want that one VPN tunnel to be through one provider, and the second through another. + +* ``192.168.1.254`` IP addreess on VyOS eth1 from ISP1 +* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 +* ``table 10`` Routing table used for ISP1 +* ``table 11`` Routing table used for ISP2 + + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '192.0.1.254' + set policy local-route rule 102 set table '11' + set policy local-route rule 102 source '192.0.2.254' + set protocols static table 10 route '0.0.0.0/0' next-hop '192.0.1.1' + set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2' + +Add multiple source IP in one rule with same priority + +.. code-block:: none + + set policy local-route rule 101 set table '10' + set policy local-route rule 101 source '192.0.1.254' + set policy local-route rule 101 source '192.0.1.253' + set policy local-route rule 101 source '203.0.113.0/24' + diff --git a/docs/nat.rst b/docs/nat.rst deleted file mode 100644 index 17698c26..00000000 --- a/docs/nat.rst +++ /dev/null @@ -1,733 +0,0 @@ -.. _nat: - -### -NAT -### - -:abbr:`NAT (Network Address Translation)` is a common method of -remapping one IP address space into another by modifying network address -information in the IP header of packets while they are in transit across -a traffic routing device. The technique was originally used as a -shortcut to avoid the need to readdress every host when a network was -moved. It has become a popular and essential tool in conserving global -address space in the face of IPv4 address exhaustion. One -Internet-routable IP address of a NAT gateway can be used for an entire -private network. - -IP masquerading is a technique that hides an entire IP address space, -usually consisting of private IP addresses, behind a single IP address -in another, usually public address space. The hidden addresses are -changed into a single (public) IP address as the source address of the -outgoing IP packets so they appear as originating not from the hidden -host but from the routing device itself. Because of the popularity of -this technique to conserve IPv4 address space, the term NAT has become -virtually synonymous with IP masquerading. - -As network address translation modifies the IP address information in -packets, NAT implementations may vary in their specific behavior in -various addressing cases and their effect on network traffic. The -specifics of NAT behavior are not commonly documented by vendors of -equipment containing NAT implementations. - -The computers on an internal network can use any of the addresses set -aside by the :abbr:`IANA (Internet Assigned Numbers Authority)` for -private addressing (see :rfc:`1918`). These reserved IP addresses are -not in use on the Internet, so an external machine will not directly -route to them. The following addresses are reserved for private use: - -* 10.0.0.0 to 10.255.255.255 (CIDR: 10.0.0.0/8) -* 172.16.0.0 to 172.31.255.255 (CIDR: 172.16.0.0/12) -* 192.168.0.0 to 192.168.255.255 (CIDR: 192.168.0.0/16) - - -If an ISP deploys a :abbr:`CGN (Carrier-grade NAT)`, and uses -:rfc:`1918` address space to number customer gateways, the risk of -address collision, and therefore routing failures, arises when the -customer network already uses an :rfc:`1918` address space. - -This prompted some ISPs to develop a policy within the :abbr:`ARIN -(American Registry for Internet Numbers)` to allocate new private -address space for CGNs, but ARIN deferred to the IETF before -implementing the policy indicating that the matter was not a typical -allocation issue but a reservation of addresses for technical purposes -(per :rfc:`2860`). - -IETF published :rfc:`6598`, detailing a shared address space for use in -ISP CGN deployments that can handle the same network prefixes occurring -both on inbound and outbound interfaces. ARIN returned address space to -the :abbr:`IANA (Internet Assigned Numbers Authority)` for this -allocation. - -The allocated address block is 100.64.0.0/10. - -Devices evaluating whether an IPv4 address is public must be updated to -recognize the new address space. Allocating more private IPv4 address -space for NAT devices might prolong the transition to IPv6. - -Overview -======== - -Different NAT Types -------------------- - -.. _source-nat: - -SNAT -^^^^ - -:abbr:`SNAT (Source Network Address Translation)` is the most common -form of :abbr:`NAT (Network Address Translation)` and is typically -referred to simply as NAT. To be more correct, what most people refer -to as :abbr:`NAT (Network Address Translation)` is actually the process -of :abbr:`PAT (Port Address Translation)`, or NAT overload. SNAT is -typically used by internal users/private hosts to access the Internet -- the source address is translated and thus kept private. - -.. _destination-nat: - -DNAT -^^^^ - -:abbr:`DNAT (Destination Network Address Translation)` changes the -destination address of packets passing through the router, while -:ref:`source-nat` changes the source address of packets. DNAT is -typically used when an external (public) host needs to initiate a -session with an internal (private) host. A customer needs to access a -private service behind the routers public IP. A connection is -established with the routers public IP address on a well known port and -thus all traffic for this port is rewritten to address the internal -(private) host. - -.. _bidirectional-nat: - -Bidirectional NAT -^^^^^^^^^^^^^^^^^ - -This is a common scenario where both :ref:`source-nat` and -:ref:`destination-nat` are configured at the same time. It's commonly -used then internal (private) hosts need to establish a connection with -external resources and external systems need to access internal -(private) resources. - -NAT, Routing, Firewall Interaction ----------------------------------- - -There is a very nice picture/explanation in the Vyatta documentation -which should be rewritten here. - -NAT Ruleset ------------ - -:abbr:`NAT (Network Address Translation)` is configured entirely on a -series of so called `rules`. Rules are numbered and evaluated by the -underlying OS in numerical order! The rule numbers can be changes by -utilizing the :cfgcmd:`rename` and :cfgcmd:`copy` commands. - -.. note:: Changes to the NAT system only affect newly established - connections. Already established connections are not affected. - -.. hint:: When designing your NAT ruleset leave some space between - consecutive rules for later extension. Your ruleset could start with - numbers 10, 20, 30. You thus can later extend the ruleset and place - new rules between existing ones. - -Rules will be created for both :ref:`source-nat` and -:ref:`destination-nat`. - -For :ref:`bidirectional-nat` a rule for both :ref:`source-nat` and -:ref:`destination-nat` needs to be created. - -.. _traffic-filters: - -Traffic Filters ---------------- - -Traffic Filters are used to control which packets will have the defined -NAT rules applied. Five different filters can be applied within a NAT -rule. - -* **outbound-interface** - applicable only to :ref:`source-nat`. It - configures the interface which is used for the outside traffic that - this translation rule applies to. - - Example: - - .. code-block:: none - - set nat source rule 20 outbound-interface eth0 - -* **inbound-interface** - applicable only to :ref:`destination-nat`. It - configures the interface which is used for the inside traffic the - translation rule applies to. - - Example: - - .. code-block:: none - - set nat destination rule 20 inbound-interface eth1 - -* **protocol** - specify which types of protocols this translation rule - applies to. Only packets matching the specified protocol are NATed. By default this - applies to `all` protocols. - - Example: - - * Set SNAT rule 20 to only NAT TCP and UDP packets - * Set DNAT rule 20 to only NAT UDP packets - - .. code-block:: none - - set nat source rule 20 protocol tcp_udp - set nat destination rule 20 protocol udp - -* **source** - specifies which packets the NAT translation rule applies - to based on the packets source IP address and/or source port. Only - matching packets are considered for NAT. - - Example: - - * Set SNAT rule 20 to only NAT packets arriving from the 192.0.2.0/24 - network - * Set SNAT rule 30 to only NAT packets arriving from the 192.0.3.0/24 - network with a source port of 80 and 443 - - .. code-block:: none - - set nat source rule 20 source address 192.0.2.0/24 - set nat source rule 30 source address 192.0.3.0/24 - set nat source rule 30 source port 80,443 - - -* **destination** - specify which packets the translation will be - applied to, only based on the destination address and/or port number - configured. - - .. note:: If no destination is specified the rule will match on any - destination address and port. - - Example: - - * Configure SNAT rule (40) to only NAT packets with a destination - address of 192.0.2.1. - - .. code-block:: none - - set nat source rule 40 destination address 192.0.2.1 - - -Address Conversion ------------------- - -Every NAT rule has a translation command defined. The address defined -for the translation is the address used when the address information in -a packet is replaced. - -Source Address -^^^^^^^^^^^^^^ - -For :ref:`source-nat` rules the packets source address will be replaced -with the address specified in the translation command. A port -translation can also be specified and is part of the translation -address. - -.. note:: The translation address must be set to one of the available - addresses on the configured `outbound-interface` or it must be set to - `masquerade` which will use the primary IP address of the - `outbound-interface` as its translation address. - -.. note:: When using NAT for a large number of host systems it - recommended that a minimum of 1 IP address is used to NAT every 256 - private host systems. This is due to the limit of 65,000 port numbers - available for unique translations and a reserving an average of - 200-300 sessions per host system. - -Example: - -* Define a discrete source IP address of 100.64.0.1 for SNAT rule 20 -* Use address `masquerade` (the interfaces primary address) on rule 30 -* For a large amount of private machines behind the NAT your address - pool might to be bigger. Use any address in the range 100.64.0.10 - - 100.64.0.20 on SNAT rule 40 when doing the translation - - -.. code-block:: none - - set nat source rule 20 translation address 100.64.0.1 - set nat source rule 30 translation address 'masquerade' - set nat source rule 40 translation address 100.64.0.10-100.64.0.20 - - -Destination Address -^^^^^^^^^^^^^^^^^^^ - -For :ref:`destination-nat` rules the packets destination address will be -replaced by the specified address in the `translation address` command. - -Example: - -* DNAT rule 10 replaces the destination address of an inbound packet - with 192.0.2.10 - -.. code-block:: none - - set nat destination rule 10 translation address 192.0.2.10 - - -Configuration Examples -====================== - -To setup SNAT, we need to know: - -* The internal IP addresses we want to translate -* The outgoing interface to perform the translation on -* The external IP address to translate to - -In the example used for the Quick Start configuration above, we -demonstrate the following configuration: - -.. code-block:: none - - set nat source rule 100 outbound-interface 'eth0' - set nat source rule 100 source address '192.168.0.0/24' - set nat source rule 100 translation address 'masquerade' - -Which generates the following configuration: - -.. code-block:: none - - rule 100 { - outbound-interface eth0 - source { - address 192.168.0.0/24 - } - translation { - address masquerade - } - } - -In this example, we use **masquerade** as the translation address -instead of an IP address. The **masquerade** target is effectively an -alias to say "use whatever IP address is on the outgoing interface", -rather than a statically configured IP address. This is useful if you -use DHCP for your outgoing interface and do not know what the external -address will be. - -When using NAT for a large number of host systems it recommended that a -minimum of 1 IP address is used to NAT every 256 host systems. This is -due to the limit of 65,000 port numbers available for unique -translations and a reserving an average of 200-300 sessions per host -system. - -Example: For an ~8,000 host network a source NAT pool of 32 IP addresses -is recommended. - -A pool of addresses can be defined by using a hyphen between two IP -addresses: - -.. code-block:: none - - set nat source rule 100 translation address '203.0.113.32-203.0.113.63' - -.. _avoidng_leaky_nat: - -Avoiding "leaky" NAT --------------------- - -Linux netfilter will not NAT traffic marked as INVALID. This often -confuses people into thinking that Linux (or specifically VyOS) has a -broken NAT implementation because non-NATed traffic is seen leaving an -external interface. This is actually working as intended, and a packet -capture of the "leaky" traffic should reveal that the traffic is either -an additional TCP "RST", "FIN,ACK", or "RST,ACK" sent by client systems -after Linux netfilter considers the connection closed. The most common -is the additional TCP RST some host implementations send after -terminating a connection (which is implementation-specific). - -In other words, connection tracking has already observed the connection -be closed and has transition the flow to INVALID to prevent attacks from -attempting to reuse the connection. - -You can avoid the "leaky" behavior by using a firewall policy that drops -"invalid" state packets. - -Having control over the matching of INVALID state traffic, e.g. the -ability to selectively log, is an important troubleshooting tool for -observing broken protocol behavior. For this reason, VyOS does not -globally drop invalid state traffic, instead allowing the operator to -make the determination on how the traffic is handled. - -.. _hairpin_nat_reflection: - -Hairpin NAT/NAT Reflection --------------------------- - -A typical problem with using NAT and hosting public servers is the -ability for internal systems to reach an internal server using it's -external IP address. The solution to this is usually the use of -split-DNS to correctly point host systems to the internal address when -requests are made internally. Because many smaller networks lack DNS -infrastructure, a work-around is commonly deployed to facilitate the -traffic by NATing the request from internal hosts to the source address -of the internal interface on the firewall. - -This technique is commonly referred to as NAT Reflection or Hairpin NAT. - -Example: - -* Redirect Microsoft RDP traffic from the outside (WAN, external) world - via :ref:`destination-nat` in rule 100 to the internal, private host - 192.0.2.40. - -* Redirect Microsoft RDP traffic from the internal (LAN, private) - network via :ref:`destination-nat` in rule 110 to the internal, - private host 192.0.2.40. We also need a :ref:`source-nat` rule 110 for - the reverse path of the traffic. The internal network 192.0.2.0/24 is - reachable via interface `eth0.10`. - -.. code-block:: none - - set nat destination rule 100 description 'Regular destination NAT from external' - set nat destination rule 100 destination port '3389' - set nat destination rule 100 inbound-interface 'pppoe0' - set nat destination rule 100 protocol 'tcp' - set nat destination rule 100 translation address '192.0.2.40' - - set nat destination rule 110 description 'NAT Reflection: INSIDE' - set nat destination rule 110 destination port '3389' - set nat destination rule 110 inbound-interface 'eth0.10' - set nat destination rule 110 protocol 'tcp' - set nat destination rule 110 translation address '192.0.2.40' - - set nat source rule 110 description 'NAT Reflection: INSIDE' - set nat source rule 110 destination address '192.0.2.0/24' - set nat source rule 110 outbound-interface 'eth0.10' - set nat source rule 110 protocol 'tcp' - set nat source rule 110 source address '192.0.2.0/24' - set nat source rule 110 translation address 'masquerade' - -Which results in a configuration of: - -.. code-block:: none - - vyos@vyos# show nat - destination { - rule 100 { - description "Regular destination NAT from external" - destination { - port 3389 - } - inbound-interface pppoe0 - protocol tcp - translation { - address 192.0.2.40 - } - } - rule 110 { - description "NAT Reflection: INSIDE" - destination { - port 3389 - } - inbound-interface eth0.10 - protocol tcp - translation { - address 192.0.2.40 - } - } - } - source { - rule 110 { - description "NAT Reflection: INSIDE" - destination { - address 192.0.2.0/24 - } - outbound-interface eth0.10 - protocol tcp - source { - address 192.0.2.0/24 - } - translation { - address masquerade - } - } - } - - -Destination NAT ---------------- - -DNAT is typically referred to as a **Port Forward**. When using VyOS as -a NAT router and firewall, a common configuration task is to redirect -incoming traffic to a system behind the firewall. - -In this example, we will be using the example Quick Start configuration -above as a starting point. - -To setup a destination NAT rule we need to gather: - -* The interface traffic will be coming in on; -* The protocol and port we wish to forward; -* The IP address of the internal system we wish to forward traffic to. - -In our example, we will be forwarding web server traffic to an internal -web server on 192.168.0.100. HTTP traffic makes use of the TCP protocol -on port 80. For other common port numbers, see: -https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers - -Our configuration commands would be: - -.. code-block:: none - - set nat destination rule 10 description 'Port Forward: HTTP to 192.168.0.100' - set nat destination rule 10 destination port '80' - set nat destination rule 10 inbound-interface 'eth0' - set nat destination rule 10 protocol 'tcp' - set nat destination rule 10 translation address '192.168.0.100' - -Which would generate the following NAT destination configuration: - -.. code-block:: none - - nat { - destination { - rule 10 { - description "Port Forward: HTTP to 192.168.0.100" - destination { - port 80 - } - inbound-interface eth0 - protocol tcp - translation { - address 192.168.0.100 - } - } - } - } - -.. note:: If forwarding traffic to a different port than it is arriving - on, you may also configure the translation port using - `set nat destination rule [n] translation port`. - -This establishes our Port Forward rule, but if we created a firewall -policy it will likely block the traffic. - -It is important to note that when creating firewall rules that the DNAT -translation occurs **before** traffic traverses the firewall. In other -words, the destination address has already been translated to -192.168.0.100. - -So in our firewall policy, we want to allow traffic coming in on the -outside interface, destined for TCP port 80 and the IP address of -192.168.0.100. - -.. code-block:: none - - set firewall name OUTSIDE-IN rule 20 action 'accept' - set firewall name OUTSIDE-IN rule 20 destination address '192.168.0.100' - set firewall name OUTSIDE-IN rule 20 destination port '80' - set firewall name OUTSIDE-IN rule 20 protocol 'tcp' - set firewall name OUTSIDE-IN rule 20 state new 'enable' - -This would generate the following configuration: - -.. code-block:: none - - rule 20 { - action accept - destination { - address 192.168.0.100 - port 80 - } - protocol tcp - state { - new enable - } - } - -.. note:: - - If you have configured the `INSIDE-OUT` policy, you will need to add - additional rules to permit inbound NAT traffic. - -1-to-1 NAT ----------- - -Another term often used for DNAT is **1-to-1 NAT**. For a 1-to-1 NAT -configuration, both DNAT and SNAT are used to NAT all traffic from an -external IP address to an internal IP address and vice-versa. - -Typically, a 1-to-1 NAT rule omits the destination port (all ports) and -replaces the protocol with either **all** or **ip**. - -Then a corresponding SNAT rule is created to NAT outgoing traffic for -the internal IP to a reserved external IP. This dedicates an external IP -address to an internal IP address and is useful for protocols which -don't have the notion of ports, such as GRE. - -Here's an extract of a simple 1-to-1 NAT configuration with one internal -and one external interface: - -.. code-block:: none - - set interfaces ethernet eth0 address '192.168.1.1/24' - set interfaces ethernet eth0 description 'Inside interface' - set interfaces ethernet eth1 address '192.0.2.30/24' - set interfaces ethernet eth1 description 'Outside interface' - set nat destination rule 2000 description '1-to-1 NAT example' - set nat destination rule 2000 destination address '192.0.2.30' - set nat destination rule 2000 inbound-interface 'eth1' - set nat destination rule 2000 translation address '192.168.1.10' - set nat source rule 2000 description '1-to-1 NAT example' - set nat source rule 2000 outbound-interface 'eth1' - set nat source rule 2000 source address '192.168.1.10' - set nat source rule 2000 translation address '192.0.2.30' - -Firewall rules are written as normal, using the internal IP address as -the source of outbound rules and the destination of inbound rules. - -NAT before VPN --------------- - -Some application service providers (ASPs) operate a VPN gateway to -provide access to their internal resources, and require that a -connecting organisation translate all traffic to the service provider -network to a source address provided by the ASP. - -Example Network -^^^^^^^^^^^^^^^ - -Here's one example of a network environment for an ASP. -The ASP requests that all connections from this company should come from -172.29.41.89 - an address that is assigned by the ASP and not in use at -the customer site. - -.. figure:: _static/images/nat_before_vpn_topology.png - :scale: 100 % - :alt: NAT before VPN Topology - - NAT before VPN Topology - - -Configuration -^^^^^^^^^^^^^ - -The required configuration can be broken down into 4 major pieces: - -* A dummy interface for the provider-assigned IP; -* NAT (specifically, Source NAT); -* IPSec IKE and ESP Groups; -* IPSec VPN tunnels. - - -Dummy interface -""""""""""""""" - -The dummy interface allows us to have an equivalent of the Cisco IOS -Loopback interface - a router-internal interface we can use for IP -addresses the router must know about, but which are not actually -assigned to a real network. - -We only need a single step for this interface: - -.. code-block:: none - - set interfaces dummy dum0 address '172.29.41.89/32' - -NAT Configuration -""""""""""""""""" - -.. code-block:: none - - set nat source rule 110 description 'Internal to ASP' - set nat source rule 110 destination address '172.27.1.0/24' - set nat source rule 110 outbound-interface 'any' - set nat source rule 110 source address '192.168.43.0/24' - set nat source rule 110 translation address '172.29.41.89' - set nat source rule 120 description 'Internal to ASP' - set nat source rule 120 destination address '10.125.0.0/16' - set nat source rule 120 outbound-interface 'any' - set nat source rule 120 source address '192.168.43.0/24' - set nat source rule 120 translation address '172.29.41.89' - -IPSec IKE and ESP -""""""""""""""""" - -The ASP has documented their IPSec requirements: - -* IKE Phase: - - * aes256 Encryption - * sha256 Hashes - -* ESP Phase: - - * aes256 Encryption - * sha256 Hashes - * DH Group 14 - - -Additionally, we want to use VPNs only on our eth1 interface (the -external interface in the image above) - -.. code-block:: none - - set vpn ipsec ike-group my-ike ikev2-reauth 'no' - set vpn ipsec ike-group my-ike key-exchange 'ikev1' - set vpn ipsec ike-group my-ike lifetime '7800' - set vpn ipsec ike-group my-ike proposal 1 dh-group '14' - set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' - set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' - - set vpn ipsec esp-group my-esp compression 'disable' - set vpn ipsec esp-group my-esp lifetime '3600' - set vpn ipsec esp-group my-esp mode 'tunnel' - set vpn ipsec esp-group my-esp pfs 'disable' - set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' - set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' - - set vpn ipsec ipsec-interfaces interface 'eth1' - -IPSec VPN Tunnels -""""""""""""""""" - -We'll use the IKE and ESP groups created above for this VPN. Because we -need access to 2 different subnets on the far side, we will need two -different tunnels. If you changed the names of the ESP group and IKE -group in the previous step, make sure you use the correct names here -too. - -.. code-block:: none - - set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' - set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' - set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' - set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' - set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' - set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' - -Testing and Validation -"""""""""""""""""""""" - -If you've completed all the above steps you no doubt want to see if it's -all working. - -Start by checking for IPSec SAs (Security Associations) with: - -.. code-block:: none - - $ show vpn ipsec sa - - Peer ID / IP Local ID / IP - ------------ ------------- - 198.51.100.243 203.0.113.46 - - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all - 1 up 0.0/0.0 aes256 sha256 no 865 3600 all - -That looks good - we defined 2 tunnels and they're both up and running. diff --git a/docs/nptv6.rst b/docs/nptv6.rst deleted file mode 100644 index f4e08325..00000000 --- a/docs/nptv6.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. include:: _include/need_improvement.txt - -.. _nptv6: - -##### -NPTv6 -##### - -:abbr:`NPTv6 (Network Prefix Translation)` is a form of NAT for IPv6. It's -described in :rfc:`6296`. - -**Usage** - -NPTv6 is very useful for IPv6 multihoming. It is also commonly used when the -external IPv6 prefix is dynamic, as it prevents the need for renumbering of -internal hosts when the extern prefix changes. - -Let's assume the following network configuration: - -* eth0 : LAN -* eth1 : WAN1, with 2001:db8:e1::/48 routed towards it -* eth2 : WAN2, with 2001:db8:e2::/48 routed towards it - -Regarding LAN hosts addressing, why would you choose 2001:db8:e1::/48 over -2001:db8:e2::/48? What happens when you get a new provider with a different -routed IPv6 subnet? - -The solution here is to assign to your hosts ULAs_ and to prefix-translate -their address to the right subnet when going through your router. - -* LAN Subnet : fc00:dead:beef::/48 -* WAN 1 Subnet : 2001:db8:e1::/48 -* WAN 2 Subnet : 2001:db8:e2::/48 - -* eth0 addr : fc00:dead:beef::1/48 -* eth1 addr : 2001:db8:e1::1/48 -* eth2 addr : 2001:db8:e2::1/48 - -VyOS Support -^^^^^^^^^^^^ - -NPTv6 support has been added in VyOS 1.2 (Crux) and is available through -`nat nptv6` configuration nodes. - -.. code-block:: none - - set rule 10 source prefix 'fc00:dead:beef::/48' - set rule 10 outbound-interface 'eth1' - set rule 10 translation prefix '2001:db8:e1::/48' - set rule 20 source prefix 'fc00:dead:beef::/48' - set rule 20 outbound-interface 'eth2' - set rule 20 translation prefix '2001:db8:e2::/48' - -Resulting in the following ip6tables rules: - -.. code-block:: none - - Chain VYOS_DNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 NETMAP all eth1 any anywhere 2001:db8:e1::/48 to:fc00:dead:beef::/48 - 0 0 NETMAP all eth2 any anywhere 2001:db8:e2::/48 to:fc00:dead:beef::/48 - 0 0 RETURN all any any anywhere anywhere - Chain VYOS_SNPT_HOOK (1 references) - pkts bytes target prot opt in out source destination - 0 0 NETMAP all any eth1 fc00:dead:beef::/48 anywhere to:2001:db8:e1::/48 - 0 0 NETMAP all any eth2 fc00:dead:beef::/48 anywhere to:2001:db8:e2::/48 - 0 0 RETURN all any any anywhere anywhere - -.. _ULAs: https://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/routing/pbr.rst b/docs/routing/pbr.rst deleted file mode 100644 index 7b0341cb..00000000 --- a/docs/routing/pbr.rst +++ /dev/null @@ -1,137 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -.. _routing-pbr: - -### -PBR -### - -:abbr:`PBR (Policy-Based Routing)` allowing traffic to be assigned to -different routing tables. Traffic can be matched using standard 5-tuple -matching (source address, destination address, protocol, source port, -destination port). - -Transparent Proxy -================= - -The following example will show how VyOS can be used to redirect web -traffic to an external transparent proxy: - -.. code-block:: none - - set policy route FILTER-WEB rule 1000 destination port 80 - set policy route FILTER-WEB rule 1000 protocol tcp - set policy route FILTER-WEB rule 1000 set table 100 - -This creates a route policy called FILTER-WEB with one rule to set the -routing table for matching traffic (TCP port 80) to table ID 100 -instead of the default routing table. - -To create routing table 100 and add a new default gateway to be used by -traffic matching our route policy: - -.. code-block:: none - - set protocols static table 100 route 0.0.0.0/0 next-hop 10.255.0.2 - -This can be confirmed using the ``show ip route table 100`` operational -command. - -Finally, to apply the policy route to ingress traffic on our LAN -interface, we use: - -.. code-block:: none - - set interfaces ethernet eth1 policy route FILTER-WEB - - -Multiple Uplinks -================ - -VyOS Policy-Based Routing (PBR) works by matching source IP address -ranges and forwarding the traffic using different routing tables. - -Routing tables that will be used in this example are: - -* ``table 10`` Routing table used for VLAN 10 (192.168.188.0/24) -* ``table 11`` Routing table used for VLAN 11 (192.168.189.0/24) -* ``main`` Routing table used by VyOS and other interfaces not - participating in PBR - -.. figure:: ../_static/images/pbr_example_1.png - :scale: 80 % - :alt: PBR multiple uplinks - - Policy-Based Routing with multiple ISP uplinks - (source ./draw.io/pbr_example_1.drawio) - -Add default routes for routing ``table 10`` and ``table 11`` - -.. code-block:: none - - set protocols static table 10 route 0.0.0.0/0 next-hop 192.0.1.1 - set protocols static table 11 route 0.0.0.0/0 next-hop 192.0.2.2 - -Add policy route matching VLAN source addresses - -.. code-block:: none - - set policy route PBR rule 20 set table '10' - set policy route PBR rule 20 description 'Route VLAN10 traffic to table 10' - set policy route PBR rule 20 source address '192.168.188.0/24' - - set policy route PBR rule 30 set table '11' - set policy route PBR rule 30 description 'Route VLAN11 traffic to table 11' - set policy route PBR rule 30 source address '192.168.189.0/24' - -Apply routing policy to **inbound** direction of out VLAN interfaces - -.. code-block:: none - - set interfaces ethernet eth0 vif 10 policy route 'PBR' - set interfaces ethernet eth0 vif 11 policy route 'PBR' - - -**OPTIONAL:** Exclude Inter-VLAN traffic (between VLAN10 and VLAN11) -from PBR - -.. code-block:: none - - set policy route PBR rule 10 description 'VLAN10 <-> VLAN11 shortcut' - set policy route PBR rule 10 destination address '192.168.188.0/24' - set policy route PBR rule 10 destination address '192.168.189.0/24' - set policy route PBR rule 10 set table 'main' - -These commands allow the VLAN10 and VLAN20 hosts to communicate with -each other using the main routing table. - -Local route -=========== - -The following example allows VyOS to use :abbr:`PBR (Policy-Based Routing)` for traffic, which originated from the router itself. -That solution for multiple ISP's and VyOS router will respond from the same interface that the packet was received. -Also, it used, if we want that one VPN tunnel to be through one provider, and the second through another. - -* ``192.168.1.254`` IP addreess on VyOS eth1 from ISP1 -* ``192.168.2.254`` IP addreess on VyOS eth2 from ISP2 -* ``table 10`` Routing table used for ISP1 -* ``table 11`` Routing table used for ISP2 - - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source '192.0.1.254' - set policy local-route rule 102 set table '11' - set policy local-route rule 102 source '192.0.2.254' - set protocols static table 10 route '0.0.0.0/0' next-hop '192.0.1.1' - set protocols static table 11 route '0.0.0.0/0' next-hop '192.0.2.2' - -Add multiple source IP in one rule with same priority - -.. code-block:: none - - set policy local-route rule 101 set table '10' - set policy local-route rule 101 source '192.0.1.254' - set policy local-route rule 101 source '192.0.1.253' - set policy local-route rule 101 source '203.0.113.0/24' diff --git a/docs/routing/policy.rst b/docs/routing/policy.rst deleted file mode 100644 index 4eeb40d6..00000000 --- a/docs/routing/policy.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. include:: ../_include/need_improvement.txt - -###### -Policy -###### - -Routing Policies could be used to tell the router (self or neighbors) what -routes and their attributes needs to be put into the routing table. - -There could be a wide range of routing policies. Some examples are below: - -* Set some metric to routes learned from a particular neighbor -* Set some attributes (like AS PATH or Community value) to advertised routes to neighbors -* Prefer a specific routing protocol routes over another routing protocol running on the same router - -Example -======= - -**Policy definition:** - -.. code-block:: none - - # Create policy - set policy route-map setmet rule 2 action 'permit' - set policy route-map setmet rule 2 set as-path-prepend '2 2 2' - - # Apply policy to BGP - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast route-map import 'setmet' - set protocols bgp 1 neighbor 203.0.113.2 address-family ipv4-unicast soft-reconfiguration 'inbound' - -Using 'soft-reconfiguration' we get the policy update without bouncing the -neighbor. - -**Routes learned before routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 i < Path - - Total number of prefixes 1 - -**Routes learned after routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ sho ip b - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 198.51.100.3/32 203.0.113.2 1 0 2 2 2 2 i - - Total number of prefixes 1 - vyos@vos1:~$ - -You now see the longer AS path. -- cgit v1.2.3 From 4abded8025a47990e58cd0a5fe9b96e38f4a3715 Mon Sep 17 00:00:00 2001 From: rebortg Date: Sun, 29 Nov 2020 21:52:28 +0100 Subject: arrange: interfaces --- Pipfile | 16 + docs/configuration/interfaces/bonding.rst | 560 +++++++++++++++++++++ docs/configuration/interfaces/bridge.rst | 270 ++++++++++ docs/configuration/interfaces/dummy.rst | 79 +++ docs/configuration/interfaces/ethernet.rst | 226 +++++++++ docs/configuration/interfaces/geneve.rst | 61 +++ docs/configuration/interfaces/index.rst | 28 ++ docs/configuration/interfaces/l2tpv3.rst | 192 +++++++ docs/configuration/interfaces/loopback.rst | 71 +++ docs/configuration/interfaces/macsec.rst | 191 +++++++ docs/configuration/interfaces/openvpn.rst | 584 ++++++++++++++++++++++ docs/configuration/interfaces/pppoe.rst | 307 ++++++++++++ docs/configuration/interfaces/pseudo-ethernet.rst | 65 +++ docs/configuration/interfaces/tunnel.rst | 216 ++++++++ docs/configuration/interfaces/vti.rst | 22 + docs/configuration/interfaces/vxlan.rst | 295 +++++++++++ docs/configuration/interfaces/wireguard.rst | 265 ++++++++++ docs/configuration/interfaces/wireless.rst | 573 +++++++++++++++++++++ docs/configuration/interfaces/wirelessmodem.rst | 128 +++++ docs/interfaces/bond.rst | 560 --------------------- docs/interfaces/bridge.rst | 270 ---------- docs/interfaces/dummy.rst | 79 --- docs/interfaces/ethernet.rst | 226 --------- docs/interfaces/geneve.rst | 61 --- docs/interfaces/l2tpv3.rst | 192 ------- docs/interfaces/loopback.rst | 71 --- docs/interfaces/macsec.rst | 191 ------- docs/interfaces/pppoe.rst | 307 ------------ docs/interfaces/pseudo-ethernet.rst | 65 --- docs/interfaces/tunnel.rst | 235 --------- docs/interfaces/vxlan.rst | 295 ----------- docs/interfaces/wireless.rst | 573 --------------------- docs/interfaces/wirelessmodem.rst | 128 ----- docs/vpn/openvpn.rst | 584 ---------------------- docs/vpn/wireguard.rst | 265 ---------- 35 files changed, 4149 insertions(+), 4102 deletions(-) create mode 100644 Pipfile create mode 100644 docs/configuration/interfaces/bonding.rst create mode 100644 docs/configuration/interfaces/bridge.rst create mode 100644 docs/configuration/interfaces/dummy.rst create mode 100644 docs/configuration/interfaces/ethernet.rst create mode 100644 docs/configuration/interfaces/geneve.rst create mode 100644 docs/configuration/interfaces/index.rst create mode 100644 docs/configuration/interfaces/l2tpv3.rst create mode 100644 docs/configuration/interfaces/loopback.rst create mode 100644 docs/configuration/interfaces/macsec.rst create mode 100644 docs/configuration/interfaces/openvpn.rst create mode 100644 docs/configuration/interfaces/pppoe.rst create mode 100644 docs/configuration/interfaces/pseudo-ethernet.rst create mode 100644 docs/configuration/interfaces/tunnel.rst create mode 100644 docs/configuration/interfaces/vti.rst create mode 100644 docs/configuration/interfaces/vxlan.rst create mode 100644 docs/configuration/interfaces/wireguard.rst create mode 100644 docs/configuration/interfaces/wireless.rst create mode 100644 docs/configuration/interfaces/wirelessmodem.rst delete mode 100644 docs/interfaces/bond.rst delete mode 100644 docs/interfaces/bridge.rst delete mode 100644 docs/interfaces/dummy.rst delete mode 100644 docs/interfaces/ethernet.rst delete mode 100644 docs/interfaces/geneve.rst delete mode 100644 docs/interfaces/l2tpv3.rst delete mode 100644 docs/interfaces/loopback.rst delete mode 100644 docs/interfaces/macsec.rst delete mode 100644 docs/interfaces/pppoe.rst delete mode 100644 docs/interfaces/pseudo-ethernet.rst delete mode 100644 docs/interfaces/tunnel.rst delete mode 100644 docs/interfaces/vxlan.rst delete mode 100644 docs/interfaces/wireless.rst delete mode 100644 docs/interfaces/wirelessmodem.rst delete mode 100644 docs/vpn/openvpn.rst delete mode 100644 docs/vpn/wireguard.rst (limited to 'docs') diff --git a/Pipfile b/Pipfile new file mode 100644 index 00000000..423092c4 --- /dev/null +++ b/Pipfile @@ -0,0 +1,16 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] +sphinx-rtd-theme = "*" +docutils = "*" +lxml = "*" +sphinx-notfound-page = "*" +Sphinx = ">=1.4.3" + +[dev-packages] + +[requires] +python_version = "3.9" diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst new file mode 100644 index 00000000..7faddd6f --- /dev/null +++ b/docs/configuration/interfaces/bonding.rst @@ -0,0 +1,560 @@ +.. _bond-interface: + +####################### +Bond / Link Aggregation +####################### + +The bonding interface provides a method for aggregating multiple network +interfaces into a single logical "bonded" interface, or LAG, or ether-channel, +or port-channel. The behavior of the bonded interfaces depends upon the mode; +generally speaking, modes provide either hot standby or load balancing services. +Additionally, link integrity monitoring may be performed. + +************* +Configuration +************* + +Common interface configuration +============================== + +.. cmdinclude:: ../_include/interface-common-with-dhcp.txt + :var0: bond + :var1: bond0 + +Member Interfaces +================= + +.. cfgcmd:: set interfaces bonding member interface + + Enslave `` interface to bond ``. + +Bond options +============ + +.. cfgcmd:: set interfaces bonding mode <802.3ad | active-backup | + broadcast | round-robin | transmit-load-balance | adaptive-load-balance | + xor-hash> + + Specifies one of the bonding policies. The default is 802.3ad. Possible + values are: + + * ``802.3ad`` - IEEE 802.3ad Dynamic link aggregation. Creates aggregation + groups that share the same speed and duplex settings. Utilizes all slaves + in the active aggregator according to the 802.3ad specification. + + Slave selection for outgoing traffic is done according to the transmit + hash policy, which may be changed from the default simple XOR policy via + the :cfgcmd:`hash-policy` option, documented below. + + .. note:: Not all transmit policies may be 802.3ad compliant, particularly + in regards to the packet mis-ordering requirements of section 43.2.4 + of the 802.3ad standard. + + * ``active-backup`` - Active-backup policy: Only one slave in the bond is + active. A different slave becomes active if, and only if, the active slave + fails. The bond's MAC address is externally visible on only one port + (network adapter) to avoid confusing the switch. + + When a failover occurs in active-backup mode, bonding will issue one or + more gratuitous ARPs on the newly active slave. One gratuitous ARP is + issued for the bonding master interface and each VLAN interfaces + configured above it, provided that the interface has at least one IP + address configured. Gratuitous ARPs issued for VLAN interfaces are tagged + with the appropriate VLAN id. + + This mode provides fault tolerance. The :cfgcmd:`primary` option, + documented below, affects the behavior of this mode. + + * ``broadcast`` - Broadcast policy: transmits everything on all slave + interfaces. + + This mode provides fault tolerance. + + * ``round-robin`` - Round-robin policy: Transmit packets in sequential + order from the first available slave through the last. + + This mode provides load balancing and fault tolerance. + + * ``transmit-load-balance`` - Adaptive transmit load balancing: channel + bonding that does not require any special switch support. + + Incoming traffic is received by the current slave. If the receiving slave + fails, another slave takes over the MAC address of the failed receiving + slave. + + * ``adaptive-load-balance`` - Adaptive load balancing: includes + transmit-load-balance plus receive load balancing for IPV4 traffic, and + does not require any special switch support. The receive load balancing + is achieved by ARP negotiation. The bonding driver intercepts the ARP + Replies sent by the local system on their way out and overwrites the + source hardware address with the unique hardware address of one of the + slaves in the bond such that different peers use different hardware + addresses for the server. + + Receive traffic from connections created by the server is also balanced. + When the local system sends an ARP Request the bonding driver copies and + saves the peer's IP information from the ARP packet. When the ARP Reply + arrives from the peer, its hardware address is retrieved and the bonding + driver initiates an ARP reply to this peer assigning it to one of the + slaves in the bond. A problematic outcome of using ARP negotiation for + balancing is that each time that an ARP request is broadcast it uses the + hardware address of the bond. Hence, peers learn the hardware address + of the bond and the balancing of receive traffic collapses to the current + slave. This is handled by sending updates (ARP Replies) to all the peers + with their individually assigned hardware address such that the traffic + is redistributed. Receive traffic is also redistributed when a new slave + is added to the bond and when an inactive slave is re-activated. The + receive load is distributed sequentially (round robin) among the group + of highest speed slaves in the bond. + + When a link is reconnected or a new slave joins the bond the receive + traffic is redistributed among all active slaves in the bond by initiating + ARP Replies with the selected MAC address to each of the clients. The + updelay parameter (detailed below) must be set to a value equal or greater + than the switch's forwarding delay so that the ARP Replies sent to the + peers will not be blocked by the switch. + + * ``xor-hash`` - XOR policy: Transmit based on the selected transmit + hash policy. The default policy is a simple [(source MAC address XOR'd + with destination MAC address XOR packet type ID) modulo slave count]. + Alternate transmit policies may be selected via the :cfgcmd:`hash-policy` + option, described below. + + This mode provides load balancing and fault tolerance. + +.. cfgcmd:: set interfaces bonding min-links <0-16> + + Specifies the minimum number of links that must be active before asserting + carrier. It is similar to the Cisco EtherChannel min-links feature. This + allows setting the minimum number of member ports that must be up (link-up + state) before marking the bond device as up (carrier on). This is useful for + situations where higher level services such as clustering want to ensure a + minimum number of low bandwidth links are active before switchover. + + This option only affects 802.3ad mode. + + The default value is 0. This will cause carrier to be asserted (for 802.3ad + mode) whenever there is an active aggregator, regardless of the number of + available links in that aggregator. + + .. note:: Because an aggregator cannot be active without at least one + available link, setting this option to 0 or to 1 has the exact same + effect. + +.. cfgcmd:: set interfaces bonding hash-policy + + * **layer2** - Uses XOR of hardware MAC addresses and packet type ID field + to generate the hash. The formula is + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + slave number = hash modulo slave count + + This algorithm will place all traffic to a particular network peer on + the same slave. + + This algorithm is 802.3ad compliant. + + * **layer2+3** - This policy uses a combination of layer2 and layer3 + protocol information to generate the hash. Uses XOR of hardware MAC + addresses and IP addresses to generate the hash. The formula is: + + .. code-block:: none + + hash = source MAC XOR destination MAC XOR packet type ID + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + This algorithm will place all traffic to a particular network peer on the + same slave. For non-IP traffic, the formula is the same as for the layer2 + transmit hash policy. + + This policy is intended to provide a more balanced distribution of traffic + than layer2 alone, especially in environments where a layer3 gateway + device is required to reach most destinations. + + This algorithm is 802.3ad compliant. + + * **layer3+4** - This policy uses upper layer protocol information, when + available, to generate the hash. This allows for traffic to a particular + network peer to span multiple slaves, although a single connection will + not span multiple slaves. + + The formula for unfragmented TCP and UDP packets is + + .. code-block:: none + + hash = source port, destination port (as in the header) + hash = hash XOR source IP XOR destination IP + hash = hash XOR (hash RSHIFT 16) + hash = hash XOR (hash RSHIFT 8) + + And then hash is reduced modulo slave count. + + If the protocol is IPv6 then the source and destination addresses are + first hashed using ipv6_addr_hash. + + For fragmented TCP or UDP packets and all other IPv4 and IPv6 protocol + traffic, the source and destination port information is omitted. For + non-IP traffic, the formula is the same as for the layer2 transmit hash + policy. + + This algorithm is not fully 802.3ad compliant. A single TCP or UDP + conversation containing both fragmented and unfragmented packets will see + packets striped across two interfaces. This may result in out of order + delivery. Most traffic types will not meet this criteria, as TCP rarely + fragments traffic, and most UDP traffic is not involved in extended + conversations. Other implementations of 802.3ad may or may not tolerate + this noncompliance. + +.. cfgcmd:: set interfaces bonding primary + + An `` specifying which slave is the primary device. The specified + device will always be the active slave while it is available. Only when the + primary is off-line will alternate devices be used. This is useful when one + slave is preferred over another, e.g., when one slave has higher throughput + than another. + + The primary option is only valid for active-backup, transmit-load-balance, + and adaptive-load-balance mode. + +.. cfgcmd:: set interfaces bonding arp-monitor interval